Programmatico

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 di pubblicità programmatica è simile a un ordine in Google Ad Manager. Le proposte di pubblicità programmatica contengono informazioni generali 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 saperne di più, consulta il Centro assistenza.

Creazione di una proposta tramite l'API

Per creare un oggetto Proposal, sono obbligatori solo il nome e l'acquirente programmatico. L'ID acquirente programmatico può essere ottenuto tramite la UI 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);

Python

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

PHP

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

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

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

Ruby

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

Prima di inviare la proposta all'acquirente per la negoziazione, è necessario impostare campi aggiuntivi. La proposta deve includere un inserzionista, un commerciale, un trafficker e i contatti del venditore.

Java

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

Python

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

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

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

Ruby

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

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

Stati di una proposta di pubblicità programmatica

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

Per saperne di più, consulta il Centro assistenza Ad Manager.

Gli stati in cui può trovarsi una proposta di pubblicità programmatica durante la sua interazione con Marketplace.
Figura 1: stati di una proposta di pubblicità programmatica

Procedura dettagliata per la negoziazione

Di seguito, ti spiegheremo come utilizzare l'API per completare una negoziazione per una proposta di pubblicità programmatica con un acquirente. Faremo riferimento agli stati nel diagramma precedente.

Preparazione per la revisione o l'accettazione da parte dell'acquirente

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

Richiesta di revisione o accettazione da parte dell'acquirente

Quando vuoi che l'acquirente esamini la proposta di pubblicità programmatica, puoi RequestBuyerReview o RequestBuyerAcceptance utilizzando il metodo ProposalService.performProposalAction. In questo modo, entrerai nella fase di negoziazione.

Negoziazione

In questa fase possono verificarsi diversi eventi.

  • L'acquirente può accettare la tua proposta di pubblicità programmatica senza modifiche.
  • L'acquirente può proporre modifiche. In questo caso, la proposta verrà riportata allo stato di bozza (state B nella Figura 1). Dovrai quindi aprire la proposta per la modifica, apportare le modifiche proposte e inviarla nuovamente per la revisione dell'acquirente.
  • Puoi anche decidere di apportare modifiche prima che l'acquirente risponda. A questo scopo, apri la proposta per modificarla da state D nella Figura 1.

Questa negoziazione continua finché 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 in state A. Per farlo, devi aggiornare il campo marketplaceComment della proposta utilizzando updateProposals. Il commento verrà inviato quando richiedi l'accettazione dell'acquirente.

Finalizzata

Quando sia tu sia l'acquirente avete accettato la proposta di pubblicità programmatica, questa passa allo stato finalizzato (state F nella Figura 1). Ad Manager crea quindi automaticamente gli elementi pubblicitari da questa proposta di pubblicità programmatica.

Nella maggior parte dei casi, la proposta programmatica è ora completata. Tuttavia, da questo stato puoi eseguire due azioni:

  • Puoi riaprire la proposta di pubblicità programmatica per rinegoziarla modificando i campi relativi alla pubblicazione nella proposta. Per farlo, apri la proposta per modificarla (state E to A nella Figura 1), apporta le modifiche e poi richiedi l'accettazione dell'acquirente.
  • Puoi apportare modifiche non pubblicate, ad esempio aggiornare il nome della proposta e applicare queste modifiche all'ordine e agli elementi pubblicitari di Ad Manager creati da questo deal. Per farlo, modifica il valore da state E nella Figura 1, quindi esegui l'azione UpdateOrderWithSellerData.