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.

Ámbito de aplicación

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á dirigida a ingenieros de software profesionales. Se da por supuesto que el lector cuenta, como mínimo, con un nivel básico de conocimientos de Java, de las herramientas habituales de desarrollo en Java, de los sistemas de compilación (Maven o Gradle) y de Git (u otro sistema de control de versiones). El lector debe sentirse cómodo leyendo y escribiendo código Java, gestionando las dependencias de un proyecto, así como implementando y ejecutando un proyecto Java. Una introducción al lenguaje Java, a la plataforma y a las herramientas asociadas queda fuera 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

• Documentación de vídeo de Vonage
• Especificación de la API de Video de Vonage
• Guía de uso en vídeo del SDK para servidores Java de Vonage
• Java Server SDK de Vonage Video API Javadocs
• Código fuente del vídeo del SDK para servidores Java de Vonage
• Vonage Java Server SDK repositorio de GitHub
• Artifactos del SDK para servidores Java de Vonage publicados en Maven Central

TokBox

• Referencia REST de la API de OpenTok
• Documentación del SDK de servidor Java de OpenTok
• Código fuente de OpenTok Java Server SDK
• OpenTok Java Server SDK GitHub repo
• Artifactos del SDK de servidor Java de OpenTok publicados en Maven Central

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 realizar cambios de forma gradual y frecuente sin afectar al proyecto existente. También puedes utilizar las pruebas del proyecto existente como referencia para comprobar que todo funciona correctamente. Lo ideal es que solo fusionaras la rama de transición con la rama principal una vez que hayas completado la conversión.

Cambios y consideraciones clave

Nuevas funciones y normas

La Video API de Vonage ofrece las mismas funcionalidades que OpenTok, y el SDK de Java se mantiene de forma activa para que se ajuste a la especificación de la API. Una de las diferencias entre los SDK de Java de OpenTok y Vonage es que el SDK de Java utiliza un modelo de datos con tipado más estricto en lugar de simples cadenas de caracteres. Además, presenta una mayor coherencia con otras API del SDK y sigue convenciones que deberían facilitar el uso intuitivo del SDK. Otra diferencia clave es que las clases de solicitud y respuesta están unificadas. Por ejemplo, se utilizaría la Archive clase tanto para crear como para recuperar un archivo, mientras que en OpenTok se utilizaría ArchiveProperties por 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 controladas. Por lo tanto, ya no es necesario realizar un try {...} catch (InvalidArgumentException ex), lo que te permite simplificar tu código. Si deseas detectar excepciones en las llamadas a la API que no se hayan realizado correctamente (es decir, aquellas con un código de estado distinto de 2xx), puedes detectar VideoResponseException en lugar de OpenTokException.

Actualización de dependencias

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 añadido el SDK de Java de Vonage a tu ruta de clases mediante tu herramienta de compilación, ya podrás empezar a utilizarlo en tu código.

Puedes sustituir las importaciones de la com.opentok y com.opentok.exception paquetes con com.vonage.client.video. Una búsqueda y sustitución en tu proyecto mediante tu IDE o editor de código debería ser de gran ayuda para 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 JWT 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.

Puedes crear una aplicación desde el 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, en definitiva, la «contraseña» de tu aplicación, por lo que debes manejarla con cuidado. Se recomienda crear una variable de entorno que apunte a la ruta del archivo de tu clave privada, para que puedas hacer referencia a ella al configurar el VonageClient, llamando a la variable algo así como VONAGE_PRIVATE_KEY_PATH. Haz lo mismo con el ID de tu aplicación (que puedes encontrar 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.

Uso

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 hayas creado una instancia del VonageClient, puedes utilizar el Video API utilizando el VideoClient, según se desprende de la 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 OpenTok clase.

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

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 compatibles.
• OpenTok#disableForceMute(String) sustituido por VideoClient#muteSession(String, boolean, String...). Es necesario configurar el active parámetro booleano para false para conseguir el mismo efecto.
• El MuteAllProperties clase y parámetro en OpenTok se ha sustituido por el uso del 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 - tal y como se utilizan en los parámetros de solicitud en OpenTok - han sido sustituidos 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.
• El listArchives Los métodos con diversos 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 simple.
    • El 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 parámetro en el interior Properties La clase se define 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.

Resolución de problemas y asistencia técnica

El SDK para servidores Java de Vonage tiene como objetivo proporcionar mensajes de excepción útiles en los trazos de pila en caso de que se produzcan errores en tiempo de ejecución. Examina estos mensajes detenidamente para determinar la causa.

Canales de asistencia

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