程式輔助

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

前往 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 查看

小茹

# 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 查看

小茹

: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)，不會自動接收市集的更新。也就是說，如果買家在您要求接受前進行變更，您在要求買家接受時，會收到 NEW_VERSION_FROM_BUYER 錯誤訊息。如要修正這個問題，請執行 DiscardProposalDrafts 動作，系統會以市集中的最新買家變更覆寫本機編輯內容。接著，您需要重新套用本機編輯內容。

協商會持續進行，直到您與買方達成協議。您與買家之間的留言可透過 getMarketplaceCommentsByStatement 擷取。在state A狀態下，您可以傳送註解給買方。如要這麼做，您必須使用 updateProposals 更新提案的 marketplaceComment 欄位。當您要求買家接受提案時，系統就會傳送這則留言。

己完成

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

在大多數情況下，您現在已完成程式輔助提案；不過，您可以在這個狀態下執行兩項操作：

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