程序化

本指南简要介绍了如何通过 API 使用程序化直投功能。它介绍了如何创建提案以及如何执行协商。

Primer

程序化提案与 Google Ad Manager 中的订单类似。程序化提案包含您与买方之间拟进行的交易的广泛信息。 提案及其订单项共同代表向买方提供的广告资源。

如需了解详情，请访问帮助中心。

通过 API 创建提案

如需创建 Proposal 对象，只需提供名称和程序化买方。程序化买方 ID 可通过界面或 Programmatic_Buyer 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);

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

在将提案发送给买家以供协商之前，您需要设置其他字段。 提案必须包含广告客户、销售人员、广告投放人员和卖方联系人。

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

由于提案通常由 ProposalLineItem 对象组成，因此下一步是在新创建的提案下添加提案订单项。

程序化提案的状态

下图从 API 的角度描绘了协商流程中各个阶段的程序化提案。每个状态都由以下字段的各种组合表示：

如需了解详情，请访问 Ad Manager 帮助中心。

程序化提案在与“市场”互动期间可能处于的状态。
图 1：程序化提案的状态

协商演练

下面，我们将引导您使用该 API 完成与买方就程序化提案进行的协商。我们将参考上图中的状态。

准备提交买方审核或接受

首先，您需要起草一份程序化提案，其中包含您要发送给买方的提案订单项。在上图中，这是 state C。

请求买方审核或接受

准备好让买方审核程序化提案后，您可以使用 ProposalService.performProposalAction 方法来执行 RequestBuyerReview 或 RequestBuyerAcceptance 操作。 这样一来，您就进入了协商阶段。

协商

在此阶段，可能会发生以下情况。

  • 买方可能会接受您的程序化提案，而不会进行任何更改。
  • 买方可能会提出更改建议。在这种情况下，提案将返回到草稿状态（图 1 中的 state B）。然后，您需要打开提案以进行修改，做出建议的更改，然后将其发回给买方以供审核。
  • 您也可以在买家回复之前决定进行更改。您可以打开图 1 中 state D 处的提案进行修改。

此协商会一直持续，直到您与买方达成协议。您可以使用 getMarketplaceCommentsByStatement 检索您与买家之间的评论。在 state A 期间，您可以向买方发送评论。为此，您需要使用 updateProposals 更新提案中的 marketplaceComment 字段。 当您请求买方接受提案时，系统会发送该评论。

已完成

当您和买方都接受程序化提案后，提案会进入最终确定状态（图 1 中的 state F）。 然后，Ad Manager 会根据此程序化提案自动创建订单项。

在大多数情况下，您现在已完成程序化提案；不过，您可以在此状态下执行两项操作：

  • 您可以修改提案中与投放相关的字段，重新打开程序化提案以进行重新协商。为此，您可以打开建议进行修改（图 1 中的 state E to A），进行更改，然后请求买方接受。
  • 您可以进行与投放无关的修改，例如更新提案的名称，并在根据相应交易创建的 Ad Manager 订单和订单项中反映这些更改。为此，请修改图 1 中的 state E，然后执行 UpdateOrderWithSellerData 操作。