Sinalização — Web

Use a API de sinalização do OpenTok para enviar texto e dados entre clientes conectados a uma sessão do OpenTok.

Para obter informações conceituais sobre a API de sinalização do OpenTok, consulte o Visão geral da sinalização guia do desenvolvedor.

Este tópico inclui as seguintes seções:

Envio de um sinal para um cliente específico em uma sessão

Para enviar um sinal a um cliente específico em uma sessão, chame a função signal() método do objeto Session e definir o to propriedade do signal parâmetro:

session.signal(
  {
    to: connection1,
    data:"hello"
  },
  function(error) {
    if (error) {
      console.log("signal error ("
                   + error.name
                   + "): " + error.message);
    } else {
      console.log("signal sent.");
    }
  }
);

O to propriedade é uma Conexão objeto correspondente aos clientes conectados à sessão à qual você deseja enviar um sinal. Você obtém referências aos objetos Connection quando o objeto Session despacha sessionConnected e connectionCreated eventos. Você também pode obter o objeto Connection correspondente a um fluxo recuperando o connection propriedade do objeto Stream.

O data propriedade do signal O parâmetro é a sequência de dados que você envia junto com a mensagem. Essa propriedade é opcional. Se você a omitir, a mensagem será enviada sem carga útil de dados. O limite para o tamanho dos dados é de 8 KB.

O completerHandler parâmetro do signal() O método é chamado quando a chamada ao método é bem-sucedida ou falha. O error o parâmetro passado para o manipulador de conclusão é definido como null se a chamada for bem-sucedida. Quando a chamada ao método falha, o objeto de erro possui as seguintes propriedades: code (um código de erro numérico), message (uma sequência de caracteres que descreve o erro), e signal (um objeto correspondente ao signal parâmetro passado para o signal() método).

Além disso, você pode passar um type propriedade do signal parâmetro. Trata-se de um valor de cadeia de caracteres que os clientes podem usar para filtrar quando ficar atento aos sinais:

session.signal(
  {
    data:"hello",
    type:"textMessage"
  },
  function(error) {
    if (error) {
      console.log("signal error ("
                   + error.name
                   + "): " + error.message);
    } else {
      console.log("signal sent.");
    }
  }
);

O comprimento máximo do type A sequência de caracteres tem 128 bytes e deve conter apenas letras (A-Z e a-z), números (0-9), '-', '_' e '~'.

Para obter mais detalhes, consulte a documentação do Session.signal() método.

Envio de um sinal para todos os clientes em uma sessão

Para enviar um sinal a todos os clientes em uma sessão, chame a função signal() método do objeto Session, mas não definir um to propriedade para o signal parâmetro:

session.signal(
  {
    data:"hello"
  },
  function(error) {
    if (error) {
      console.log("signal error ("
                   + error.name
                   + "): " + error.message);
    } else {
      console.log("signal sent.");
    }
  }
);

Para obter detalhes sobre as outras opções que você passa para o signal() método, consulte a seção anterior.

Chamar esse método sem limitar o conjunto de clientes destinatários resultará no envio de vários sinais (um para cada cliente na sessão).

Recebimento de sinais em uma sessão

Para começar a receber todos os sinais enviados em uma sessão, adicione um ouvinte de eventos para o signal evento, disparado pelo objeto Session:

    session.on("signal", function(event) {
      console.log("Signal sent from connection " + event.from.id);
      // Process the event.data property, if there is any data.
    });

Você também pode monitorar apenas sinais definidos como um tipo específico. (É possível definir o tipo de um sinal, opcionalmente, ao enviar um sinal.) Registrar um ouvinte de evento para o signal:type evento, substituindo “type” pela string do tipo. Por exemplo, o código a seguir escuta sinais do tipo “foo”:

session.on("signal:foo", function(event) {
 console.log("Signal sent from connection " + event.from.id);
 // Process the event.data property, if there is any data.
});

Você pode comparar o from propriedade do objeto do evento com o connection propriedade do objeto Session para verificar se o sinal foi enviado pelo seu cliente ou por outro:

session.on("signal:foo", function(event) {
  if (connection && event.from.connectionId != session.connection.id) {
    // Signal received from another client
  }
}

Observe que você pode usar um Chamada à API REST para enviar um sinal a partir do seu servidor, em vez de a partir de um cliente conectado à sessão. Nesse caso, o from a propriedade do objeto do evento está definida como null.

Impedir que sinais sejam enviados durante a reconexão automática

Os clientes tentarão se reconectar automaticamente a uma sessão da qual tenham se desconectado inesperadamente (por exemplo, devido a uma queda na conectividade de rede). Por padrão, quaisquer sinais que você enviar enquanto o cliente estiver temporariamente desconectado de uma sessão são colocados em fila e enviados quando (e se) ele se reconectar com sucesso. Você pode definir o retryAfterReconnect propriedade para false nas opções que você passa para o Session.signal() método para evitar que os sinais fiquem na fila enquanto o cliente estiver desconectado. Para obter mais informações, consulte Reconexão automática.