Utilizando as APIs da Vonage com o MongoDB Atlas – Parte 5

Nesta série:

• Parte 1 - O que é o MongoDB Atlas?

• Parte 2 - Como usar o Vonage Verify com logins

• Parte 3 - Como usar o Vonage para interações com os clientes

• Parte 4 - Como usar o Atlas para autenticação de usuários

• Parte 5 - Como usar o In-App Messaging no aplicativo da Vonage para notificações

Encerramos nossa série sobre o MongoDB Atlas e as APIs da Vonage com uma análise da nossa In-App Messaging API. Ao longo das outras partes da série, vimos como configurar o MongoDB Atlas e o Vonage na Parte 1, como adicionar o Vonage Verify a um aplicativo na Parte 2, permitindo a interação com o cliente por meio de nossas APIs de Mensagens e Meetings API e, finalmente, mostraremos como podemos utilizar nossa API de In-App Messaging para enviar notificações aos usuários conectados à seção de administração do nosso site.

In-App Messaging

O In-App Messaging faz parte de um conjunto abrangente de chamadas de API, sendo que a outra metade da API é o nosso produto In-App Voice. Como os nomes sugerem, o In-App Messaging lida com o envio de mensagens de texto de um dispositivo cliente para outro, enquanto o In-App Voice lida com o tráfego de voz. Essas APIs contam com SDKs para iOS, Android e navegadores web modernos. Apresentaremos o Client SDK em nossa demonstração, mas você pode ampliá-lo para permitir a comunicação entre plataformas a partir de qualquer combinação de Web, iOS e Android.

In-App Messaging e In-App Voice são suportados por duas outras APIs que compõem nosso produto Conversations. São elas: a Conversation API, que lida com eventos entre um ou mais membros, e a API de Usuários, que gerencia as informações de contexto do usuário. O fluxo de trabalho geral é o seguinte: um usuário se autentica por meio do seu aplicativo e é associado a um Usuário em nossa API de Usuários. Esse Usuário se tornará um Membro de várias Conversas, ou armazenamentos de eventos compostas por diferentes eventos acionados, como text, message:submitted, member:joined, etc.

Cada Client SDK se comunicará com esses servidores de back-end para facilitar a comunicação em tempo real por meio de eventos de Voice ou texto. Isso permite que você, como desenvolvedor, tenha uma única interface para interagir com nossas APIs, e os SDKs cuidam de todo o trabalho de conexão e interação com elas. Assim, você não precisa mais criar sistemas de mensagens dependentes de plataforma nem encontrar maneiras de transferir mensagens entre plataformas diferentes.

Usaremos a In-App Messaging API para nossa demonstração de restaurante a fim de enviar mensagens a qualquer usuário administrador conectado. Isso fará com que uma janela pop-up apareça na tela dele com um link para a reunião que foi solicitada. Embora a utilizemos apenas para uma única notificação, você pode expandir isso para um sistema de bate-papo completo. Usaremos a nexmo-client para lidar com todo o trabalho no navegador e usaremos um cliente personalizado em nosso código do servidor back-end para se comunicar com as Conversation APIs.

As notificações do administrador

Vamos começar analisando como funciona a seção de administração. Queremos que uma notificação apareça quando um usuário solicitar uma reunião. Para as notificações pop-up, podemos usar @meforma/vue-toaster, que é um plugin do VueJS que gera pop-ups no estilo “toast” (toasts são pequenas notificações que aparecem na parte inferior da tela e depois desaparecem).

Mas como recebemos a notificação? Precisamos usar o nexmo-client SDK da web para nos conectarmos ao nosso aplicativo da Vonage e, em seguida, nos inscrevermos na conversa correta ou na série de mensagens. Criamos um Componente de Notificação que se conectará à conversa e exibirá em uma janela pop-up todas as novas notificações que chegarem.

import ConversationClient from 'nexmo-client'
import { createToaster } from '@meforma/vue-toaster'
import { authenticationStore } from '../stores/authenticationStore';

const authStore = authenticationStore();
const toaster = createToaster({ dismissable: true });

async function boot() {
    const data = await fetch(import.meta.env.VITE_API_URL + '/jwt', {
        method: 'POST',
        body: JSON.stringify({username: authStore.username}),
        headers: {
            'Content-Type': 'application/json',
            'Authorization': 'Bearer ' + authStore.token
        }
    })
        .then(resp => resp.json())
        .catch(err => console.log(err));
    
    const jwt = data.token
    const conversationID = data.conversation

    const client = new ConversationClient({ debug: true })
    let app = await client.createSession(jwt)
    const conversation = await app.getConversation(conversationID)

    conversation.on("support_request", async (sender: any, event: any) => {
        toaster.show(`${event.body.email} has request support: <a target="_blank" href="${event.body.host_url}">Join Meeting</a>`);
    });
}

boot()

Precisamos de um token de autorização para conectar o SDK da web ao Vonage. Esse token é um JWT assinado com a chave privada que geramos na Parte 1, quando criamos um aplicativo do Vonage. Esse JWT permitirá que o SDK da web se comunique com as APIs do Vonage e realize a autenticação. Esse processo é muito semelhante à forma como o MongoDB Realms autenticou nosso usuário administrador.

Para obter informações completas sobre como criar JWTs de cliente para a Conversation API, consulte nossa documentação. Vamos ver como criamos o JWT daqui a pouco para que você possa ver um exemplo, mas, por enquanto, vamos continuar com o código do VueJS. No momento, precisamos apenas nos preocupar em solicitar ao nosso servidor back-end que gere um JWT para nossos usuários.

O servidor back-end retornará duas informações: o JWT assinado da Vonage e o ID da conversa à qual devemos nos conectar. Precisaremos disso para indicar ao SDK da web qual conversa deve ser monitorada.

Depois disso, criamos um novo ConversationClient(), um objeto do nexmo-client pacote. Chamamos createSession(jwt) esse método no objeto e passamos o JWT que nosso backend criou para nós. Isso autentica nossa aplicação web no Vonage. Em seguida, solicitamos que ele busque uma conversa específica, cujo ID foi retornado pelo nosso servidor backend.

Nosso aplicativo agora está escutando eventos, mas não está processando nada. Precisamos usar o conversation.on() método para processar as mensagens recebidas. Usaremos uma mensagem personalizada chamada support_request para passar esse nome como primeiro parâmetro. O segundo parâmetro é uma função de tratamento. Nossa função de tratamento extrairá as informações da solicitação de suporte e exibirá uma notificação.

É isso aí. Se você acessar a seção de administração e for até “Visualizar Pedidos”, você poderá ver isso em ação. Se você abrir uma nova janela, fazer login como cliente, enviar um pedido e iniciar uma Videochamada, uma nova notificação deverá aparecer na janela de administração.

Como geramos um token?

Antes de analisarmos o código do backend, vamos ver como criamos o JWT. Precisamos adicionar duas informações essenciais ao JWT para criar um token válido do lado do cliente. Uma delas é sub, que é o usuário para o qual o token está sendo gerado. A outra é path, uma lista de caminhos aos quais o JWT tem acesso.

app.post('/jwt', async (req, res) => {
    const { username } = req.body;
    const conversation = await conversations.fetchByName('pos-notifications');
    const conversationPath = `/*/conversations/${conversation.id}/**`;
    let acl = {
        "paths": {
            "/*/sessions/**": {},
          }
    }
    acl.paths[conversationPath] = { methods: ['GET'] }

    const key = readFileSync(process.env.VONAGE_PRIVATE_KEY);
    const token = tokenGenerate(process.env.VONAGE_APPLICATION_ID, key, {
        sub: username,
        acl: acl,
    });
    res.json({ token, conversation: conversation.id })
})

Para ajudar a restringir nosso token apenas ao que precisamos, definimos nossa ACL como /*/sessions/** e /*/conversations/<conversation-id>/**. Isso significa que nosso JWT é válido apenas para a conversa específica para a qual nossas notificações são enviadas, chamada pos-notifications. Se alguém conseguisse se apropriar do token, ele serviria apenas para acessar uma conversa.

Reforçamos ainda mais a segurança do JWT, informando que só permitiremos GET solicitações relacionadas à conversa. Isso significa que nosso front-end ou qualquer pessoa que tente usar o JWT só poderá ler a conversa, sem modificá-la. Em seu aplicativo, você deve restringir os caminhos e métodos de forma tão rigorosa quanto possível para o JWT.

Criação de uma notificação

Sabemos como ler os dados de uma conversa, mas como inserimos um evento nessa conversa? Se abrirmos nosso server.ts arquivo e acessarmos nossa /api/website/video-call rota, geramos um novo evento ali.

const orderRecord = await client.db('restaurant_pos_demo')
    .collection('orders')
    .updateOne(
        { _id: new ObjectId(orderNumber) },
        { $set: { meetingUrl: data._links.host_url.href}}
    )
    .then(async (document) => {
        const userRecord = await client.db('restaurant_pos_demo')
            .collection('users')
            .findOne({ _id: new ObjectId(decodedToken.user_id) });

        await conversations.addEventToConversation(
            'pos-notifications',
            userRecord.username, 
            {
                type: 'custom:support_request',
                body: { 
                    host_url: data._links.host_url.href,
                    email: userRecord.username
                }
            });

        res.json({
            guest_url: data._links.guest_url.href
        })
    });

Atualizamos o pedido com os novos URLs das reuniões. Assim que isso estiver concluído, consultamos o usuário no MongoDB usando a users coleção e findOne(). Isso nos fornece o registro do usuário autenticado e, então, podemos usar conversations.addEventToConversation() para inserir um novo evento em nossa conversa. Para todas as notificações, usamos uma conversa chamada pos-notifications.

addEventToConversation() é um wrapper que lida com grande parte do trabalho subjacente necessário para adicionar um evento a uma conversa e faz parte de um conjunto de métodos em conversation.ts que farão muitas consultas e configurações para nós.

Como mencionei anteriormente, a Conversation API é uma combinação da API de Conversas e da API de Usuários. Quando chamamos addEventToConversation(), o método tentará buscar uma conversa com um nome especificado. Essa busca por conversa irá gerar uma conversa com um nome (no nosso caso, pos-notification) caso ainda não exista.

Em seguida, precisamos de um membro ao qual associar o evento. Membros são usuários que fazem parte de uma conversa específica. Um membro faz parte de apenas uma conversa. No entanto, um usuário pode ser membro de várias conversas. addEventToConversation() Tentaremos localizar um membro pelo endereço de e-mail especificado. Se esse membro não fizer parte da conversa, também adicionaremos o evento. O sistema procurará um usuário com esse e-mail. Se esse usuário não existir, ele será criado. Esse usuário será então adicionado à conversa como membro, e as informações do membro serão retornadas.

Podemos, então, enviar o novo evento para a conversa. O evento é propagado a todos os clientes conectados que estiverem acompanhando a conversa. Quando enviamos um evento no servidor, todos os usuários conectados na página “Pedidos” receberão o evento e a notificação em janela pop-up.

Conclusão

Esta é apenas uma pequena amostra do que a Conversation API é capaz de fazer. Você pode criar interfaces de bate-papo com todos os recursos que os usuários esperam, como notificações de digitação, compartilhamento de imagens e armazenamento de mensagens. Além disso, tudo isso funciona em tempo real e é multiplataforma. Um usuário da web pode enviar uma notificação para um cliente iOS da mesma forma que para um cliente Android ou outro cliente web.

Você também pode combinar isso com o In-App Voice para oferecer comunicação por voz em tempo real entre vários clientes ou integrá-lo à nossa Voice API, permitindo que um usuário do aplicativo ligue para um telefone ou vice-versa. O cliente poderia, por exemplo, ligar para o restaurante, e o restaurante poderia atender diretamente no navegador dele!

Isso encerra nosso tour pelo MongoDB Atlas e por algumas APIs complementares da Vonage. Esperamos que esta série tenha servido de inspiração para você conhecer o que cada uma de nossas plataformas oferece e como elas podem ser úteis para você. Como sempre, entre em contato com nossos especialistas em desenvolvimento caso tenha alguma dúvida.

Boa programação!

• Parte 1 - O que é o MongoDB Atlas?

• Parte 2 - Como usar o Vonage Verify com logins

• Parte 3 - Como usar o Vonage para interações com os clientes

• Parte 4 - Como usar o Atlas para autenticação de usuários

• Parte 5 - Como usar o In-App Messaging no aplicativo da Vonage para notificações