When building customized AddThis experiences, or when integrating AddThis with your own web analytics software (like Omniture or Webtrends), it can be useful to know exactly what’s happening in the UI. We dispatch key events asynchronously for your consumption. N.B. Events are dispatched globally; we do not currently support distinguishing between multiple menus on a page.
If you’re not familiar with JavaScript Events, this article is a good starting point.
Registering an Event Listener
AddThis events behave much like standard DOM events. To be notified when an event occurs, you must indicate which event you’d like to listen to and provide a callback function for the event itself. Upon the even being fired, the provided function will be called with the event object as its single argument. Any relevant event metadata will be attached to the event object.
addthis.addEventListener(type, listener);
type is a string representing the event type to listen for.
listener is a reference to the function handling this event.
Example:
// Alert a message when the AddThis API is ready function addthisReady(evt) { alert('AddThis API is fully loaded.'); } // Listen for the ready event addthis.addEventListener('addthis.ready', addthisReady);
Event Objects
All AddThis event objects have a type and metadata associated with them.
Let’s look at the skeleton of the event handler from the example above:
function eventHandler(evt) { // evt is the event object }
The event object will always have a type property indicating which event was dispatched (so you can use the same handler for multiple events).
function eventHandler(evt) { alert(evt.type); // In the example above, this would alert "addthis.ready" }
Additionally, the event object may provide an data property with additional information about the event. For example, the “addthis.menu.share” event stores which service the user just shared to:
// Alert a message when the user shares somewhere function shareEventHandler(evt) { if (evt.type == 'addthis.menu.share') { alert(typeof(evt.data)); // evt.data is an object hash containing all event data alert(evt.data.service); // evt.data.service is specific to the "addthis.menu.share" event } } // Listen for the share event addthis.addEventListener('addthis.menu.share', shareEventHandler);
Event Types
Code | Description | Data |
---|---|---|
addthis.ready | Dispatched when the API has fully loaded. | none |
addthis.menu.open | Dispatched when a menu pane (the compact menu, the expanded menu, or the email form) is opened. | pane : one of “compact”, “expanded” or “email” |
addthis.menu.close | Dispatched when a menu pane is closed. | pane : one of “compact”, “expanded” or “email” |
addthis.menu.share | Dispatched when the user shares. | service : one of our supported services |
addthis.user.clickback | Dispatched when a page loads and the API can detect that the page view originated from a share. |
|
Event Examples
Putting it all together:
<a class="addthis_button"></a> <script type="text/javascript"> // Alert a message when the user shares somewhere function eventHandler(evt) { switch (evt.type) { case "addthis.menu.open": console.log('menu opened; surface=' + evt.data.pane); break; case "addthis.menu.close": console.log('menu closed; surface=' + evt.data.pane); break; case "addthis.menu.share": console.log('user shared to ' + evt.data.service); break; default: console.log('received an unexpected event', evt); } if (evt.type == 'addthis.menu.share') { alert(typeof(evt.data)); // evt.data is an object hash containing all event data alert(evt.data.service); // evt.data.service is specific to the "addthis.menu.share" event } } // Listen to various events addthis.addEventListener('addthis.menu.open', eventHandler); addthis.addEventListener('addthis.menu.close', eventHandler); addthis.addEventListener('addthis.menu.share', eventHandler); </script>
« Preferred Services & Personalization
Last modified: September 7th, 2016