awe.sm-powered Share Buttons

What are these?

Twitter and Facebook provide widgets for you to embed on your website to encourage users to share your content on those sites. With awe.sm, you can easily track how your users use these tools and how successful they are. We currently have four widgets:

Facebook Like button

The Like button lets a user share your content with friends on Facebook. When the user clicks the Like button on your site, a one-line story appears in the user's friends' News Feed with a link back to your website. Your page will also appear in the "Likes and Interests" section of the user's profile, and you have the ability to publish updates to the user. If the user enters an optional comment after the Like, a larger story will appear in the user's friends' News Feed. Learn more…

Facebook Send button

The Send Button allows your users to easily send your content to their friends. People will have the option to send your URL in an inbox message to their Facebook friends, to the group wall of any Facebook group they are a member of, and as an email to any email address. While the Like Button allows users to share your content with all of their friends, the Send Button allows them to send a private message to just a few friends. Learn more…

Facebook Share button

Our version of the conventional Facebook sharecount button lets a user share your content on Facebook. When the user clicks the Share button on your site, a pop-up is invoked in which they are asked to compose a comment. If they complete the share from the pop-up, a link story (with a preview image, title, and description in addition to the user's comment) appears in the user's friends' News Feed with a link back to your website. Learn more…

Twitter Tweet button

The Tweet Button is a small widget which allows users to easily share your website with their followers without having to leave the page. Promote strategic Twitter accounts at the same time while driving traffic to your website. Learn more…

How do I use them?

There are three ways. See the documentation for each button for parameters that allow you to customize the appearance and behavior of your buttons.

1. Custom tag method
   • Include the awe.sm JavaScript library
   • Put our special HTML tag wherever you need a button
   • Use if: you want the simplest, easiest implementation
   • Best for most use cases
2. JavaScript call method
   • Include the awe.sm Javascript library
   • Make JavaScript calls specifying HTML tags to be replaced by buttons
   • Use if:
     • You don't always want the button to show immediately
     • The URL you want users to share is generated later on
   • Best for dynamically-generated content, JavaScript apps.
3. IFRAME method
   • Put an IFRAME tag wherever you need a button
   • Use if:
     • You are concerned about the overhead of executing JavaScript
     • You're writing a plugin that needs precise control of the markup generated
   • Not all FaceBook functionality is available in IFRAME buttons

awe.sm JavaScript library

Both the custom tag and JavaScript call methods require the awe.sm JS library to be loaded at least once (you can load it multiple times without error, but there's no reason to do so). The library creates a single global object called AWESM.

Load library asynchronously (recommended for best performance)

To load the awe.sm JavaScript library, simply include the following code anywhere on the page, replacing the Xs with your 64-character API key.

<script type="text/javascript">
var AWESM = AWESM || {};
AWESM.api_key = 'XXXXXXXXXX';                 

(function() {
    var js = document.createElement('script'); js.type = 'text/javascript'; js.async = true;
    js.src = '//widgets.awe.sm/v3/widgets.js?key=' + AWESM.api_key + '&async=true';
    var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(js,s);
})();
</script> 

Loading the awe.sm library asynchronously will ensure your page renders as fast as possible. It will load via HTTPS if your page is secure.

Or: load library synchronously

If loading the library asynchronously does not fit your needs, you can also include the library directly (replace the Xs with your 64-character API key):

<script src="//widgets.awe.sm/v3/widgets.js?key=XXXXXXXXXX"></script>

In many browsers, page rendering will pause while scripts are loaded, so we recommend putting script tags such as this one as close to the bottom of your markup as possible.

Custom tag method: simplest, easiest.

Step 1: include the awe.sm JS library

See above for instructions. You need include the library only once, no matter how many different buttons are on the page.

Step 2: put our special HTML tag wherever you need it.

Facebook Like button:

<awesm:fblike show_faces="false" width="450"></awesm:fblike>

Facebook Send button:

<awesm:fbsend></awesm:fbsend>

Combined Facebook Like+Send button:

<awesm:fblike show_faces="false" width="450" send="true"></awesm:fblike>

Facebook Share button:

<awesm:fbshare></awesm:fbshare>

Twitter Tweet button:

<awesm:tweet></awesm:tweet>

JavaScript call method: dynamically generated content, JavaScript apps

When created by our custom tag or the IFRAME, buttons are generated at page render time. If you don't always want to show a button, or if the URL you want users to share is generated later on, you may want to generate our buttons on-demand using JavaScript. Developers may also find this method useful when building JavaScript applications.

Step 1: include the awe.sm JS library

See above for instructions. We recommend the asynchronous loading method.

Step 2: set a JavaScript callback (asynchronous library)

If you are loading the awe.sm library asynchronously as recommended, you should embed your calls to the AWESM object inside the AWESM.onavailable callback function. This function will be called as soon as the AWESM object is fully ready. The first parameter to the callback function is the user's sessionId, but our button calls do not use it.

You can only define the onavailable method once. If you are calling multiple buttons, you can put multiple buttons calls inside the onavailable method.

The awesm_buttonid parameter specifies where on the page the button will appear via an HTML ID; the HTML element with that ID will be replaced by the button. If you omit this parameter the library will not know where to put the button, and will log an error to console.

Facebook Like button:

<div id="mylikebutton"></div>
<script>
AWESM.onavailable = function() {
  AWESM.fblike({
      'href': 'http://example.com/my-page.html',
      'awesm_buttonid': 'mylikebutton'
  });
}
</script>

Facebook Send button:

<div id="mysendbutton"></div>
<script>
AWESM.onavailable = function() {
  AWESM.fbsend({
    'awesm_buttonid': 'mysendbutton'
  });
}
</script>

Combined Facebook Like+Send buttons:

<div id="mysendandlikebutton"></div>
<script>
AWESM.onavailable = function() {
  AWESM.fblike({
      'href': 'http://example.com/my-page.html',
      'send': 'true',
      'awesm_buttonid': 'mysendandlinkbutton'
  });
}
</script>

Facebook Share button:

<div id="mysharebutton"></div>
<script>
AWESM.onavailable = function() {
  AWESM.fbshare({
      'href': 'http://example.com/my-page.html',
      'awesm_buttonid': 'mysharebutton'
  });
}
</script>

Twitter Tweet button:

<div id="mytweetbutton"></div>
<script>
AWESM.onavailable = function() {
  AWESM.tweet({
      'data-url': 'http://example.com/my-page.html',
      'awesm_buttonid': 'mytweetbutton'
  });
}
</script>

The href and data-url parameters used in the examples above are optional. See the documentation for each button for a complete list of parameters.

Step 2a: call JavaScript synchronously

If you are loading the awe.sm library synchronously, the onavailable method will still fire, but you can also call the methods synchronously, e.g.

<div id="mylikebutton"></div>
<script>
AWESM.fblike({
    'href': 'http://example.com/my-page.html',
    'awesm_buttonid': 'mylikebutton'
});
</script>

This version of the call will fail if you are using the asynchronous library load.

IFRAME method: for plugin developers

To save the overhead of loading and executing JavaScript on your page, or if you are writing a plugin that is pre-generating markup for a content-management system, you may wish to generate an IFRAME tag directly. Note that you must include your awe.sm API key in the URL as awesm_key.

Facebook does not support rendering the Send button in an IFRAME.

If you include multiple IFRAMED buttons per page, you should pass the parameter capture_data set to false. Failing to do so can result in double-counting clicks and pageviews.

Facebook Like button:

<iframe allowtransparency="true" frameborder="0" scrolling="no"
src="//widgets.awe.sm/v3/fblike_button?awesm_key=XXXXXXXXXX"
style="width:130px; height:50px;"></iframe>

Facebook Like button with capture_data false:

<iframe allowtransparency="true" frameborder="0" scrolling="no"
src="//widgets.awe.sm/v3/fblike_button?awesm_key=XXXXXXXXXX&capture_data=false"
style="width:130px; height:50px;"></iframe>

Facebook Share button:

<iframe allowtransparency="true" frameborder="0" scrolling="no"
src="//widgets.awe.sm/v3/fbshare_button?awesm_key=XXXXXXXXXX"
style="width:53px; height:69px;"></iframe>

Twitter Tweet button:

<iframe allowtransparency="true" frameborder="0" scrolling="no"
src="//widgets.awe.sm/v3/tweet_button?awesm_key=XXXXXXXXXX"
style="width:55px; height:62px;"></iframe>

If you're using WordPress, you can use our Twitter Tweet button plugin or Facebook Share button plugin. A single plugin to add one or more or any of our buttons is coming soon.

Last updated 2012-02-16