Widget

Items in the Widget category interact with the widget as a whole, and can be used to show, hide, or sign a user into Engage, and more.

Usage: janrain.engage.share

Field Value Description
show None This displays the widget.
hide None This hides the widget.
reset None This resets all sharing widgets on the page.
showMode “broadcast” or “contact” This shows the desired mode (“broadcast”, “contact”) for the current provider. Note: showMode only works if that mode is actually supported by the Identity Provider.
showProvider String This field brings the specified provider tab to the forefront. Valid values include providers, such as facebook, as well as email for the email tab.
createBlankProvider name and position This creates an additional provider button which hosts a client’s own social sharing javascript. See the Custom Provider section below for further information.

These features require service level:   

Field Value Description
login List of comma separated Identity Providers This initiates a sign-in to Engage with the specified providers. The valid values for login are: yahoo, facebook, myspace, twitter, linkedin, and email.
Note: This is only available when the custom setting is set to “true.”
send Text This sends data to Engage 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 only available when the custom setting is set to “true.”
loginAndSend Text Similar to ‘send’, but automatically spawns the login window, avoiding the need to add the onShareLoginComplete event listener. Note: This is only available when the custom setting is set to “true.”

Custom Provider

Some sites have their own sharing functionality. For sites who would like their own Provider button added to the share widget, the createBlankProvider function is used. This command has no sharing capabilities itself. It only creates a spot in the capture widget 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 — This defines the provider name for the custom button.
  • position – This number determines where the button appears in the list of buttons. It defines how many buttons appear above the new button.

This example would create a new provider named ‘providerName’, and place 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’. See the Settings page for more information.

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

Multiple custom providers may be added, depending on your needs.

Examples

There are three different modes available: broadcast, contact, and email. A broadcast message is posted on the user’s social network page, or wall. A contact message is posted on the social network pages of the user’s specified friends. Email (which isn’t available for Facebook), sends an email using the provider specified.

If you have Basic or Plus level service, your widget will support only broadcast and email modes. You must pay for Pro or Enterprise service to get the contact mode. Your end users can choose which mode in the widget.

You can customize the widget if you want to modify its behavior.

The following examples are for login, send, and loginAndSend only.
Broadcasting Examples
Example for broadcasting a message, contains all possible fields.

{
  "provider":"facebook",
  "mode":"broadcast",
  "contacts":[],
  "title":"Example Movie",
  "url":"http://example.com/",
  "description":"Check it out!",
  "message":"hey i just saw this movie!",
  "image":"http://youtube.com/thumbnail.gif",
  "media":"http://youtube.com/video.swf",
  "actionLink":{
    "name":"Movie",
    "link":"http://shop.example.com/"
  }
}

Example for broadcasting a message with the unnecessary fields removed.

{
  "provider":"twitter",
  "mode":"broadcast",
  "url":"http://example.com/",
  "message":"hey i just saw this movie!"
}

Contact Mode Example
Example for contact mode.

{
  "provider":"twitter",
  "mode":"contact",
  "contacts":[
    {"identifier": "http://twitter.com/account/profile?user_id=blah16628"} //userIdentifier is an example. This is the url to his or her account.
  ],
  "title":"Example Movie",
  "url":"http://example.com/",
  "description":"Check it out!",
  "message":"hey i just saw this movie!",
  "image":"http://youtube.com/thumbnail.gif",
  "media":"http://youtube.com/video.swf",
  "actionLink":{
    "name":"Movie",
    "link":"http://shop.example.com/"
  }
}

Email Example
Example for email. Notice that you need to use userName instead of userIdentifier for email mode.

{
  "provider":"google",
  "mode":"email",
  "contacts":[
    {"userId":"john@example.com", "userName":"john brown"}
  ],
  "title":"Example Movie",
  "url":"http://example.com/",
  "description":"Check it out!",
  "message":"hey i just saw this movie!",
  "image":"http://youtube.com/thumbnail.gif",
  "media":"http://youtube.com/video.swf",
  "actionLink":{
    "name":"Movie",
    "link":"http://shop.example.com/"
  }
}

Keep in mind that using the send function requires that the user already be logged in, through either the login or loginAndSend function.

Help Us Improve!

Give us your feedback