Users and identity
Support anonymous visitors and logged-in customers with stable IDs across recommendations, events, and analytics. Merge anonymous session history when users authenticate.
API base URLs
| Engine API base URL | Admin UI |
|---|---|
| https://api.proxy.vpn.recomnext.com/api | https://admin.proxy.vpn.recomnext.com |
Use the engine base URL as baseUrl in widgets and SDKs.
Anonymous vs known users
| Setting | Type | Default | Description |
|---|---|---|---|
| Anonymous (default) | session | — | Browser SDK and widgets use sess_… in localStorage (recomnext_session_id), shared across tabs. |
| Host-owned anonymous | session | — | You supply sess_… as userId (e.g. sess_{device_uid}). Use getHostAnonymousUserId on RecomnextIdentity or pass the same id on widgets. |
| Known | userId | — | Your stable account ID from auth system. |
| Recommendations | both | — | user-to-item uses history for known users; session-scoped for anonymous. |
RecomnextIdentity coordinator (recommended)
For storefronts with widgets and the browser SDK, configure RecomnextIdentity once. On login or logout you only call setAuthenticatedUserId — one merge per login (engine ledger + client dedupe), anonymous session rotation on logout, and mounted carousels refetch without passing userId on every instance.
import { RecomnextIdentity } from '@recomnext/browser';
RecomnextIdentity.configure({
baseUrl: 'https://api.proxy.vpn.recomnext.com/api',
tenantId: 'aurora-games',
publicToken: 'rnx_pub_…',
getHostAnonymousUserId: () => 'sess_' + deviceUid, // optional
onHostLogout: () => rotateDeviceUid(), // required with host-owned anon
});
await RecomnextIdentity.setAuthenticatedUserId('customer-42');
await RecomnextIdentity.setAuthenticatedUserId(null);Login commits authenticated state only after POST /identity/merge succeeds (with SDK-style retries). Other tabs on the same origin receive auth via recomnext_authenticated_user_id in localStorage but still need your app to establish auth on each tab for non-RecomNext UI. Follower tabs apply auth from that key without a second merge (the login tab already merged).
Account switch (user A → user B without an explicit logout) runs an internal logout+login: rotate anonymous storage, then merge onto B where the engine allows. See Widgets — user identity for HTML recomnext:identity events and RecomnextIdentityProvider.
Identity merge
On login, copy anonymous session events to the authenticated user. Safe to retry on transient errors; the engine dedupes via a merge ledger. Merge must target the same id used for anonymous ingest (default localStorage sess_… or your host-owned sess_…).
POST https://api.proxy.vpn.recomnext.com/api/identity/merge
Content-Type: application/json
X-Tenant-Id: aurora-games
{
"userId": "customer-42",
"sessionIds": ["sess_abc123"]
}Response
{ "merged": 12, "alreadyMerged": false }Browser (manual)
recomnext.setUserId('customer-42');
await recomnext.mergeIdentity('customer-42');User provisioning
Tenant userProvisioningModes controls automatic catalog user creation:
| Setting | Type | Default | Description |
|---|---|---|---|
| on_identity_merge | mode | — | Create minimal user row after merge. |
| on_first_known_interaction | mode | — | Create user on first interaction with userId. |
Rich profiles from IDP
Bulk sync attributes with POST /ingestion/users when you need segments beyond auto-provisioned rows.
POST https://api.proxy.vpn.recomnext.com/api/ingestion/users
{
"users": [
{ "externalId": "customer-42", "attributes": { "country": "US", "tier": "premium" } }
]
}First interaction without scenarioSlug
With on_first_known_interaction provisioning, a minimal user row is created on the first interaction that includes userId — no scenarioSlug required.
POST https://api.proxy.vpn.recomnext.com/api/ingestion/interactions
{
"interactions": [
{ "userId": "customer-42", "itemId": "game-elden-ring", "type": "view" }
]
}Logout and account switch
On logout, clear app auth state and signal the coordinator (or manually clear SDK user + rotate session). Without rotation, a second login on the same browser can attach the wrong anonymous history.
await RecomnextIdentity.setAuthenticatedUserId(null);
// Manual equivalent:
recomnext.setUserId('');
recomnext.clearSession();Setting custom user IDs
| Setting | Type | Default | Description |
|---|---|---|---|
| REST API | — | — | userId on POST /recommendations and ingestion payloads. |
| Browser SDK | — | — | userId in constructor, setUserId(), or RecomnextIdentity.setAuthenticatedUserId. |
| Widget HTML | — | — | data-user-id when logged in; omit when RecomnextIdentity is configured. |
| React widget | — | — | userId prop optional with coordinator; RecomnextIdentityProvider syncs auth. |
| Widgets + auth | — | — | With coordinator: signal setAuthenticatedUserId only. Without: mergeIdentity + clearSession + sync userId on each widget. |
Compliance note
Merge attaches anonymous behavioral history to a known account. User export and delete APIs are available for API-key-authenticated requests. See site privacy and DPA pages for legal terms.