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

  • Mis à jour le 24 juil. 2024
  • Publié le 8 juil. 2024
  • 4 procès-verbal (procès-verbaux) lu(s)
Précédent Suivant

Intégration des rapports d'analyse de la consultation pour les lecteurs Web et mobiles personnalisés

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é.

Les développeurs et éditeurs tiers peuvent également activer cette fonction pour un lecteur web ou mobile personnalisé à l'aide de l'API correspondante.

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 évacués ou envoyés au serveur que lorsque la session est terminée et qu'aucun autre événement n'est possible pour la session (par exemple, lorsque l'auditeur a terminé la lecture du clip, a changé d'épisode ou a fermé l'application, mais pas lorsqu'il vient de suspendre la lecture, car il peut reprendre la session à tout moment).

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 préconisons un stockage local prolongé pour enregistrer les événements en mémoire ou en file d'attente, de sorte que même si l'application a été fermée de manière inattendue, les événements peuvent être conservés ou effacés à la prochaine occasion.

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

Lors de la transmission des sessions terminées, il faut compter jusqu'à 10 minutes pour que les résultats apparaissent sur le portail d'Omny Studio. Notez que les sessions d'une durée totale inférieure à 10 secondes sont exclues de l'analyse de la consommation.

Assistance

Veuillez écrire à support@omnystudio.com si vous avez besoin d'aide.

---

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 Recommandée pour les applications mobiles personnalisées
    ​SmartSpeaker  Recommandée pour les applications d’enceintes connectées personnalisées
    ​CustomWeb  Recommandée pour les lecteurs Web personnalisés
    ​Custom  Recommandée 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 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 du modèle

TrackConsumptionEvent

Il s'agit d'un objet d'événement relatif à l'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.