Events for developers
The browser events the widget sends to your page, so your site can react to what visitors open and choose.
The widget can tell the page it runs on what the visitor is doing. Your developer can listen for these events to update the page title and description, track views in your analytics, or take over navigation.
These events exist only with the script installation of paid plans. An iframe cannot send events to your page.
| Event | Sent on | When |
|---|---|---|
sapi:entity | window | A match, team, competition or player view loads. Needs Broadcast entity metadata. |
sapi:navigate | window | The widget is about to navigate to one of your Dynamic Pages. |
theme-change | the <ls-soccersapi> element | The visitor switches between light and dark. |
ls:timezone-changed | window | The visitor changes the time zone in the widget settings. |
ls:offer-impression | the offer, bubbling to window | One of your offers has been at least half on screen for one second (once per offer and placement while the page is open; in a rotating unit, each offer when its turn comes). |
ls:offer-click | the offer button, bubbling to window | The visitor clicks the button of one of your offers. |
None of these events says which widget sent it. If your page has several widgets, keep that in mind.
sapi:entity: the item being viewed
Plans
Sent when a match, team, competition or player view loads its data, and again when its season changes. It needs Broadcast entity metadata on, in the Dynamic Pages section, on a domain with the Dynamic Pages add-on.
window.addEventListener('sapi:entity', (event) => {
const item = event.detail;
if (item.kind === 'match') {
document.title = `${item.home} vs ${item.away} | My site`;
}
});event.detail.kind is match, team, league or player. The other fields
depend on it:
kind | Fields |
|---|---|
match | id, name, home, away, home_id, away_id, league, league_id, season_id, date, status, status_name, minute, score |
team | id, name, team_name, country, league, league_id, season_id, logo |
league | id, name, league_name, country, season_id, logo |
player | id, name, player_name, country, team, team_id, season_id, logo |
- A live match sends the event again as its data changes. Write your handler so it can run many times.
- Floating cards do not send it; only the main view does.
- The widget itself never changes your page title or meta tags.
Search engines
Titles set from JavaScript are read by some search engines and ignored by others. For the most reliable result, render the title and description on your server from the same data: the number in the page address identifies the item.
sapi:navigate: before a Dynamic Pages navigation
Sent before the widget moves the visitor to one of your pages in Dynamic Pages
mode, when the navigation does not come from a plain link click. The event can
be cancelled: call event.preventDefault(), or set event.detail.handled = true, and the widget does not navigate. Your application then handles the
route itself.
window.addEventListener('sapi:navigate', (event) => {
const { href, action } = event.detail;
if (myRouter.canHandle(href)) {
event.preventDefault();
action === 'replace' ? myRouter.replace(href) : myRouter.push(href);
}
});| Field | What it holds |
|---|---|
href | The address of the page, for example /en/matches/{name}/{id}. |
entity, params | The kind of item and its identifiers. |
action | push, replace or back. |
target, rel | The link target and rel set in the configurator. |
mode, source, state, options, delta | Details of the navigation request. |
theme-change and ls:timezone-changed
theme-changeis sent on the<ls-soccersapi>element and bubbles.event.detail.themeislightordark.ls:timezone-changedis sent onwindow.event.detail.timezoneis the new time zone, such asEurope/Madrid.
document.querySelector('ls-soccersapi')
.addEventListener('theme-change', (event) => {
document.documentElement.dataset.theme = event.detail.theme;
});ls:offer-impression and ls:offer-click
Both bubble from the offer to document and window.
event.detail holds placement (where the offer is, such as
livescore.belowToolbar), offerId (the id of the offer in your library) and
source (customer). The widget doesn't count them for you: send them to
your own analytics.
Buttons and text links in the inline places (match.row, match.header,
match.odds, dock.live) add matchId (the match, as a string) and format
(pill or text); a converted affiliate link adds origin: 'affLinks', and
SoccersAPI's own buttons on Free widgets have source: 'soccersapi'. Their
impression counts once per place, offer and match while the page is open.
placement | Where in the configurator |
|---|---|
livescore.belowToolbar | Above the matches |
livescore.top | Top of the widget (banner zone) |
livescore.feed | Between leagues |
livescore.bottom | Bottom of the widget (banner zone) |
entity.top | Item pages, top (banner zone) |
entity.bottom | Item pages, bottom (banner zone) |
window.prematchHero | Match window, Prematch tab |
window.footer | Match window footer |
match.row | Match rows (inline) |
match.header | Match header and window (inline) |
match.odds | Below the odds (inline) |
dock.live | Floating match card (inline) |
window.addEventListener('ls:offer-click', (event) => {
analytics.track('offer_click', event.detail);
});