Programática

Este guia é uma visão geral de alto nível de como usar os recursos do Programmatic Direct pela API. Ele descreve como criar uma proposta e realizar uma negociação.

Primer

Uma proposta programática é semelhante a um pedido de veiculação no Google Ad Manager. As propostas programáticas contêm informações gerais sobre uma transação proposta entre você e um comprador. Uma proposta, junto com os itens de linha, representa uma oferta de inventário para um comprador.

Para mais informações, consulte a Central de Ajuda.

Como criar uma proposta usando a API

Para criar um objeto Proposal, apenas o nome e o comprador programático são obrigatórios. O ID do comprador programático pode ser obtido na interface ou na tabela 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(),
  # ...
}
    

Antes de enviar ao comprador para negociação, outros campos precisam ser definidos. A proposta precisa ter um anunciante, um vendedor, um coordenador de publicidade e contatos do vendedor.

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
    

Como as propostas geralmente são compostas de objetos ProposalLineItem, a próxima etapa é adicionar itens de linha abaixo da proposta recém-criada.

Estados de uma proposta programática

A figura a seguir mostra uma proposta programática em vários pontos durante o processo de negociação do ponto de vista da API. Cada estado é representado por várias combinações dos seguintes campos:

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

Para mais informações, consulte a Central de Ajuda do Ad Manager.

Tutorial de negociação

Aqui, vamos mostrar como usar a API para concluir uma negociação de uma proposta programática com um comprador. Vamos fazer referência aos estados no diagrama acima.

Preparação para revisão ou aceitação do comprador

Primeiro, você precisa criar um rascunho de uma proposta programática com itens de linha que quer enviar a um comprador. Esse é o state C na figura acima.

Solicitar revisão ou aceitação do comprador

Quando estiver tudo pronto para o comprador analisar a proposta programática, você poderá RequestBuyerReview ou RequestBuyerAcceptance usando o método ProposalService.performProposalAction. Isso vai levar você à fase de negociação.

Negociação

Nessa fase, várias coisas podem acontecer.

• O comprador pode aceitar sua proposta programática sem alterações.
• O comprador pode propor mudanças. Nesse caso, a proposta será enviada de volta para um estado de rascunho (state B na Figura 1). Em seguida, abra a proposta para edição, faça as mudanças sugeridas e envie de volta para revisão do comprador.
• Você também pode fazer mudanças antes mesmo de o comprador responder. Para isso, abra a proposta para edição em state D na Figura 1.

Essa negociação continua até que você chegue a um acordo com o comprador. Os comentários entre você e o comprador podem ser recuperados usando getMarketplaceCommentsByStatement. Você pode enviar um comentário ao comprador enquanto estiver em state A. Para fazer isso, atualize o campo marketplaceComment na proposta usando updateProposals. O comentário será enviado quando você pedir a aceitação do comprador.

Finalizada

Quando você e o comprador aceitam a proposta programática, ela passa para o estado finalizado (state F na Figura 1). Em seguida, o Ad Manager cria automaticamente itens de linha com base nessa proposta programática.

Na maioria dos casos, a proposta programática está concluída. No entanto, há duas ações que você pode realizar nesse estado:

• Para reabrir a proposta programática para renegociação, edite os campos relacionados à veiculação. Para isso, abra a proposta para edição (state E to A na Figura 1), faça as mudanças e peça a aceitação do comprador.
• É possível fazer edições não veiculadas, como atualizar o nome da proposta e refletir essas mudanças no pedido e nos itens de linha do Ad Manager criados com base nessa transação. Para isso, edite o state E da Figura 1 e execute a ação UpdateOrderWithSellerData.