API de análisis de consumo para reproductores de terceros (beta)

  • Actualizado el 24 de julio de 2024
  • Publicado el Jul 8, 2024
  • 4 minuto(s) de lectura
Anterior Siguiente

Integración de informes de análisis de consumo para reproductores móviles y web personalizados

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.

Los desarrolladores y publishers de terceros también pueden habilitar el análisis de consumo para un reproductor móvil o web personalizado usando la API de análisis de consumo.

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 la sesión haya finalizado y no sea posible realizar eventos adicionales para la sesión (por 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 puede reanudar 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 memoria o cola de eventos, de modo que incluso si la aplicación se cerró inesperadamente, los eventos se puedan 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 tardarán hasta 10 minutos en aparecer en el portal de Omny Studio. Nota: Las sesiones con un total de menos de 10 segundos de duración se filtran del análisis de consumo.

Asistencia técnica

Póngase en contacto con support@omnystudio.com si necesita ayuda.

---

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 Recomendado para aplicaciones móviles personalizadas
    ​SmartSpeaker  Recomendado para aplicaciones personalizadas de altavoces inteligentes
    ​CustomWeb  Recomendado para reproductores web personalizados
    ​Custom  Recomendado 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.
    ​sLos 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.