Microsoft Monétiser un serveur publicitaire pour une offre programmatique garantie

La configuration d’une implémentation d’API pour une transaction par programmation garantie (PG) via Microsoft Monetize Ad Server 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’une transaction PG à l’aide de notre API.

Vue d’ensemble

Les offres PG 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 pour les transactions à prix fixe.

La configuration d’une transaction PG implique de demander aux points de terminaison de service API suivants d’accéder aux objets API correspondants ou de 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 vis-à-vis 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 une offre PG. 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 une transaction PG.

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 pour PG
• Étape 4 : Create une offre PG
• Étape 5 : Create un profil d’élément de ligne de transaction PG
• Étape 6 : Create un élément de ligne de transaction PG

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

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

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

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

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

Vous devez créer un ordre d’insertion ou y accéder pour créer une transaction PG. Les éléments de ligne de transaction 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 (pour plus d’informations, consultez Service d’ordre d’insertion) :

1. Create un json d’ordre d’insertion (deux exemples sont présentés ci-dessous) :

   Exemple JSON : aucune date de fin, budget illimité

   $ cat insertion-order-noenddate.json
   {
       "insertion-order": {
           "name": "PG Deal Example IO",
                   "state": "active",
           "budget_intervals": [{
               "start_date": "2022-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
           }],
           "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, budget illimité

   curl -b cookies -c cookies -X POST -d @insertion-order-noenddate.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 PG à l’étape 6 - Create un élément de ligne de transaction.

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

Étape 4 : Create une offre PG

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

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

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.

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'

IP Address (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'

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

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

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

   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 des limites de pays, de fréquence/récurrence et 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 PG à l’étape 6 - Create un élément de ligne de transaction PG.

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.

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

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

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

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 : Élément de ligne de transaction PG sans budget

   > cat deal_line_item.json
   {
       "line-item": {
           "ad_types": ["banner"],
           "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": "2022-08-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": "cpm",
           "revenue_value": "5",
           "supply_strategies": {
               "managed": true,
                           "rtb": false,
                           "programmatic_guaranteed": false
           },
           "profile_id": 112548354,
           "valuation": {
               "min_revenue_value": null
           }
       }
   }
   

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

   > cat deal_line_item_lifetime.json
   {
       "line-item": {
           "ad_types": ["banner"],
           "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": "2022-10-18 23:59:59",
                       "lifetime_budget_imps": 2586,
                       "start_date": "2022-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": "cpm",
           "revenue_value": "5",
           "supply_strategies": {
               "managed": true,
                           "rtb": false,
                           "programmatic_guaranteed": false
           },
           "profile_id": 112548354,
           "valuation": {
               "min_revenue_value": null
           }
       }
   }
   

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

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

budget_intervals Exemple

"budget_intervals": [
{
"id": 18770835,
"object_id": 18601984,
"object_type": "campaign_group",
"start_date": "2022-08-08 00:00:00",
"end_date": "2022-08-17 23:59:59",
"timezone": "Europe/Paris",
"code": null,
"parent_interval_id": null,
"creatives": null,
"subflights": null,
"lifetime_budget": null,
"lifetime_budget_imps": 100,
"lifetime_pacing": false,
"enable_pacing": true,
"daily_budget_imps": null,
"lifetime_pacing_pct": 105,
"daily_budget": null,
"daily_budget_imps_opt": null,
"daily_budget_opt": null,
"underspend_rollover_state": false
}
]

auction_event Exemple

"auction_event": {
"payment_auction_event_type_code": "impression",
"payment_auction_event_type": "impression",
"payment_auction_type_id": 1,
"revenue_auction_event_type_code": "impression",
"revenue_auction_event_type": "impression",
"revenue_auction_type_id": 1,
"kpi_auction_event_type_code": "impression",
"kpi_auction_event_type": "impression",
"kpi_auction_type_id": 1,
"kpi_value_type": null,
"kpi_value": null
}

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

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