程式輔助

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

小茹

# 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
};

小茹

: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 動作。