プログラマティック

このガイドでは、API を介してプログラマティック直接取引機能を使用する方法の概要を説明します。ここでは、プロポーザルを作成する方法と、交渉を行う方法について説明します。

Primer

プログラマティック プロポーザルは、Google アド マネージャーのオーダーと似ています。プログラマティック プロポーザルには、お客様と購入者との間で提案された取引に関する広範な情報が含まれています。プロポーザルは、広告申込情報とともに、購入者への広告枠のオファーを表します。

詳しくは、ヘルプセンターをご覧ください。

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

詳しくは、アド マネージャー ヘルプセンターをご覧ください。

図 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）。アド マネージャーでは、このプログラマティック プロポーザルから広告申込情報が自動的に作成されます。

ほとんどの場合、プログラマティック取引の提案はこれで完了です。ただし、この状態から次の 2 つの操作を行うことができます。

• プロポーザルの配信関連のフィールドを編集することで、プログラマティック プロポーザルを再交渉のために再度開くことができます。これを行うには、編集するプロポーザルを開き（図 1 の state E to A）、変更を加えてから、購入者の承認をリクエストします。
• プロポーザル名の更新など、配信に関連しない編集を行い、この取引から作成されたアド マネージャーのオーダーと広告申込情報にこれらの変更を反映できます。これを行うには、図 1 の state E を編集してから、UpdateOrderWithSellerData アクションを実行します。