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. |
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;
});