# Conceitos básicos do Amazon IVS Chat O Amazon Interactive Video Service (IVS) Chat é um recurso gerenciado de chat ao vivo para acompanhar suas transmissões de vídeo ao vivo. (O Chat do IVS também poderá ser usado sem uma transmissão de vídeo.) É possível criar salas de chat e habilitar sessões de chat entre seus usuários. Com o Amazon IVS Chat, você pode se concentrar na criação de experiências de chat personalizadas junto com vídeos ao vivo. Não é necessário gerenciar a infraestrutura ou desenvolver e configurar componentes de seus fluxos de trabalho de chat. O Amazon IVS Chat é escalável, seguro, confiável e econômico. O Amazon IVS Chat funciona melhor para promover o envio de mensagens entre os participantes de uma transmissão de vídeo ao vivo com um início e um fim. O restante deste documento orienta as etapas para criar sua primeira aplicação de chat usando o Amazon IVS Chat. **Exemplos:** as seguintes aplicações de demonstração estão disponíveis (três exemplos de aplicações clientes e uma aplicação de servidor de backend para criação de tokens): + [Demonstração do Amazon IVS Chat Web](https://github.com/aws-samples/amazon-ivs-chat-web-demo) + [Demonstração do Amazon IVS Chat para Android](https://github.com/aws-samples/amazon-ivs-chat-for-android-demo) + [Demonstração do Amazon IVS Chat para iOS](https://github.com/aws-samples/amazon-ivs-chat-for-ios-demo) + [Demonstração do backend do Amazon IVS Chat](https://github.com/aws-samples/amazon-ivs-chat-web-demo/tree/main/serverless) **Importante:** as salas de chat que não tiverem novas conexões ou atualizações num período de 24 meses serão excluídas automaticamente. **Topics** + [Etapa 1: realizar a configuração inicial](getting-started-chat-create-account.md) + [Etapa 2: criar uma sala de chat](getting-started-chat-create-room.md) + [Etapa 3: criar uma token de chat](getting-started-chat-auth.md) + [Etapa 4: enviar e receber sua primeira mensagem](getting-started-chat-send-and-receive.md) + [Etapa 5: verificar limites de cota de serviço (opcional)](getting-started-chat-check-service-quota.md) # Etapa 1: realizar a configuração inicial Antes de prosseguir, é necessário: 1. Criar uma conta da AWS. 1. Configurar os usuários raiz e administrativo. 1. Configurar as permissões do AWS IAM (Identity and Access Management). Usar a política especificada abaixo. Para obter as etapas específicas para todo o exposto, consulte [Conceitos básicos do streaming de baixa latência do IVS](https://docs.aws.amazon.com/ivs/latest/LowLatencyUserGuide/getting-started.html) no *Guia do usuário do Amazon IVS*. **Importante**: na “Etapa 3: configurar permissões do IAM”, use esta política para o IVS Chat: ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "ivschat:CreateChatToken", "ivschat:CreateLoggingConfiguration", "ivschat:CreateRoom", "ivschat:DeleteLoggingConfiguration", "ivschat:DeleteMessage", "ivschat:DeleteRoom", "ivschat:DisconnectUser", "ivschat:GetLoggingConfiguration", "ivschat:GetRoom", "ivschat:ListLoggingConfigurations", "ivschat:ListRooms", "ivschat:ListTagsForResource", "ivschat:SendEvent", "ivschat:TagResource", "ivschat:UntagResource", "ivschat:UpdateLoggingConfiguration", "ivschat:UpdateRoom" ], "Resource": "*" }, { "Effect": "Allow", "Action": [ "servicequotas:ListServiceQuotas", "servicequotas:ListServices", "servicequotas:ListAWSDefaultServiceQuotas", "servicequotas:ListRequestedServiceQuotaChangeHistoryByQuota", "servicequotas:ListTagsForResource", "cloudwatch:GetMetricData", "cloudwatch:DescribeAlarms" ], "Resource": "*" }, { "Effect": "Allow", "Action": [ "logs:CreateLogDelivery", "logs:GetLogDelivery", "logs:UpdateLogDelivery", "logs:DeleteLogDelivery", "logs:ListLogDeliveries", "logs:PutResourcePolicy", "logs:DescribeResourcePolicies", "logs:DescribeLogGroups", "s3:PutBucketPolicy", "s3:GetBucketPolicy", "iam:CreateServiceLinkedRole", "firehose:TagDeliveryStream" ], "Resource": "*" } ] } ``` ------ # Etapa 2: criar uma sala de chat Uma sala de chat do Amazon IVS tem informações de configuração associadas a ela (por exemplo, tamanho máximo da mensagem). As instruções nesta seção mostram como usar o console ou a AWS CLI para configurar salas de chat (incluindo a configuração opcional para revisar e/ou registrar mensagens) e criar salas. # Instruções do console para criar uma sala de chat do IVS Essas etapas são divididas em fases, começando pela configuração inicial da sala e terminando com a criação final da sala. Se preferir, você pode configurar uma sala para que as mensagens sejam revisadas. Por exemplo, você pode atualizar o conteúdo da mensagem ou metadados, negar mensagens para evitar que sejam enviadas ou deixar a mensagem original passar. Isso é abordado em [Configuração para revisar as mensagens da sala (opcional)](#create-room-console-review-messages). Opcionalmente, você também pode configurar uma sala para que as mensagens sejam registradas em log. Por exemplo, se você tiver mensagens sendo enviadas para uma sala de chat, poderá registrá-las em log em um bucket do Amazon S3, no Amazon CloudWatch ou no Amazon Kinesis Data Firehose. Isso é abordado em [Configuração para registro de mensagens em log (opcional)](#create-room-console-log-messages). ## Configuração inicial da sala 1. Abra o [console do Amazon IVS Chat](https://console.aws.amazon.com/ivs/chat). (Você também pode acessar o console do Amazon IVS via [Console de Gerenciamento da AWS ](https://console.aws.amazon.com/).) 1. Na barra de navegação, use o menu suspenso **Select a Region** (Selecione uma região) para escolher uma região. Sua nova sala será criada nessa região. 1. Na caixa **Get started** (Comece a usar), no canto superior direito, escolha **Amazon IVS Chat Room** (Sala do Amazon IVS Chat). Será exibida a janela **Create room** (Criar sala). ![\[Criar uma sala de chat.\]](http://docs.aws.amazon.com/pt_br/ivs/latest/ChatUserGuide/images/Chat_Create_Room.png) 1. Em **Setup** (Configuração), opcionalmente, especifique um **Room name** (Nome da sala). Os nomes de sala não são exclusivos, mas oferecem um modo de distinguir salas diferentes do ARN (nome do recurso da Amazon) da sala. 1. Em **Setup > Room configuration** (Configuração > Configuração da sala), aceite a **Default configuration** (Configuração padrão) ou selecione **Custom configuration** (Configuração personalizada) e configure o **Maximum message length** (Tamanho máximo da mensagem) e/ou **Maximum message rate** (Taxa máxima de mensagens). 1. Se você quiser revisar as mensagens, continue com [Configuração para revisar as mensagens da sala (opcional)](#create-room-console-review-messages) abaixo. Caso contrário, pule essa parte (ou seja, aceite **Message Review Handler > Disabled** [Manipulador de revisão de mensagens > Desabilitado]) e prossiga diretamente para [Final Room Creation](#create-room-console-final) (Criação da sala final). ## Configuração para revisar as mensagens da sala (opcional) 1. Em **Message Review Handler** (Manipulador de revisão de mensagens), selecione **Handle with AWS Lambda** (Manipular com o AWS Lambda). A seção **Message Review Handler** (Manipulador de revisão de mensagem) se expandirá para exibir outras opções. 1. Configure **Fallback result** (Resultado de fallback) para **Allow** (Permitir) ou **Deny** (Negar) a mensagem se o manipulador não retornar uma resposta válida, encontrar um erro ou exceder o período de tempo limite. 1. Especifique a **função Lambda** existente ou use **Create Lambda function** (Criar função Lambda) para criar uma nova função. A função Lambda deve estar na mesma conta da AWS e nas mesmas regiões da AWS que a sala de chat. É necessário dar ao serviço Amazon Chat SDK permissão para invocar seu recurso do Lambda. A política baseada em recursos será criada automaticamente para a função Lambda selecionada. Para obter mais informações sobre permissões, consulte [Política baseada em recursos para Chat do Amazon IVS](security-iam.md#security-chat-policy-examples). ## Configuração para registro de mensagens em log (opcional) 1. Em **Message logging** (Registro de mensagens em log), selecione **Automatically log chat messages** (Registrar mensagens em log automaticamente). A seção **Message logging** (Registro de mensagens em log) se expandirá para exibir outras opções. É possível adicionar uma configuração de log existente a essa sala ou criar uma nova configuração de log selecionando **Create logging configuration** (Criar configuração de log). 1. Se você escolher uma configuração de log existente, um menu suspenso será exibido e mostrará todas as configurações de log que você já criou. Selecione uma na lista e suas mensagens de chat serão automaticamente registradas em log nesse destino. 1. Se você escolher **Create logging configuration** (Criar configuração de log), uma janela modal será exibida, permitindo que você crie e personalize uma nova configuração de log. 1. Opcionalmente, especifique um **Logging configuration name** (Nome da configuração de log). Os nomes das configuração de log, como os nomes das sala, não são exclusivos, mas oferecem um modo de distinguir as configurações de log diferentes do ARN da configuração de log. 1. Em **Destino**, selecione **Grupo de logs do CloudWatch**, **Stream de entrega do Kinesis Firehose** ou **Bucket do Amazon S3** para escolher o destino para seus logs. 1. Dependendo do seu destino, selecione a opção de criar um novo **CloudWatch log group** (Grupo de logs do CloudWatch), **Kinesis firehose delivery stream** (Stream de entrega do Kinesis Firehose) ou **Amazon S3 bucket** (Bucket do Amazon S3), ou usar um já existente. 1. Depois de revisar, escolha **Create** (Criar) para criar uma nova configuração de log com um ARN exclusivo. Isso anexa automaticamente a nova configuração de log à sala de chat. ## Criação da sala final 1. Depois de revisar, escolha **Create chat room** (Criar sala de chat) para criar uma nova sala de chat com um ARN exclusivo. # Instruções da CLI para criar uma sala de chat do IVS Este documento orienta você pelas etapas envolvidas na criação de uma sala de Chat do Amazon IVS usando a AWS CLI. ## Criar uma sala de chat A criação de uma sala de chat com a AWS CLI é uma opção avançada e exige que você baixe e configure a CLI em sua máquina primeiro. Para obter mais detalhes, consulte o [Guia do usuário da Interface de Linhas de Comando da AWS](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-welcome.html). 1. Execute o comando `create-room` e envie um nome opcional: ``` aws ivschat create-room --name test-room ``` 1. Isso retorna uma nova sala de chat: ``` { "arn": "arn:aws:ivschat:us-west-2:123456789012:room/g1H2I3j4k5L6", "id": "string", "createTime": "2021-06-07T14:26:05-07:00", "maximumMessageLength": 200, "maximumMessageRatePerSecond": 10, "name": "test-room", "tags": {}, "updateTime": "2021-06-07T14:26:05-07:00" } ``` 1. Observe o campo `arn`. Você precisará dele para criar um token de cliente e se conectar a uma sala de chat. ## Definição de uma configuração de log (opcional) Assim como na criação de uma sala de chat, a definição de uma configuração de log com a AWS CLI é uma opção avançada e exige que você baixe e configure a CLI em sua máquina primeiro. Para obter mais detalhes, consulte o [Guia do usuário da Interface de Linhas de Comando da AWS](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-welcome.html). 1. Execute o comando `create-logging-configuration` de chat e insira um nome opcional e uma configuração de destino apontando para um bucket do Amazon S3 pelo nome. Esse bucket do Amazon S3 deve existir antes da criação da configuração de log. (Para obter detalhes sobre como criar um bucket do Amazon S3, consulte a [Documentação do Amazon S3](https://docs.aws.amazon.com/AmazonS3/latest/userguide/create-bucket-overview.html).) ``` aws ivschat create-logging-configuration \ --destination-configuration s3={bucketName=demo-logging-bucket} \ --name "test-logging-config" ``` 1. Isso retornará uma nova configuração de log: ``` { "Arn": "arn:aws:ivschat:us-west-2:123456789012:logging-configuration/ABcdef34ghIJ", "createTime": "2022-09-14T17:48:00.653000+00:00", "destinationConfiguration": { "s3": {"bucketName": "demo-logging-bucket"} }, "id": "ABcdef34ghIJ", "name": "test-logging-config", "state": "ACTIVE", "tags": {}, "updateTime": "2022-09-14T17:48:01.104000+00:00" } ``` 1. Observe o campo `arn`. Você precisará disso para anexar a configuração de log à sala de chat. 1. Se você estiver criando uma nova sala de chat, execute o comando `create-room` e passe a configuração de log `arn`: ``` aws ivschat create-room --name test-room \ --logging-configuration-identifiers \ "arn:aws:ivschat:us-west-2:123456789012:logging-configuration/ABcdef34ghIJ" ``` 1. Se você estiver atualizando uma sala de chat existente, execute o comando `update-room` e passe a configuração de log `arn`: ``` aws ivschat update-room --identifier \ "arn:aws:ivschat:us-west-2:12345689012:room/g1H2I3j4k5L6" \ --logging-configuration-identifiers \ "arn:aws:ivschat:us-west-2:123456789012:logging-configuration/ABcdef34ghIJ" ``` # Etapa 3: criar uma token de chat Para que um participante do chat se conecte a uma sala e comece a enviar e receber mensagens, um token de chat deve ser criado. Os tokens de chat são usados para autenticar e autorizar clientes de chat. Este diagrama ilustra o fluxo de trabalho para a criação de um token de chat do IVS: ![\[Autentique e autorize seus clientes para sua sala de chat recém-criada.\]](http://docs.aws.amazon.com/pt_br/ivs/latest/ChatUserGuide/images/Chat_Getting_Started_Auth.png) Conforme mostrado acima, um aplicativo cliente solicita um token ao aplicativo do lado do servidor, e o aplicativo do lado do servidor chama CreateChatToken usando um SDK da AWS ou solicitações assinadas pelo [SIGv4](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_aws-signing.html). Como as credenciais da AWS são usadas para chamar a API, o token deve ser gerado em um aplicativo seguro do lado do servidor, não no aplicativo do lado do cliente. Uma aplicação de servidor de backend que demonstra a geração de tokens está disponível em [Demonstração de backend do Amazon IVS Chat](https://github.com/aws-samples/amazon-ivs-chat-web-demo/tree/main/serverless). A *duração da sessão* informa por quanto tempo uma sessão estabelecida pode permanecer ativa antes de ser encerrada automaticamente. Ou seja, a duração da sessão significa por quanto tempo o cliente pode permanecer conectado à sala de chat antes que um novo token seja gerado e seja necessário estabelecer uma nova conexão. Durante a criação do token, também é possível especificar a duração da sessão. Cada token pode ser usado para estabelecer uma conexão somente uma vez. Se a conexão for encerrada, será necessário criar um novo token para que a conexão possa ser restabelecida. O token em si é válido até o timestamp de expiração do token incluído na resposta. Quando um usuário final quiser se conectar a uma sala de chat, o cliente deve solicitar um token ao aplicativo do servidor. O aplicativo do servidor cria um token e o repassa para o cliente. Os tokens devem ser criados para usuários finais sob demanda. Para criar um token de autenticação de dados, siga as instruções abaixo. Ao criar um token de chat, use os campos de solicitação para transmitir dados sobre o usuário final do chat e as funcionalidades de mensagens do usuário final. Para obter mais detalhes, consulte [CreateChatToken](https://docs.aws.amazon.com//ivs/latest/ChatAPIReference/API_CreateChatToken.html) na *Referência de API do Chat do IVS*. ## Instruções do AWS SDK Criar um token de chat com o AWS SDK exige que você baixe e configure o SDK no aplicativo primeiro. As instruções para o AWS SDK usando JavaScript são descritas a seguir. **Importante:** esse código deve ser executado no lado do servidor e sua saída transferida para o cliente. **Pré-requisito**: para usar o exemplo de código abaixo, você precisa carregar o AWS JavaScript SDK em sua aplicação. Para obter mais detalhes, consulte .[Conceitos básicos do AWS SDK for JavaScript](https://docs.aws.amazon.com/sdk-for-javascript/v3/developer-guide/getting-started.html). ``` async function createChatToken(params) { const ivs = new AWS.Ivschat(); const result = await ivs.createChatToken(params).promise(); console.log("New token created", result.token); } /* Create a token with provided inputs. Values for user ID and display name are from your application and refer to the user connected to this chat session. */ const params = { "attributes": { "displayName": "DemoUser", }", "capabilities": ["SEND_MESSAGE"], "roomIdentifier": "arn:aws:ivschat:us-west-2:123456789012:room/g1H2I3j4k5L6", "userId": 11231234 }; createChatToken(params); ``` ## Instruções da CLI A criação de um token de chat com a AWS CLI é uma opção avançada e exige que você baixe e configure a CLI em sua máquina primeiro. Para obter mais detalhes, consulte o [Guia do usuário da Interface de Linhas de Comando da AWS](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-welcome.html). Observação: gerar tokens com a AWS CLI é bom para fins de teste, mas para uso em produção, recomendamos gerar tokens no lado do servidor com o AWS SDK (consulte as instruções acima). 1. Execute o comando `create-chat-token` junto com o identificador da sala e o ID do usuário para o cliente. Inclua qualquer um destes recursos: `"SEND_MESSAGE"`, `"DELETE_MESSAGE"`, `"DISCONNECT_USER"`. (Opcionalmente, inclua a duração da sessão (em minutos) ou atributos personalizados (metadados) sobre a sessão de chat. Esses campos não são exibidos abaixo.) ``` aws ivschat create-chat-token --room-identifier "arn:aws:ivschat:us-west-2:123456789012:room/g1H2I3j4k5L6" --user-id "11231234" --capabilities "SEND_MESSAGE" ``` 1. Isso retorna um token de cliente: ``` { "token": "abcde12345FGHIJ67890_klmno1234PQRS567890uvwxyz1234.abcd12345EFGHI67890_jklmno123PQRS567890uvwxyz1234abcde12345FGHIJ67890_klmno1234PQRS567890uvwxyz1234abcde", "sessionExpirationTime": "2022-03-16T04:44:09+00:00", "tokenExpirationTime": "2022-03-16T03:45:09+00:00" } ``` 1. Salve esse token. Você precisará dele para se conectar à sala de chat e enviar ou receber mensagens. Será necessário gerar outro token de chat antes que sua sessão termine (conforme indicado por `sessionExpirationTime`). # Etapa 4: enviar e receber sua primeira mensagem Use o token do chat para se conectar a uma sala de chat e enviar sua primeira mensagem. Veja um exemplo de código JavaScript abaixo. Os SDKs do cliente do IVS também estão disponíveis: consulte [Chat SDK: Android Guide](chat-sdk-android.md), [Chat SDK: iOS Guide](chat-sdk-ios.md) e [Chat SDK: JavaScript Guide](chat-sdk-js.md). **Serviço regional:** o exemplo de código abaixo se refere à “região de sua preferência compatível”. O Amazon IVS Chat oferece endpoints regionais que podem ser usados para fazer as solicitações. Para a API do Amazon IVS Chat Messaging, a sintaxe geral de um endpoint regional é: + wss://edge.ivschat..amazonaws.com Por exemplo, wss://edge.ivschat.us-west-2.amazonaws.com é o endpoint da região Oeste dos EUA (Oregon). Para obter uma lista das regiões compatíveis, consulte as informações sobre o Amazon IVS Chat na [página do Amazon IVS](https://docs.aws.amazon.com/general/latest/gr/ivs.html) na *AWS General Reference* (Referência geral da AWS). ``` /* 1. To connect to a chat room, you need to create a Secure-WebSocket connection using the client token you created in the previous steps. Use one of the provided endpoints in the Chat Messaging API, depending on your AWS region. */ const chatClientToken = "GENERATED_CHAT_CLIENT_TOKEN_HERE"; const socket = "wss://edge.ivschat.us-west-2.amazonaws.com"; // Replace “us-west-2” with supported region of choice. const connection = new WebSocket(socket, chatClientToken); /* 2. You can send your first message by listening to user input in the UI and sending messages to the WebSocket connection. */ const payload = { "Action": "SEND_MESSAGE", "RequestId": "OPTIONAL_ID_YOU_CAN_SPECIFY_TO_TRACK_THE_REQUEST", "Content": "text message", "Attributes": { "CustomMetadata": "test metadata" } } connection.send(JSON.stringify(payload)); /* 3. To listen to incoming chat messages from this WebSocket connection and display them in your UI, you must add some event listeners. */ connection.onmessage = (event) => { const data = JSON.parse(event.data); displayMessages({ display_name: data.Sender.Attributes.DisplayName, message: data.Content, timestamp: data.SendTime }); } function displayMessages(message) { // Modify this function to display messages in your chat UI however you like. console.log(message); } /* 4. Delete a chat message by sending the DELETE_MESSAGE action to the WebSocket connection. The connected user must have the "DELETE_MESSAGE" permission to perform this action. */ function deleteMessage(messageId) { const deletePayload = { "Action": "DELETE_MESSAGE", "Reason": "Deleted by moderator", "Id": "${messageId}" } connection.send(deletePayload); } ``` Parabéns, já está tudo pronto\$1 Agora você tem uma aplicação de chat simples que pode enviar ou receber mensagens. # Etapa 5: verificar limites de cota de serviço (opcional) Suas salas de chat serão escaladas junto com sua transmissão ao vivo do Amazon IVS, para permitir que todos os espectadores se envolvam em conversas por chat. Porém, todas as contas do Amazon IVS têm limites de número de participantes do chat simultâneo e na taxa de entrega de mensagens. *Certifique-se de que seus limites são adequados e, se necessário, solicite um aumento, especialmente se você estiver planejando um grande evento de streaming*. [Para obter detalhes, consulte [Service Quotas (streaming de baixa latência)](https://docs.aws.amazon.com/ivs/latest/LowLatencyUserGuide/service-quotas.html), [Service Quotas (streaming em tempo real)](https://docs.aws.amazon.com/ivs/latest/RealTimeUserGuide/service-quotas.html) e Service Quotas (Chat)](service-quotas.md).