Participar de uma sessão — Web

Usando um ID de sessão e um token, você pode se conectar à sessão do OpenTok por meio da biblioteca OpenTok.js.

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

Para obter informações sobre como criar um ID de sessão e um token de autenticação, consulte Criação de sessão e Criação de tokens.

Inicializando um objeto Session

Antes de se conectar a uma sessão, instancie um objeto Session chamando o método OT.initSession() método com o seu Chave da API do OpenTok e o ID da sessão correspondente:

// Replace with your OpenTok API key and session ID:
var session = OT.initSession(apiKey, sessionID);

O OT.initSession() O método retorna um objeto Session, por meio do qual são realizadas as chamadas subsequentes à API.

Observe que chamar o OT.initSession() o método não criar uma sessão do OpenTok; ela cria um objeto Session do JavaScript, que representa uma sessão existente do OpenTok. Você cria uma sessão do OpenTok usando as bibliotecas do OpenTok do lado do servidor. Consulte Criação de uma sessão do OpenTok.

Se o navegador do usuário não for compatível com WebRTC, a chamada para OT.initSession() faz com que a página exiba uma mensagem para o usuário. Para verificar se há suporte ao WebRTC e evitar que essa mensagem seja exibida, você pode chamar o OT.checkSystemRequirements() método antes de chamar OT.initSession():

if (OT.checkSystemRequirements() == 1) {
  var session = OT.initSession(apiKey, sessionId);
} else {
  // The client does not support WebRTC.
  // You can display your own message.
}

Conectando-se a uma sessão

Depois de inicializou um objeto Session, chame-o de connect() método, passando um token e uma função de manipulador de conclusão:

var session = OT.initSession(apiKey, sessionId);
session.connect(token, function(error) {
  if (error) {
    console.log("Error connecting: ", error.name, error.message);
  } else {
    console.log("Connected to the session.");
  }
});

Um objeto de erro é passado para o manipulador de conclusão do connect evento que ocorre quando o cliente não consegue se conectar à sessão do OpenTok. Caso contrário, nenhum objeto de erro é passado, indicando que o cliente se conectou com sucesso à sessão.

O objeto Session também dispara um sessionConnected evento quando o cliente se conecta à sessão do OpenTok. E o objeto OT dispara um exception evento quando ocorre um erro na conexão. No entanto, é mais simples verificar se a conexão foi bem-sucedida passando um manipulador de conclusão para o connect() método, como último parâmetro.

Desconectando-se de uma sessão

Para se desconectar de uma sessão, ligue para o disconnect() método do objeto Session:

session.disconnect();

Detectar quando a conexão foi interrompida

Quando seu cliente se desconecta de uma sessão, o objeto Session dispara um sessionDisconnected evento:

session.on("sessionDisconnected", function (event) {
  // The event is defined by the SessionDisconnectEvent class
  if (event.reason == "networkDisconnected") {
    alert("Your network connection terminated.")
  }
});
session.connect(token);

O reason A propriedade do evento é uma string que descreve o motivo pelo qual a sessão foi desconectada. Por exemplo, o exemplo anterior avisa o usuário caso ele tenha sido desconectado devido ao término da conexão de rede. Para mais detalhes, consulte Event de Desconexão de Sessão.

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). Você não precisa adicionar nenhum código para que os clientes se reconectem automaticamente, a menos que queira responder aos eventos disparados quando o cliente se desconectar e se reconectar. Para ver um código de exemplo que demonstra o uso desses eventos, consulte o opentok-reconexão repositório no GitHub.

Quando a conexão é interrompida e o cliente tenta se reconectar, o objeto Session dispara um reconnecting evento. Quando a conexão é restabelecida, o objeto Session dispara um reconnected evento. Se o cliente não conseguir restabelecer a conexão, ele se desconecta da sessão do OpenTok, e o objeto Session dispara o sessionDisconnected evento.

Em resposta a esses eventos, seu aplicativo pode (opcionalmente) exibir notificações na interface do usuário indicando os estados de desconexão temporária, reconexão e desconexão:

session.on(
  sessionReconnecting: function() {
    // Display a user interface notification.
  },
  sessionReconnected: function() {
    // Adjust user interface.
  },
  sessionDisconnected: function() {
    // Adjust user interface.
  }
);

Quando seu cliente se desconecta temporariamente de uma sessão, os objetos Subscriber nos clientes inscritos em um fluxo publicado por você disparam eventos quando o fluxo publicado é interrompido e quando (e se) ele for retomado automaticamente. Para obter mais informações, consulte Reconexão automática no guia do desenvolvedor “Inscrição em streams”.

Por padrão, quaisquer sinais que você enviar enquanto seu cliente estiver temporariamente desconectado de uma sessão são colocados em fila e enviados quando (e se) você 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 você estiver desconectado. Para obter mais informações, consulte Impedir que sinais sejam enviados durante a reconexão automática.

Detectar quando os clientes se conectam e se desconectam

O objeto Session despacha um connectionCreated evento quando um novo cliente (incluindo o seu próprio) se conecta à sessão. O objeto Session dispara um connectionDestroyed evento quando outros clientes saem da sessão. Esses eventos são definidos pela classe ConnectionEvent, que possui um connection objeto, que é um objeto Connection para a conexão (criada ou encerrada) relacionada ao evento:

var connectionCount;
session.on({
  connectionCreated: function (event) {
    connectionCount++;
    if (event.connection.connectionId != session.connection.connectionId) {
      console.log('Another client connected. ' + connectionCount + ' total.');
    }
  },
  connectionDestroyed: function connectionDestroyedHandler(event) {
    connectionCount--;
    console.log('A client disconnected. ' + connectionCount + ' total.');
  }
});
session.connect(token, function (error) {
  if (error) {
    console.log("Failed to connect.");
  } else {
    console.log('You have connected to the session.');
  }
});

Solução de problemas de conexão com a sessão

O Session.connect() O método possui uma função de retorno de chamada à qual é passado um parâmetro opcional error parâmetro. Se esse parâmetro estiver presente e definido (não null ou indefinido), então ocorreu um erro durante a conexão. Procurar por esse erro no seu código ajudará você a entender por que o usuário final não conseguiu se conectar:

session.connect(token, function(err) {
  if (err) {
    // handle error
  } else {
    // connection succeeded
  }
});

Grande parte dos erros que ocorrem ao tentar se conectar se deve a tokens inválidos ou vencidos. Certifique-se de seguir as práticas recomendadas para o uso de tokens descritas aqui.

Outro motivo comum para a falha na conexão a uma sessão está relacionado à conexão à Internet do usuário final. Exemplos disso incluem:

  • O usuário final perdeu a conexão com a internet
  • O usuário final tem as portas comuns bloqueadas porque está em uma rede restritiva.

Isso resultará em um erro com o código 1006. Recomendamos que você lide com essa situação usando o código abaixo. Outras razões para a falha na conexão com uma sessão incluem a indisponibilidade dos servidores do OpenTok ou a ocorrência de algum tipo de erro inesperado (como um erro de nível 500 no servidor). Embora isso não aconteça com frequência, é uma boa prática tratar esses erros.

Se você seguir essas instruções, seu código de tratamento de erros deverá ficar mais ou menos assim:

session.connect(token, function(err) {
  if (err) {
    if (err.name === "OT_NOT_CONNECTED") {
      showMessage('Failed to connect. Please check your connection and try connecting again.');
    } else {
      showMessage('An unknown error occurred connecting. Please try again later.');
    }
  }
});

É possível que você perca a conexão depois de já ter se conectado com sucesso a uma sessão. Você pode lidar com essa situação ficando atento ao sessionDisconnected evento com o motivo “networkDisconnected”:

session.on({
  sessionDisconnected: function(event) {
    if (event.reason === 'networkDisconnected') {
      showMessage('You lost your internet connection.'
        + 'Please check your connection and try connecting again.');
    }
  }
});

Juntando tudo isso

O código a seguir inclui um connect() método, que se conecta a uma sessão. Uma vez conectado, o código rastreia quando os clientes entram e saem da sessão. Ele também possui um método para se desconectar da sessão:

var session;
var connectionCount = 0;

function connect() {
  // Replace apiKey and sessionId with your own values:
  session = OT.initSession(apiKey, sessionId);
  session.on({
    connectionCreated: function (event) {
      connectionCount++;
      console.log(connectionCount + ' connections.');
    },
    connectionDestroyed: function (event) {
      connectionCount--;
      console.log(connectionCount + ' connections.');
    },
    sessionDisconnected: function sessionDisconnectHandler(event) {
      // The event is defined by the SessionDisconnectEvent class
      console.log('Disconnected from the session.');
      document.getElementById('disconnectBtn').style.display = 'none';
      if (event.reason == 'networkDisconnected') {
        alert('Your network connection terminated.')
      }
    }
  });
  // Replace token with your own value:
  session.connect(token, function(error) {
    if (error) {
      console.log('Unable to connect: ', error.message);
    } else {
      document.getElementById('disconnectBtn').style.display = 'block';
      console.log('Connected to the session.');
      connectionCount = 1;
    }
  });
}

function disconnect() {
  session.disconnect();
}

connect();