Monitoramento de sessões

Cadastre-se para receber notificações em tempo real sobre eventos de sessão e monitorar a atividade da sua sessão a partir do servidor de aplicativos.

Usando a plataforma OpenTok, os desenvolvedores podem monitorar determinadas atividades dos clientes que utilizam os SDKs de cliente da OpenTok, diretamente de seu servidor de aplicativos. Ao se registrar para callbacks com a API REST do OpenTok, sua URL de callback receberá solicitações HTTP POST quando sessões forem criadas e encerradas, quando clientes se conectarem e se desconectarem, e quando clientes publicarem e retirarem transmissões de uma sessão em seu projeto do OpenTok. Além disso, você pode registrar um callback para monitorar eventos relacionados aos arquivos do OpenTok do seu projeto.

Registrando callbacks

As informações sobre eventos de sessão e atualizações de status do arquivo podem ser registradas em pontos de extremidade HTTP no seu servidor. Sempre que ocorrer uma atividade registrada, uma solicitação HTTP é enviada da infraestrutura da OpenTok para o seu ponto de extremidade.

Para registrar um retorno de chamada:

  1. Visite o seu Página da conta da Video API da Vonage.

  2. Selecione o projeto OpenTok para o qual você deseja registrar um callback.

  3. Defina a URL de retorno de chamada na seção “Monitoramento de sessão”.

    Callbacks seguros: É possível proteger as solicitações de retorno de chamada do webhook com retornos de chamada assinados, utilizando um segredo de assinatura. Consulte Callbacks seguros.

A URL de retorno de chamada do arquivo e a URL de retorno de chamada de transmissão são definidas separadamente da URL de retorno de chamada para eventos de sessão. Defina a URL de retorno de chamada do arquivo na seção “Arquivo” do seu Página da conta da Video API da Vonage.

Importante: O serviço de monitoramento de sessão não desativa mais o encaminhamento de eventos em caso de falhas excessivas na entrega (como ocorria nas versões anteriores), uma vez que é utilizado um mecanismo de repetição de tentativas e recuo. Você não receberá mais e-mails sobre interrupções no callback do monitoramento de sessão, já que o serviço não será suspenso nem desativado.

Monitoramento do início e do término das sessões

Quando os clientes começam a usar uma sessão pela primeira vez e quando uma sessão deixa de ser usada, sessionCreated e sessionDestroyed os eventos são enviados para o seu endpoint de callback registrado.

Sessão criada

Este evento é disparado quando o primeiro cliente se conecta a uma sessão. Se todos os clientes se desconectarem (consulte Sessão encerrada), os clientes podem se reconectar posteriormente à mesma sessão.

Para cada evento distinto, o servidor envia uma solicitação HTTP POST para a URL de retorno de chamada que você fornecer. O tipo de conteúdo (Content-Type) da solicitação é application/json. Os dados da solicitação consistem em um objeto JSON no seguinte formato:

{
  "sessionId": "2_MX4xMzExMjU3MX5-MTQ3MDI1NzY3OTkxOH45QXRr",
  "projectId": "123456",
  "event": "sessionCreated",
  "timestamp": 1470257688309,
  "createdAt": 1470257688309
}

O objeto JSON inclui as seguintes propriedades:

  • sessionId — O ID da sessão associado a este evento

  • projectId — O ID do projeto associado a este evento

  • event — "sessionCreated"

  • timestamp — O carimbo de data e hora em que o evento de retorno de chamada foi enviado

  • createdAt — A data e hora em que o primeiro cliente se conectou à sessão

Sessão encerrada

Este evento é disparado quando uma sessão deixa de ser utilizada:

  • Um minuto após todos os participantes terem se desconectado da sessão.

  • Quando uma sessão da Video API expira, o que pode ocorrer após 8 horas.

  • Quando um servidor da Video API é desligado inesperadamente.

Depois que esse evento for disparado, ainda será possível reutilizar a sessão. Os clientes podem se reconectar à sessão usando o mesmo ID de sessão Sessão criada será enviado um evento de retorno de chamada. No entanto, é recomendável que os clientes se reconectem usando um novo ID de sessão.

Além disso, como prática recomendada, você deve fazer com que os clientes se reconectem a novas sessões (usando um novo ID de sessão) dentro de 8 horas após o Sessão criada evento de retorno de chamada.

Para cada evento distinto, o servidor envia uma solicitação HTTP POST para a URL de retorno de chamada que você fornecer. O tipo de conteúdo (Content-Type) da solicitação é application/json. Os dados da solicitação consistem em um objeto JSON no seguinte formato:

{
  "sessionId": "2_MX4xMzExMjU3MX5-MTQ3MDI1NzY3OTkxOH45QXRr",
  "projectId": "123456",
  "event": "sessionDestroyed",
  "timestamp": 1470258896953,
  "createdAt" : 1470258896953,
  "reason" : "clientDisconnected"
}

O objeto JSON inclui as seguintes propriedades:

  • sessionId — O ID da sessão associado a este evento

  • projectId — O ID do projeto associado a este evento

  • event — "sessionDestroyed"

  • timestamp — O carimbo de data e hora em que o evento de retorno de chamada foi enviado

  • createdAt — A data e hora em que esta sessão deixou de ser utilizada

  • reason — Esse valor deve ser definido como uma das seguintes opções:

    • "clientDisconnected" — Todos os clientes se desconectaram da sessão.

    • "forceDisconnected" — Um moderador desconectou os clientes da sessão. Ou a sessão atingiu o tempo limite. Ou um servidor da Video API foi desligado inesperadamente.

    • "mediaIdle" — Todos os clientes foram desconectados da sessão porque não publicaram nem se inscreveram em fluxos nas últimas 4 horas após a conexão.

    • "serverRotation" — Todos os clientes foram desconectados da sessão devido à rotação de servidores. É possível evitar que os clientes sejam desconectados durante a rotação de servidores configurando-os para usar a migração de sessão. Consulte Rotação de servidores e migração de sessões.

Eventos de notificação de sessão

O sessionNotification O evento é enviado quando está programada a rotação de um grupo de servidores da Video API para uma de suas sessões. Esse evento é enviado 4 horas e 1 hora antes da rotação programada.

O sessionNotification O evento é uma solicitação HTTP POST enviada para a URL de retorno de chamada de monitoramento de sessão que você fornecer. O Content-Type da solicitação é application/json. Os dados da solicitação consistem em um objeto JSON com o seguinte formato:

{
  "sessionId": "2_MX4xMzExMjU3MX5-MTQ3MDI1NzY3OTkxOH45QXRr",
  "projectId": "123456",
  "event": "sessionNotification",
  "reason": "serverRotation",
  "timestamp": 1470282888309,
  "remainingTime": 3600,
  "createdAt": 1470257688309
}

O objeto JSON inclui as seguintes propriedades:

  • sessionId — O ID da sessão associado a este evento

  • projectId — O ID do projeto associado a este evento

  • event — "sessionNotification"

  • reason — Para um evento de rotação de servidores, isso é definido como "serverRotation". (Atualmente, esse é o único tipo de evento de notificação de sessão.)

  • remainingTime — O tempo restante, em segundos, até que os servidores da sessão sejam alternados. Esse valor será definido como 14.400 segundos (4 horas) ou 3.600 segundos (1 hora).

  • timestamp — O carimbo de data e hora em que o evento de retorno de chamada foi enviado

  • createdAt — A data e hora em que o primeiro cliente se conectou à sessão

Veja Rotação de servidores e migração de sessões para obter mais informações sobre a rotação de servidores da Video API e como manter os clientes conectados quando ocorre a rotação de servidores.

Monitoramento da atividade de conexão

Uma vez devidamente registrada, a infraestrutura do OpenTok pode enviar solicitações HTTP para todas as conexões estabelecidas (e encerradas) em todas as sessões de um único projeto. Isso é particularmente útil para monitorar a disponibilidade do usuário sem a necessidade de conexões adicionais ou de relatórios diretamente do endpoint.

Quando os clientes recebem connectionCreated e connectionDestroyed eventos em resposta à conexão e desconexão de outros clientes de uma sessão; esses mesmos eventos são enviados ao seu endpoint de callback registrado.

Conexão criada

Para cada evento distinto, o servidor envia uma solicitação HTTP POST para a URL que você fornecer. O Content-Type da solicitação é application/json. Os dados da solicitação consistem em um objeto JSON no seguinte formato:

{
    "sessionId": "2_MX4xMzExMjU3MX5-MTQ3MDI1NzY3OTkxOH45QXRr",
    "projectId": "123456",
    "event": "connectionCreated",
    "timestamp": 1470257688309,
    "connection": {
        "id": "c053fcc8-c681-41d5-8ec2-7a9e1434a21e",
        "createdAt": 1470257688143,
        "data": "TOKENDATA"
    }
}

O objeto JSON inclui as seguintes propriedades:

  • sessionId — O ID da sessão associado a este evento

  • projectId — O ID do projeto associado a este evento

  • event — "connectionCreated"

  • timestamp — Milissegundos desde a época Unix

  • connection — Um objeto que define a conexão, contendo as seguintes propriedades:

    • id — O ID da conexão

    • data — Os dados de conexão (consulte Conexão dados)

    • createdAt — O valor da data e hora em que este objeto foi criado

Conexão interrompida

Para cada evento distinto, o servidor envia uma solicitação HTTP POST para a URL que você fornecer. O Content-Type da solicitação é application/json. Os dados da solicitação consistem em um objeto JSON no seguinte formato:

{
    "sessionId": "2_MX4xMzExMjU3MX5-MTQ3MDI1NzY3OTkxOH45QXRr",
    "projectId": "123456",
    "event": "connectionDestroyed",
    "reason": "clientDisconnected",
    "timestamp": 1470258896953,
    "connection": {
        "id": "c053fcc8-c681-41d5-8ec2-7a9e1434a21e",
        "createdAt": 1470257688143,
        "data": ""
    }
}

O objeto JSON inclui as seguintes propriedades:

  • sessionId — O ID da sessão associado a este evento

  • projectId — O ID do projeto associado a este evento

  • reason — Para um connectionDestroyed evento, esse valor é definido como um dos seguintes:

    • "clientDisconnected" — Um cliente se desconectou da sessão (por exemplo, chamando o método `Session.disconnect()` do OpenTok.js ou fechando o navegador ou o aplicativo).

    • "forceDisconnected" — Um moderador desconectou o cliente da sessão (ao chamar o OpenTok.js Session.forceDisconnect() método).

    • "networkDisconnected" — A conexão de rede foi interrompida repentinamente (por exemplo, o cliente perdeu a conexão com a internet).

    • "mediaIdle" — O cliente foi desconectado de uma sessão porque não publicou nem se inscreveu em fluxos nas 4 horas seguintes à conexão.

    • "serverRotation" — O cliente foi desconectado de uma sessão devido à rotação de servidores. É possível evitar que os clientes sejam desconectados durante a rotação de servidores configurando-os para usar a migração de sessão. Consulte Rotação de servidores e migração de sessões.

  • event — "connectionDestroyed"

  • timestamp — Milissegundos desde a época Unix

  • connection — Um objeto que define a conexão, contendo as seguintes propriedades:

    • id — O ID da conexão

    • data — Os dados de conexão (consulte Conexão dados)

    • createdAt — O valor da data e hora em que este objeto foi criado

Monitoramento de fluxos

Os endpoints do servidor também podem se registrar para receber solicitações HTTP acionadas pela atividade dos streams em todas as sessões de um determinado projeto. Quando os streams são criados e destruídos, a solicitação conterá os dados do stream e da conexão correspondentes ao stream que acionou o evento.

Quando os clientes recebem streamCreated e streamDestroyed eventos em resposta à publicação de outros clientes em uma sessão; esses mesmos eventos são enviados ao seu endpoint de callback registrado.

Fluxo criado

Para cada evento distinto, o servidor envia uma solicitação HTTP POST para a URL que você fornecer. O Content-Type da solicitação é application/json. Os dados da solicitação consistem em um objeto JSON no seguinte formato:

{
    "sessionId": "2_MX4xMzExMjU3MX5-MTQ3MDI1NzY3OTkxOH45QXRr",
    "projectId": "123456",
    "event": "streamCreated",
    "timestamp": 1470258860571,
    "stream": {
        "id": "63245362-e00e-4834-8371-9397deb3e452",
        "connection": {
            "id": "c053fcc8-c681-41d5-8ec2-7a9e1434a21e",
            "createdAt": 1470257688143,
            "data": ""
        },
        "createdAt": 1470258845416,
        "name": "",
        "videoType": "camera"
    }
}

  • sessionId — O ID da sessão associado a este evento

  • projectId — O ID do projeto associado a este evento

  • event — "streamCreated"

  • timestamp — Milissegundos desde a época Unix

  • stream — Um objeto que define o fluxo:

    • id — O ID da transmissão

    • connection — A conexão associada a este fluxo. Este objeto inclui as seguintes propriedades:

      • id — O ID da conexão

      • data — Os dados de conexão (consulte Conexão dados)

      • createdAt — O valor do carimbo de data e hora em que a conexão foi criada

    • createdAt — O valor do carimbo de data e hora em que o fluxo foi criado

    • name — O nome, se houvesse algum, foi passado quando o editor associado a este fluxo foi inicializado

    • videoType — O tipo de vídeo transmitido nesta transmissão, seja "camera", "screen", ou "custom" (ou indefinido para uma transmissão apenas de áudio).

Córrego destruído

Para cada evento distinto, o servidor envia uma solicitação HTTP POST para a URL que você fornecer. O Content-Type da solicitação é application/json. Os dados da solicitação consistem em um objeto JSON no seguinte formato:

{
    "sessionId": "2_MX4xMzExMjU3MX5-MTQ3MDI1NzY3OTkxOH45QXRr",
    "projectId": "123456",
    "event": "streamDestroyed",
    "reason": "clientDisconnected",
    "timestamp": 1470258896953,
    "stream": {
        "id": "63245362-e00e-4834-8371-9397deb3e452",
        "connection": {
            "id": "c053fcc8-c681-41d5-8ec2-7a9e1434a21e",
            "createdAt": 1470257688143,
            "data": ""
        },
        "createdAt": 1470258845416,
        "name": "",
        "videoType": "camera"
    }
}

  • sessionId — O ID da sessão associado a este evento

  • projectId — O ID do projeto associado a este evento

  • event — "streamDestroyed"

  • reason — Para um streamDestroyed evento, esse valor é definido como um dos seguintes:

    • "clientDisconnected" — O cliente se desconectou da sessão (por exemplo, chamando o OpenTok.js Session.disconnect() método).

    • "forceDisconnected" — Um moderador desconectou o emissor da transmissão da sessão, chamando o OpenTok.js Session.forceDisconnect() método.

    • "forceUnpublished" — Um moderador obrigou o emissor da transmissão a interromper a transmissão, chamando o OpenTok.js Session.forceUnpublish() método.

    • "mediaStopped" — O usuário que está transmitindo a transmissão interrompeu o compartilhamento da tela. Esse valor é utilizado apenas em transmissões de vídeo com compartilhamento de tela.

    • "networkDisconnected" A conexão de rede foi interrompida repentinamente (por exemplo, o cliente perdeu a conexão com a internet).

    • "serverRotation" — A transmissão foi interrompida porque o cliente de publicação foi desconectado de uma sessão devido a Rotação do servidor da Video API.

  • timestamp — Milissegundos desde a época Unix

  • stream — Um objeto que define o fluxo:

    • id — O ID da transmissão

    • connection — A conexão associada a este fluxo. Este objeto inclui as seguintes propriedades:

      • id — O ID da conexão

      • data — Os dados de conexão (consulte Conexão dados)

      • createdAt — O valor do carimbo de data e hora em que a conexão foi criada

    • createdAt — O valor do carimbo de data e hora em que o fluxo foi criado

    • name — O nome, se houvesse algum, foi passado quando o editor associado a este fluxo foi inicializado

    • videoType — O tipo de vídeo transmitido nesta transmissão, seja "camera", "screen", ou "custom" (ou indefinido para uma transmissão apenas de áudio).

Arquivos de monitoramento

Cada arquivo passa por vários estados ao longo de seu ciclo de vida. A cada atualização de status que ocorrer, um endpoint do servidor com um registro de status do arquivo receberá uma solicitação HTTP. Isso é particularmente útil para acionar o pós-processamento de um arquivo ou para realizar quaisquer tarefas administrativas necessárias após o arquivo ter sido enviado para um armazenamento persistente. Para obter mais informações, consulte o Alterações no status do arquivo seção sobre arquivamento do OpenTok do guia do desenvolvedor.

Monitoramento de transmissões

Veja o Monitoramento das alterações no status das transmissões ao vivo seção do guia do desenvolvedor sobre transmissões ao vivo da OpenTok.

Monitoramento do andamento das chamadas SIP

É possível monitorar as atualizações de status das conexões SIP com a sessão do OpenTok. Consulte o Acompanhamento do andamento da chamada seção do guia do desenvolvedor do OpenTok SIP Interconnect.

Monitoramento do Experience Composer

Você pode acompanhar as atualizações de status dos Experience Composers. Consulte o Configurando callbacks seção do guia do desenvolvedor do Experience Composer.

Monitoramento de legendas em tempo real

Você pode acompanhar as atualizações de status das legendas em tempo real. Consulte o Retornos de chamada de legendas em tempo real seção do guia do desenvolvedor de legendas em tempo real.