Embedding the live animation widget

Situation labels, the trail and attack zones exist in 2.5D only; 3D shows the pitch and the players, and those three modules switch off by themselves. In 3D the ball and the events are live data; player movement is simulated on the server from the ball position, the situation and the events, so every viewer sees the same picture, but it is not real tracking data. Modules and templates depend on your plan; what this endpoint returns is what you can use: /api/v1/widget/options

1. Get access: ask sales to enable the animation widget and to register the domains allowed to embed it (for example *.example.com), the views you may use and the concurrent viewer limit. Once enabled, your API key can call /api/v1/widget/*.
2. Configure: in the widget console choose the view, template, style, data modules and layout, with a live preview of a real match on the right; saving and publishing gives you a configuration id (starting with wgt_).
3. Exchange a token: your server calls POST /api/v1/widget/tokenwith its API key, the configuration id and the origin of the embedding page, and gets a token valid for 2 hours by default. The API key stays on the server; never put it in a page or an app package.
4. Embed: put an iframe in the page with the address /widget/anim?cfg=<configuration id>&match=<match id or auto>&token=<token>. match is the platform's match id; auto picks a popular match in play.
5. Transport: the widget receives live data over SSE by default; add &transport=ws to the address for WebSocket (it falls back to SSE when that cannot connect). The content is the same either way; the player movement frames of the 3D view come with it, about 10 frames a second.

No server of your own? See App Key embedding below. For Flutter, iOS and Android apps, see SDKs and client libraries →

① Exchange a token on your server

curl -X POST https://api.sports.csap.ai/api/v1/widget/token \
  -H "X-API-Key: $API_KEY" -H "Content-Type: application/json" \
  -d '{"config":"wgt_1a2b3c4d","origin":"https://www.example.com","ttl":7200}'
# → {"code":0,"data":{"token":"…","expires_at":1794240000,"embed_url":"/widget/anim?cfg=wgt_1a2b3c4d&token=…"}}

② Embed in the page (your server hands out the token)

<iframe id="live-anim" style="width:100%;height:640px;border:0" allow="autoplay; fullscreen"
  src="https://api.sports.csap.ai/widget/anim?cfg=wgt_1a2b3c4d&match=auto&token=<token>"></iframe>
<script>
  // the widget tells the page how tall it needs to be
  addEventListener('message', (e) => {
    const f = document.getElementById('live-anim');
    if (e.source === f.contentWindow && e.data && e.data.type === 'anim-widget-size') f.style.height = e.data.height + 'px';
  });
</script>

In the console under “Live animation widget → App Keys”, create an App Key (it starts with pk_) and enter your website’s domains. It can only load the widget — it can’t call data endpoints — so it may sit in your page source. The page passes a match ID and it plays; no token-exchange server is needed. Create an App Key in the console →

① iframe: paste one snippet

<!-- The App Key may sit in your page source; it only plays on allowlisted domains -->
<iframe src="https://api.sports.csap.ai/widget/embed?app_key=pk_3f9a…&match=4651805&view=3d"
        style="width:100%;aspect-ratio:16/9;border:0" allow="autoplay; fullscreen"></iframe>

② Script: sizes itself and turns goals / full time into page events

<!-- The script creates the iframe where it sits -->
<script src="https://api.sports.csap.ai/widget/embed.js" data-app-key="pk_3f9a…"
        data-match="4651805" data-view="2.5d" async></script>
<script>
  document.addEventListener('animwidget:goal', (e) => console.log('Goal', e.detail.score));
  document.addEventListener('animwidget:end', (e) => console.log('Full time', e.detail.score));
  document.addEventListener('animwidget:error', (e) => console.warn(e.detail.reason)); // why it could not play
</script>

Parameters

Page events of the script embed (listen on document; data is in e.detail)

How an App Key stays safe

③ Signed mode: sign on your server (Node.js example)

const crypto = require('crypto');
const secret = process.env.WIDGET_APP_SECRET;        // keep the App Secret on your server
const match = '4651805';
const exp = Math.floor(Date.now() / 1000) + 3600;    // expiry (Unix seconds), at most 7 days ahead
const sig = crypto.createHmac('sha256', secret).update(match + ':' + exp).digest('hex');
// write exp and sig into the page:
// https://api.sports.csap.ai/widget/embed?app_key=pk_3f9a…&match=${match}&exp=${exp}&sig=${sig}

Refusal reasons (the code on the “unavailable” notice, the X-Widget-Refused response header, and reason in animwidget:error)

The widget tells the embedding page through postMessage (sent for token embeds and App Key embeds alike; with the script embed, the script handles them for you and turns them into animwidget:* page events):

• A token is bound to a configuration and an origin; the widget page may only be framed by that origin (response header Content-Security-Policy: frame-ancestors), so it does not work on another domain.
• Tokens last 2 hours by default and 24 hours at most; when one expires the widget asks for a refresh, and the page simply asks your server for a new token.
• When the number of concurrent viewers passes your limit, newly opened widgets get 429.
• When the widget is turned off or the organization is suspended, both ways of embedding stop: new loads are refused, and pages that are playing stop within seconds and show a notice.
• For a match without animation data (not started, finished, or no animation for this match) the widget does not wait in vain: the score bar shows the real score and the stage says "not started / finished / no animation data".
• A configuration takes effect once published; after changing the view, template or layout, publish again and embedded pages show it after a reload.