awe.sm-Powered Tweet Button

Overview

This is effectively a clone of Twitter's official tweet button but with native support for awe.sm.

Specifically, you can specify your awe.sm API Key when embedding the button and have it create a unique awe.sm-powered tracking link for each tweet. This button will also automatically build parent-child relationships between awe.sm-powered links when that setting is enabled on your awe.sm account.

In all other regards, this button should function identically to Twitter's version as specified in the Tweet Button Documentation and Tweet Button FAQ.

Ways to add the Tweet Button to your website

There are three ways you can add the Tweet Button to your webpage.

Using javascript

The easiest way to add the Tweet Button to your website is to use javascript. This method requires adding a line of javascript and an HTML anchor to your webpage. Using this method you can customise the Tweet Button using data attributes and query string parameters.

Notice how the anchor element has a class of twitter-share-button. This is required for the Tweet Button javascript to know which anchor elements to convert to buttons.

<script src="http://tools.awe.sm/tweet-button/files/widgets.js" type="text/javascript"></script>
<a href="http://twitter.com/share" class="twitter-share-button" awesm:key="5c8b1a212434c2153c2f2c2f2c765a36140add243bf6eae876345f8fd11045d9">Tweet</a>

Using the WordPress Plugin

If you're using self-hosted WordPress, you can just grab the Tweet Button with Shortening plugin and enter your awe.sm API Key on the settings page.

Using an iframe

If you prefer you can add a Tweet Button using an iframe. When using this method you have to use query string parameters to customise the Tweet Button’s behavior.

<iframe allowtransparency="true" frameborder="0" scrolling="no"
        src="http://tools.awe.sm/tweet-button/files/tweet_button.html?awesm:key=5c8b1a212434c2153c2f2c2f2c765a36140add243bf6eae876345f8fd11045d9"
        style="width:130px; height:50px;"></iframe>

Properties

There are several properties for the Tweet Button which allow you to customise its behavior. Whilst the Tweet Button will work without any of this properties, using them allows you to provide default values for the user to Tweet. If the query string, data source or link source are not provided the Tweet Button will use the default values available from the web page and referrer information.

To learn more about each property and to see ways you can use them check the examples further down this page.

Properties which can be used by all types of Tweet Button

The properties in this table can be used by the javascript, iframe and build your own Tweet Buttons. Each property is a query string parameter for the http://twitter.com/share URL.

Query String Parameter Description
url URL of the page to share
via Screen name of the user to attribute the Tweet to
text Default Tweet text
related Related accounts
count Count box position
lang The language for the Tweet Button
counturl The URL to which your shared URL resolves to
awesm:key The API Key of the awe.sm account on which you'd like tracking links to the shared URL created

Properties which can be used by the javascript Tweet Button

The properties in this table can only be used by the javascript Tweet Button. When used they provide additional places the Tweet Button can look for information on what to pre fill the Tweet with. The Tweet Button looks for property values in the priority order given in the table. For example when looking for the URL to use, the Tweet Button will:

  1. Look for url in the share link query string.
  2. If not found, look for the data-url attribute of the Tweet Button anchor tag
  3. If not found, look for the rel="canonical" link tag in the head of the document
  4. If not found use the URL of the webpage
Data Source Share query string data- attribute of anchor tag rel= attribute of a link tag Default
Priority 1 2 3 4
URL to Tweet url data-url rel="canonical" HTTP Referrer
via user via data-via rel="me"  
Tweet text text data-text   Content of the <title> tag
Recommended accounts related data-related    
Count box position count data-count   horizontal
Language lang data-lang   en
URL to which your shared URL resolves to counturl data-counturl   the url being shared
API Key of awe.sm account to use awesm:key awesm:key    

Examples

The examples that follow show different ways you can use the Tweet Button. The code to produce the example is also given so you can copy and paste it onto your own website.

These examples are real Tweet Buttons. If you press the button you will see a real Share Box.

Default Tweet Button

The default Tweet Button works without any configuration or parameters beyond your awe.sm API Key. In this example the Tweet Button will use a demo awe.sm API Key (replace it with your own) along with the URL of the current webpage and the content of the <title> element as the text of the Tweet.

<script src="http://tools.awe.sm/tweet-button/files/widgets.js" type="text/javascript"></script>
<div>
   <a href="http://twitter.com/share?awesm:key=5c8b1a212434c2153c2f2c2f2c765a36140add243bf6eae876345f8fd11045d9" class="twitter-share-button">Tweet</a>
</div>

Using the query string to set the url and via properties

Query string configuration can be used in the javascript, iframe and build your own Tweet Button. For each property you should URL encode the value you are sending.

In this example we’ll be setting the awesm:key, url, and via properties, which are URL encoded and joined together using &amp;.

<script src="http://tools.awe.sm/tweet-button/files/widgets.js" type="text/javascript"></script>
<div>
  <a href="http://twitter.com/share?awesm:key=5c8b1a212434c2153c2f2c2f2c765a36140add243bf6eae876345f8fd11045d9&amp;url=http%3A%2F%2Ftotally.awe.sm&amp;via=awesm" class="twitter-share-button">Tweet</a>
</div>

Configuring using data attributes

Whilst query string parameters are a convenient way to share your webpage they can make your anchor tag very long. A long URL is difficult to maintain, especially when you have to URL encode the parameters.

To make things easier the javascript Tweet Button allows you to supply data attributes. These data attributes take the same values and cause the same Tweet Button behaviour as the query string parameters. The difference is they are attributes of the anchor tag, not the URL.

In this example we are setting the awesm:key, url, via, text, related, and count properties.

Notice the related field includes a screen name followed by a colon and then some text. This format for the related attribute allows you to add a custom piece of text to display above the related account name. In this case we will display Our company above the @snowballfactory account name on the recommendations screen.

<script src="http://tools.awe.sm/tweet-button/files/widgets.js" type="text/javascript"></script>
<div>
   <a href="http://twitter.com/share" class="twitter-share-button"
      awesm:key="5c8b1a212434c2153c2f2c2f2c765a36140add243bf6eae876345f8fd11045d9"
      data-url="http://tools.awe.sm/tweet-button/"
      data-via="awesm"
      data-text="Checking out the new awe.sm-powered Tweet Button"
      data-related="snowballfactory:Our company"
      data-count="vertical">Tweet</a>
</div>