Hosted pages
A hosted page is one widget on a page of its own, served by Statpad at embed.statpad.dev. Use one where the script tag can’t go:
- In a mobile app, load it in a WebView.
- On a site whose editor strips scripts, such as some CMSes, put it in an iframe.
On a site that can run scripts, use the script tag instead. It sizes itself, uses your page’s font and needs no extra settings on the key.
URLs
The query string takes key and the element’s attributes:
Replace GAME_ID with a game’s id, which you get the same way as for the script tag: from a scores page’s statpad:select message (Messages), or from GET /v1/{league}/games in the REST API. Encode the # of an accent as %23. Otherwise the browser reads the colour as the URL’s fragment and the widget gets no accent. The page renders the widget edge to edge in the system font.
The Embeds page of your account builds these URLs for each key under Mobile apps and iframes.
Turn them on for a key
A key serves hosted pages only where you allow them. Edit the key on the Embeds page and turn on one or both switches under Hosted pages:
With both off, no load is allowed. A change reaches new page loads within a few minutes.
Apps send no origin that Statpad can check. So with Mobile apps on, any app, or any browser tab opened at the URL, can show the key’s widgets, and the key’s origins don’t restrict that. Its widgets show only what your pages already show publicly, and they cost you nothing but view-count accuracy. Use a separate key for your apps, so you can revoke it without touching your websites.
When a load isn’t allowed
What you see depends on where the page loads:
- In an iframe, the browser blocks the frame and shows its own blank or error frame instead of the widget. That happens when the framing site isn’t on the key’s origins, when Iframes on these sites is off, when the key is unknown or revoked, and when Statpad can’t look the key up. Statpad sends every refusal with a policy that forbids framing it, so no text shows.
- Top-level, in an app’s WebView or a browser tab, you get a short page of plain text:
To see why an iframe stays blank, check the browser console, which names the blocked frame. Opening the iframe’s URL in a browser tab shows the key’s problem, unless Mobile apps is off, in which case the tab shows the apps refusal instead.
A page that loaded is different: it shows the widget, and if a later check refuses it, the widget replaces the game with a message, such as Embed key revoked.
In an iframe
The page must be framed by one of the key’s origins. In a page nested inside another frame, every frame above it must be on the key’s origins too.
A site that can’t run scripts can’t resize the frame, so give it a fixed height:
Where your page can run a script, size the frame to its content with the statpad:height message:
Referrer-Policy
A framed page checks which sites are framing it, and a restrictive referrer policy on a framing page can hide that page’s origin. Most browsers tell the widget every frame above it, but they can hide a frame’s origin when that frame sends Referrer-Policy: no-referrer or same-origin, and the check then fails with Not available on this site. A browser that lists no frames leaves the widget only the referrer, the address of the page directly above it. There, the same policies, or an iframe with referrerpolicy="no-referrer", leave the widget unable to name the site, and it shows Not available on this site with the line “This page can’t confirm which site is embedding it, so it can’t check that site is allowed.”
To fix it, send a policy that keeps the origin, such as the browser default, strict-origin-when-cross-origin, on the pages that frame the widget, and don’t set referrerpolicy on the iframe. Or use the script tag, which doesn’t depend on the referrer.
Messages
A hosted page tells whatever hosts it what’s happening, with three messages:
A statpad:select, with the recorded Bills at Vikings game from Sample responses. That id belongs to the sample data, so it won’t load in a widget:
state is the game’s widget state, such as live or final.
Each message goes to every listener that’s there:
In an app with a listener, tapping the link sends statpad:open and the page doesn’t navigate, so your app can open the URL in the browser. In an iframe, or in an app with no listener, the link opens as usual. The link is https://statpad.dev/ with a query string.
In a mobile app
Turn on Mobile apps for the key, then load the hosted page’s URL in a WebView and listen for the messages.
Give the widget a WebView of its own, and keep it on https://embed.statpad.dev. Anything a page in that WebView can run can call your listener, so the examples below:
- refuse navigation to any other origin, so no other content loads there
- accept messages only from
https://embed.statpad.dev - open a
statpad:openURL only when it’shttpsonstatpad.dev
On Android, WebViewCompat comes from the androidx.webkit:webkit library. Unlike addJavascriptInterface, its listener exposes StatpadAndroid only to pages from the origins you name. Add it before loadUrl, because it applies from the next page load. shouldOverrideUrlLoading doesn’t see the URL your app loads, so the helper builds that URL rather than taking one: webView.showStatpad("statpad_pk_...", "scoreboard", mapOf("league" to "nfl", "game" to gameId)).
In React Native, flex: 0 lets the height take effect. originWhitelist={["*"]} hands every navigation to onShouldStartLoadWithRequest, which allows only the hosted pages. With a narrower whitelist, the WebView would open a URL outside it with Linking.openURL before your check runs. A message’s url is the page’s origin on Android and its full address on iOS, so onEmbed accepts both.
height is in CSS pixels. iOS points and React Native’s layout units match them, and Android multiplies by the screen density, as above.
When the key changes
A hosted page that’s already open asks again every 2 minutes, and whenever it’s shown after being hidden, whether the key still allows it there. So revoking the key, removing the site’s origin, or turning off the switch the page relies on stops open pages within a few minutes. The page then shows why, such as Embed key revoked, or Not available on this site with a line saying which switch to turn on. A page stopped this way needs a reload after you fix the key.
If those checks can’t reach Statpad at all, the page keeps working for 10 minutes, then shows Score unavailable.