Web Intents Javascript Events

Updated on Thu, 2011-12-08 11:06

By using Web Intents Javascript Events, you agree to the Developer Rules of the Road.

If you're integrating your site with Twitter using Web Intents, the Tweet Button and the Follow Button, and you want to detect the value you're getting from the integration, Web Intents Events provide the easiest way to measure user interaction with intents.

By adding a few basic "listeners" to the actions users perform in Web Intents, you can easily send data about those events to your web analytics provider (like Google Analytics and Omniture) or to your own analytics engine. These Javascript Events won't work if you are directly using iframed versions of the Tweet Button and Follow Button.

You must include the widgets.js file if you are using event bindings. We encourage you to use the code snippet below to asynchronously load the widgets.js file, which will also require you to wait for and invoke a callback. Loading the widgets.js synchronously will still work and will not require the use of the callback.

<script type="text/javascript" charset="utf-8">

```
  window.twttr = (function (d,s,id) {
```

    var t, js, fjs = d.getElementsByTagName(s)[0];

    if (d.getElementById(id)) return; js=d.createElement(s); js.id=id;

    js.src="//platform.twitter.com/widgets.js"; fjs.parentNode.insertBefore(js, fjs);

    return window.twttr || (t = { _e: [], ready: function(f){ t._e.push(f) } });

  }(document, "script", "twitter-wjs"));

```
</script>
```

The Intent Event Object

When a detectable action occurs within a Web Intent, Tweet or Follow Button, an object representing the Intent Event is passed to your Javascript callback. Intent Event objects respond to the following methods:

Method	Return Format	Example Values
type	a String noting the type of event that occurred	"click", "favorite", "tweet", "retweet", "follow"
target	a DOM node reference to HTML element or IFRAME. This value will correspond to the original inciting DOM element. Use this value to differentiate between different intents or buttons on the same page.
region	A String indicating whether the user clicked a Tweet Button, Follow Button, Tweet Count, or Screen Name on Tweet Button or Follow Button integrations.	"tweet", "count", "follow", "screen_name"
data	a Javascript hash with key/value pairs relevant to the Web Intent just actioned	Possible key values include: "tweet_id", "source_tweet_id", "screen_name", and "user_id"

Intent Events

You can bind a callback function to each of these events. Events are triggered when the underlying action is successfully completed by the user. Some Web Intents may result in multiple event triggers — for instance, both the "tweet" and "follow" intent events would trigger if a user used the Tweet Button to issue a tweet, and then followed a related account at the end of the flow.

Waiting for Asynchronous Resources

Loading the widgets.js file asynchronously will require you to wait before binding events. You will need to wrap your event bindings in a callback function which will be invoked once everything has loaded. All event examples below assume you have wrapped those event bindings in this callback.

```
  twttr.ready(function (twttr) {
```
```
    // bind events here
```
```
  });
```

Supported by: Tweet Button & Web Intents

This event will be triggered when the user publishes his tweet within the share box.

twttr.events.bind('tweet', function(event) {

```
    // Do something there
```
```
});
```

follow

Supported by: Tweet Button, Follow Button, & Web Intents

This event will populate the followed user_id in the Event Object's data method.

twttr.events.bind('follow', function(event) {

    var followed_user_id = event.data.user_id;

    var followed_screen_name = event.data.screen_name;

```
});
```

retweet

Supported by: Web Intents

This event will populate the original Tweet that was retweeted's source_tweet_id in the Event Object's data method.

twttr.events.bind('retweet', function(event) {

    var retweeted_tweet_id = event.data.source_tweet_id;

```
});
```

favorite

Supported by: Web Intents

This event will populate the favorited tweet_id in the Event Object's data method.

twttr.events.bind('favorite', function(event) {

    var favorited_tweet_id = event.data.tweet_id;

```
});
```

click

Supported by: Tweet Button & Follow Button

Receive an event when the user has clicked the Tweet Button or Follow Button.

The Event Object returned in your callback will respond to a region method returning a string with four possible states:

"tweet" — the click occurred on the Tweet Button itself, invoking an Intent (which will trigger an Intent Event Callback when complete).
"count" — the click occurred on the Tweet Count portion of the Tweet Button, resulting in navigation to a Twitter.com search experience.
"follow" — the click occurred on the Follow Button itself, which may lead to an immediate follow event if the user already had an active Twitter session, or otherwise the invocation of the Follow Web Intent which may in turn also trigger a follow event.
"screen_name" — the click occurred on the screen name portion of the Follow Button, resulting in the invoking of a User Intent pop-up. If the user chooses to follow from this pop-up, a follow event will be triggered.

twttr.events.bind('click', function(event) {

```
    var click_type = event.region;
```
```
});
```

Detectable Events for Web Analytics

It's easy to capture these events and pipe them to your web analytics solution. Please note that you'll need to be using HTTP or HTTPs protocols on the hosting page for these events, file:// scheme is not supported.

  // Log any kind of Web Intent event to Google Analytics

```
  // Category: "twitter_web_intents"
```
```
  // Action: Intent Event Type
```

  // Label: Identifier for action taken: tweet_id, screen_name/user_id, click region

```
 
```

  // First, load the widgets.js file asynchronously

```
  window.twttr = (function (d,s,id) {
```

    var t, js, fjs = d.getElementsByTagName(s)[0];

    if (d.getElementById(id)) return; js=d.createElement(s); js.id=id;

    js.src="//platform.twitter.com/widgets.js"; fjs.parentNode.insertBefore(js, fjs);

    return window.twttr || (t = { _e: [], ready: function(f){ t._e.push(f) } });

  }(document, "script", "twitter-wjs"));

```
 
```
```
  // Define our custom event hanlders
```

  function clickEventToAnalytics(intent_event) {

```
    if (intent_event) {
```
```
      var label = intent_event.region;
```

      pageTracker._trackEvent('twitter_web_intents', intent_event.type, label);

```
    };
```
```
  }
```
```
 
```

  function tweetIntentToAnalytics(intent_event) {

```
    if (intent_event) {
```
```
      var label = "tweet";
```

      pageTracker._trackEvent('twitter_web_intents', intent_event.type, label);

```
    };
```
```
  }
```
```
 
```

  function favIntentToAnalytics(intent_event) {

    tweetIntentToAnalytics(intent_event);

```
  }
```
```
 
```

  function retweetIntentToAnalytics(intent_event) {

```
    if (intent_event) {
```

      var label = intent_event.data.source_tweet_id;

      pageTracker._trackEvent('twitter_web_intents', intent_event.type, label);

```
    };
```
```
  }
```
```
 
```

  function followIntentToAnalytics(intent_event) {

```
    if (intent_event) {
```

      var label = intent_event.data.user_id + " (" + intent_event.data.screen_name + ")";

      pageTracker._trackEvent('twitter_web_intents', intent_event.type, label);

```
    };
```
```
  }
```
```
 
```

 // Wait for the asynchronous resources to load

```
 twttr.ready(function (twttr) {
```
```
  // Now bind our custom intent events
```

  twttr.events.bind('click',    clickEventToAnalytics);

  twttr.events.bind('tweet',    tweetIntentToAnalytics);

  twttr.events.bind('retweet',  retweetIntentToAnalytics);

  twttr.events.bind('favorite', favIntentToAnalytics);

  twttr.events.bind('follow',   followIntentToAnalytics);

```
  });
```