Manual del SDK

Manual básico de API de Triton Digital

Introducción

Este documento describe la información esencial necesaria para integrar correctamente los servicios de streaming de Triton Digital en un contexto en el cual el publisher desee la integración en el nivel del protocolo/la API y NO usar el kit de desarrollo de software (SDK). El objetivo es ayudar al publisher a integrarse a los servicios de streaming de Triton Digital directamente, sin usar el SDK de Triton. Si lo que desea es la implementación del SDK, comuníquese con Triton Digital para obtener los documentos indicados.

Este texto instructivo básico de API asume que usted ya está familiarizado con ciertos conceptos que se consideran de conocimiento general entre los desarrolladores de aplicaciones móviles para Web, Android e iOS, tales como, entre otras:

• Cómo usar Xcode para desarrollo de Apple.
• Cómo usar e integrar https://google.github.io/ExoPlayer/ en su código de Android.
• Comprender cómo crear secuencias de URL (codificación de URL, codificación Base64, parámetros de URL de paso y solicitudes GET/POST).
• Cómo usar Web Sockets.
• Conocimientos generales sobre trabajar con marcas de tiempo Epoch y cómo convertirlos en un formato legible para los humanos.
• Conocimientos generales sobre análisis, VAST e integración de códigos de publicidad.

Documentos de referencia

Este documento proporciona informaciòn de alto nivel y hace referencia a una gran cantidad de otros documentos para usuarios de Triton Digital donde puede encontrar un mayor nivel de detalle. 

Los documentos de referencia incluyen:

• Especificación de streaming de Triton Digital
• Especificación on demand de Triton Digital
• Especificación técnica de publicidad de Triton Digital
• Kit de desarrollo de software móvil de Triton Digital (Android)
• Kit de desarrollo de software móvil de Triton Digital (iOS)

Funcionalidad esencial

A grandes rasgos, la funcionalidad esencial es conectarse al(los) montaje(s) correcto(s) en la red de streaming en vivo de Triton Digital con un URL que garantice el cumplimiento con algunas reglas básicas de conexión, stream en vivo y medición. Además, su reproductor o aplicación puede conectarse para recibir la activación de publicidad on demand (en general, anuncios antes de los podcasts). Esta función de anuncios on demand es opcional, ya que la mayoría de los clientes prefieren que los anuncios sean insertados por los servidores de streaming y no administrados por el reproductor o las aplicaciones.

Streaming en vivo:

• Conéctese al stream y reproduzca el audio del stream.
• Garantice el cumplimiento (evite reproducción doble, evite el botón "pause", backoff para conectividad).
• Lea los metadatos del stream y reaccione a eventos tales como cortes comerciales e inserciones de anuncios.
• Muestre y reporte cualquier evento relativo a VAST/DAAST.
• Establezca métodos de conexión y cree la lista de parámetros (para parámetros que el reproductor pasa al Servicio de streaming de Triton Digital).
• Asegúrese de tener un parámetro de HTTP "UserAgent" apropiadamente formado. Se usa mucho para fines de análisis y medición.
• Proporcione cierto nivel de inteligencia de conectividad (por ej.: conéctese al tipo de stream correcto que admite el dispositivo solicitante).

Vea a continuación los detalles sobre la funcionalidad esencial de la transmisión en vivo.

On demand:

• Llame a un extremo on demand para recibir anuncios VAST/DAAST.
• Muestre y reporte cualquier evento relativo a VAST/DAAST.
• Conéctese al archivo y reprodúzcalo.
• Ofrezca una interfaz de usuario para permitir la "búsqueda" en el archivo cuando esa opción es posible.

Streaming en vivo

Esta sección proporciona más detalles sobre la funcionalidad esencial del streaming en vivo.

Conexión y reproducción

Hay dos métodos ligeramente diferentes para conectarse a un stream en la red de streaming de Triton Digital. Hay puntos de entrada URL para diferentes escenarios y usos de conectividad, entre ellos:

• Redirector de stream en vivo
• XML de aprovisionamiento

Estos puntos de entrada se explican con más detalle a continuación.

Redirector de stream en vivo

Para simplificar, esta es la manera recomendada de conectarse a los streams de Triton Digital. Este extremo siempre retornará como una redirección URL, por lo que no necesita tener muchos conocimientos sobre el XML de aprovisionamiento de Triton Digital para que funcione.

Los detalles de cómo crear la URL para conectarse a su transmisión en vivo se pueden encontrar en la sección Especificación de transmisión en redireccionamiento de transmisión en vivo.

Por ejemplo, si su estación es KSAD usando un montaje AAC ("KSADAAC") en el stream HLS, su URL sería:

http://playerservices.streamtheworld.com/api/livestream-redirect/KSADAAC.m3u8 

Los reintentos deben hacerse adecuadamente. Si un servidor de streaming no funciona, puede hacer un reintento en el mismo URL mediante un mecanismo de retardo. El servicio de redireccionamiento del reproductor elegirá al azar uno de los numerosos servidores de diferentes centros de datos para cada solicitud.

Consulte también la sección Especificación de streaming de Triton Digital sobre Gestión de conexión para obtener más información sobre cómo manejar la reconexión.

Para obtener más información sobre HLS, consulte la sección Especificación de streaming sobre HLS.

XML de aprovisionamiento

El XML de aprovisionamiento le ofrece un máximo control, ya que hace un amplio uso de los componentes personalizados del kit de desarrollo de software de Triton Digital, pero también requiere mayor esfuerzo en cuanto a comprender los componentes y usarlos de manera correcta.  Sin embargo, si simplemente desea conectarse a un stream mediante HTTP Live Streaming (HLS), le recomendamos que utilice el método Live Streaming Redirector (ver más abajo).

El XML URL de aprovisionamiento contiene todo lo "que se sabe" sobre la estación a la que se conecta. Si sigue la lógica del aprovisionamiento, siempre puede encontrar un punto de entrada URL en todos los formatos posibles y disponibles para la estación. Su código puede desplazarse a través de ellos o ser específico para el método de conexión apropiado. También regresa a todos los servidores que tienen el punto de conexión disponible.

Este método es usado principalmente en casos donde necesita control total de la conexión. Por ejemplo, una base de código individual creada en Xamarin o JAVA; la lógica de qué y dónde conectar es controlada por las bibliotecas de descubrimientos de la plataforma de Xamarin o Java.

Para obtener los mejores resultados y el mecanismo de conmutación por error, siga la información de Gestión de conexión en la Especificación de streaming de Triton Digital.

Garantice el cumplimiento

Cree su reproductor de manera que cumpla con los requisitos de Triton Metrics:

• No permita dos o más conexiones simultáneas (es decir, "reproducción doble").
• No permita la "pausa" en la transmisión en vivo. Utilice solo Stop y Start. Puede incluir un botón "Silenciar", pero debe funcionar igual que Detener, en realidad detener el stream, y esto debería quedar claro para el oyente. Desde el punto de vista de las mediciones, los botones Mute y Stop son lo mismo.  
• Utilice un esquema de "retroceso/reintento" al conectarse, para evitar que los servidores de Triton Digital tengan demasiadas solicitudes de conexión. Para obtener más información, consulte la sección Especificación de streaming de Triton Digital sobre Gestión de conexión y la sección sobre HTTP Live Streaming.

Metadatos 

Puede usar Shoutcast para los metadatos, pero no se usa ampliamente. Una mejor opción son los metadatos de banda lateral (SBM). Esta es una conexión secundaria que proporciona diferentes eventos en paralelo con la transmisión, como la lista de pistas para la visualización de "reproducción en curso" y eventos publicitarios para la inserción de anuncios. Asegúrese de que su reproductor tenga un gestor que sepa cómo interpretar estos eventos.

Algunas notas:

• Un evento de anuncio puede contener un enlace a un URL VAST, el cual puede incluir parámetros de anuncio, como banners, etc.
• La marca de tiempo de los metadatos en el stream en vivo representa milisegundos desde que se inició el stream. Los datos de banda lateral suelen ser unos milisegundos más tarde. Debe echar a andar un cronómetro en la aplicación que rastree el tiempo transcurrido desde la conexión. Los eventos en metadatos contendrán marcas de tiempo que indiquen cuándo el reproductor debería reaccionar al evento. Es importante ser preciso en el caso de eventos que implican inserción de anuncios. Si no va a hacer una inserción de anuncios, entonces no es necesario que el tiempo sea tan preciso.
• Cree su propio analizador VAST o use uno que esté disponible en línea, tal como el kit de desarrollo de software IMA de Google.
• Asegúrese de respetar los principios de VAST. Por ejemplo, asegúrese de reportar cada impresión, y de accionar cada URL.
• No sea innecesariamente estricto con el analizador VAST. Por ejemplo, no rechace archivos VAST que tienen una versión diferente a la de su analizador; debería reproducir VAST 2.0 o VAST 4.0 incluso si su analizador es versión 3.0.
• Para obtener más información, consulte la sección Especificación de streaming de Triton Digital sobre metadatos de banda lateral.

Cree su URL (lista de parámetros)

La sección Especificación de streaming en URL de stream describe la estructura de la URL y los parámetros que puede incorporar en ella. Los parámetros de búsqueda disponibles se enumeran aquí.

Los parámetros más importantes que debería pasar con el URL son:

• LSID.
• SBMID, el cual se usa para correlacionar el stream con sus metadatos asociados.
• Cualquier atributo de direccionamiento. Le recomendamos que los cree previamente en la medida de lo posible antes de conectarse al stream.
• Cualquier atributo de ubicación.

Recuerde que mientras más parámetros use, más valiosas podrán ser sus impresiones.

Agente usuario

Como agente usuario del reproductor web se usará automáticamente el proporcionado por el navegador, que no puede modificarse. Sin embargo, los desarrolladores pueden tener control sobre el agente usuario de su aplicación.  Cree el agente usuario de su reproductor de manera inteligente para que los analistas de Triton puedan detectar su aplicación o dispositivos correctamente y darles un nombre. Si necesita orientación al respecto, hable con un especialista en soluciones digitales de Triton.

Inteligencia de conectividad

Connection Management se explica en la Especificación de streaming, aquí.

El diagrama de ese documento es aplicable principalmente al método XML de aprovisionamiento. Es más simple para el método Live Stream Redirector.

Algunas notas:

• Esté preparado para las desconexiones y sepa qué hacer cuando ocurra alguna.
• Use las técnicas correctas para conexiones y desconexiones.
• Con ayuda de un buffer, su aplicación/reproductor puede administrar las conexiones de manera que el oyente no tenga prácticamente ningún inconveniente.