Programmatique

Ce guide présente de manière générale comment utiliser les fonctionnalités Programmatic Direct via l'API. Il explique 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 transaction proposée entre vous et un acheteur. Une proposition, ainsi que ses éléments de campagne, représente une offre d'inventaire à un acheteur.

Pour en savoir plus, 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 obligatoires. Vous pouvez obtenir l'ID d'acheteur programmatique dans l'UI ou dans la table PQL Programmatic_Buyer.

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

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

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

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

// 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
    }
};
    

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

Avant d'envoyer la proposition à l'acheteur pour négociation, vous devrez définir des champs supplémentaires. La proposition doit comporter un annonceur, un commercial, un trafficker et des contacts du vendeur.

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

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

// 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);
    

// 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
};
    

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

Étant donné que les propositions sont généralement composé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.

Tutoriel sur la négociation

Nous allons vous expliquer comment utiliser l'API pour finaliser la négociation d'une proposition programmatique avec un acheteur. Nous ferons référence aux états dans le diagramme ci-dessus.

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

Tout d'abord, vous devez rédiger une proposition programmatique avec les é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

Lorsque vous êtes prêt à ce que l'acheteur examine la proposition programmatique, vous pouvez RequestBuyerReview ou RequestBuyerAcceptance à l'aide de la méthode ProposalService.performProposalAction. Vous serez alors redirigé vers la phase de négociation.

Négociation

Lors de cette phase, plusieurs événements peuvent se produire.

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

Cette négociation se poursuit jusqu'à ce que vous trouviez un accord avec l'acheteur. Vous pouvez récupérer les commentaires échangés entre vous et l'acheteur à l'aide de getMarketplaceCommentsByStatement. Vous pouvez envoyer un commentaire à l'acheteur dans state A. Pour ce faire, vous devrez mettre à jour le champ marketplaceComment de la proposition à l'aide de updateProposals. Le commentaire sera ensuite envoyé lorsque vous demanderez l'acceptation de l'acheteur.

Finalisée

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

Dans la plupart des cas, vous avez terminé de configurer 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. Pour ce faire, ouvrez la proposition à modifier (state E to A dans la figure 1), apportez les modifications, puis demandez l'acceptation de l'acheteur.
• Vous pouvez apporter des modifications n'entraînant aucune diffusion, comme modifier le nom de la proposition et refléter ces changements dans la commande et les éléments de campagne Ad Manager créés à partir de cet accord. Pour ce faire, modifiez le state E de la figure 1, puis effectuez l'action UpdateOrderWithSellerData.