Migração da versão 1.0 da biblioteca OpenTok.js

O versão mais recente da biblioteca OpenTok.js utiliza WebRTC em vez do Adobe Flash para comunicações de áudio e vídeo. Este guia ajuda você a migrar seu site da versão 1.0 para a versão mais recente da biblioteca OpenTok.js.

A versão mais recente da biblioteca OpenTok.js interage com os aplicativos por meio das seguintes bibliotecas do OpenTok:

• O SDK do OpenTok para Android 2.3+
• O SDK do OpenTok para iOS 2.3+

Se você estiver migrando código da versão 2.0, consulte esta página.

• Carregando a versão mais recente da biblioteca OpenTok.js
• Modos de mídia para criação de sessões
• Migração para a versão mais recente da biblioteca OpenTok.js
• Novos recursos

Carregando a versão mais recente da biblioteca OpenTok.js

Defina o src atributo do script Adicione a tag à seguinte URL para carregar a versão mais recente da biblioteca OpenTok.js:

<script src="https://static.opentok.com/v2/js/opentok.min.js"></script>

Criação de sessões e modos de mídia

É necessário criar novas sessões para uso na nova biblioteca OpenTok.js. As sessões que eram utilizadas anteriormente no OpenTok 1.0 não podem ser usadas na versão mais recente do OpenTok.

Na versão 1.0, os fluxos eram enviados diretamente entre os clientes (ponto a ponto) ou por meio do OpenTok Media Router. Ao criar uma sessão para a versão 1.0, utilizando um dos SDKs de servidor do OpenTok, você definia um p2p.preference parâmetro para "enabled" ou "disabled". Isso muda na versão mais recente do OpenTok.

Agora, ao criar uma sessão, você especifica como os clientes nessa sessão enviarão fluxos de áudio e vídeo, conhecidos como modo de mídia. Existem duas opções:

• Repassado — Em uma sessão retransmitida, os clientes tentarão enviar fluxos de áudio e vídeo diretamente entre si (ponto a ponto). No entanto, se os clientes não conseguirem se conectar devido a restrições de firewall, a sessão utilizará o servidor TURN da OpenTok para retransmitir os fluxos de áudio e vídeo. (Antes da versão 2.2, os SDKs do servidor OpenTok se referiam a essas sessões como sessões ponto a ponto. No entanto, mesmo ao usar esses SDKs, as sessões ainda utilizarão o servidor TURN do OpenTok para retransmitir os fluxos caso restrições de firewall bloqueiem a transmissão ponto a ponto.)

• Encaminhado — A sessão utiliza o OpenTok Media Router para encaminhar fluxos de áudio e vídeo entre os clientes. O Roteador de mídia OpenTok oferece os seguintes benefícios:

  • O OpenTok Media Router pode reduzir o uso de largura de banda em sessões com vários participantes. (Quando a propriedade “media mode” está definida como “relayed”, cada cliente deve enviar um fluxo de áudio e vídeo separado para cada cliente que o esteja recebendo.)
  • O OpenTok Media Router pode melhorar a qualidade da experiência do usuário por meio de solução alternativa para áudio e recuperação de vídeo. Com esse recurso, se a conectividade de um cliente se deteriorar a ponto de não suportar o vídeo de uma transmissão à qual ele está inscrito, o vídeo é interrompido nesse cliente (sem afetar os demais clientes), e o cliente passa a receber apenas o áudio. Se a conectividade do cliente melhorar, o vídeo é restabelecido.
  • O OpenTok Media Router é compatível com o Recurso de arquivamento do OpenTok 2.0, que permite gravar, salvar e recuperar sessões do OpenTok.

Observação: Nas novas versões dos SDKs de servidor do OpenTok, o modo de mídia padrão é o retransmitido. (Nas versões anteriores, o padrão era usar o OpenTok Media Router.)

<script src="https://static.opentok.com/v2/js/opentok.min.js"></script>

Migração para a versão mais recente da biblioteca OpenTok.js

Importante: A versão mais recente da biblioteca OpenTok.js inclui alterações que não são compatíveis com o OpenTok.js 1.0. Esta seção mostra como adaptar o código existente para funcionar com a versão mais recente da biblioteca OpenTok.js.

API removida

As seguintes classes, propriedades, métodos e eventos da versão 1.0 não estão incluídos na versão mais recente do OpenTok.js.

Obsoleto

O objeto OT

O objeto TB foi renomeado para OT (de OpenTok). Observe também que a URL da biblioteca OpenTok.js agora aponta para o arquivo opentok.min.js:

<script src="https://static.opentok.com/v2/js/opentok.min.js"></script>

No entanto, por uma questão de compatibilidade com versões anteriores, o objeto TB do JavaScript continuará funcionando, e a URL TB.min.js também continuará funcionando.

Conectando-se a uma sessão

Na versão mais recente da biblioteca OpenTok.js, você passa sua chave de API para o OT.initSession() método (como primeiro parâmetro):

var session = OT.initSession(apiKey, sessionId);
session.connect(token, function(error) {
  if (!error) {
    var publisher OT.initPublisher();
    session.publish(publisher);
  }
});

Observe que o Session.connect() método e o OT.initPublisher() O método não aceita uma chave de API como parâmetro, já que você passa a chave de API para o OT.initSession() método. (No entanto, a sintaxe antiga ainda é compatível.)

Alterações que exigem atualização

Procuramos manter a compatibilidade com versões anteriores da biblioteca JavaScript do OpenTok 1.0. No entanto, algumas das alterações na API exigem algumas modificações no código para aplicativos portados da versão 1.0.

Alterações nos eventos de stream para streams publicados pelo seu cliente

O objeto Session não realiza o despacho streamCreated eventos para transmissões ao vivo próprio o cliente publica. Para detectar quando um fluxo é criado para o seu Publisher, adicione um manipulador de conclusão para o Session.publish() método:

var publisher = session.publish(publisher, properties, function(error) {
  if (error) {
    console.log("Failed to publish.")
  } else {
    console.log("Stream publishing.")
  }
})

O objeto Publisher também dispara um streamCreated evento para o stream que ele publica.

Além disso, o objeto Publisher (e não o objeto Session) agora despacha streamDestroyed eventos para o fluxo que ele publica. Se você quiser manter o Publisher no DOM HTML (para reutilização), chame o preventDefault() método no ouvinte de eventos para o streamDestroyed evento disparado pelo Publisher:

publisher = OT.initPublisher(apiKey)
  .on("streamDestroyed", function(event) {
    event.preventDefault(); // This lets you reuse the Publisher.
  }
);

Chamando o preventDefault() método do streamDestroyed e sessionDisconnected Os objetos de evento disparados pelo objeto Session não impedem mais que o objeto Publisher seja removido (como acontecia na versão 1.0).

Para mais detalhes, consulte Alterações nos eventos de fluxo e conexão.

Detecção de fluxos e conexões iniciais em uma sessão

Na biblioteca OpenTok.js atual, o connections e streams propriedade do sessionConnected Os eventos estão obsoletos e são definidos como matrizes vazias. O objeto Session despacha connectionCreated e streamCreated eventos para cada cliente e fluxo na sessão, tanto no momento da conexão quanto após a conexão.

Para verificar se havia outro cliente na sessão no momento em que você se conectou, compare o connection.creationTime propriedade do connectionCreated objeto de evento com o connection.creationTime propriedade do objeto Session:

session.on("connectionCreated", function(event) {
  if (event.connection.creationTime <= session.connection.creationTime) {
    console.log("Detected a client that connected before you.")
  }
}

Para mais detalhes, consulte Alterações nos eventos de fluxo e conexão.

API de sinalização aprimorada

Na versão 1.0, o Session.signal() Esse método simplesmente envia um ping a todos os clientes conectados à sessão. A versão mais recente da biblioteca OpenTok.js apresenta uma nova API de sinalização, com mais recursos. Agora é possível incluir uma sequência de dados no sinal e enviar o sinal para toda a sessão ou para clientes específicos conectados à sessão. Para mais detalhes, consulte o JavaScript Tutorial sobre sinalização.

Outras alterações e novos recursos

Para saber mais sobre outras alterações e começar a aproveitar outros novos recursos, consulte Novos recursos.

Novos recursos

• Controle de qualidade inteligente—Agora é possível definir uma resolução e uma taxa de quadros recomendadas para uma transmissão publicada. Também é possível reduzir o uso de largura de banda da transmissão de vídeo de um assinante.
• Manipuladores de conclusão para métodos—Alguns métodos da biblioteca OpenTok.js agora incluem um completionHandler parâmetro. Esse parâmetro é uma função que é chamada quando o método é executado com sucesso ou falha.
• Novos métodos de inscrição em eventos—A versão mais recente da biblioteca OpenTok.js inclui novos métodos — on(), once(), e off() — para adicionar e remover ouvintes de eventos.
• Alterações nos eventos de fluxo e conexão—A biblioteca OpenTok.js inclui melhorias nos eventos relacionados a transmissões e aos clientes que entram e saem das sessões do OpenTok.
• APIs DOM do Publisher e do Subscriber—Existem novas APIs para a inserção e remoção de Publisher e Subscriber no DOM HTML.
• Nova propriedade Publisher.accessAllowed—O accessAllowed Essa propriedade permite verificar se um cliente autorizou o acesso à câmera e ao microfone.

Nova API

Controle de qualidade inteligente

A versão mais recente da biblioteca OpenTok.js traz novos recursos para definir a resolução de vídeo e a taxa de quadros recomendadas para uma transmissão publicada.

Para definir uma resolução de vídeo recomendada para uma transmissão publicada, defina o resolution propriedade do properties parâmetro que você passa para o OT.initPublisher() método:

var publisherProperties = {resolution: "1280x720"};
var publisher = OT.initPublisher(apiKey, targetElement, publisherProperties);

Isso resolution A propriedade é uma string que define a resolução desejada do vídeo. O formato da string é "widthxheight", em que a largura e a altura são representadas em pixels. Os valores válidos são "1280x720", "640x480", e "320x240".

A resolução solicitada para uma transmissão de vídeo é definida como a videoDimensions.width e videoDimensions.height propriedades do objeto Stream.

A resolução padrão para uma transmissão (caso você não especifique uma resolução) é de 640x480 pixels. Se o sistema do cliente não for compatível com a resolução solicitada, a transmissão utilizará a próxima configuração maior compatível.

Para definir uma taxa de quadros recomendada para uma transmissão publicada, defina o frameRate propriedade do properties parâmetro que você passa para o OT.initPublisher() método:

var publisherProperties = {frameRate: 7};
var publisher = OT.initPublisher(apiKey, targetElement, publisherProperties);

Defina o valor correspondente à taxa de quadros desejada, em quadros por segundo, do vídeo. Os valores válidos são 30, 15, 7 e 1.

Se o editor especificar uma taxa de quadros, a taxa de quadros real do fluxo de vídeo é definida como a frameRate propriedade do objeto Stream, embora a taxa de quadros real varie de acordo com as condições variáveis da rede e do sistema. Se o desenvolvedor não especificar uma taxa de quadros, essa propriedade fica indefinida.

Para sessões que utilizam o OpenTok Media Router (sessões com o modo de mídia (configurado como “routed”), diminuir a taxa de quadros ou a resolução reduz a largura de banda máxima que a transmissão pode utilizar. No entanto, em sessões que possuem o modo de mídia Se estiver configurado para retransmissão, reduzir a taxa de quadros ou a resolução pode não diminuir a largura de banda da transmissão.

Você também pode restringir a taxa de quadros do fluxo de vídeo de um assinante. Para restringir a taxa de quadros de um assinante, chame a função restrictFrameRate() método do assinante, passando true:

mySubscriber.restrictFrameRate(true);

Passe para false e a taxa de quadros do fluxo de vídeo não é limitada:

mySubscriber.restrictFrameRate(false);

Quando a taxa de quadros é limitada, o quadro de vídeo do Assinante será atualizado uma vez ou menos por segundo.

Esse recurso está disponível apenas nas sessões modo de mídia definido como “routed”, e não em sessões com o modo de mídia definido como “relayed”. Em sessões “relayed”, a chamada a este método não produz efeito.

A restrição da taxa de quadros do assinante traz os seguintes benefícios:

• Isso reduz o uso da CPU.
• Isso reduz a largura de banda da rede consumida pelo aplicativo.
• Isso permite que você assine mais canais simultaneamente.

A redução da taxa de quadros de um assinante não afeta a taxa de quadros do vídeo em outros clientes.

Por fim, em sessões que utilizam o OpenTok Media Router, um assinante pode passar para o modo somente áudio quando o OpenTok Media Router determinar que as condições de rede do cliente não suportam vídeo. Esse recurso não estava disponível no OpenTok.js 1.0. Na versão mais recente da biblioteca OpenTok, se a conectividade de rede do cliente melhorar o suficiente para suportar vídeo, o cliente envia um videoEnabled evento, e o vídeo continua.

Manipuladores de conclusão para métodos

Alguns métodos da biblioteca OpenTok.js agora incluem um novo completionHandler parâmetro. Para esse parâmetro opcional, é possível passar uma função que será chamada caso o método seja bem-sucedido ou falhe.

Por exemplo, o connect() O método de um objeto Session agora inclui um parâmetro chamado completionHandler. Esse é o último parâmetro do método. Essa função recebe um parâmetro — error. Se for bem-sucedido, o completionHandler A função não recebe nenhum argumento. Em caso de erro, é passado à função um error parâmetro de objeto. O error O objeto possui duas propriedades: code (um número inteiro) e message (uma sequência de caracteres), que identifica a causa da falha. O código a seguir adiciona um completionHandler ao chamar o connect() método:

// Set apiKey and token to your API key and a token for the session.
session.connect(apiKey, token, function(error) {
  if (error) {
    console.log(error.message);
  } else {
    console.log("Connected to session.");
  }
});

Observe que, ao se conectar à sessão, o objeto Session dispara um sessionConnected evento, além de chamar o completionHandler. No entanto, o completionHandler Na biblioteca OpenTok.js, há uma maneira padrão de verificar se uma chamada de método foi bem-sucedida ou falhou.

Cada um dos métodos a seguir inclui um completionHander parâmetro, como último parâmetro do método:

• OT.initPublisher()
• Session.connect()
• Session.forceDisconnect()
• Session.forceUnpublish()
• Session.publish()
• Session.signal()
• Session.subscribe()

Verifique o message propriedade para obter mais detalhes sobre o erro.

Em caso de erro, o code valor do error O parâmetro é definido como um objeto Error. Para obter mais informações, consulte a documentação do OpenTok Classe de erro.

Novos métodos de inscrição em eventos

A biblioteca OpenTok.js agora inclui novos métodos — on(), once(), e off() — para adicionar e remover ouvintes de eventos. Esses métodos são adicionados a cada classe capaz de disparar um evento:

• Editora — on(), off(), uma vez()
• Sessão — on(), off(), uma vez()
• Assinante — on(), off(), uma vez()
• OT — on(), off(), uma vez()

O addEventListener() e removeEventListener() Esses métodos estão obsoletos. Eles foram substituídos pelos novos métodos. Os novos métodos apresentam as seguintes vantagens:

• É possível adicionar ou remover vários manipuladores de eventos em uma única chamada para on() ou off().

  Por exemplo, o código a seguir adiciona ouvintes de eventos para o accessAllowed, accessDenied, e streamDestroyed eventos de um objeto Publisher:

  Copiar

  publisher.on({
    accessAllowed: function (event) {
      // This is the handler for the accessAllowed event.
    },
    accessDenied:  function (event) {
      // This is the handler for accessDenied.
    }
    streamDestroyed: function (event) {
      // This is the handler for the streamDestroyed event.
    },
  });
  

• O once() Esse método permite adicionar facilmente um ouvinte de evento que é chamado apenas uma vez. (É equivalente a chamar on() e, em seguida, chamar off() na função do manipulador de eventos.

• Você pode usar o context parâmetro para definir o valor de this no método do manipulador.

Alterações nos eventos de fluxo e conexão

A biblioteca OpenTok.js agora traz uma série de melhorias relacionadas a eventos envolvendo transmissões e clientes que entram e saem de uma sessão.

Um item por StreamEvent ou ConnectionEvent

Na versão mais recente da biblioteca OpenTok.js, o ConnectionEvent classe, que define o connectionCreated e connectionDestroyed eventos, tem um connection propriedade, que representa a única conexão criada ou destruída. A connections A propriedade (a partir da versão 1.0) está obsoleta.

Da mesma forma, o StreamEvent classe, que define o streamCreated e streamDestroyed eventos, tem um stream propriedade, que representa o único Stream criado ou destruído. O streams A propriedade (a partir da versão 1.0) está obsoleta.

Portanto, para detectar outros clientes e seus fluxos em uma sessão (seja na primeira conexão ou posteriormente), basta registrar ouvintes de eventos para o connectionCreated e streamCreated eventos disparados pelo objeto de sessão:

var connectionCount = 0;
session.on(
  {
    connectionCreated: function(event) {
      connectionCount++;
      console.log("New client: " event.connection.connectionId);
      console.log("Clients in the session: " connectionCount);
    },
    connectionDestroyed: function(event) {
      connectionCount--;
      console.log("Client left the session: " event.connection.connectionId);
      console.log("Clients in the session: " connectionCount);
    },
    streamCreated: function(event) {
      console.log("Stream created: " event.stream.streamId);
      // This is another client's stream, so you may want to subscribe to it.
    },
    streamDestroyed: function(event) {
      console.log("Stream destroyed: " event.stream.streamId);
      // This is another client's stream leaving the session.
    }
  }
).connect(apiKey, token, function(error) {
  if (error) {
    console.log("Failed to connect: " error.message);
  } else {
    connectionCount++;
  }
});

Descontinuação do uso de fluxos e conexões a partir do evento `sessionConnected`

Na versão 2 da biblioteca OpenTok.js, o connections e streams propriedade do sessionConnected Os eventos estão obsoletos e são definidos como matrizes vazias. Na versão 2, o objeto Session despacha connectionCreated e streamCreated eventos para cada cliente e fluxo na sessão, tanto no momento da conexão quanto após a conexão.

Para detectar outros clientes presentes em uma sessão no momento da conexão, compare o connection.creationTime propriedade do connectionCreated evento e compará-lo com o connection.creationTime propriedade do objeto Session:

session.on("connectionCreated", function(event) {
  if (event.connection.creationTime <= session.connection.creationTime) {
    console.log("Detected a client that connected before you.")
  }
}

Você pode usar o manipulador de conclusão para o Session.connect() método em vez do sessionConnected evento (conforme mostrado no código de exemplo).

Alterações nos eventos das transmissões que você publica

Na versão 2 da biblioteca OpenTok.js, um objeto Publisher (e não o objeto Session) despacha streamCreated e streamDestroyed eventos para os streams que publica.

publisher = OT.initPublisher(apiKey)
  .on(
    {
      streamCreated: function(event) {
        // The Publisher started streaming.
      },
      streamDestroyed: function(event) {
        // The Publisher stopped streaming.
      }
    }
);

O objeto Session não realiza o despacho streamCreated eventos para transmissões ao vivo próprio publicado pelo cliente. Portanto, não há necessidade de verificar se esse evento corresponde a um dos seus próprios fluxos publicados. Por exemplo, se você quiser se inscrever em todos os fluxos de terceiros na sessão, basta usar o seguinte código:

session.on("streamCreated", function(event) {
    session.subscribe(event.stream);
  },
}

Como preservar um objeto Publisher quando seu fluxo é destruído

Se você quiser manter o Publisher no DOM HTML (para reutilização), chame o preventDefault() método no ouvinte de eventos para o streamDestroyed evento disparado pelo Publisher:

publisher = OT.initPublisher(apiKey)
  .on("streamDestroyed", function(event){
    event.preventDefault(); // This lets you reuse the Publisher.
  }
);

Chamando o preventDefault() método do sessionDisconnected O evento não faz mais com que um Publisher seja preservado.

APIs DOM do Publisher e do Subscriber

A versão 2 da biblioteca OpenTok.js inclui novas APIs para a inserção e remoção de Publisher e Subscriber no DOM HTML.

O insertMode propriedade do properties parâmetro do OT.initPublisher() especifica como o objeto Publisher será inserido no DOM HTML, em relação ao targetElement parâmetro. É possível definir esse parâmetro com um dos seguintes valores:

• "replace" — O objeto Publisher substitui o conteúdo do targetElement. Essa é a configuração padrão.
• "after" — O objeto Publisher é um novo elemento inserido após o targetElement no DOM HTML. (Tanto o Publisher quanto o targetElement têm o mesmo elemento pai.)
• "before" — O objeto Publisher é um novo elemento inserido antes do targetElement no DOM HTML. (Tanto o Publisher quanto o targetElement têm o mesmo elemento pai.)
• "append" — O objeto Publisher é um novo elemento adicionado como filho do targetElement. Se houver outros elementos filhos, o Publisher é anexado como o último elemento filho do targetElement.

Por exemplo, o código a seguir adiciona um novo objeto Publisher como filho de um publisherContainer Elemento DOM:

var publisherProperties = {insertMode: "append"};
var publisher = OT.initPublisher('publisher', publisherContainer, function(error) {
  if (error) {
    console.log(error);
  } else {
    console.log("Publisher initialized.");
  }
});

Cada objeto Publisher e Subscriber possui um element propriedade, que é definida como o elemento DOM HTML que contém o editor ou o assinante.

Cada objeto Publisher e Subscriber despacha um destroyed evento que ocorre quando o objeto é removido do DOM HTML. Em resposta a esse evento, você pode optar por ajustar (ou remover) os elementos do DOM relacionados ao editor ou assinante que foi removido.

Nova propriedade Publisher.accessAllowed

O novo accessAllowed Essa propriedade indica se um cliente concedeu acesso à câmera e ao microfone. Além disso, o Publisher ainda envia accessAllowed e accessDenied eventos, assim como na versão 1.0.