Skip to navigation
Embeds

Embeds

Live scoreboards and score lists you add to a page with a script tag.

Embeds are live widgets that Statpad renders and keeps up to date. You add a script tag and an element to your page, and your readers see the score, clock and last play change while they read. There’s no server to run, no API call to make and no polling code to write.

There are two elements:

  • <statpad-scoreboard> shows one game, compact or expanded.
  • <statpad-scores> shows a league’s games for a day or a week, as a list or a strip.

For a mobile app, or a site that can’t run scripts, the same widgets come as hosted pages that you load in a WebView or an iframe.

What’s included

Embeds come with every plan that has active access, the Pro trial included. Widget traffic doesn’t count toward your request allowance, your request rate or your stream connections. Statpad counts one view each time a widget loads, and the Embeds page of your account shows this period’s views. Views aren’t capped.

Embeds cover football and basketball today: nfl, ncaaf, nba, ncaab and wnba. A widget can show any of those leagues your account holds. Leagues has the details.

Embed keys and API keys

Widgets load with an embed key, not an API key. The two work differently:

Embed keyAPI key
Starts withstatpad_pk_sporty_
SecretNo. It sits in your page’s HTML.Yes. Keep it on your server.
Works onThe embed widgets only/v1 and the stream
Where it worksOnly on the origins you list for itAnywhere
Uses your allowanceNoYes
Per account5 active keys, on every planDepends on the plan

An embed key never works on /v1 or the stream, so publishing it gives nobody access to your API. If someone copies your script tag to their own site, their visitors’ browsers send that site’s origin, and the widget answers origin_not_allowed.

Each embed key takes 1 to 10 origins. Revoked keys don’t count toward the 5.

Quickstart

This puts a live NFL scoreboard and the week’s NFL scores on a page. It takes about five minutes.

1

Create an embed key

Sign in at app.statpad.dev, open Embeds and choose Create embed key.

  1. Give the key a name that says where it runs, such as blog.
  2. Under Origins, list each site the widgets will run on, as the browser’s address bar shows it: https://example.com. Add https://*.example.com for its subdomains, and http://localhost:3000, with your port, while you build.
  3. Leave Iframes on these sites and Mobile apps off. You need them only for hosted pages.

The Embeds page keeps showing the key, because it isn’t a secret. Origins lists which origins a key accepts.

2

Add the script

Add the loader once per page, with your embed key in data-key:

<script type="module" src="https://embed.statpad.dev/v1/embed.js" data-key="statpad_pk_..."></script>

Keep type="module". The loader is an ES module, so a script tag without it doesn’t run. The loader fetches each widget’s code only when the page has that widget, including widgets your app adds after the page loads.

3

Add a scores list

A scores list needs only the league:

<statpad-scores league="nfl"></statpad-scores>

With no date, NFL and NCAAF show the current football week, and every other league shows today. Live games come first under Live, then the rest under a heading for each day, in the reader’s time zone.

4

Add a scoreboard

A scoreboard shows one game, so it needs the game’s id:

<statpad-scoreboard league="nfl" game="GAME_ID"></statpad-scoreboard>

Game ids are the same as in the REST API. There are two ways to get one:

  • From the scores list. Picking a row fires statpad-select with the game’s id. Log it, then click the game you want:

    <script>
    addEventListener("statpad-select", (e) => console.log(e.detail.league, e.detail.game));
    </script>
  • From the REST API. List a day’s games with GET /v1/{league}/games, as in Find a game, and copy the game’s id.

Replace GAME_ID with the id. A scoreboard is compact in a container narrower than 380px and expanded from 380px up.

Open the page. The widgets show a loading state for a moment, then the games. While a game is live, the widgets check for changes about every 4 seconds and mark each change with your accent colour. Before games start they check every 30 seconds, and once games are final every 60.

If a widget shows Not available on this site, the page’s origin isn’t on the key. Check the address bar: https://www.example.com and https://example.com are different origins. States and messages lists every message a widget can show and what to do about each.

A full page

This page lists the week’s NFL games and shows the one a reader picks in the scoreboard above them. Until a reader picks one, the scoreboard shows Widget not set up, so it starts hidden:

index.html
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<script type="module" src="https://embed.statpad.dev/v1/embed.js" data-key="statpad_pk_..."></script>
</head>
<body>
<statpad-scoreboard league="nfl" hidden></statpad-scoreboard>
<statpad-scores league="nfl" layout="list" max="8"></statpad-scores>
<script>
const board = document.querySelector("statpad-scoreboard");
addEventListener("statpad-select", (e) => {
board.setAttribute("league", e.detail.league);
board.setAttribute("game", e.detail.game);
board.hidden = false;
});
</script>
</body>
</html>

A widget follows changes to its attributes, so setting game switches the scoreboard to that game.

To try it on your machine, add http://localhost:3000 to the key and serve the folder on that port, for example with npx serve -l 3000. Opening the file directly doesn’t work, because a file:// page has no origin to allow.

If your site sends a Content-Security-Policy, allow https://embed.statpad.dev in script-src for the loader and https://live.statpad.dev in connect-src, where the widgets read their data.

Next