Publicar: Diagnósticos

Este guia explica como coletar dados de diagnóstico para editores e resolver problemas comuns.

Como obter estatísticas sobre o stream de um editor

O SDK de vídeo da Vonage disponibiliza métricas detalhadas sobre a qualidade do fluxo por meio de uma API de estatísticas de alto nível — recomendada para a maioria dos casos de uso —, que fornece estatísticas de áudio, vídeo, rede e do lado do remetente de forma unificada e sensível à sessão, mantendo-se estável durante as transições entre conexões entre pares. Para depuração avançada, o SDK também oferece acesso ao relatório bruto de estatísticas do WebRTC, que reflete dados não processados das conexões entre pares.

Consulte Guia do desenvolvedor sobre observabilidade do cliente para obter informações detalhadas.

Transmissão de teste

Você pode publicar uma transmissão de teste e verificar suas estatísticas de áudio e vídeo para determinar o tipo de transmissão (como alta resolução ou somente áudio) compatível com a sua conexão.

Para obter estatísticas de um stream publicado pelo cliente local, é necessário usar uma sessão que utilize o Media Router (sessões com o modo de mídia definido como “routed”) e definir o testNetwork propriedade para true no options objeto que você passa para o Session.subscribe() método. Em seguida, você pode usar o getStats() método do objeto Subscriber para obter estatísticas de áudio e vídeo da transmissão que você publica.

Melhores práticas na publicação

Esta seção traz dicas para publicar transmissões com sucesso.

Permitir o acesso ao dispositivo

É recomendável informar aos usuários que será solicitado que eles autorizem o acesso à câmera e ao microfone.

Constatamos que, de longe, a maior parte das falhas na publicação se deve ao fato de os usuários clicarem no botão “recusar” ou simplesmente não clicarem no botão “permitir”. Disponibilizamos todos os eventos necessários para que você possa orientar seus usuários nesse processo:

publisher.on({
  accessDialogOpened: function (event) {
    // Show allow camera message
    pleaseAllowCamera.style.display = 'block';
  },
  accessDialogClosed: function (event) {
    // Hide allow camera message
    pleaseAllowCamera.style.display = 'none';
  }
});

Também é uma boa ideia hospedar seu site por SSL. Isso porque o Chrome exige que os usuários cliquem para permitir o acesso aos dispositivos apenas uma vez por domínio, desde que esse domínio seja hospedado por SSL. Isso significa que seus usuários (se estiverem no Chrome) não precisam lidar com aquela caixa de diálogo inconveniente de permissão/recusa toda vez que carregarem a página.

Separar OT.initPublisher() e Session.publish()

Outra coisa que recomendamos é dividir o OT.initPublisher() e Session.publish() etapas. Isso agiliza o tempo de conexão inicial, pois você se conecta à sessão enquanto aguarda que o usuário clique no botão “Permitir”. Portanto, em vez de:

session.connect(token, function (err) {
{... your error handling code ...}
if (!err) {
    var publisher = OT.initPublisher();
    session.publish(publisher);
  }
});

Mova o OT.initPublisher() siga este passo antes de se conectar, conforme mostrado a seguir:

var publisher = OT.initPublisher();
session.connect(token, function (err) {
{... your error handling code ...}
  if (!err) {
    session.publish(publisher);
  }
});

Resolução e taxa de quadros

É possível definir a resolução e a taxa de quadros do Publisher ao inicializá-lo:

OT.initPublisher(divId, {
  resolution: '320x240',
  frameRate: 15
});

Por padrão, a resolução de um Publisher é 640x480, mas você também pode defini-la como 1920x1080, 1280x720 ou 320x240. É recomendável tentar ajustar a resolução ao tamanho em que o vídeo será exibido. Se você estiver exibindo o vídeo apenas em 320x240 pixels, não faz sentido transmitir em 1280x720 ou 1920x1080. Reduzir a resolução pode economizar largura de banda e diminuir o congestionamento e as quedas de conexão.

Por padrão, a taxa de quadros do vídeo é de 30 quadros por segundo, mas você também pode defini-la para 15, 7 ou 1. Reduzir a taxa de quadros pode diminuir a largura de banda necessária. Vídeos com resolução menor podem ter uma taxa de quadros mais baixa sem que haja uma diferença perceptível para o usuário. Portanto, se você estiver usando uma resolução baixa, talvez seja interessante considerar o uso de uma taxa de quadros baixa também.

Solução de problemas

Siga as dicas desta seção para evitar problemas de conectividade ao publicar. Para obter informações gerais sobre solução de problemas, consulte Depuração — Web.

Tratamento de erros

Existem métodos de retorno de chamada para ambos Session.publish() e OT.initPublisher(). Recomendamos tratar as respostas de erro desses dois métodos. Conforme mencionado anteriormente, é melhor dividir essas etapas e chamar OT.initPublisher() antes de iniciar a conexão com sua sessão. Além disso, o tratamento de erros fica mais fácil se você não chamar esses dois métodos ao mesmo tempo. Isso porque ambos os manipuladores de erros serão acionados caso ocorra algum erro na publicação. É melhor aguardar até que OT.initPublisher() para concluir e Session.connect() preencher e, em seguida, ligar Session.publish(). Dessa forma, você pode lidar com todos os problemas relacionados ao hardware no OT.initPublisher() callback e todos os problemas relacionados à rede no Session.publish() chamada de retorno.

var connected = false,
  publisherInitialized = false;

var publisher = OT.initPublisher(function(err) {
  if (err) {
    // handle error
  } else {
    publisherInitialized = true;
    publish();
  }
});

var publish = function() {
  if (connected && publisherInitialized) {
    session.publish(publisher);
  }
};

session.connect(token, function(err) {
  if (err) {
    // handle error
  } else {
    connected = true;
    publish();
  }
});

Acesso negado

O maior número de casos em que não se conseguiu OT.initPublisher() são resultado da recusa do usuário final em conceder acesso à câmera e ao microfone. Isso pode ser resolvido monitorando o accessDenied evento ou ao detectar uma resposta de erro no método OT.initPublisher() com um code propriedade definida como 1500 e um message propriedade definida como “Acesso do editor negado:”. Recomendamos que você trate dessa situação e exiba uma mensagem ao usuário indicando que ele deve tentar publicar novamente e permitir o acesso à câmera.

publisher.on({
  'accessDenied': function() {
    showMessage('Please allow access to the Camera and Microphone and try publishing again.');
  }
});

Acesso ao dispositivo

Outra razão para OT.initPublisher() A falha ocorre quando o OpenTok não consegue acessar uma câmera ou um microfone. Isso pode acontecer se não houver uma câmera ou um microfone conectado ao computador, se houver algum problema com o driver da câmera ou do microfone, ou se algum outro aplicativo estiver usando a câmera ou o microfone (isso só ocorre no Windows). Você pode tentar minimizar a ocorrência desses problemas usando nosso Componente de Configuração de Hardware ou ligando para o OT.getDevices() método diretamente. No entanto, você também deve tratar qualquer erro ao chamar OT.initPublisher() porque ainda pode dar algo errado. Por exemplo, o usuário pode ter negado o acesso à câmera ou ao microfone. Nesse caso, o error.name a propriedade está definida como "OT_USER_MEDIA_ACCESS_DENIED":

publisher = OT.initPublisher('publisher', {}, function (err) {
  if (err) {
    if (err.name === 'OT_USER_MEDIA_ACCESS_DENIED') {
      // Access denied can also be handled by the accessDenied event
      showMessage('Please allow access to the Camera and Microphone and try publishing again.');
    } else {
      showMessage('Failed to get access to your camera or microphone. Please check that your webcam'
        + ' is connected and not being used by another application and try again.');
    }
    publisher.destroy();
    publisher = null;
  }
});

Erros de rede

As outras causas de falhas na publicação geralmente se devem a algum tipo de falha na rede. Lidamos com elas na função de retorno de chamada para Session.publish(). Se o usuário não estiver conectado à rede, é passado à função de retorno de chamada um objeto de erro com o name propriedade definida como "OT_NOT_CONNECTED". Se o usuário estiver em uma conexão de rede muito restritiva que não permita conexões WebRTC, o Publisher não conseguirá se conectar, e o elemento Publisher exibirá uma roda giratória. Esse erro tem um name propriedade definida como "OT_CREATE_PEER_CONNECTION_FAILED". Nesse caso, recomendamos que você exiba uma mensagem ao usuário informando que a publicação não foi bem-sucedida e que ele deve verificar sua conexão de rede. O tratamento desses erros é feito da seguinte forma:

session.publish(publisher, function(err) {
  if (err) {
    switch (err.name) {
      case "OT_NOT_CONNECTED":
        showMessage("Publishing your video failed. You are not connected to the internet.");
        break;
      case "OT_CREATE_PEER_CONNECTION_FAILED":
        showMessage("Publishing your video failed. This could be due to a restrictive firewall.");
        break;
      default:
        showMessage("An unknown error occurred while trying to publish your video. Please try again later.");
    }
    publisher.destroy();
    publisher = null;
  }
});

Perda de conectividade

Seu Publisher também pode perder a conexão depois de já ter conseguido se conectar. Na maioria das vezes, isso também fará com que a sessão perca a conexão, mas nem sempre é assim. Você pode lidar com a desconexão do Publisher monitorando o streamDestroyed evento com um reason propriedade definida como “networkDisconnected” desta forma:

publisher.on({
  streamDestroyed: function (event) {
    if (event.reason === 'networkDisconnected') {
      showMessage('Your publisher lost its connection. Please check your internet connection and try publishing again.');
    }
  }
});