OnAim Integration Guide
1. Introduction
This guide describes everything needed to connect your platform to OnAim. Sections 1–6 cover the backend integration; Sections 7–9 cover embedding OnAim pages in your frontend.
When you have read Sections 1–6, fill in the Information Request — the single document we need back from you to set up your integration.
OnAim is a gamification platform. Your platform tells OnAim what players do (deposits, bets, …); OnAim runs promotions on top of that activity (missions, leaderboards, coins, prize wheels, …) and asks your platform to pay out the rewards players win.
There are three integration points:
| # | Integration point | Direction | What you build |
|---|---|---|---|
| 1 | Authentication | Your site → OnAim (and optionally OnAim → you) | Issue a token that identifies the logged-in player when they open an OnAim promotion page |
| 2 | Event ingestion | You → OnAim | Send player activity events (at minimum Deposit) in real time |
| 3 | Reward payouts (withdrawals) | OnAim → you | An HTTP endpoint that credits a reward (cash, bonus, free spins, …) to a player |
1.1 The player id
OnAim identifies players only by your player id. The same value, as the same string, must appear in all three places:
| Where | Field |
|---|---|
| Authentication token / player endpoint | PlayerId (JWT claim) or the field you map to Id |
| Every event | customerId |
| Payout requests OnAim sends you | {{PlayerId}} |
If these differ (e.g. 12345 in events but "P-12345" in the token), a player's activity will not be linked to their promotion page and their rewards cannot be paid. Pick one stable, never-reused id (your internal account id is ideal — not the username, not the email).
1.2 Conventions
- Times are UTC. Send timestamps in ISO 8601 with a
Zsuffix or an explicit offset:2026-10-16T12:30:05.120Z. - Money amounts are decimal numbers in the major unit (
12.50, not1250cents). - Currencies are ISO 4217 codes (
EUR,USD,GEL, …). Common crypto codes (BTC,ETH,USDT, …) are also supported. - Field names are case-sensitive everywhere unless stated otherwise.
2. Authentication
When a logged-in player opens an OnAim promotion page inside your site, the page must know who the player is. Your platform proves this with a token generated by your backend. The page passes the token to OnAim, OnAim validates it, and the player is signed in to the promotion page.
OnAim supports three methods. Method A (signed JWT) is the default and the one we recommend. Choose one and tell us in the Information Request.
| A. Signed JWT (default) | B. One-time token + player endpoint | C. Token pass-through | |
|---|---|---|---|
| What your backend issues | A JWT signed with your private RSA key | A random one-time token | Any token/session string you already have |
| Does OnAim call your backend? | No | Yes — with Basic auth or HMAC | Yes — without credentials |
| What you build | Token signing | Token store + 1 endpoint | 1 endpoint |
| What you send us | RSA public key | Endpoint URL, credentials, field mapping | Endpoint URL, field mapping |
2.1 How it works
Player opens promotion page on your site
│
├─ 1. Your frontend asks your backend for a token for the current player
├─ 2. Your frontend loads the OnAim page with the token in the URL (2.2)
├─ 3. The OnAim page sends the token to the OnAim backend
├─ 4. OnAim validates the token ← method A, B or C below
└─ 5. OnAim creates (on first visit) or loads the player and opens the session
Tokens are passed in a URL, so they must be URL-safe (letters, digits, -, _, .). JWTs and hex/base64url strings are fine; standard base64 with +, /, = is not.
On first visit OnAim creates its own record of the player from the id and display name in the token — there is no separate player registration call.
2.2 Passing the token to the promotion page
Whichever method you use, your frontend puts the token in the ott parameter of the promotion page URL:
https://[onaim-landing].io/?promotionId=752&lang=en&landingPageId=574&ott={token}
promotionId and landingPageId come from OnAim. The same ott parameter is used by the iframe, the Web Component widget, Smart Links and the Promotion Hub described in Sections 7–9; there, "OTT" means the player token issued by any of the methods below.
2.3 Method A — Signed JWT (default)
Your backend signs a short-lived JWT for the current player. OnAim verifies the signature with your public key; there is no call back to your systems.
Requirements
| Item | Requirement |
|---|---|
| Algorithm | RS256 (RSA + SHA-256, PKCS#1 v1.5). Other algorithms (HS256, ES256, …) are rejected. |
| Key size | RSA 2048-bit or larger |
| Key you send us | The public key in PEM format (-----BEGIN PUBLIC KEY----- …). Never send the private key. |
| Header | {"alg":"RS256","typ":"JWT"} |
| Required claims | PlayerId — your player id (string) · UserName — the name shown to the player and on leaderboards |
| Recommended claims | exp — expiry, at most 5 minutes after issue · iat — issue time |
| Claim names | Exact, case-sensitive: PlayerId, UserName. Standard claims such as sub are not read. |
Claims may be top-level or inside a data object — both are accepted:
{ "PlayerId": "100234", "UserName": "lucky_joe", "iat": 1760617800, "exp": 1760618100 }
{ "data": { "PlayerId": "100234", "UserName": "lucky_joe" }, "iat": 1760617800, "exp": 1760618100 }
2.4 Method B — One-time token + player endpoint
Your backend generates a random, single-use token, stores it against the player, and puts it in the page URL. OnAim calls your player endpoint with the token; you return the player and invalidate the token.
Token requirements
- Generated server-side, cryptographically random (≥ 128 bits).
- Single use — invalidate it once OnAim has resolved it.
- Short-lived — expire unused tokens after at most 1 minute.
- URL-safe characters only (the token is inserted into your URL as-is, without encoding).
Request OnAim sends you
GET https://api.yourcasino.com/onaim/player/{token}
Authorization: Basic b25haW06czNjcjN0
- URL — you choose it. The token may be in the path or the query string; tell us the template with
{token}marking the position, e.g.https://api.yourcasino.com/onaim/player/{token}orhttps://api.yourcasino.com/onaim/player?ott={token}. - Method — always
GET, no body. - Authentication — choose one:
- Basic auth (default): you issue a username and password to OnAim.
- HMAC signature: OnAim issues a shared secret and signs each call (see 6.1). For this
GET, the signed body is empty, so the signed string is"{timestamp}.".
Response you return
Success — HTTP 2xx, Content-Type: application/json, a flat JSON object that contains the player id and display name:
{ "playerId": "100234", "username": "lucky_joe", "currency": "EUR" }
- Field names are up to you. You tell us which field is the id and which is the display name (the field mapping, e.g.
Id → playerId,UserName → username). - The two fields must be top-level properties. Nested paths such as
data.playerIdare not supported. - Number values are accepted (
"playerId": 100234) and treated as text. - Other fields are ignored.
Failure — any non-2xx status (e.g. 401 for an unknown or expired token). The player sees a sign-in error on the promotion page.
Respond within 5 seconds; the player is waiting on the page.
2.5 Method C — Token pass-through
The same as Method B, but OnAim sends no credentials with the call. Use this only when the token itself is a secret your endpoint already validates (for example, your existing player session token).
Request OnAim sends you
GET https://api.yourcasino.com/onaim/player?token={token}
- The token is URL-encoded before it is inserted.
- No
Authorizationor signature headers. Your endpoint must reject unknown or expired tokens on its own.
Response: identical to Method B.
2.6 What you send us
| Method | You send |
|---|---|
| A | RSA public key (PEM) |
| B | Endpoint URL template with {token} · Basic username + password or "use HMAC" · field mapping for Id and UserName · an example response |
| C | Endpoint URL template with {token} · field mapping for Id and UserName · an example response |
3. Event Ingestion
Your platform sends OnAim a stream of events describing what players do. Promotions are built in the OnAim Admin Panel on top of these events, for example "Deposit at least €50 in total this week" or "Bet on 20 slot rounds".
3.1 Delivery methods
| Method | How it works | Use when |
|---|---|---|
| REST API (default) | You POST signed JSON events to your OnAim endpoint |
Most integrations |
| Kafka | OnAim connects to your Kafka cluster and consumes your topics | You already publish player activity to Kafka |
Choose one and tell us in the Information Request.
3.2 REST API
Base URL — provided by OnAim, e.g. https://yourbrand-externaleventsbridgeapi.onaim.io.
| Endpoint | Body |
|---|---|
POST /api/Integrations/events |
One event (JSON object) |
POST /api/Integrations/events/batch |
Several events (JSON array). Recommended: up to 500 events per request. |
Headers (every request)
| Header | Value |
|---|---|
Content-Type |
application/json |
X-Timestamp |
Current Unix time in seconds, e.g. 1760617805 |
X-Signature |
HMAC-SHA256 signature of the request — required, see 6.1. Base64 encoded. |
The signing secret is issued by OnAim. Requests with a missing or invalid signature, or a timestamp more than 300 seconds away from OnAim's clock, will be rejected.
Responses
| Status | Meaning | What you do |
|---|---|---|
202 Accepted |
Received and queued. Single: empty body. Batch: {"accepted": N} |
Done. Do not resend. |
400 Bad Request |
Empty body, or /batch body not an array |
Fix the request; do not retry as is |
401 Unauthorized |
Signature missing/invalid or timestamp outside the 300 s window | Check secret, signing string, server clock |
503 Service Unavailable |
Intake buffer is full | Retry with backoff (e.g. 1 s, 2 s, 4 s … max 60 s) |
| Network error / timeout | — | Retry with backoff |
For /batch, a 503 body looks like {"error": "...", "accepted": 120}: the first 120 events (indexes 0–119) were accepted. Resend only the events from index 120 onward.
Important: 202 means received, not validated. Validation happens afterwards. An event with a missing or misspelled customerId is accepted with 202 and then discarded. Validate events on your side (see 3.4) before sending.
Duplicates are counted. OnAim does not de-duplicate events sent over REST — sending the same deposit twice counts as two deposits. Resend an event only if you did not receive a 202 for it.
Delivery recommendations
- Send events in real time, as they happen (within seconds), not in daily or hourly batches. Promotions react to activity live.
- Send from a durable queue/outbox, not fire-and-forget from the player's request path, so that OnAim downtime or a network blip does not lose events.
Request structure
POST /api/Integrations/events HTTP/1.1
Host: yourbrand-externaleventsbridgeapi.onaim.io
Content-Type: application/json
X-Timestamp: 1760617805
X-Signature: <base64 HMAC-SHA256 of "1760617805.{body}">
{"customerId":"100234","eventType":"Deposit","create_time":"2026-10-16T12:30:05.120Z","transactionId":"dep-778812","amount":50.00,"currency":"EUR"}
3.3 Kafka
OnAim runs a consumer that reads from your Kafka cluster.
What you provide
| Item | Notes |
|---|---|
| Bootstrap servers | host:port list reachable from the internet |
| Topics | One topic per event type is recommended, e.g. deposits → Deposit |
| Authentication | SASL_SSL with SCRAM-SHA-256 (username + password) — recommended. Or mutual TLS (client certificate + key). |
| CA certificate | PEM, if your brokers use a private CA |
| Message format | JSON (UTF-8) — recommended. Or Avro with a Confluent Schema Registry (registry URL must be reachable without authentication). |
| ACLs | Read on the topics; Read on consumer groups with the prefix OnAim gives you (OnAim uses one group per topic: {prefix}-{topic}) |
| Firewall | Allow OnAim's egress IP address(es), provided by OnAim |
Message rules
- The message value is the event. The message key is ignored.
- The value must be a flat JSON object (nested objects are not flattened on Kafka).
- The player id field must be
customerId(orcustomer_id— tell us which).playerIdis not recognised on Kafka. - The event type is taken from the event's
eventTypefield if present; otherwise from the topic → event type mapping you give us. - OnAim starts reading from the latest offset when the consumer first connects. Messages published before that moment are not read.
3.4 Event format
Every event is a flat JSON object: one level of "key": value pairs, no nested objects or arrays.
Required fields on every event
| Field | Type | Rules |
|---|---|---|
customerId |
string | Your player id — exactly the same value as in authentication (see 1.1). Spell the key exactly customerId. Also accepted: customer_id, and playerId (REST only). Not accepted: CustomerId, customerID. |
eventType |
string | Name of the event, e.g. Deposit. Case-sensitive value: Deposit and deposit are different event types. Use exactly the names you list in your event catalog. |
| Event time — any field name | string | When the action happened on your side, ISO 8601 with Z or an explicit offset (2026-10-16T12:30:05.120Z). Use the field name you already have (create_time, created_at, timestamp, …) and tell us which field it is; it must be the same field name on every event type. Promotions use this time, not the time OnAim received the event. |
Recommended on every event
| Field | Type | Why |
|---|---|---|
transactionId (or your own name) |
string | Unique id of the action in your system. Lets both sides trace and reconcile events. |
Reserved names — do not send
| Field | Reason |
|---|---|
promotionId |
Restricts the event to one OnAim promotion. Sending your own field with this name breaks promotion matching. |
customerId as part of another name |
OnAim renames the configured player id key across the whole event; avoid other keys that contain it (e.g. affiliate_customer_id). |
Everything else is free. Send any other fields with the names and values you already use (amount, game_code, payment_method, is_first_deposit, …). Promotions can filter and sum on any field described in your event catalog (see 3.6). You can add new fields at any time without OnAim changing anything.
3.5 Required events
Deposit is required. It is the one event OnAim's platform relies on for every client: deposit-based promotions, deposit totals and USD conversion. The eventType value must be exactly Deposit.
Send it once per successful deposit, at the moment the funds are credited to the player (not when the deposit is initiated, not for failed/cancelled deposits).
Example structure:
{
"customerId": "100234",
"eventType": "Deposit",
"create_time": "2026-10-16T12:30:05.120Z",
"transactionId": "dep-778812",
"amount": 50.00,
"currency": "EUR",
"payment_method": "card",
"is_first_deposit": false,
"channel": "mobile"
}
OnAim automatically adds usdAmount (the amount converted to USD at the current rate), so promotions can work across currencies.
If you want game-based promotions ("play slots from provider X"), also send us your game list (see the Information Request): at least game code, provider and game type for each game. Game events must then carry the same game code and provider values.
3.6 Event catalog and mappings
The OnAim Admin Panel only lets promotion managers build rules on fields it knows about. You describe your events once in an event catalog, and OnAim imports it.
The catalog lists, for each event type you send:
- the event name (
eventTypevalue) and a human-readable label, - each field: name exactly as in the JSON, label, type (
string,int,decimal,dateTime,stringArray,intArray), and whether it is a summable amount, - for enumerable fields (status, channel, payment method, …): every possible raw value and its label — these become dropdowns in the Admin Panel.
You can deliver it either as:
- the machine-readable event metadata file — format, JSON Schema and examples in Event Metadata File; or
- a spreadsheet with the same information plus one real example payload per event type — OnAim converts it.
You do not rename anything. Your field names and raw values are used as they are; labels make them readable in the Admin Panel. OnAim can also derive extra fields from yours without any change on your side, for example:
usdAmountfromamount+currency(automatic forDeposit; for other events on request),game_typefromgame_code+providervia a mapping table maintained in the Admin Panel.
Tell us in the catalog which field holds the amount and which the currency for every monetary event.
4. Reward Payouts (Withdrawals)
When a player redeems a reward on an OnAim promotion page (e.g. exchanges coins for a €10 bonus or 20 free spins), OnAim calls your payout endpoint to credit the reward. OnAim builds each request from a template you define, so your endpoint can keep its own field names.
4.1 How rewards are configured
- Payout endpoint — one HTTP request template: URL, method, headers, query string, JSON body. You typically have one endpoint per kind of reward (cash, bonus, free spins, free bets).
- Reward option — what the player sees and picks, e.g. "€10 Bonus" or "20 Free Spins on Book of Dead". Each option uses one payout endpoint and fills in that endpoint's option-specific fields (e.g. your bonus template id).
- Packages (nominals) — for rewards that come in fixed packages (10 / 20 / 50 free spins), each package maps to your own id for that package.
For each kind of reward you want to offer, tell us in the Information Request: the endpoint, what OnAim must send, and which values differ between reward options.
4.2 The request OnAim sends
You define the template. Each value in the body, query string or headers is one of:
- a fixed value, e.g.
"brand": "mycasino"; - a placeholder filled in by OnAim per payout (table below), e.g.
"user_id": "{{PlayerId}}"; - an option field, set per reward option in the Admin Panel, e.g.
"bonus_template_id"=B-1001for the "€10 Bonus" option.
Placeholders
| Placeholder | Value | Example |
|---|---|---|
{{ExternalId}} |
Unique id of this payout. Your idempotency key — identical on every retry of the same payout. | 88213_6f1c2a9e-… |
{{PlayerId}} |
Your player id (same as customerId) |
100234 |
{{Username}} |
Player display name (may be empty) | lucky_joe |
{{Quantity}} |
Number of units to credit (e.g. number of spins, number of bonus units) | 20 |
{{Value}} |
Value of one unit, as configured on the reward option | 0.20 |
{{Nominal}} |
Your package id (packages/nominals only) | FS-20-BOD |
{{CampaignCode}} |
Campaign code configured on the reward coin (may be empty) | XMAS26 |
{{PromotionId}} |
OnAim promotion id (may be empty) | 752 |
{{LandingPageId}} |
OnAim promotion page id (may be empty) | 574 |
{{CurrentDate}} |
Request time, UTC, format yyyy-MM-ddTHH:mm:ss (no Z) |
2026-10-16T12:31:40 |
Placeholders can be combined with text: "reference": "onaim-{{ExternalId}}".
Format rules
- Body is JSON (
Content-Type: application/json; charset=utf-8) forPOST,PUT,PATCH.GET/DELETEsend no body — use query parameters. - The body is a flat JSON object and every value is sent as a string:
"quantity": "20", not20. Parse numbers on your side. - Query parameters are URL-encoded.
- Additional headers OnAim always sends:
X-Tenant-Id,X-Tenant-Code(ignore them).
Example — template you give us
{
"url": "https://api.yourcasino.com/onaim/bonus/credit",
"method": "POST",
"body": {
"request_id": "{{ExternalId}}",
"user_id": "{{PlayerId}}",
"bonus_template_id": "<per reward option>",
"amount": "{{Value}}",
"count": "{{Quantity}}"
}
}
…and the request your endpoint receives
POST /onaim/bonus/credit HTTP/1.1
Host: api.yourcasino.com
Content-Type: application/json; charset=utf-8
Authorization: Basic b25haW06czNjcjN0
{"request_id":"88213_6f1c2a9e-4b9a-4c55-9d0e-5f0b0a6f3e11","user_id":"100234","bonus_template_id":"B-1001","amount":"10.00","count":"1"}
4.3 Authentication of payout requests
Choose one:
- Basic auth (default) — you issue a username and password to OnAim; sent as
Authorization: Basic …. - HMAC signature — OnAim signs every request with a secret it issues to you; see 6.1. Headers:
X-OnAim-Timestamp,X-OnAim-Signature(lowercase hex). Each retry is re-signed with a new timestamp. - Static header — a fixed API key header you give us (e.g.
X-Api-Key: …), sent on every request.
Basic auth and HMAC can be combined.
4.4 How OnAim reads your response
| Your response | OnAim treats it as | Retried? |
|---|---|---|
HTTP 200, body without error_code, or {"error_code": 0} |
✅ Success — reward delivered | — |
HTTP 200 with {"error_code": <non-zero integer>} |
❌ Rejected (permanent) | No |
| HTTP 4xx | ❌ Rejected (permanent) | No |
| HTTP 5xx, timeout, connection error | ⚠️ Temporary failure | Yes |
| HTTP 201, 202, 204 or any other 2xx | ❌ Failure | — |
- Success must be exactly HTTP 200. Return 200 only once the reward is actually credited (or guaranteed to be).
error_code, if present, must be a JSON integer.- On a temporary failure OnAim retries automatically, about every 5 seconds, up to 6 requests in total. All retries carry the same
{{ExternalId}}. - OnAim may also send the same request a second time after a 4xx or non-zero
error_code. Answer it the same way as the first time. - Payouts that still fail are shown to OnAim operators, who can retry them manually later — again with the same
{{ExternalId}}. - Respond within 30 seconds.
4.5 Idempotency — mandatory
Because of retries, your endpoint will receive the same payout more than once. It must credit each {{ExternalId}} at most once:
You receive an ExternalId that… |
Respond |
|---|---|
| you have never seen | Process it; return 200 (or a rejection) |
| you already credited | Return 200 again without crediting again |
| you already rejected | Return the same rejection again |
| is still being processed | Return 5xx so OnAim retries later, or wait and return the final result |
Store ExternalId with a unique constraint on your side.
4.6 Testing
OnAim must be able to send test payouts to your endpoint during setup, using test players on your side.
5. Optional: Reading Player Balances
If you want to show OnAim coin balances inside your own site or app, you can query them:
POST /api/Integrations/players/balances (same base URL as events)
Content-Type: application/json
X-Timestamp: 1760617805
X-Signature: <HMAC, same scheme as events>
{ "playerId": "100234", "promotionId": 752 }
promotionId and coinId are optional filters. Response:
{
"playerId": "100234",
"balances": [
{ "coinId": "5", "coinName": "Gold", "coinType": "In", "isGlobal": false, "amount": 120, "promotionId": 752 }
]
}
6. Request Signing & Go-live
6.1 HMAC signatures
All HMAC signatures in this guide use the same algorithm:
signing string = "{timestamp}.{raw body}"
signature = HMAC-SHA256( key = secret as UTF-8 bytes, message = signing string as UTF-8 bytes )
{timestamp}is the Unix time in seconds, exactly as sent in the timestamp header.{raw body}is the exact bytes of the HTTP body as sent — sign after serialising, and do not re-serialise or pretty-print afterwards. Empty forGET(signing string ends with.).- The secret is used as UTF-8 text, not base64-decoded.
- Reject (when verifying) any timestamp more than 300 seconds from your clock.
| Direction | Timestamp header | Signature header | Encoding |
|---|---|---|---|
| You → OnAim (events, balances) | X-Timestamp |
X-Signature |
Base64 |
| OnAim → you (player endpoint, payouts) | X-OnAim-Timestamp |
X-OnAim-Signature |
lowercase hex |
6.2 Go-live checklist
- Auth: opening a promotion page as a test player shows that player's name; an expired/invalid token shows a sign-in error.
- Player id: the id OnAim shows for the test player equals
customerIdin that player's events. - Events: a signed test
Depositreturns202, and OnAim confirms it was received with all fields. - Events: a request with a wrong signature returns
401. - Catalog: every event type and field you send is in the event catalog.
- Payout: an OnAim test payout credits the reward on your side.
- Payout idempotency: OnAim resends the same
ExternalId→ you return 200 and do not credit twice. - Payout rejection: a payout for an unknown player returns 4xx (or
error_code≠ 0). - End to end: OnAim sets up a test promotion ("deposit €10 → get 1 coin → redeem for a bonus"); a test player completes it.
7. Promotion Page Embedding (Frontend)
Sections 1–6 cover the backend integration (player authentication, events, reward payouts). This section covers the frontend side: how the Promotion Landing Page is embedded into your site and how it communicates with your page at runtime (login, deposit, balance, resize). It expands on the basic iframe embed in Section 2.2.
There are two embed shapes, both served from the same renderer. The iframe is the currently recommended integration; the Web Component widget is also supported.
| Shape | What it is | When to use |
|---|---|---|
| iframe (recommended) | The landing page loaded as a URL inside an <iframe>. Communicates via window.postMessage. |
Default embed. Broadest host compatibility and cross-origin isolation. |
| Web Component widget | A <onaim-landing-page> custom element loaded from a single JS bundle. Style-isolated (Shadow DOM). Communicates via element methods + DOM events. |
Embedding directly in your own page: no iframe, no scrollbars, sizes to content automatically (minimum one screen height). |
7.1 iframe embedding (recommended)
Embed the landing page as a URL inside an <iframe>, using the base URL and OTT described in Section 2.2. At runtime the iframe and your page exchange postMessage events (see 7.3 and 7.4).
<iframe
id="onaim-landing"
src="https://[onaim-landing].io/?promotionId=752&lang=ka&landingPageId=574&ott=80b6a17cc251"
style="width:100%; border:none;">
</iframe>
The iframe posts its content height so you can resize it (7.5). Do not give it a viewport-relative height (100vh, %) in this mode. This auto-height behaviour is the default and the recommended setup: the promotion reads as a native part of your page, with no inner scrollbar.
When to useembedMode=innerinstead. This parameter turns off auto-height and lets the landing page scroll inside a fixed-size iframe. Use it only when the promotion sits in a container whose size you already control — a full-screen dialog, a modal, or a side drawer. Do not use it for a landing page placed inline in a normal page: it produces a scrollable box inside your page, and you have to guess a height that suits every promotion.
Two behaviour differences to be aware of in this mode: dialogs inside the promotion centre themselves and no longer need thescrollTocommand (7.3), but "scroll to section" buttons configured on the promotion will not work, because scrolling happens inside the iframe rather than on your page. AvoidembedMode=innerfor promotions that use those buttons.
URL parameters
| Parameter | Required | Description |
|---|---|---|
slug |
Recommended | Smart Link slug provided by OnAim (see below). Takes precedence over promotionId / landingPageId. The player token is also removed from the iframe URL after authentication in this mode. |
promotionId |
Conditional | Promotion/campaign id (integer). Use together with landingPageId when you are not using slug. This pins the embed to one fixed landing page. |
landingPageId |
Conditional | Landing-page id (integer). Normally paired with promotionId. Passed alone (no slug, no promotionId) it selects a Global Page — a multi-promotion catalog page rather than a single promotion. See Section 9. |
ott |
No | Player One-Time Token (see Section 2). one-time-token is accepted as an alias. Omit it to render the page for a logged-out visitor. |
lang |
Recommended | Language code, e.g. en, ka. If omitted the page defaults to ka (Georgian) — always pass this explicitly. An unknown code falls back to the promotion's first configured language. |
embedMode |
No | inner disables auto-height posting and lets the landing page scroll inside a fixed-size iframe. Only for promotions placed in a container you already size yourself, such as a dialog or drawer — see the note above. Leave it out for a normal inline embed. |
Unauthenticated embeds are supported. Withoutottthe page renders its logged-out variant; components configured for signed-in players are hidden and no personalized data is fetched. The expected flow is: embed anonymously → the player clicks a call-to-action → the landing sendslogin(code1001, see 7.3) → you sign the player in → you reload the iframe with a freshott.
Smart Links (recommended targeting)
A Smart Link is a named slug configured in the OnAim admin panel. Instead of pointing your embed at a specific promotion and landing page, you point it at the slug, and OnAim decides at request time which promotion and landing page that particular player should see — based on the player segment they belong to, with a default for everyone else.
<iframe
id="onaim-landing"
src="https://[onaim-landing].io/?slug=summer-promo&lang=en&ott=80b6a17cc251"
style="width:100%; border:none;">
</iframe>
For you this is a one-parameter change, and it removes ongoing work:
- Your embed code stops changing. When a campaign ends and a new one replaces it, OnAim repoints the slug — the markup on your site stays exactly as it is. With
promotionId/landingPageIdyou would have to update and redeploy your page for every campaign. - Pass the player token if you want segment-based routing. Segments are resolved from the authenticated player, so a visitor embedded without
ottalways receives the default landing page. - One slug can serve different players different pages — VIP, new player, country-specific — with no branching logic on your side.
- A slug can be deactivated in the admin panel. If that happens the embed will fail to load and the iframe will show an error page; this is a configuration state, not a fault in your integration.
Ask OnAim for the slug that corresponds to your placement. If you have not been given one, use promotionId + landingPageId as shown above.
Player token lifecycle
The OTT is exchanged once, inside the landing page, for a short-lived session. Practical consequences for your integration:
- There is no token refresh. When the session expires, the landing page does not renew it — reload the iframe with a newly generated OTT.
- OTTs are single-use and short-lived. Generate one per embed, at the moment you render the iframe. Do not cache it or reuse it across page loads.
- Failures are silent. If the token is rejected, the page renders as logged-out; no message is sent to your page. If the player unexpectedly appears signed-out, check the token first.
- With
slug, the session is cached briefly in the iframe so a refresh keeps the player signed in. Browsers that block third-party storage (Safari, and Chrome with storage partitioning) will drop that cache — the player is then treated as logged-out on refresh, which is expected. No cookies are used anywhere in the integration.
7.2 Web Component widget
Add the widget bundle and drop the element wherever the promotion should appear. OnAim provides the bundle URL and your promotion-id / landing-page-id values — the widget loads its own environment configuration from the host it is served from, so no additional setup is required on your side.
<!-- widget bundle (URL provided by OnAim) -->
<script type="module" src="https://<LANDING_HOST>/widget/onaim-landing-page.js"></script>
<!-- the element -->
<onaim-landing-page
promotion-id="752"
landing-page-id="574"
language="ka"
otp="80b6a17cc251">
</onaim-landing-page>
Overriding the gateway (optional). The widget fetches its configuration fromhttps://<LANDING_HOST>/env.json load. If your Content-Security-Policy blocks that, or you need to point the widget at a specific gateway, define the global yourself before the bundle tag and the widget will use it and skip the fetch:If neither is available the widget still loads, but its API calls fail and it renders nothing — check the browser console for an<script> window.OnAim = window.OnAim || {}; window.OnAim['landing-v2'] = { GATEWAY_URL: 'https://<GATEWAY_HOST>' }; </script>[env]message.
The widget adds two tags to your<head>. On mount it injects a Google-Fonts stylesheet link (markeddata-onaim-font="roboto"), and — only if your page has none — a<meta name="viewport" content="width=device-width, initial-scale=1">tag, which the promotion's responsive layout depends on. If your site is not otherwise mobile-responsive, adding that meta tag can change how your page renders on mobile; declare your own viewport meta tag to keep control.
The widget fetches its own configuration, renders inside its Shadow DOM, and grows to fit its content — no height messaging is required. Note that it always occupies at least the full height of the screen, even for a short promotion, so it is designed to be placed as a full section of your page rather than inline between paragraphs.
Widget attributes
| Attribute | Required | Description |
|---|---|---|
promotion-id |
Yes | Promotion/campaign id (integer). |
landing-page-id |
Yes | Landing-page id (integer). |
language |
No | Language code, e.g. en, ka. |
otp |
No | Player One-Time Token for personalized/authenticated content (see Section 2). |
enable-signalr |
No | Real-time updates. Enabled unless set to "false". |
config |
No | Inline configuration JSON (an array of components, or { components, fonts }). Testing/preview only — normally the widget fetches its own configuration. |
Methods and events
Call methods directly on the element, and listen for its DOM events:
const el = document.querySelector('onaim-landing-page');
el.setLanguage('en'); // switch language at runtime
// el.setConfig([...]); // replace config (preview/testing only)
el.addEventListener('ready', () => console.log('landing ready'));
el.addEventListener('error', (e) => console.error('landing error', e.detail));
Important: the widget still uses thepostMessagecommands in 7.3 for player actions —login(1001),register(1002),openTab(1011) anddeposit(1012). Because there is no iframe, the widget posts them to your own page's window, so you must add the samemessagelistener shown in 7.3. Without it, the Login, Register and Deposit buttons inside the widget will do nothing. The iframe-specific messages areheight(1003) andscrollTo(1031) — the widget never sends either (it scrolls your page directly).
One exception: a few device-routed external links (for example the refer-a-friend CTA) callwindow.open()directly in widget mode instead of postingopenTab. Those are subject to your browser's popup blocker; they are opened from a real click, so a standard blocker allows them.
// Widget mode: the same handler as 7.3, listening on your own window.
window.addEventListener('message', (event) => {
const { code, value } = event.data || {};
switch (code) {
case 1001: showLoginModal(); break;
case 1002: showRegisterModal(); break;
case 1011:
if (typeof value === 'string' && value.startsWith('https:')) {
window.open(value, '_blank', 'noopener');
}
break;
case 1012: openDepositFlow(value); break;
}
});
7.3 Messages FROM the landing page (landing → host)
Add a single message listener on the parent window. This applies to both embed shapes — in the iframe embed the messages come from the iframe, in the widget embed they arrive on your own window (7.2). Command messages carry both a numeric code and a string action (match on either); the message field is a human-readable label and must not be used for control flow.
Handling 1001, 1002, 1011 and 1012 is required for a working integration in both shapes; 1031 is required for the iframe embed (widgets never send it); 1003 is required for the auto-height iframe embed.
| code | action | Extra | Meaning / host action |
|---|---|---|---|
1001 |
login |
— | Player requested sign-in. Show your login UI; after a successful login, reload the iframe with a fresh OTT. |
1002 |
register |
— | Player requested registration. Show your sign-up UI. |
1003 |
height |
value (px) |
Content height changed. Resize the iframe (7.5). |
1011 |
openTab |
value (URL) |
Open an external link in a new tab. |
1012 |
deposit |
value (method or null) |
Player triggered a deposit. Open your deposit/cashier flow. value is an optional payment-method hint and is currently always null — handle the null case. |
1031 |
scrollTo |
value (Y px) |
Required. Scroll your page so this Y offset aligns to the top of the viewport. The landing sends this to bring a dialog into view when it opens (only while you do not post host-viewport, 7.7), and for any "scroll to section" button configured on the page. The value is already adjusted for a comfortable top margin — apply it as-is, do not re-center it. |
1032 |
scrollLock |
value (true/false) |
Recommended, after 1031/1020. A landing dialog opened (true) or the last one closed (false) — freeze and restore your page's scroll. Auto-height embeds only. In auto-height mode the iframe never scrolls, so the landing cannot hold your page still by itself; without this the page keeps scrolling behind an open dialog. Ref-counted and always balanced (overlapping dialogs send one true and one false), plus an unlock on pagehide. See the note below for the prerequisite and the iOS Safari variant. |
1021 |
host-viewport-request |
— | Optional. The landing is asking for your current viewport (7.7) — sent when a pinned component mounts or a dialog opens. You can receive it more than once per session; answer each one by posting a single host-viewport message. Ignore it if you have not implemented 7.7. |
scrollLock(1032) on iOS Safari. iOS ignoresoverflow: hiddenon the body, so pin the scroll position instead: on lock storewindow.scrollY, setbody.style.position = 'fixed'andbody.style.top = '-' + storedY + 'px'; on unlock clear both andwindow.scrollTo(0, storedY). Note thatscrollTo(1031) stays live while locked — the landing sends 1032 after any 1031 that positions the dialog, but scroll-to-section buttons fire at any time; with the pinned variant apply an incoming 1031 by updating the stored Y andbody.style.top, because a locked page ignoreswindow.scrollTo. HandlescrollTo(1031) orhost-viewport(1020) before implementing 1032. Those position a dialog on the visible screen; 1032 only freezes the page. Locking without either leaves the dialog off-screen with no way for the player to scroll to it, which reads as a frozen landing. Skipping 1032 is safe — without it the page simply scrolls behind an open dialog, as it does today.
Dialogs and popups depend on1031orhost-viewport(7.7). In the auto-height iframe embed the iframe is as tall as its content and never scrolls — your page does. If you implementhost-viewport(code1020, section 7.7), dialogs render centered on the player's visible screen and1031is no longer sent for dialogs. Otherwise, when a dialog opens the landing asks you to scroll it into view via1031. If you implement neither, dialogs will open far outside the visible screen and appear broken. Keep the1031handler in every case — "scroll to section" buttons post it in any iframe embed, regardless ofhost-viewport.
State messages use type (no code). They are reserved for upcoming promotion types and are not emitted by the current release — you can safely omit handlers for them today; they are listed so you can plan for them.
| type | Extra | Meaning |
|---|---|---|
balance-update |
amount (number) |
In-game balance changed. Refresh your balance display. |
no-more-balance |
— | Player is out of balance. Prompt a deposit. |
tournament-play |
— | Tournament-over "Play" CTA. Route the player to the next playable surface. |
Native app embeds: inside the OnAim native app, thedeposit(1012) and alink/ redirect command (code 1010, withvalue= URL) are delivered throughwindow.PromotionChannelinstead ofpostMessage. Pure web hosts only need thepostMessagecodes above.
Complete listener:
const iframe = document.getElementById('onaim-landing');
const HEADER_HEIGHT = 0; // height in px of your fixed/sticky header, if any
window.addEventListener('message', (event) => {
// Required in production: only act on messages from the landing page.
// iframe embed — the message comes from the landing origin:
if (event.origin !== 'https://<LANDING_HOST>') return;
// Widget embed — the widget runs inside your page, so the message comes from
// your own origin instead. Use this check there:
// if (event.origin !== window.location.origin) return;
const { type, code, value, amount } = event.data || {};
switch (code) {
case 1001: showLoginModal(); break; // login
case 1002: showRegisterModal(); break; // register
case 1003: iframe.style.height = value + 'px'; break; // height
case 1011: // openTab
if (typeof value === 'string' && value.startsWith('https:')) {
window.open(value, '_blank', 'noopener');
}
break;
case 1012: openDepositFlow(value); break; // deposit (value is currently always null)
case 1031: { // scrollTo — required; value is a Y offset in the IFRAME's document
const r = iframe.getBoundingClientRect();
// Subtract the height of any fixed/sticky header so the target is not hidden under it.
window.scrollTo({ top: r.top + window.scrollY + value - HEADER_HEIGHT, behavior: 'smooth' });
break;
}
case 1032: // scrollLock — hold your page still behind a landing dialog
// iOS Safari ignores overflow:hidden on body; pin scrollY instead (see note above).
document.body.style.overflow = value ? 'hidden' : '';
break;
case 1021: postHostViewport(); break; // host-viewport-request — see 7.7
}
// Reserved, not emitted by the current release:
switch (type) {
case 'balance-update': updateBalance(amount); break;
case 'no-more-balance': showDepositPrompt(); break;
case 'tournament-play': routeToNextGame(); break;
}
});
Security: treat everyvalueURL as untrusted — allow onlyhttps:links and open them withnoopener. Validatingevent.originis your responsibility: the landing page broadcasts its messages and does not restrict who receives them, so without this check any other frame on your page could impersonate it.
7.4 Messages TO the landing page (host → iframe)
Post to the iframe's contentWindow:
const iframe = document.getElementById('onaim-landing');
iframe.contentWindow.postMessage({ type: 'SET_LANGUAGE', payload: 'en' }, '*');
| type | Payload | Effect |
|---|---|---|
SET_LANGUAGE |
string |
Switch the display language. |
SET_LANGUAGES |
string[] |
Adds languages to the list already available. This is additive only — languages cannot be removed by sending a shorter list. |
SET_CONFIG |
config object/array | Replace the rendered component configuration. |
SET_GLOBAL_VARIABLES |
object (CSS variables) | ⚠️ Not currently applied in iframe mode. For widget theming, use the element's setGlobalVariables() method instead. |
host-viewport (action, code 1020) |
scrollY, innerHeight, iframeTop |
Pinned components + dialog centering — see 7.7. |
7.5 Height auto-adjustment (iframe)
Unless you pass embedMode=inner, the iframe measures its content and posts a height command (code 1003) whenever it changes (initial load, dynamic content, layout shifts). Apply it so there is no inner scrollbar:
window.addEventListener('message', (event) => {
const { code, value } = event.data || {};
if (code === 1003) {
document.getElementById('onaim-landing').style.height = value + 'px';
}
});
A CSS transition: height 0.2s on the iframe keeps resizes smooth.
The height is re-checked frequently, so expect to receive this message several times per second, often with an unchanged value. Ignore no-op updates rather than assuming one message per real change:
let lastHeight = 0;
if (code === 1003 && Math.abs(value - lastHeight) > 1) {
lastHeight = value;
iframe.style.height = value + 'px';
}
If the iframe stops growing: the landing page detects a runaway resize loop (its content growing because the iframe grew, and vice versa) and stops posting heights to protect your page. The symptom is an iframe that freezes at one height with content cut off; it starts posting again by itself once the content genuinely shrinks. It is almost always caused by giving the iframe a viewport-relative height — see the warning below.
Do not give the iframe a viewport-relative height (100vh,%) in auto-height mode: the content grows with the iframe, which grows with the content — an unbounded loop. Let the posted height drive the size. (embedMode=inneravoids the loop too, but it is only appropriate for dialog-style containers — see 7.1.)
7.6 iframe vs widget
| Concern | iframe (recommended) | Web Component widget |
|---|---|---|
| Embed | <iframe src> |
<onaim-landing-page> + bundle |
| Style isolation | full document boundary | Shadow DOM |
| Host → landing | postMessage (SET_LANGUAGE, SET_CONFIG) |
element methods (setLanguage, setConfig) |
| Landing → host | postMessage codes (7.3) |
postMessage codes (7.3, on your own window) + DOM events (ready, error) |
| Height | height 1003 → you resize (7.5) |
grows automatically |
| Targeting | promotionId + landingPageId (URL) |
promotion-id + landing-page-id (attributes) |
| Player token | ott URL parameter |
otp attribute |
| Theming | not applied via postMessage |
setGlobalVariables() method |
| Player actions (login / register / deposit) | postMessage codes (7.3) |
postMessage codes (7.3) — same handler, listening on your own window |
| Targeting by player segment | Smart Link slug (7.1) |
not available — use fixed ids |
7.7 Sharing your scroll position with the iframe (host viewport, code 1020)
Recommended for the default auto-height iframe embed, and required if your promotion uses pinned / sticky components — components configured to stay fixed to the top or bottom of the screen while the player scrolls. It also gives dialogs and popups proper in-place centering: they render on the player's visible screen instead of the page jumping to them (1031). By posting your page's scroll position and viewport size down to the iframe, you let the landing page see where the visible screen is.
Why it's needed: in auto-height mode the iframe is grown to its full content height (7.5), so the iframe itself never scrolls — your page does. Code inside the iframe cannot read your scroll position across origins, so on its own it can only position things relative to the whole (tall) document, not the player's visible screen. The host-viewport message tells it where that visible screen is.
Skipping it degrades gracefully rather than breaking: a pinned component simply scrolls with the page instead of staying fixed, and dialogs fall back to the scrollTo page jump (1031, see 7.3). Implement it if your promotion uses pinned components or you want dialogs centred without a page jump. The Web Component widget and self-sized iframes (embedMode=inner) have a real viewport of their own, so they do not need it — the landing ignores host-viewport in those modes.
Dialog centering: when you posthost-viewport, dialogs and popups render centered on the player's visible screen and the landing stops sendingscrollTo(1031) for dialogs. Keep the1031handler anyway — "scroll to section" buttons still post it, and it is the dialog fallback for any moment the landing has not yet received a viewport from you. The landing ignoreshost-viewportoutside the auto-height embed (e.g.embedMode=inner), so posting it unconditionally is safe.
Post your viewport to the iframe
Send a host-viewport message to the iframe's contentWindow on load, on scroll, and on resize:
| Field | Type | Value |
|---|---|---|
action |
string |
"host-viewport" |
code |
number |
1020 |
scrollY |
number |
Current vertical scroll position of your page, in px (window.scrollY). |
innerHeight |
number |
Height of the visible viewport, in px (window.innerHeight). |
iframeTop |
number |
The iframe element's top edge in your document: rect.top + window.scrollY. |
All three numeric fields are required and must be finite numbers — a malformed message is ignored and the last good value is kept.
const iframe = document.getElementById('onaim-landing');
function postHostViewport() {
const rect = iframe.getBoundingClientRect();
iframe.contentWindow.postMessage({
action: 'host-viewport',
code: 1020,
scrollY: window.scrollY,
innerHeight: window.innerHeight,
iframeTop: rect.top + window.scrollY, // iframe's top in the document
}, '*');
}
// Post on scroll and resize (passive listeners keep scrolling smooth)…
window.addEventListener('scroll', postHostViewport, { passive: true });
window.addEventListener('resize', postHostViewport);
// …and once when the iframe is ready, so overlays are placed correctly before any scroll.
iframe.addEventListener('load', postHostViewport);
// The iframe may ask for the current viewport (action 'host-viewport-request',
// code 1021) — when a pinned component mounts or a dialog opens. It can arrive
// more than once per session; answer each by posting once. Post from THIS
// window (the iframe's direct parent) — other frames are ignored.
window.addEventListener('message', (event) => {
if (event.source === iframe.contentWindow && event.data?.code === 1021) {
postHostViewport();
}
});
Fixed or sticky header: if your page has a fixed header (or any bar pinned over the top of the viewport), report the viewport below it —scrollY: window.scrollY + headerHeightandinnerHeight: window.innerHeight - headerHeight,iframeTopunchanged. Otherwise dialogs are centered on the full screen and, on short screens, their top edge can slide under your header. Apply the same offset toscrollTo(1031):top: rect.top + window.scrollY + value - headerHeight.
Tip: keep posting on every scroll and resize — the landing coalesces the updates to one per animation frame. Also re-post after any layout change that moves the iframe without a scroll (content collapsing above it, applying a new height from a1003message), oriframeTopgoes stale and overlays land offset.
7.8 Network and Content-Security-Policy requirements
The landing page talks to OnAim services directly from the player's browser. If your site sends a Content-Security-Policy header, or sits behind a proxy that filters outbound traffic, allow the following. <LANDING_HOST>, <GATEWAY_HOST>, <ASSET_HOST>, <GAME_HOST> and <WIDGET_HOST> are provided by OnAim per environment.
How much of this applies depends on the embed shape. In the iframe embed the landing page runs in its own document under its CSP, so your page only needsframe-src(plusconnect-srcif a proxy filters outbound traffic). In the Web Component widget and the floating widget the OnAim code runs inside your document, so your CSP governs everything it loads — every row below applies.
| Directive | Allow | Needed for |
|---|---|---|
frame-src |
<LANDING_HOST> |
iframe embed (7.1), and the dialog opened by the floating widget (Section 8) |
script-src, img-src, font-src |
<LANDING_HOST> |
Web Component widget — the bundle, its env.js configuration, its images and its fonts are loaded from the OnAim host into your page. script-src covers both the bundle and env.js; if you would rather not allow the latter, define the gateway global yourself (7.2). |
img-src, media-src |
<ASSET_HOST> |
Widget — images, videos and GIFs uploaded in the admin panel are served from OnAim's file/CDN host, not from <LANDING_HOST> |
script-src, connect-src |
<GAME_HOST> |
Widget — promotions containing a game load the game as a script into the page. Blocked = the game silently never starts. |
frame-src, img-src |
https://www.youtube.com, https://img.youtube.com |
Widget — promotions containing a YouTube video component |
style-src, font-src |
https://fonts.googleapis.com, https://fonts.gstatic.com |
Web Component widget and floating widget — web fonts |
connect-src |
<GATEWAY_HOST> |
Promotion data, balances, player eligibility |
connect-src (WebSocket) |
wss://<GATEWAY_HOST> |
Real-time updates (balance, leaderboards) |
script-src, connect-src |
<WIDGET_HOST>, <WIDGET_API_HOST> |
Floating promotion widget (Section 8) — embed.js and its configuration script are served from <WIDGET_HOST>; the widget's own configuration API is a separate host from the gateway |
WebSockets must not be blocked. Leaderboards connect over a raw WebSocket with no HTTP fallback. If a corporate proxy or firewall blocks the upgrade, leaderboards silently fall back to slow periodic refreshes instead of updating live — this is a common cause of "leaderboard looks frozen" reports.
7.9 Troubleshooting
| Symptom | Likely cause |
|---|---|
| The page renders in Georgian. | No lang parameter / language attribute was passed — it defaults to ka (7.1). |
| Login / Register / Deposit buttons do nothing. | No message listener on your page (7.3). This applies to the widget embed too. |
| A dialog opens but the player cannot see it. | Neither scrollTo (1031, 7.3) nor host-viewport (1020, 7.7) is handled. If you do post host-viewport, check that iframeTop is rect.top + window.scrollY — posting the raw rect.top misplaces dialogs by your current scroll amount. |
| The page jumps to a dialog instead of opening it on the current screen. | That jump is the scrollTo (1031) fallback. Post host-viewport (1020, 7.7) and dialogs open centered on the player's visible screen with no scroll. |
| A pinned component scrolls away instead of staying fixed. | host-viewport (1020) is not posted, or is posted from a window other than the iframe's direct parent (7.7). |
| The player appears logged out despite passing a token. | Expired, reused or invalid OTT — generate a fresh one per embed (7.1). Rejected tokens fail silently. |
| The iframe stops growing and content is cut off. | Runaway-resize protection triggered, almost always from a viewport-relative iframe height (7.5). |
The Web Component widget renders nothing and the console shows an [env] error. |
The widget could not load env.js from <LANDING_HOST> — usually a script-src CSP rule (7.8). Define the gateway global yourself as a workaround (7.2). |
| Widget renders, but the game inside a promotion never starts, or images/videos are missing. | Your page's Content-Security-Policy is blocking the game script or the asset host (7.8). |
Nothing renders at all, and the iframe URL changes to /error. |
The promotion or landing page could not be loaded — the Smart Link slug may have been deactivated, or the promotionId / landingPageId values are wrong. Check with OnAim. |
| Blank area where the page should be, no error. | The embed URL is missing a valid target (no slug, and no promotionId + landingPageId), or the player is not eligible for this promotion. |
| Balances or leaderboards do not update live. | WebSocket traffic is blocked (7.8). |
8. Floating Promotion Widget
The floating widget is a small circular button that sits in the corner of every page of your site, follows the player as they browse, shows their current promotion balance, and opens the full promotion landing page in a dialog when clicked. It is a separate, self-contained product from the embeds in Section 7 — you install it once, site-wide, instead of placing a landing page on one specific page.
Each widget is created and configured in the OnAim admin panel (promotion, coin, landing page, trigger). The admin panel then gives you a ready-made snippet containing your widget id — copy it from the widget's Embed dialog.
8.1 Installing the widget
Choose one of the three snippets below — they are equivalent. All of them need your widget id and the player's One-Time Token (Section 2). Install the snippet on every page where the widget should appear, ideally in your global layout.
Method 1 — script tag
Simplest option for server-rendered sites. The widget creates its own container and attaches itself to the page.
<script
data-balance-widget
data-widget-id="YOUR_WIDGET_ID"
data-player-token="PLAYER_OTT"
data-lang="en"
src="https://<WIDGET_HOST>/embed.js">
</script>
Method 2 — custom element
Preferred for single-page applications: you control exactly where the element lives and can update its attributes as your app state changes.
<script type="module" src="https://<WIDGET_HOST>/embed.js"></script>
<minimal-widget
widget-id="YOUR_WIDGET_ID"
player-token="PLAYER_OTT"
lang="en">
</minimal-widget>
Method 3 — programmatic loader
Use when you cannot add markup directly, for example when injecting the widget from a tag manager.
(function () {
const s = document.createElement('script');
s.type = 'module';
s.src = 'https://<WIDGET_HOST>/embed.js?' + Date.now();
s.async = true;
s.setAttribute('data-balance-widget', '');
s.setAttribute('data-widget-id', 'YOUR_WIDGET_ID');
s.setAttribute('data-player-token', 'PLAYER_OTT');
s.setAttribute('data-lang', 'en');
document.body.appendChild(s);
})();
No configuration is required on your side. The widget loads its own environment settings from the OnAim host it is served from.
8.2 Attributes
| Attribute (element) | Attribute (script tag) | Default | Description |
|---|---|---|---|
widget-id |
data-widget-id |
— | Required. Copied from the widget's Embed dialog in the admin panel. |
player-token |
data-player-token |
— | Required. The player's One-Time Token (Section 2). Also forwarded to the landing page when the dialog opens, so the player stays signed in. |
lang |
data-lang |
en |
Language code, e.g. en, ka. |
progress-mode |
data-progress-mode |
cumulative |
How progress is displayed: cumulative or step. |
Changing lang or progress-mode updates the widget in place. Changing widget-id or player-token re-initialises it, including re-authenticating the player — so set a fresh token by updating the attribute rather than re-injecting the script.
8.3 Open / close events
The widget notifies your page when the promotion dialog opens and closes, so you can pause background video, hide your own overlays, or record analytics. Events carry { promotionId } in event.detail.
// Custom element (Method 2)
const el = document.querySelector('minimal-widget');
el.addEventListener('minimal-widget:open', (e) => console.log('opened', e.detail));
el.addEventListener('minimal-widget:close', (e) => console.log('closed', e.detail));
// Script tag (Methods 1 and 3) — the widget owns its container, so listen on document
document.addEventListener('minimal-widget:open', (e) => console.log('opened', e.detail));
document.addEventListener('minimal-widget:close', (e) => console.log('closed', e.detail));
8.4 What your page still has to handle
The dialog opened by the widget contains the promotion landing page, so the message listener from 7.3 is still required — login, register, deposit and open-link requests made from inside the dialog are delivered to your page exactly as described there. Add that listener once, globally, alongside the widget snippet.
The dialog is a self-sizing embed. The widget loads the landing page withembedMode=inner(7.1), because the dialog already has a fixed size. Two consequences: you never need to handleheight(1003) orscrollTo(1031) for the dialog, and — as in anyinnerembed — "scroll to section" buttons configured on that promotion will not work inside the widget dialog. Pick a landing page without them for this placement.
8.5 Behaviour and limitations
- Placement. The widget appears in the bottom-right corner and the player can drag it anywhere on the screen; its position is remembered. It stays within the visible area when the browser is resized.
- Style isolation. The widget renders inside a Shadow DOM, so your CSS cannot affect it and its CSS cannot affect your site.
- Eligibility. If the player is not eligible for the promotion, the widget renders nothing at all. A missing widget is expected behaviour, not an error.
- Single-page apps. The widget survives client-side navigation, and installing the same widget id twice is a no-op — it will not appear more than once.
- Live balance. The balance shown on the button updates in real time over a WebSocket; see the network requirements in 7.8, including the widget-specific hosts.
9. Promotion Hub (Global Pages)
A Global Page — also called a Hub Page — is a single page presenting all of your active promotions as one catalog, rather than one landing page for one promotion. It is embedded as an iframe, like Section 7.1, but it is served by a separate renderer with a smaller contract. Ask OnAim which host and landingPageId to use for your Global Page.
9.1 Embedding
<iframe
id="onaim-hub"
src="https://<HUB_HOST>/?landingPageId=574&lang=en&ott=80b6a17cc251"
style="width:100%; height:1200px; border:none;">
</iframe>
| Parameter | Required | Description |
|---|---|---|
landingPageId |
Yes | Global Page id (integer), provided by OnAim. There is no promotionId — a Global Page spans many promotions. |
lang |
Recommended | Language code, e.g. en, ka. Defaults to en here (not ka as in 7.1). |
ott |
No | Player One-Time Token (Section 2); one-time-token is accepted as an alias. Omit it to render the page for a logged-out visitor. Same single-use, no-refresh lifecycle as 7.1. |
Smart Link slugs and embedMode do not apply here. A Global Page is targeted by id only.
9.2 What differs from a promotion landing page
| Concern | Promotion landing page (Section 7) | Global Page (this section) |
|---|---|---|
| Embed shapes | iframe or Web Component widget | iframe only — there is no widget bundle |
| Height | Auto-height by default: the page posts height (1003) and you resize (7.5) |
No height messages are sent. Give the iframe a height you control, and re-check it on your own breakpoints. The page scrolls internally. |
| Messages to your page | 1001, 1002, 1003, 1011, 1012, 1031 |
Only login (1001), register (1002) and openTab (1011). No deposit, no height, no scrollTo. |
| Host viewport (7.7) | Optional; required for pinned components | Not used — the page has a real viewport of its own |
| Targeting | slug, or promotionId + landingPageId |
landingPageId only |
The message listener from 7.3 is still required — handling 1001, 1002 and 1011 is enough for a Global Page, and the same listener covers both embeds if you use them on one site.
9.3 Network requirements
Because a Global Page is iframe-only, your page's Content-Security-Policy only needs frame-src <HUB_HOST>. The renderer talks to the OnAim gateway from inside its own document. If a proxy filters outbound traffic, apply the connect-src rows of 7.8.