このガイドでは、プロポーザルの概要、API を使って Proposal オブジェクトを作成する手順、プロポーザルの作成後にできることについて説明します。
はじめに
DFP セールス マネージャのプロポーザルとは、DFP での入稿に進む前の段階で存在している機会を形として表したものです。プロポーザルでは、オーダーの請求に関する情報として、取引に割り当てられる予算、プロセスを管理する営業担当者と入稿担当者、プロポーザル広告申込情報の形態で販売される広告枠といった内容を指定します。
API を使ってプロポーザルを作成する
Proposal オブジェクトを作成するのに必要なフィールドは名前のみです。
Java
// Get the ProposalService.
ProposalServiceInterface proposalService =
dfpServices.get(session, ProposalServiceInterface.class);
// Create a proposal.
Proposal proposal = new Proposal();
proposal.setName("Proposal #" + new Random().nextInt(Integer.MAX_VALUE));
Python
# Initialize appropriate services.
proposal_service = client.GetService('ProposalService', version='v201805')
# Create proposal objects.
proposal = {
'name': 'Proposal #%s' % uuid.uuid4(),
...
PHP
$proposalService = $serviceFactory->createProposalService($session);
// Create a proposal.
$proposal = new Proposal();
$proposal->setName('Proposal #' . uniqid());
C#
using (ProposalService proposalService =
(ProposalService) user.GetService(DfpService.v201805.ProposalService))
// Create a proposal.
Proposal proposal = new Proposal();
proposal.name = "Proposal #" + new Random().Next(int.MaxValue);
残りの設定フィールドは、販売計画チームが後から入力できます。入稿に必要なフィールドへの入力が送信前に終わっている場合は、プロポーザルの作業を少しずつ進めることができます。送信に最低限必要なフィールドは、プロポーザルと広告主の関連付けです。
Java
// Create a proposal company association.
ProposalCompanyAssociation proposalCompanyAssociation = new ProposalCompanyAssociation();
proposalCompanyAssociation.setCompanyId(advertiserId);
proposalCompanyAssociation.setType(ProposalCompanyAssociationType.ADVERTISER);
proposal.setAdvertiser(proposalCompanyAssociation);
Python
...
'advertiser': {
'companyId': advertiser_id,
'type': 'ADVERTISER'
},
...
PHP
// Create a proposal company association.
$proposalCompanyAssociation = new ProposalCompanyAssociation();
$proposalCompanyAssociation->setCompanyId($advertiserId);
$proposalCompanyAssociation->setType(ProposalCompanyAssociationType::ADVERTISER);
$proposal->setAdvertiser($proposalCompanyAssociation);
C#
// Create a proposal company association.
ProposalCompanyAssociation proposalCompanyAssociation = new ProposalCompanyAssociation();
proposalCompanyAssociation.companyId = advertiserId;
proposalCompanyAssociation.type = ProposalCompanyAssociationType.ADVERTISER;
proposal.advertiser = proposalCompanyAssociation;
プロポーザルに関連付けられる会社に連絡先を追加する必要がある場合は、proposalCompanyAssociation オブジェクトに ID のリストを設定します。
Java
proposalCompanyAssociation.setContactIds(new long[] {INSERT_YOUR_LIST_OF_CONTACTS_HERE});
proposal.setAdvertiser(proposalCompanyAssociation);
Python
...
'advertiser': {
'companyId': advertiser_id,
'type': 'ADVERTISER',
'contactIds': [INSERT_YOUR_LIST_OF_CONTACTS_HERE]
},
...
PHP
$proposalCompanyAssociation->contactIds = array(INSERT_YOUR_LIST_OF_CONTACTS_HERE);
$proposal->advertiser = $proposalCompanyAssociation;
C#
proposalCompanyAssociation.contactIds = new long[] {INSERT_YOUR_LIST_OF_CONTACTS_HERE};
proposal.advertiser = proposalCompanyAssociation;
DFP への送信前に、メインの営業担当者を設定する必要があります。副営業担当者は省略できます。営業担当者を割り当てるには SalespersonSplit オブジェクトを作成し、営業担当者のユーザー ID と配分の割合（%）を設定します。副営業担当者の設定についても同様です。この設定が終わったら、SalespersonSplit オブジェクトを使ってメインの営業担当者と副営業担当者をプロポーザルに直接関連付けます。
Java
// Create salesperson splits for the primary salesperson and secondary salespeople.
SalespersonSplit primarySalesperson = new SalespersonSplit();
primarySalesperson.setUserId(primarySalespersonId);
primarySalesperson.setSplit(75000);
proposal.setPrimarySalesperson(primarySalesperson);
SalespersonSplit secondarySalesperson = new SalespersonSplit();
secondarySalesperson.setUserId(secondarySalespersonId);
secondarySalesperson.setSplit(25000);
proposal.setSecondarySalespeople(new SalespersonSplit[] {secondarySalesperson});
Python
...
'primarySalesperson': {
'userId': primary_salesperson_id,
'split': '75000'
},
'secondarySalespeople': [{
'userId': secondary_salesperson_id,
'split': '25000'
}],
...
PHP
// Create salesperson splits for the primary salesperson and secondary
// salespeople.
$primarySalesperson = new SalespersonSplit();
$primarySalesperson->setUserId($primarySalespersonId);
$primarySalesperson->setSplit(75000);
$proposal->setPrimarySalesperson($primarySalesperson);
$secondarySalesperson = new SalespersonSplit();
$secondarySalesperson->setUserId($secondarySalespersonId);
$secondarySalesperson->setSplit(25000);
$proposal->setSecondarySalespeople([$secondarySalesperson]);
C#
// Create salesperson splits for the primary salesperson and secondary salespeople.
SalespersonSplit primarySalesperson = new SalespersonSplit();
primarySalesperson.userId = primarySalespersonId;
primarySalesperson.split = 75000;
proposal.primarySalesperson = primarySalesperson;
SalespersonSplit secondarySalesperson = new SalespersonSplit();
secondarySalesperson.userId = secondarySalespersonId;
secondarySalesperson.split = 25000;
proposal.secondarySalespeople = new SalespersonSplit[] { secondarySalesperson };
Proposal オブジェクトには probabilityOfClose() フィールドも含まれます。ここにはミリパーセントの値を入力します。このフィールドはレポートでの収益計算やワークフローでの確認に使用します。
Java
// Set the probability to close to 100%.
proposal.setProbabilityOfClose(100000L);
Python
...
'probabilityOfClose': '100000',
...
PHP
// Set the probability to close to 100%.
$proposal->setProbabilityOfClose(100000);
C#
// Set the probability to close to 100%.
proposal.probabilityOfClose = 100000L;
プロポーザルを送信するには、メインの広告担当者を設定する必要があります。
Java
// Set the primary trafficker on the proposal for when it becomes an order.
proposal.setPrimaryTraffickerId(primaryTraffickerId);
Python
...
'primaryTraffickerId': primary_trafficker_id,
...
PHP
// Set the primary trafficker on the proposal for when it becomes an order.
$proposal->setPrimaryTraffickerId($primaryTraffickerId);
C#
// Set the primary trafficker on the proposal for when it becomes an order.
proposal.primaryTraffickerId = primaryTraffickerId;
プロポーザルには予算も割り当てる必要があります。それには Money オブジェクトを作成し、マイクロ単位の金額と通貨コードを指定します。通貨コードは必須で、プロポーザルの設定で使用されている通貨と一致する必要があります。
Java
// Create a budget for the proposal worth 100 in the network local currency.
Money budget = new Money();
budget.setMicroAmount(100000000L);
budget.setCurrencyCode(networkService.getCurrentNetwork().getCurrencyCode());
proposal.setBudget(budget);
Python
...
'budget': {
'microAmount': '100000000',
'currencyCode': network_service.getCurrentNetwork()['currencyCode']
},
...
PHP
// Create a budget for the proposal worth 100 in the network local currency.
$budget = new Money();
$budget->setMicroAmount(100000000);
$budget->setCurrencyCode(
$networkService->getCurrentNetwork()
->getCurrencyCode()
);
$proposal->setBudget($budget);
C#
// Create a budget for the proposal worth 100 in the network local currency.
Money budget = new Money();
budget.microAmount = 100000000L;
budget.currencyCode = networkService.getCurrentNetwork().currencyCode;
proposal.budget = budget;
請求のフィールドでは、配信済みインプレッションの請求方法と、請求計算の際にどの配信数を使用するかを指定します。いずれも省略可能で、省略した場合はデフォルト値が使用されます。
Java
proposal.setBillingCap(BillingCap.CAPPED_CUMULATIVE);
proposal.setBillingSource(BillingSource.DFP_VOLUME);
Python
...
'billingCap': 'CAPPED_CUMULATIVE',
'billingSource': 'DFP_VOLUME'
...
PHP
$proposal->setBillingCap(BillingCap::CAPPED_CUMULATIVE);
$proposal->setBillingSource(BillingSource::DFP_VOLUME);
C#
proposal.billingCap = BillingCap.CAPPED_CUMULATIVE;
proposal.billingSource = BillingSource.DFP_VOLUME;
これらのフィールドを設定した後、プロポーザル オブジェクトの配列で createProposals を呼び出すと、新しい Proposal オブジェクトが作成されます。
Java
// Create the proposal on the server.
Proposal[] proposals = proposalService.createProposals(new Proposal[] {proposal});
Python
# Add proposals.
proposals = proposal_service.createProposals([proposal])
PHP
// Create the proposals on the server.
$proposals = $proposalService->createProposals([$proposal]);
C#
// Create the proposal on the server.
Proposal[] proposals = proposalService.createProposals(new Proposal[] { proposal });
通常、プロポーザルは ProposalLineItem オブジェクトで構成されます。そのため、新しいプロポーザルを作成したら、次はその下にプロポーザル広告申込情報を追加します。広告申込情報の追加が終わったら、プロポーザルを承認に向けて送信します。
プログラマティック
プログラマティック プロポーザルは、購入者とのやり取りを行う場です。購入者を指定するには、ProposalMarketplaceInfo.buyerAccountId フィールドを設定します。有効な購入者 ID を取得するには Programmatic_Buyer PQL テーブルを使用してください。ProposalMarketplaceInfo の他のフィールドはほとんどが読み取り専用で、プログラマティック プロポーザルの状態や適用可能なアクションを特定する目的で使用します。
プログラマティック プロポーザルの状態
プログラマティック プロポーザルが経過する各状態は、販売管理を使用している場合とそうでない場合とで少し異なります。販売管理を使用している場合と販売管理を使用していない場合のプログラマティック プロポーザルの各状態について、DFP ヘルプセンターで概要をご確認ください。
次の図は、API の観点から、交渉中のさまざまな時点におけるプログラマティック プロポーザルを示したものです。個々の状態は、次のフィールドの組み合わせで表されます。
- ProposalMarketplaceInfo.hasLocalVersionEdits
- ProposalMarketplaceInfo.negotiationStatus
- Proposal.status
交渉の流れ
ここでは、API を使って購入者とのプログラマティック プロポーザルの交渉を完了させるまでの流れについて、上の図で示す個々の状態も引用しながら説明します。
購入者の承認に向けて準備する
販売管理を使用している場合もそうでない場合も、まず購入者に送信するプログラマティック プロポーザルの下書きを作成し、プロポーザル広告申込情報を設定する必要があります。これは上の図 1、2 の state C に該当します。
販売管理を使用していない場合は、購入者に承認をリクエストするステップに進みます。販売管理を使用している場合は、プロポーザルに関連付けられた内部ワークフローを通過する必要があります（図 1 の state C to D）。これを行うには SubmitProposalsForApproval を呼び出します。
購入者に承認をリクエストする
購入者にプログラマティック プロポーザルを確認してもらう準備が整ったら、RequestBuyerAcceptance アクションを使って購入者に承認をリクエストします。そうすると、プロポーザルは交渉段階に入ります。
プロポーザルについて交渉する
この段階では、次のようにさまざまなシナリオが想定されます。
- 購入者がプログラマティック プロポーザルをそのまま承認する。
- 購入者が変更を提案する。この場合、プロポーザルは返送され、下書きの状態に戻ります（上の図 1、2 の
state B）。プロポーザルを編集用に開き、変更案を反映して、購入者に返送して確認を求める必要があります。 - 購入者から返信がある前に変更を加える。販売管理を使用している場合、これを行うには RetractProposals アクションを実行します。このアクションにより、プロポーザルは図 1 の
state Bに戻ります。ここでプロポーザルを編集用に開き、変更を加えてから、購入者に返送します。販売管理を使用していない場合、これを行うには、図 2 のstate Dから直接プロポーザルを編集用に開きます。
この交渉は、購入者と合意に達するまで続きます。購入者との間で交わされたコメントは、getMarketplaceCommentsByStatement を使って取得できます。購入者にコメントを送信できるのは、図 1、2 の state A のときです。コメントを追加するには、updateProposals を使ってプロポーザルの marketplaceComment フィールドを更新します。追加したコメントは、購入者に承認をリクエストする際に送信されます。
プロポーザルが確定する
お客様と購入者の両者がプログラマティック プロポーザルを承認すると、そのプロポーザルは確定済みの状態となります（図 1 の state E、図 2 の state F）。DFP では、確定したプログラマティック プロポーザルから広告申込情報が自動的に作成されます。
ほとんどの場合、これでプログラマティック プロポーザルでの作業は完了です。ただし、この状態で次の 2 つのアクションを実行することもできます。
- プログラマティック プロポーザルをもう一度開いて、配信関連のフィールドを編集し、再交渉に送る。販売管理を使用している場合、これを行うにはまずプロポーザルを撤回（図 1 の
state F to B）し、編集用に開いて変更を加え、内部ワークフローに送信した後、購入者に承認をリクエストします。販売管理を使用していない場合は、プロポーザルを編集用に開き（図 2 のstate E to A）、変更を加えた後、購入者に承認をリクエストします。 - 配信関連以外のフィールドを編集し（プロポーザル名を更新するなど）、この取引から作成された DFP のオーダーと広告申込情報にその変更を反映する。販売管理を使用している場合、これを行うには、図 1 の
state Fからプロポーザルを撤回して編集し、内部ワークフローに送信します。そうすると図 1 のstate Gとなるので、UpdateOrderWithSellerData アクションを実行します。販売管理を使用していない場合は、図 2 のstate Eからプロポーザルを編集し、UpdateOrderWithSellerDataアクションを実行します。