Overview

The Social Sharing API provides access to the Janrain Engage Social Widget, which allows users to post activity updates to popular social networks.

The Social Widget provides an interface for users to select which social networks will be updated, and once the updates have been posted the user will be presented with a page linking to the new posts on each social network.

To use the API, create a function which creates an Activity object and passes it to publishActivity. Use the Setup API to load the Social module and invoke your function.

Setup API

Janrain Engage provides a top-level "bootstrapping" API to give you access to the social API. While we provide a detailed example on the Social Sharing page of your Janrain Engage application, we present the details here for reference.

To get started, follow these steps:

1. Load the Janrain Engage javascript (https://rpxnow.com/js/lib/rpx.js) as the last element in the BODY of your HTML document.
2. Initialize the RPXNOW library with RPXNOW.init({appId: "...", xdReceiver: "..."}). appId is your Application ID as shown on your application dashboard and xdReceiver is the absolute path to the cross-domain communication document that Janrain Engage requires you to host (e.g., "/rpx_xdcomm.html").
3. Load the appropriate module(s) and supply a callback with RPXNOW.loadAndRun. This function takes a list of module names and a callback. Once the specified modules are loaded, your callback will be called. To determine which module(s) you need to load, see the individual API specifications below. Sample:

   RPXNOW.loadAndRun(['Social'], publishMyComment);

RPXNOW.Social.publishActivity

Modules: ['Social']

This call provides in-page social sharing. Calling this function creates an in-page overlay that lets the user select up to four social sites to publish an activity to. If the user needs to authenticate or authorize posting with any of those sites, a popup with an address bar will be opened at the remote site to perform that activity.

To clear the cookies used by the widget to maintain authentication state, call clearSocialCookies.

var activity = new RPXNOW.Social.Activity(...);
RPXNOW.Social.publishActivity(activity);

The options parameter

You can supply an options parameter to publishActivity. options can be specified as an array of JavaScript objects with the following structure:

Attribute	Required?	Description
finishCallback	no	A callback function to invoke once publishing is finished. The function should take a single parameter whose structure is described in the finishCallback section.
exclusionList	no	A JavaScript list of provider names you would like to exclude from the widget for this invocation only.
urlShortening	no	A boolean indicating whether to provide the entire url in the post/tweet, or the shortened version. Defaults to true.
postTruncation	no	'true' (default) or 'false'. If 'true', truncate activity update text when posting to providers which impose a length limit (currently Twitter).
primaryKey	no	The primary key, as a string, you have used with the Mapping API. This value is used as a hint for displaying providers as connected based on the mappings associated with the primary key.
timestamp	w/ primaryKey	A unix timestamp. The timestamp is an integer representing the number of seconds elapsed since midnight proleptic Coordinated Universal Time (UTC) of January 1, 1970, not counting leap seconds.
signature	w/ primaryKey	A Base64 encoded HMAC SHA-256 signature. The signature is computed by applying the HMAC SHA-256 function to a key and a message. The key is your applications apiKey. The message is constructed by joining the timestamp as a decimal string with the primaryKey separated by the '|' character. For example: apiKey = "1a26526515aa34bcc15d04715006f9b7437c2b61" timestamp = 1275987204 primaryKey = "DEADBEAFC0FFEEDEADBEAF" message = "1275987204|DEADBEAFC0FFEEDEADBEAF" signature = "I5kckgc3v4JaxavG5QQ8+FTbBKgPrmu+2+zXZZ93124=" SECURITY: The signature MUST be computed server-side to avoid exposing your apiKey.

var activity = new RPXNOW.Social.Activity(...);

var finished = function(results) {
  // Process results of publishing.
}
RPXNOW.Social.publishActivity(activity,
  {
   finishCallback: finished,
   exclusionList: ["facebook", "yahoo"],
   urlShortening: true,
   primaryKey: '1029384756',
   timestamp: 1275987204,
   signature: 'I5kckgc3v4JaxavG5QQ8+FTbBKgPrmu+2+zXZZ93124='
  }
);

The finishCallback

If you supply a finishCallback to publishActivity, it will be called once publishing has completed. The callback will be given a single parameter which will be JavaScript array of objects each with the following structure:

RPXNOW.Social.Activity

Modules: ['Social']

This class provides a straightforward API for creating correctly-structured activity objects for the publishActivity javascript API call. Methods that verify the form/content of their arguments throw javascript Errors when they fail.

The constructor alone provides sufficient data to make a successful publishActivity call. The other methods allow you to provide additional information that some social sites may take advantage of to render a complete story.

Constructor

Methods

addActionLink

Adds a short link to the end of Facebook posts only.

addTextProperty

Adds a property to Facebook posts only. This version creates a text property.

addLinkProperty

Adds a property to Facebook posts only. This version creates a link property.

addProviderUrl

Adds a provider-specific publish URL.

Media Items

These classes encapsulate the different types of media attachments Facebook allows. LinkedIn supports one image from the ImageMediaCollection attachment. At the moment, no other supported provider supports any media attachment from third-party sources.

Mp3MediaItem

This class encapsulates an mp3, which will be displayed with Facebook's mp3 player. The required fields in the constructor are the minimum sufficient information to use this class.

Additionally, there are methods to set all the optional fields.

VideoMediaItem

This class encapsulates a video, which will be displayed with Facebook's video player. The required fields in the constructor are the minimum sufficient information to use this class.

Additionally, there are methods to set all the optional fields.

FlashMediaItem

This class encapsulates a flash application, which will be displayed on Facebook. The required fields in the constructor are the minimum sufficient information to use this class.

Additionally, there are methods to set all the optional fields.

ImageMediaCollection

This class encapsulates a set of up to 5 images, which will be displayed as thumbnails by Facebook. LinkedIn will only use the first image. At least one call to addImage must be made.

var activity = new RPXNOW.Social.Activity(
                "Share your status",
                "changed his status on Velog",
                "http://velog.com/brian");

activity.setUserGeneratedContent('rode 5 miles in the rain');

activity.addActionLink('Buy a bike', 'http://portlandbicylestudio.com/');
activity.addActionLink('Join velog', 'http://velog.com/');

activity.addTextProperty('Distance', '5 miles');
activity.addTextProperty('Weather', 'Rain');

var song = new RPXNOW.Social.Mp3MediaItem(
            "http://brianellin.com/Mannequin.mp3",
            "Mannequin",
            "Wire");

activity.setMediaItem(song);

RPXNOW.Social.clearSocialCookies

Modules: ['Social']

This call removes all state that the social widget uses to track who to publish updates to. It's intended to be called when a user logs out of your application. Since the cookies are stored on Janrain's domain, a hidden iframe is loaded to clear the cookies on the correct domain. Since that process can take a bit of time, and you'd often like to use this as part of a Sign Out action, the call can optionally take an absolute URL to redirect the browser to upon completion of loading the hidden iframe. If provided, the URL must be absolute and the domain must match the current page's domain.

RPXNOW.Social.clearSocialCookies();

RPXNOW.Social.clearSocialCookies("http://your.domain.com/path/");