Overview
Adding Userplane to your website begins with including an embed code on every page of your site. The embed code consists of a token that is used to identify the local user. For the embed code to work, the token must be generated using public and private keys, in conjunction with some basic information about the user. Generating this token is your first step, and needs to be completed and verified before anything else can function within your Userplane integration. We have sample code available, which the documentation below covers in greater detail.
Step 1: Get your Site ID and API Key
To get started, you will need to login to the Userplane Dashboard and retrieve your SiteID and ApiKey.
Step 2: Generate your token
Your Site ID ( or Public Key ) and API Key ( or Private Key ) are used to identify your site and to secure the information you provide to Userplane.
How do I generate my token?
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.
Step 3: 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.
If you would like more detailed instructions on how the token process works, or detailed information on each property, please see our detailed instructions for further explanation.
Step 4: Validate your Token
Test your token to make sure it is well-formed, by using the inputs below:
Step 5: Add your token and Embed code to every page
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.
Still having issues? Some commonly asked questions are included in the FAQ section below:
How do I know if I am getting connected?
You can enable Debug Mode from the SDK by adding debug=true to the URL for the page you are on. Debug Mode will add a clickable icon, which will display detailed information about the status of your active user and their connection. Additionally, this will provide further information in the browser's native console.
Example:
http://www.yourwebsite.com/?debug=true
If you’ve successfully added the embed code to each page of your website, the next step is to select and integrate a Userplane experience.
Step 6: Select the experience you want to add:
Presence Bar
A chatbar application that allows your users to have a persistent chat experience that is available on every page of your site.
Webchat
An immersive Group Chat experience that allows the users on your side to come together in a multi-room video chat experience.
Webmessenger
An immersive Instant Message experience allowing users a more intimating engaging conversation including audio and video calling features.
Webchat Lite
A light weight single room group chat experience that allows users to engage in a conversation while maintaining a very small visual footprint.