API d’analyse de la consommation pour les lecteurs tiers (bêta)

Third-party developers and publishers integrate can enable consumption analytics for a custom web or mobile player using the consumption analytics API.

Les analyses de la consommation proposées par Omny Studio permettent aux éditeurs de visualiser les habitudes de consultation et d'interaction de leurs auditeurs avec leur contenu audio. Les rapports statistiques sur la consommation sont disponibles par défaut pour les lectures effectuées via le lecteur Web Omny.fm et le lecteur embarqué.

En utilisant l'API relative aux analyses de consommation, le lecteur transmet des événements de lecture instantanée qui sont examinés, filtrés et traités par nos services statistiques afin de générer des rapports globaux sur le sujet.

Les données brutes des événements sont analysées, triées et traduites par nos centres d'analyse qui produisent des tableaux et graphiques récapitulatifs de la consommation.

Client Implementation

Lors de la lecture d'un clip, le lecteur doit émettre les événements mentionnés ci-après dans la mémoire locale/la file d'attente.

Events must only be flushed/sent to the server when the session is complete and no additional events for the session are possible. Example: the listener ended playback of the clip, changed episodes, or closed the app, but not when the user has just paused playback because they may resume the session in the future.

Pour les navigateurs, nous recommandons d’utiliser Navigator.sendBeacon() pour envoyer des événements au moment de la fermeture de la page. For apps, we recommend a persisted local storage to store the events queue so even if the app was closed unexpectedly, the events can be persisted and flushed at the next available opportunity.

Traitement par lots (facultatif)

Pour réduire l'utilisation du réseau au niveau du terminal de l'API, vous pouvez éventuellement envoyer plusieurs sessions achevées en une seule demande d'API, à condition que l'unicité de chaque SessionId soit garantie.

Tests

Upon submitting completed sessions, it takes up to 10 minutes for the results to appear in the Omny Studio portal. Sessions totaling less than 10 seconds in duration are filtered from consumption analytics.

Send Consumption Data

Envoyez les données d'événements des analyses de consommation à Omny Studio.

Request (Demande)

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

Paramètres :

OrganizationId Le GUID de l’organisation d'Omny Studio

Headers:

Content-Type doit être application/json

Body (JSON):

Source (chaîne) La source où cette information de consommation a été enregistrée. Cela permet de séparer les différentes données de consommation provenant de différents types de sources ou d'applications dans l'interface utilisateur. Les sources suivantes sont disponibles pour les implémentations personnalisées :
- MobileApp for custom mobile apps
- SmartSpeaker for custom smart speaker apps
- CustomWeb for custom web players
- Custom for all other custom apps
- Le lecteur embarqué Omny et le site Omny.fm utilisent par défaut la source Web source
Events (TrackConsumptionEvent[]) Ensemble d’événements de consommation en cours de soumission. Doit contenir au moins un événement. Voir TrackConsumptionEvent model below.
Completed (booléen) Si la session est terminée. Doit être true

Exemple 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
}'

Response (Réponse)

Modèle

Enabled (booléen) Indique si le service d'analyse de la consommation est activé ou non. Si la réponse est « false », le client doit cesser de tenter de soumettre des événements pour la session de la page web ou de l'application mobile.

Exemple :

{
    "Enabled": true
}

TrackConsumptionEvent Model Schema

A consumption analytics event object:

OrganizationId (chaîne) Le GUID de l’organisation du clip
ClipId (chaîne) Le GUID du clip
SessionId (chaîne) ID unique généré côté client (GUID/UUID) qui désigne la même session d'écoute pour un clip individuel.
Une session est définie comme étant une lecture unique et continue. Tout changement de clip est considéré comme une nouvelle session (par exemple, le passage d'un clip A, à un clip B, à un clip A dans une liste de lecture devrait générer 3 sessions uniques). L'identifiant de session ne doit pas être réutilisé pour d'autres sessions.
Type (chaîne) Le type d’événement émis. Valid types are:
- Start La lecture a démarré à la position actuelle
- Stop La lecture s’est arrêtée à la position actuelle
Position (nombre) Temps de la position d’écoute en fractions de secondes, par exemple 1,5 qui représente 1 500 millisecondes sur la ligne de temps audio.
SeqNumber (nombre) Un numéro de séquence à partir de 1 qui doit être augmenté pour chaque nouvel événement dans la session. Cette valeur est utilisée pour résoudre les questions de concurrence avec les événements générés par le programme qui se succèdent très rapidement et peuvent avoir le même horodatage.
Timestamp (nombre) Horodatage Unix (en secondes) représentant le moment où cet événement a été émis. Par ex. 1502072310 Il est important que l'horodatage reflète l'heure réelle d'émission de l'événement, et non le moment où celui-ci est transmis à l'API.