Eventos do player

O player pode avisar sua página em tempo real do que está acontecendo: o vídeo começou, pausou, chegou a 90%, terminou, deu erro. Cada aviso é um evento, e você escolhe o que executar quando ele acontecer — registrar uma conversão na sua ferramenta de métricas, liberar um material extra, atualizar botões da sua própria interface.

Este guia cobre o player instalável. Se você usa o embed por iframe, pule para Eventos via iframe — o mecanismo é outro.

A estrutura básicaCopiar link da seção

Uma linha para ouvir, uma função para agir:

player.on('ended', function () {
  // roda quando o vídeo termina
});

O primeiro valor é o nome do evento; a função é o que sua página faz em resposta. Você pode se inscrever em quantos eventos quiser. A inscrição devolve uma função de cancelamento, caso precise parar de ouvir:

const cancelar = player.on('ended', acao);
cancelar(); // para de ouvir

Receitas prontasCopiar link da seção

Registrar conversão quando o vídeo termina — troque o comentário pelo código da sua ferramenta de métricas (Google Ads, Meta Pixel, GA4...):

let marcouFim = false;

player.on('ended', () => {
  if (marcouFim) return; // evita contar duas vezes
  marcouFim = true;
  // ex.: gtag('event', 'video_completo');
});

Saber quanto o espectador já assistiu — o evento timeupdate dispara várias vezes por segundo enquanto o vídeo toca:

player.on('timeupdate', () => {
  const progresso = player.currentTime / player.duration; // 0 a 1
  if (progresso >= 0.9) {
    // assistiu 90% — bom momento para liberar um certificado, por exemplo
  }
});

Reagir a erros — o evento error só dispara quando a reprodução de fato para; falhas que o player recupera sozinho (como uma queda breve de internet) não chegam até aqui:

player.on('error', (e) => {
  console.error('falha na reprodução:', e);
});

Todos os eventosCopiar link da seção

Os que mais importam na prática:

Detalhes que valem saber:

• ready só dispara depois que a mídia carrega de fato — não é só a configuração chegando.
• aderror traz code e message do erro de anúncio.
• daifallback avisa que o intervalo comercial costurado ao vídeo (DAI) não veio, ou veio e não carregou, e a reprodução seguiu pelo conteúdo normal — o motivo vem em reason: sdk_ausente, stream_error ou erro_ao_iniciar.
• error só é emitido quando a reprodução para. O player não emite error para falhas que recupera sozinho.

Para ouvir tudo de uma vez (útil para depurar ou registrar telemetria própria):

player.on('*', (event, metadata) => {
  console.log(event.event, metadata);
});

Eventos via iframeCopiar link da seção

No embed por iframe (https://beyond.spalla.io/player/?video=SEU_ID_AQUI, ou ?live=SEU_ID_AQUI para transmissões) o player roda "dentro de uma janela separada", e os avisos chegam como mensagens entre janelas. Cole isto na sua página e adapte o que cada aviso faz:

window.addEventListener('message', (event) => {
  if (event.origin !== 'https://beyond.spalla.io') return;

  const { type, payload } = event.data;
  if (type === 'player.play') console.log('reprodução iniciada', payload);
  if (type === 'player.watchedPercent') console.log('progresso', payload);
});

A checagem de origin garante que sua página só reaja a mensagens vindas do player da Spalla — nunca de qualquer outra janela.

Controlando o player da sua interfaceCopiar link da seção

Os mesmos métodos do player servem para botões seus — funcionam igual no computador, no celular e durante um Chromecast:

botaoPlay.addEventListener('click', () => player.togglePlay());
player.currentTime;   // posição atual, em segundos
player.duration;      // duração total
player.muted = true;  // silencia
player.seek(120);     // pula para 2 minutos

A lista completa de métodos e propriedades está na referência da API do player.