API d’analyse de la consommation pour les lecteurs tiers

Les développeurs et éditeurs tiers intégrés peuvent activer l’analyse de la consommation pour un lecteur Web ou mobile personnalisé à l’aide de l’API d’analyse de la consommation.

L’API Omny Studio Consumption Analytics est une fonctionnalité bêta

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.

Mise en œuvre par le client

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.

Les événements ne doivent être vidés/envoyés au serveur que lorsque la session est terminée et qu’aucun événement supplémentaire pour la session n’est possible. Exemple : l’auditeur a mis fin à la lecture de l'émission, a changé d’épisode ou a fermé l’application, mais pas lorsque l’utilisateur a simplement mis la lecture en pause, car il pourrait reprendre la session ultérieurement.

Pour les navigateurs, nous recommandons d’utiliser Navigator.sendBeacon() pour envoyer des événements au moment de la fermeture de la page. Pour les applications, nous recommandons un stockage local persistant pour stocker la file d’attente des événements, de sorte que même si l’application a été fermée de manière inattendue, les événements peuvent être conservés et vidés à la prochaine occasion disponible.

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

Une fois les sessions terminées, il faut compter jusqu’à 10 minutes pour que les résultats apparaissent sur le portail Omny Studio. Les sessions d’une durée totale inférieure à 10 secondes sont filtrées à partir de l’analyse de consommation.

Envoyer des données de consommation

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

En-têtes :

Content-Type doit être application/json

Corps (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 pour les applications mobiles personnalisées
- SmartSpeaker pour les applications d’enceintes intelligentes personnalisées
- CustomWeb pour les lecteurs Web personnalisés
- Custom pour toutes les autres applications personnalisées
- 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 modèle ci-dessous.
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
}

Schéma de modèle TrackConsumptionEvent

Un objet d’événement d’analyse de la consommation :

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. Les types valides sont les suivants :
- 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.