Como funcionam os eventos na Video API

A Video API da Vonage é orientada a eventos: toda alteração em uma sessão, transmissão ou módulo opcional gera callbacks documentados para os objetos do Client SDK do cliente (Session, Publisher, Subscriber) e para quaisquer endpoints do servidor que você registrar. Ao associar manipuladores a esses callbacks — e analisá-los posteriormente com ferramentas como o Video Inspector ou o Archiving Inspector —, você pode reagir imediatamente, manter os participantes informados e manter um registro de auditoria do estado da sessão.

Fluxo do evento em uma sessão de vídeo

1. Conecte-se e participe: Um cliente se conecta a uma sessão e começa a publicar ou a se inscrever em fluxos.
2. Emitar eventos do ciclo de vida: Objetos SDK (Session, Publisher, Subscriber, Stream) e módulos opcionais — tais como arquivamento, transmissão/transmissão ao vivo, compositor experiente, legendas em tempo real, transcrição, e Interconexão SIP — enviar eventos que descrevem o ciclo de vida e as alterações na mídia (consulte a tabela de módulos opcionais abaixo para ver o catálogo completo).
3. Eventos de despacho: A nuvem da Vonage encaminha eventos para outros participantes e, quando configurada, para seus pontos de extremidade de webhook.
4. React no seu aplicativo: Atualize o estado da interface do usuário no cliente, acione a lógica de negócios no servidor e registre eventos relevantes para análise posterior. Juntas, essas funcionalidades permitem que você observe, responda e se recupere dinamicamente — tudo por meio de um modelo de eventos unificado.

De onde vêm os eventos em vídeo

SDKs de cliente

Sessão

• Ciclo de vida: sessionConnected, connectionDestroyed.
• Alterações no fluxo: streamCreated, streamPropertyChanged.
• Sinalização: signal, signal:type.
• Módulos opcionais: Callbacks voltados para o cliente para arquivamento, transcrição, legendas em tempo real e controle de transmissão. Consulte os guias dos módulos nos links abaixo para obter informações completas.

Editora

• O estado da mídia: videoEnabled / videoDisabled, audioEnabled / audioDisabled.
• Rede/qualidade: networkQualityLevelChanged, videoDisableWarning.
• Módulos opcionais: Solicitações de permissão do dispositivo (accessDialogOpened, accessDenied) e diagnósticos (audioLevelUpdated) estão disponíveis nos guias de publicação.

Assinante

• O estado da mídia: videoEnabled / videoDisabled.
• Rede/qualidade: videoDisableWarning, videoDisableWarningLifted.
• Módulos opcionais: audioLevelUpdated, callbacks de layout e outros recursos de auxílio aos assinantes são apresentados nos guias de personalização.

Famílias de callbacks

Ferramentas de observabilidade

• Inspecionador de Vídeos exibe as linhas do tempo dos eventos da sessão para fins de depuração.
• Inspetor de Arquivamento apresenta uma linha do tempo das alterações no status de arquivamento para os fluxos de trabalho de arquivamento.
• API do Insights e Relatórios de uso de vídeos contagens agregadas de eventos para análise.
• O Guia de monitoramento de sessões explica como monitorar o início e o término das sessões e como exibir o estado atual da sessão para as equipes operacionais (por exemplo, em seus próprios painéis).

Trabalhando com manipuladores de eventos do cliente

Os padrões de manipuladores de eventos são semelhantes entre os SDKs. O exemplo a seguir mostra o SDK do JavaScript:

session.on('streamCreated', event => {
  const stream = event.stream;
  session.subscribe(stream, 'subscriberContainer', {
    insertMode: 'append',
    width: '100%',
    height: '100%'
  });
});

publisher.on('networkQualityLevelChanged', event => {
  updateNetworkBadge(event.networkQualityLevel);
});

session.on('signal:layout', event => {
  applyLayout(event.data);
});

Aplique o mesmo padrão aos SDKs nativos: iOS (OTSessionDelegate), Android (Session.SessionListener), Windows (Session manipuladores de eventos) e Linux (otc_session_callbacks) ao vincular os observadores equivalentes para cada plataforma.

Para obter listas completas de eventos, consulte as referências da plataforma: Eventos de sessão em JavaScript, iOS OTSessionDelegate callbacks, Android Session.SessionListener, API de sessão do Windows, e Callbacks de sessão no Linux.

Tratamento de callbacks do servidor

• Registre os URLs de retorno de chamada no Painel da Video API da Vonage ou pelo API REST de vídeo.
• Valide as solicitações recebidas, implemente novas tentativas e analise a política de assinatura/retrocesso descrita em Verificação de webhooks.
• Processe cargas de trabalho rapidamente: coloque as tarefas na fila e responda com 200 OK para evitar que as tentativas repetidas bloqueiem sua fila.
• Registre os corpos das solicitações juntamente com metadados, como ID da sessão, ID da conexão e ID do fluxo, para que você possa correlacionar as respostas do servidor com os eventos do lado do cliente.

Escolhendo onde React

• Lidar com atualizações temporárias da experiência do usuário (UX) no cliente: Use os eventos do SDK para ativar ou desativar indicadores da interface do usuário (ícones de mudo, banners de reconexão) ou solicitar que o usuário atualize a página.
• Encaminhar problemas persistentes para o servidor: Encaminhe falhas de fluxo ou de conexão para o seu backend a fim de alertar os operadores ou acionar fluxos de trabalho automatizados.
• Permanência dos dados de Audit: Armazenar callbacks críticos (por exemplo sessionDestroyed, arquivo failed) para análises de conformidade e pós-incidente.
• Teste com ferramentas: Reproduza os problemas executando os logs de sessão no Inspecionador de Vídeos ou exportar métricas por meio do API do Insights.

Guia rápido de referência de eventos

Recursos adicionais

• Participar de uma sessão
• Transmissões de publicação
• Guia de sinalização
• Guia de monitoramento de sessões
• Reserva de áudio e resiliência de rede
• Verificação de webhooks