You are viewing the Portuguese (Brazil) site, but your language preference is set to English. Switch to English site →

Menu

Expand
Classifique esta página:

SDK de JavaScript do Voice: Melhores práticas

Você está visualizando a documentação da versão 2.X do Voice JavaScript SDK. Consulte o Guia de migração para saber como migrar do 1.X para o 2.X ou veja a documentação específica do 1.x.

Visão geral

O SDKs do Twilio Voice permitem que criar experiências de chamada de alta qualidade diretamente em aplicativos de dispositivos móveis e da Web. Eles podem ser usados para criar casos de uso, como contact centers, discadores de vendas, chamadas ponto a ponto e mais usando ferramentas familiares de desenvolvimento para Web e dispositivos móveis.

Há algumas coisas para ter em mente para aproveitar ao máximo o Voice JavaScript SDK. Seguir essas práticas recomendadas garantirá que seus usuários tenham uma experiência de chamada sem percalços. Elas também facilitarão a resolução de problemas de conexão e de qualidade de chamada.

Para aproveitar este guia ao máximo, use‐o junto com os inícios rápidos e a documentação do Voice JS SDK.

Depuração

O SDK do JavaScript expõe um agente baseado em nível de log para permitir a configuração do registro de log em tempo de execução.

Para configurar o nível de log, use a propriedade logLevel no objeto DeviceOptions ao instanciar um Twilio.Device ou ao chamar o device.updateOptions() em uma instância do Twilio.Device.

O valor do DeviceOptions.logLevel é um número que corresponde aos diferentes níveis de registro disponíveis:

Valor do DeviceOptions.logLevel Nível de registro
logLevel: 0 "TRACE"
logLevel: 1 "DEBUG"
logLevel: 2 "INFO"
logLevel: 3 "WARN"
logLevel: 4 "ERROR"
logLevel: 5 "SILENT"

Abaixo estão exemplos de como habilitar o nível de registro "DEBUG" ao instanciar um Twilio.Device e ao chamar o device.updateOptions().

// ao instanciar um dispositivo Twilio.Device

const device = new Twilio.Device (token, { logLevel: 1 });


// ao chamar device.updateOptions()

const deviceOptions = {
  logLevel: 1
}

device.updateOptions(deviceOptions);

Dê feedback aos usuários quando o estado do dispositivo for alterado

O SDK do JavaScript depende de eventos que seguem a interface EventEmiter para controlar a experiência de chamada. Por exemplo, alertar o usuário sobre uma chamada recebida requer escutar para o evento Device.on('incoming'). Da mesma forma, o SDK também fornece eventos para monitorar os estados Device e Call.

Trazer a tona alterações nos estados Device e Call na interface do usuário usando esses eventos pode muitas vezes ser a diferença entre uma experiência de chamada tranquila e uma extremamente frustrante. Eventos importantes a serem escutados incluem os seguintes:

O dispositivo está pronto para chamadas: .on('registered', handler)

O evento Device.on('registered') é acionado quando o dispositivo é configurado com êxito usando um access token (token de acesso) válido e é registrado para receber chamadas (observe que o client [cliente] Voice ainda pode fazer chamadas outbound se não estiver registrado; consulte mais informações aqui). Use este evento para alterar um elemento de interface do usuário, como um indicador de status. Isso garante que o usuário esteja ciente de que seu aplicativo está online e pronto para começar a fazer e receber chamadas.

O dispositivo não está disponível para chamadas: .on('unregistered', handler)

Da mesma forma, é importante notificar o usuário se o aplicativo ficar offline a qualquer momento. Use o evento Device.on('unregistered') para alterar o indicador de status para off‐line para alertar o usuário. Esse evento é acionado se a conexão com a Twilio cair por algum motivo ou se o access token (token de acesso) expirar. Você também deve usar esse evento para tentar se reconectar usando o Device.register().

Algo deu errado: .on('error', handler)

O manejo desse evento permite que você capture e lide com os erros do dispositivo normalmente. Você pode ver a lista de erros exibidos por este manipulador aqui. Alguns erros comumente encontrados são:

  • Erros com o access token (token de acesso) devido à expiração ou invalidação. Para evitar a expiração do access token (token de acesso), você pode implementar um código para atualizar automaticamente o access token (token de acesso) do seu app.
  • O usuário que nega acesso do seu aplicativo ao microfone. Você pode usar isso para desabilitar o botão de chamada e instruir o usuário a fornecer acesso ao microfone.

Lide com situações sem respostas sem problemas

Também é importante lidar com situações em que uma chamada para o client (cliente) Voice não é atendida, apesar de estar on‐line. Dependendo de como o client (cliente) Voice é trazido para a chamada, existem diferentes formas de lidar com a situação:

Uso do <Dial>

As chamadas recebidas podem ser conectadas ao client (cliente) Voice usando o substantivo <Client> (cliente) do verbo <Dial>. Nesse caso, você deve definir o atributo timeout para um valor que funcione melhor para seu caso de uso. Você também deve configurar um URL de ação usando o atributo action. A Twilio faz uma solicitação para este URL com esses parâmetros assim que a chamada for concluída e inclui informações sobre o resultado da chamada (se ela foi atendida ou não).

Como usar a API REST

Você também pode usar a API REST para trazer um client (cliente) Voice para uma chamada. Isso envolve primeiro fazer uma chamada outbound para o Client (cliente). Quando o client (cliente) atende, o parâmetro Url recupera a TwiML que é usada para configurar a chamada. Você pode saber mais sobre como usar a API REST aqui. É importante definir um Timeout na solicitação da API que funcione melhor para seu caso de uso. Observe que o máximo é 60 segundos para chamadas feitas para o client (cliente) Voice. Certifique‐se de configurar um URL de retorno de chamada usando o parâmetro StatusCallback e especifique os webhooks do evento do progresso da chamada usando o parâmetro StatusCallbackUrl. Isso garante que seu aplicativo saiba o resultado da chamada.

Se o resultado da chamada em ambas as situações for não atendida, é importante que isso seja transmitido ao autor da chamada. Uma maneira de fazer isso é direcioná‐los para o correio de voz. Você pode usar o verbo <Record> para configurar o correio de voz. Se a chamada não for atendida, o autor da chamada será direcionado para o TwiML que usa o verbo <Record> para deixar um correio de voz.

Como trabalhar com microfones e getUserMedia

O SDK escolherá automaticamente os dispositivos de entrada e saída padrão ao fazer ou receber chamadas. No entanto, recomendamos configurar o dispositivo de entrada o mais cedo possível para evitar problemas na conexão de chamada ou na hora da aceitação; por exemplo, problemas de hardware ou problemas relacionados a permissões. O fragmento de código a seguir demonstra como trabalhar com dispositivos de entrada e definir o microfone a ser usado o mais rápido possível. Observe que isso não é compatível com o Firefox devido a este bug.

// Nossa interface do usuário é um menu suspenso que mostra os dispositivos de entrada disponíveis (microfones).
// O usuário pode selecionar o dispositivo de entrada.
const micOptions = document.createElement('select');
micOptions.addEventListener('change', () => {
  Twilio.Device.audio.setInputDevice(micOptions.value);
});

// Atualizar interface do usuário com a lista atualizada de dispositivos disponíveis
const updateMicOptions = () => {
  micOptions.innerHTML = '';
  Twilio.Device.audio.availableInputDevices.forEach(d => {
    const option = document.createElement('option');
    option.value = d.deviceId;
    option.innerText = d.label;
    micOptions.appendChild(option);
  });
};

// Queremos detectar se a lista de dispositivos muda; por exemplo, se um headset foi conectado/desconectado.
// Configuramos manipuladores para atualizar a nossa lista suspensa com a nova lista de dispositivos
Twilio.Device.on('registered', () => {
  // Inscreva‐se ao evento para saber quando a lista de dispositivos mudar
  Twilio.Device.audio.on('deviceChange', () => updateMicOptions());
  
  // Agora é hora de chamar o getUserMedia para obter os nomes dos dispositivos de entrada.
  // Isso é necessário para obter os rótulos. Caso contrário, teremos somente IDs de dispositivo.
  // Também é recomendado garantir que sabemos qual microfone usar quando a chamada é recebida.
  // Além disso, executar esta ação aqui permite a captura antecipada de erros gUM (getUserMedia)
  // antes de aceitar/receber uma chamada e é possível criar uma experiência de usuário muito melhor
  navigator.mediaDevices.getUserMedia({ audio: true }).then((stream) => {
    updateMicOptions();
    
    // Chamar o getUserMedia iniciará o faixa de mídia selecionada.
    // Isso não é desejado, pois o usuário pode ter a impressão de que o microfone está em uso.
    // Por isso, queremos que as faixas sejam iniciadas quando não forem necessárias.
    // Só queríamos obter a lista de dispositivos de entrada, por isso, paramos as faixas imediatamente.
    stream.getTracks().forEach(track => track.stop());
  }).catch(error => {
    // Lidar com erro. Diga ao usuário que há um problema com o microfone. Você também pode dizer
    // seu back‐end ou emitir um alerta para o administrador do sistema resolver esse problema.
    console.log(error);
  });
  
  // Ao lidar com chamadas recebidas, use o dispositivo selecionado anteriormente
  Twilio.Device.on('incoming', (conexão) => {
    // Agora podemos definir o dispositivo de entrada que lemos em updateMicOptions.
    // "Device" armazenará isso internamente. Isso evitará chamadas getUserMedia. 
    Twilio.Device.audio.setInputDevice(micOptions.value)
      .then(() => connection.accept())
      .catch(erro => {
        // Não foi possível definir o dispositivo de áudio. Algo falhou,
        // possivelmente uma falha de hardware (headset).
        // Informe o usuário e tente novamente ou desligue a chamada.
        // Aqui você também pode relatar isso ao seu back‐end ou administrador do sistema para obter ajuda para resolver o problema
      });
  });
});

Monitore a qualidade das chamadas com o Voice Insights

O Voice Insights para os SDKs do Twilio Voice fornece análises da qualidade de chamada para as chamadas de clientes. Ele fornece uma API REST para recuperar estatísticas históricas da qualidade de chamada, como jitter, MOS (Mean Opinion Score, pontuação média de opinião) e perda de pacote. Ele também fornece um componente no SDK do JavaScript que dispara eventos quando a qualidade da chamada cai abaixo dos limites aceitáveis. Isso pode ser usado para notificar o usuário em tempo real sobre problemas com a qualidade da chamada.

O Voice Insights aciona dois tipos de eventos no front‐end: avisos de rede e avisos de nível de áudio.

  • Os avisos de rede são disparados quando há uma redução na qualidade da chamada, conforme indicado por três medidas: tempo de ida e volta ou RTT, pontuação média de opinião ou MOS, jitter e perda de pacotes.
  • Os eventos de nível de áudio são disparados quando o Insights detecta níveis de áudio inalterados. Embora isso possa indicar um problema, eles geralmente apontam que o áudio foi silenciado no microfone ou no dispositivo de entrada.

Ao implementar manipuladores para esses eventos e mostrá‐los na interface do usuário, você pode notificar o usuário sobre a degradação na qualidade da chamada ou problemas com a entrada de áudio. Isso pode ser usado para solicitar que o usuário tome medidas corretivas, como verificar a conexão com a Internet ou o áudio do dispositivo de entrada.

Implementar o Voice Insights para os SDKs do Twilio Voice também pode facilitar muito a resolução de problemas. O dashboard do Voice Insights no console fornece métricas agregadas de qualidade de chamada em todas as chamadas e pode ser filtrado apenas para chamadas de client (cliente) Voice. Isso é útil para ver tendências em suas estatísticas de qualidade de chamada. Por exemplo, você pode observar que as chamadas do client (cliente) com uma determinada versão do navegador apresentam mais problemas de qualidade. Ele também registra eventos de configuração de chamadas, possibilitando o diagnóstico de problemas com a conexão de chamadas. Os mesmos dados também são disponibilizados para chamadas individuais.

Para saber mais sobre o Voice Insights, confira os documentos.

Gerencie o ambiente de chamadas

A qualidade da chamada VoIP é fortemente influenciada por fatores ambientais como configuração de firewall, condições de rede e largura de banda disponível, versão do navegador (para WebRTC), além de SO e hardware de microfone e alto‐falante. É importante que você revise nossas práticas recomendadas de implantação e a documentação de requisitos de conectividade antes de colocar seu app em produção.

Se for possível, você também deve aproveitar o suporte ao DSCP habilitado na versão 1.3 em diante do Voice JavaScript SDK. O DSCP, ou Ponto de código de serviços diferenciados, permite que os pacotes sejam marcados para priorizá‐los na rede. Os navegadores que suportam o DSCP são capazes de marcar pacotes de mídia de chamada enviados pelo client (cliente) Voice dessa maneira. Seu roteador ou elemento de rede pode então usar essas tags para priorizar pacotes de mídia de chamada em relação a outro tráfego na rede. Além disso, observe que seu roteador ou elemento de rede precisa ser compatível com DSCP.

Atualmente, apenas o Google Chrome é compatível com o DSCP. Para obter ajuda para configurar o DSCP em uma máquina Windows, consulte este artigo do Zendesk.

Use o data center da Twilio mais próximo

A Twilio tem presença global em data centers em todo o mundo. Veja a lista completa dos locais aqui. A conexão com edge locations (locais de borda) minimiza a latência, permitindo que o dispositivo do Twilio Client se conecte ao ponto de presença mais próximo. Há duas maneiras de configurar o Client (cliente) para se conectar à Twilio:

  • Use o roteamento de baixa latência global da Twilio para permitir que a Twilio use lookups de DNS baseados em latência para escolher o data center mais próximo. Você pode fazer isso omitindo o parâmetro edge ao criar o dispositivo.
  • Forçar a seleção de edge (borda) usando o parâmetroedge. Você pode encontrar a lista de edges (bordas) e seus endereços IP aqui. Essa abordagem faz sentido se todos os clients (clientes) do Twilio Voice estiverem baseados no mesmo edge location (local de borda). Você pode instanciar o dispositivo com o parâmetro edge ou usar device.updateOptions para definir o edge (borda).

Mantenha os AccessTokens (tokens de acesso) atualizados

O Voice JavaScript SDK fornece três recursos para ajudar a manter os AccessTokens (tokens de acesso) atualizados.

  1. O método device.updateToken()
  2. O evento 'tokenWillExpire' emitido pela instância do Twilio.Device
    • Por padrão, esse evento é emitido 10 segundos (10.000 milissegundos) antes de o AccessToken (Token de acesso) expirar, mas você pode configurar esse comportamento com a propriedade DeviceOptions.tokenRefreshMs.
  3. A propriedade DeviceOptions.tokenRefreshMs
    • Esta propriedade permite que você configure quantos milissegundos antes da expiração de um AccessToken (Token de acesso) o evento 'tokenWillExpire' será emitido.

Como mostrado no exemplo abaixo, você pode usar esses três recursos juntos para manter um AccessToken (Token de acesso) atualizado automaticamente.

const device = new Device(token, {
  // O evento 'tokenWillExpire' será emitido 30 segundos antes de o AccessToken (Token de acesso) expirar
  tokenRefreshMs: 30000,
});

device.on('tokenWillExpire', () => {
  return getTokenViaAjax().then(token => device.updateToken(token));
});

Classifique esta página:

Precisa de ajuda?

Às vezes, todos nós precisamos; a programação é difícil. Receba ajuda agora da nossa equipe de suporte, ou confie na sabedoria da multidão navegando pelo Stack Overflow Collective da Twilio ou buscando a tag Twilio no Stack Overflow.

        
        
        

        Obrigado pelo seu feedback!

        Selecione o(s) motivo(s) para seu feedback. As informações adicionais que você fornece nos ajudam a melhorar nossa documentação:

        Enviando seu feedback...
        🎉 Obrigado pelo seu feedback!
        Algo deu errado. Tente novamente.

        Obrigado pelo seu feedback!

        thanks-feedback-gif