Your platform.
One SounDiva account.

01 · SYSTEM BOUNDARIES

How the integration works

02 · SIGN-IN, BALANCE AND PROFILE

Add hosted SounDiva widgets

The updated widgets are available on DEV. Load one public module directly from SounDiva, then place the HTML tags where you need sign-in, the account balance or the player profile. The partner runs its own frontend and backend; SounDiva serves the private widget frames and the same account page used on its website.

<script type="module"
  src="https://dev.soundiva.com/widget/sdk/v1.js"></script>

<soundiva-login locale="en"></soundiva-login>

<soundiva-balance balance-theme="brand-dark" size="auto"
  locale="en"></soundiva-balance>

<soundiva-profile theme="dark" mode="inline"
  locale="en"></soundiva-profile>

Put <soundiva-balance> in a header, sidebar, game screen or another page container. size="auto" adapts between desktop and compact presentations. Points are Bonus Points; Tickets are Winnings Points. The SounDiva balance signature is required in every theme and in the signed-out state. The balance opens the account; a separate profile tag can also render it inline or in a modal.

Balance presets are neutral, dark, light, brand-neutral, brand-dark and brand-light. Balance and profile support optional background-color, surface-color, text-color, muted-color, accent-color and border-color, each an opaque #RRGGBB value. The sign-in button keeps SounDiva's canonical styling. Try the themes, colors and inline/modal account in the SounDiva account demo.

PROFILE_WIDGET_URL=https://dev.soundiva.com/widget

SOUNDIVA_WIDGET_URL=https://dev.soundiva.com/widget
OIDC_CLIENT_ID=<your interactive client ID>
OIDC_CLIENT_SECRET=<server-only secret>
AUTH_SESSION_SECRET=<partner-generated secret>

The HTML tags infer the widget URL from the hosted script and need no OIDC credentials. The two URL settings above configure the separate reference applications. Use the URLs issued for your environment. Before using your own website, have SounDiva register its exact origin and interactive OIDC client.

Keep your backend's OIDC session and binding routes

One user sign-in creates separate partner and SounDiva widget token sessions, each refreshed automatically on its own server. Your backend retains /api/auth/* and implements /api/widget-auth/login and /api/widget-auth/complete as in this reference. Validate the single-use bindingId transaction and finish your own Authorization Code + S256 PKCE callback before binding the verified partner session server to server:

POST https://dev.soundiva.com/widget/api/partner/bind
Authorization: Bearer <partner interactive access token>
Content-Type: application/json

{ "bindingId": "<verified one-use binding ID>" }

EXPECT · 200
{ "requestId": "<opaque request ID>" }

Before clearing your partner session, call POST https://dev.soundiva.com/widget/api/partner/logout with the same verified interactive bearer credential and JSON {}; expect 204. Preserve the partner session if linked revocation fails. SounDiva checks the registered client, subject and SSO session. Neither endpoint returns private profile fields, points or widget credentials.

The public soundiva-auth-success and soundiva-auth-signed-out events contain no account data. Use them to recheck your own backend status. After confirmed settlement, call the balance tag's .refresh(); after confirmed server-side logout, call .sessionEnded(). The partner frontend cannot read the SounDiva frame DOM, profile or global balance. Activity budgets remain a separate backend API.

Your CSP must allow the exact SDK URL in script-src and https://dev.soundiva.com in frame-src. The current loader inserts inline presentation styles, so its style-src policy must permit those. No private API CORS access is needed; the parent can keep connect-src 'self'.

This DEV release displays the current profile and Points/Tickets. Unsupported account edits, responsible-play changes, purchases, history and subscriptions remain unavailable. The bundled soundiva-sign-in artifact is retained for explicit offline and legacy examples; use the online soundiva-login tag for this integration.

PHONE SIGN-IN · OPTIONAL

QR sign-in for websites and kiosks

The hosted SounDiva login can offer phone sign-in with qr-login, or qr-login="only" on a kiosk. Keep the same online SDK; SounDiva renders the QR and private account inside its iframe.

Online platform uses the sign-in button without QR. Game machine uses QR without a sign-in button. The experience selector preserves the current player, waiting sign-in and game. The public machine emulator remains a web session; the server determines the actual channel. Settle with Exit, then choose End session for the next player.

SANDBOX_QR_BROKER=true
SANDBOX_QR_CHANNEL=web
# Isolated loopback kiosk demo only (never the public Sandbox):
# SANDBOX_TERMINAL_MACHINE_ID=<registered machine ID>

The backend fixes the channel and machine. Browser commands carry only a public widget request reference and statuses. Device secrets, private profile data and full balances stay with SounDiva.

Terminal demo mode requires loopback backend and frontend addresses. A public kiosk gateway needs its own verified per-device adapter; a machine ID is not a credential. Enable terminal games after SounDiva confirms Activity API support for partner sessions. The local vendored SDK remains available for explicit legacy examples; use the hosted component for QR.

03 · AUTHORIZE THE ACTIVITY

Get a Keycloak service token, then open one session

Both calls originate from your backend, but they have different destinations. Keycloak authenticates the provider service; The OIDC identity endpoint separately identifies the member. The browser never chooses a point amount. Your backend sends only the approved activity, pairwise participant correlation, and your participation reference to the Activity API.

Authorization: Basic <clientId:clientSecret>
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
scope=activity:open activity:complete

{
  "access_token": "<server-only>",
  "token_type": "Bearer",
  "expires_in": 300
}

Authorization: Bearer <provider access token>
Content-Type: application/json

{
  "activityId": "partner-activity:demo",
  "partnerSubject": "sdpa_<pairwise-subject>",
  "externalRef": "participation-123",
  "idempotencyKey": "open-<unique-id>"
}

{
  "sessionId": "asession_...",
  "activityId": "partner-activity:demo",
  "sessionBudgetPoints": 1000,
  "balanceMode": "combined",
  "resultMode": "partner_balances",
  "spendingMode": "bonus_first",
  "sessionBalances": { "bonusPoints": 700, "winningsPoints": 300 },
  "expiresAt": "...",
  "status": "open"
}

HTTP 400  { "code": "insufficient_member_points", ... }
HTTP 404  { "code": "activity_not_available", ... }
HTTP 404  { "code": "partner_subject_not_linked", ... }
HTTP 409  { "code": "account_not_active", ... }
HTTP 409  { "code": "activity_session_limit_reached", ... }

04 · PARTNER-OWNED PROCESS

Run gameplay on your backend

Play steps, quiz answers, prize reveals, contest transitions, and other activity events remain in your system. You do not send one SounDiva transaction per event.

05 · ONE TERMINAL EFFECT

Complete the session or cancel

When the member presses Exit, your backend derives and sends one completion using the resultMode returned at open. For partner_balances, send final bonusPoints and winningsPoints in result: {type: "balances", ...}. For round_history, send result: {type: "history", rounds: [...]} with every closed round in order. This applies to both combined and separate game displays. Only legacy_aggregate accepts the old consumedPoints / awardedPoints format. For either new result mode, use its example below. Never turn a new session into one net delta: losing bonuses and winning the same amount changes the composition of Points.

Authorization: Bearer <provider access token>
Content-Type: application/json

{
  "result": { "type": "balances", "bonusPoints": 400, "winningsPoints": 750 },
  "resultRef": "partner-result-123",
  "idempotencyKey": "complete-<unique-id>"
}

{
  "result": {
    "type": "history",
    "rounds": [
      { "roundId": "r1", "stakePoints": 200, "payoutPoints": 450 },
      { "roundId": "r2", "stakePoints": 100, "payoutPoints": 0 }
    ]
  },
  "resultRef": "partner-result-123",
  "idempotencyKey": "complete-<unique-id>"
}

{
  "sessionId": "asession_...",
  "status": "completed",
  "sessionBalances": { "bonusPoints": 400, "winningsPoints": 750 },
  "consumedPoints": 300,
  "awardedPoints": 450,
  "releasedPoints": 700
}

{
  "consumedPoints": 0,
  "awardedPoints": 0,
  "balanceResults": {
    "bonus": { "consumedPoints": 0, "awardedPoints": 0 },
    "winnings": { "consumedPoints": 0, "awardedPoints": 0 }
  },
  "resultRef": "partner-result-123",
  "idempotencyKey": "complete-<unique-id>"
}

Authorization: Bearer <provider access token>
Content-Type: application/json

{ "idempotencyKey": "cancel-<unique-id>" }

{
  "sessionId": "asession_...",
  "status": "cancelled"
}

06 · OPERATIONS

Retries, idempotency, and failures

{
  "code": "activity_session_expired",
  "message": "The activity session is expired."
}

07 · READY TO INTEGRATE

Partner checklist

• Mount the shared SounDiva auth SDK on your backend.
• Load the online SounDiva SDK and place <soundiva-login>, <soundiva-balance> and <soundiva-profile> where needed. Do not keep a local copy of the loader.
• Register the exact website origin and interactive client with SounDiva. Complete the backend binding and linked logout flow.
• Keep identity correlation, secrets, and access tokens server-side.
• Use the service-account-only Keycloak client issued by SounDiva and verify it has the required Activity API roles.
• Persist externalRef, session IDs, idempotency keys, and internal evidence.
• Open one session without sending an amount; use the returned budget, source balances and modes throughout that session.
• Preserve ordered financial rounds and send exactly one result in the opened format. Finish before expiry and limits.
• Implement unchanged retry and explicit cancellation.
• Pass all contract tests before production credentials are enabled.