本指南简要介绍了如何通过 API 使用程序化直接交易功能。其中说明了如何创建提案以及如何执行协商。
Primer
程序化提案类似于 Google Ad Manager 中的订单。程序化提案包含您和买方之间有关一个提议的交易的各种信息。 提案及其订单项代表着向买方发出的广告资源报价。
如需了解详情,请参阅帮助中心。
通过 API 创建提案
如需创建 Proposal
对象,您只需提供名称和程序化交易买方。您可以通过界面或 Programmatic_Buyer
PQL 表格获取程序化交易买方 ID。
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 的角度描述了程序化提案在协商过程中的各个时间点。每种状态均由以下字段的各种组合表示:
- ProposalMarketplaceInfo.hasLocalVersionEdits
- ProposalMarketplaceInfo.negotiationStatus
- Proposal.status
如需了解详情,请参阅 Ad Manager 帮助中心。
协商演示
在这里,我们将逐步介绍如何使用 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
操作。