Comunicação por canal de dados entre um aplicativo e um cliente web - Amazon GameLift Streams
AtributosUsando canais de dadosNo lado do clienteNo lado do aplicativo

As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.

Comunicação por canal de dados entre um aplicativo e um cliente web

Os canais de dados permitem que você comunique com segurança mensagens arbitrárias entre seu aplicativo Amazon GameLift Streams e o cliente web (o JavaScript código executado no navegador do usuário final). Isso permite que os usuários finais interajam com o aplicativo que o Amazon GameLift Streams está transmitindo, por meio do navegador da web em que estão visualizando o stream.

Aqui estão alguns exemplos de casos de uso de canais de dados no Amazon GameLift Streams:

  • Os usuários podem abrir URLs o aplicativo em seu navegador local.

  • Os usuários podem passar o conteúdo da área de transferência para o aplicativo.

  • Os usuários podem carregar conteúdo de sua máquina local para o aplicativo.

  • Os desenvolvedores podem implementar a interface do usuário no navegador que envia comandos para o aplicativo.

  • Os usuários podem passar esquemas para controlar a exibição das camadas de visualização.

Atributos

Limites de tamanho de mensagem

O Amazon GameLift Streams Web SDK impõe um limite máximo de tamanho de 64 KB (65536 bytes) por mensagem. Isso garante que os limites de tamanho da mensagem sejam compatíveis com a maioria dos navegadores e que a comunicação tenha baixo impacto na largura de banda total do stream.

Métricas

As métricas sobre o uso do seu canal de dados são enviadas para sua conta da AWS quando uma sessão de stream termina. Para obter mais informações, consulte a Canais de dados seção Monitoramento do Amazon GameLift Streams.

Usando canais de dados

O Amazon GameLift Streams Web SDK fornece a sendApplicationMessage função que envia uma mensagem como uma matriz de bytes para o aplicativo. A mensagem é processada por uma função de retorno de chamada, clientConnection.applicationMessage que você define.

Se o cliente enviar mensagens antes que o aplicativo se conecte à porta do canal de dados, as mensagens serão enfileiradas. Então, quando o aplicativo se conecta, ele recebe as mensagens. No entanto, se o aplicativo enviar mensagens antes que o cliente se conecte à porta do canal de dados, as mensagens serão perdidas. O aplicativo deve verificar o estado da conexão dos clientes antes de enviar uma mensagem.

No lado do cliente

Escreva o código a seguir em seu aplicativo cliente web.

  1. Defina a função de retorno de chamada para receber mensagens do aplicativo. 

    function streamApplicationMessageCallback(message) {
    console.log('Received ' + message.length + ' bytes of message from 
    Application');
}

  2. clientConnection.applicationMessageDefina sua função de retorno de chamada. 

    clientConnection: {
    connectionState: streamConnectionStateCallback,
    channelError: streamChannelErrorCallback,
    serverDisconnect: streamServerDisconnectCallback,
    applicationMessage: streamApplicationMessageCallback,
}

  3. Chame a GameLiftStreams.sendApplicationMessage função para enviar mensagens para seu aplicativo. Você pode chamar isso a qualquer momento, desde que a sessão de transmissão esteja ativa e a entrada esteja anexada.

Como exemplo, consulte o cliente de amostra do Amazon GameLift Streams Web SDK, que demonstra como configurar um canal de dados simples no lado do cliente.

No lado do aplicativo

Escreva a seguinte lógica em seu aplicativo.

Etapa 1. Conecte-se à porta do canal de dados

Quando seu aplicativo for iniciado, conecte-se à porta 40712 ativadalocalhost. Seu aplicativo deve manter essa conexão por toda a duração da execução. Se o aplicativo fechar a conexão, ela não poderá ser reaberta.

Etapa 2. Ouça os eventos

Um evento começa com um cabeçalho de tamanho fixo, seguido por dados associados de tamanho variável. Quando seu aplicativo recebe um evento, analise o evento para recuperar as informações.

Formato do evento

  • Cabeçalho: um cabeçalho de 4 bytes no formulário abcc

    • a: byte de identificação do cliente. Isso identifica uma conexão de cliente específica, no caso de várias conexões (devido à desconexão e reconexão).

    • b: byte do tipo de evento. 0- o cliente conectado, 1 - o cliente desconectado, 2 - uma mensagem é enviada pelo cliente. Outros tipos de eventos podem ser recebidos com futuras atualizações do serviço Amazon GameLift Streams e devem ser ignorados.

    • cc: tamanho dos dados do evento associado. Isso é representado como 2 bytes com ordenação big-endian (o primeiro byte é o mais significativo). Se o tipo de evento for 2, os dados do evento representarão o conteúdo da mensagem do cliente.

  • Dados: os bytes restantes contêm os dados do evento, como uma mensagem do cliente. O comprimento dos dados é indicado cc no cabeçalho.

Para ouvir os eventos

  1. Leia os quatro bytes do cabeçalho para recuperar o ID do cliente, o tipo de evento e o tamanho dos dados do evento.

  2. Leia os dados do evento de tamanho variável, independentemente do ID do cliente e do tipo de evento, de acordo com o tamanho descrito no cabeçalho. É importante ler os dados incondicionalmente para que os dados do evento nunca sejam deixados no buffer, onde possam ser confundidos com o próximo cabeçalho do evento. Não faça suposições sobre o tamanho dos dados com base nos tipos de eventos.

  3. Tome as medidas apropriadas com base no tipo de evento, se reconhecido pelo seu aplicativo. Essa ação pode incluir registrar uma conexão ou desconexão de entrada ou analisar a mensagem do cliente e acionar a lógica do aplicativo.

Etapa 3. Transmita mensagens para o cliente

O aplicativo deve transmitir mensagens com o mesmo formato de cabeçalho de quatro bytes usado pelos eventos recebidos.

Para transmitir uma mensagem ao cliente

  1. Escreva o cabeçalho com as seguintes propriedades:

    1. a: byte de identificação do cliente. Se sua mensagem for em resposta a uma mensagem do cliente, ela deverá reutilizar o mesmo ID do cliente que a mensagem recebida do cliente, para evitar condições de disputa, como entregar uma resposta de uma conexão antiga do cliente para um cliente recém-reconectado. Se seu aplicativo estiver enviando uma mensagem não solicitada ao cliente, ele deverá definir o ID do cliente para corresponder ao evento de “conexão do cliente” mais recente (evento tipo 0).

    2. b: O tipo de evento das mensagens enviadas deve ser sempre 2. O cliente ignora mensagens com outros tipos de eventos.

    3. cc: tamanho da mensagem, em bytes.

  2. Escreva os bytes da mensagem.

A mensagem é entregue ao cliente especificado, a menos que o cliente se desconecte. Quando um cliente desconectado se reconecta, uma nova ID de cliente é atribuída por meio de um evento conectado ao cliente. Todas as mensagens não entregues para o ID do cliente antigo são descartadas.

O pseudocódigo a seguir demonstra a lógica para comunicar mensagens no lado do aplicativo. Para obter um exemplo completo do uso do Winsock, consulte Código completo do cliente Winsock na documentação do Windows Sockets 2.


connection = connect_to_tcp_socket("localhost:40712")
loop:
    while has_pending_bytes(connection):
        client_id = read_unsigned_byte(connection)
        event_type = read_unsigned_byte(connection)
        event_length = 256 * read_unsigned_byte(connection)
        event_length = event_length + read_unsigned_byte(connection)
        event_data = read_raw_bytes(connection, event_length)
        if message_type == 0:
            app_process_client_connected(client_id)
        else if message_type == 1:
            app_process_client_disconnected(client_id)
        else if message_type == 2:
            app_process_client_message(client_id, event_data)
        else:
            log("ignoring unrecognized event type")
    while app_has_outgoing_messages():
        target_client_id, message_bytes = app_next_outgoing_message()
        message_length = length(message_bytes)
        write_unsigned_byte(connection, target_client_id)
        write_unsigned_byte(connection, 2)
        write_unsigned_byte(connection, message_length / 256)
        write_unsigned_byte(connection, message_length mod 256)
        write_raw_bytes(connection, message_bytes)