​

Deal Sync API Specification

​

このドキュメントについて

※この翻訳は、IAB Tech Lab による公式なものではありません。翻訳の正確性については翻訳者が責任を負います。

​

About the IAB Tech Lab（IAB Tech Lab について）

IAB Technology Laboratory は、グローバルな業界技術標準およびソリューションの策定と実装を支援することを使命とする非営利の研究開発コンソーシアムです。Tech Lab の目標は、デジタル広告およびマーケティングサプライチェーンに関連する摩擦を軽減し、業界の安全な成長に貢献することです。IAB Tech Lab は技術標準の開発を主導し、IAB 標準の迅速でコスト効率の高い実装を支援するコードライブラリを作成・維持し、企業が自社の技術ソリューションと IAB 標準との互換性を評価するためのテストプラットフォームを確立しています。IAB 標準は 18 年間にわたり、デジタル広告サプライチェーンにおける相互運用性と収益性の高い成長の基盤となってきました。IAB Technology Lab の詳細については www.iabtechlab.com をご覧ください。

​

IAB Tech Lab Lead:

Hillary Slattery, Sr. Director of Product, IAB Tech Lab

​

License

This specification is licensed under a Creative Commons Attribution 3.0 License. To view a copy of this license, visit creativecommons.org/licenses/by/3.0/ http://creativecommons.org/licenses/by/3.0/ or write to Creative Commons, 171 Second Street, Suite 300, San Francisco, CA 94105, USA.

​

Disclaimer

THE STANDARDS, THE SPECIFICATIONS, THE MEASUREMENT GUIDELINES, AND ANY OTHER MATERIALS OR SERVICES PROVIDED TO OR USED BY YOU HEREUNDER (THE “PRODUCTS AND SERVICES”) ARE PROVIDED “AS IS” AND “AS AVAILABLE,” AND IAB TECHNOLOGY LABORATORY, INC. (“TECH LAB”) MAKES NO WARRANTY WITH RESPECT TO THE SAME AND HEREBY DISCLAIMS ANY AND ALL EXPRESS, IMPLIED, OR STATUTORY WARRANTIES, INCLUDING, WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AVAILABILITY, ERROR-FREE OR UNINTERRUPTED OPERATION, AND ANY WARRANTIES ARISING FROM A COURSE OF DEALING, COURSE OF PERFORMANCE, OR USAGE OF TRADE. TO THE EXTENT THAT TECH LAB MAY NOT AS A MATTER OF APPLICABLE LAW DISCLAIM ANY IMPLIED WARRANTY, THE SCOPE AND DURATION OF SUCH WARRANTY WILL BE THE MINIMUM PERMITTED UNDER SUCH LAW. THE PRODUCTS AND SERVICES DO NOT CONSTITUTE BUSINESS OR LEGAL ADVICE. TECH LAB DOES NOT WARRANT THAT THE PRODUCTS AND SERVICES PROVIDED TO OR USED BY YOU HEREUNDER SHALL CAUSE YOU AND/OR YOUR PRODUCTS OR SERVICES TO BE IN COMPLIANCE WITH ANY APPLICABLE LAWS, REGULATIONS, OR SELF-REGULATORY FRAMEWORKS, AND YOU ARE SOLELY RESPONSIBLE FOR COMPLIANCE WITH THE SAME, INCLUDING, BUT NOT LIMITED TO, DATA PROTECTION LAWS, SUCH AS THE PERSONAL INFORMATION PROTECTION AND ELECTRONIC DOCUMENTS ACT (CANADA), THE DATA PROTECTION DIRECTIVE (EU), THE E-PRIVACY DIRECTIVE (EU), THE GENERAL DATA PROTECTION REGULATION (EU), AND THE E-PRIVACY REGULATION (EU) AS AND WHEN THEY BECOME EFFECTIVE.

​

Introduction（はじめに）

この API は、ディールの概要的な条件を明確にすることで手動入力を削減し、自動化されたセットアップをより容易に実行できるようにするなど、さまざまな利点があります。また、現在ビッドストリームでは利用できないキュレーテッドディールの透明性も向上させます。

​

目標

• ディール条件を入力し、配信を行うシステムにレビューおよび承認のために送信する方法を提供することで、システム間のディール情報の手動入力を削減する。
• セリングシステムのディールに含まれる内容を概要レベルで説明する。
• パッケージのキュレーションおよび販売に関与した当事者を把握する。

​

この API でできること

• 特定のディールに関する静的情報をサブスクライバーに提供し、ディールの要点を概説する API です。
• この MVP は、ディールが作成されたシステムから受信システムにディール情報を PUSH するための、オリジンシステムによる一方向設計です（例: SSP → DSP）。また、同じシステムが初回のディール送信後に受信システムにディールステータスを問い合わせることも可能です。将来のバージョンでは、双方向通信のサポートが追加される可能性があります。
• バージョン 1.0 のこの API は差分オーバーライドをサポートしていませんが、1.1 ではサポートされる予定です。1.0 バージョンでは、ディール受信者による定期的なポーリングをフォールバックとして使用できます。データの整合性を確保するために、ディール受信者は、通知の取りこぼしに対処するためのフォールバックメカニズムとして定期的なポーリングを実装することが推奨されます。

​

この API でできないこと

• これは OpenRTB リクエスト / レスポンスには含まれない別個の API です。
• ビッドリクエストに含まれるリアルタイム情報は含まれず、ディールが適用されるかどうかを判定するものではありません。実装者は、期待が満たされていることを確認するために、このディールで提示された条件を OpenRTB リクエストと照合して検証することが強く推奨されます。
• この API の MVP は、提案、改訂、交渉をサポートしていません。それらは実装者が 事前に 把握していることを前提としています。将来のバージョンではこの機能が検討される可能性があります。
• MVP はディールマーケットプレイスにおけるディスカバリをサポートすることを意図していません。将来のバージョンでその機能が含まれる可能性があります。

​

留意事項

• これらのフィールドの値は、バイヤーとセラーが 事前に 合意したビジネス条件の概要を示すことを意図しています。この API に含まれる情報は、合意された条件のガイドとして使用するべきですが、OpenRTB ビッドリクエストから得られる情報がこの API で示された条件と一致していることを検証せずに入札に使用してはなりません。
• このチャネルを通じて提供されるディール基準が、関連するディール ID を含むビッドリクエストに正確に反映されることは保証されていません。ディール ID を含むビッドリクエストがディール基準に準拠していることを検証するのはバイヤーの責任です。言い換えれば、バイヤーは常に、ディールで示された条件に一致するターゲティングを自社側で適用するべきです。例えば、US のみのインベントリに対するディールが成立した場合、バイヤーはキャンペーントラフィッキング時に DSP にそのターゲティングを含めるべきです。
• ビッドリクエストが API で示された期待と継続的に一致しない場合、バイヤーとセラーの間でオフラインの交渉を続けるための話し合いを行うべきです。
• インベントリを販売する当事者が認可されていることを検証するには、パブリッシャーの (app)ads.txt ファイルと一致するアプリバンドルまたはサイト ID を含める必要があります。その情報なしでリクエストを受信するディール ID は、まれにしか使用せず、注意深く監視するべきです。

---

​

Deal API Specification（Deal API 仕様）

受信システムが実装する HTTP POST エンドポイントで、オリジンシステムからプッシュされたデータを受け入れます。プッシュコールの設定はこの仕様の範囲外であり、オリジンシステムの責任となります。

​

Object: Deal

​

Object: Terms

​

Object: Inventory

Inventory オブジェクトの属性は、ディールが表示される可能性のある広告およびインベントリの種類の概要を示すことを意図しています。

​

Object: Curation

テクノロジーとデータを使用してインベントリを選択・整理し、プリパッケージまたはリアルタイム運用を通じて広告主向けの効果的なパッケージを作成することに関する情報です。

---

​

受信システムエンドポイント

受信システムが実装する HTTP POST エンドポイントで、オリジンシステムが特定のディールに関する現在の情報をリクエストできるようにします。

​

Object: BuyerSeat

バイイングシステムにおけるディールのステータスに関する情報（シートレベル）。

​

Object: BuyerStatus

バイイングシステムにおけるディールのシートレベルのステータスに関する情報。

---

​

Implementation Guidance（実装ガイダンス）

​

ビッドリクエストとディールのマッチング

ディール ID を購入する際にはある程度の信頼が必要です。Deal API の情報と OpenRTB ビッドリクエストに含まれる情報を比較し、期待を満たしていることを確認するのはバイヤーの責任です。 バージョン 1.0 のこの API はディールの改訂をサポートしていません。ただし、一部の属性はディール期間中に変更される可能性があります。ディールが開始された後にどの属性が変更される可能性があるかについて、実装者間で話し合うべきです。 送信者と受信者の両方の deal.id は、入札時に OpenRTB リクエストの deal.id と一致するべきです。実装者は、PUSH を行ったオリジンシステムのディール ID を使用するべきです。 実装者は、ターゲティング基準がどこで設定されるかについて話し合うことが強く推奨されます。受信システムで追加のターゲティングが適用される場合、ターゲティングのソースが異なる場合の配信への潜在的な影響について話し合うべきです。

​

認可

サプライチェーンの検証は、常に OpenRTB の Object: Supply Chain を使用して行うべきです。この情報が利用できない場合、実装者は、特定のパスがインベントリの販売を認可されているかどうかを知るメカニズムがないことを理解した上で、細心の注意を払って進めるべきです。

​

情報の送受信

新しいディールに関する情報を送信するには、オリジンシステムが受信システムパートナーの API エンドポイントに PUSH リクエストを送信します。 ディールがオリジンシステムから受信システムに送信された後、受信システムが設定したエンドポイントにディールのステータスに関する情報を問い合わせることができます。 実装者は、イベントに対する受信 Webhook を API エンドポイントで受け入れることを選択してもよいです。この機能とサポートについては、選択した連携パートナーと話し合ってください。

​

Deal オブジェクトガイダンス

​

補助データ

auxdata は、特定のディールに非パブリッシャーデータが含まれることが予想される場合に常に使用するべきです。これは多くの場合、従来のデータプロバイダーですが、パブリッシャーに属さない最適化サービスも含まれる場合があります。非パブリッシャーデータエンティティの名前は明示されませんが、いずれかの企業がデータおよび / または最適化に対して報酬を受けている場合、この値は非パブリッシャーデータの存在を示すべきです。 この属性は、ディール開始後に追加のデータレイヤーが適用される可能性があるかどうかについての情報も伝えます。例えば、追加データを含んだ状態でディールが開始され、ディール期間中にデータおよび / または最適化サービスのリストが追加または更新されることが予想される場合は、値 2 を使用するべきです。

​

パブリッシャー数

pubcount は、ディールが単一のパブリッシング企業向けであるか、複数のパブリッシング企業にまたがるかを伝えることを意図しています。複数の Web およびアプリプロパティを持つ単一企業をカバーするディールは、単一パブリッシャーとみなされます。複数のパブリッシングサイトを代表するインベントリ集約サービスも、単一パブリッシャーディールとみなされる場合があります。 pubcount 属性は、非パブリッシャー当事者（トランザクションに関与するアドテクスタックを含む）を考慮しないことに注意してください。仲介者は、OpenRTB リクエストの Supply Chain Validation を使用して識別するべきです。

​

動的インベントリ

dinventory は、初期オファリングに含まれるサイトやアプリがディール開始後に更新されることが予想されるかどうかについての情報を伝えます。言い換えれば、この属性は、ディール開始後にサイトおよび / またはアプリの追加や削除によってインベントリが変更される（またはされない）という期待を伝えます。実装者は、期待が満たされるよう、インベントリ更新の詳細についてすべてコミュニケーションし、話し合うことが強く推奨されます。

​

Terms オブジェクト

価格属性は、ディールが固定価格ディール（特にプログラマティックギャランティードディール）の場合に提供しなければなりませんが、それ以外の場合は価格ガイダンスとして使用するか、価格ガイダンスがない場合（例: 価格ガイダンスのない Run-of-Exchange ディール）は提供しなくてもよいです。 複数の DSP シートが含まれる場合、シートごとの承認 / 拒否は DSP が内部システムおよびユーザーインターフェースで表示するものとします。 ディール名と説明の例は、フィールドに含めるべき内容の標準的な方法の参照点として提供されています。

​

Inventory オブジェクト

このオブジェクトは、ディールが静的なサイトまたはアプリのセットに対するものである場合（dinventory=1）にのみ含めるべきです。

​

含まれるインベントリ

この属性は、ディールが実行されるインベントリのタイプを伝えるものであり、インベントリ自体の詳細ではありません。したがって、この属性に直接関連する OpenRTB の特定のオブジェクトはありません。 例えば、inclinventory.adtype=1,2 は、ディールがバナー広告と動画広告の両方を含むことを意味します。実装者は、ディール開始後に imp.banner または imp.video のいずれかを使用した ORTB ビッドリクエストを受信することを期待するべきです。

​

価格とフロアのガイダンス

歴史的にディールは、一定の価格での配信を保証するために合意された料金で交渉されてきました。現在、多くの SSP やキュレーターは、インベントリ自体とは直接関係のないデータポイントを中心にメディアを集約しています。そのようにキュレートされたディールのインプレッションは、リクエストごとに異なる価格ポイントを持つ可能性があります。そのような場合にフロアが提供される代わりに、サプライヤーはインベントリ全体で効果的な勝率を提供する入札ガイダンスを提供しますが、ディールに含まれるビッドリクエストの個々のフロアを記述するものではありません。

​

Origin、Curator、および Seller

origin 属性は、ディールが最初に入力される UI を持つシステムを指します。通常、これは SSP です。 curator 属性は、インベントリ、テクノロジー、および / またはデータのパッケージングを行ったビジネスエンティティの名前です。多くの場合（ただし常にではなく）、これはバイヤーにディールを販売した当事者です。 seller 属性は、デマンドをソースした（つまりディールのバイヤーと契約した）ビジネスエンティティを表します。これが origin または curator 属性で指定されたエンティティのいずれでもない場合、このフィールドは特に有用です。

​

例 1

• SALESHOUSE が営業チームを持ち、デマンドをソースする
• キュレーテッドディールは DATA PROVIDER A、DATA PROVIDER B、および場合によっては DATA PROVIDER C や DATA PROVIDER D が提供するデータを組み込む
• ディールは SSP に入力される
• CURATOR が SALESHOUSE のディール立ち上げを支援するすべてのオペレーションを行う

この場合、seller=saleshousedomain.com、curator=curatordomain.com、origin=sspdomain.com となります。

​

例 2

• PUBLISHER が DATA PROVIDER A とビッドリクエストのデコレーションに関する契約を結び、パブリッシャーのインベントリをパッケージングする
• PUBLISHER がディールのデマンドをソースする
• PUBLISHER が SSP ユーザーインターフェースにディールを入力する

この場合、seller=publishercompany.com、curator=datacompany.com、origin=sspdomain.com となります。

​

Curation オブジェクト

​

キュレーション料金

curationfee は、ビッドストリームで適用される料金のタイプに関する情報を提供しますが、その料金額は含みません。例えば、キュレーターが CPM $5 を請求している場合、CPM であるため `curationfee` は 3 になります。キュレーターが定額料金$100 を請求している場合、定額料金であるため curationfee 属性で送信される値は 2 になります。キュレーターがインベントリとともにデータをパッケージングし、キュレーションサービス自体に対する特定の料金を取らない場合、料金なしのため値は 4 になります。

​

シナリオ例

---