Configurator options
What each main Widgets V2 configurator area does and when to use it.
This page explains the main areas in the Widgets V2 configurator. It is written for customers using the admin panel.
Saved vs published
Widgets V2 uses two related concepts:
Saved configuration
A reusable setup stored in the admin. Use it as a draft, template or layout version.
Published configuration
The active setup used by the public widget for the selected uid and widget id.
Approved domains are both an allow-list and a routing choice for saved
configurations. Each domain can load the default/current configuration or one of
the saved configurations from the Loads column.
Header actions
Publish before testing
Use Publish current after changing the visible configuration and before
checking the public page.
| Control | What it does | When to use it |
|---|---|---|
| Saved state | Shows whether the open editor has unpublished changes. | Check it before copying code or testing the public site. |
| Current plan | Shows the effective Widgets V2 plan. | Confirm that Free, Starter, Pro or Ultra matches the account access you expect. |
| Publish current | Publishes the current editor state as the public active configuration. | Use this after editing the visible configuration and before testing the public widget. |
| Publish controls | Opens or closes the configuration and domain controls. | Use it to manage saved configurations and approved domains. |
| Refresh | Reloads the latest configuration, saved configurations and domain data. | Use it after billing changes, support changes or another tab update. |
| Get code | Opens the embed snippet for the current delivery mode. | Use it only after publishing the configuration. |
| Fullscreen | Expands the configurator and preview workspace. | Useful for checking match modals, league pages and mobile widths. |
Configurations area
The configurations area is for saving and reusing different setup versions.
| Control | What it does |
|---|---|
| Configuration selector | Chooses an existing saved configuration or the default one. |
| Load | Loads the selected saved configuration into the editor. It does not publish it by itself. |
| New configuration name | Names a new saved configuration. |
| Save new | Stores the current editor settings as a new saved configuration. |
| Update | Updates the selected saved configuration with the current editor settings. |
| Publish selected | Makes the selected saved configuration the public active one. |
| Delete | Removes a saved configuration that is no longer needed. |
Use saved configurations when you want to keep versions such as:
Homepage light themeArticle sidebar compactSpanish site layoutPartner launch draft
Remember: only the published configuration is loaded by the public embed.
Domains area
Domains control where the widget is allowed to run. Add domains without protocol and without paths.
| Control | What it does |
|---|---|
| Domain selector | Selects an existing approved domain or the new-domain row. |
| New domain | Clears the input so you can add another domain. |
| Domain input | Adds or edits the domain name. |
| Loads | Chooses which saved configuration that domain should load. |
| Add domain | Adds a new approved domain when the plan limit allows it. |
| Save | Appears after editing an existing domain. Saves the rewritten domain. |
| Delete | Removes the selected domain from the allow-list. |
Examples:
| Website | Domain to add |
|---|---|
https://example.com/live | example.com |
https://www.example.com/scores | www.example.com |
https://scores.example.com | scores.example.com |
Do not add paths such as /live or /widgets. Domain validation is based on
the host.
Widget type
The widget type decides the football experience shown to the visitor.
| Widget | Use case |
|---|---|
| Livescore | A daily match list with live score states and match entry points. |
| Match details | A focused match page with summary, events, lineups, statistics and related tabs. |
| League | A competition page with fixtures, standings, teams and stats. |
| Leagues | A country or competition directory. |
| Team | Team profile pages, fixtures, results and squad views. |
| Player | Player profile pages, career history and statistics. |
Free is iframe-only and focused on the livescore widget. Paid plans can unlock the broader widget set.
Language and localization
The locale controls interface language and labels. Typical values are en,
es, fr, de, it, pt, nl, pl, ru, ar, ko, cn, vi, gr
and tk.
Use one configuration per language if your website needs different layouts or
copy per market. If the layout is identical, changing the locale parameter in
the copied embed may be enough.
Layout and navigation
Layout controls decide how much structure the widget shows.
Common options:
- main widget header
- entity headers for match, team, league and player screens
- compact spacing
- tab visibility
- match-detail behavior
- modal or in-page navigation
- segmented widget behavior for paid plans
Use a modal-style match view when the widget is embedded in an article, blog post or homepage section. Use internal navigation for a fuller widget experience on one page. Use link/page or host router navigation only when Live SEO Pages is active for the domain.
Match details
Match detail views can include:
- summary
- pre-match information
- events
- lineups
- statistics
- commentary
- standings
- head-to-head
- TV or broadcast information when available
- odds when available and enabled
Not every match has every data type. If a competition has limited data, the widget may hide tabs or show a lighter empty state.
Entity views
Entity views cover leagues, teams and players.
Use them when you want visitors to move beyond the live score list:
- League pages help users explore fixtures, standings, teams and stats.
- Team pages help users follow one club or national team.
- Player pages help users inspect profile, career and statistics.
If entity headers are enabled in the configurator, test them inside the public embed after publishing. Unsaved changes are the most common reason a header looks different in production.
Theme and styling
Theme controls change the visual style of the widget.
Recommended workflow:
- Choose the style preset or base mode.
- Set the primary color.
- Adjust header, tab and accent colors.
- Review spacing and compact mode.
- Open a match modal and an entity page before publishing.
Do not validate only the first livescore screen. Headers, modals and entity views can reveal spacing issues that are not visible in the match list.
Featured leagues
Featured leagues let you highlight selected competitions near the top of the experience when the plan includes the feature.
Use featured leagues for:
- a football news homepage focused on top European competitions
- a country-specific site that wants local competitions first
- a betting or media page that wants to promote a small group of competitions
Sounds
Sound controls enable live event alerts when the plan includes them.
Use sounds only when the widget experience is meant to be watched actively, for example a livescore page. Avoid sounds on article pages or pages where the user does not expect audio.
Pro options
Pro options are plan-gated commercial controls.
| Option | What it is for |
|---|---|
| Branding controls | Custom logo, colors and visible brand treatment. |
| White-label | Removes visible SoccersAPI branding when included in the plan. |
| Navigation controls | Modal and internal entity navigation behavior. |
| Dynamic Pages | Optional per-domain add-on for link/page routing, host router mode and entity metadata broadcast. |
| Affiliate links | Your own commercial links attached to widget placements. |
| Bookmaker links | Your bookmaker inventory and outbound links. |
| Bookmaker odds | Odds modules when odds coverage is available. |
| Top banners | Commercial or promotional banner above widget content. |
| Bottom banners | Commercial or promotional banner below widget content. |
| Custom CSS | Final styling adjustments for paid plans. |
| Streaming module | Custom-only feature when commercially agreed. |
Free widgets may show SoccersAPI branding, SoccersAPI affiliate links, bookmaker placements or promotional banners. Use Pro or Ultra when you want to control monetization yourself.
Embed code
The Get code panel gives the snippet for the current delivery mode.
- iframe delivery
- default generated iframe height is
1200px - SoccersAPI-hosted frame
- one approved domain by default
- native Web Component embed
- content appears directly on the page instead of inside a Free iframe
- plan-gated commercial controls
- optional Dynamic Pages add-on for entity URLs
If you change only colors, tabs, Pro options or branding, publish again and refresh the website. You usually do not need to replace the code.
Copy fresh code when changing:
- delivery mode
- iframe height
- language parameter
uidwidget-id
Example use cases
Small site testing the widget
Use Free. Create one livescore configuration, add one domain, publish it and
copy the iframe. Keep the default 1200px height until you have tested busy
match days.
Publisher with Dynamic Pages
Use a paid plan with the Dynamic Pages add-on enabled for the domain. Then use link/page or host router navigation so match, league, team and player views can open as URLs.
Commercial affiliate site
Use Pro. Configure affiliate links, bookmaker links, odds modules and banners. Test that commercial placements only appear where they make sense.
Multi-site network
Use Ultra for higher base limits: 10 approved domains, unlimited saved configurations, 3M monthly widget views, 20 affiliate links and 50 bookmakers. If the network needs more domains, use a Custom agreement.