This guide is for your development team. It walks through embedding SocialLadder's community dashboard on your website so that visitors can browse your community without logging in, and authentication only happens when they try to interact — reacting to a message, posting, or sending files. If the visitor is already logged into your site, the community loads fully authenticated with no extra steps for the user.
Your site handles the login experience. SocialLadder handles the community. The two connect through a simple event-driven handshake described below.
For a business-level overview of Open Community (what it is, the customer experience, what's included), see Open Community Integrated.
How the Authentication Flow Works
Before diving into code, here's what happens end-to-end when a visitor interacts with your community:
Step | What Happens | Who Handles It |
User already logged in |
| Your server → SocialLadder API → widget |
Widget loads (guest) | Community visible in read-only mode | SocialLadder widget |
User interacts | sl-auth-required event fires | SocialLadder widget |
Login/sign-up | User authenticates through your site | Your site |
autoRegister | Profile created, deviceUUID returned | Your server → SocialLadder API |
authenticate() | Widget transitions to full interactive mode | Your site → SocialLadder widget |
The key security principle: your SocialLadder API key never touches the browser. The browser talks to your server, your server talks to SocialLadder's API with the key, and only the deviceUUID token flows back to the client.
Prerequisites
Public Discovery must be enabled in your SocialLadder Portal settings.
You'll need your areaGuid and apiKey from your SocialLadder Portal (found in the Dev Dashboard under your area settings).
Your website must have an existing login/sign-up flow that you can trigger programmatically (modal, redirect, OAuth, etc.).
Step 1 — Add the container and load the widget
Place a container div on whatever page will host your community:
<div id="slWebFrame"></div>
<script src="https://socialladder.rkiapps.com/SLWeb/slweb-frame.js"></script>
⚠️ IMPORTANT: Place the embed snippet in the page body, not the <head>. Avoid synchronous <script> tags before it in the DOM — anything loading before it delays the widget.
Before loading the widget, your page needs to check whether the visitor is already logged into your website. This determines which path to take:
If the user is already logged in
If your site knows the user is authenticated, call your server to get their deviceUUID via the autoRegister endpoint (described in detail in Step 3), then pass it directly to loadSLWebFrame. This skips the public preview mode entirely — the user gets a fully authenticated community immediately.
// User is already logged in on your site
fetch("https://YOURSERVER.COM/api/socialladder-token", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
userId: user.id,
firstName: user.firstName,
lastName: user.lastName,
email: user.email
})
})
.then(function(res) { return res.json(); })
.then(function(data) {
if (data.deviceUUID) {
// Load the widget already authenticated
loadSLWebFrame(areaGuid, data.deviceUUID);
} else {
// Fallback: load in public preview mode
loadSLWebFrame(areaGuid, "");
}
})
.catch(function(error) {
// Fallback: load in public preview mode
loadSLWebFrame(areaGuid, "");
});
In this path, you don't need to listen for the sl-auth-required event — the user is already authenticated and can interact with the community right away. Steps 2 through 4 are skipped entirely.
If the user is not logged in
Pass an empty string as the second parameter. This loads the widget in public preview mode — the visitor can browse community content in read-only mode.
// User is not logged in — load in public preview mode
var areaGuid = "YOUR_AREA_GUID";
loadSLWebFrame(areaGuid, "");
In this path, when the visitor tries to interact with content, the widget will fire the sl-auth-required event. Continue to Step 2 to handle that.
Step 2 — Listen for the authentication event
When a visitor tries to do something that requires authentication (react to a message or post content), the widget fires a custom DOM event called sl-auth-required on the #slWebFrame element.
Listen for this event and trigger your own login flow:
document.getElementById("slWebFrame").addEventListener("sl-auth-required", function(event) {
console.log("Auth required:", event.detail);
// This is where YOUR site takes over.
// Option A: Show your login/signup modal
// Option B: Redirect to your login page
// Option C: Trigger your OAuth flow
//
// After successful login, proceed to Step 3.
});
SocialLadder does not handle the login UI. Your brand controls the entire login/sign-up experience, ensuring it's consistent with the rest of your site.
Step 3 — Register the user and get a deviceUUID
After the user logs in through your flow, call SocialLadder's autoRegister endpoint to create or retrieve their community profile and get a deviceUUID. There are two ways to do this depending on your infrastructure.
The autoRegister endpoint is idempotent. If a user with the given externalUserId already exists, it returns their existing deviceUUID rather than creating a duplicate.
Option A — Server-side call (recommended)
This option requires a server. Your SocialLadder API key must never appear in client-side JavaScript — exposing it in the browser is a security vulnerability.
Send the user's info from your browser to your own backend, then have your server make the autoRegister call with your API key.
Your server-side code
POST https://socialladder.rkiapps.com/SocialLadderAPI/api/v1/sso/autoregister
Content-Type: application/json
{
"apiKey": "YOUR_API_KEY",
"externalUserId": "user-123",
"customerData": {
"first_name": "Jane",
"last_name": "Smith",
"email_address": "jane@example.com",
"phone": {
"phone_number": "1234567890",
"country_code": "1",
}
}
}
Your client-side code
From the browser, call your own server — not the SocialLadder API directly:
// Call YOUR server to get the SocialLadder token
fetch("https://YOURSERVER.COM/api/socialladder-token", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
userId: user.id,
firstName: user.firstName,
lastName: user.lastName,
email: user.email
})
})
.then(function(res) { return res.json(); })
.then(function(data) {
if (data.deviceUUID) {
// Proceed to Step 4 — complete authentication
window.SLCommunityWidget.authenticate(areaGuid, data.deviceUUID);
} else {
// Handle error — show a message to the user
document.querySelector('#slWebFrame').innerHTML =
'<p style="margin:40px 0">Something went wrong. Please contact support.</p>';
}
})
.catch(function(error) {
document.querySelector('#slWebFrame').innerHTML =
'<p style="margin:40px 0">Something went wrong. Please contact support.</p>';
});
Option B — Client-side call (for Shopify and front-end-only environments)
If you don't have access to a server (for example, if you're installing the widget on a Shopify storefront), you can call autoRegister directly from the browser. Instead of an API key, this call uses your areaGuid to identify the community. No API key is sent or exposed.
fetch("https://socialladder.rkiapps.com/SocialLadderAPI/api/v1/sso/autoregister?areaGuid=[YOUR_AREA_GUID]&externalUserId=[USER_ID_IN_YOUR_SITE]", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
first_name: user.firstName,
last_name: user.lastName,
email_address: user.email
})
})
.then(function(res) { return res.json(); })
.then(function(data) {
if (data) {
window.SLCommunityWidget.authenticate(areaGuid, data);
} else {
document.querySelector('#slWebFrame').innerHTML =
'<p style="margin:40px 0">Something went wrong. Please contact support.</p>';
}
})
.catch(function(error) {
document.querySelector('#slWebFrame').innerHTML =
'<p style="margin:40px 0">Something went wrong. Please contact support.</p>';
});
Parameters:
apiKey — Your SocialLadder API key (provided by SocialLadder). Keep this on your server only.
areaGuid — The GUID for the community area you're embedding (provided by SocialLadder).
externalUserId — Your system's unique user identifier. This is how SocialLadder maps your users to community members.
customerData — Object with user profile fields. At minimum, send first_name, last_name, and email_address.
Regardless of which option you use, once you have the deviceUUID, proceed to Step 4 to complete authentication in the widget.
Step 4 — Complete authentication in the widget
Once your front-end receives the deviceUUID from your server, pass it to the widget:
// After successful autoRegister, complete the auth:
window.SLCommunityWidget.authenticate(areaGuid, deviceUUID);
The widget transitions from public preview mode to a fully authenticated session. The user can now join challenges, post content, earn rewards, and interact with the entire community.
Troubleshooting
The widget isn't loading
Verify the script src URL is correct and accessible. Check the browser console for network errors. Ensure the <div id="slWebFrame"> exists in the DOM before calling loadSLWebFrame() — the div must come first in the HTML.
autoRegister returns an error or null
Double-check your apiKey and areaGuid values. Ensure externalUserId is a non-empty string. If the API returns null, the user could not be registered — check that all required customerData fields are present.
User is authenticated but the widget doesn't update
Confirm you're calling SLCommunityWidget.authenticate() with the correct areaGuid and the deviceUUID returned from autoRegister — not your own user ID or session token.
The widget loads slowly
The widget typically loads in under 2 seconds. If you're seeing 5 to 10 seconds, the most common cause is other scripts on the page competing for CPU and network resources.
Things to check:
Synchronous <script> tags appearing before the SocialLadder embed in the DOM will delay it. Move them after, or add the defer attribute.
Open DevTools (F12) > Network tab, reload with "Disable cache" checked, and filter by "JS". If you see 50+ scripts loading on the page, that's the likely culprit.
Live chat widgets (like Intercom or Drift) are frequent offenders — they can load 15 to 25 scripts on initialization. Try lazy-loading them or excluding them from your community page.
If you're on Shopify, your theme likely loads product-related scripts (sliders, quick-add, predictive search) that are unused on the community page. A dedicated minimal page template can cut load time significantly.
For a business-level overview, see Open Community Integrated. For the standard SSO embed (without public discovery), see How to embed SLWeb Module: Non-Shopify SSO. For implementation support, contact your SocialLadder onboarding specialist.