This document will go over the steps in embedding the SLWeb Module using SSO and auto register user in the SocialLadder system from 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 with the user data to get them to auto register if they are not already registered in the SocialLadder system. We will need basic data of the user for example the userId (unique identifier from your system), first name, last name. etc. 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 check the user in the SocialLadder system using the unique id, the API will return a deviceUUID of the existing user or of the new user after registration. The deviceUUID 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. You will need to pass the user data to a new authenticated endpoint on your server that returns a token (deviceUUID).
The following endpoint called from the server side with user data will always return the deviceUUID for the authenticated user.
POST https://socialladder.rkiapps.com/SocialLadderAPI/api/v1/sso/autoregister?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:
Authenticate/register the user.
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]";
var userData = {[USER DATA FROM YOUR SYSTEM]}
fetch(`https://YOURSERVER.COM/GETSOCIALLADDERTOKEN?customerId=${customerId}`, {
method: 'POST',
body: JSON.stringify(userData)
})
.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 as the script will look for that id to load the 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 by SocialLadder and is required.
deviceUUID: In order for SSO to work, the deviceUUID will need to be passed down from the server side (after calling SocialLadder's SSO API to obtain the token).
If the deviceUUID is not passed, 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
Post Call to the API:
Need to send an object containing user data. It is required to auto register the users if they don’t exist in the SocialLadder system.
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.
User Data payload example in json:
First Name (first_name) (required)
Type: String
Description: This field is mandatory and must contain the user's first name as a string. It cannot be empty or null.
Last Name (last_name) (optional)
Type: String
Description: This field contains the user's last name. It is optional, but if provided, it must be a valid string.
Email Address (email_address) (required)
Type: String (Formatted as Email)
Description: This field is mandatory and must contain the user’s email address in a valid email format (e.g., user@example.com).
Phone Number (phone) (optional)
Type: Object
Description: This is an optional field. If the phone number is provided, it must contain:
phone_number: A numeric string with the user's phone number.
country_code: A string with the country calling code (e.g., +1 for the US).
Custom Data (custom_data) (optional)
Type: Array of Objects (name-value pairs)
Description: This is an optional field that holds an array of objects. This will map the data to the SocialLadder’s custom field feature. Each object contains:
field_name: A string representing the custom data field.
Need to ensure the field name matches with the field names used in the SocialLadder system. Unmatched fields will be skipped and not stored.
field_value: A string containing the associated value.
Tags (tags) (optional)
Type: Array of Strings
Description: This field can hold up to 5 tags. If more than 5 tags are passed, only the first 5 will be accepted.
Promo Code (promo_code) (optional)
Type: String
Description: This optional field holds a string containing the user's promo code.
{
"first_name": "John",
"last_name": "Doe",
"email_address": "johndoe@example.com",
"phone": {
"phone_number": "1234567890",
"country_code": "+1"
},
"custom_data": [
{
"field_name": "SL_CITY",
"field_value": "Lorem City"
},
{
"field_name": "SL_COUNTRY",
"field_value": "Lorem Land"
}
],
"tags": ["newuser", "verified"],
"promo_code": "LOREM2025"
}