Yield Analytics API

Vue d’ensemble

L’API et les services Yield Analytics sont exposés via une interface REST. Il est destiné à faciliter le développement de fonctionnalités personnalisées aux développeurs expérimentés avec les plateformes de développement web 2.0, AJAX, REST et orientées service. Les développeurs doivent être familiarisés avec les paradigmes d’application web, notamment AJAX, XML, JSON et le protocole HTTP(S) avant de tenter de développer avec l’API et les services Yield Analytics.

Types de contenu

L’API REST Yield Analytics est actuellement accessible via deux types de contenu MIME de réponse :

XML - utilisation de Content-type: application/xml
JSON - utilisation de Content-type: application/json

La sélection du type de contenu souhaité est un choix que le développeur d’API doit faire au cas par cas. La fonctionnalité d’API est symétrique entre les types de contenu. Les développeurs d’API peuvent spécifier le type de contenu souhaité dans les paramètres de la méthode HTTP GET ou POST ou via leur bibliothèque de client AJAX ou HTTP.

Vérification des erreurs et codes status

Les développeurs d’API doivent case activée les codes de réponse HTTP retournés par l’API REST du service pour détecter les erreurs propagées à partir des appels d’API. Les appels réussis au service entraînent l’utilisation de 200 codes de réponse de plage. Les réponses HTTP de plage 400 et 500 indiquent des erreurs. Les codes de réponse et le texte spécifiques seront probablement modifiés pendant le développement BÊTA de l’API, mais pas les plages.

Sécurité

L’API de service expose les données d’application de manière sécurisée. L’utilisation des fonctionnalités d’API est limitée aux utilisateurs authentifiés et est exposée via des protocoles de transport sécurisés. L’accès à l’API doit avoir lieu dans le contexte suivant :

Exemple d’authentification cURL

L’authentification se produit en transmettant des informations d’identification via des en-têtes HTTP sur chaque requête.
```
- username: curl -H "username:username"
- password: curl -H "password:password"
- source: curl -H "source:client_id"        
```

Exemple d’authentification HTTPS

GET /api/v1/rest/
HTTPS/1.1
Host: yieldanalytics.xandr.com
Accept: application/xml, application/json
Content-Type: application/json
username: {{username}}
password: {{password}}
source: {{client_id}}

Exemple d’authentification POSTMAN

Recherchez un exemple de paramètres d’en-tête dans Postman ci-dessous :
Remarque
- 'Authorization' est défini sur « No Auth » ; Les paramètres ci-dessous doivent être placés sous l’onglet « En-têtes ».
- Pour obtenir un didacticiel plus approfondi sur l’utilisation de Postman, consultez Utilisation de Postman avec l’API Yield Analytics.

Confidentialité

La confidentialité est maintenue à l’aide de la communication basée sur la couche de sockets sécurisés pour interagir avec l’API Yield Analytics. Les développeurs d’API doivent préférer l’utilisation du protocole HTTPS à la communication http non sécurisée dans la mesure du possible. Consultez votre bibliothèque cliente HTTP pour savoir comment activer HTTP sur SSL lors du développement en dehors d’un contexte de navigateur web.

Services d’API

Filtrage des données

Fonctions d’alias

Filtrage de la consommation

Pour tous les appels d’API qui acceptent un filtre consommation en tant que variable de chemin ou objet de requête, le calcul de disponibilité peut être contrôlé davantage. Disponibilité = Capacité - Consommation. L’ajout d’un filtre de consommation à une demande de disponibilité contrôle la consommation qui est soustraite de la capacité pour donner la disponibilité. Toutes les lignes de commande qui correspondent à un filtre de consommation verront leur consommation soustraite de la capacité lors du calcul de la disponibilité.

Lorsque plusieurs paires clé-valeur sont fournies avec la même clé et un opérateur = (EQUAL) comme dans CONSUMPTION_TYPE ci-dessus, les valeurs sont combinées à l’aide d’une règle OR. Par exemple, CONSUMPTION_TYPE peut être DIRECT ou CONTAINED
Lorsque plusieurs paires clé-valeur sont fournies avec la même clé et un opérateur != (NOT_EQUAL) (par exemple, EXTERNAL_ID !=223415 ; EXTERNAL_ID !=223416), les valeurs sont combinées à l’aide d’une règle AND.
Lorsque plusieurs paires clé-valeur sont fournies avec des opérateurs différents (par exemple, PRIORITY>=5 ; PRIORITY<=10), les valeurs sont combinées à l’aide d’une règle AND.
Les paires avec différentes clés de fonction sont combinées à l’aide d’une règle AND.

Pour afficher toutes les valeurs de clé de fonction disponibles pour une installation Analytics donnée (elles peuvent différer selon le client), vous pouvez envoyer une requête REST au moteur de requête et retourner une liste de toutes les clés de fonction. Voici le format de la requête REST pour répertorier les clés de fonction :

Modèle de données

Diagramme du modèle objet Yield Analytics.

Objets clés

Commande

Une commande est un conteneur d’éléments de ligne qui a été créée dans un système de gestion des commandes (OMS) ou directement dans le serveur publicitaire, puis est introduite dans Yield Analytics chaque nuit pendant l’étape d’importation de la commande pendant le traitement. Une commande dans la partie garantie directe de l’industrie de la publicité en ligne fait référence à un ordre d’insertion mutuellement convenu qui intègre des conditions spécifiques, en vertu desquelles les éditeurs livreront des annonces (lignes de commande) sur les sites au profit de l’agence ou de l’annonceur.

Lorsque vous faites référence à une commande dans Yield Analytics, elle fait référence au nom de la commande associée à une ligne de commande ou à un groupe de lignes de commande.

Article de ligne de commande

Une ligne de commande est une annonce ou un placement qui a un ensemble spécifique de dates de vol et un créatif qui lui est associé et qui est acheté dans le cadre d’un ordre d’insertion. Parfois appelées articles de ligne également, ces lignes de commande sont associées à des métadonnées qui permettent de décrire les accords contractuels de livraison tels que le CPM (taux) ainsi que les accords de diffusion publicitaire tels que le ciblage et la quantité d’impressions planifiées.

Produit

Considérez un produit comme la chose qu’un éditeur vendrait réellement aux annonceurs. Chaque produit a un nom unique et peut être considéré comme un pointeur vers une cible. Mais attention ! Il y a une tendance à confondre les produits et le ciblage. Il s’agit d’un nom incorrect, car plusieurs produits peuvent être associés à une cible. En plus d’être associés à des cibles, les produits ont des métadonnées supplémentaires qui leur sont attachées, telles que le nom et éventuellement le taux et le groupe de produits. Je le répète : les cibles sont uniques ; de nombreux produits peuvent être associés à une seule cible.

Les produits peuvent être désactivés par les clients, mais pas supprimés. Si aucun produit actif n’est associé à une cible, Yield Analytics ne traite pas la cible, mais conserve son historique.

Il existe quatre types de produits dans Yield Analytics :

Carte de taux : représente les produits du catalogue à partir duquel l’équipe de vente de l’éditeur vend
Rapports : tout inventaire que vous souhaitez analyser dans Yield Analytics. Il s’agit du type de produit le plus important, car il s’agit de la classe de produit sur laquelle le client a le plus de contrôle et de ceux qui sont utilisés pour accumuler des données historiques. Ce dernier élément, qui constitue la base des données historiques, est souvent l’un des concepts les plus difficiles à comprendre pour les clients lors de l’implémentation, car il les oblige à réfléchir à tous les produits sur lesquels ils devront éventuellement collecter des données. Les prévisions peuvent être effectuées sans créer de rapports sur les produits, mais pas les rapports historiques (comme vous pouvez vous y attendre).
Personnalisé : produits qui correspondent aux lignes de commande. Chaque fois que Yield Analytics importe des lignes de commande, elle crée des produits de ligne de commande personnalisés qui existent uniquement pendant la durée de vie de la ligne de commande. Ces produits sont entièrement gérés par Yield Analytics (créés, gérés, inactivés). Souvent, lorsque les clients souhaitent créer un produit propre, ils essaient de supprimer des produits personnalisés et doivent être rééduqués par notre équipe de services.
Saisonnier : permet de définir l’inventaire influencé par un modèle saisonnier spécifique. Yield Analytics permet d’appliquer des modèles saisonniers à des zones d’inventaire lorsqu’il y a des fluctuations d’activité saisonnières connues dans le volume d’impression d’un éditeur (par exemple, un éditeur de sport comme ESPN peut voir un pic énorme une fois par an à la fin de janvier qui correspond au Superbowl.)

Target

Une cible représente un pool d’inventaire unique décrit par une combinaison de paires attribut-valeur, qui identifie de façon unique le pool d’inventaire. Cette combinaison unique et descriptive est ce que nous appelons une expression cible. Les cibles peuvent être définies à n’importe quel niveau de granularité ('sports', 'entertainment', '300x250', 'Chicago', etc.). « Sports » et « divertissement » correspondent probablement à une section du site web d’un éditeur ou à une étiquette utilisée pour catégoriser l’inventaire sur le back-end (pour les ventes publicitaires). « 300x250 » correspond à la taille d’une étiquette publicitaire. « Chicago » ferait probablement référence à l’adresse IP de l’utilisateur.

En utilisant les cibles ci-dessus, un exemple d’expression cible peut être :

adunit in ('sports')

Dans l’expression cible ci-dessus, « adunit » est l’attribut de ciblage et « sports » est la valeur de l’attribut.

Une expression cible plus complexe peut être :

adunit dans ('sports', 'entertainment') et taille dans ('300x250') ou placement dans ('business') et taille dans ('300x250','300x600','1x1') et pos in ('top')

Termes clés

Allocation

Processus par lequel Yield Analytics émule la logique du serveur publicitaire pour prévoir la façon dont chaque ligne de commande sera consommée par rapport à des produits individuels pour chaque jour de la plage de dates de prévision.

Ce processus tient compte de plusieurs lignes de commande en concurrence pour le même inventaire
Ce processus tient compte des chevauchements entre les produits. Une seule ligne de commande peut consommer sur plusieurs produits à la fois avec une seule impression. Selon la relation entre la cible de la ligne de commande et la cible du produit, le type de consommation de la ligne de commande par rapport au produit peut être Indirect, Direct ou Contenu (voir ci-dessous).

Processus d’allocation

Un jour donné, pour un niveau donné (ensemble de priorités), un ensemble de lignes d’ordre demande une partie de leurs impressions
La portion est définie par la version d’évaluation, l’objectif de ligne de commande (si l’objectif est basé sur l’objectif), la part de voix (pour les lignes CPD)
La quantité d’impressions est limitée par ce qui est disponible
La disponibilité diminue à mesure que nous travaillons sur les lignes de commande
La disponibilité diminue davantage par rapport à une cible, car la consommation est prise à partir de cibles qui se chevauchent
L’objectif de Yield Analytics est de conserver ces totaux et les relations entre eux (processus itératif)

Métriques à risque

Yield Analytics utilise les résultats d’allocation pour générer plusieurs métriques à risque qui peuvent aider les ops publicitaires à comprendre quelles lignes de commande garanties sont exposées à un risque de sous-livraison afin qu’elles puissent effectuer des interventions appropriées.

Mesures	Formule	Description
Rythme	Impressions consommées – Impressions planifiées	Mesure du risque d’une ligne de commande en cours de livraison ou de livraison supérieure. Cette métrique inclut à la fois la sous-livraison et la sur-livraison, et doit être utilisée pour mesurer les deux.
Rythme (durée de vie)	Impressions consommées – Impressions planifiées	Cela est identique à la métrique Rythme, sauf que cette métrique agrège sur la durée de vie de la ligne de commande et n’est pas liée par la période. Lorsque la métrique de durée de vie est utilisée, le filtre de période est utilisé uniquement pour filtrer les lignes de commande remises dans la période sélectionnée.
Pourcentage de consommation à planification	(Événements consommés / Événements planifiés) x 100	Mesure de rythme par planification. Pour les périodes futures, ce nombre prend en compte la consommation attendue en fonction des prévisions d’allocation. Les lignes de commande garanties avec les types tarifaires CPM, CPD et CPC sont soumises à ce calcul. C :S% est indépendant des événements, ce qui signifie que les impressions et les clics sont utilisés indifféremment, déterminés par le type de tarification de la ligne de commande.
% de consommation à planification (durée de vie)	(Événements consommés / Événements planifiés) x 100	Il s’agit de la même que la métrique Consommation-à-planification %, sauf que cette métrique agrège sur la durée de vie de toutes les lignes de commande et n’est pas liée par la période. Lorsque la métrique de durée de vie est utilisée, le filtre de période est utilisé uniquement pour filtrer les lignes de commande remises dans la période sélectionnée.
Chiffre d’affaires par rapport à l’objectif	Chiffre d’affaires gagné - Chiffre d’affaires sous contrat	Mesure du chiffre d’affaires qui risque de sous-être remis. Cette métrique inclut à la fois la sous-livraison et la sur-livraison, et doit être utilisée pour mesurer les deux.
Chiffre d’affaires par rapport à l’objectif (durée de vie)	Chiffre d’affaires gagné - Chiffre d’affaires sous contrat	Cela est identique à la métrique Chiffre d’affaires par rapport à l’objectif, sauf que cette métrique agrège sur la durée de vie de toutes les lignes de commande et n’est pas liée par la période. Lorsque la métrique de durée de vie est utilisée, le filtre de période est utilisé uniquement pour filtrer les lignes de commande remises dans la période sélectionnée.

Disponibilité

Capacité – Consommation (garantie)

La capacité d’un produit peut être entièrement consommée par un mélange de lignes de commande garanties et préeptibles. La consommation par lignes de commande préemptibles est considérée comme disponible.
L’objectif d’un éditeur est généralement de « vendre » la consommation préeptible avec des lignes de commande garanties (vente directe), car ces lignes ont généralement un taux plus élevé et ne mettent pas en danger d’autres demandes garanties.

Capacité

Nombre maximal d’impressions pouvant être livrées sur un produit donné.

Modèle de consommation

Nombre d’impressions qui ont été livrées dans le passé ou qui sont prévues pour être livrées dans l’avenir.

Type de consommation

C’est ainsi que Yield Analytics classe la façon dont une ligne de commande donnée consomme par rapport à un produit donné, et est une fonction de la relation entre la cible de la ligne de commande et la cible du produit.

Direct : La ligne de commande et le produit partagent la même cible
Contenu : la ligne de commande doit être remise dans le produit. La cible de la ligne de commande est un enfant de la cible du produit.
Indirect : la ligne de commande peut livrer à l’intérieur ou à l’extérieur du produit. La cible de la ligne de commande est un parent ou un frère de la cible du produit.

Méthode de mise en version d’évaluation

Indique la forme idéale de la distribution des impressions sur la plage de dates de la ligne de commande (également appelée rythme)

Les méthodes de version d’évaluation courantes sont les suivantes :

Uniformément
front loaded
aussi vite que possible

Classe d’inventaire

Attribut de chaque ligne de commande dans Yield Analytics, dérivé du type de contrat de la ligne de commande. Il existe trois valeurs de classe d’inventaire :

Inventory, classe	Description
Garanti	Les éditeurs ont fait une garantie aux annonceurs de fournir un volume spécifique d’impressions pour des lignes basées sur des objectifs ou une part spécifique de voix (SOV) pour les lignes de coût par jour. SOV fait référence à la proportion d’impressions consommées par une ligne de commande donnée d’un produit particulier. - Types de contrats APAS : Exclusif garanti, Standard garanti - Types de contrats DFP : Parrainage, Standard - Types de contrats OEA : Dynamique, Mensuel dynamique, Exclusif, Fixe, Ouvert
Préempte	Ces lignes de commande peuvent être préemptées par des lignes de commande garanties. - Types de contrats APAS : Impressions, Pourcentage - Types de contrats DFP : AdMob, AdSense, Advertising Exchange, Bulk, Click Tracking, House, Network, Price Priority - Types de contrats OEA : Maison et tout type de contrat qui inclut le mot « Préeptible »
Non spécifié.	Correspond aux impressions non renseignées et aux impressions livrées par des lignes de commande qui n’ont pas été importées dans Yield Analytics et sont donc « inconnues ».

Priorité

Détermine la ligne de commande qui sera la première à consommer la capacité (définie dans le serveur publicitaire).

C :S %

Mesure de rythme par planification. Pour les périodes futures, ce nombre prend en compte la consommation attendue en fonction des prévisions d’allocation. Les lignes de commande garanties avec les types tarifaires CPM, CPD et CPC sont soumises à ce calcul.

Rythme

Mesure du risque d’une ligne de commande en cours de livraison ou de livraison supérieure. Cette métrique inclut à la fois la livraison et la livraison en cours, et doit être utilisée pour mesurer les deux.

Attributs de tableau croisé dynamique

Le fait de faire pivoter les attributs permet d’associer des valeurs différentes pour le même attribut de ciblage dans une seule expression cible. Le ciblage de Yield Analytics ne vous permet pas d’utiliser la logique AND entre deux valeurs qui appartiennent au même attribut. C’est problématique, car il y a des cas où cela a du sens. Par exemple, mot clé ciblage dans lequel vous souhaitez cibler à la fois « basketball » et « baseball ». Par exemple, si l’expression souhaitée est la suivante :

kw dans ('basketball') et kw dans ('baseball')

Il ne sera pas autorisé et vous devrez utiliser le pivot. Le tableau croisé dynamique vous permet de cibler les deux dans une seule expression en créant un attribut avec l’attribut d’origine et la valeur concaténés ensemble. Par exemple :

kw_basketball dans (« true ») et kw_baseball dans (« true »)

Les attributs croisés dynamiques peuvent également être exclus. Par exemple, supposons que dans DFP, vous avez adunit 1, qui contient les éléments suivants en tant qu’enfants : adunit 2_a, adunit 2_b, adunit 2_c. Si vous souhaitez cibler tout sauf adunit 2_b, vous devez utiliser l’expression ci-dessous :

adunit dans ('adunit 1') et adunit exclude !in ('adunit 2_b')

DFP a également un attribut appelé adunit_only, qui vous permet de sélectionner uniquement l’adunit spécifié et non aucun de ses enfants. Toutefois, étant donné que ce n’est pas universel pour tous les serveurs publicitaires, nous pouvons utiliser la syntaxe dans l’expression ci-dessus.

Lignes de commande zombie

Une ligne de commande en status en attente avec une date de début dans le passé. La ligne de commande n’est pas remise en temps réel, mais Yield Analytics l’alloue à l’avenir, car elle est en status en attente. Les lignes de commande qui sont en attente et qui ont dépassé leur date de début sont appelées lignes de commande « zombie » car elles réservent des stocks dans Yield Analytics qu’elles ne consommeront jamais, en supposant que leur status n’est pas modifié.

Last updated on 2025-04-02

Partager via