Sharing Widget

Documentation
Widgets
Sharing Widget

The Social Sharing Widget enables your users to post activities from your site to social sites (Facebook, Twitter, Yahoo!, and others). Users can even post to multple social networks at once.

How it works

Activity — User performs an action on your site like a comment, rating, review, or purchase and then your site invokes the Social Sharing Widget by calling a method on our JavaScript object.
Publish — User selects one or more social networks, and can add additional notes, then clicks Publish. Janrain Engage sends the activity to all of the selected networks.

Sharing a Video with Social Sharing

You can implement the Sharing Widget in conjunction with the Login Widget, or separately.

Implementation

The main steps to implement the Sharing Widget are:

Include the Widget Library on your page.
Initialize the Widget API with your credentials.
Create an Activity Object.
Invoke publishActivity, passing your Activity Object.

Step 1. Include the Widget Library

The widget API is a JavaScript library. It is hosted on our CDN (Content Delivery Network) at Janrain’s rpxnow.com domain. You use an HTML script tag to load the API like any other JavaScript library. It’s usually best to put the script tag as the last tag inside your HTML <body> element.

For browser security and performance, different methods are available for HTTP and HTTPS. For simplicity, we show each call individually; and then for practicality, we provide code that dynamically detects and switches between modes for both.

HTTP
<script type="text/javascript" src="http://static.rpxnow.com/"></script>
HTTPS
<script type="text/javascript" src="https://rpxnow.com/"></script>

Step 2. Initialize the Widget API

You initialize the library by passing in your app ID (Application Identifier). You can find your app ID on your Janrain Engage Dashboard. (See Application Info, at the bottom of the Janrain Dashboard page.) For learning purposes, on your local host you can just cut and paste your app ID directly into the JavaScript. For security reasons, your production code should load it dynamically. See the live example at http://engage-sample.janraindemo.com/.
RPXNOW.init({appId: "YOUR APP ID", xdReceiver: window.location+'rpx_xdcomm.html'});

Step 3. Create an Activity Object

var jnActivity = new RPXNOW.Social.Activity("Share", "found", window.location);

Step 4. Invoke publishActivity

Here, we tell the library to load the [Social] module and pass in an anonymous callback function to execute once the [Social] module is loaded. This is a common JavaScript technique.

RPXNOW.loadAndRun(['Social'], function () {
   RPXNOW.Social.publishActivity( window.jnActivity );
});

Server Code

We supply you with a static HTML file, rpx_xdcomm.html, that you must place on your site. This enables communication with your Janrain Engage. Download the file here.

Example of Dynamic HTTP and HTTPS Protocol Detection

This example first sets the host prefix based on the protocol, and then writes the script tag to include the widget library. Many websites add the protocol detection just before the closing <body> tag in the page.

<script type="text/javascript">
  var rpxJsHost =
    (("https:" == document.location.protocol) ? "https://" : "http://static.");
  document.write(
    unescape(
      "%3Cscript src='" +
      rpxJsHost +
      "rpxnow.com/js/lib/rpx.js' type='text/javascript'%3E%3C/script%3E"
    )
  );
</script>

Example JS function with photo thumbnail support

This example requires the rpx.js file above.

<script type="text/javascript"><!--
function rpxSocial (rpxLabel, rpxSummary, rpxLink, rpxLinkText, rpxComment, rpxImageSrc){
  RPXNOW.init({appId: 'qwertyuiopasdfghjklz', xdReceiver: '/rpx_xdcomm.html'});
  RPXNOW.loadAndRun(['Social'], function () {
    var activity = new RPXNOW.Social.Activity(
       rpxLabel,
       rpxLinkText,
       rpxLink);
    activity.setUserGeneratedContent(rpxComment);
    activity.setDescription(rpxSummary);
    if (document.getElementById('rpxshareimg') != undefined &amp;&amp; (rpxImageSrc == '' || rpxImageSrc == null)) {
      rpxImageSrc = document.getElementById('rpxshareimg').src;
    }
    if (rpxImageSrc != '' && rpxImageSrc != null) {
      var shareImage = new RPXNOW.Social.ImageMediaCollection();
      shareImage.addImage(rpxImageSrc,rpxLink);
      activity.setMediaItem(shareImage);
    }
    RPXNOW.Social.publishActivity(activity,
      {finishCallback:function(data){
        for (i in data) {
          if (data[i].success == true) {
            //do something for each share success here
            //e.g. recordShare(data[i].provider_name, data[i].provider_activity_url);
          }
        }
      }
    });
  });
}
--></script>

Activity Properties Mapped to Widget and Post Text

The illustration below shows the mapping of JavaScript code to the Janrain Sharing Widget and to Facebook.

Field to UI Mapping