Events

The social sharing solution supports client-side handling of a number of events. These are useful for making customizations based on information gathered at run time, and for using third-party analytics to track specific events.

Supported Events

The following events are supported:

Object Description Data
provider_select Fired when the user clicks on a provider icon.
  • id — The HTML ID of the share tool that was used.
  • provider — The name of the provider.
  • mode — “email”, “contact”, or “broadcast”
share_start Fired when the user clicks on the Share button, but before the share actually happens.
  • id — The HTML ID of the share tool that was used.
  • provider — The name of the provider.
  • mode — “email”, “contact”, or “broadcast”
auth_done Fired when the user authorizes a provider for sharing, but before the share actually happens. For broadcast sharing, the share will occur immediately after this authorization step, without additional user interaction.
  • id — The HTML ID of the share tool that was used.
  • provider — The name of the provider.
  • mode — “email”, “contact”, or “broadcast”
  • auth_token — user authenticity token
auth_fail Fired when the user fails to authorize a provider for sharing.
  • id — The HTML ID of the share tool that was used.
  • provider — The name of the provider.
  • mode — “email”, “contact”, or “broadcast”
share_done Fired when the user successfully completes sharing.
  • id — The HTML ID of the share tool that was used.
  • provider — The name of the provider.
  • mode — “email”, “contact”, or “broadcast”
  • auth_token — user authenticity token
share_fail Fired when the user cancels sharing or there was an error.
  • id — The HTML ID of the share tool that was used.
  • provider — The name of the provider.
  • mode — “email”, “contact”, or “broadcast”

Example

function janrainSocialOnLoad() {
    janrain.social.on({
        provider_select: function(data) {
            console.log("Clicked on provider " + data.provider);
        },
        share_done: function(data) {
            console.log("Sharing completed for provider " + data.provider);
        },
        share_fail: function(data) {
            console.log("Sharing failed or was canceled for provider " + data.provider);
        },
        auth_done: function(data) {
            console.log("Authorized for provider " + data.provider);
        }
    });
}

Event Methods on janrain.social

.on(eventName, callback)

Example:

janrain.social.on("share_done", function(data) { ... });

eventName is the name of the event the callback should be fired on.
callback is called with a data object containing the data described in the event documentation table.

eventName can also be of the form “eventName:instanceId” which will only call the callback if the event is fired by a Social tool with HTML ID equal to instanceId.

Example:

janrain.social.on("share_done:main_share_bar", ...);

.on(eventNameToCallbackMapping)

Example:

janrain.social.on({ share_done: callback1, share_fail: callback2 });

This is just a shortcut for calling on repeatedly. The following code snippets are equivalent:

janrain.social.on({ a: f, b: g });
// ...works the same as...
janrain.social.on(a, f);
janrain.social.on(b, g);

.off(eventName, callback)

Example:

janrain.social.off("share_done", shareCompleteCallback);

This function removes the callback from the internal list of callbacks for the specified eventName.