Guía de transición de vídeo de Vonage para Java

Transición de com.tokbox:opentok-server-sdk a com.vonage:server-sdk.

Introducción

Propósito

El objetivo de este documento es brindar un punto de partida para la transición de OpenTok Java Server SDK a Vonage Java Server SDK.

Alcance

Este documento presupone que está utilizando al menos la versión 4.0.0 o posterior de la aplicación SDK Java de OpenTok. La Video API se agregó al Java Server SDK en la versión 8.0.0. Debes usar la última versión del Vonage Java SDK, que puedes encontrar en GitHub o Maven Central.

Supuestos

Esta guía está pensada para que la siga un ingeniero de software profesional. Se asume al menos un nivel básico de competencia con Java, herramientas comunes para desarrolladores Java, sistemas de compilación (Maven o Gradle) y Git (u otro sistema de control de versiones). Deberá sentirse cómodo leyendo y escribiendo código Java, gestionando las dependencias del proyecto, desplegando y ejecutando un proyecto Java. Una introducción al lenguaje Java, la plataforma y las herramientas asociadas va mucho más allá del alcance de este documento.

Recursos

Los siguientes enlaces son útiles como lecturas complementarias de este documento y como referencia para todo lo que no se haya tratado en él:

Vonage

TokBox

Planificación de la migración

Antes de realizar la transición de OpenTok a Vonage Video, debes tener en cuenta la magnitud de la tarea para establecer expectativas realistas.

Evaluar el impacto

La primera pregunta a responder es: ¿qué parte del código de tu aplicación depende del SDK de OpenTok? Haz una lista de todos los archivos en los que se utiliza directamente el SDK. Es decir, cualquier archivo fuente Java que contenga importaciones del SDK. com.opentok paquete. Puede buscar en los archivos de su proyecto la declaración import com.opentok utilizando un IDE o una herramienta de línea de comandos para identificar los archivos afectados.

Cronología

Account the time required to complete the transition. Esto dependerá de tu experiencia con el proyecto y su impacto, así como de las pruebas. Es fundamental contar con un buen conjunto de pruebas para poder verificar la equivalencia entre OpenTok y Vonage Video. El tiempo que tomará completar la transición es aproximadamente proporcional a la cantidad de lugares donde se utiliza el SDK de OpenTok en tu código, así como a la variedad de funciones utilizadas. Algunas llamadas a la API serán más simples de reemplazar que otras.

Versionado

Lo ideal es que crees una nueva rama en tu sistema de control de versiones para la transición, de modo que puedas hacer cambios gradualmente y con frecuencia sin romper el proyecto existente. También puede utilizar las pruebas del proyecto existente como un oráculo para la corrección. Lo ideal sería fusionar la rama de transición con la rama principal una vez completada la conversión.

Principales cambios y consideraciones

Nuevas funciones y normas

La Video API de Vonage tiene paridad de funciones con OpenTok, y el SDK de Java se mantiene activamente en línea con la especificación de la API. Una de las diferencias entre los SDK Java de OpenTok y Vonage es que el SDK Java utiliza un modelo de datos con tipificación más fuerte en lugar de cadenas simples. También tiene una mayor coherencia con otras API en el SDK y sigue convenciones que deberían hacer que el uso del SDK sea intuitivo. Otra diferencia clave es que las clases request y response están unificadas. Por ejemplo, se puede utilizar la clase Archive tanto para crear como para recuperar un archivo, mientras que en OpenTok se utilizaría la clase ArchiveProperties para la solicitud y Archive para la respuesta. Al igual que el SDK de OpenTok, el SDK de Java utiliza el patrón Builder para construir objetos de solicitud.

A diferencia del SDK de OpenTok, el SDK de Vonage no utiliza excepciones verificadas. Por lo tanto, ya no necesitas hacer un try {...} catch (InvalidArgumentException ex)lo que le permitirá reducir el desorden de su código. Si desea capturar excepciones de llamadas a la API fallidas (es decir, sin código de estado 2xx), puede capturar VideoResponseException en lugar de OpenTokException.

Actualización de la dependencia

En primer lugar, deberás actualizar las dependencias de tu sistema de compilación para utilizar el SDK Java de Vonage en lugar de OpenTok. Las instrucciones para hacerlo dependerán de tu sistema de compilación. Puedes encontrar instrucciones sobre cómo incluir la última versión de Vonage Java SDK en tu compilación en Maven Central o mvnrepository.com.

Para una migración gradual, puedes incluir tanto las dependencias de OpenTok como las de Vonage en tu proyecto, sin embargo, recomendamos encarecidamente que esto sea sólo para pruebas y no para despliegues en producción, ya que el SDK de OpenTok tiende a utilizar versiones antiguas de las dependencias que pueden causar problemas en tiempo de ejecución.

Nombre del paquete

Una vez que hayas agregado el Vonage Java SDK a tu classpath mediante tu herramienta de compilación, podrás comenzar a utilizarlo en tu código.

Puede sustituir las importaciones del com.opentok y com.opentok.exception paquetes con com.vonage.client.video. Buscar y reemplazar en el IDE o en el editor de código del proyecto debería ayudar a resolver la mayoría de los errores de compilación.

Tenga en cuenta que no hay más subpaquetes para excepciones - la única excepción que necesita capturar para tratar los errores de la API es com.vonage.client.video.VideoResponseException.

Cambios en la autenticación

La autenticación tanto en OpenTok como en Vonage Java Server SDK se maneja por ti, por lo que solo tienes que proporcionar las credenciales de tu Account una vez durante la inicialización. La diferencia es que OpenTok requiere la clave y el secreto de la API, mientras que para la Video API en el SDK Java de Vonage, debes proporcionar un ID de aplicación y su clave privada. Si bien tanto Vonage como OpenTok utilizan autenticación basada en tokens, los tokens de Vonage son JWTs mientras que OpenTok utiliza un formato personalizado. Aunque puede proporcionar una clave de API y un secreto a la aplicación VonageClient al igual que con OpenTok, esto se utiliza para otras API de Vonage, no para Video. Por lo tanto, deberás crear o usar una aplicación existente.

Puede crear una aplicación desde la sección Panel de Vonage. Asegúrese de que su aplicación tiene activada la función de vídeo. Haga clic en "Editar" en una aplicación existente para ver sus capacidades y credenciales. Desde aquí, haz clic en "Generar clave pública y privada". Esto sólo debe hacerse una vez, ya que cada vez que lo hagas, las credenciales cambiarán y se romperá el par de claves existente. Al hacer clic, se descargará tu clave privada. Coloca este archivo en un lugar seguro para realizar pruebas. NO COMPARTA NI EXPONGA NUNCA SU CLAVE PRIVADA. La clave privada es la "contraseña" de su aplicación, por lo que debe ser tratada con cuidado. Se recomienda crear una variable de entorno que apunte a la ruta del archivo de la clave privada, de modo que pueda hacer referencia a ella cuando configure la aplicación VonageClientllamando a la variable algo como VONAGE_PRIVATE_KEY_PATH. Lo mismo debe hacerse con el ID de su aplicación (que puede encontrarse en el panel de control o en la URL al editarla).

Para más información sobre cómo crear una aplicación, consulte la Guía de introducción.

Utilización

Véase LÉAME del SDK de Java para obtener instrucciones de configuración.

En lugar de esto:

OpenTok videoClient = new OpenTok.Builder(apiKey, apiSecret).build();

Haz lo siguiente:

import com.vonage.client.video.*;
import com.vonage.client.VonageClient;

// Inside a constructor or method body:
VonageClient vonage = VonageClient.builder()
 .applicationId(VONAGE_APPLICATION_ID)
 .privateKeyPath(VONAGE_PRIVATE_KEY_PATH)
 .build();
VideoClient videoClient = vonage.getVideoClient();

Una vez que haya instanciado el VonageClientpuede utilizar la función Video API utilizando el VideoClientobtenido a partir del VonageClient (véase más arriba).

Los métodos de la API en VideoClient están documentados mediante Javadocs, y son más o menos análogos a los métodos que se encuentran en el directorio OpenTok clase.

Para obtener instrucciones de uso más detalladas, consulte el Guía en vídeo del SDK Java Sever.

Cambios de método

Hay algunos pequeños cambios que debes tener en cuenta al migrar a Vonage desde OpenTok. Muchos de ellos son sencillos y tu IDE te ayudará con el autocompletado, pero para mayor claridad, ten en cuenta lo siguiente:

  • projectId es ahora applicationId cuando proceda.
  • Utilización de una tipografía más fuerte cuando proceda (p. ej. UUID y URI en lugar de String).
  • playDTMF ha pasado a llamarse sendDtmf para todos los terminales DTMF aplicables.
  • OpenTok#disableForceMute(String) sustituido por VideoClient#muteSession(String, boolean, String...). Es necesario configurar el active parámetro booleano a false para conseguir el mismo efecto.
  • En MuteAllProperties y parámetro en OpenTok se ha sustituido por el uso de excludedStreamIds directamente en el parámetro del método de VideoClient#muteSession(String, boolean, Collection<String>) (o VideoClient#muteSession(String, boolean, String...) for convenience). Estos métodos sustituyen OpenTok#forceMuteAll(String, MuteAllProperties).
  • ArchiveProperties y BroadcastProperties - como se utilizaban en los parámetros de solicitud en OpenTok - se han sustituido por Archive y Broadcast respectivamente. Ambos utilizan el patrón constructor para la construcción.
    • Archive y Broadcast en Vonage también representan las respuestas de forma similar a sus homólogos de OpenTok.
    • Así, los objetos de solicitud y respuesta que representan Archive y Broadcast se han unificado en la implementación de Vonage.
  • OpenTok#setBroadcastLayout(String, BroadcastProperties) sustituido por VideoClient#updateBroadcastLayout(String, StreamCompositionLayout).
  • OpenTok#setArchiveLayout(String, ArchiveProperties) sustituido por VideoClient#updateArchiveLayout(String, StreamCompositionLayout).
  • OpenTok#dial(String, String, SipProperties) sustituido por VideoClient#sipDial(SipDialRequest).
    • Sip sustituido por SipResponse.
  • En listArchives con varios parámetros en OpenTok han sido sustituidos por VideoClient#listArchives(ListStreamCompositionsRequest) para controlar las opciones.
    • La respuesta es un simple List<Archive> en lugar de ArchiveList. Utilice Collection#size() en lugar de ArchiveList#getTotalCount() para obtener el número de elementos.
  • OpenTok#setStreamLayouts(String, StreamListProperties) sustituido por VideoClient#setStreamLayout(String, List<SessionStream>) (o VideoClient#setStreamLayout(String, SessionStream...) por comodidad).
  • OpenTok#signal(String, String, SignalProperties) y OpenTok#signal(String, SignalProperties) sustituido por VideoClient#signal(String, String, SignalRequest) y VideoClient#signalAll(String, SignalRequest)respectivamente.
  • La estructura de fichas obtenida utilizó el generateToken métodos en OpenTok y VideoClient son diferentes. Vonage utiliza JWT, mientras que OpenTok utiliza una solución personalizada.
  • OpenTok#startCaptions(String, String, CaptionProperties) sustituido por VideoClient#startCaptions(CaptionsRequest).
    • CaptionProperties sustituido porCaptionsRequest.
    • Caption sustituido por CaptionsResponse.
      • CaptionsRequest utiliza un enum para languageCode en lugar de una cadena normal.
      • En token y sessionId siguen siendo necesarios y se establecen en el CaptionsRequest.Builder objeto.
  • OpenTok#connectAudioStream(String, String, AudioConnectorProperties) sustituido por VideoClient#connectToWebsocket(ConnectRequest).
    • AudioConnectorProperties sustituido por ConnectRequest.
    • AudioConnector sustituido por ConnectResponse.
  • OpenTok#startRender(String, String, RenderProperties) sustituido por VideoClient#startRender(RenderRequest).
    • RenderProperties sustituido por RenderRequest.
      • name en el parámetro interno Properties en el nivel superior RenderRequest.Builder.
    • Render sustituido por RenderResponse.
      • resolution es ahora un enum en lugar de una cadena normal.
  • OpenTok#listRenders(Integer, Integer) sustituido por VideoClient#listRenders(ListStreamCompositionsRequest).
    • Funciona de forma similar a la actualización listBroadcasts y listArchives (véase más arriba).

Recomendaciones para las pruebas

Para que la transición sea fluida, tanto durante como después de la migración, es esencial realizar pruebas exhaustivas. Esto incluye no sólo las pruebas unitarias, sino también las de integración y regresión. También merece la pena probar manualmente el flujo de la aplicación al menos una vez antes y después de la migración para asegurarse de que las pruebas automatizadas hacen lo que usted cree que hacen, o para detectar cualquier problema que las pruebas no hayan detectado. Incluso puede plantearse crear pruebas de equivalencia. La idea es crear un conjunto que afirme que las versiones de OpenTok y Vonage Video de tu aplicación hacen lo mismo. Estas pruebas pueden descartarse una vez finalizada la transición y eliminada la versión de OpenTok de tu aplicación.

Solución de problemas y asistencia

Vonage Java Server SDK se esfuerza por proporcionar mensajes de excepción útiles en los rastros de pila en caso de que encuentres errores en tiempo de ejecución. Examínalos detenidamente para determinar la causa.

Canales de apoyo

Para obtener ayuda general y debatir sobre la transición a Vonage Video, consulta la sección Canal #video-api en nuestra comunidad Slackdonde podrás obtener respuestas del personal de Vonage y de otros usuarios. También puedes ponerte en contacto con nosotros en X @VonageDev. El contacto principal para cualquier problema con la propia Video API es support@api.vonage.com. Si encuentra un error en el SDK, por favor Presentar un problema con los pasos para reproducir en GitHub.