Our product documentation has a new home.
Please visit: http://documentation.janrain.com for the most current version of Janrain Engage implementation documents.

Janrain: User management platform for the social web

Documentation » Social Sharing API

Contents

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.

Javascript Call
RPXNOW.Social.publishActivity(activity, options)
Parameter Required? Description
activity yes The activity to post. The activity is a javascript object created via the RPXNOW.Social.Activity interface.
options no An associative array of named optional parameters that can be used to control the behavior of the widget for the current invocation. The structure of the objects array can be found in the options parameter section.
Example
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.
Example
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:

Attribute Description
provider_name The name of the provider shown in the overlay
attempted A boolean indicating whether the user attempted to publish to this provider
success A boolean indicating whether an attempted social publish to this provider was successful
provider_activity_url Possibly null; the URL of the activity update, when available from the provider

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

Javascript Constructor
new RPXNOW.Social.Activity(share_display, action, url)
Parameter Required? Description
share_display yes

Tell the user what they're sharing. This is a short string that appears at the top of the social sharing widget that is presented to the user. Examples might include:

  • If the user posted a review: "Share your review"
  • If the user watched a video: "Share this video"
action yes A description of the action the user is sharing, as it should be displayed on the sites the user chooses to share it with.
url yes Where people who see the user's update on social sites can visit for further information. This should be as specific as possible. If the user is sharing a review they wrote, this url should point to the review. If they are sharing a video they watched, it should be a link to the page with the video embedded in it. It's also possible to specify provider-specific URLs, see the addProviderUrl method.

Methods

Javascript method on RPX.Social.Activity objects
setTitle(title)
Parameter Required? Description
title yes The title for this activity. This information is displayed by Yahoo!, Facebook and LinkedIn.
Javascript method on RPX.Social.Activity objects
setDescription(description)
Parameter Required? Description
description yes A description of this activity. This information is displayed by Facebook and LinkedIn.
Javascript method on RPX.Social.Activity objects
setUserGeneratedContent(user_generated_content)
Parameter Required? Description
user_generated_content yes Any textual content the user made about this action. If this is provided, it overrides the action for Yahoo!, Myspace, LinkedIn and Twitter. It is displayed in an independent location on Facebook.

addActionLink

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

Javascript method on RPX.Social.Activity objects
addActionLink(text, url)
Parameter Required? Description
text yes The text of the link. This should be short, preferably one or two words.
url yes The url the link goes to.

addTextProperty

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

Javascript method on RPX.Social.Activity objects
addTextProperty(name, text)
Parameter Required? Description
name yes The name of the property being displayed.
text yes The text of the property being displayed.

addLinkProperty

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

Javascript method on RPX.Social.Activity objects
addLinkProperty(name, text, url)
Parameter Required? Description
name yes The name of the property being displayed.
text yes The text of the link portion of the property being displayed.
url yes The target of the link portion of the property being displayed.
Javascript method on RPX.Social.Activity objects
setMediaItem(mediaItem)
Parameter Required? Description
mediaItem yes A media item object to embed into Facebook posts only. This is a complex structure and should be generated using the media item apis.

addProviderUrl

Adds a provider-specific publish URL.

Javascript method on RPX.Social.Activity objects
addProviderUrl(provider, url)
Parameter Required? Description
provider yes The name of the provider to add the URL for.
url yes A provider-specific publish URL to use instead of the default URL set through the RPXNOW.Social.Activity constructor.

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.

Javascript Constructor
new RPXNOW.Social.Mp3MediaItem(src, title, artist, album)
Parameter Required? Description
src yes The absolute URL of the MP3 to embed.
title no The title of the MP3 track.
artist no The artist of the MP3 track.
album no The album the MP3 track is from.

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

Javascripts method on RPX.Social.Mp3MediaItem objects
setTitle(title)
setArtist(artist)
setAlbum(album)

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.

Javascript Constructor
new RPXNOW.Social.VideoMediaItem(video_src, preview_img, video_link, video_title)
Parameter Required? Description
video_src yes The absolute URL of the video to embed.
preview_img yes The image to show as the preview for the video.
video_link no An absolute URL to link the user to, from the video.
video_title no The title of the video.

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

Javascripts method on RPX.Social.VideoMediaItem objects
setVideoLink(video_link)
setVideoTitle(video_title)

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.

Javascript Constructor
new RPXNOW.Social.FlashMediaItem(
swfsrc, imgsrc, width, height, expanded_width, expanded_height)
Parameter Required? Description
swfsrc yes The absolute URL of the .swf file to embed.
imgsrc yes The image to show as the preview for the Flash application.
width no The width to display the preview at, before the application is started. Must be a value of 100, 110, or 130.
height no The height to display the preview at, before the application is started. Must be between within the range 30 to 100.
expanded_width no The width to display the application at after it's started. Max size if 460. Note: if not provided, the player will run at thumbnail size.
expanded_height no The height to display the application at after it's started. Max size is 460. Note: if not provided, the player will run at thumbnail size.

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

Javascripts method on RPX.Social.FlashMediaItem objects
setWidth(width)
setHeight(height)
setExpandedWidth(expanded_width)
setExpandedHeight(expanded_height)

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.

Javascript Constructor
new RPXNOW.Social.ImageMediaCollection()
Javascript method on RPX.Social.ImageMediaCollection objects
addImage(src, href)
Parameter Required? Description
src yes The absolute URL of the image being added to the collection.
href yes The absolute URL that the image is a link to.
Example
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.

Example
RPXNOW.Social.clearSocialCookies();
Example
RPXNOW.Social.clearSocialCookies("http://your.domain.com/path/");
Copyright © 2016 Janrain, Inc.