Guide de configuration de l’API Deal Line Item

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

Vue d’ensemble

Les articles de ligne de transaction sont une fonctionnalité puissante qui permet aux clients du réseau et des éditeurs de mieux soutenir leurs acheteurs en fournissant des outils d’achat préemballés et conviviaux.

La configuration d’un élément de ligne de transaction 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 les 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 pour créer ou accéder à des objets lorsque vous créez un élément de ligne de transaction. Par exemple, vous devez fournir les ID des objets API suivants :
- advertiser
- insertion-order
- deal
- 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.

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 à la configuration d’un élément de ligne de transaction :

• Définissez le state champ de l’élément de ligne de transaction 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 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
• Étape 6 : Create un élément de ligne de transaction

Authentification

É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"      
      }
   }
   

Annonceur

É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. Pour les éléments de ligne de transaction, les annonceurs sont configurés de la même façon que les éléments de ligne augmentée.

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

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": "Deal Line Item Example Advertiser",
           "timezone": "US/Pacific"
       }
   }
   

2. Effectuez une POST demande au https://api.appnexus.com/advertiser endpoint avec ce JSON d’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 à l’étape 6 - Create un élément de ligne de transaction

Ordre d’insertion

É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. Les éléments de ligne de transaction nécessitent un ordre d’insertion transparent (voir les champs obligatoires ci-dessous).

Champs JSON pour l’ordre d’insertion fluide (champs facultatifs obligatoires et utiles)

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 (deux exemples sont présentés ci-dessous) :

   Exemple JSON : aucune date de fin, aucun budget

   $ cat insertion-order-noenddate.json
   {
       "insertion-order": {
           "name": "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"
       }
   }
   

   Exemple JSON : versions d’évaluation, budgets d’impression

   $ cat insertion-order-flights.json
   {
       "insertion-order": {
           "name": "Deal Line Item Example IO",
           "budget_intervals": [
   
               {
                   "start_date": "2019-10-10 00:00:00",
                   "end_date": "2019-10-12 23:59:59",
                   "daily_budget": null,
                   "daily_budget_imps": 10,
                   "enable_pacing": true,
                   "lifetime_budget": null,
                   "lifetime_budget_imps": 980,
                   "lifetime_pacing": false
               },
               {
                   "start_date": "2019-10-13 00:00:00",
                   "end_date": "2019-10-18 23:59:59",
                   "daily_budget": null,
                   "daily_budget_imps": 10,
                   "enable_pacing": true,
                   "lifetime_budget": null,
                   "lifetime_budget_imps": 100,
                   "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.appnexus.com/insertion-order?advertiser_id=2605036&member_id=2378'
   

   Exemple de demande : vols, budgets d’impression

   $ curl -b cookies -c cookies -X POST -d @insertion-order-flights.json 'https://api.appnexus.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 à l’étape 6 - Create un élément de ligne de transaction.

Affaire

Étape 4 : Create une transaction

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

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
                }
            ] 

Langue (voir Language Service)

Exemple de langue

"language_restrict": true,
            "languages": [
                {
                    "id": 1,
                    "name": "English",
                    "override": false
                },
                {
                    "id": 2,
                    "name": "Chinese",
                    "override": true
                }
            ]

Niveau de confiance

Exemple de niveau de confiance

"audit_status_option": "max_trust" 

Catégorie de création

Exemple de catégorie de création

"categories": [
                 {
                     "id": 1,
                     "name": "Airlines",
                     "override": false
                 },
                 {
                     "id": 2,
                     "name": "Apparel",
                     "override": true
                 }
             ],
             "category_restrict": true

Créations spécifiques

Exemple de créations spécifiques

"creatives": [
                {
                    "id": 161501729,
                    "status": "banned"
                },
                {
                    "id": 161501882,
                    "status": "approved"
                }
            ]

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"
                 }
             ]

Attributs techniques (voir Technical Attribute Service)

Exemple d’attributs techniques

"technical_attribute_restrict": false,
             "technical_attributes": [
                 {
                     "id": 1,
                     "name": "Image",
                     "override": true
                 }
             ]

Champs JSON pour la protection des données de transaction (voir Visibility Profile Service)

ID d’utilisateur et ID d’appareil

Exemple protéger l’ID utilisateur et l’ID d’appareil

Étape 1 : Create un profil de visibilité

> cat visibility_profile.json
{
    "visibility-profile": {
        "expose_device_id_default": false,
        "expose_user_id_default": false,
        "name": "Deal Visibility Profile"
    }
}
 
 
> curl -b cookies -c cookies -X POST -d @visibility_profile.json 'https://api.appnexus.com/visibility-profile?member_id=2378'

Étape 2 : Associer le profil de visibilité à la transaction et activer la protection des données

> cat deal_data_protection.json
{
    "deal": {
        "visibility_profile_id": 29657,
        "data_protected": true
    }
}
 
 
> curl -b cookies -c cookies -X PUT -d @deal_data_protection.json 'https://api.appnexus.com/deal?id=549271'

Adresse IP

Exemple d’adresse IP de protection

Étape 1 : Create un profil de visibilité

> cat visibility_profile.json
{
    "visibility-profile": {
        "expose_ip_default": false,
        "ip_exposure_default": "truncated",
        "name": "Deal Visibility Profile - Hidden"
    }
}
 
 
> curl -b cookies -c cookies -X POST -d @visibility_profile.json 'https://api.appnexus.com/visibility-profile?member_id=2378'

Étape 2 : Associer le profil de visibilité à la transaction et activer la protection des données

> cat deal_data_protection.json
{
    "deal": {
        "visibility_profile_id": 29657,
        "data_protected": true
    }
}
 
 
> curl -b cookies -c cookies -X PUT -d @deal_data_protection.json 'https://api.appnexus.com/deal?id=549271'

URL

Exemple de domaine de protection

Étape 1 : Create un profil de visibilité

> cat visibility_profile.json
{
    "visibility-profile": {
        "name": "Deal Visibility Profile - Hidden",
        "url_exposure_default": "hidden"
    }
}
 
 
> curl -b cookies -c cookies -X POST -d @visibility_profile.json 'https://api.appnexus.com/visibility-profile?member_id=2378'

Étape 2 : Associer le profil de visibilité à la transaction et activer la protection des données

> cat deal_data_protection.json
{
    "deal": {
        "visibility_profile_id": 29657,
        "data_protected": true
    }
}
 
 
> curl -b cookies -c cookies -X PUT -d @deal_data_protection.json 'https://api.appnexus.com/deal?id=549271'

Ajouter au segment (voir Deal Service)

Empêcher l’ajout d’un segment lors d’un clic ou d’un exemple d’affichage

> cat add_segment.json
{
    "deal": {
        "allow_creative_add_on_click": false,
        "allow_creative_add_on_view": false
    }
}
 
 
> curl -b cookies -c cookies -X PUT -d @add_segment.json 'https://api.appnexus.com/deal?id=123456'

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": "Deal Line Item Example Deal",
           "buyer": {
               "id": 2379
           },
           "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.

Profil

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

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

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 pour le ciblage avec l’élément de ligne de transaction. 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.

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

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

   Exemple : création de profil avec des limites de pays, de fréquence/récurrence et de taux d’affichage/taux d’achèvement

   $ 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"
               }
           ],
           "max_day_imps": 10,
           "min_minutes_per_imp": 300
       }
   }
   

   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 profil de transaction JSON et un approprié advertiser_id.

   Exemple : création de profil avec pays, limites de récurrence de fréquence et seuils de taux d’affichage/taux d’achèvement

   > 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 à l’étape 6 - Create un élément de ligne de transaction.

Élément de ligne

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

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

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

Champs JSON facultatifs utiles

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

1. Create un élément de ligne de transaction 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 sans budget

   > cat 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
           },
           "bid_object_type": "deal",
           "budget_intervals": [{
               "start_date": "2019-10-11 12:00:00"
           }],
           "deals": [{
               "id": 618159
           }],
           "insertion_orders": [{
               "id": 1363850
           }],
           "line_item_type": "standard_v2",
           "name": "Deal Line Item Example Line Item",
           "revenue_type": "vcpm",
           "revenue_value": null,
           "supply_strategies": {
               "managed": true
           },
           "profile_id": 112548354,
           "valuation": {
               "min_revenue_value": 10
           }
       }
   }
   

   Exemple JSON : Budget d’impression de durée de vie des éléments de ligne de transaction

   > cat deal_line_item_lifetime.json
   {
       "line-item": {
           "ad_types": ["video"],
           "auction_event": {
               "kpi_auction_type_id": 1,
               "payment_auction_type_id": 1,
               "revenue_auction_type_id": 1
           },
           "bid_object_type": "deal",
           "budget_intervals": [
                   {
                       "end_date": "2019-10-18 23:59:59",
                       "lifetime_budget_imps": 2586,
                       "start_date": "2019-10-11 12:00:00",
                       "timezone": "US/Pacific"
                   },
                   {
                       "end_date": "2019-10-25 23:59:59",
                       "lifetime_budget_imps": 2414,
                       "start_date": "2019-10-19 00:00:00",
                       "timezone": "US/Pacific"
                   }
               ],
           "deals": [{
               "id": 618159
           }],
           "insertion_orders": [{
               "id": 1363850
           }],
           "line_item_type": "standard_v2",
           "name": "Deal Line Item Example Line Item",
           "revenue_type": "vcpm",
           "revenue_value": null,
           "supply_strategies": {
               "managed": true
           },
           "profile_id": 112548354,
           "valuation": {
               "min_revenue_value": 10
           }
       }
   }
   

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

   > cat 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
           },
           "bid_object_type": "deal",
           "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_type": "standard_v2",
           "name": "Deal Line Item Example Line Item",
           "revenue_type": "vcpm",
           "revenue_value": null,
           "supply_strategies": {
               "managed": true
           },
           "profile_id": 112548354,
           "valuation": {
               "min_revenue_value": 10
           }
       }
   }
   

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

     Exemple de demande : Article de ligne de transaction pas de budget

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

     Exemple de demande : Budget d’impression de durée de vie des éléments de ligne de transaction

   > curl -b cookies -c cookies -X POST -d @deal_line_item_lifetime.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

   > curl -b cookies -c cookies -X POST -d @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 ultérieurement pour modifier son state (active ou inactive).

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