Oddin.gg Disir - Widgets documentation

Introduction

Oddin.gg’s Esports widgets, Disir, are the ultimate analytical companion to the odds feed. They bring together engaging facts and statistics meant to drive up interest in markets, by encouraging bettors to theorise, speculate and calculate around each individual match, while also acting as a one-stop solution for all relevant tournament information: fixtures, schedules, standings, and rosters.

Disir features all the depth and richness of established, community-favoured stats and news websites like hltv.org, dotabuff.com, or lol.fandom.com, but is integrated close to the odds, without users ever having to leave your website.

Data quality and freshness are ensured - we process raw data sources closest to the game publishers and update the data as soon as match replays are available.

Currently, Widgets come in the Prematch bundle featuring historical statistics for the two match competitors (with components: Team stats, Player stats, and Tournament stats), and as Live widgets, featuring real time data for the ongoing map. The Team stats, Player stats, and Tournament stats are all collected under the match widget endpoint (/statistics/match/:id), while the Tournament stats component can also be loaded separately by accessing the tournament widget endpoint (/statistics/tournament/:id). The live scoreboard Widget is available at the /live/scoreboard endpoint.

1. Supported Esports and eSimulators

2. iFrame integration

Widgets behave as iFrame elements within HTML. We created a REST API that will prepare URL addresses for each widget - the returned URL address is used as src in the iFrame.

2.1. Usage

Call the REST API from your backend to receive the URL address of the widget. The address from the API response (JSON format) should then be used as src value in the iFrame element. Subscribe to the iFrame events to resize the iFrame and eliminate the scrollbar in the widget.

ℹ The match widget URL itself will not expire. However, in the case of older matches, it might not load anything if one of the teams has stopped being active (~3 month time-frame).

2.2. Domain whitelisting

Every domain where the Widgets will be running needs to be whitelisted on the Oddin.gg side, including the domains used for staging/integration purposes. At the start of the Widgets integration process, you should list all such domain URLs and send them to Oddin.gg integration support.

2.3. Recommended width

The minimum recommended width for both live and prematch widgets is at least 360px, with a minimal "usable" at 320px. Beyond this, readability cannot be ensured.

2.4. Referrer policy

For maximum compatibility with all possible Widget integrations (mobile, web…), we recommend to add the referrerpolicy attribute with the value "no-referrer-when-downgrade" to your iFrame element displaying the Widgets:

<iframe src="..." referrerpolicy="no-referrer-when-downgrade" ...></iframe>

3. REST API

This chapter provides a complete reference to the REST API. Here you will find the description of all methods and other necessary information required to interact with the REST API.

Additional parameters:

• All responses use JSON format.
• All requests are without body.

3.1. Authentication

The REST API is secured via a brand token. You should receive your brand token from our support. If the token is not working, or you still need to obtain it, please contact us at support@oddin.gg. Please note that you need a different access token for each environment, and then you need to supply the access token in each request in the header - “x-brand-token”.

3.2. Available endpoints

The REST API offers the following endpoints:

<env> takes the values:

• integration - for the Integration environment
• main - for the Production environment.

We currently provide two different environments - Production and Integration. The Production environment is intended to be used only when you are finished with integration and ready to go live. Please use the Integration environment for all development and testing purposes. You can select the environment by providing a different parameter in the URL for the REST calls.

3.2.1. Match endpoint

3.2.1.1. Query parameters

3.2.1.2. Response body

3.2.2. Tournament endpoint

3.2.2.1. Query parameters

3.2.2.2. Response body

3.2.3. Live scoreboard endpoint

3.2.3.1. Query parameters

3.2.3.2. Response body

3.3. Error response

The HTTP response code will be the same as in the JSON body.

We use the standard HTTP response codes. Please check the next table for a description of statuses used:

REST API response codes

4. Events

iFrame widgets are reporting events via the Window.postMessage() method.

4.1. Subscribe to events

You should listen to the message events on the window - the iFrame is sending serialised JSON objects with a type property.

TypeScript code example

function subscribeToEvents(
 iframe: HTMLIFrameElement,
 onMessage: (event: WidgetEvent) => void,
 onError?: (err: Error) => void
) {
 const handleMessage = (e: MessageEvent) => {
   if (e.source !== iframe.contentWindow) {
     return
   }

   try {
     const message = JSON.parse(e.data)

     if (message && typeof message.type === 'string') {
       onMessage(message)
     }
   } catch (e) {
     onError?.(e)
   }
 }

 window.addEventListener('message', handleMessage)

 return () => window.removeEventListener('message', handleMessage)
}

4.2. Available events

type EventLoaded = {
 type: 'LOADED'
}

type EventDataAvailability = {
 type: 'DATA'
 available: boolean
}

type EventClose = {
 type: 'CLOSE'
}

type EventResize = {
 type: 'RESIZE'
 height: number
}

type EventScrollTop = {
 type: 'SCROLL_TOP'
}

type WidgetEvent = EventLoaded | EventClose | EventResize | EventScrollTop

Events

4.3. Example use: prematch widget

const unsubscribe = subscribeToEvents(
 iframeInstance,
 (event) => {
   switch (event.type) {
     case 'RESIZE':
       iframeInstance.style.height = `${event.height}px`
       break
     case 'CLOSE':
       destroyInstance()
       break
     case 'LOADED':
       setLoading(false)
       break
     case 'SCROLL_TOP':
       syncScrolling()
       break
   }
 },
 (err) => {
   // Error
 }
)

4.4. Example use: live widget

The addresses for live widgets are generated even without data, so the frontend can load the widget in advance and wait for data availability. For the best user experience, we recommend hiding the widget initially, and then revealing it only when the data becomes available. The data can be lost during the match, sending the widget into an Empty state (“Live stats not available” screen). Clients have the option to display this screen, or the widget can be hidden until the data becomes available again.

iframeInstance.style.display = 'none'
const unsubscribe = subscribeToEvents(
 iframeInstance,
 (event) => {
   switch (event.type) {
     case 'RESIZE':
       iframeInstance.style.height = `${event.height}px`
       break
     case 'DATA':
       iframeInstance
.style.display = event.available ? 'block' : 'none'
       break
   }
 },
 (err) => {
   // Error
 }
)