API de análisis de consumo para reproductores de terceros

Los desarrolladores y editores de terceros pueden habilitar el análisis de consumo para un reproductor móvil o web personalizado mediante la API de análisis de consumo.

La API de análisis de consumo de Omny Studio es una función beta

El análisis de consumo de Omny Studio permite a los editores ver una visualización de cómo sus oyentes consumen e interactúan con su contenido de audio. De forma predeterminada, el análisis de consumo está disponible en reproducciones mediante el reproductor incrustable y el reproductor web de Omny.fm.

Al usar la API de análisis de consumo, el reproductor envía eventos de reproducción que se analizan, filtran y procesan mediante nuestros servicios de análisis para generar informes de análisis de consumo conjuntos.

Nuestros servicios de análisis analizan, filtran y procesan los datos de eventos sin procesar para generar informes analíticos de consumo agregados.

Implementación del cliente

Durante la reproducción de un clip, el reproductor debe emitir los siguientes eventos a la memoria/cola local.

Los eventos solo deben vaciarse/enviarse al servidor cuando se completa la sesión y no es posible realizar eventos adicionales para la sesión. Ejemplo: el oyente finalizó la reproducción del clip, cambió los episodios o cerró la aplicación, pero no cuando el usuario acaba de pausar la reproducción porque es posible que reanude la sesión en el futuro.

Para los navegadores, recomendamos usar Navigator.sendBeacon() para enviar eventos al descargar la página. Para las aplicaciones, recomendamos un almacenamiento local persistente para almacenar la cola de eventos, de modo que incluso si la aplicación se cerró inesperadamente, los eventos se pueden conservar y vaciar en la próxima oportunidad disponible.

Procesamiento por lotes (opcional)

Para reducir el uso de la red en el extremo de la API, puede enviar opcionalmente varias sesiones completadas en una solicitud de API, siempre y cuando cada SessionId está garantizado para ser único.

Ensayo

Al enviar las sesiones completadas, los resultados tardan hasta 10 minutos en aparecer en el portal de Omny Studio. Las sesiones con un total de menos de 10 segundos de duración se filtran del análisis de consumo.

Enviar datos de consumo

Envíe datos de eventos de análisis de consumo a Omny Studio.

Solicitud

POST https://traffic.omny.fm/api/consumption/events?organizationId={organizationId}

Parámetros:

OrganizationId El GUID de la organización Omny Studio

Encabezados:

Content-Type debe ser application/json

Cuerpo (JSON):

Source (cadena) La fuente de donde se registró esta información de consumo. Esto permite separar diferentes consumos de diferentes tipos de fuentes o aplicaciones en la interfaz de usuario. Los siguientes orígenes están disponibles para implementaciones personalizadas:
- MobileApp para aplicaciones móviles personalizadas
- SmartSpeaker Para aplicaciones personalizadas de altavoces inteligentes
- CustomWeb para reproductores web personalizados
- Custom para todas las demás aplicaciones personalizadas
- De forma predeterminada, el reproductor incrustado de Omny y Omny.fm sitio web utiliza el Web source
Events (TrackConsumptionEvent[]) Una serie de eventos de consumo que se están enviando. Debe tener al menos un evento incluido. Consulte TrackConsumptionEvent modelo a continuación.
Completed (booleano) Si la sesión ha finalizado. Debe ser true

Ejemplo de cURL

curl -X POST \
  'https://traffic.omny.fm/api/consumption/events?organizationId=126281f8-200e-4c9f-8378-a4870055423b' \
  -H 'Content-Type: application/json' \
  -d '{
    "Source": "Web",
    "Events": [
        {
            "OrganizationId": "126281f8-200e-4c9f-8378-a4870055423b",
            "ClipId": "9b5c82f7-74cf-4841-a870-a670017cc8eb",
            "SessionId": "a039f83d-1916-436b-a090-efbc08698506",
            "Type": "Start",
            "Position": 0,
            "SeqNumber": 1,
            "Timestamp": 1540270724
        },
        {
            "OrganizationId": "126281f8-200e-4c9f-8378-a4870055423b",
            "ClipId": "9b5c82f7-74cf-4841-a870-a670017cc8eb",
            "SessionId": "a039f83d-1916-436b-a090-efbc08698506",
            "Type": "Stop",
            "Position": 4.554,
            "SeqNumber": 2,
            "Timestamp": 1540270728
        },
        {
            "OrganizationId": "126281f8-200e-4c9f-8378-a4870055423b",
            "ClipId": "9b5c82f7-74cf-4841-a870-a670017cc8eb",
            "SessionId": "a039f83d-1916-436b-a090-efbc08698506",
            "Type": "Start",
            "Position": 308.053,
            "SeqNumber": 3,
            "Timestamp": 1540270728
        },
        {
            "OrganizationId": "126281f8-200e-4c9f-8378-a4870055423b",
            "ClipId": "9b5c82f7-74cf-4841-a870-a670017cc8eb",
            "SessionId": "a039f83d-1916-436b-a090-efbc08698506",
            "Type": "Stop",
            "Position": 542.643,
            "SeqNumber": 4,
            "Timestamp": 1540270962
        }
    ],
    "Completed": true
}'

Respuesta

Modelo

Enabled (booleano) Si el servicio Análisis de consumo está habilitado o no. Si la respuesta es falsa, el cliente debe dejar de intentar enviar eventos para la sesión de la página web/aplicación móvil.

Ejemplo:

{
    "Enabled": true
}

Esquema del modelo TrackConsumptionEvent

Un objeto de evento de análisis de consumo:

OrganizationId (cadena) El GUID de la organización del clip
ClipId (cadena) El GUID del clip
SessionId (cadena) ID único globalmente generado por el cliente (GUID/UUID) que identifica la misma sesión de escucha para un clip individual.
Una sesión se considera una sola reproducción continua. El cambio de clips se considera una sesión nueva (por ejemplo, cambiar entre los clips A, B, A en una lista de reproducción debería generar 3 sesiones únicas). El SessionId no debe reutilizarse para otras sesiones.
Type (cadena) El tipo de evento emitido. Los tipos válidos son:
- Start La reproducción ha comenzado en la posición actual
- Stop La reproducción se ha detenido en la posición actual
Position (número) Tiempo de la posición de escucha en fracciones de segundo, como 1,5, que representa 1,500 milisegundos a lo largo de la línea de tiempo de audio.
SeqNumber (número) Un número de secuencia a partir de 1 que debe incrementarse para cada nuevo evento en la sesión. Esto se usa para resolver problemas de condición de carrera con eventos generados mediante programación que ocurren muy rápidamente uno tras otro y que pueden tener la misma marca de tiempo.
Timestamp (número) Una marca de tiempo unix (en segundos) que representa el momento en que se emitió este evento. P. ej.. 1502072310 Es importante que la marca de tiempo refleje el tiempo de emisión del evento real, y no cuando el evento se está vaciando en la API.