Programmatique

Ce guide explique dans les grandes lignes comment utiliser les fonctionnalités du programmatique direct via l'API. Il décrit comment créer une proposition et comment effectuer une négociation.

Primer

Une proposition programmatique est semblable à une campagne dans Google Ad Manager. Les propositions programmatiques contiennent des informations générales sur une proposition de transaction entre vous et un acheteur. Une proposition et ses éléments de campagne représentent une offre d'inventaire présentée à un acheteur.

Pour plus d'informations, consultez le Centre d'aide.

Créer une proposition via l'API

Pour créer un objet Proposal, seuls le nom et l'acheteur programmatique sont requis. Vous pouvez obtenir l'ID de l'acheteur programmatique via l'interface utilisateur ou la table PQL Programmatic_Buyer.

Java

Proposal proposal = new Proposal();

// Setting required Marketplace information.
ProposalMarketplaceInfo proposalMarketplaceInfo = new ProposalMarketplaceInfo();
proposalMarketplaceInfo.setBuyerAccountId(programmaticBuyerId);

// Set common required fields for a proposal.
proposal.setName("Proposal #" + new Random().nextInt(Integer.MAX_VALUE));
proposal.setPrimaryTraffickerId(primaryTraffickerId);
proposal.setMarketplaceInfo(proposalMarketplaceInfo);
    

Afficher sur GitHub

Python

proposal = {
    # Setting required Marketplace information.
    'isProgrammatic': 'true',
    'marketplaceInfo': {
        'buyerAccountId': programmatic_buyer_id,
    },
    # Set common required fields for proposals.
    'name': 'Proposal #%s' % uuid.uuid4(),
    # ...
}
    

Afficher sur GitHub

PHP

$proposal = new Proposal();
$proposal->setName('Proposal #' . uniqid());

// Set the required Marketplace information.
$proposalMarketplaceInfo = new ProposalMarketplaceInfo();
$proposalMarketplaceInfo->setBuyerAccountId($buyerId);
$proposal->setMarketplaceInfo($proposalMarketplaceInfo);
    

Afficher sur GitHub

C#

// Create a proposal with the minimum required fields.
Proposal proposal = new Proposal()
{
    name = "Programmatic proposal #" + new Random().Next(int.MaxValue),
    // Set required Marketplace information
    marketplaceInfo = new ProposalMarketplaceInfo()
    {
        buyerAccountId = programmaticBuyerId
    }
};
    

Afficher sur GitHub

Ruby

# Create proposal configuration object.
proposal = {
  :marketplace_info => {
    :buyer_account_id => buyer_id
  },
  :name => 'Proposal %s' % SecureRandom.uuid(),
  # ...
}
    

Afficher sur GitHub

Avant d'envoyer le message à l'acheteur pour négociation, vous devez définir des champs supplémentaires. La proposition doit comporter un annonceur, un commercial, un gestionnaire de trafic et des contacts du vendeur.

Java

SalespersonSplit primarySalesperson = new SalespersonSplit();
primarySalesperson.setUserId(primarySalespersonId);
proposal.setPrimarySalesperson(primarySalesperson);
    

Afficher sur GitHub

Python

'primarySalesperson': {
    'userId': primary_salesperson_id,
},
'primaryTraffickerId': primary_trafficker_id,
'probabilityOfClose': '100000',
    

Afficher sur GitHub

PHP

// Create salesperson splits for the primary salesperson.
$primarySalesperson = new SalespersonSplit();
$primarySalesperson->setUserId($primarySalespersonId);
$proposal->setPrimarySalesperson($primarySalesperson);

// Set the primary trafficker on the proposal for when it becomes an
// order.
$proposal->setPrimaryTraffickerId($primaryTraffickerId);

$advertiser = new ProposalCompanyAssociation();
$advertiser->setType(
    ProposalCompanyAssociationType::ADVERTISER
);
$advertiser->setCompanyId($advertiserId);
$proposal->setAdvertiser($advertiser);
    

Afficher sur GitHub

C#

// Set fields that are required before sending the proposal to the buyer.
proposal.primaryTraffickerId = primaryTraffickerId;
proposal.sellerContactIds = new long[] { primarySalespersonId };
proposal.primarySalesperson = new SalespersonSplit()
{
    userId = primarySalespersonId,
};
proposal.advertiser = new ProposalCompanyAssociation()
{
    type = ProposalCompanyAssociationType.ADVERTISER,
    companyId = advertiserId
};
    

Afficher sur GitHub

Ruby

:primary_salesperson => {
  :user_id => primary_salesperson_id
},
:primary_trafficker_id => primary_trafficker_id
    

Afficher sur GitHub

Étant donné que les propositions sont généralement constituées d'objets ProposalLineItem, l'étape suivante consiste à ajouter des éléments de campagne de proposition sous la proposition que vous venez de créer.

États d'une proposition programmatique

La figure suivante représente une proposition programmatique à différents moments du processus de négociation du point de vue de l'API. Chaque état est représenté par différentes combinaisons des champs suivants:

• ProposalMarketplaceInfo.hasLocalVersionEdits
• ProposalMarketplaceInfo.negotiationStatus
• Proposal.status

Pour en savoir plus, consultez le Centre d'aide Ad Manager.

Figure 1: États d'une proposition programmatique

Tutoriel de la négociation

Ici, nous vous expliquons comment utiliser l'API afin de négocier une proposition programmatique avec un acheteur. Nous allons faire référence aux états dans le schéma ci-dessus.

Préparer l'examen ou l'acceptation par l'acheteur

Tout d'abord, vous devez rédiger une proposition programmatique avec des éléments de campagne de proposition que vous souhaitez envoyer à un acheteur. Il s'agit de state C dans la figure ci-dessus.

Demander l'examen ou l'acceptation de l'acheteur

Une fois que vous êtes prêt à demander à l'acheteur d'examiner la proposition programmatique, vous pouvez utiliser la méthode RequestBuyerReview ou RequestBuyerAcceptance à l'aide de la méthode ProposalService.performProposalAction. Vous accédez alors à la phase de négociation.

Négociation

Au cours de cette phase, plusieurs choses peuvent se produire.

• L'acheteur peut accepter votre proposition programmatique sans la modifier.
• L'acheteur peut proposer des modifications. Dans ce cas, la proposition est renvoyée à l'état de brouillon (state B sur la figure 1). Vous devez ensuite ouvrir la proposition pour modification, apporter les modifications proposées, puis la renvoyer pour examen par l'acheteur.
• Vous pouvez également apporter des modifications avant même que l'acheteur ne réponde. Pour ce faire, ouvrez la proposition de modification à partir de state D dans la figure 1.

Remarque :Lorsqu'une proposition programmatique est ouverte en modification (state A sur la figure 1), elle ne reçoit pas automatiquement les mises à jour de la place de marché. Cela signifie que si l'acheteur apporte une modification avant de demander l'accord de l'acheteur, vous recevrez le message d'erreur NEW_VERSION_FROM_BUYER lorsqu'il tentera de demander l'accord de l'acheteur. Pour résoudre ce problème, effectuez l'action DiscardProposalDrafts. Cette action remplacera vos modifications locales par les dernières modifications apportées par l'acheteur sur Marketplace. Vous devrez ensuite appliquer de nouveau les modifications locales.

Cette négociation se poursuit jusqu'à ce que vous parveniez à un accord avec l'acheteur. Les commentaires entre vous et l'acheteur peuvent être récupérés à l'aide de getMarketplaceCommentsByStatement. Vous pouvez envoyer un commentaire à l'acheteur depuis state A. Pour ce faire, vous devez mettre à jour le champ marketplaceComment de la proposition à l'aide de updateProposals. Le commentaire sera ensuite envoyé lorsque vous demanderez l'accord de l'acheteur.

Finalisée

Lorsque l'acheteur et vous avez tous les deux accepté la proposition programmatique, celle-ci passe à l'état finalisé (state F sur la figure 1). Ad Manager crée alors automatiquement des éléments de campagne à partir de cette proposition programmatique.

Dans la plupart des cas, vous en avez terminé avec la proposition programmatique. Toutefois, vous pouvez effectuer deux actions à partir de cet état:

• Vous pouvez rouvrir la proposition programmatique pour la renégocier en modifiant les champs liés à la diffusion de la proposition. Pour ce faire, ouvrez la proposition pour la modifier (state E to A sur la figure 1), apportez les modifications requises, puis demandez l'accord de l'acheteur.
• Vous pouvez apporter des modifications qui ne sont pas liées à la diffusion (par exemple, mettre à jour le nom de la proposition, et appliquer ces modifications dans la campagne Ad Manager et les éléments de campagne créés à partir de cet accord). Pour ce faire, modifiez le state E de la figure 1, puis effectuez l'action UpdateOrderWithSellerData.