Configurator guide

Step-by-step guide to create, customize, save and publish a Widgets V2 configuration.

The Widgets V2 configurator is where you decide how the widget will look, what it can show, where it is allowed to run and which code should be copied to your website.

The most important rule is simple: publish the configuration before copying the embed code. The public widget loads the active published configuration, not the temporary changes that are still open in your browser.

Recommended order

Configure the widget, add the domain, save the setup if you want to reuse it, publish it, then copy the code.

Saved, published and domains

The admin lets you save several named configurations. Public embeds still load by uid, widget-id and domain, but each approved domain can be mapped to the configuration it should load.

Saved configuration

A reusable draft or template stored in the admin.

Published configuration

The version visitors see on your website.

Approved domain

The host where the widget is allowed to run.

If you need two different layouts live at the same time on two different domains, save both configurations and assign each domain to the right setup from the Domains area.

1. Open the configurator

In the SoccersAPI admin, open the Widgets V2 area and choose the Livescore widget product.

If you already have configurations, open the one you want to edit. If this is a new setup, create a new configuration first.

Use a clear name such as:

Main site livescore
Spanish homepage widget
Partner site embed
Testing configuration

Good names help when one account has several websites, domains or layout versions.

Widgets V2 can publish different football experiences depending on your plan:

Widget	Typical use
Livescore	Daily match list, live scores and match access
Match details	Full match page with summary, events, lineups, statistics and more
League	One competition page with fixtures, standings, teams and stats
Leagues	Country and competition directory
Team	Team profile, fixtures, results and squad views
Player	Player profile, career and statistics

Free plans are limited to the hosted iframe livescore experience. Paid plans can use the broader widget set when the plan includes it.

3. Add the allowed domain

Before testing the widget on a real website, add the exact domain where it will be used.

Examples:

Website URL	Add this domain
`https://example.com/scores`	`example.com`
`https://www.example.com/live`	`www.example.com`
`https://scores.example.com`	`scores.example.com`

Domain validation protects your widget configuration from being copied to unapproved websites.

If you test from a different domain than the one saved in the admin, the widget may show an access error even if the configuration is correct.

The Domains area now works like a small editor:

Choose New domain in the domain selector.

Type the host, for example example.com.

Click Add domain.

To change an existing domain, select it, rewrite the value and click Save.

Use the Loads field to choose which saved configuration that domain should use.

Use Delete only when the widget should no longer run on that host.

Adding a domain approves the host. The Loads field decides which saved configuration the domain should use after publishing.

4. Configure the layout

Start with the general structure before fine-tuning colors.

Typical layout decisions:

show or hide the main widget header
show or hide entity headers for teams, leagues and players
choose compact or expanded spacing
decide how match details open
choose which tabs are visible
choose whether the widget should prioritize live matches, today's matches or selected competitions

For iframes, also choose a practical height. A livescore widget usually needs enough vertical space to avoid feeling cut off on a busy match day. If the generated iframe includes height=1200, keep the iframe style consistent with that value on your page.

Common examples:

Page type	Recommended layout
Homepage livescore block	Show header, compact spacing, modal match details
Full live score page	Show header, full tabs, comfortable spacing
Article sidebar	Compact spacing, fewer tabs, no unexpected sounds
Football page with entity navigation	Native embed, entity headers enabled, modal or internal navigation
Dynamic Pages domain	Native embed, entity headers enabled, page/router navigation after add-on activation

5. Configure match details and entity views

Match, team, league and player screens can include several views. The exact availability depends on data coverage and plan access.

Common match detail sections:

summary
pre-match information
events
lineups
statistics
standings
head-to-head
TV or broadcast information when available
odds when available and enabled

Common entity screens:

league fixtures and standings
team fixtures, results and squad
player profile, career and statistics
country and competition navigation

If a tab has no data for a match or competition, the widget may hide it or show a lighter empty state.

6. Customize the theme

Use the theme controls to match the widget with your website.

Recommended order:

Choose light or dark style.

Set the primary color.

Adjust header and accent colors.

Review typography and spacing.

Preview a match modal and at least one entity view.

Avoid checking only the first screen. Open a match, a league and a team/player view before publishing. Some layout issues only appear inside details or modal screens.

7. Review plan-locked options

The configurator shows options that may be locked depending on your plan. This is expected.

iframe delivery
one approved domain
one saved configuration
monthly traffic cap
SoccersAPI branding or promotional placements may appear
client monetization options are locked

native Web Component embed
more domains
more saved configurations
custom branding
featured leagues
sounds
navigation options
affiliate links
bookmaker links and odds modules
top and bottom banners
optional Dynamic Pages add-on by domain

If a section says it is locked, publishing the configuration will not activate that feature until the plan includes it.

8. Set Pro options

The Pro options area is for commercial and plan-gated features.

Use it to configure:

your affiliate links
your bookmaker links
top banners
bottom banners
featured leagues
sound alerts
branding and white-label options when included

Free widgets may still show SoccersAPI branding or SoccersAPI promotional placements. Paid widgets are the right option when you want a cleaner commercial experience for your own site.

Use Pro options with a specific goal:

Goal	Options to review
Monetize outbound traffic	Affiliate links, bookmaker links, bookmaker odds
Sell direct sponsorship	Top banners and bottom banners
Match your brand	Branding controls, logo, custom CSS
Create a richer football hub	Navigation controls and segmented widgets
Remove visible SoccersAPI branding	Ultra white-label controls

9. Save and publish the configuration

Save after important changes and always publish before copying code.

Saving a named configuration:

stores the selected layout and styling
lets you load or reuse the same setup later
does not necessarily change the public widget by itself

Publishing:

updates the public active widget configuration
makes the embed code valid for the selected uid and widget-id
clears the difference between preview and production

If you copy the code before publishing, the public page may show an old version or a widget_not_found error.

10. Copy the embed code

After publishing, copy the code for the delivery mode you want to use.

Free plan:

use the iframe code
paste it into the page where the widget should appear
keep the recommended height unless you have tested a different one

Paid plans:

use the native Web Component embed when available
paste the code into the page where the widget should appear
make sure the page domain is approved in the admin
use Dynamic Pages only on domains where the add-on is active

If you have several saved configurations, publish the one you want public before copying the code. The copied code does not carry a saved configuration id.

11. Test from the final website

Test the widget from the real page and domain, not only from the admin preview.

Check:

the widget loads without access errors
the approved domain is correct
the language is correct
the height is comfortable on desktop and mobile
match details open correctly
entity headers appear as expected
locked features are not showing on Free plans
Pro options only show when the plan includes them
traffic and branding behavior matches the selected plan

Also test on mobile. If the widget is inside a narrow article or sidebar, the iframe or container must be allowed to use the full available width.

To change a published widget:

Open the saved configuration.
Make the changes.
Preview the main widget and detail views.
Save the configuration if you want to keep that named version.
Publish the updated configuration.
Refresh the website page where the widget is embedded.

In most cases, you do not need to replace the embed code when only changing colors, tabs, layout, Pro options or branding. Save and publish the updated configuration, then refresh the website page.

You only need new code if you change the delivery mode, the uid, the widget-id, the language parameter or the iframe height.

Example workflows

Launch a Free livescore iframe

Open the Livescore configurator.
Keep iframe delivery.
Add the website domain.
Adjust colors and layout.
Publish current.
Copy the iframe code.
Paste it on the approved domain.
Test on desktop and mobile.

Open or create a Pro configuration.
Add the production domain.
Enable the match detail tabs you want.
Add affiliate links and bookmaker links.
Configure top or bottom banners if needed.
Publish current.
Copy the native Web Component embed.
Test that commercial placements appear only where intended.

Keep a seasonal layout ready

Create a saved configuration called Summer tournament layout.
Adjust colors, featured leagues and banners.
Save it as a configuration.
Do not publish until you want it live.
When ready, select it and use Publish selected.

Common mistakes

Problem	Most likely cause	What to do
`widget_not_found`	Code copied before publishing, wrong `widget-id` or wrong user/configuration	Publish again and copy fresh code
Domain access error	Current website domain is not approved	Add the exact domain in the admin
Free widget shows limited options	Free plan restrictions are active	Upgrade to a paid plan for Pro options
Paid options do not appear	The selected plan does not include that feature	Check the plan limits
Public widget differs from preview	Unpublished changes or old embed code	Publish and refresh the public page
Iframe feels too short	Page is using a smaller height than the generated code	Increase iframe height in the copied code
Entity header missing	Header option is disabled or an old published configuration is being loaded	Enable it, publish and test again

Publishing checklist

Before considering the widget live, confirm:

the configuration is saved
the configuration is published
the correct domain is approved
the correct plan is active
the correct delivery mode is being used
the copied code uses the right uid
the copied code uses the right widget-id
mobile layout has been checked
match details and entity views have been checked
Pro options and branding match the plan