程式輔助

本指南概略介紹如何透過 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);
    

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

前往 GitHub 查看

PHP

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

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

前往 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
    }
};
    

前往 GitHub 查看

Ruby

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

前往 GitHub 查看

您必須先設定其他欄位，才能傳送給買方進行協商。 提案必須包含廣告主、銷售專員、廣告投放專員和賣方聯絡人。

Java

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

前往 GitHub 查看

Python

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

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

前往 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
};
    

前往 GitHub 查看

Ruby

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

前往 GitHub 查看

由於提案通常包含 ProposalLineItem 物件，因此下一步是在新建立的提案底下新增提案委刊項。

程式輔助提案的狀態

下圖以 API 的角度描述協議過程中各個階段的程式輔助提案。每個狀態都以下列欄位的多種組合表示：

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

詳情請參閱 Ad Manager 說明中心。

圖 1：程式輔助提案的狀態

協商逐步操作說明

以下說明如何運用 API，與買方完成程式輔助提案的協商。我們會參考上圖中的狀態。

正在準備買方審查或接受程序

首先，您需要根據要傳送給買方的提案委刊項撰寫程式輔助提案草稿。這是上圖中的 state C。

要求買方審查或接受

準備好讓買方審查程式輔助提案後，您就可以使用 ProposalService.performProposalAction 方法 RequestBuyerReview 或 RequestBuyerAcceptance。這樣就會進入協商階段。

協商

這個階段可能會發生諸多事。

• 買方可能不須進行任何變更，即可接受您的程式輔助提案。
• 買方可能會提議變更。在這種情況下，提案將傳回草稿狀態 (圖 1 中的 state B)。接著，您需要開啟提案以便進行編輯，進行提議的變更並回傳給我們，以供買方審核。
• 您也可以在買方回應之前修改。方法是在圖 1 開啟 state D 中的提案開啟編輯。

注意： 當程式輔助提案開放編輯時 (圖 1 中的 state A)，並不會自動接收來自 Marketplace 的更新。這表示如果買方在您要求買家接受之前進行變更，您會在嘗試要求買家接受時收到 NEW_VERSION_FROM_BUYER 錯誤訊息。如要修正這個問題，請執行「CancelProposalDrafts」DiscardProposalDrafts動作，以便使用 Marketplace 最新的買家變更內容覆寫您的本機編輯內容。屆時您必須重新套用本機編輯內容。

這個協商會持續到您與買方達成協議為止。您可以使用 getMarketplaceCommentsByStatement 擷取您與買家之間的評論。您可以在 state A 中留言給買方。如要這麼做，您必須使用 updateProposals 更新提案的 marketplaceComment 欄位。當您要求買方接受時，系統就會傳送留言。

己完成

您和買方都接受程式輔助提案後，提案就會進入最終狀態 (圖 1 中的 state F)。接著，Ad Manager 會自動根據這個程式輔助提案建立委刊項。

在多數情況下，您已經完成程式輔助提案；但是，從這個狀態可以執行兩項操作：

• 您可以編輯提案中的放送相關欄位，重新開啟程式輔助提案來重新協商。方法是開啟要編輯的提案 (圖 1 中的 state E to A)、進行變更，然後要求買方接受。
• 您可以編輯與放送無關的相關編輯內容 (例如更新提案名稱)，並在透過這筆交易建立的 Ad Manager 訂單和委刊項中反映這些變更。方法是編輯圖 1 中的 state E，然後執行 UpdateOrderWithSellerData 動作。