Social Sharing v2

Events

Overview

Note: This topic is for legacy Social Sharing v2 support only. For all new integrations, please see the current Social Sharing documentation.

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

Registering Event Handlers

To handle events generated by Social Sharing, define the function janrainShareOnload. The UI will call this function when it is loaded, making it a good place to register event handlers. Each event object provides an addHandler function for this purpose.

Example Event Handler

janrain.events.onShareLoginComplete.addHandler(function(response) {
  // Do something with response
});

Supported Events

The following fields in the janrain.events object define events.

Object Description Event Handler Parameter
onShareCustomizationChange Occurs when a qualified function is called, including:
  • setProviders
  • setProvidersEmail
  • setModes
  • setMobile
  • setOrientation
  • setMessage
  • setTitle
  • setUrl
  • setDescription
  • setImage
  • and every Style function.
An object containing the following fields:
  • defaults − Object of every setting.
  • setting − The current setting of the function.
onShareLoginStart Occurs when the user selects a provider or return experience button from the UI.
  • provider − Returns the provider name.
onShareLoginError Occurs when encountering an error during logging in to Social Sharing.
  • provider − Returns the provider name.
  • widget_type − Returns the type of solution (for example, auth or share).
onShareLoginCancel Occurs when a user closes the provider's sign-in popup.
  • provider − Returns the provider name.
  • widget_type − Returns the type of solution (for example, auth or share).
onShareLoginToken Returns the user token (which may be used in conjunction with other API features).
  • token − Returns the user token.
  • janrainWidgetParameters − An object that returns both widget_type and provider.
onShareLoginComplete Occurs once the user has successfully selected an identity provider to use for sharing the activity.
  • jprovider − Returns the provider name.
onShareContactImportStart Occurs when an identity provider begins transferring a user's contact list to the client website.
  • provider − Returns the provider name.
onShareContactImportError Occurs when an identity provider encounters an error during the process of transferring a user's contact list to the client website.
  • message − Returns the error message generated by the import.
onShareContactImportComplete Occurs when an identity provider has completed transferring a user's contact list to the client website.
  • provider − Returns the provider name.
  • contacts − An array of objects containing information describing the user's contacts. Information includes provider, username, image location, and so on.
onShareUserInfoImportError Occurs when an identity provider encounters an error while transferring user information to the client website.
  • message − Returns the error message generated by the import.
onShareUserInfoImportComplete Occurs when an identity provider has successfully completed transferring user information to the client website.
  • provider − Returns the provider name.
  • name − Returns the user name.
  • image − URL of user image.
  • email − User email address.
onShareLogoutStart Occurs when a user chooses to exit Social Sharing.
  • provider − Returns the provider name.
onShareLogoutComplete Occurs when the user has successfully exited Social Sharing.
  • provider − Returns the provider name.
onShareSendStart Occurs once the solution has initiated sending sharing information to the identity provider.
  • provider − Returns the provider name.
  • mode − Returns the sharing mode of email, contact, or broadcast.
  • contacts − An array of objects containing information describing the user's contacts. Information includes provider, username, image location, and so on.
  • title − Title of the shared content.
  • url − Additional URL associated with the shared content.
  • description – Returns the text describing the shared content.
  • message − Returns the user generated content.
  • image − URL pointing to the image associated with the shared content.
  • media − URL pointing to the media associated with the shared content.
  • actionLink − Returns the name and link to the shared content.
onShareSendError Occurs if Social Sharing encounters an error while sending sharing information to the identity provider.
  • provider − Returns the provider name.
  • mode − Returns the sharing mode of email, contact, or broadcast.
  • results − Provides an object that details the failure and contains the error code and description.
  • success − Returns false.
onShareSendComplete Returns a receipt of the shared information from the identity provider.
  • provider − Returns the provider name.
  • pmode − Returns the sharing mode of email, contact, or broadcast.
  • presults − Provides an object that details the failure, and contains the error code and description. Note: In contact mode, the recipientId handler returns ID numbers for contacts.
  • psuccess − Returns false.
onShareContactSelect Occurs once the user selects a contact from the user's contact list.
  • provider − Returns the provider name.
  • contact − Returns a hash of information describing the user contact. Information includes provider, username, image location, and other fields depending on the provider.
onShareContactUnselect Occurs once the user de-selects a contact from the user's contact list.
  • provider − Returns the provider name.
  • contact − Returns a hash of information describing the user contact. Information includes provider, username, image location, and other fields depending on the provider.
onShareProviderSelect Occurs once the user selects a provider.
  • provider − Returns the provider name.
onShareInputMessage Occurs on the keyup event as a user is entering a message in the message text area.
  • provider − Returns the provider name.
  • message − Returns the user-generated text in the message text box.
onShareEmailDirect Occurs when the user clicks the Send email directly link when sharing via email.
  • provider − Returns the provider name.
  • message − Returns the user-generated text in the message text box.
onShareReturnExperienceFound Occurs when Social Sharing loads and finds a relevant cookie stating which providers were last used. This event fires once for each provider that has a return experience.
  • provider − Returns the provider name.
  • image − URL pointing to the image associated with the shared content.
  • name − Returns the user name.
onModalOpen Fires when the modal window opens. None
onModalClose Fires when the modal window closes. None
onProviderLoginCancel Occurs when the end user clicks Cancel or No Thanks on the login screen. Some identity providers do not include a Cancel button or their cancel message does not get passed to Social Login. You may encounter issues with these providers:
  • AOL
  • Disqus
  • Flickr
  • Foursquare
  • Linkedin
  • LiveJournal
  • Renren
  • Tumblr
  • Twitter
  • Verisign
  • WordPress
  • Yahoo!
This event is fired from inside the cancelLogin call.
onProviderLoginComplete Occurs when the sign-in process is complete (whether successful or not). None
onProviderLoginError Occurs when encountering an error during the sign-in process. An object containing the following fields:
  • err − Error object
  • code − Numeric error code
  • msg − Descriptive error string
  • origin − Origin of sign-in error
  • stat − Status message
onProviderLoginStart Occurs when the user clicks the provider or return experience button, beginning the sign-in process. Object with a single field (indicating provider chosen).
onProviderLoginSuccess Occurs when the user successfully signs in. None
onProviderLoginToken Occurs when the user successfully signs in, and the  tokenAction setting is true. A response object containing a single token field (which contains the one-time token).
onProviderLogoutComplete Fires when the user successfully signs out. Object with a single field (which indicates provider).
onProviderLogoutStart Fires when the user begins the sign-out process. Object with a single field (which indicates provider).

Settings

This topic is for legacy Social Sharing v2 support only. For all new integrations, please see the current Social Sharing documentation.

When the Social Sharing solution is first launched, it applies these settings either by accessing the stored configuration in the application or from embedded code on the client page.

Using the API, it is possible to change the settings on a page-by-page basis, customizing the solution to meet your needs.

Service Level Required Field Value Description
embed true, false When set to true, the UI appears embedded on the client web page. If false, the UI appears as modal (appearing in a pop-up). When embedded, the UI renders inside the element with an ID of janrainEngageShare.
previewMode 03 The previewMode affects the preview shown in the Dashboard when you design the UI.
0 − Turns preview off.
1 − General preview mode (disable sign-in, auto-reveal UI).
2 − Mode for configuring providers.
3 − Mode for configuring email providers.
providers A comma-separated list of identity providers. Used to define the providers used by Social Sharing.
providersEmail A comma-separated list of identity providers. Defines the providers that are available in the Email tab, which shares the activity by email instead of the social network.
modes broadcast or contact Dictates the ways in which Social Sharing can share. Choosing broadcast posts the activity to your own wall or stream. Choosing contact shares the activity with specified contacts through the provider. The provider sends direct messages in whatever manner the provider chooses.
If contact, both the userId and userIdentifier must be provided. See the example at the end of the topic.
Note: The mode cannot be set for the Email tab. It is permanently set to contact.
setState  Widget styles Allows the administrator to apply changes to settings in bulk.
getState none or Parameter Returns data showing the current settings of the UI. Returns all values (styles, automatic settings, settings) as an object. If a parameter is defined, getState returns the object only for that parameter.
resetState true, false Resets the settings to a default state.
translate JSON object matching text keys to new text. Overwrites the default text in the UI. The value is a JSON object that matches text keys with new default text. Keys not present in the object retain the original text values.
Pro Enterprise custom true, false When set to true, custom bypasses all other regular Settings fields and makes Login, Send, and LoginAndSend available. This is used to launch Social Sharing while bypassing rendering of the UI. Developers who design the appearance of the UI in code instead of using the Dashboard use custom to allow this customized implementation to share content.
Pro Enterprise shortenUrl true, false Overrides the default set in the Janrain application. When set to true, shared URLs are shortened using the Janrain URL-shortening service. If false, shared URLs are not modified.

Sharing To a Facebook Fan Page

Social Sharing can be configured to share to a destination fan page instead of to the wall of the user sharing the content. To do this, you need the Object ID of the fan page (as defined by Facebook).

Field Value Description
objectId Numerical object ID code The object ID code assigned to the Facebook fan page.

Contact Example

The following code is an example of a contact share using LinkedIn.

Note: LinkedIn uses the same value for userId and userIdentifier, but you must still pass both.

{
  "provider":"linkedin",
  "mode":"contact",
  "contacts":[
    {
      "userIdentifier":"http://www.linkedin.com/profile?viewProfile=S_example_7",
      "userId":"http://www.linkedin.com/profile?viewProfile=S_example_7"
    }
  ],
  "title":"Janrain is so very very very awesome!",
  "message":"This example uses both userId and userIdentifier and it works!"
}

Functions

Note: This topic is for legacy Social Sharing v2 support only. For all new integrations, please see the current Social Sharing documentation. These functions specify content for the share activity and the styling and state of the Social Sharing solution.

Content

The Content API calls are used to add additional media (such as images and text) to the activity being shared. For example, you can use the Content API calls to enable a user to share a URL along with a blog post or an image with a video. Such elements will appear along with the shared activity in the social network chosen by the user.

Note: Not all options are available for every provider.

Supported by Field Value Description
All Providers setMessage text Adds preset text to the text box used to provide messages with the activity being shared.
Facebook Google Google+ LinkedIn (share and direct share) Mixi (share) Yahoo! setTitle text The title given to the shared content.
Facebook LinkedIn (share) setUrl URL The URL associated with the content being shared.
Facebook LinkedIn (share) setImage URL pointing to image An image associated with the content being shared.
Facebook setDescription text The description of the shared content. This appears in the preview of the shared object and describes what is being shared. Not to be confused with user-generated content, which appears as the status message.
Facebook setMedia URL A media (video or audio) object associated with the content being shared.
Facebook setActionLink URL Link that appears below the user-generated message and content fields. In the case of Facebook, this link appears next to the Like and Comment links. The format is JSON with name and link (both properties are required). {"name":"foo", "link":"http://bar.com"}

Style

Pro Enterprise

The Style settings affect the appearance of the Social Sharing UI. These settings take effect when Social Sharing is launched.

Field Value Description
setMobile true, false When true, changes the style to one optimized for mobile browsers.
setOrientation landscape or portrait Changes the orientation of the UI to either landscape or portrait. Works when mobile is set to on or off.
Note: This is called automatically when screen orientation changes on supported devices.
setModalBackgroundColor Hex color value Sets the background color of the modal border using the webcolor hexadecimal value. The default color is #000000 (black).
setModalOpacity Between 0 and 1 (in tenths) Defines the border opacity of a modal UI. 0 is completely clear, and 1 is completely solid. Use a value expressed in tenths (for example, .04). Default value is .05.
setModalBorderRadius 1-20 Sets the rounding angle of the border of a modal UI. 1 represents square corners, and 20 represents the greatest rounding. Default value is 5.
setModalWidth 1-20 Sets the width of the border on a scale of 1-20 pixels. Default value is 5.
setBodyBackgroundColor Hex color value Determines the background color using the webcolor hexadecimal value. This only affects email unless the bodyBackgroundColorOverride option is set to true. The default color is #009DDC.
setBodyBackgroundColorOverride true, false If true, the bodyBackgroundColor is used regardless of provider. If false, bodyBackgroundColor only affects the email tab.
setBodyColor Hex color value Sets the color of the text (in the body, not user-generated content in text boxes) using the webcolor hexadecimal value. The default color is #333333.
setBodyContentBackgroundColor Hex color value Sets the background color of the internal whitespace using the webcolor hexadecimal value. The default color is #ffffff.
setBodyFontFamily Font name Sets the font. Default is Helvetica.
setBodyTabBackgroundColor Hex color value Sets the background color of the navigation menu on the left of the UI using the webcolor hexadecimal value. The default color is #f8f8f8.
setBodyTabColor Hex color value Sets the color of the text in the navigation menu on the left of the UI using the webcolor hexadecimal value. The default color is #000000.
setElementBackgroundColor Hex color value Sets the background color of the input text boxes of the UI using the webcolor hexadecimal value. The default color is #f6f6f6.
setElementBorderColor Hex color value Sets the color of the border of the input text boxes of the UI using the webcolor hexadecimal value. The default color is #cccccc.
setElementBorderRadius 1-10 Sets the rounding angle of the text box borders of the UI. 1 represents square corners, and 20 represents the greatest rounding. Default value is 3.
setElementButtonBorderRadius 1-10 Sets the rounding angle of the buttons of the UI. 1 represents square corners, and 20 represents the greatest rounding. Default value is 6.
setElementButtonBoxShadow 0-3 Sets a drop shadow on buttons. A value of 0 removes the drop shadow, and 3 is the greatest amount of drop shadow on the button. Default value is 3.
setElementColor Hex color value Sets the color of the element using the webcolor hexadecimal value. The default color is #333333.
setElementHoverBackgroundColor Hex color value Sets the background color of the element hover using the webcolor hexadecimal value. The default color is #eeeeee.
setElementLinkColor Hex color value Sets the hyperlink color using the webcolor hexadecimal value. The default color is #009DDC.
setAttributionDisplay true, false If true, displays the “Social Sharing by Janrain” attribution message. If false, the attribution message is hidden.

Widget

Functions in the Widget category interact with the solution as a whole and can be used to show, hide, or sign a user into Janrain.

Service Level Required Field Value Description
show None Displays the UI.
hide None Hides the UI.
reset None Resets all sharing solutions on the page.
showMode broadcast or contact Shows the desired mode (broadcast or contact) for the current provider.
Note: showMode works only if that mode is actually supported by the identity provider. Also, you must have Pro- or Enterprise-level service to use the contact mode.
showProvider string Brings the specified provider tab to the front. Valid values include providers such as “facebook,” as well as “email” for the email tab.
createBlankProvider name and position Creates an additional provider button that hosts a client’s own Social Sharing JavaScript. See the Custom Provider section later in this topic for further information.
Pro Enterprise login A comma-separated list of identity providers. Initiates a sign-in to Janrain with the specified providers. The valid values for login are:
  • “email”
  • “facebook”
  • “linkedin”
  • “myspace”
  • “twitter”
  • “yahoo”

Note: This is available only when the custom setting is set to true.
Pro Enterprise send text Sends data to Janrain to post. The data must be an object that contains all necessary fields. No validation is performed on this object (other than checking that there was a login event for the provider).
Note: This is available only when the custom setting is set to true.
Pro Enterprise loginAndSend text Similar to send, but automatically spawns the login window (avoiding the need to add the onShareLoginComplete event listener).
Note: This is available only when the custom setting is set to true.
Pro Enterprise shortenUrl true, false Overrides the default set in the Janrain application. When set to true, shared URLs are shortened using the Janrain URL-shortening service. If false, shared URLs are not modified.

Custom Provider

Some sites have their own sharing functionality. For adding a custom provider button to the Social Sharing UI, the createBlankProvider function is used. This command has no sharing capabilities itself; it only creates a spot in Social Sharing where your sharing code can be added.

createBlankProvider creates placeholder elements into which JavaScript for the sharing functionality is added. It requires two parameters:

  • name — Defines the provider name for the custom button.
  • position — A number that specifies where the button appears in the list of buttons by defining how many buttons appear above the new button.

This example creates a new provider named “providerName” and places it third on the button list:

janrain.engage.share.createBlankProvider("providerName", 2)

Note: The custom provider functionality is not available when the custom setting is set to true.

Once executed, createBlankProvider returns an object with two DOM elements: tab and page.

Multiple custom providers may be added (depending on your needs).

Localization

Note: This topic is for legacy Social Sharing v2 support only. For all new integrations, please see the current Social Sharing documentation.

You can set the language for the Social Sharing UI interface to any of the following language codes.

Language Codes

  • en − English
  • fr − French
  • de − German
  • it − Italian
  • ja − Japanese
  • ko − Korean
  • pt − Portuguese
  • ru − Russian
  • es − Spanish

Example

This setting displays your social sharing in German:

janrain.settings.language = 'de';

Examples

Sharing with Default Settings

Note: This topic is for legacy Social Sharing v2 support only. For all new integrations, please see the current Social Sharing documentation.

Share Button

The Code

This is the UI with customizations loaded from the Janrain server. The following is the minimum code you need to get the functionality up and running on your site.

Note that there are optional message, title, url, and description settings present. These are neither required for page load nor provided by the server. If these settings are to be taken advantage of, they must be present in your custom code or set via the JavaScript API.

<button id="janrainEngageShare">Share</button>
(function() {
  if (typeof window.janrain !== 'object') window.janrain = {};
  if (typeof window.janrain.settings !== 'object') window.janrain.settings = {};
  if (typeof window.janrain.settings.share !== 'object') window.janrain.settings.share = {};
  if (typeof window.janrain.settings.packages !== 'object') janrain.settings.packages = [];
  janrain.settings.packages.push('share');

  /* _______________ can edit below this line _______________ */

  janrain.settings.share.message = "Janrain is really amazing.";
  janrain.settings.share.title = "Janrain is awesome!";
  janrain.settings.share.url = "http://janrain.com/";
  janrain.settings.share.description = "Janrain is more awesome than ever before.";

  /* _______________ can edit above this line _______________ */

  function isReady() { janrain.ready = true; };
  if (document.addEventListener) {
    document.addEventListener("DOMContentLoaded", isReady, false);
  } else {
    window.attachEvent('onload', isReady);
  }

  var e = document.createElement('script');
  e.type = 'text/javascript';
  e.id = 'janrainWidgets';
  e.src = 'https://widget-cdn.rpxnow.com/load/widget-examples-pro';

  var s = document.getElementsByTagName('script')[0];
  s.parentNode.insertBefore(e, s);
})();

Embedded Mode

Note: This topic is for legacy Social Sharing v2 support only. For all new integrations, please see the current Social Sharing documentation.

You can embed sharing on a page instead of having it appear in a modal. To do this, set janrain.settings.share.embed to true.

Overwriting Server Settings

Note: This topic is for legacy Social Sharing v2 support only. For all new integrations, please see the current Social Sharing documentation.

Instead of loading the provider list that was configured through the Dashboard, you may want to load a custom list of providers (in this case, only Facebook). Example:

janrain.settings.share.providers = ['facebook'];

Custom User Interface

Note: This topic is for legacy Social Sharing v2 support only. For all new integrations, please see the current Social Sharing documentation.

If you don’t want to use the default share interface, you can write your own and use the JavaScript API to share. By changing the custom setting to true, the UI will not render and instead expose three new functions for use within a custom GUI: login, send, and loginAndSend.

By combining these functions with the Janrain JavaScript event system, Social Sharing can take on limitless forms. The following code is a very simple example of how to set up buttons that will automatically share a predefined message.

<button id="facebookShare">Post on your Wall</button>
janrain.settings.share.custom = true;

var janrainShareOnload = function() {
  var facebookShare = document.getElementById("facebookShare");
  // Let's use an onclick event for the button
  facebookShare.onclick = function() {
    // The "loginAndSend" function is available when "custom" is set to true
    janrain.engage.share.loginAndSend({
      // This needs to be an object with the relevant
      // data to be posted.
      "provider":"facebook",
      // We want to broadcast this to our friends, not
      // send to individuals specifically
      "mode":"broadcast",
      // We can leave this blank because we are broadcasting
      "contacts":[],
      // This URL will be shortened by Janrain to provide
      // extensive analytic capabilities
      "url":"http://janrain.com",
      "title":"Janrain is awesome!",
      "description":"Janrain is awesome and then some",
      "message":"I love Janrain! Check it out everyone!",
      // Any of these settings will be ignored if the
      // provider does not support them. Fortunately
      // Facebook supports a lot
      "image":"http://janrain.com/thumbnail.png",
      "media":"http://janrain.com/video.swf",
      "actionLink":{
        "name":"Login!",
        "link":"http://janrain.com"
      }
    });
  };
};

Multiple Widgets

Note: This topic is for legacy Social Sharing v2 support only. For all new integrations, please see the current Social Sharing documentation.

Often, a page needs to contain multiple social sharing links. In such cases, the usual janrainEngageShare ID will not work, so we suggest that you use the Social Sharing JavaScript API to launch the UI from different elements and/or events.

<a href="#">Share on Facebook</a>
<a href="#">Share on Twitter</a>
<script>
var janrainShareOnload = function() {
  var anchors = document.getElementsByTagName("a");

  // Facebook link
  anchors[0].onclick = function() {
    janrain.engage.share.reset();
    janrain.engage.share.setUrl('http://facebook.com/');
    janrain.engage.share.showProvider('facebook');
    janrain.engage.share.show();
  };

  // LinkedIn link
  anchors[1].onclick = function() {
    janrain.engage.share.reset();
    janrain.engage.share.setUrl('http://twitter.com/');
    janrain.engage.share.showProvider('twitter');
    janrain.engage.share.show();
  };
}
</script>