このページは Cloud Translation API によって翻訳されました。

プログラマティック

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

Primer

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

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

API 経由で提案を作成する

Proposal オブジェクトの作成に必要なのは、名前とプログラマティック購入者のみです。プログラマティック購入者 ID は、管理画面または 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 の観点から示しています。各状態は、次のフィールドのさまざまな組み合わせで表されます。

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

マーケットプレイスとのやり取りにおけるプログラマティックプロポーザルの状態。 — **図 1**: プログラマティックプロポーザルの状態

交渉のチュートリアル

ここでは、API を使用して購入者とプログラマティックプロポーザルに関する交渉を完了する手順について説明します。上の図で状態を参照しています。

購入者の審査または承認の準備をしています

まず、購入者に送信するプロポーザル広告申込情報を含むプログラマティックプロポーザル広告申込情報の下書きを作成する必要があります。上の図では state C です。

購入者の審査または承認をリクエストする

購入者にプログラマティックプロポーザルを確認する準備ができたら、ProposalService.performProposalAction メソッドを使用して RequestBuyerReview または RequestBuyerAcceptance を実行します。これで交渉の段階に入ります。

交渉

このフェーズでは、さまざまなことが起こる可能性があります。

購入者はプログラマティックプロポーザルを変更せずに承認できます。
購入者が変更を提案できます。この場合、提案は下書きステータス（図 1 の state B）に戻ります。その後、プロポーザルを開いて編集し、提案された変更を行って、購入者の確認のために返送する必要があります。
購入者が返信する前であっても、変更を加えることもできます。そのためには、図 1 の state D から編集用に提案を開きます。

この交渉は、お客様が購入者と合意するまで継続されます。購入者との間のコメントは、getMarketplaceCommentsByStatement を使用して取得できます。state A では購入者にコメントを送信できます。そのためには、updateProposals を使用して、提案の marketplaceComment フィールドを更新します。コメントは、購入者に承認をリクエストすると送信されます。

最終処理済み

パブリッシャーと購入者の両者がプログラマティックプロポーザルを承認すると、そのプロポーザルは確定済み状態になります（図 1 の state F）。アドマネージャーでは、このプログラマティックプロポーザルから広告申込情報が自動的に作成されます。

ほとんどの場合、プログラマティックプロポーザルは完了していますが、この状態から実行できるアクションは次の 2 つです。

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

プログラマティック

Primer

API 経由で提案を作成する

Java

Python

PHP

C#

Ruby

Java

Python

PHP

C#

Ruby

プログラマティック プロポーザルの状態

交渉のチュートリアル

購入者の審査または承認の準備をしています

購入者の審査または承認をリクエストする

交渉

最終処理済み

プログラマティックプロポーザルの状態