Overview
The Userplane Embed Code is a single JavaScript call placed on each page of your website. It functions as a universal loader that establishes the Userplane platform on a page-to-page basis, which in turn, tracks user presence, handles the launch and management of chat conversations, and serves as a base for deploying rich Internet applications built with the Userplane SDK.
The Embed Code uses your siteId in conjunction with a token that is specific to the user, to establish Userplane services on the page. Here is a simple illustration of how the process works…
A key benefit of Single Sign-On is it’s simplicity – you pass the siteId and a user’s token through embedded code on the page, and Userplane provides the user’s access and identity on-the-fly, based on the data we receive from your web server. Security is engineered into Userplane’s Single Sign-On process, as described below in Securing the Token.
The Userplane Embed Code
The Userplane Embed Code is comprised of two script tags. The first is a call to the userplane.js file on the Userplane CDN, and the second is the up.init function which passes an object, containing key information about your site and a specific user, as it’s sole argument. An example of the Embed Code is just below, but first, here are some key requirements for successfully writing the Embed Code…
Requirements
- A user base with basic profile information
- A unique identifier for each user
- The ability to perform an md5 hash (UTF-8)
- The ability to determine the current time (in milliseconds, also known as epoch
<script type="text/javascript" src="http://cdn.userplane.com/release/sdk/userplane.js"></script>
<script>
up.init({
siteId:"YOUR_SITE_ID",
key: "",
token: "YOUR_TOKEN_IDENTIFIER",
settings: {},
lang: "en-us"
});
</script>
Parameters
| Property | Description | Required |
|---|---|---|
| siteId | The identifier for your particular site. This is the public key Userplane employes to identify what site your users are a part of, as well as to track statistics and analytical data against. | Yes |
| key | Key is a pass through value for our server callbacks. The key parameter is also used as a part of our caching strategy. Providing a value specific the user who is logged in is recommended if you want to ensure that a user on the same browser’s identity within Userplane is cleared out if the log out and back in with another account. | No |
| token | The token parameter provides the identity of the user in a secured fashion. Because its simply a string you generate with a special key it provides portability and ease of management for your implementation. | Yes |
| lang | The language you wish to use for your integration. See Supported Locales | Yes |
| settings | An object used to configure your integration beyond the simple identification elements provided in the rest of the embed code. | Yes |
Embed Settings
Occasionally, you may require that some settings are provided at a global level for the Userplane SDK, and not to a specific application. This is done using the settings property in the Embed Code. See the example below…
<script>
up.init({
siteId:"YOUR_SITE_ID",
key: "",
token: "YOUR_TOKEN_IDENTIFIER",
settings: {
// Add new property:value pairs here to pass in global settings for the SDK
// sampleGlobalSetting1: "Some Value",
// sampleGlobalSetting2: "Etc."
},
lang: "en-us"
});
</script>
| Property | Description |
|---|---|
| cssOverrideURI | Full path to an override CSS file on your website server (see Customization) |
Building the Token
Identify the user
To generate a token, you need to provide user data for the currently logged in user from your webserver, in the form of a string. Here’s an example:
&avatarFull=http://c.api.userplane.com/sandbox/avatar-icon.jpg &avatarIcon=http://c.api.userplane.com/sandbox/avatar-icon.jpg &avatarThumb=http://c.api.userplane.com/sandbox/avatar-icon.jpg &displayName=Winston &email=user@email.com &line1=25 &line2=Male &line3=Santa Monica &line4=CA &ts=1305906667528 &userId=1 &role=default
Please note, this is on multiple lines to make it easier to read, but it should NOT have returns in it when you include the token value in the Embed Code. The example token string above is using static / hard-coded values, but your actual token string should utilize dynamic data values that are specific to the logged in user.
Bear in mind that you only need to identify the user who is currently connected. Whether a user is a sender or receiver in a chat conversation is inconsequential – they are all “currently logged in users” and their individual token is the only requirement to successfully communicate with other users.
If your site regularly uses special characters, you may need to encode your token to prevent the characters from being munged in translation. To do so you will need to Base64 encode the characters in your values.
Securing the Token
Once you’ve created the token string, you will secure it using your private API Key (you can find this in your Dashboard account, under Configure / Details) and MD5 encryption.
Example:
mySsoToken = md5.hash( stringFromAbove & "&apiKey=YOUR API KEY" )
Please note that this is pseudo-code written in JavaScript, and you may need to alter this to suit the programming language used for your site.
Once you have created the encrypted string, append it to the original token you generated:
&avatarFull=http://c.api.userplane.com/sandbox/avatar-icon.jpg &avatarIcon=http://c.api.userplane.com/sandbox/avatar-icon.jpg &avatarThumb=http://c.api.userplane.com/sandbox/avatar-icon.jpg &displayName=Winston &email=user@email.com &line1=25 &line2=Male &line3=Santa Monica &line4=CA &ts=1305906667528 &userId=1 &role= &token=7E5D5F3B7647A325368F7188F5DEA30F
Because your token string is encrypted with your API Key (or Private Key), and Userplane is the only other entity that knows this information, the token you provide is immune to tampering.
Validate your Token
Test your token to make sure it is well-formed, by using the inputs below:
Adding the token to your Embed Code
Once you’ve validated the token, the Embed Code with the user’s token must be placed on every page of your website, once the user has been authenticated. After this is complete, you will be ready to add the Userplane experience of your choice to your site.
What does the embed code look like?
<script type="text/javascript" src="http://cdn.userplane.com/release/sdk/userplane.js"></script>
<script>
up.init({
siteId:"{YOUR_SITE_ID}",
key: "",
token: "{YOUR_TOKEN}",
settings: {},
lang: "en-us"
});
</script>
Note that in the above example of a Userplane Embed the {YOUR_SITE_ID} and {YOUR_TOKEN} are placeholders and would need to be replaced with site specific information, as described above.
Sample Code
We currently only have sample code available in PHP, which you can download below. This code will help you construct the token so you can choose to skip straight to it if you like.