This document will go over the steps in embedding the SLWeb Module using SSO on your web pages. You should have your IT staff or web developer help with embedding the SLWeb Module iframe as there might be different code blocks needed based on how you would like to embed the iframe. The sections covered in this article are:
SocialLadder Web Module Code Block
SSO API
SocialLadder Web Module Code Block
First, determine which web page you would like to host the SLWeb Module on. On that page two things need to happen, one on the server side and one on the client side.
Server Side: You need to make a call to the SocialLadder servers to tell us what the customerID is of the user that's already authenticated with your system. This call needs to be made from your server as it will include your SocialLadder API Key (which cannot be shared on the client). The call will return a deviceUUID which is the token used to load the ambassador dashboard for that given user. This call can be made on page load if the page is being rendered using a server side rendering technology. If the page is single page application or using AJAX calls, you will need to pass the customerID to a new authenticated endpoint on your server that will authenticate the user and pass back the token (deviceUUID).
The following endpoint can be called from the server side to obtain the deviceUUID (it will return a JSON response containing a field called deviceUUID on success)
GET https://socialladder.rkiapps.com/SocialLadderAPI/api/v1/sso/userlogin?apiKey=[API_KEY]&customerId=[CUSTOMER_ID]
Client Side: SocialLadder's rendering code will need to be deployed on the client side to render the dashboard into the correct div after getting the deviceUUID (the token needed by SocialLadder).
The following code block outlines the client side code needed for a single page application, note that the first call being made is to your own servers which should 1) authenticate the user and 2) make the secure call above (see Server Side) to the SocialLadder endpoint to obtain the deviceUUID
<div id="slWebFrame"></div>
<script src="https://socialladder.rkiapps.com/SLWeb/slweb-frame.js"></script>
<script>
var areaGuid = "[AREA_GUID]";
var customerId = "[CUSTOMER_ID]";
fetch(`https://YOURSERVER.COM/GETSOCIALLADDERTOKEN?customerId=${customerId}`)
.then((response) => response.json())
.then((deviceUUID) => {
if (deviceUUID) {
loadSLWebFrame(areaGuid, deviceUUID);
}
else {
document.querySelector('#slWebFrame').innerHTML = '<p style="margin: 40px 0">Error! Please contact customer support at [CUSTOMER_SUPPORT_EMAIL]</p>';
}
})
.catch((error) => {
document.querySelector('#slWebFrame').innerHTML = '<p style="margin: 40px 0">Error! Please contact customer support at [CUSTOMER_SUPPORT_EMAIL]</p>';
});
</script>
Notes about the above code block:
The div tag with id=”slWebFrame” is important in the snippet as the script will look for that id to load slweb iframe inside that div.
The sequence of the div & script should be exactly the same as shown in the snippet.
areaGuid: Will be provided from SocialLadder and is required.
deviceUUID: In order for SSO to work, the deviceUUID will need to be passed down from the server side on your server (after calling SocialLadder's SSO API to obtain the token)
If the deviceUUID is not passed, then it will show the login page and SSO will not work.
SSO API:
Using the SSO API, we can get the Ambassador's deviceUUID, which is needed for this function:
loadSLWebFrame(areaGuid, deviceUUID)
NOTE: THIS MUST BE CALLED FROM THE SERVER SIDE - CALLING THIS FROM THE CLIENT SIDE WILL RESULT IN A SECURITY VULNERABILITY
API_KEY: This is provided by SocialLadder and is Required
CRM_CUSTOMER_ID: This is the Customer ID of the user that is logged into their account on your website.
This ID needs to be assigned to the user in the SocialLadder Portal. There are two ways to do this:
Send Customer ID in the Embedded Web Application. This is an application filled out by a user logged in to your website to become an Ambassador
By manually adding the CRM Customer ID to the Ambassador's profile in the SocialLadder Portal
RETURN: The API will return a string, which is the deviceUUID of Ambassador in the SocialLadder system. NOTE: If the user is not present in the SocialLadder system, then the API will return null.