Social Sharing Global Settings

When the Social Sharing solution is initialized, it reads some or all of its settings from the janrain.settings object that you will include on each page where sharing is enabled. These settings are included in the JavaScript that is generated when you configure Social Sharing in the Janrain Dashboard.

You may modify these settings per instance of the sharing widget in order to customize the solution where needed. See the Instance Settings section for details on how to override these settings.

Example:

<script type="text/javascript">
	janrain.settings.social = {
	   orientation: "vertical",
	   providers: [
	    "facebook",
	    "twitter",
	    "email-googleplus",
	    "email"
	   ]
	};
	janrain.settings.appUrl = "https://my-app.rpxnow.com";
	janrain.settings.language = "es-ES";
</script>

appUrl

string Required

The domain for this application. You can find this value in the Settings section on your application home page in the Janrain Dashboard.

Note: If you are also using Social Login, janrain.settings.appUrl may already be defined on the page. If so, do not include it in the sharing configuration script.

language

Default: en-US string

The language to use for the Social Sharing UI. Note that for languages other than English, the number of characters in a share message is determined by the URL encoding for those characters.

Available language values:

Code Language
ar Arabic
bg-BG Bulgarian
cs-CZ Czech
da-DK Danish
de-DE German
el-GR Greek (Modern)
en-US English
es-ES Spanish (Spain)
es-LA Spanish (Latin America)
fi-FI Finnish
fr-FR French
he-IL Hebrew
hr-HR Croatian
hu-HU Hungarian
id-ID Indonesian
it-IT Italian
ja-JP Japanese
ko-KR Korean
lt-LT Lithuanian
my Burmese
nb-NO Norwegian
nl-BE Dutch (Belgium)
nl-NL Dutch (Netherlands)
pl-PL Polish
pt-BR Portuguese (Brazil)
pt-PT Portuguese (Portugal)
ro-RO Romanian
ru-RU Russian
sk-SK Slovak
sl-SI Slovenian
sr Serbian
sv-SE Swedish
th-TH Thai
tr-TR Turkish
uk-UA Ukranian
vi-VN Vietnamese
zh-CHS Chinese (Simplified)
zh-CHT Chinese (Traditional)

social.cssUrl

string

The full URL path to a CSS resource to be used for styling the sharing widget.

social.formFactor

Default: bar string Overridden by: form-factor

Available values are bar or drawer. Determines whether the widget’s provider buttons are displayed immediately or if they are hidden until a user clicks the Share button. This value may also be set on the social share HTML element (see the Instance Settings for details).

social.orientation

Default: horizontal string Overridden by: orientation

Available values are horizontal or vertical. Determines whether the widget’s provider buttons are displayed as a row or column. Recommend using vertical when right-aligning the sharing widget, and horizontal when bottom-aligning the sharing widget. This value may also be set on the social share HTML element (see the Instance Settings for details).

social.providers

array Overridden by: providers

List of comma-separated identity providers that may be used for sharing. See the Social Sharing Overview for more information on provider configuration. This value may also be set on the social share HTML element (see the Instance Settings for details).

Available provider values:

  • email-google (only for use with the Google OpenID provider)
  • email-googleplus (for use with the current Google+ provider)
  • email-mailto
  • email-yahoo
  • facebook
  • linkedin
  • mixi
  • native-facebook
  • native-googleplus
  • native-linkedin
  • native-mixi
  • native-odnoklassniki
  • native-pinterest
  • native-reddit
  • native-sinaweibo
  • native-tumblr
  • native-twitter
  • native-vk
  • native-xing
  • qq
  • tencentweibo
  • twitter
  • xing

social.providerFormats

object

A nested JSON object with key/value pairs mapping a custom share messaging format to a named provider. The initial key is that of the provider (for example, facebook). The value is an object with nested key of a variable and a value of the custom message data.

Attributes that may be used as nested key variables are:

  • description
  • image
  • media
  • message
  • title
  • url

Example:

<script type="text/javascript">
	janrain.settings.social = {
		providerFormats: {
	     twitter: {
	       message: "{{ message }} - {{ url }}"
	     },
	     mixi: {
	       message: "{{ message }} - {{ url }}"
	     },
	    }
	}
</script>

social.providerIcons

object

A JSON object with key/value pairs mapping a custom icon to a named provider. The key is that of the provider (for example, facebook). The value is the full URL to the image to use in place of Janrain’s default.

<script type="text/javascript">
	janrain.settings.social.providerIcons = {
		"facebook": "https://example.com/facebook.png",
		"native-facebook": "https://example.com/facebook2.png"
	};
</script>

social.shareCountMin

Default: -1 integer Overridden by: share-count-min

Minimum number of shares before the ShareCount element should be displayed. (Note: The share count does not include those performed via native share methods.) The default value -1 will cause the ShareCount element to be immediately displayed, regardless of sharing activity. This value may also be set on the social share HTML element (see the Instance Settings for details).

social.shareCountMode

Default: none string Overridden by: share-count-min

Available values are none or combined. The share count will not be displayed by default. If set to combined, the share count combines Janrain shares with total provider shares. This value may also be set on the social share HTML element (see the Instance Settings for details).

Social Sharing Instance Settings

These settings define the activity, description, and type of sharing to be enabled. They may be defined on any HTML element with the class janrainSocialPlaceholder as data-janrain-* attributes. These settings will override the corresponding settings defined globally in the JavaScript object janrain.settings.social.

Example:

<div
  class="janrainSocialPlaceholder"
  data-janrain-url="http://www.google.com/"
  data-janrain-title="Share this!"
  data-janrain-description="This is a cool thing"
  data-janrain-image="http://www.coolmath.com/fractals/images/fractal11.gif"
  data-janrain-message="Hey come look at this amazing thing!"
></div>

description

string

The description that appears in the preview of the shared object. Not editable by the user.

form-factor

Default: bar string Overrides: formFactor

See the Global Settings section for details. This value will override anything set for janrain.settings.social.formFactor.

image

string

The full URL path to an image associated with the content being shared.

message

string

The preset text populated in the message that users may edit when sharing content.

mode

Default: broadcast string

Available values are broadcast or contact. Determines whether the share activity will be posted to the user’s own wall or stream or to specified contacts through the provider. Providers available in contact mode are:

  • LinkedIn
  • Mixi
  • Twitter
  • Xing
  • all email providers

orientation

Default: horizontal string Overrides: orientation

See the Global Settings section for details. This value will override anything set for janrain.settings.social.orientation.

providers

array Overrides: providers

See the Global Settings section for details. This value will override anything set for janrain.settings.social.providers.

share-count-min

Default: -1 integer Overrides: shareCountMin

See the Global Settings section for details. This value will override anything set for janrain.settings.social.shareCountMin.

share-count-mode

Default: none string Overrides: shareCountMode

See the Global Settings section for details. This value will override anything set for janrain.settings.social.shareCountMode.

shorten-url

Default: true boolean

Available values are true or false. By default, shared URLs will be shortened with the rpx.me domain or a custom URL shortening service if configured in the Janrain dashboard. See Configure URL Shortening for more information.

subject

string

The subject line to be used for an email share. If not specified, title will be used as the subject line.

title

string

The title given to the shared content.

url

string

The URL associated with the content being shared.

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">
    function janrainSocialOnLoad() {
        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">
    function janrainSocialOnLoad() {
        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">
    function janrainSocialOnLoad() {
        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">
    function janrainSocialOnLoad() {
        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">
    function janrainSocialOnLoad() {
        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

Fired when a user authorizes a provider for sharing.

auth_fail

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

provider_select

Fired when a user clicks on a provider icon.

share_done

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

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

share_start

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"
}

Social Sharing Functions

The Social Sharing solution supports client-side functions that allow you to dynamically load the sharing widget to a page after it has been loaded. Use the janrain.social method after the janrainSocialOnLoad function has been called to attach the share tool to an HTML element.

.addWidgetTo(element, options)

This method will accept an element to options mapping. element is required and refers to the HTML element to which the sharing widget should be attached. options is an optional JavaScript object containing settings that will override anything currently set on the element in the data-janrain-\* attributes. See the Instance Settings for a list of valid keys that may be used. Do not include the data-janrain-\* prefix. Use camelCase.

Example using JavaScript to create a new element, with options:

<script type="text/javascript">
    var e = document.createElement("div");
    document.body.appendChild(e);
    janrain.social.addWidgetTo(e, { url: "http://twitter.com", formFactor: "drawer" });
</script>

Example using JQuery to create a new element, without options:

<script type="text/javascript">
    var placeholder = $("<div></div>")
        .attr("data-janrain-url", "http://bing.com")
        .appendTo(document.body);
    janrain.social.addWidgetTo(placeholder[0])
</script>

Example using JQuery to add the share widget to an existing element (the last janrainSocialPlacholder element on the page):

<script type="text/javascript">
    janrain.social.addWidgetTo($(".janrainSocialPlaceholder").get(-1), { url: "http://bing.com" })
</script>
Scroll ↓