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

Menu

Expand
Calificar esta página:

SDK de Voice para Javascript: Prácticas recomendadas

Estás viendo la documentación de la versión 2.X del SDK de Voice para JavaScript. Consulta la Guía de migración para aprender a migrar de 1.X a 2.X o consulta la documentación específica de 1.x.

Descripción general

Los SDK de Twilio Voice te permiten crear experiencias de llamada de alta calidad directamente en las aplicaciones web y móviles. Se pueden utilizar en casos de uso como contact center, marcadores de ventas, llamadas entre pares y demás, mediante herramientas de desarrollo web y de aplicaciones móviles conocidas.

Hay algunas cosas que debes tener en cuenta para sacar el máximo provecho del SDK de Voice para JavaScript. El seguimiento de estas prácticas recomendadas garantizará que los usuarios tengan una experiencia de llamada perfecta. También facilitarán la solución de problemas de conexión y calidad de llamada.

Para sacar el máximo provecho de esta guía, utilízala junto con los inicios rápidos y la documentación del SDK de Voice para JS.

Depuración

El SDK para JavaScript expone un registrador basado en loglevel para permitir la configuración del registro en tiempo de ejecución.

Para configurar el nivel de registro, utiliza la propiedad logLevel del objeto DeviceOptions a la hora de crear una instancia de Twilio.Device o llamar a device.updateOptions() en una instancia de Twilio.Device.

El valor de DeviceOptions.logLevel es un número que corresponde a los diferentes niveles de registro disponibles:

Valor de DeviceOptions.logLevel Nivel de registro
logLevel: 0 "TRACE" (RASTREO)
logLevel: 1 "DEBUG" (DEPURACIÓN)
logLevel: 2 "INFO" (INFORMACIÓN)
logLevel: 3 "WARN" (ADVERTENCIA)
logLevel: 4 "ERROR"
logLevel: 5 "SILENT" (SILENCIO)

A continuación, se muestran ejemplos de cómo habilitar el registro de nivel "DEBUG" (DEPURACIÓN) a la hora de crear una instancia de Twilio.Device y llamar a device.updateOptions().

// al crear una instancia de Twilio.Device

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


// al llamar a device.updateOptions()

const deviceOptions = {
  logLevel: 1
}

device.updateOptions(deviceOptions);

Proporcionar información a los usuarios cuando el estado del dispositivo cambie

El SDK para JavaScript se basa en eventos de la interfaz EventEmitter para controlar la experiencia de llamada. Si se desea alertar al usuario de una llamada entrante, es necesario, por ejemplo, asignar un detector para el evento Device.on('incoming'). Asimismo, el SDK también proporciona eventos para supervisar el estado de Device y Call.

Reflejar en la IU que utiliza estos eventos los cambios en el estado de Device y Call a menudo puede marcar la diferencia entre brindar una experiencia de llamada fluida y una extremadamente frustrante. Estos son algunos de los eventos importantes que deberías detectar:

El dispositivo está listo para las llamadas: .on('registered', handler)

El evento Device.on('registered') se activa una vez que el dispositivo se ha configurado correctamente mediante un token de acceso válido y se registra para recibir llamadas entrantes (ten en cuenta que el client [cliente] de voz puede realizar llamadas salientes aunque no esté registrado. Consulta esto para obtener más información). Utiliza este evento para cambiar un elemento de la IU, como un indicador de estado, por ejemplo. De esta forma, se garantiza que el usuario sepa que la aplicación está online y lista para comenzar a realizar y recibir llamadas.

El dispositivo no está disponible para llamadas: .on('unregistered', handler)

Del mismo modo, es importante notificar al usuario si la aplicación se desconecta en algún momento. Utiliza el evento Device.on('unregistered') para cambiar el indicador de estado a offline y alertar al usuario. Este evento se activa si la conexión con Twilio se interrumpe por algún motivo o si caduca el token de acceso. También debes utilizar este evento para intentar una reconexión mediante Device.register().

Algo está mal: .on('error', handler)

El manejo de este evento permite detectar y controlar los errores del dispositivo correctamente. Puedes ver la lista completa de errores que emite este controlador aquí. Estos son algunos de los errores más comunes:

  • Errores en el token de acceso, ya sea debido a su caducidad o invalidación. Para evitar la caducidad del token de acceso, puedes implementar código para actualizar automáticamente el token de acceso de la app.
  • El usuario deniega a su aplicación el acceso al micrófono Puedes utilizar esta opción para desactivar el botón de llamada e indicar al usuario que proporcione acceso al micrófono.

Gestionar con elegancia situaciones sin respuesta

También es importante gestionar con elegancia las situaciones en las que una llamada al cliente de voz queda sin respuesta a pesar de estar online. La forma de gestionar esto depende de cómo se incorpore el cliente de voz a la llamada:

Uso de <Dial>

Las llamadas entrantes se pueden conectar al cliente de voz mediante el sustantivo <Client> del verbo <Dial>. En este caso, debes configurar el atributo timeout con el valor que mejor funcione para tu caso de uso. También debes configurar una URL de acción mediante el atributo action. Twilio realizará una petición a la URL con estos parámetros una vez que la llamada se concluya, lo que incluye el resultado de la llamada (si la contestaron o no).

A través de la API REST

También puedes utilizar la API REST para incluir un cliente de voz en una llamada. Esto implica realizar primero una llamada saliente al cliente. Cuando el client (cliente) contesta, el parámetro Url obtiene la instrucción TwiML que se utiliza para configurar la llamada. Puedes obtener más información sobre el uso de la API REST aquí. Es importante que establezcas el timeout que mejor funcione para tu caso de uso en la solicitud a la API. Ten en cuenta que el máximo es de 60 segundos para las llamadas realizadas al cliente de voz. Asegúrate de configurar una URL de devolución de estado mediante el parámetro StatusCallback y especifica los webhooks del evento de progreso de llamada mediante el parámetro StatusCallbackUrl. Esto garantiza que la aplicación conozca el resultado de la llamada.

Si el resultado de la llamada en ambas situaciones es que la llamada no recibe respuesta, es importante que se transmita esta información al agente de llamada. Una forma de hacerlo es dirigiéndolo al buzón de voz. Puedes utilizar el verbo <Record> para configurar el buzón de voz. Si la llamada no tiene respuesta, el agente de llamada se dirige a la instrucción TwiML que utiliza el verbo <Record> para dejar un mensaje en el buzón de voz.

Trabajar con micrófonos y getUserMedia

El SDK elegirá automáticamente los dispositivos de entrada y salida predeterminados a la hora de realizar o recibir llamadas. Sin embargo, recomendamos configurar el dispositivo de entrada lo antes posible para evitar problemas en el momento de conectarse a la llamada o aceptarla, por ejemplo, problemas de hardware o problemas relacionados con los permisos. En el siguiente fragmento de código se muestra cómo trabajar con dispositivos de entrada y configurar el micrófono para utilizarlo lo antes posible. Ten en cuenta que esta opción no es compatible con Firefox debido a este error.

// Nuestra IU es un menú desplegable que muestra los dispositivos de entrada disponibles (micrófonos).
// El usuario puede seleccionar un dispositivo de entrada.
const micOptions = document.createElement('select');
micOptions.addEventListener('change', () => {
  Twilio.Device.audio.setInputDevice(micOptions.value);
});

// Actualizar la IU con la lista actualizada de dispositivos disponibles
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 si la lista de dispositivos cambia, p. ej., cuando unos auriculares se conectan o desconectan.
// Configuramos controladores para actualizar nuestra lista desplegable con la nueva lista de dispositivos
Twilio.Device.on('registered', () => {
  // Suscribirse al evento para detectar cuando la lista de dispositivos cambie
  Twilio.Device.audio.on('deviceChange', () => updateMicOptions());
  
  // Es hora de llamar a getUserMedia para obtener los nombres de los dispositivos de entrada.
  // Esto es necesario para obtener las etiquetas. De lo contrario, solo tendremos los ID de los dispositivos.
  // También se recomienda que sepamos qué micrófono utilizar cuando se recibe la llamada.
  // Además, realizar esta acción aquí permite capturar errores de gUM (getUserMedia) de forma temprana
  // antes de aceptar o recibir una llamada, y nos permite brindar una experiencia de usuario mucho mejor
  navigator.mediaDevices.getUserMedia({ audio: true }).then((stream) => {
    updateMicOptions();
    
    // Llamar a getUserMedia iniciará la pista multimedia seleccionada.
    // Esto no es algo que queramos, ya que el usuario puede tener la impresión de que el micrófono está en uso.
    // Por lo tanto, debemos evitar que se inicien las pistas cuando no se necesitan.
    // Solo queremos obtener la lista de dispositivos de entrada, así que detenemos las pistas de inmediato.
    stream.getTracks().forEach(track => track.stop());
  }).catch(error => {
    // Manejar el error. Indicar al usuario que hay un problema con el micrófono. También podrías decirle
    // a tu actividad en segundo plano o generar una alerta para que el admin del sistema resuelva este problema.
    console.log(error);
  });
  
  // A la hora de manejar las llamadas entrantes, usa el dispositivo que se seleccionó anteriormente
  Twilio.Device.on('incoming', (connection) => {
    // Ahora podemos configurar el dispositivo de entrada que obtuvimos de updateMicOptions.
    // `Device` almacenará esto internamente. De esta forma, se evitarán las llamadas a getUserMedia. 
    Twilio.Device.audio.setInputDevice(micOptions.value)
      .then(() => connection.accept())
      .catch(error => {
        // No se pudo configurar el dispositivo de audio. Hubo un fallo,
        // lo más probable es que se trate de un fallo de hardware (auriculares).
        // Informa al usuario e intenta de nuevo o cuelga la llamada.
        // Aquí también puedes informar de esto al admin del sistema o al equipo de actividad en segundo plano para que ayuden con el problema
      });
  });
});

Supervisar la calidad de las llamadas con Voice Insights

Implementar Voice Insights en los SDK de Twilio Voice proporciona un análisis de calidad de las llamadas de los clientes. Proporciona una API REST para obtener estadísticas históricas de la calidad de las llamadas, como fluctuación, puntuación media de la opinión (MoS) y pérdida de paquetes. También proporciona un componente en el SDK para JavaScript que activa eventos cuando la calidad de la llamada cae por debajo de los umbrales aceptables. Se puede utilizar para notificar al usuario en tiempo real sobre problemas relacionados con la calidad de la llamada.

Voice Insights activa dos tipos de eventos en la interfaz: advertencias de red y advertencias de nivel de audio.

  • Las advertencias de red se activan cuando se produce una disminución de la calidad de la llamada, como lo indican las siguientes cuatro medidas: tiempo de ida y vuelta, o RTT; puntuación media de la opinión, o MOS; fluctuación, y pérdida de paquetes.
  • Los eventos de nivel de audio se activan cuando Insights detecta niveles de audio sin cambios. Aunque esto podría indicar un problema, normalmente indica que el audio del micrófono o dispositivo de entrada se ha silenciado.

Si implementas controladores para estos eventos y los reflejas en la IU, puedes notificar al usuario de la degradación de la calidad de la llamada o la existencia de problemas con la entrada de audio. Puedes utilizar esto para solicitar al usuario que tome medidas correctivas, como comprobar su conexión a Internet o el audio del dispositivo de entrada.

La implementación de Voice Insights en los SDK de Twilio Voice también puede facilitar la solución de problemas. En el panel de control de Voice Insights que hay en la consola se proporcionan métricas totales de la calidad de llamada de todas las llamadas, las cuales se pueden filtrar para ver solo las llamadas del cliente de voz. Esto es útil a la hora de identificar tendencias en las estadísticas de calidad de las llamadas. Por ejemplo, podrías identificar que los clientes con una versión de navegador determinada experimentan más problemas de calidad de audio. También se registran los eventos de configuración de llamadas, lo que te permite diagnosticar problemas de la conexión de llamadas. Los mismos datos también están disponibles en relación con las llamadas individuales.

Para obtener más información sobre Voice Insights, consulta la documentación.

Gestionar el entorno de llamadas

La calidad de las llamadas de VoIP se ve afectada en gran medida por factores del entorno, como la configuración del firewall, las condiciones de la red y el ancho de banda disponible, la versión del navegador (en el caso de WebRTC) y el sistema operativo, el micrófono y el hardware del altavoz. Es importante que revises nuestras prácticas recomendadas de implementación y la documentación de requisitos de conectividad antes de llevar la app a producción.

Si es posible, también deberías aprovechar la compatibilidad con DSCP, habilitada a partir del SDK de Voice para Javascript 1.3. DSCP, o punto de código de servicios diferenciados permite etiquetar paquetes para darles prioridad en la red. Los navegadores que admiten DSCP son capaces de etiquetar paquetes multimedia de llamada enviados por el cliente de voz de esta manera. Tu enrutador o elemento de red puede utilizar estas etiquetas para priorizar los paquetes multimedia de llamada por sobre otro tráfico de la red. Además, debes tener en cuenta que el enrutador o elemento de red también debe ser compatible con DSCP.

Actualmente, DSCP solo es compatible con Google Chrome. Para obtener ayuda en relación con la configuración de DSCP en un equipo Windows, consulta este artículo de Zendesk.

Utilizar el data center de Twilio más cercano

Twilio tiene una presencia global con data center en todo el mundo; revisa la lista completa de ubicaciones aquí. La conexión a edge locations (ubicaciones periféricas) minimiza la latencia, ya que permite que el dispositivo Twilio Client se conecte al punto de presencia más cercano. Hay dos formas de configurar el client (cliente) para que se conecte con Twilio:

  • Utiliza el enrutamiento de baja latencia global de Twilio para permitir que Twilio utilice las búsquedas en el DNS basadas en latencia para seleccionar el data center más cercano. Para hacerlo, omite el parámetro edge a la hora de crear el dispositivo.
  • Fuerza la selección de una ubicación periférica utilizando el parámetro edge. Puedes encontrar la lista de ubicaciones periféricas y sus direcciones IP aquí. Esta estrategia tiene sentido cuando todos los clientes de Twilio Voice estarán en la misma ubicación. Puedes crear instancias de Device con el parámetro edge o utilizar device.updateOptions para establecer la ubicación periférica.

Mantener los AccessTokens actualizados

El SDK de Voice para JavaScript ahora proporciona tres funciones para ayudarte a mantener actualizados los AccessTokens (tokens de acceso).

  1. El método device.updateToken()
  2. El evento 'tokenWillExpire' emitido por la instancia de Twilio.Device
    • De forma predeterminada, este evento se emitirá 10 segundos (10 000 milisegundos) antes de que caduque el token de acceso, pero puedes configurar este comportamiento con la propiedad DeviceOptions.tokenRefreshMs.
  3. La propiedad DeviceOptions.tokenRefreshMs
    • Esta propiedad permite configurar cuántos milisegundos se esperará antes de emitir el evento 'tokenWillExpire' asociado con la caducidad de un token de acceso.

Como se muestra en el siguiente ejemplo, puedes utilizar estas tres funciones juntas para mantener actualizado un token de acceso de forma automática.

const device = new Device(token, {
  // El evento 'tokenWillExpire' se emitirá 30 segundos antes de que el token de acceso caduque
  tokenRefreshMs: 30000,
});

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

Calificar esta página:

¿Necesitas ayuda?

Todos la necesitamos a veces; la programación es difícil. Obtén ayuda ahora de nuestro equipo de soporte, o recurre a la sabiduría de la multitud visitando Stack Overflow Collective de Twilio o navegando por la etiqueta de Twilio en Stack Overflow.

        
        
        

        Gracias por tus comentarios.

        Selecciona los motivos de tus comentarios. La información adicional que nos brindas nos ayuda a mejorar nuestra documentación:

        Enviando tus comentarios…
        🎉 Gracias por tus comentarios.
        Se produjo un error. Inténtalo de nuevo.

        Gracias por tus comentarios.

        thanks-feedback-gif