Scripting: Events

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 publish a tweet and then followed a related account at the end of the publishing flow.

Note that not all browsers trigger events: if a user chooses to complete the action inside Twitter’s iOS or Android application rather than a Web Intent you may not receive an event for the completed action. Click events on widgets should always complete.

Waiting for Asynchronous Resources

Loading the widgets.js file asynchronously will require you to wait before binding events: the functions you are calling do not yet exist. You will need to wrap your event bindings in a callback function such as the twttr.ready asynchronous function queue 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
  }
);

Available Events

loaded

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

twttr.events.bind(
  'loaded',
  function (event) {
    event.widgets.forEach(function (widget) {
      console.log("Created widget", widget.id);
    });
  }
);

rendered

Occurs after an individual widget in a page is rendered. Includes a 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.

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

tweet

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

Includes a Tweet in reply to an embedded Tweet or a Tweet displayed in an embedded Timeline.

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

follow

This event will populate the followed user_id and screen_name in the event object’s data argument.

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

retweet

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

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

favorite

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

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

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.

// 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 js, fjs = d.getElementsByTagName(s)[0],
    t = window.twttr || {};
  if (d.getElementById(id)) return;
  js = d.createElement(s);
  js.id = id;
  js.src = "https://platform.twitter.com/widgets.js";
  fjs.parentNode.insertBefore(js, fjs);

  t._e = [];
  t.ready = function(f) {
    t._e.push(f);
  };

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

// Define our custom event handlers
function clickEventToAnalytics (intentEvent) {
  if (!intentEvent) return;
  var label = intentEvent.region;
  pageTracker._trackEvent('twitter_web_intents', intentEvent.type, label);
}

function tweetIntentToAnalytics (intentEvent) {
  if (!intentEvent) return;
  var label = "tweet";
  pageTracker._trackEvent(
    'twitter_web_intents',
    intentEvent.type,
    label
  );
}

function favIntentToAnalytics (intentEvent) {
  tweetIntentToAnalytics(intentEvent);
}

function retweetIntentToAnalytics (intentEvent) {
  if (!intentEvent) return;
  var label = intentEvent.data.source_tweet_id;
  pageTracker._trackEvent(
    'twitter_web_intents',
    intentEvent.type,
    label
  );
}

function followIntentToAnalytics (intentEvent) {
  if (!intentEvent) return;
  var label = intentEvent.data.user_id + " (" + intentEvent.data.screen_name + ")";
  pageTracker._trackEvent(
    'twitter_web_intents',
    intentEvent.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);
});

Supplemental Events Resources and Examples

• Google Analytics Event Tracking Guide
• Twitter Intent Events with Google Analytics using _gaq.push(); by @nulluk
• An optimized approach to Google Analytics integration by @yahel

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.