OnAim Integration Guide

1. Introduction

Your system sends player activity events (such as Bet, Win, Registration, Deposit, or custom-defined events) to OnAim in real time.

OnAim processes these events according to your promotion’s configuration — awarding coins, filling progress bars, updating leaderboards, unlocking prizes, and more.

Players access promotions through a Promotion Landing Page, which you embed into your platform via an iframe, allowing a seamless in-platform experience.

To ensure smooth integration:

• Player identification must be secure and verified.

• Events must include the required fields.

• Specific backend endpoints must be available for player info and coin withdrawals.

Note: OnAim operates as a single-tenant platform. Each partner has a dedicated, isolated environment for event ingestion, data processing, and player interactions.

---

2. Event Integration

2.1 Supported Integration Methods

Note: These values are indicative and may vary based on deployment and load. Each tenant can request customized throughput limits.

2.2 Dynamic Event Schema

Only the following three fields are mandatory:

{
  "customerId": "string",
  "eventType": "string",
  "timeStamp": "string (ISO 8601, UTC recommended)"
}

All other fields are free and flexible — you can include any additional data relevant to your use case.

These fields can be:

• Shared properties, such as `deviceType`, `promotionId`, `country`, or `sessionId`

• Event-specific properties, such as `amount`, `gameName`, or `RefereeId`

UTC Time: Timestamps should be provided in UTC. Non-UTC values are accepted but can result in misaligned reporting and aggregation windows.

If an event is missing any of the three required fields (`customerId`, `eventType`, `timeStamp`):

• The event will be rejected and logged in the ingestion service.

• Logs will contain the tenant ID, malformed payload, and timestamp for traceability.

There is no restriction on additional data — OnAim automatically flattens all properties for processing. You can extend event structure anytime without redeploying backend code.

2.3 Example Event

{
    "customerId": "P_123456",
    "eventType": "Bet",
    "timeStamp": "2025-05-23T10:16:58.980Z",
    "deviceType": "Mobile",
    "gameName": "Roulette",
    "gameType": "Table",
    "amount": 100,
    "currency": "USD"
}

• `customerId`, `eventType`, and `timeStamp` are mandatory.

• `deviceType` and `promotionId` are shared fields.

• `gameName`, `gameType`, `amount`, and `currency` are custom properties.

• The structure is flat — all properties are accessible in the Admin Panel once described in the schema.

2.4 Schema Description for Admin Panel

This schema can be defined via:

• UI configuration in the OnAim Admin Panel

The schema describes all fields and expected types. Once registered, OnAim automatically generates UI elements (filters, dropdowns, numeric inputs) for building conditions and analytics.

{
  "customerId": "string",
  "eventType": "Bet | Win | Registration | Deposit | CustomEvent",
  "timeStamp": "2025-05-23T10:16:58.980Z",
  "deviceType": "Mobile | Desktop | Tablet | Other",
  "customProperties": {
    "Bet": {
      "gameName": "string",
      "gameType": "string",
      "amount": 100,
      "currency": "USD"
    },
    "Win": {
      "gameName": "string",
      "value": 250,
      "coinId": "FreeSpin"
    },
    "Registration": {
      "RefereeId": "string",
      "RegistrationDate": "2025-05-23T10:16:58.980Z"
    }
  }
}

Schema Description Rules

---

3. Promotion Page Integration (Iframe + OTT Authentication)

3.1 Base URL

https://[onaim-landing].io/?promotionId=752&lang=ka&landingPageId=574

3.2 Secure Player Identification (OTT Token)

https://[onaim-landing].io/?promotionId=752&lang=ka&landingPageId=574&ott=80b6a17cc251

OTT Requirements

<iframe src="https://[onaim-landing].io/?promotionId=752&lang=ka&landingPageId=574&ott=80b6a17cc251" width="100%" height="800" frameborder="0" allowfullscreen></iframe>

---

4. Player Info Endpoint

There is no strict requirement to use the OTT-based flow. The endpoint can be implemented in any form that your system supports, as long as OnAim can uniquely identify the player and retrieve accurate player details.

For example:

• You can use the previously described OTT flow for higher security.

• Or, you can expose a direct authenticated endpoint that takes any identifying token, or session key to resolve the player.

The only requirement is that your endpoint must reliably return the correct player information based on the identifier provided by OnAim.

Example Request

GET https://[yourdomain].com/onaim/player?token={ANY_UNIQUE_IDENTIFIER}

Example Response

{
  "PlayerId": "P_123456" , 
  "UserName": "JohnDoe",
  "Email": "[email protected]",
  "Country": "GE",
}

4.3 Field Mapping

{
  "FieldMappings": {
    "default": {
      "PlayerId": "YOUR_PLAYER_ID_PROPERTY", 
      "UserName": "YOUR_PLAYER_NAME_PROPERTY"
    }
  }
}

---

5. Coin Withdrawal Endpoint

All withdrawal options — endpoint URL, HTTP method, headers, query parameters, and body mappings — are fully configured in the OnAim Admin Panel UI.

5.1 Example Configuration

{
  "endpointUrl": "https://api.yourdomain.com/onaim/withdraw",
  "method": "POST",
  "headers": {
    "Authorization": "Bearer {API_KEY}"
  },
  "body": {
    "playerId": "{PlayerId}",
    "amount": "{Amount}", 
    "currency": "{Currency}", 
    "transactionId": "{TransactionId}"
    }
}

5.2 Response Requirements & Behavior

5.3 Retry and Rollback Policy

• If idempotency is implemented on your side (using `transactionId` as a unique key):

• OnAim may safely retry failed or timed-out requests.

• Retries will not create duplicate transactions.

• You may also roll back or reconcile failed attempts safely.

• If no idempotency mechanism exists:

• OnAim will send the withdrawal request once.

• If it fails or times out, the transaction will be marked as failed in Admin.

• Manual review or reprocessing will be required.

Recommendation: Always implement an idempotent withdrawal endpoint that can detect duplicate `transactionId` values. This enables safe automatic retries and prevents payout duplication.

---

6. Security & Best Practices

• Always use HTTPS for all communications.

• Generate OTTs server-side only.

• Limit OTT validity to 1 minute or less.

• Always provide timestamps in UTC for consistent analytics.

• Validate every event payload for the three required fields.

• Use idempotency keys to prevent duplicates in withdrawals and event ingestion.

• Implement acknowledgment and retry mechanisms for message broker integrations.

• Regularly update your schema definition to expose new event fields.

• Consider adding monitoring dashboards to visualize event flow and error rates.