Programática

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

Primer

Uma proposta programática é semelhante a um pedido no Google Ad Manager. Propostas programáticas conter informações abrangentes sobre uma transação proposta entre você e um comprador. Uma proposta, junto com seus itens de linha, representa uma oferta de inventário para um por um comprador.

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

Criação de uma proposta por meio da API

Para criar um objeto Proposal, somente o nome e o comprador programático são obrigatórios. O ID do comprador programático pode ser encontrado na interface ou Programmatic_Buyer na tabela PQL.

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

Ver no 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(),
    # ...
}
    

Ver no GitHub

PHP

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

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

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

Ver no GitHub

Ruby

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

Ver no GitHub

Antes de enviar ao comprador para negociação, campos adicionais precisam ser definidos. A proposta deve ter os contatos de anunciante, vendedor, coordenador de publicidade e vendedor.

Java

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

Ver no GitHub

Python

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

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

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

Ver no GitHub

Ruby

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

Ver no GitHub

Como as propostas geralmente são compostas por ProposalLineItem objetos, a próxima etapa seria adicionar itens de linha da proposta abaixo do seu objeto proposta 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 de APIs. 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.

Figura 1: estados de uma proposta programática

Tutorial da negociação

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

Como se preparar para a revisão ou aceitação do comprador

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

Solicitação de análise ou aceitação do comprador

Quando estiver tudo pronto para que o comprador analise a proposta programática, use RequestBuyerReview ou RequestBuyerAcceptance usando o método ProposalService.performProposalAction. Isso o levará para a fase de negociação.

Negociação

Nesta fase, várias coisas podem acontecer.

• O comprador pode aceitar sua proposta programática sem mudanças.
• 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, você vai precisar abrir a proposta para edição, fazer as mudanças propostas e enviar de volta para a revisão do comprador.
• Também é possível fazer mudanças antes de o comprador responder. Você pode faça isso abrindo a proposta para edição de state D na Figura 1.

.

Observação :quando uma proposta programática está aberta para edição (state A na Figura 1), ele não receberá atualizações do Marketplace automaticamente. Isso significa que, fizer uma alteração antes de solicitar a aceitação do comprador, você receberá o mensagem de erro NEW_VERSION_FROM_BUYER ao tentar solicitar a aceitação do comprador. Para corrigir isso, execute a ação DiscardProposalDrafts, que substituirá suas edições locais pelas alterações mais recentes do comprador, de Google Marketplace. Em seguida, você terá que aplicar novamente as edições locais.

A negociação continua até chegar a um acordo com o comprador. Comentários entre você e o comprador podem ser recuperadas usando getMarketplaceCommentsByStatement. Você pode enviar um comentário para o comprador enquanto estiver em state A. Afazeres você vai precisar atualizar marketplaceComment na proposta usando updateProposals. O comentário será enviado quando você solicitar a aceitação do comprador.

Finalizada

Quando você e o comprador aceitarem a proposta programática, entra em um estado finalizado (state F na Figura 1). Depois disso, o Ad Manager cria automaticamente itens de linha com base nessa proposta programática.

Na maioria dos casos, você já terminou a proposta programática. No entanto, há duas ações que podem ser realizadas a partir desse estado:

• Para reabrir a proposta programática para renegociação, edite campos relacionados à veiculação na proposta. Você pode fazer isso abrindo o proposta para edição (state E to A na Figura 1), fazendo alterações e solicitando a aceitação do comprador.
• É possível fazer edições não relacionadas à veiculação, como atualizar o e refletindo essas alterações no pedido do Ad Manager e nos itens de linha criados a partir desta transação. Para fazer isso, edite o state E na Figura 1 e, em seguida, execute a ação UpdateOrderWithSellerData.