Widget Sharing

Last Updated: Jul 10, 2013 02:00PM EDT


Overview

If you have Flash or HTML widgets such as games or video players, you can use our widget sharing functionality to allow users to share your content to popular destinations like Facebook, iGoogle or their Windows and OS X desktops. Instead of vanilla link sharing, your widget will embed directly into their feed, desktop or start page. You can use widget sharing with any of our tools and you can even embed sharing buttons in your widgets so users can reshare it in the wild.

Setting up widget sharing is easy, you use our normal sharing tools and tell us the width and height of your widget and the URL to your SWF file or iframe. To do this, you just tag your page with Facebook-style meta tags. When AddThis shares your page to a supporting destination, that destination will read these tags and share your widget along with your link. If you're unable to tag the page your widget lives on, you can also pass extra parameters to our APIs, though we recommend the tagging approach for a variety of important reasons.




Tagging Your Pages to Identify Widgets

AddThis looks for Facebook Share and Open Graph Protocol tags in your web pages to identify widgets. If there is a widget on your page or one that should be shared along with it, add these tags to the page's <head>:

<meta property="og:title" content="AddThis Tour" />
     <meta property="og:description" content="Watch the AddThis Tour video." />
     <meta property="og:image" content="http://i2.ytimg.com/vi/1F7DKyFt5pY/default.jpg" />          <meta property="og:video" content="http://www.youtube.com/v/1F7DKyFt5pY&fs=1" />   
     <meta property="og:video:width" content="560" />    
     <meta property="og:video:height" content="340" />     
     <meta property="og:video:type" content="application/x-shockwave-flash" /> 

If your widget is built with HTML instead of Flash, use these tags instead:

<meta property="og:title" content="UFO Maps" />
     <meta property="og:description" content="UFO Maps, sightings as they happen" />
     <meta property="og:image" content="http://www.ufomaps.com/gadget/ufomaps.jpg" />     
     <link rel="iframe_src" href="http://www.gmodules.com/ig/ifr?url=http%3A%2F%2Fufomaps.com%2Fgadget%2Fufomaps.xml" />     
     <meta property="og:video:width" content="320" />     
     <meta property="og:video:height" content="200" /> 

When your users share to a destination that supports widgets, we will read the page source, look for these tags, and pass your widget to the site in a format it can understand. Please note that width and height are treated as "preferred" values. Your widget should be resizable as many destinations will fit widgets to their page template (though they will generally preserve the aspect ratio). Also, the og:image parameter is required to display a preview screenshot on several destinations.

A Simple Example

This example page contains the tags shown above, try it out and take a look at the HTML source. This particular example creates a button using the link decoration feature of the Client API:

<a class="addthis_button" addthis:url="http://www.addthis.com/pages/embedded-example-meta"> 

Here's the button in action:

 

Page tagging works the same way if you're using JavaScript rendering instead of link decoration. Here's another example page that uses page tags to share an HTML widget.

Why Tags are Preferred

We strongly recommend the page-tagging approach over passing your widget parameters to our APIs:

  • You'll have a better sharing experience on Facebook and other sites that adopt Open Graph Protocol tags (even if you're not using AddThis tools)
  • Google, Yahoo, and other search engines support these tags and will be able to index your widget and provide richer search results for your site
  • Flash sharing will work automatically if your site already supports these tags (many do)

We are adding support for more page tags and microformats on an ongoing basis; if you have any suggestions, please let our team know in here. It is our goal over time to track with the major search engines' microformat support, so check back here and on our blog for updates as we add additional tag support.

Sharing from pages with multiple widgets

Some of your pages may have more than one widget, for example a video search results page. If you want to put a sharing button next to each result, don't try to cram several sets of link/meta tags into the <head> of the listings page. Instead, configure each sharing button with the permalink of the respective video, and tag that page instead. In other words, you are sharing the specific video, not the search results page. This is how you would use AddThis on a listings page in general, whether or not that page has widget tags.

Sharing Flash on Facebook

Facebook, by default, will accept Flash content but won't show it expanded in-line in feed posts unless the domain that serves the SWF has been approved. Please see this troubleshooting guide for details on enabling this.




Sharing Widgets via the APIs

Though we recommend the page tagging approach, there are times where you may not be able to add tags to the page you're sharing. If this is the case, you can provide a subset of the content via the APIs directly.

Widget Parameters

The following parameters are available in a variety of APIs to describe your widget:

Name Description Example
screenshot The URL to a full-size image of your widget (required) http://www.example.com/img/preview2374.png
width The preferred width of the widget (required) 500
height The preferred height of the widget (required) 300
swfurl The URL to your SWF (Flash widgets only) http://www.example.com/assets/flash/mycoolflashthingy.swf
iframeurl The URL to your iframe (HTML widgets only) http://www.example.com/widget.html

Note: Using these parameters (specifically swfurl or iframeurl) turns off page-scraping and will tell AddThis NOT to read the link and meta tags from your page. If you pass either of these parameters to our api it's important to pass title, height, width and screenshot as well. You can use either the tag-based or the api-parameter-based method, but not both.

Passing Widget Parameters to the Client API

If you are using the Client API to include AddThis on your page, you can specify these parameters, and more, via JavaScript (see the Client API documentation for additional details).

An Example

This JavaScript code uses wiget parameters and the Client API to specify a Flash widget for sharing:

<a id="btn1"></a>
<script type="text/javascript">
var addthis_ui_config =
{
    services_compact: 'facebook, myspace, igoogle, netvibes, windows, dashboard, more'
}
var addthis_share_config = 
{
    url: "http://www.addthis.com/pages/embedded-example-js",
    title: "AddThis Tour",
    description: "Watch the AddThis Tour video.",
    swfurl: "http://www.youtube.com/v/1F7DKyFt5pY&hl=en&fs=1",
    width: "560",
    height: "340",
    screenshot: "http://i2.ytimg.com/vi/1F7DKyFt5pY/default.jpg"
}
addthis.button("#btn1", addthis_ui_config, addthis_share_config);
</script>

Here's the button in action:

 

Take a look at this in more detail on this example page, which isn't tagged but still supports Flash widget sharing.

Passing Widget Parameters to the Sharing Endpoints

If you are using the Sharing Endpoints – if you are in a Flash environment or if you are just rolling your own buttons – you can specify these parameters on the call. Take a look at the Sharing Endpoint documentation for additional reference information.

Note: While we recommend the page tagging approach for most use cases, you must pass your Widget as parameters to our api when sharing pages that can't be reached by our servers. This includes private intranet pages or any pages that require user login.

A Simple Link Example

Sharing widgets using our Sharing Endpoints is easy since they are just URLs that you hit with a browser. All you need to do is build the appropriate endpoint URL and add the widget parameters.

The following link shares a Flash video player to iGoogle:

http://api.addthis.com/oexchange/0.8/forward/igoogle/offer?
    url=http://www.youtube.com/watch?v=1F7DKyFt5pY&
    title=AddThis+Tour&
    description=Watch+the+AddThis+Tour+video.&
    swfurl=http://www.youtube.com/v/1F7DKyFt5pY&
    height=251&
    width=400&
    screenshot=http://i2.ytimg.com/vi/1F7DKyFt5pY/default.jpg

Note: Always make sure that all of your parameters are URL encoded (not shown here for clarity).

A Flash Example

To call these endpoints from Flash, you use the exact same link, you're just using ActionScript code to open the URLs. For example, in AS 3:

var url:String = "http://api.addthis.com/oexchange/0.8/forward/igoogle/offer?url=http://www.youtube.com/watch?v=1F7DKyFt5pY&title=AddThis+Tour&description=Watch+the+AddThis+Tour+video.&swfurl=http://www.youtube.com/v/1F7DKyFt5pY&height=251&width=400&screenshot=http://i2.ytimg.com/vi/1F7DKyFt5pY/default.jpg";
var request:URLRequest = new URLRequest(url);
try {
  navigateToURL(request, '_blank'); // second argument is target
} catch (e:Error) {
  trace("Error occurred!");
}

 

We have Flash reference code you can use to handle this for you. Read more about invoking the Sharing Endpoints from Flash, or about the Flash example code.




A Complete Example

Taking all of the capabilities described on this page together, this page demonstrates what you might actually do with a real-world video page:

  • the page includes a simple embedded Flash video player, which takes some configuration parameters
  • the page is tagged with meta tags to help AddThis, Facebook, and search engines find that Flash player
  • the Flash player uses the Sharing Endpoints and the Flash example code to enable sharing even beyond this page, from directly in the widget.

Take a look, play around, and view the source.




Working with Configurable Widgets

If your widget is customizable or uses flash vars you can add your configuration parameters as URL arguments on the SWF or iframe URL. When using on-page tags to specify your widget (on its homepage for example), you would usually generate the tags based on parameters passed to the page itself.

For example, imagine you have a video page with an embedded Flash player, where the player takes a video ID as a parameter. If the URL to your video page looked something like:

http://www.example.com/video/watch?video_id=1234 

...and your Flash player SWF looks something like:

http://www.example.com/videoplayer.swf?video_id=1234 

Then your page will generate a tag that correctly provides the configured player. In the page, you therefore might have code like this:

<meta property="og:video" content="http://www.example.com/videoplayer.swf?video_id=<?= $_GET["video_id"] ?>"/>
<meta property="og:video:height" content="340" /> 
<meta property="og:video:width" content="560" />
<meta property="og:video:type" content="application/x-shockwave-flash" />

The page is looking for the parameters passed to it, and generating an og:video meta tag with the dynamically generated URL to the correct SWF.




Destinations Which Support Widgets

Flash Widgets
HTML Widgets

We frequently add destinations, check back here or watch our blog for updates.

Widget-Only Destinations

There are a few sharing services which require widgets and can't share standalone URLs (including iGoogle, Windows and Dashboard). Our sharing menu will automatically hide these services if it can't find a widget in the <head> or menu configuration of the current page. If you're using our sharing menu to share a different page, we won't be able to immediately tell whether it has a widget. If you know that the page does have a widget, you can activate these widget-only services with the ui_use_embeddable_services flag:

var addthis_config = {     ui_use_embeddable_services: true } 



Overriding Module Generation

Certain destinations require special packaging and descriptor files for widgets shared to their site. We refer to a widget packaged in this manner as a "module". There are several formats such as OpenSocial or Netvibes' Universal Widget API. The destinations that require special packaging include:

We do all the work for you - when your widget is shared to any of these destinations we'll automatically wrap it with the necessary packaging and share the newly generated module. If you want to build a custom experience for a specific destination you can build the widget yourself in the site-specific format, host it on your domain and tell us where it is using the module parameter. We'll share it for you using our standard tools. (Hint: if you want a few simple customizations, use our service to share your widget to the destination, grab the module we generated and tweak it to your liking, this should save you time over a ground-up rewrite).

Menu Configuration

If you're using the sharing menu, set up the modules object in the sharing configuration. You can provide one url per destination that supports modules:

var addthis_share = 
{ 
// ...
    modules: {
        igoogle: 'http://example.com/gadget.xml',
        dashboard: 'http://example.com/widget.zip',
        windows: 'http://example.com/gadget.gadget' 
    }
}

Note: for Windows gadgets, it's important to set the file download MIME type to: application/x-windows-gadget

Sharing Endpoint Parameter

If you're calling our share forward endpoints, you can pass the module parameter:

Name Description Type Required? Example
module Custom module override (when sharing widgets to supported destinations). URL no http://example.com/gadget.xml


Meta Tag Support

In addition to Open Graph Protocol tags we also support common <meta> and <link> tags for describing your content:

<meta name="title" content="AddThis Tour" />
    <meta name="description" content="Watch the AddThis Tour video." />
    <meta name="video_width" content="560" />
    <meta name="video_height" content="340" />
    <meta name="video_type" content="application/x-shockwave-flash" />
    <link rel="image_src" href="http://i2.ytimg.com/vi/1F7DKyFt5pY/default.jpg" />
    <link rel="video_src" href="http://www.youtube.com/v/1F7DKyFt5pY&fs=1" />

If we find multiple values for a given field we will keep the last one we see.

Still need help?


General Topics

 

Developers