Créer un achat matriciel de campagne avec l'API

Cet exemple illustre comment créer une campagne d'achat matriciel (Matrix Buy) à l'aide de l'API REST de Guaranteed Campaigns. Il montre l'ensemble complet des opérations requises pour créer une ligne de diffusion, valider les requêtes de soumission pour achat, vérifier la disponibilité et mettre à jour les lignes de diffusion d'achat matriciel. Cet exemple montre également comment identifier les lignes de diffusion d'achat matriciel dans l'interface utilisateur de Guaranteed Campaigns.

Les points de terminaison et les paramètres de l'API REST Guaranteed Campaigns sont décrits dans la Référence de la méthode REST.

Note : Les numéros d'identification que nous utilisons dans ces échantillons sont fournis à titre d'illustration. Ils ne sont pas valides. Assurez-vous d’utiliser vos propres numéros d’identification pour vos intégrations.

Note : Tous les exemples de corps de requête dans ce document sont des fichiers JSON bruts.

Campagne d'achat matriciel

Guaranteed Campaigns

Conseil : L'achat matriciel (Matrix Buy) peut uniquement être créé et mis à jour via l'API REST de Guaranteed Campaigns.

Note : La fonctionnalité d'achat matriciel doit être activée dans votre domaine Guaranteed Campaigns. Contactez Broadsign Services pour activer la fonctionnalité.

L'achat matriciel est utilisé pour soumettre des campagnes pour achat impliquant des horaires fixes multicibles (par ex. moment de la journée, jour de la semaine, ensemble d'écrans) au cours d'une journée ou sur plusieurs jours, avec un minimum de flux de travail. Il peut être utilisé par les clients de Guaranteed Campaigns qui utilisent un outil de planification externe et exploitent l'API REST de Guaranteed Campaigns pour soumettre leurs campagnes pour acaht de manière plus efficace.

L'achat matriciel offre les avantages suivants :

  • Permet aux utilisateurs de l'API REST de Guaranteed Campaigns d'implémenter des stratégies de ciblage de campagne avancées provenant d'outils de planification externes, incluant la soumission pour achat d'écrans ou d'ensembles d'écrans avec plusieurs horaires non contigus dans une seule ligne de diffusion.
  • Minimise le nombre de lignes de diffusion qu'un utilisateur doit créer. Vous pouvez créer une seule ligne de diffusion impliquant des horaires multiples et/ou non contigus, ce qui nécessitait auparavant la création de plusieurs lignes de diffusion.
  • Minimise le nombre de campagnes résultantes dans la solution Content and Network Management afin de réduire la charge de travail liée à la programmation du contenu.

Clonage d'achat matriciel

Une ligne de diffusion d'achat matriciel ne peut pas être clonée.

Impact sur Content and Network Management

Le module Guaranteed Campaigns transmettra un fichier de saturation marquant les données de saturation appropriées pour chaque écran sélectionné dans la ligne de diffusion d'achat matriciel.

Le format de fichier de saturation externe existant ne sera pas affecté.

Prises de contrôle (Takeovers)

Les prises de contrôle seront priorisées pour être diffusées de la manière habituelle, ce qui signifie qu'une ligne de diffusion d'achat matriciel pourrait ne pas être diffusée intégralement. Elle ne peut pas être rééquilibrée ailleurs en raison de ses allocations fixes. Toutefois, si une prise de contrôle affectant une ligne de diffusion d'achat matriciel est annulée par la suite, les allocations de la ligne de diffusion d'achat matriciel concernée seront rétablies.

Pour créer une campagne d'achat matriciel :

Guaranteed Campaigns

Vous devrez utiliser les méthodes suivantes pour créer une campagne d'achat matriciel.

Note : Vous aurez besoin des numéros d'identification des réponses comme valeurs pour les paramètres des étapes suivantes de la séquence.

  1. Créez une ligne de diffusion d'achat matriciel. Utilisez la méthode POST /api/v1/proposal/proposal_items.
  2. Vérifiez la disponibilité des écrans que vous avez sélectionnés. Utilisez l'une des méthodes suivantes :
    • retenir : méthode GET /api/v1/proposal/{proposal_id}/availability?type=[hold].
    • book : méthode GET /api/v1/proposal/{proposal_id}/availability?type=[book].
  3. À l'aide du numéro d'identification de votre nouvelle campagne, réservez (Hold) ou soumittez pour achat (Book) la campagne. Utilisez l'une des méthodes suivantes :
    • retenir : méthode PUT /api/v1/proposal/{proposal_id}/hold
    • book : méthode POST /api/v1/proposal/book_proposal/{proposal_id}
  4. Assurez-vous que la campagne a bien été réservée ou soumise pour achat. Utilisez la méthode GET /api/v1/proposal/{proposal_id}.
  5. Mettez à jour, modifiez et annulez les lignes de diffusion d'achat matriciel. Utilisez la méthode PUT /api/v1/proposal/proposal_item/{proposal_item_id}.

Méthode de requête : POST

URL de requête : https://direct.broadsign.com/api/v1/proposal/proposal_items

Documentation : Swagger /api/v1/proposal/proposal_items

Créez une ligne de diffusion d'achat matriciel en appelant cette méthode.

Le module Guaranteed Campaigns accepte et stocke les requêtes de soumission pour achat provenant d'un outil de planification externe via un point de terminaison d'API. La requête de soumission pour achat doit contenir :

  • La date de début et de fin de chaque segment de la requête de soumission pour achat.
  • L'heure de début et de fin de chaque segment de la requête de soumission pour achat.
  • Les identifiants d'écran cibles (Screen_ids).
  • Les requêtes de soumission pour achat doivent être envoyées dans un format JSON valide.

Par exemple :

Horaire Date de début Date de fin Heure de début Heure de fin Identifiant de cadre/d'écran
1 2023-01-01 2023-01-01 13:00:00 14:59:58 167781
2 2023-01-01 2023-01-01 16:00:00 17:59:58 167782

Requête

Copier 
 {
  "proposal_id": 623387,
  "line_items": [
 {
  "name": "Matrix PLI",
  "reference_id": "123321",
  "slot_duration": "5.0",
  "buy_mode": {
  "type": "matrix",
  "values":
 {
 "saturation": 1
 }
 },
  "price": 1,
  "priority": 1,
  "matrix": [{
  "start_date": "2023-06-30",
  "end_date": "2023-07-05",
  "start_time": "8:00:00",
  "end_time": "9:00:00",
  "screen_ids": [220710]
 }
 ]
}
 ]
 }

Réponse

Copier 
{
   "proposal_id": 623387,
   "line_items": [
       {
           "reference_id": "123321",
           "id": 926096
       }
   ]
}

Les codes de réponse suivants sont possibles :

  • Si la charge utile (payload) est valide :

    • 201 - {"schedule/matrix created successfully"}

  • si la charge utile n'est pas valide :

    • 40x, {"problematic_schedules": []}

    ou

    40x, {"proposal item doesn't exist"}

Vous devez toujours vérifier la disponibilité des écrans avant de r/server la campagne ou de la soumettre pour achat.

La vérification de la disponibilité tient compte de la réallocation et du rééquilibrage.

  • La vérification de la disponibilité s'effectue en deux étapes :
    1. La vérification de la disponibilité, si elle est réussie, permettra de passer la ligne de diffusion à l'état Held ou Booked. Si la vérification de la disponibilité échoue, la ligne de diffusion sera envoyée au rééquilibrage pour des calculs supplémentaires.
    2. Si le rééquilibrage est nécessaire et permet de résoudre le problème de disponibilité, il renverra le résultat et la ligne de diffusion pourra être mise en Held ou Booked. Sinon, le résultat initial de Étape 1 – Créer une ligne de diffusion d'achat matriciel sera publié.
  • Les soumissions pour achat effectuées avec l'achat matriciel géreront la réallocation comme d'habitude. Les campagnes existantes en état Held, Booked, Submitted et Live seront réallouées pour faire de la place aux demandes de soumissions pour achat entrantes, tant qu'il y a de l'espace disponible pour le déplacement.
  • Les campagnes soumises pour achat avec l'achat matriciel ne peuvent pas être rééquilibrées, car elles sont soumises avec un horaire fixe et immuable.
  • Les soumissions pour achat qui réussissent la vérification de disponibilité pourront être mises en réservation ou soumises pour achat.
  • Pour les requêtes d'achat qui ne réussissent pas la vérification de disponibilité, l'API renverra la liste des identifiants d'écran, des dates et des heures indisponibles.
  • Les lignes de diffusion qui ne réussissent pas la vérification de disponibilité resteront dans un état Saved à moins qu'elles ne soient mises à jour (via l'API uniquement) ou supprimées via l'API ou l'interface utilisateur.

Méthode de requête : GET

URL de requête : https://direct.broadsign.com/api/v1/proposal/{proposal_id}/availability?type=hold

Documentation : Swagger /api/v1/proposal/{proposal_id}/availability

Vérifiez la disponibilité des écrans que vous avez sélectionnés en appelant cette méthode.

Utilisez l'identifiant de proposition créé à Étape 1 – Créer une ligne de diffusion d'achat matriciel comme proposal_id.

Réponse

Pour poser une option sur la campagne, le paramètre availability doit être « available ».

Copier 
 {
    "proposal_id": 623387,
    "proposal_name": "Broadsign Proposal",
    "availability": "available",
    "goals": [],
    "proposal_items": [
       {
           "proposal_item_id": 926096,
           "proposal_item_name": "Matrix PLI",
           "availability": "available",
           "inventory_type": "digital",
           "is_package": false,
           "screens": {
               "available": {
                   "screen_ids": [
                       220710
                   ],
                   "messages": [],
                   "group_count": 0,
                   "screen_count": 1
               }
           },
           "messages": [],
           "proposal_item_reference_id": "123321"
       }
   ],
   "requested_group_count": 0,
   "bookable_group_count": 0,
   "requested_screen_count": 1,
   "bookable_screen_count": 1
 }

Méthode de requête : GET

URL de requête : https://direct.broadsign.com/api/v1/proposal/{proposal_id}/availability?type=book

Documentation : Swagger /api/v1/proposal/{proposal_id}/availability

Vérifiez la disponibilité des écrans que vous avez sélectionnés en appelant cette méthode.

Utilisez l'identifiant de proposition créé à Étape 1 – Créer une ligne de diffusion d'achat matriciel comme proposal_id.

Réponse

Pour soumettre la campagne pour achat, le paramètre availability doit être « available ».

Copier 
 {
   "proposal_id": 623387,
   "proposal_name": "Broadsign Proposal",
   "availability": "available",
   "goals": [],
   "proposal_items": [
       {
           "proposal_item_id": 926096,
           "proposal_item_name": "Matrix PLI",
           "availability": "available",
           "inventory_type": "digital",
           "is_package": false,
           "screens": {
               "available": {
                   "screen_ids": [
                       220710
                   ],
                   "messages": [],
                   "group_count": 0,
                   "screen_count": 1
               }
           },
           "messages": [],
           "proposal_item_reference_id": "123321"
       }
   ],
   "requested_group_count": 0,
   "bookable_group_count": 0,
   "requested_screen_count": 1,
   "bookable_screen_count": 1
 }

Vous pouvez maintenant poser une option sur la campagne ou la soumettre pour achat.

Méthode de requête : PUT

URL de requête : https://direct.broadsign.com/api/v1/proposal/{proposal_id}/hold

Documentation : Swagger /api/v1/proposal/{proposal_id}/hold

Si vous souhaitez poser une option sur la campagne, appelez cette méthode.

Utilisez l'identifiant de proposition créé à Étape 1 – Créer une ligne de diffusion d'achat matriciel comme proposal_id.

Réponse

Copier 
{
   "id": 623387,
   "creation_tm": "2023-06-19 19:37:17",
   "modification_tm": "2023-06-19 21:51:05",
   "active": true,
   "domain_id": 53,
   "name": "Broadsign Proposal",
   "description": "This is a test proposal",
   "price": 0.0,
   "discount": 0.0,
   "status": 1,
   "client_id": "Client ID 1234",
   "client_name": "Doe Company",
   "client_address": "Montreal, Canada",
   "contact_name": "John Doe",
   "contact_phone": "1-888-000-0000",
   "contact_email": "john@doe.com",
   "start_date": "2023-06-30",
   "earliest_start_datetime_in_utc": "2023-06-30 12:00:00",
   "latest_end_datetime_in_utc": "2023-07-05 13:00:00",
   "picture": "",
   "contract_id": "ABC-1234",
   "contract_number": "ABC-1234",
   "hold_expiry_tm": "2023-06-28 21:51:05",
   "locks": {
       "book": false,
       "edit": false,
       "hold": false,
       "sync": false,
       "delete": false,
       "download": false,
       "sync_button": false,
       "contact_edit": false
   },
   "custom_data": {},
   "owner_user_id": 3186,
   "hold_requested": false,
   "hold_tm": "2023-06-19 21:51:05",
   "creation_user_id": 3186,
   "modification_user_id": 3186,
   "creation_date_time": "2023-06-19 19:37:17",
   "last_modification_date_time": "2023-06-19 21:51:05",
   "owner_user_name": "Sarah",
   "creation_user_name": "Sarah",
   "suggested_price": 1.0,
   "end_date": "2023-07-05",
   "proposal_item_id_list": [
       926096
   ],
   "category_ids": [],
   "is_cloneable": false
}

Méthode de requête : POST

URL de requête : https://direct.broadsign.com/api/v1/proposal/book_proposal/{proposal_id}

Documentation : Swagger /api/v1/proposal/book_proposal/{proposal_id}

Si vous souhaitez soumettre une campagne pour achat, appelez cette méthode.

Utilisez l'identifiant de proposition créé à Étape 1 – Créer une ligne de diffusion d'achat matriciel comme proposal_id.

Réponse

Les codes de réponse suivants sont possibles :

  • Si la charge utile (payload) est valide :

    • 200 - {"success"}

  • si la charge utile n'est pas valide :

    • 40x, {"problematic_schedules": []}

    ou

    40x, {"proposal item doesn't exist"}

Méthode de requête : GET

URL de requête : https://direct.broadsign.com/api/v1/proposal/{proposal_id}

Documentation : Swagger /api/v1/proposal/{proposal_id}

Cette étape est importante, car elle garantit que la campagne a bien été mise en option ou soumise pour achat.

Utilisez l'identifiant de proposition créé à Étape 1 – Créer une ligne de diffusion d'achat matriciel comme proposal_id.

Réponse

Pour une campagne en option, le paramètre status doit être « 4 ».

Pour une campagne soumise pour achat, le paramètre status doit être « 10 ».

Pour plus d'informations sur les valeurs de statut de campagne, consultez Valeurs d'état de campagne pour l'API REST.

Copier 
{
   "id": 623387,
   "creation_tm": "2023-06-19 21:58:28",
   "modification_tm": "2023-06-19 21:59:40",
   "active": true,
   "domain_id": 53,
   "name": "Broadsign Proposal",
   "description": "This is a test proposal",
   "price": 0.0,
   "discount": 0.0,
   "status": 10,
   "client_id": "Client ID 1234",
   "client_name": "Doe Company",
   "client_address": "Montreal, Canada",
   "contact_name": "John Doe",
   "contact_phone": "1-888-000-0000",
   "contact_email": "john@doe.com",
   "start_date": "2023-06-30",
   "earliest_start_datetime_in_utc": "2023-06-30 12:00:00",
   "latest_end_datetime_in_utc": "2023-07-05 13:00:00",
   "picture": "",
   "contract_id": "ABC-1234",
   "contract_number": "ABC-1234",
   "hold_expiry_tm": null,
   "locks": {
       "book": false,
       "hold": false,
       "contact_edit": false,
       "download": false,
       "sync": false,
       "delete": false,
       "edit": false,
       "sync_button": false
   },
   "custom_data": {},
   "owner_user_id": 3186,
   "hold_requested": false,
   "hold_tm": null,
   "creation_user_id": 3186,
   "modification_user_id": 3186,
   "creation_date_time": "2023-06-19 21:58:28",
   "last_modification_date_time": "2023-06-19 21:59:40",
   "owner_user_name": "Sarah",
   "creation_user_name": "Sarah",
   "suggested_price": 1.0,
   "end_date": "2023-07-05",
   "proposal_item_id_list": [
       926106
   ],
   "category_ids": [],
   "is_cloneable": false
}

La modification des lignes de diffusion d'achat matriciel dépend de leur état actuel.

  • Les modifications des lignes de diffusion d'achat matriciel dans l'état Saved peuvent être mises à jour via l'API.
  • Les modifications des lignes de diffusion d'achat matriciel dans l'état Held peuvent être effectuées en libérant la ligne de diffusion et en la mettant à jour via l'API.
  • Les modifications des lignes de diffusion d'achat matriciel dans l'état Submitted nécessitent une annulation et une nouvelle requête de ligne de diffusion via l'API.

Méthode de requête : PUT

URL de requête : https://direct.broadsign.com/api/v1/proposal/proposal_item/{proposal_item_id}

Documentation : Swagger /api/v1/proposal/proposal_item/{proposal_item_id}

Vous pouvez mettre à jour une ligne de diffusion dans l'état Saved.

Réponse

Copier 
{
   "id": 926154,
   "creation_tm": "2023-06-19 22:40:19",
   "modification_tm": "2023-06-19 23:34:33",
   "active": true,
   "active_type": "matrix",
   "actual_impressions": null,
   "actual_repetitions": null,
   "name": "Matrix PLI",
   "price": 1,
   "custom_price": null,
   "proposal_id": 623446,
   "package_id": null,
   "flight_duration": 1,
   "flight_type": 0,
   "slot_duration": 5.0,
   "saturation": 1.0,
   "suggested_price": "0",
   "status": 1,
   "start_date": "2023-06-30",
   "end_date": "2023-07-05",
   "start_time": "08:00:00",
   "end_time": "10:00:00",
   "earliest_start_datetime_in_utc": "2023-06-30 12:00:00",
   "latest_end_datetime_in_utc": "2023-07-05 14:00:00",
   "dow_mask": 127,
   "provider_id": null,
   "external_id": null,
   "multiplier": 6,
   "filters": [],
   "mode": [
       {
           "type": "matrix",
           "active": true,
           "values": {
               "saturation": 1.0
           }
       }
   ],
   "inventory_type": "digital",
   "day_masks": {
       "1560824": null
   },
   "priority": 1,
   "performance_update_tm": null,
   "last_auto_rebalance_tm": null,
   "synchronized": false,
   "is_processing": false,
   "is_preemptible": null,
   "booking_tm": null,
   "is_name_templatized": false,
   "expected": null,
   "projected": 0,
   "target": 0,
   "proposal_goal_id": null,
   "reference_id": "1234562",
   "cpm": 0.0,
   "custom_cpm": 0.0,
   "saturation_freeze_tm": null,
   "creation_user_id": 3186,
   "modification_user_id": 3186,
   "group_count": 1,
   "screen_count": 3,
   "screens": [
       204114,
       220710
   ],
   "dynamic_screen_selection": null
}

Méthode de requête : DELETE

URL de requête : https://direct.broadsign.com/api/v1/proposal/proposal_item/{proposal_item_id}/hold

Documentation : Swagger /api/v1/proposal/proposal_item/{proposal_item_id}/hold

Les modifications des lignes de diffusion d'achat matriciel dans l'état Held peuvent être effectuées en libérant la ligne de diffusion, puis en la mettant à jour comme décrit à Étape 5A – Modifier des lignes de diffusion d'achat matriciel enregistrées.

Réponse

Copier 
{
   "id": 623387,
   "creation_tm": "2023-06-19 22:40:19",
   "modification_tm": "2023-06-19 22:43:08",
   "active": true,
   "active_type": "matrix",
   "actual_impressions": null,
   "actual_repetitions": null,
   "name": "Matrix PLI",
   "price": 1,
   "custom_price": null,
   "proposal_id": 623446,
   "package_id": null,
   "flight_duration": 1,
   "flight_type": 0,
   "slot_duration": 5.0,
   "saturation": 1.0,
   "suggested_price": "0",
   "status": 1,
   "start_date": "2023-06-30",
   "end_date": "2023-07-05",
   "start_time": "08:00:00",
   "end_time": "09:00:00",
   "earliest_start_datetime_in_utc": "2023-06-30 12:00:00",
   "latest_end_datetime_in_utc": "2023-07-05 13:00:00",
   "dow_mask": 127,
   "provider_id": null,
   "external_id": null,
   "multiplier": 6,
   "filters": [],
   "mode": [
       {
           "type": "ppl",
           "active": false,
           "values": {
               "bs_saturation": null,
               "saturation": null
           }
       },
       {
           "type": "sov",
           "active": false,
           "values": {
               "sov": 15.0
           }
       },
       {
           "type": "takeover",
           "active": false,
           "values": {
               "sov": 100.0
           }
       },
       {
           "type": "goal_impressions",
           "active": false,
           "values": {
               "impressions": null,
               "cpm": null,
               "budget": null
           }
       },
       {
           "type": "goal_budget",
           "active": false,
           "values": {
               "impressions": null,
               "cpm": null,
               "budget": null
           }
       },
       {
           "type": "goal_repetitions",
           "values": {
               "repetitions": null
           },
           "active": false
       },
       {
           "type": "average_sov",
           "active": false,
           "values": {
               "sov": 15.0,
               "distribution": "screen_day"
           }
       },
       {
           "type": "matrix",
           "active": true,
           "values": {
               "saturation": 1.0,
               "expected_repetitions": 360,
               "expected_impressions": 0
           }
       }
   ],
   "inventory_type": "digital",
   "day_masks": {
       "1560824": null
   },
   "priority": 1,
   "performance_update_tm": null,
   "last_auto_rebalance_tm": null,
   "synchronized": false,
   "is_processing": false,
   "is_preemptible": null,
   "booking_tm": null,
   "is_name_templatized": false,
   "expected": null,
   "projected": 0,
   "target": 0,
   "proposal_goal_id": null,
   "reference_id": "123321",
   "cpm": null,
   "custom_cpm": 0.0,
   "saturation_freeze_tm": null,
   "creation_user_id": 3186,
   "modification_user_id": 3186,
   "group_count": 0,
   "screen_count": 1,
   "dynamic_screen_selection": null
}

Méthode de requête : POST

URL de requête : https://direct.broadsign.com/api/v1/proposal/proposal_item/{proposal_item_id}/cancel

Documentation : Swagger /api/v1/proposal/proposal_item/{proposal_item_id}/cancel

Les modifications des lignes de diffusion d'achat matriciel dans l'état Submitted nécessitent l'annulation de la ligne de diffusion, puis la création d'une nouvelle ligne de diffusion avec les modifications, comme décrit à Étape 1 – Créer une ligne de diffusion d'achat matriciel.

Réponse

Les codes de réponse suivants sont possibles :

  • Si la charge utile (payload) est valide :

    • 200 - {"success"}

  • si la charge utile n'est pas valide :

    • 40x, {"PROPOSAL_NOT_FOUND": []}

Les soumissions pour achat sont créées dans le module Guaranteed Campaigns sous un nouveau type d'achat appelé Matrix.

Statut En ligne (Live)

Statut Enregistré (Saved)

Les lignes de diffusion d'achat matriciel ne peuvent pas être clonées ou modifiées dans l'interface utilisateur de Guaranteed Campaigns.

Elles peuvent uniquement être créées et mises à jour via l'API.