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.recomnext.com | https://admin.recomnext.com |
Use the engine base URL as baseUrl in widgets and SDKs.
Anonymous vs known users
| Setting | Type | Default | Description |
|---|---|---|---|
| Anonymous | session | — | Browser SDK generates sess_… in sessionStorage if no userId. |
| Known | userId | — | Your stable account ID from auth system. |
| Recommendations | both | — | user-to-item uses history for known users; session-scoped for anonymous. |
Identity merge
On login, copy anonymous session events to the authenticated user. Call once after login — not idempotent for auto-retry.
POST https://api.recomnext.com/identity/merge
Content-Type: application/json
X-Tenant-Id: aurora-games
{
"userId": "customer-42",
"sessionIds": ["sess_abc123"]
}Response
{ "merged": 12 }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.recomnext.com/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.recomnext.com/ingestion/interactions
{
"interactions": [
{ "userId": "customer-42", "itemId": "game-elden-ring", "type": "view" }
]
}Setting custom user IDs
| Setting | Type | Default | Description |
|---|---|---|---|
| REST API | — | — | userId on POST /recommendations and ingestion payloads. |
| Browser SDK | — | — | userId in constructor or setUserId(). |
| Widget HTML | — | — | data-user-id="customer-42". |
| React widget | — | — | userId prop on RecomnextCarousel. |
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.