Social Sharing JavaScript API: Social Sharing Events

The Social Sharing solution supports client-side handling of a number of events. These are useful for customizing the user experience or tracking user behavior with a third-party analytics tool.

To handle events generated by Social Sharing, register your event handlers using the janrain.social method within the janrainSocialOnLoad function. Each of the following events has on and off methods that may be used to register callback functions.


<script type="text/javascript">
 functionjanrainSocialOnLoad(){
 janrain.social.on({
 provider_select:function(data){
 console.log("Clicked on provider "+ data.provider);
 },
 auth_done:function(data){
 console.log("Authorized for provider "+ data.provider);
 },
 share_done:function(data){
 console.log("Sharing completed for provider "+ data.provider);
 }
 });
 }
</script>

Event Methods

Each event method will accept an eventName to callback mapping. See the Event Responses section for the data that will be available for the callback function to handle.

.on(eventName, callback)

This method will register a callback for the specified eventName. It will accept one event per call. Example:


<script type="text/javascript">
 functionjanrainSocialOnLoad(){
 janrain.social.on("share_done",function(data){
 console.log("Sharing completed for provider "+ data.provider);
 });
 }
</script>

If you have multiple instances of Social Sharing on a single page, you can specify an individual instance by passing in the instance’s HTML ID in the form of eventName:instanceId. Example:


<script type="text/javascript">
 functionjanrainSocialOnLoad(){
 janrain.social.on("share_done:shareInstance1",function(data){
 console.log("Sharing completed for provider "+ data.provider);
 });
 }
</script>

.on(eventNameToCallbackMapping)

If you have multiple events you want to call, you can pass them into the same method inside of an object with eventName:callback pairs. The following examples are equivalent:


<script type="text/javascript">
 functionjanrainSocialOnLoad(){
 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);
 }
 });
 }
</script>
<script type="text/javascript">
 functionjanrainSocialOnLoad(){
 janrain.social.on("provider_select",function(data){
 console.log("Clicked on provider "+ data.provider);
 });
 janrain.social.on("share_done",function(data){
 console.log("Sharing completed for provider "+ data.provider);
 });
 }
</script>

.off(eventName, callback)

This method will remove a callback from the specified eventName. It will accept one event per call.


<script type="text/javascript">
 janrain.social.off("share_done",shareCompleteCallback);
</script>

auth_done

Type: Share Authorization

Fired when a user authorizes a provider for sharing.

auth_fail

Type: Share Activity

Fired when a user fails to authorize a provider for sharing.

provider_select

Type: Share Activity

Fired when a user clicks on a provider icon.

share_done

Type: Share Authorization

Fired when a user successfully completes sharing. For broadcast sharing, the share will occur immediately after the user authorizes a provider for sharing and the auth_done event fires.

share_fail

Type: Share Activity

Fired when the user cancels sharing or there was an error.

share_start

Type: Share Activity

Fired when a user clicks on the Share button.

Event Responses

Depending on the event type, different information is passed to the event handler function.

Share Activity

These types of events contain the HTML ID of the share tool that was used, the name of the social identity provider used for authentication, and the sharing mode (email, contact, or broadcast). Example event:


{
    "id": "shareInstance1",
    "provider": "facebook",
    "mode": "broadcast"
}

Share Authorization

These types of events contain the HTML ID of the share tool that was used, the name of the social identity provider used for authentication, the sharing mode (email, contact, or broadcast), and an authentication token from the social provider. Example event:


{
    "id": "shareInstance2",
    "provider": "facebook",
    "mode": "broadcast",
    "auth_token": "ab12cd34ef56gh78ij90kl12mn34op56qr78st78"
}