Your first widget

Choose a widget, copy its embed, then make it your own.

1. Open the widget catalog and choose the view you need. Use the builder to select a team, league, competition or match.
2. Sign in and select a developer plan when required. Copy the finished embed code, including its token, iframe class and sizing script.
3. Paste the embed into an HTML block on your site. For a native WebView, use the widget URL and configure the host app to support video and fullscreen.
4. Adjust only the preferences supported by that widget. Test on mobile and with the same account token you will use in production.

<iframe id="football-widget"
  title="Football scores"
  src="https://www.scorebat.com/embed/livescore/?token=YOUR_EMBED_TOKEN"
  style="display:block;width:100%;height:760px;border:0"
  allow="autoplay; fullscreen"
  allowfullscreen>
</iframe>

How preferences work

Four different kinds of setting, with different scopes.

The URL parameter is pref, singular. It contains URL-encoded JSON, not Base64. Use booleans true and false, not strings such as "true". Unknown keys are not a supported customization mechanism.

const url = new URL("https://www.scorebat.com/embed/standings/team/chelsea/");
url.searchParams.set("token", "YOUR_EMBED_TOKEN");
url.searchParams.set("pref", JSON.stringify({
  language: "en",
  tableview: "nearby",
  tableneighbors: 2,
  nomaxwidth: true
}));
// URLSearchParams performs the URL encoding once.
const iframe = document.querySelector("#football-widget");
iframe.src = url.toString();

When editing an existing URL, parse its pref JSON, change the keys you need, then serialize it again. Do not concatenate unescaped JSON or encode an already encoded value a second time.

A preference may be parsed successfully but have no effect if the selected widget does not consume it. Each widget section below lists the supported preferences and important exceptions.

Find the right content

Use real selections from the builder; keep the entity type.

Team and tournament routes use the identifiers emitted by the builder. Slugs such as chelsea or england-premier-league are readable examples; do not create identifiers by lowercasing a display name. Match routes require a match identifier from the match picker or an existing returned matchviewUrl.

A competition identifies an individual competition or stage. A league groups related competitions. The unified picker chooses the appropriate type; league and competition are not interchangeable.

The World Cup builder is a preset over the same league, score-bar, video-panel and match widgets. Use the current builder’s selection rather than an old tournament alias.

Responsive sizing

Match the helper script to the widget.

<iframe title="Football widget"
  class="_scorebatEmbeddedPlayer_"
  src="https://www.scorebat.com/embed/team/chelsea/?token=YOUR_EMBED_TOKEN"
  allow="autoplay; fullscreen" allowfullscreen
  style="display:block;width:100%;height:760px;border:0"></iframe>
<script src="https://www.scorebat.com/embed/embed.js?v=arrv"
  id="scorebat-jssdk"></script>

<iframe title="Football videos"
  class="_scorebatEmbeddedPanel_"
  src="https://www.scorebat.com/embed/videopanel/?token=YOUR_EMBED_TOKEN"
  allow="autoplay; fullscreen" allowfullscreen
  style="display:block;width:100%;height:800px;border:0"></iframe>
<script>
  window.SCOREBAT_OPTIONS = {
    panelClassName: "_scorebatEmbeddedPanel_",
    panelSizing: "responsive"
  };
</script>
<script src="https://www.scorebat.com/embed/panelx.js?v=f4fksn"
  id="scorebat-paneljs"></script>

Load each helper once per page after the iframe elements it should manage. Keep the matching iframe class. In a client-rendered app, mount the iframe elements before inserting the helper; do not assume a script string placed into HTML will execute.

Score bars use their fixed strip height. For fixed-size panels or other fixed-height embeds, omit automatic sizing and set the iframe dimensions in CSS. Internal nomaxwidth does not resize the iframe.

Colors, access & account settings

Keep instance preferences separate from saved settings.

The builder saves background color as the account’s ui.color setting and score-bar color as ui.barColor. It may also add a background-color style to the iframe. Putting color or barColor inside pref does not set the widget’s internal theme.

Saved colors are account-wide and require the applicable customization entitlement. Changing them can affect other embeds using the same account. The builder preview can show demo styling; validate the exported embed with your actual token.

Hiding a content header with noheader requires active ad-free access. Removing branding is a separate entitlement. Preferences cannot unlock paid features, remove plan restrictions or force unavailable AI content.

Eligible accounts can configure match, team, league and competition navigation URLs in their account settings. These are saved link preferences, not arbitrary pref keys. Keep the builder’s standard navigation unless you have configured and tested a custom integration.

Ad-free widget/player loads share the developer allowance with billable Video API calls. A billable API call consumes five credits and an ad-free widget/player load consumes one. Check your active plan and usage in your account; exceeding the allowance can restore free-plan restrictions.

Tabs & custom navigation

Initial tabs and custom destinations use separate configuration.

Full match, team, league and competition widgets can open on a selected tab. tab is a separate query parameter, not a key inside pref. It requires active ad-free access; the requested tab must also be available for the selected content.

const url = new URL("https://www.scorebat.com/embed/team/chelsea/");
url.searchParams.set("token", "YOUR_EMBED_TOKEN");
url.searchParams.set("tab", "fixtures");
url.searchParams.set("pref", JSON.stringify({language: "en", nomaxwidth: true}));

Custom navigation bases are saved account preferences: matchviewUrl, teamUrl, competitionUrl and leagueUrl. Where supported, the widget appends the selected identifier and a trailing slash to the configured base. Use a base ending in a slash, and make sure the destination handles that route.

When opening a configured custom popup, the widget normally adds sbprf containing URL-encoded JSON with the current language. Your destination can read that parameter and pass the supported language into its own widget. It is not a copy of every source preference.

Custom-domain setup

Keep visitors on your website when they open matches, competitions, leagues and teams. Available with Advanced and Enterprise.

This feature connects widget links to pages you host. It does not move ScoreBat services to your domain or require a DNS change. Your server must render the appropriate widget at every supported URL.

1. Create one host page containing the loader below. Replace YOUR_EMBED_TOKEN with your own embed token from the builder.
2. Configure internal rewrites so each supported path serves this page while keeping the original URL and query string in the browser.
3. Test real match, competition, league and team URLs before activating your account-wide links.
4. In Account, open Developer settings and enter the base URLs. Review the changes, confirm that you tested the pages, and save. Links take effect immediately after a successful save; no manual approval is required.

<script>
window.SCOREBAT_OPTIONS = {
  embedToken: "YOUR_EMBED_TOKEN",
  baseDir: "/"
};
</script>
<script src="https://www.scorebat.com/embed/embedx.js?v=vh2"></script>

The shared loader expects matchview, competition, league and team path names. A path such as /match/123/ needs your own routing logic that maps it to the matchview embed; renaming the URL alone is not enough.

RewriteEngine On
RewriteRule ^(?:matchview|competition|league|team)/[^/]+/?$ popup.html [L]
# Place popup.html at the website root.
# Keep these rules before a general application catch-all.

location ~ ^/(matchview|competition|league|team)/[^/]+/?$ {
    rewrite ^ /popup.html last;
}
# Serve /popup.html as an existing static file in this server.
# Adapt this example to your application routing before reloading Nginx.

For a subdirectory such as /football/, use baseDir: "/football/", route /football/matchview/... and the other three paths to the shared page, and save base URLs with the same /football/ prefix. Preserve query parameters, including sbprf, which carries navigation preferences.

The loader can update the host page title. Set noTitle: true in SCOREBAT_OPTIONS if your website manages its own title. Use real identifiers from the builder; placeholders are not valid content.

WordPress setup

Serve the same WordPress page at each widget route.

1. Create a WordPress page for your widget host and add the shared host-page script from the previous section. Use your own embed token.
2. Find the page ID in the editor URL, then replace 123 in the example below. Put the code in a small site plugin or your child theme, not in a parent theme that updates may overwrite.
3. Save Settings → Permalinks once after adding or changing the rewrite rules. Do not flush rewrite rules on every request.
4. Open real URLs for all four content types and confirm that the correct widgets load before saving your base URLs in Account.

<?php
// Put this in a small plugin or child theme functions.php.
// Omit the opening PHP tag if the file already has one.
function scorebat_custom_widget_routes() {
    $page_id = 123; // Replace with your widget host page ID.
    add_rewrite_rule(
        '^(matchview|competition|league|team)/[^/]+/?$',
        'index.php?page_id=' . $page_id,
        'top'
    );
}
add_action('init', 'scorebat_custom_widget_routes');

Some WordPress roles, editors and hosting platforms strip script tags from Custom HTML blocks. If the loader disappears, have your developer add it through a trusted site plugin or page template, only on the widget host page. Check your caching, redirect and security plugins if deep links fail.

For WordPress installed in a subdirectory, set baseDir to the installation path with a trailing slash. Rewrite patterns are relative to that installation; account base URLs must include the same prefix.

Test and activate your links

A saved URL is not proof that your website is ready. Test first, then confirm the account-wide change.

1. Visit one real URL for each configured content type. Confirm the correct widget appears, then refresh the page and open it in a new browser tab.
2. Check mobile layout, widget height and navigation between content types. Keep the original deep-link URL visible; do not redirect every request to popup.html or the WordPress page slug.
3. Make sure HTTPS works and your server preserves the query string. Check browser errors if a content security policy blocks ScoreBat scripts or iframes.
4. Save in Account after confirming the setup. Click through from a widget using the same account token to verify the activated destinations.
5. To restore ScoreBat destinations, clear the relevant base URLs or choose Use ScoreBat links, then review and save again.

These colors are shared by every eligible widget using your account token, including widgets you have already published.

Custom-domain editing requires an active Advanced or Enterprise subscription. Other developers can see the controls and upgrade. Existing configured links are preserved. Contact ScoreBat if you need help with a setup that does not fit these examples.

Choose your widget

Each reference lists its own supported preferences, defaults and exceptions.

Use the family filter below to find the widget you are embedding. Shared parameter names can have widget-specific effects; a preference is supported only where listed. Advanced routes are marked when they do not have a dedicated builder preset.

Livescore

Scores, fixtures and results across competitions.

/embed/livescore/

Supported preferences

Defaults describe bare URLs. Only use preferences listed for this widget.

const url = new URL("https://www.scorebat.com/embed/livescore/");
url.searchParams.set("token", "YOUR_EMBED_TOKEN");
url.searchParams.set("pref", JSON.stringify({
  "limitwidth": true
}));
// Replace route placeholders with your builder selection.
// Use this URL as the iframe src with the sizing setup above.

Score bar

A horizontal score strip for all matches, a team, or a tournament.

/embed/livescore-bar/
/embed/livescore-bar/team/{team}/
/embed/livescore-bar/competition/{competition}/
/embed/livescore-bar/league/{league}/

Supported preferences

Defaults describe bare URLs. Only use preferences listed for this widget.

const url = new URL("https://www.scorebat.com/embed/livescore-bar/");
url.searchParams.set("token", "YOUR_EMBED_TOKEN");
url.searchParams.set("pref", JSON.stringify({}));
// Replace route placeholders with your builder selection.
// Use this URL as the iframe src with the sizing setup above.

Full league

A full league view combining related competitions, matches and tables.

/embed/league/{league}/

Supported preferences

Defaults describe bare URLs. Only use preferences listed for this widget.

Builder defaults

The builder explicitly sets these preferences. Other defaults are inherited from the selected variant.

{
  "nomaxwidth": true
}

const url = new URL("https://www.scorebat.com/embed/league/{league}/");
url.searchParams.set("token", "YOUR_EMBED_TOKEN");
url.searchParams.set("pref", JSON.stringify({
  "nomaxwidth": true
}));
// Replace route placeholders with your builder selection.
// Use this URL as the iframe src with the sizing setup above.

Full competition

Matches, results and available standings for one competition.

/embed/competition/{competition}/

Supported preferences

Defaults describe bare URLs. Only use preferences listed for this widget.

Builder defaults

The builder explicitly sets these preferences. Other defaults are inherited from the selected variant.

{
  "nomaxwidth": true
}

const url = new URL("https://www.scorebat.com/embed/competition/{competition}/");
url.searchParams.set("token", "YOUR_EMBED_TOKEN");
url.searchParams.set("pref", JSON.stringify({
  "nomaxwidth": true
}));
// Replace route placeholders with your builder selection.
// Use this URL as the iframe src with the sizing setup above.

Fixtures & results

A focused schedule and results view with a Today tab when applicable.

/embed/fixtures/competition/{competition}/
/embed/fixtures/league/{league}/

Supported preferences

Defaults describe bare URLs. Only use preferences listed for this widget.

Builder defaults

The builder explicitly sets these preferences. Other defaults are inherited from the selected variant.

{
  "fixturesview": "fixtures",
  "nomaxwidth": true
}

const url = new URL("https://www.scorebat.com/embed/fixtures/competition/{competition}/");
url.searchParams.set("token", "YOUR_EMBED_TOKEN");
url.searchParams.set("pref", JSON.stringify({
  "fixturesview": "results",
  "nomaxwidth": true
}));
// Replace route placeholders with your builder selection.
// Use this URL as the iframe src with the sizing setup above.

Competition & league standings

Focused league tables; a league may display several stage tables.

/embed/standings/competition/{competition}/
/embed/standings/league/{league}/

Supported preferences

Defaults describe bare URLs. Only use preferences listed for this widget.

Builder defaults

The builder explicitly sets these preferences. Other defaults are inherited from the selected variant.

{
  "nomaxwidth": true
}

const url = new URL("https://www.scorebat.com/embed/standings/competition/{competition}/");
url.searchParams.set("token", "YOUR_EMBED_TOKEN");
url.searchParams.set("pref", JSON.stringify({
  "tabledetailed": true,
  "nomaxwidth": true
}));
// Replace route placeholders with your builder selection.
// Use this URL as the iframe src with the sizing setup above.

Full team

A complete team page with matches and available team information.

/embed/team/{team}/

Supported preferences

Defaults describe bare URLs. Only use preferences listed for this widget.

Builder defaults

The builder explicitly sets these preferences. Other defaults are inherited from the selected variant.

{
  "nomaxwidth": true
}

const url = new URL("https://www.scorebat.com/embed/team/{team}/");
url.searchParams.set("token", "YOUR_EMBED_TOKEN");
url.searchParams.set("pref", JSON.stringify({
  "nomaxwidth": true
}));
// Replace route placeholders with your builder selection.
// Use this URL as the iframe src with the sizing setup above.

Team standings

A table centered on one team, with an option to show the whole table.

/embed/standings/team/{team}/

Supported preferences

Defaults describe bare URLs. Only use preferences listed for this widget.

Builder defaults

The builder explicitly sets these preferences. Other defaults are inherited from the selected variant.

{
  "tableview": "nearby",
  "tableneighbors": 3,
  "nomaxwidth": true
}

const url = new URL("https://www.scorebat.com/embed/standings/team/{team}/");
url.searchParams.set("token", "YOUR_EMBED_TOKEN");
url.searchParams.set("pref", JSON.stringify({
  "tableview": "nearby",
  "tableneighbors": 2,
  "nomaxwidth": true
}));
// Replace route placeholders with your builder selection.
// Use this URL as the iframe src with the sizing setup above.

Team match card

Upcoming and/or latest completed match cards for one team.

/embed/team-match/team/{team}/

Supported preferences

Defaults describe bare URLs. Only use preferences listed for this widget.

Builder defaults

The builder explicitly sets these preferences. Other defaults are inherited from the selected variant.

{
  "matchmode": "both",
  "nomaxwidth": true
}

const url = new URL("https://www.scorebat.com/embed/team-match/team/{team}/");
url.searchParams.set("token", "YOUR_EMBED_TOKEN");
url.searchParams.set("pref", JSON.stringify({
  "matchmode": "next",
  "nomaxwidth": true
}));
// Replace route placeholders with your builder selection.
// Use this URL as the iframe src with the sizing setup above.

Full match

The complete match view with the information available for that game.

/embed/matchview/{match}/

Supported preferences

Defaults describe bare URLs. Only use preferences listed for this widget.

Builder defaults

The builder explicitly sets these preferences. Other defaults are inherited from the selected variant.

{
  "nomaxwidth": true
}

const url = new URL("https://www.scorebat.com/embed/matchview/{match}/");
url.searchParams.set("token", "YOUR_EMBED_TOKEN");
url.searchParams.set("pref", JSON.stringify({
  "nomaxwidth": true
}));
// Replace route placeholders with your builder selection.
// Use this URL as the iframe src with the sizing setup above.

Match score

A match score card with optional events.

/embed/matchscore/{match}/

Supported preferences

Defaults describe bare URLs. Only use preferences listed for this widget.

Builder defaults

The builder explicitly sets these preferences. Other defaults are inherited from the selected variant.

{
  "nomaxwidth": true
}

const url = new URL("https://www.scorebat.com/embed/matchscore/{match}/");
url.searchParams.set("token", "YOUR_EMBED_TOKEN");
url.searchParams.set("pref", JSON.stringify({
  "noevents": true,
  "layout": "mini",
  "nomaxwidth": true
}));
// Replace route placeholders with your builder selection.
// Use this URL as the iframe src with the sizing setup above.

Line-up

Starting players, field/list presentation and substitutes when available.

/embed/line-up/{match}/

Supported preferences

Defaults describe bare URLs. Only use preferences listed for this widget.

Builder defaults

The builder explicitly sets these preferences. Other defaults are inherited from the selected variant.

{
  "nomaxwidth": true
}

const url = new URL("https://www.scorebat.com/embed/line-up/{match}/");
url.searchParams.set("token", "YOUR_EMBED_TOKEN");
url.searchParams.set("pref", JSON.stringify({
  "layout": "field",
  "subs": "collapse",
  "nomaxwidth": true
}));
// Replace route placeholders with your builder selection.
// Use this URL as the iframe src with the sizing setup above.

Match statistics

Available match statistics in a focused view.

/embed/matchstats/{match}/

Supported preferences

Defaults describe bare URLs. Only use preferences listed for this widget.

Builder defaults

The builder explicitly sets these preferences. Other defaults are inherited from the selected variant.

{
  "nomaxwidth": true
}

const url = new URL("https://www.scorebat.com/embed/matchstats/{match}/");
url.searchParams.set("token", "YOUR_EMBED_TOKEN");
url.searchParams.set("pref", JSON.stringify({
  "nomaxwidth": true
}));
// Replace route placeholders with your builder selection.
// Use this URL as the iframe src with the sizing setup above.

Head-to-head

Previous meetings and comparison content for the selected match.

/embed/match-h2h/{match}/

Supported preferences

Defaults describe bare URLs. Only use preferences listed for this widget.

Builder defaults

The builder explicitly sets these preferences. Other defaults are inherited from the selected variant.

{
  "nomaxwidth": true
}

const url = new URL("https://www.scorebat.com/embed/match-h2h/{match}/");
url.searchParams.set("token", "YOUR_EMBED_TOKEN");
url.searchParams.set("pref", JSON.stringify({
  "nomaxwidth": true
}));
// Replace route placeholders with your builder selection.
// Use this URL as the iframe src with the sizing setup above.

Match video & AI

Video content and available AI context for a selected match.

/embed/g/{match}/

Supported preferences

Defaults describe bare URLs. Only use preferences listed for this widget.

const url = new URL("https://www.scorebat.com/embed/g/{match}/");
url.searchParams.set("token", "YOUR_EMBED_TOKEN");
url.searchParams.set("pref", JSON.stringify({
  "autoplay": false
}));
// Replace route placeholders with your builder selection.
// Use this URL as the iframe src with the sizing setup above.

Match standings

Available standings with the two match teams highlighted.

/embed/matchstandings/{match}/

Supported preferences

Defaults describe bare URLs. Only use preferences listed for this widget.

const url = new URL("https://www.scorebat.com/embed/matchstandings/{match}/");
url.searchParams.set("token", "YOUR_EMBED_TOKEN");
url.searchParams.set("pref", JSON.stringify({
  "dontcollapse": true,
  "nomaxwidth": true
}));
// Replace route placeholders with your builder selection.
// Use this URL as the iframe src with the sizing setup above.

Match AI

A focused AI prediction view where available.

/embed/matchai/{match}/

Supported preferences

Defaults describe bare URLs. Only use preferences listed for this widget.

const url = new URL("https://www.scorebat.com/embed/matchai/{match}/");
url.searchParams.set("token", "YOUR_EMBED_TOKEN");
url.searchParams.set("pref", JSON.stringify({
  "nomaxwidth": true
}));
// Replace route placeholders with your builder selection.
// Use this URL as the iframe src with the sizing setup above.

Video panel

A video player with a browsable selection of matches.

/embed/videopanel/
/embed/videopanel/team/{team}/
/embed/videopanel/competition/{competition}/
/embed/videopanel/league/{league}/
/embed/videopanel/live-stream/

Supported preferences

Defaults describe bare URLs. Only use preferences listed for this widget.

Builder defaults

The builder explicitly sets these preferences. Other defaults are inherited from the selected variant.

{
  "autoplay": true
}

const url = new URL("https://www.scorebat.com/embed/videopanel/");
url.searchParams.set("token", "YOUR_EMBED_TOKEN");
url.searchParams.set("pref", JSON.stringify({
  "autoplay": false
}));
// Replace route placeholders with your builder selection.
// Use this URL as the iframe src with the sizing setup above.

Video feed

A vertical feed of match videos, with optional expansion and autoplay.

/embed/videofeed/
/embed/videofeed/team/{team}/
/embed/videofeed/competition/{competition}/
/embed/videofeed/league/{league}/
/embed/videofeed/live-stream/

Supported preferences

Defaults describe bare URLs. Only use preferences listed for this widget.

Builder defaults

The builder explicitly sets these preferences. Other defaults are inherited from the selected variant.

{
  "autoplay": true,
  "dontcollapse": true
}

const url = new URL("https://www.scorebat.com/embed/videofeed/");
url.searchParams.set("token", "YOUR_EMBED_TOKEN");
url.searchParams.set("pref", JSON.stringify({
  "autoplay": false,
  "dontcollapse": true
}));
// Replace route placeholders with your builder selection.
// Use this URL as the iframe src with the sizing setup above.

WordPress plugin

Add and manage football widgets directly from your WordPress dashboard.

Use the ScoreBat plugin to add live scores, fixtures, standings, team and match widgets, and official video highlights to your WordPress website.

Get the ScoreBat plugin on WordPress.org

1. In your WordPress dashboard, open Plugins → Add New Plugin, search for ScoreBat, then install and activate the plugin.
2. Open ScoreBat in your dashboard and choose Connect to ScoreBat. Sign in or create a free account, then approve the connection to your website.
3. Open the widget catalog, choose and customize a widget, then confirm Use in WordPress to save it to your site.
4. Add a ScoreBat Football Widget block and select your saved widget, or paste its shortcode into a Shortcode block. You can also create a draft page with the widget already added from the ScoreBat dashboard.
5. Preview your page on desktop and mobile, then publish when you are ready.

When a setting does not work

Check the route, value type, entitlement and embed environment.

1. Confirm the route matches the widget section you are reading. Full team, team standings and team match card are different renderers.
2. Check the exact lowercase key and JSON type. Use pref={...} encoded once; do not pass UI labels or internal camelCase names.
3. Compare with the supported preference list. A builder control may be present on multiple variants even when a particular renderer does not use it.
4. Check your active plan and token. Header removal, colors, branding and AI features can depend on entitlements.
5. Test the actual exported URL, not a demo preview. Check that the host page allows the iframe and the required sizing script.
6. If the content itself is missing, verify another match or competition with available data. A preference cannot generate missing tables, videos or line-ups.

For layout issues, inspect the parent container width and height first. If content is clipped, verify the helper script and iframe class, or increase a fixed height. Refresh the widget after changing its URL or saved settings.

Build with an AI assistant

A copyable guide and a machine-readable widget manifest.

Use the Markdown guide for integration instructions and the JSON manifest for routes, supported preference names, allowed values, defaults and applicability notes. Both contain placeholders rather than account tokens.

1. Choose the exact widget variant and a real identifier from the builder. Never invent a route or a preference.
2. Use the supported preference list for that widget. Preserve lowercase keys and JSON value types.
3. Construct URLs with URL and URLSearchParams, and preserve the embed token. Keep sizing settings outside pref.
4. Respect account entitlements and content availability. Never promise that changing a preference removes branding or makes unavailable content appear.
5. Include a descriptive iframe title, suitable dimensions, video permissions where needed, and the correct helper script.