Pubblicità programmatica

Questa guida è una panoramica generale su come utilizzare le funzionalità di Programmatic Direct tramite l'API. Descrive come creare una proposta e come eseguire la negoziazione.

Primer

Una proposta programmatica è simile a un ordine in Google Ad Manager. Le proposte programmatiche contengono ampie informazioni su una transazione proposta tra te e un acquirente. Una proposta, insieme ai relativi elementi pubblicitari, rappresenta un'offerta di inventario per un acquirente.

Per ulteriori informazioni, visita il Centro assistenza.

Creare una proposta tramite l'API

Per creare un oggetto Proposal, sono obbligatori solo il nome e l'acquirente di pubblicità programmatica. L'ID acquirente programmatico può essere ottenuto tramite l'interfaccia utente o la tabella 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);
    

Visualizza su 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(),
    # ...
}
    

Visualizza su GitHub

PHP

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

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

Visualizza su 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
    }
};
    

Visualizza su GitHub

Ruby

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

Visualizza su GitHub

Prima dell'invio all'acquirente per la negoziazione, sarà necessario impostare altri campi. La proposta deve avere un inserzionista, un commerciale, un trafficker e un contatto venditore.

Java

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

Visualizza su GitHub

Python

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

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

Visualizza su 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
};
    

Visualizza su GitHub

Ruby

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

Visualizza su GitHub

Poiché le proposte sono generalmente composte da oggetti ProposalLineItem, il passaggio successivo consiste nell'aggiungere gli elementi pubblicitari della proposta sotto la proposta appena creata.

Stati di una proposta programmatica

La figura seguente illustra una proposta programmatica in vari punti del processo di negoziazione dal punto di vista dell'API. Ogni stato è rappresentato da varie combinazioni dei seguenti campi:

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

Per ulteriori informazioni, visita il Centro assistenza Ad Manager.

Figura 1: stati di una proposta programmatica

Procedura dettagliata per la negoziazione

In questo articolo illustreremo l'utilizzo dell'API per completare una negoziazione per una proposta programmatica con un acquirente. Faremo riferimento agli stati nel diagramma sopra.

Preparazione per la revisione o l'accettazione dell'acquirente

Innanzitutto, devi creare una bozza di proposta programmatica con gli elementi pubblicitari della proposta che vuoi inviare a un acquirente. state C nella figura precedente.

Richiesta di revisione o accettazione dell'acquirente

Quando è tutto pronto per far esaminare la proposta programmatica all'acquirente, puoi RequestBuyerReview o RequestBuyerAcceptance utilizzando il metodo ProposalService.performProposalAction. Accederai così alla fase di negoziazione.

Negoziazione

In questa fase, possono verificarsi diverse situazioni.

• L'acquirente può accettare la tua proposta programmatica senza modifiche.
• L'acquirente può proporre modifiche. In questo caso, la proposta verrà rinviata a uno stato di bozza (state B nella Figura 1). Devi quindi aprire la proposta per la modifica, apportare le modifiche proposte e inviarla nuovamente all'acquirente per la revisione.
• Puoi anche decidere di apportare modifiche anche prima che l'acquirente risponda. Per farlo, apri la proposta di modifica da state D nella Figura 1.

Nota: quando una proposta di pubblicità programmatica è aperta per la modifica (state A nella Figura 1), non riceverà automaticamente aggiornamenti da Marketplace. Ciò significa che se l'acquirente apporta una modifica prima che tu richieda l'accettazione dell'acquirente, riceverai il messaggio di errore NEW_VERSION_FROM_BUYER quando cerchi di richiedere l'accettazione dell'acquirente. Per risolvere il problema, esegui l'azione DiscardProposalDrafts che sovrascriverà le modifiche locali con le ultime modifiche apportate dall'acquirente a Marketplace. Dovrai quindi applicare di nuovo le modifiche locali.

Questa negoziazione continua fino a quando non raggiungi un accordo con l'acquirente. I commenti tra te e l'acquirente possono essere recuperati utilizzando getMarketplaceCommentsByStatement. Puoi inviare un commento all'acquirente mentre sei nella pagina state A. A questo scopo, devi aggiornare il campo marketplaceComment della proposta utilizzando updateProposals. Il commento verrà inviato quando richiedi l'accettazione dell'acquirente.

Finalizzata

Quando sia tu che l'acquirente avete accettato la proposta programmatica, la proposta diventa finalizzata (state F nella Figura 1). Ad Manager crea quindi automaticamente gli elementi pubblicitari da questa proposta programmatica.

Nella maggior parte dei casi hai finito con la proposta programmatica; tuttavia, puoi eseguire due azioni da questo stato:

• Puoi riaprire la proposta programmatica per la rinegoziazione modificando i campi correlati alla pubblicazione della proposta. Per farlo, apri la proposta per la modifica (state E to A nella Figura 1), apporta le modifiche e poi richiedi l'accettazione dell'acquirente.
• Puoi apportare modifiche che non generano traffico, ad esempio aggiornare il nome della proposta e riflettere queste modifiche nell'ordine Ad Manager e negli elementi pubblicitari creati da questo deal. Per farlo, modifica il campo state E nella Figura 1 ed esegui l'azione UpdateOrderWithSellerData.