Guide de configuration de l’API d’élément de ligne de transaction organisée

La configuration d’une implémentation d’API d’un élément de ligne de transaction organisé pour cibler une transaction nécessite la configuration d’un certain nombre de propriétés différentes sur différents objets d’API. Ce guide explique le processus de création et de configuration d’un élément de ligne de transaction organisé à l’aide de notre API.

Vue d’ensemble

Les transactions organisées représentent un accord négocié entre un acheteur et un curateur qui combine les actifs propriétaires d’un curateur avec l’offre de la Place de marché Xandr. Ces ressources propriétaires peuvent inclure des données d’audience, un accès privilégié aux stocks, des tarifs spécialement négociés, des talents d’optimisation, une stratégie d’investissement et d’autres fonctionnalités qui améliorent l’offre de transaction et créent une offre unique. Les curateurs de transactions ont leur propre siège de membre sur la plateforme Xandr, qu’ils utilisent pour empaqueter l’approvisionnement et leurs propres actifs dans des ID de transaction organisés pour les acheteurs. N’importe quel DSP intégré à l’échange Xandr peut acheter des offres organisées.

La configuration d’un élément de ligne de transaction organisé implique généralement d’effectuer des demandes aux points de terminaison de service d’API suivants pour accéder aux objets API correspondants ou en créer :

Ce guide utilise cURL exemples pour toutes les demandes. Vous pouvez utiliser d’autres outils de demande d’API (par exemple, Postman), mais vous devez ensuite ajuster les exemples en conséquence.

Configuration requise

Avant de commencer cette configuration, veillez à lire les Prise en main de l’API. Il fournit des informations sur les environnements de test, les contraintes d’utilisation, la sémantique d’API (exécution de commandes, filtrage, tri, etc.) et les bonnes pratiques.

Ordre des opérations

Les objets API ont souvent des dépendances sur d’autres objets API et il existe un ordre que vous devez suivre lors de la création ou de l’accès aux objets lorsque vous créez un élément de ligne de transaction organisé. Par exemple, vous devez fournir les ID des objets API suivants : advertiser, insertion-order, dealet profile. Pour obtenir les ID de ces objets, vous devez les créer ou y avoir déjà accès. Les étapes décrites dans ce guide suivent l’ordre classique des opérations requises pour créer un élément de ligne de transaction organisé.

Meilleures pratiques

Pour obtenir la liste générale des meilleures pratiques à suivre lors de l’utilisation de l’API, consultez Bonnes pratiques relatives à l’API. Voici quelques bonnes pratiques spécifiques à une configuration d’élément de ligne de transaction organisée :

• Définissez le state champ de l’élément de ligne de transaction organisé sur jusqu’à "inactive" ce que l’élément de ligne soit entièrement configuré et prêt pour le test.
• Notez l’ID des objets que vous créez. Les ID des objets que vous créez sont retournés dans le corps de la réponse des requêtes. Vous aurez souvent besoin de ces ID ultérieurement afin de les copier quand ils sont retournés peut réduire le nombre de demandes supplémentaires GET que vous devez effectuer pour les obtenir.

Procédure d’installation

Les étapes suivantes vous guident tout au long du processus de configuration d’un élément de ligne de transaction organisé avec des configurations classiques :

• Étape 1 : Obtenir un jeton d’autorisation
• Étape 2 : Create ou accéder à un annonceur
• Étape 3 : Create ou accéder à un ordre d’insertion
• Étape 4 : Create une transaction
• Étape 5 : Create un profil d’élément de ligne de transaction organisé
• Étape 6 : Create un élément de ligne de transaction organisé

Étape 1 : Obtenir un jeton d’autorisation

Tout d’abord, vous devez obtenir un jeton d’autorisation. Vous devez ensuite inclure ce jeton d’autorisation dans toutes les demandes suivantes (pour plus d’informations, consultez Service d’authentification ). Pour obtenir un jeton d’autorisation, procédez comme suit :

1. Create un fichier JSON contenant votre nom d’utilisateur et votre mot de passe.

   {
       "auth": {
           "username" : "USERNAME",
           "password" : "PASSWORD"
       }
   }
   

2. Effectuez une POST demande au point de /auth terminaison avec ce fichier JSON dans le corps de la demande (pour plus d’informations, consultez Service d’authentification ). Dans la requête cURL ci-dessous, le jeton d’autorisation retourné est stocké dans le fichier «cookies ».

   curl -c cookies -X POST -d @authentication.json 'https://api.appnexus.com/auth'
   

3. Vérifiez le corps de la réponse de votre demande (voir Exemple de réponse ci-dessous). Si votre demande a réussi, vous obtenez un «status » de «OK » et le champ «token » sera rempli avec la valeur du jeton d’authentification.
   
   Exemple de réponse

   {
      "response" : {
         "token" : "authn:225692:2d787d1838283:lax1",
         "status" : "OK"      
      }
   }
   

Étape 2 : Create ou accéder à un annonceur

Vous devez créer ou accéder à un annonceur à partir duquel créer un élément de ligne de transaction organisé. Vous configurez des annonceurs pour les éléments de ligne de transaction organisés de la même façon que vous le feriez pour les éléments de ligne augmentée.

Si vous n’avez pas encore d’annonceur à utiliser, créez un annonceur en procédant comme suit (consultez Service annonceur pour plus d’informations) :

1. Create un json d’annonceur :

   $ cat advertiser.json
   {
       "advertiser": {
           "name": "Curated Deal Line Item Example Advertiser",
           "timezone": "US/Pacific"
       }
   }
   

2. Effectuez une POST demande au point de https://api.appnexus.com/advertiser terminaison avec ce JSON de l’annonceur et un approprié member_id.

   $ curl -b cookies -c cookies -X POST -d @advertiser.json 'https://api.appnexus.com/advertiser?member_id=2378'
   

3. Vérifiez le corps de la réponse de votre demande. Si votre demande a réussi, vous obtenez un «status » de «OK » et vous verrez les mises à jour que vous avez effectuées.

4. Notez l’ID de l’annonceur dans le corps de la réponse afin de pouvoir l’utiliser lorsque vous créez l’élément de ligne de transaction organisé à l’étape 6 - Create un élément de ligne de transaction organisé.

Champs JSON pour l’annonceur (champs facultatifs obligatoires et utiles)

Étape 3 : Create ou accéder à un ordre d’insertion

Vous devez créer un ordre d’insertion ou y accéder pour créer un élément de ligne de transaction organisé. Les éléments de ligne de transaction organisés nécessitent un ordre d’insertion transparent (voir les champs obligatoires ci-dessous).

Si vous n’avez pas encore d’ordre d’insertion à utiliser, créez un ordre d’insertion en procédant comme suit (consultez Service d’ordre d’insertion pour plus d’informations) :

1. Create un json d’ordre d’insertion :

   Exemple JSON : aucune date de fin, aucun budget

   $ cat insertion-order-noenddate.json
   {
       "insertion-order": {
           "name": "Curated Deal Line Item Example IO",
           "budget_intervals": [{
               "start_date": "2019-10-10 00:00:00",
               "end_date": null,
               "daily_budget": null,
               "daily_budget_imps": null,
               "enable_pacing": true,
               "lifetime_budget": null,
               "lifetime_budget_imps": null,
               "lifetime_pacing": false
           }],
           "budget_type": "impression"
       }
   }
   

2. Effectuez une POST requête auprès du point de https://api.appnexus.com/insertion-order terminaison avec ce json d’ordre d’insertion et un et member_idappropriésadvertiser_id.

   Exemple de demande : aucune date de fin, aucun budget

   $ curl -b cookies -c cookies -X POST -d @insertion-order-noenddate.json 'https://api..com/insertion-order?advertiser_id=2605036&member_id=2378'
   

3. Vérifiez le corps de la réponse de votre demande. Si votre demande a réussi, vous obtenez un «status » de «OK » et vous verrez les mises à jour que vous avez effectuées.

4. Notez l’ID d’ordre d’insertion dans le corps de la réponse afin de pouvoir l’utiliser lorsque vous créez l’élément de ligne de transaction organisé à l’étape 6 - Create un élément de ligne de transaction organisé.

Champs JSON pour un ordre d’insertion transparent

Étape 4 : Create une transaction

Vous devez créer la transaction que vous souhaitez associer à l’élément de ligne de transaction organisé.

Pour créer une transaction, procédez comme suit (consultez Deal Service pour plus d’informations) :

1. Create un json de transaction :

   $ cat deal.json
   {
       "deal": {
           "name": "Curated Deal",
           "buyer": {
               "id": 2379
           },
           "type": {
               "id": 5,
               "name": "Curated"
           },
           "version": 2
       }
   }
   

2. Effectuez une POST demande au point de https://api.appnexus.com/deal terminaison avec ce json de transaction et un approprié member_id.

   $ curl -b cookies -c cookies -X POST -d @deal.json 'https://api.appnexus.com/deal?member_id=2378'
   

3. Vérifiez le corps de la réponse de votre demande. Si votre demande a réussi, vous obtenez un «status » de «OK » et vous verrez les mises à jour que vous avez effectuées.

4. Notez l’ID de transaction dans le corps de la réponse afin de pouvoir l’utiliser lorsque vous créez l’élément de ligne de transaction à l’étape 6 - Create un élément de ligne de transaction organisé.

Champs JSON pour la transaction

Champs JSON facultatifs utiles

Champs JSON pour les créations autorisées

Marque (voir Brand Service)

Exemple de marque

"brand_restrict": true,
            "brands": [
                {
                    "id": 2,
                    "name": "1800Flowers",
                    "override": true
                },
                {
                    "id": 4,
                    "name": "Acura",
                    "override": false
                }
            ] 

Type de média (voir Media Subtype Service et Media Type Service)

Exemple de type de média

"allowed_media_subtypes": [
                 {
                     "id": 2,
                     "last_modified": "2015-09-17 19:19:21",
                     "media_type": {
                         "id": 2,
                         "media_type_group_id": 2,
                         "name": "Pop",
                         "uses_sizes": "sometimes"
                     },
                     "name": "Popup",
                     "native_assets": null,
                     "permitted_sizes": null
                 }
             ],
 "allowed_media_types": [
                 {
                     "id": 1,
                     "last_modified": "2012-03-16 21:36:10",
                     "media_type_group_id": 1,
                     "name": "Banner",
                     "uses_sizes": "always"
                 },
                 {
                     "id": 4,
                     "last_modified": "2016-08-22 16:23:12",
                     "media_type_group_id": 1,
                     "name": "Video",
                     "uses_sizes": "never"
                 }
             ]

Étape 5 : Create un profil d’élément de ligne de transaction organisé

Ensuite, créez un profil d’élément de ligne de transaction organisé à utiliser dans le ciblage avec l’élément de ligne de transaction organisé. Veillez à noter l’ID de ce profil pour une utilisation ultérieure. Pour plus d’informations, consultez Service de profil.

Pour créer un profil d’élément de ligne de transaction organisé, procédez comme suit (consultez Service de profil pour plus d’informations) :

1. Create un json de profil d’élément de ligne de transaction organisé :

   Exemple : Création de profil avec les seuils de taux d’achèvement des pays et des vues

   $ cat profile.json
   
   {
           "profile": {
                   "country_action": "include",
                   "country_targets": [{
                           "active": true,
                           "code": "US",
                           "id": 233,
                           "name": "United States"
                   }],
                   "engagement_rate_targets": [{
                                   "engagement_rate_pct": 25,
                                   "engagement_rate_type": "video_completion"
                           },
                           {
                                   "engagement_rate_pct": 50,
                                   "engagement_rate_type": "predicted_iab_video_view_rate"
                           }
                   ],
                   "platform_publisher_targets": [{
                           "action": "include",
                           "deleted": false,
                           "id": 1238721,
                           "name": "test_publisher"
                   }],
                   "platform_placement_targets": [{
                                   "action": "include",
                                   "deleted": false,
                                   "id": 5126395
                           },
                           {
                                   "action": "include",
                                   "deleted": false,
                                   "id": 5301719
                           }
                   ],
                   "platform_content_category_targets": [{
                           "action": "include",
                           "deleted": false,
                           "id": 19062,
                           "is_system": false,
                           "name": "1"
                   }]
           }
   }
   

   Exemple : création de profil sans ciblage

   > cat profile.json
   
   {
       "profile": {
       }
   }
   

2. Effectuez une POST demande au point de https://api.appnexus.com/profile terminaison avec ce json de profil de transaction organisé et un approprié advertiser_id.

   Exemple : Création de profil avec les seuils de taux d’achèvement des pays et des vues

   > curl -b cookies -c cookies -X POST -d @profile.json 'https://api.appnexus.com/profile?advertiser_id=3410892&member_id=2378'
   

   Exemple : création de profil sans ciblage

   > curl -b cookies -c cookies -X POST -d @profile.json 'https://api.appnexus.com/profile?advertiser_id=3410892&member_id=2378'
   

3. Vérifiez le corps de la réponse de votre demande. Si votre demande a réussi, vous obtenez un «status » de «OK » et vous verrez les mises à jour que vous avez effectuées.

4. Notez l’ID de profil dans le corps de la réponse afin de pouvoir l’utiliser lorsque vous créez l’élément de ligne de transaction organisé à l’étape 6 - Create un élément de ligne de transaction organisé.

Champs JSON facultatifs pour le profil d’élément de ligne de transaction

De nombreux champs facultatifs sont disponibles dans le profil d’élément de ligne de transaction organisée pour le ciblage avec l’élément de ligne de transaction organisé. Par exemple, vous pouvez cibler les propriétés associées à l’inventaire, aux types d’inventaire, aux listes d’autorisation, aux listes de blocage, aux types d’appareils, etc. Pour plus d’informations sur les champs disponibles, consultez Service de profil.

Étape 6 : Create un élément de ligne de transaction organisé

Enfin, vous devez créer l’élément de ligne de transaction organisé pour associer l’ID de transaction et le profil d’élément de ligne de transaction organisé que vous avez créé à l’étape 5 - Create un profil d’élément de ligne de transaction organisé.

Pour créer un élément de ligne de transaction organisé, procédez comme suit (consultez Service d’élément de ligne pour plus d’informations) :

1. Create un élément de ligne de transaction organisé JSON (vous aurez besoin d’un ID d’annonceur, d’un ID de commande d’insertion, d’un ID de transaction et d’un ID de profil existants).

   Exemple JSON : Article de ligne de transaction organisé sans budget

   > cat curated_deal_line_item.json
   {
           "line-item": {
                   "ad_types": ["video"],
                   "auction_event": {
                           "kpi_auction_type_id": 1,
                           "payment_auction_type_id": 1,
                           "revenue_auction_type_id": 1
                   },
                   "budget_intervals": [{
                           "start_date": "2019-10-11 12:00:00"
                   }],
                   "deals": [{
                           "id": 628539
                   }],
                   "insertion_orders": [{
                           "id": 1363850
                   }],
                   "line_item_subtype": "standard_curated",
                   "name": "Curated Deal Line Item Example Line Item",
                   "revenue_type": "vcpm",
                   "revenue_value": null,
                   "supply_strategies": {
                           "managed": false,
                           "deals": true,
                           "rtb": false
                   },
                   "profile_id": 113067333,
                   "valuation": {
                           "min_revenue_value": 10
                   }
           }
   }
   

   Exemple JSON : Budget de chiffre d’affaires quotidien de l’élément de ligne de transaction organisé

   > cat curated_deal_line_item_daily.json
   {
           "line-item": {
                   "ad_types": ["video"],
                   "auction_event": {
                           "kpi_auction_type_id": 1,
                           "payment_auction_type_id": 1,
                           "revenue_auction_type_id": 1
                   },
                   "budget_intervals": [{
                           "daily_budget_imps": 270,
                           "end_date": "2019-10-18 23:59:59",
                           "start_date": "2019-10-11 12:00:00",
                           "timezone": "US/Pacific"
                   }],
                   "deals": [{
                           "id": 618159
                   }],
                   "insertion_orders": [{
                           "id": 1363850
                   }],
                   "line_item_subtype": "standard_curated",
                   "name": "Curated Deal Line Item Example Line Item",
                   "revenue_type": "vcpm",
                   "revenue_value": null,
                   "supply_strategies": {
                           "managed": true,
                           "deals": true,
                           "rtb": false
                   },
                   "profile_id": 113067333,
                   "valuation": {
                           "min_revenue_value": 10
                   }
           }
   }
   

2. Effectuez une POST demande au point de terminaison à l’aide de https://api.appnexus.com/line-item cet élément de ligne de transaction JSON et d’un élément approprié advertiser_id.

   Exemple de demande : Article de ligne de transaction organisé sans budget

   > curl -b cookies -c cookies -X POST -d @curated_deal_line_item.json 'https://api.appnexus.com/line-item?member_id=2378&advertiser_id=3410892'
   

   Exemple de demande : budget de chiffre d’affaires quotidien de l’élément de ligne de transaction organisé

   > curl -b cookies -c cookies -X POST -d @curated_deal_line_item_daily.json 'https://api.appnexus.com/line-item?member_id=2378&advertiser_id=3410892'
   

3. Vérifiez le corps de la réponse de votre demande. Si votre demande a réussi, vous obtenez un «status » de «OK » et vous verrez les mises à jour que vous avez effectuées.

4. Notez l’ID d’élément de ligne dans le corps de la réponse afin de pouvoir identifier cet élément de ligne de transaction organisé ultérieurement pour modifier son state (active ou inactive).

Champs JSON pour l’élément de ligne de transaction organisé

Remarque pour line_item_subtype le champ

La définition line_item_subtype du champ sur "standard_curated" affecte automatiquement les valeurs suivantes à ces champs associés.

"line_item_type": "standard_v2",
"bid_object_type": "deal",
"delivery_model_type": "standard",
"supply_strategies": {
"managed": false,
"programmatic_guaranteed": false
}

Impossible de modifier le line_item_subtype champ (et les champs/tableaux associés) après la création de l’élément de ligne.

Champs JSON facultatifs utiles pour l’élément de ligne de transaction organisé

Voir aussi

• Prise en main d’API
• Bonnes pratiques relatives aux API
• Sémantique d’API
• Service de transaction
• Service d’élément de ligne (ALI)
• Service de profil