Scripting: Events

Updated on Thu, 2014-05-01 23:53

By using Twitter Javascript, you agree to the Developer Rules of the Road.

By default, widgets-js will find mark-up in a page and convert basic, functional mark-up into rich interactive widgets. In addition, there are a number of functions of widgets-js that allow developers to work with Twitter content dynamically, after the page has loaded:

If you're integrating your site with Twitter using Web Intents or Twitter for Websites widgets, Web Intent Events provide an easy way to integrate feedback in your application, and respond to user interaction with intents. By adding listeners to the actions users perform in Web Intents, you can trigger functionality in your app, or send (anonymous) data about those events to your web analytics system (like Google Analytics, Omniture, or your own analytics engine.)

Bind an event like this:

twttr.events.bind('click', function (ev) { console.log(ev); }

The Intent Event Object

When a detectable action occurs within a Web Intent or widget, an object representing the event is passed to your JavaScript callback. Intent Event objects include the following data:

Intent event object
Attribute Return Format Example Values
target HTMLElement The DOM node where the widget is instantiated. Most like an iframe, but may also be the original embed code element if the widget failed to initialize, or another sandboxed element. Use this value to differentiate between different intents or buttons on the same page.
region String Extended detail indicating where in a widget a user clicked. For example, button, count, or screen name portions of Tweet button or Follow button integrations, or tweet actions within embedded Tweets. tweet, count, follow, screen_name
data Object Key/value pairs relevant to the Web Intent just actioned Possible key values include: tweet_id, source_tweet_id, screen_name, and user_id

When Events Are Triggered

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.

Note that no all browsers trigger events, and if a user chooses to use a native application rather than a Web Intent to complete their interaction you may not get an event for the action. Click events on widgets should always function.

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.

Available Events

  1. twttr.ready(function (twttr) {
  2.   // bind events here
  3. });

loaded

Occurs after twttr.widgets.load has initialized widgets in a page, from an embed code. Includes an array of references to the newly created widget nodes.

  1. twttr.events.bind('loaded', function (event) {
  2.   event.data.widgets.forEach(function (widget) {
  3.     console.log("Created widget", widget.id);
  4.   });
  5. });

rendered

Occurs after an individual widget in a page is rendered. Includes a of reference to the newly created widget node. Occurs at the same time as loaded, but for each individual widget. Also triggered when creating a widget with a factory function.

  1. twttr.events.bind('rendered', function (event) {
  2.   console.log("Created widget", event.data.target.id);
  3. });

tweet

This event will be triggered when the user publishes a Tweet (either new, or a reply) through the Tweet Web Intent.

  1. twttr.events.bind('tweet', function (event) {
  2.   // Do something there
  3. });

follow

This event will populate the followed user_id in the event object's data argument.

  1. twttr.events.bind('follow', function (event) {
  2.   var followedUserId = event.data.user_id;
  3.   var followedScreenName = event.data.screen_name;
  4. });

retweet

This event will populate the original Tweet that was retweeted's source_tweet_id in the event object's data argument.

  1. twttr.events.bind('retweet', function(event) {
  2.     var retweetedTweetId = event.data.source_tweet_id;
  3. });

favorite

This event will populate the favorited tweet_id in the event object's data argument.

  1. twttr.events.bind('favorite', function(event) {
  2.     var favoritedTweetId = event.data.tweet_id;
  3. });

click

Receive an event when the user invokes a Web Intent from within an embedded widget.

Example: Detecting 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.

  1. // Log any kind of Web Intent event to Google Analytics
  2. // Category: "twitter_web_intents"
  3. // Action: Intent Event Type
  4. // Label: Identifier for action taken: tweet_id, screen_name/user_id, click region
  5.  
  6. // First, load the widgets.js file asynchronously
  7. window.twttr = (function (d,s,id) {
  8.   var t, js, fjs = d.getElementsByTagName(s)[0];
  9.   if (d.getElementById(id)) return; js=d.createElement(s); js.id=id;
  10.   js.src="https://platform.twitter.com/widgets.js"; fjs.parentNode.insertBefore(js, fjs);
  11.   return window.twttr || (t = { _e: [], ready: function(f){ t._e.push(f) } });
  12. }(document, "script", "twitter-wjs"));
  13.  
  14. // Define our custom event handlers
  15. function clickEventToAnalytics (intentEvent) {
  16.   if (!intentEvent) return;
  17.   var label = intentEvent.region;
  18.   pageTracker._trackEvent('twitter_web_intents', intentEvent.type, label);
  19. }
  20.  
  21. function tweetIntentToAnalytics (intentEvent) {
  22.   if (!intentEvent) return;
  23.   var label = "tweet";
  24.   pageTracker._trackEvent('twitter_web_intents', intentEvent.type, label);
  25. }
  26.  
  27. function favIntentToAnalytics (intentEvent) {
  28.   tweetIntentToAnalytics(intentEvent);
  29. }
  30.  
  31. function retweetIntentToAnalytics (intentEvent) {
  32.   if (!intentEvent) return;
  33.   var label = intentEvent.data.source_tweet_id;
  34.   pageTracker._trackEvent('twitter_web_intents', intentEvent.type, label);
  35. }
  36.  
  37. function followIntentToAnalytics (intentEvent) {
  38.   if (!intentEvent) return;
  39.   var label = intentEvent.data.user_id + " (" + intentEvent.data.screen_name + ")";
  40.   pageTracker._trackEvent('twitter_web_intents', intentEvent.type, label);
  41. }
  42.  
  43. // Wait for the asynchronous resources to load
  44. twttr.ready(function (twttr) {
  45.   // Now bind our custom intent events
  46.   twttr.events.bind('click', clickEventToAnalytics);
  47.   twttr.events.bind('tweet', tweetIntentToAnalytics);
  48.   twttr.events.bind('retweet', retweetIntentToAnalytics);
  49.   twttr.events.bind('favorite', favIntentToAnalytics);
  50.   twttr.events.bind('follow', followIntentToAnalytics);
  51. });

Supplemental Events Resources and Examples

These functions make it possible to integrate Twitter user's content into your site dynamically in a JavaScript application, and integrate user interactions into your own application experience.

Please ask questions and share your code and examples in the developer forum. You may also refer to the main Twitter for Websites documentation.