本指南概略介紹如何透過 API 使用程式輔助直接交易功能。說明如何建立提案以及如何執行協商。
Primer
程式輔助提案與 Google Ad Manager 訂單類似,當中包含您與買方之間提議交易的廣泛資訊。提案及其委刊項,代表買方向買方提出的廣告空間要約。
如需瞭解詳情,請參閱說明中心。
透過 API 建立提案
如要建立 Proposal
物件,只需要名稱和程式輔助買方。程式輔助買方 ID 可透過 UI 或 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 的角度描述協議過程中各個階段的程式輔助提案。每個狀態都以下列欄位的多種組合表示:
- 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
動作。