IFrame Player API

Atualizado: 07.04.2026

A IFrame Player API permite o controle programático do player via JavaScript: iniciar e parar a reprodução, gerenciar volume, assinar eventos e muito mais.

Para quem é este artigo

Desenvolvedores frontend — precisam controlar programaticamente o player na página
Desenvolvedores de LMS — precisam rastrear o progresso de aprendizado e criar cenários interativos
Desenvolvedores de aplicações — precisam integrar o player com a lógica de negócio da aplicação

Por que usar a IFrame Player API?

Com a IFrame Player API você pode:

Controlar programaticamente o player — iniciar, parar, buscar no vídeo
Reagir a eventos — rastrear o início da reprodução, pausas, fim do vídeo
Criar cenários interativos — sincronizar o player com outros elementos da página
Gerenciar playlists — alternar dinamicamente entre vídeos
Configurar parâmetros — alterar qualidade, volume, velocidade de reprodução programaticamente

O que a IFrame Player API oferece

A IFrame Player API ajuda a conectar o player à lógica da sua aplicação: controle a reprodução e assine eventos.

Controle e eventos

Integração com a lógica da aplicação — você pode vincular o controle do player ao estado do usuário, direitos de acesso e outras condições no seu produto.
Interface Promise — os métodos da API retornam uma Promise, por isso são convenientes para chamar via await ou .then().
Eventos do player — assinar eventos (play/pause/ended, etc.) permite acionar ações na sua interface no momento certo.

Métricas personalizadas e envio de dados

Contexto de analytics — você pode enriquecer eventos com seus próprios dados (por exemplo, ID do usuário, curso, lição, dispositivo, navegador).
Eventos detalhados — quando necessário, rastreie pausas, buscas, repetições e outras ações.
Exportação para seus sistemas — envie eventos coletados para seus analytics, CRM ou LMS.

Parâmetros e cenários

Altere parâmetros em tempo real — altere volume, velocidade, qualidade e outras configurações quando for contextualmente apropriado.
Cenários sobre vídeo — crie mecânicas interativas (quizzes, transições, dicas) vinculadas a eventos do player.

Casos de uso típicos

Sistemas de Gestão de Aprendizado (LMS)

A IFrame Player API é especialmente útil para plataformas educacionais onde muitos fatores importam:

Rastreamento do progresso de aprendizado — registro do tempo de visualização, conclusão de lições, repetições
Aprendizado adaptativo — avançar automaticamente para a próxima lição após o término da atual
Verificação de conhecimento — pausar a reprodução para mostrar perguntas em momentos específicos
Personalização — configurando velocidade de reprodução, qualidade de vídeo e outros parâmetros de acordo com as preferências do aluno
Integração com sistema de notas — vinculação da visualização de vídeo a notas e conquistas

Aplicações interativas

Sincronização de conteúdo — mostrando informações adicionais, comentários ou legendas em momentos específicos do vídeo
Integração com formulários — pausar a reprodução para preencher formulários ou completar pesquisas
Cenários multi-tela — controlando múltiplos players em uma página

Portais corporativos

Controle de acesso — verificação das permissões do usuário antes da reprodução
Log de atividades — rastreamento detalhado do uso de conteúdo por funcionários
Integração com sistemas internos — vinculação da visualização de vídeo a tarefas, projetos e relatórios

Exemplo: Analytics avançado para sistemas de aprendizado

Aqui está um exemplo de construção de um sistema de analytics que coleta dados de visualização de vídeo e os enriquece com contexto:

// Sistema de analytics para uma plataforma educacional
class LearningAnalytics {
  constructor(player, context) {
    this.player = player;
    this.context = {
      userId: context.userId,
      courseId: context.courseId,
      lessonId: context.lessonId,
      device: this.getDeviceInfo(),
      browser: this.getBrowserInfo(),
      timestamp: new Date().toISOString()
    };
    this.events = [];
    this.setupEventListeners();
  }

  setupEventListeners() {
    const player = this.player;

    // Rastrear início da reprodução
    player.on(player.Events.Play, () => {
      this.trackEvent('play', {
        currentTime: null,
        playbackRate: null
      });
    });

    // Rastrear pausa
    player.on(player.Events.Pause, async () => {
      const currentTime = await player.getCurrentTime();
      const duration = await player.getDuration();
      const percent = (currentTime / duration) * 100;

      this.trackEvent('pause', {
        currentTime,
        percent,
        reason: this.detectPauseReason()
      });
    });

    // Rastrear progresso de visualização
    let lastTrackedPercent = 0;
    player.on(player.Events.TimeUpdate, async (event) => {
      const percent = event.data.percent;
      
      // Enviar evento a cada 10% visualizados
      if (percent - lastTrackedPercent >= 10) {
        lastTrackedPercent = percent;
        this.trackEvent('progress', {
          percent: Math.floor(percent),
          currentTime: event.data.currentTime
        });
      }
    });

    // Rastrear fim da reprodução
    player.on(player.Events.Ended, async () => {
      const duration = await player.getDuration();
      this.trackEvent('completed', {
        totalDuration: duration,
        watchedDuration: duration
      });
    });

    // Rastrear busca
    let lastSeekTime = 0;
    player.on(player.Events.Seeked, async () => {
      const currentTime = await player.getCurrentTime();
      if (Math.abs(currentTime - lastSeekTime) > 5) {
        this.trackEvent('seek', {
          from: lastSeekTime,
          to: currentTime,
          direction: currentTime > lastSeekTime ? 'forward' : 'backward'
        });
      }
      lastSeekTime = currentTime;
    });

    // Rastrear mudanças de qualidade
    player.on(player.Events.QualityChanged, (event) => {
      this.trackEvent('quality_changed', {
        quality: event.data.quality,
        reason: 'user_selection'
      });
    });

    // Rastrear erros
    player.on(player.Events.Error, (event) => {
      this.trackEvent('error', {
        error: event.data.error,
        currentTime: null
      });
    });
  }

  trackEvent(eventType, eventData) {
    const event = {
      type: eventType,
      data: eventData,
      context: this.context,
      timestamp: new Date().toISOString()
    };

    this.events.push(event);
    this.sendToAnalytics(event);
  }

  async sendToAnalytics(event) {
    try {
      await fetch('/api/analytics/track', {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
        },
        body: JSON.stringify(event)
      });
    } catch (error) {
      console.error('Analytics send error:', error);
    }
  }

  detectPauseReason() {
    return 'user_action';
  }

  getDeviceInfo() {
    return {
      type: /Mobile|Android|iPhone|iPad/.test(navigator.userAgent) ? 'mobile' : 'desktop',
      screen: {
        width: window.screen.width,
        height: window.screen.height
      }
    };
  }

  getBrowserInfo() {
    return {
      name: navigator.userAgent.match(/(Chrome|Firefox|Safari|Edge)\/[\d.]+/)?.[1] || 'unknown',
      version: navigator.userAgent.match(/(Chrome|Firefox|Safari|Edge)\/([\d.]+)/)?.[2] || 'unknown'
    };
  }

  getSummary() {
    return {
      totalEvents: this.events.length,
      events: this.events,
      context: this.context
    };
  }
}

// Usando o sistema de analytics
function onKinescopeIframeAPIReady(playerFactory) {
  playerFactory
    .create('player', {
      url: 'https://kinescope.io/1111111',
      size: { width: '100%', height: 400 }
    })
    .then(function (player) {
      const analytics = new LearningAnalytics(player, {
        userId: 'user_12345',
        courseId: 'course_67890',
        lessonId: 'lesson_11111',
      });

      window.addEventListener('beforeunload', () => {
        const summary = analytics.getSummary();
        navigator.sendBeacon('/api/analytics/track', JSON.stringify({
          type: 'session_end',
          summary: summary
        }));
      });
    });
}

Este exemplo mostra como:

Coletar dados detalhados sobre visualizações de vídeo vinculadas ao contexto de aprendizado
Enriquecer eventos com informações de usuário, curso, dispositivo e outros dados
Rastrear várias métricas — tempo de visualização, pausas, buscas, qualidade de vídeo
Integrar com seu sistema — enviando dados para seus analytics, LMS ou outros sistemas

Integrando com a lógica da aplicação

A IFrame Player API facilita a integração do player com a lógica interna da sua aplicação:

Exemplo: Controle de acesso

function onKinescopeIframeAPIReady(playerFactory) {
  checkUserAccess()
    .then(hasAccess => {
      if (!hasAccess) {
        showAccessDeniedMessage();
        return;
      }

      return playerFactory.create('player', {
        url: 'https://kinescope.io/1111111',
        size: { width: '100%', height: 400 }
      });
    })
    .then(function (player) {
      if (!player) return;
      setupPlayerLogic(player);
    });
}

async function checkUserAccess() {
  const response = await fetch('/api/check-access');
  const data = await response.json();
  return data.hasAccess;
}

function setupPlayerLogic(player) {
  player.on(player.Events.Ended, async () => {
    await updateUserProgress();
    await unlockNextLesson();
    showNotification('Lição concluída!');
  });
}

Exemplo: Sincronizando com o estado da aplicação

// Integração com estado da aplicação React/Vue/Angular
function createPlayerWithState(playerFactory, appState) {
  return playerFactory.create('player', {
    url: appState.currentVideo.url,
    behavior: {
      autoPlay: appState.settings.autoPlay,
      muted: appState.settings.muted
    }
  }).then(function (player) {
    player.on(player.Events.Pause, () => {
      appState.setPlayerState('paused');
    });

    player.on(player.Events.Playing, () => {
      appState.setPlayerState('playing');
    });

    appState.on('videoChanged', (newVideo) => {
      player.switchTo(newVideo.id);
    });

    return player;
  });
}

Conectando a API

Para usar a IFrame Player API, inclua o script na página e declare a função onKinescopeIframeAPIReady, que será chamada automaticamente após o carregamento da API.

Exemplo básico de conexão

<!doctype html>
<html>
  <body>
    <!-- Contêiner do player -->
    <div id="player"></div>

    <script>
      // Carregar o script da IFrame Player API
      var tag = document.createElement('script');
      tag.src = 'https://player.kinescope.io/latest/iframe.player.js';
      var firstScriptTag = document.getElementsByTagName('script')[0];
      firstScriptTag.parentNode.insertBefore(tag, firstScriptTag);

      // Esta função é chamada automaticamente após o carregamento da API
      function onKinescopeIframeAPIReady(playerFactory) {
        playerFactory
          .create('player', {
            url: 'https://kinescope.io/1111111',
            size: { width: '100%', height: 400 },
          })
          .then(function (player) {
            console.log('Player criado:', player);
          });
      }
    </script>
  </body>
</html>

Criando um player

Use o método create do objeto playerFactory para criar um player:

playerFactory.create(elementId, options).then(function(player) {
  // Player está pronto
});

Parâmetros de criação

elementId — ID do elemento da página a ser substituído por um iframe (ou ID de um iframe existente)
options — objeto de configurações do player

Parâmetros principais

{
  // URL do vídeo (obrigatório)
  url: 'https://kinescope.io/1111111',
  
  // Dimensões do player
  size: {
    width: '100%',  // ou número em pixels
    height: 400     // ou string '56.25%' para proporção 16:9
  },
  
  // Configurações de comportamento
  behavior: {
    preload: 'metadata',  // 'none', 'metadata', 'auto'
    autoPlay: false,
    muted: false,
    loop: false,
    keyboard: true,
    playsInline: true
  },
  
  // Configurações de UI
  ui: {
    language: 'pt',
    controls: true,
    mainPlayButton: true
  }
}

Exemplo: Criando um player com configurações

function onKinescopeIframeAPIReady(playerFactory) {
  playerFactory
    .create('player', {
      url: 'https://kinescope.io/1111111',
      size: {
        width: '100%',
        height: '56.25%'  // proporção 16:9
      },
      behavior: {
        preload: 'metadata',
        autoPlay: false,
        muted: false
      },
      ui: {
        language: 'pt',
        controls: true
      }
    })
    .then(function (player) {
      console.log('Player pronto');
    });
}

Controle do player

Após criar o player, você recebe um objeto player com métodos para controlar a reprodução.

Métodos principais de controle

Reprodução

await player.play();
await player.pause();
await player.stop();
await player.seekTo(60);  // buscar para 1 minuto

Obtendo informações

const isPaused = await player.isPaused();
const isEnded = await player.isEnded();
const currentTime = await player.getCurrentTime();
const duration = await player.getDuration();

Controle de volume

const volume = await player.getVolume();
await player.setVolume(0.5);  // definir 50%
await player.mute();
await player.unmute();
const isMuted = await player.isMuted();

Controle de CTA

await player.closeCTA();

Controle de qualidade

const qualities = await player.getVideoQualityList();
const currentQuality = await player.getVideoQuality();
await player.setVideoQuality('1080p');

Controle de velocidade de reprodução

const playbackRate = await player.getPlaybackRate();
await player.setPlaybackRate(1.5);  // velocidade 1.5x

Modo tela cheia

const isFullscreen = await player.isFullscreen();
await player.setFullscreen(true);

Modo picture-in-picture

const isPip = await player.isPip();
await player.setPip(true);

Exemplo: Usando métodos

function onKinescopeIframeAPIReady(playerFactory) {
  playerFactory
    .create('player', {
      url: 'https://kinescope.io/1111111',
      size: { width: '100%', height: 400 }
    })
    .then(function (player) {
      player.setVolume(0.5);
      
      player.on(player.Events.Playing, function() {
        console.log('Reprodução iniciada');
      });
      
      player.on(player.Events.Pause, function() {
        console.log('Reprodução pausada');
      });
      
      player.on(player.Events.TimeUpdate, function(event) {
        console.log('Tempo atual:', event.data.currentTime);
      });
    });
}

Eventos do player

O player dispara eventos que você pode assinar para rastrear mudanças de estado.

Assinando eventos

player.on(player.Events.Play, function(event) {
  console.log('Reprodução iniciada');
});

player.once(player.Events.Loaded, function(event) {
  console.log('Player carregado');
});

function handler(event) {
  console.log('Evento ocorreu');
}
player.on(player.Events.Play, handler);
player.off(player.Events.Play, handler);

Eventos principais

Events.Loaded — o player carregou todos os dados necessários e está pronto para reproduzir
Events.Play — reprodução iniciada
Events.Playing — reprodução ativa
Events.Pause — pausa
Events.Ended — reprodução encerrada
Events.TimeUpdate — tempo de reprodução atual alterado
Events.VolumeChange — nível de volume alterado
Events.QualityChanged — qualidade de vídeo alterada
Events.FullscreenChange — modo tela cheia alterado
Events.CallAction — botão CTA clicado
Events.Error — erro crítico

Dados do evento

Cada evento contém um objeto de dados:

{
  type: player.Events.Play,
  data: { /* dados do evento */ },
  target: player
}

Exemplo: Trabalhando com eventos

player
  .once(player.Events.Loaded, function(event) {
    console.log('Duração:', event.data.duration);
    console.log('Qualidade:', event.data.quality);
  })
  .on(player.Events.TimeUpdate, function(event) {
    const currentTime = event.data.currentTime;
    const percent = event.data.percent;
    console.log(`Reproduzido: ${currentTime}s (${percent}%)`);
  })
  .on(player.Events.Ended, function() {
    console.log('Reprodução finalizada');
  })
  .on(player.Events.Error, function(event) {
    console.error('Erro do player:', event.data.error);
  });

Trabalhando com playlists

A IFrame Player API suporta criação e gerenciamento de playlists com múltiplos vídeos.

Criando uma playlist

playerFactory
  .create('player', {
    url: 'https://kinescope.io/1111111',
    playlist: [
      {
        id: 'video1',
        title: 'Primeiro Vídeo',
        subtitle: 'Descrição do primeiro vídeo'
      },
      {
        id: 'video2',
        title: 'Segundo Vídeo',
        subtitle: 'Descrição do segundo vídeo'
      }
    ],
    behavior: {
      playlist: {
        autoSwitch: true,
        loop: false
      }
    }
  })
  .then(function(player) {
    // Player com playlist está pronto
  });

Controle de playlist

const currentItem = await player.getPlaylistItem();

await player.switchTo('video2', {
  autoPlay: true,
  time: 0
});

await player.next();
await player.previous();

player.on(player.Events.CurrentTrackChanged, function(event) {
  console.log('Vídeo atual:', event.data.item.id);
});

Call To Action (CTA)

Funcionalidade beta. Pode mudar após a coleta de feedback.

Call To Action (CTA) permite mostrar chamadas para ação durante a reprodução do vídeo. Útil para anúncios, assinaturas, registros ou outros objetivos.

Como funciona: Quando o CTA é ativado, a reprodução para e uma tela de ação é mostrada sobre o player. Quando o usuário clica no botão de ação, um evento é disparado que você pode manipular programaticamente.

O CTA pode ser configurado para ser exibido:

No final de um vídeo ou playlist
Em momentos específicos de reprodução
Quando o vídeo é pausado

Configurando CTA via IFrame API

Use o parâmetro playlist ao criar o player. Veja a documentação completa para todos os recursos da API.

Exemplo de configuração de CTA:

import { createPlayer } from '@kinescope/iframe-api';

const player = await createPlayer({
  videoId: '123456789',
  playlist: [
    {
      videoId: '123456789',
      cta: {
        title: 'Assine nosso canal',
        description: 'Receba novos vídeos primeiro',
        buttonText: 'Assinar',
        buttonUrl: 'https://example.com/subscribe',
        showAt: 'end' // ou tempo em segundos
      }
    }
  ]
});

Controle programático do CTA

Para fechar a tela do CTA programaticamente, chame o método closeCTA() no objeto do player:

await player.closeCTA();

Manipulando eventos de CTA

Quando o usuário clica no botão CTA, o evento CallAction é disparado. Assine para rastrear interações:

player.on(player.Events.CallAction, function(event) {
  console.log('CTA clicado:', event.data);
});

Veja a documentação completa da IFrame Player Factory para todos os parâmetros de criação, e a documentação de eventos para eventos do player.

Tipos TypeScript

Uma biblioteca com tipos TypeScript está disponível:

npm install @kinescope/player-iframe-api-loader

Veja mais sobre a biblioteca e tipos no GitHub .

Recomendações

Não armazene o objeto do player em uma variável global — isso pode criar problemas de segurança
Use await ou .then() — todos os métodos da API retornam uma Promise
Cancele a assinatura de eventos — ao remover o player, lembre-se de cancelar a assinatura de todos os eventos
Trate erros — assine Events.Error para lidar com erros críticos

Documentação completa

Para informações completas sobre todos os métodos, eventos e parâmetros da API, veja a documentação completa da IFrame Player API .

O que fazer a seguir?

Analytics — colete métricas e vincule-as ao seu contexto (usuário, curso, lição, etc.)
Personalização do player — personalize a aparência e o comportamento do player
Incorporação — incorporação básica do player sem API
Solução de problemas — problemas comuns de API

Ainda tem dúvidas? Escreva para o chat de suporte na interface do Kinescope — nossos especialistas vão ajudar!

IFrame Player API

Para quem é este artigo

Por que usar a IFrame Player API?

O que a IFrame Player API oferece

Controle e eventos

Métricas personalizadas e envio de dados

Parâmetros e cenários

Casos de uso típicos

Sistemas de Gestão de Aprendizado (LMS)

Aplicações interativas

Portais corporativos

Exemplo: Analytics avançado para sistemas de aprendizado

Integrando com a lógica da aplicação

Exemplo: Controle de acesso

Exemplo: Sincronizando com o estado da aplicação

Conectando a API

Exemplo básico de conexão

Criando um player

Parâmetros de criação

Parâmetros principais

Exemplo: Criando um player com configurações

Controle do player

Métodos principais de controle

Reprodução

Obtendo informações

Controle de volume

Controle de CTA

Controle de qualidade

Controle de velocidade de reprodução

Modo tela cheia

Modo picture-in-picture

Exemplo: Usando métodos

Eventos do player

Assinando eventos

Eventos principais

Dados do evento

Exemplo: Trabalhando com eventos

Trabalhando com playlists

Criando uma playlist

Controle de playlist

Call To Action (CTA)

Configurando CTA via IFrame API

Controle programático do CTA

Manipulando eventos de CTA

Tipos TypeScript

Recomendações

Documentação completa

O que fazer a seguir?

Artigos relacionados