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

O versão mais recente A biblioteca OpenTok.js inclui um conjunto de novos recursos que facilitam o desenvolvimento de aplicativos OpenTok. Este documento descreve as alterações que foram adicionadas na versão 2.2 (que também estão presentes na versão mais recente).

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

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

Para utilizar os novos recursos disponíveis na versão mais recente, defina o src atributo do script tag para carregar a nova biblioteca:

<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 2.0. Esta seção mostra como adaptar o código existente para funcionar com a versão mais recente da biblioteca OpenTok.js.

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

Agora você deve inserir sua chave de API no 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 OpenTok.js 2.0. No entanto, algumas das alterações na API da versão mais recente do OpenTok.js exigem algumas modificações no código dos aplicativos portados a partir da biblioteca OpenTok.js 2.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, na versão 2.2, o objeto Publisher (e não o objeto Session) 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 despachados pelo objeto Session não impedem mais que o objeto Publisher seja removido (como acontecia na v2.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

No OpenTok.js 2.2 ou superior, 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.

Alterações no método Session.signal()

No Session.signal() método, o data propriedade do signal O parâmetro deve ser uma string. (No OpenTok.js 2.0, o data (essa propriedade pode ser definida como qualquer objeto serializável em JSON.)

Além disso, o opcional to propriedade do signal O parâmetro recebe um único objeto Connection (que define a conexão para a qual o sinal será enviado). O to a propriedade não aceita um matriz de objetos Connection, assim como acontecia na biblioteca OpenTok.js 2.0.

Para enviar um sinal a vários clientes individuais conectados a uma sessão, chame a função signal() método repetidamente, passando um único objeto Connection como o to parâmetro a cada vez:

var connections;
// Set the connections object to an array of Connection objects corresponding to the clients you want to signal.

for (var i = 0; i < a.connections; i++) {
  session.signal(
    {
      type: "foo",
      to: connections[i],
      data: "hello"
    },
    function(error) {
      if (error) {
        console.log("signal error: " + error.reason);
      } else {
        console.log("signal sent");
      }
    }
  );
}

Outras alterações e novos recursos

Para saber mais sobre outras alterações e começar a aproveitar outros novos recursos, consulte Novidades da versão 2.2.

Novos recursos

Esta página descreve os recursos que foram adicionados na versão 2.2. Consulte a versão mais recente notas de lançamento para os recursos que foram adicionados desde então.

  • 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 versão mais recente 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 versão mais recente da biblioteca OpenTok.js inclui melhorias nos eventos relacionados a transmissões e à entrada e saída de clientes 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.

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 participante pode mudar 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 estava disponível no OpenTok.js 2.0. Na versão mais recente da biblioteca OpenTok.js, 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 nova biblioteca do OpenTok oferece uma maneira padronizada 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:

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:

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:

    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 inclui uma série de melhorias nos eventos relacionados a transmissões e à entrada e saída de clientes de uma sessão.

Um item por StreamEvent ou ConnectionEvent

O ConnectionEvent classe, que define o connectionCreated e connectionDestroyed eventos, agora conta com um connection propriedade, que representa a única conexão criada ou destruída. A connections A propriedade (a partir da v2.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 v2.0) está obsoleta.

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

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);
  }
});

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

Na nova 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.2, o objeto Session dispacha 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 nova 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 biblioteca OpenTok.js agora inclui novas APIs para inserir e remover Publisher e Subscriber do 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 2.0.