Scripting: Events

The Twitter for Websites JavaScript fires events on initialization and after a viewer interacts with a widget. Enhance your application and analytics by tapping into widget events.

Note that Web Intent events fire when the interaction occurs, not after the action completes.

Bind an Twitter widget event in your JavaScript code by registering a callback function with twttr.events.bind.

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 properties

Property Data Type Description
target HTMLElement The DOM node where the widget is instantiated. Most likely 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 the event originated. For example, button or count components of Tweet button or Follow button integrations, or Tweet actions within an embedded Tweet.
data Object Key/value pairs relevant to the event.

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 clicks a 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 or screen_name in the event object’s data argument, depending on the parameters you provided in the web intent.

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;
  }
);

like

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

twttr.events.bind(
  'like',
  function(event) {
    var likedTweetId = 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 likeIntentToAnalytics (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('like', likeIntentToAnalytics);
  twttr.events.bind('follow', followIntentToAnalytics);
});

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.