OpenRTB 仕様 v3.0(日本語訳)OpenRTB Specification v3.0

本文書は OpenRTB 仕様 v3.0(最終版 v1.0)を日本語に翻訳したものです。
Creative Commons Attribution 3.0 の元で公開しており、ライセンスコピーの詳細はこちらをご参照ください。

最終版 v1.0

2018年11月

IAB テクノロジーラボについて

IAB テクノロジーラボラトリ(テックラボ)は、標準化仕様、ソフトウェア、およびサービスを制作・提供することで、効果的かつ持続可能なグローバルデジタルメディアエコシステムの成長を促進させる非営利の研究開発団体です。 IAB テックラボは、デジタル配信事業者や広告技術会社、さらにマーケティング担当者、代理店、インタラクティブマーケティング分野に関心のある会社で構成され、モバイルおよびテレビ・デジタルビデオチャネルの有効化に重点を置くことで、透明で安全かつ効果的なサプライチェーン、よりシンプルで一貫した成果測定、そして消費者にとってのより良い広告体験を通じて、ブランドとメディアの成長を実現することを目指しています。 IAB テックラボは、消費者、配信事業者、広告主、およびサードパーティプラットフォームのデジタル体験を向上させるために設計された、DigiTrust 標準リアルタイムアイデンティティサービスも所有しています。ボードメンバーには AppNexus、ExtremeReach、Google、GroupM、Hearst Digital Media、Integral Ad Science、Index Exchange、LinkedIn、MediaMath、Microsoft、Moat、Pandora、PubMatic、Quantcast、Telaria、Yahoo! Japan が参加しています。 IAB テックラボは 2014 年に設立され、ニューヨークに本社を置いています。さらに、サンフランシスコに事務所、シアトルとロンドンに代理店を構えています。

IAB テックラボについては、www.iabtechlab.comでさらに知ることが出来ます。

ライセンス(訳注:元文献)

OpenRTB 仕様 IAB テックラボは Creative Commons Attribution 3.0 でライセンスされています。 ライセンスのコピーを見るには、 creativecommons.org/licenses/by/3.0/を訪れるか「Creative Commons, 171 Second Street, Suite 300, San Francisco, CA 94105, USA」へ問い合わせて下さい。

 

 

概要

OpenMedia のミッション

OpenMedia プロジェクトのミッションは、広告主である買い手と配信在庫を抱える売り手との間のコミュニケーションを実現するオープンな業界標準の提供によって、プログラマチック広告市場の成長を加速させることです。この標準には、実際のリアルタイム入札プロトコル、情報分類、オフライン構成同期といった内容が含まれますが、これらに限定されるものではありません。

本ドキュメントは、リアルタイム入札(Real-Time Bidding; RTB)のインタフェイス標準を規定しています。これらのプロトコル標準は、配信在庫の供給者(つまり、取引所、配信者と連携しているネットワーク、売り手サイドのプラットフォーム)と競争的なその在庫の買い手(つまり、入札者、買い手サイドのプラットフォーム、もしくは広告主と連携しているネットワーク)の間の繋がりをシンプルにすることを目的としています。

OpenRTB の全体目標は、買い手と売り手の間のコミュニケーションにおける「リンガフランカ (訳注:共通言語)」 を作成することです。 その目的は、各当事者がどのようにビジネスを行うかを正確に規制することではありません。プロジェクトとして私たちは、技術革新が「水道管よりも」深いレベルで起こるように当事者間の接続を容易にすることを目指しています。

 

OpenRTB の歴史

OpenRTB は、2010年11月に3つの買い手側プラットフォーム(dataxu、MediaMath、Turn)と3つの売り手側プラットフォーム(Admeld、PubMatic、Rubicon プロジェクト)による、パイロットプロジェクトとして立ち上げられました。当初の目標は、ブロックリストを取引するための当事者間通信を標準化することでした。そうして、OpenRTB ブロックリスト仕様のバージョン 1.0 が 2010年12月にリリースされました。

業界からのポシティブな反応を経て、Nexage は実際のリアルタイム入札要求・応答プロトコルに焦点を当て、さらにモバイル広告をサポートする点に特筆した OpenRTB の API 仕様を作成するという提案を、OpenRTB プロジェクトに持ち込みました。そしてモバイル小委員会が、買い手サイドを代表する企業(dataxu、Fiksu、[X+1])と売り手サイドを代表する企業(Nexage、Pubmatic、Smaato、Jumptap)の間で結成されました。このプロジェクトによって、OpenRTB v1.0 モバイル仕様が生まれ、2011年2月にリリースされました。

モバイル仕様のリリースに続いて、dataxu と ContextWeb が協業する動画広告取引所(BrightRoll、Adap.tv)のための、動画小委員会が結成されました。 その目標は、ディスプレイ、動画、モバイルのサポートを一つに統合することでした。 この取り組みによりOpenRTB 2.0 が生まれ、これが2011年6月に統一規格としてリリースされました。

OpenRTB は業界で非常に幅広く採用されたため、2012年1月のバージョン 2.1 のリリースに併せて IAB 標準として発行されました。仕様の技術的内容に関する意思決定は、OpenRTB コミュニティとそのガバナンスルールに基づきます。

それ以来、プログラマチック広告は業界で支配的な強制力を持つようになりました。 しかし、これによってサプライチェーンがますます複雑化し、不正行為やその他のリスクが増加する可能性があります。これが OpenRTB v3.0 を推進する鍵となる動機の一つです。

 

バージョン変遷

OpenRTB リアルタイム入札 API

3.0 複雑なサプライチェーン、階層化仕様アーキテクチャ、在庫信頼性のためのデジタル署名

2.5 ヘッダービディング、請求および敗北通知、フレックス広告、請求 ID、戦略 ID、インプレッションメトリック、アウトストリームビデオ、その他多くの軽微な機能拡張をサポート。

2.4 オーディオ広告枠のサポートと、2.x バージョンで最も多くの軽度から中程度の機能拡張。

2.3 ネイティブ広告枠のサポートと、複数の軽微な機能拡張。

2.2 非公開市場直接取引、動画、モバイル、および規制信号に関する新しい機能拡張。

2.1 IQG コンプライアンス、軽微な機能拡張、および訂正のための改訂。

2.0 ディスプレイ、モバイル、動画の標準を統一仕様へ統合。

1.0 OpenRTB モバイルの初回リリース。

 

OpenRTB ブロックリストブランチ

1.2 配信者設定 API (提案済み)。

1.1 クリエイティブ属性のリアルタイム取引を含める軽微な変更。

1.0 OpenRTB ブロックリスト仕様の初回リリース。

 

アーキテクチャ

この章では仕様の詳細が正しく理解できるように、RTB トランザクションが適用されるエコシステムの基本モデルと、OpenRTB の全体構成について説明します。

用語

以下の用語はこの文書を通して、OpenRTB および本仕様の文脈の上で明確な意味を持って使用されています。

用語 定義
RTB リアルタイムもしくはそれに近い商品への入札。
サプライソース 配信者ないし在庫を売るオーディエンスソース。
取引所 商品単位で入札者間のオークションを執りしきる主体。(例:SSP)
仲介者 サプライソースとデマンドソースの間にある主体。(例:取引所)
サプライチェーン 最後のサプライソースとデマンドソースまでの間にある複数の仲介者のセット。
デマンドソース オークションにおいて商品への入札を行う主体。(例:DSP)
シート 商品の獲得を目指して、デマンドプラットフォームを使用する購入主体(例:広告主、代理店)。通常は購入予算の所有者。
取引 特定条件下における商品購入についての売り手・買い手間の協定。

 


参照モデル

OpenRTB は一般的に、取引所とデマンドソース、あるいは競売人と入札者の間で起こるインタラクションであると考えれるでしょう。つまり、OpenRTB は小商品(例:広告インプレッション)を販売する方法を定義していて、取引所からそのデマンドパートナーへ入札リクエストを公告し、レスポンスの中から入札を集め、オークションルールのいずれかの形式に基づいて勝者を決定します。取引所によっては、入札が受け入れられたことを各買い手へ通知し、ビジネスポリシーに基づいて入札が請求可能とみなされた時点で(例:広告マークアップの描画)、清算価格といった重要なデータとともに勝利した買い手へ通知します。一方、勝利した以外の買い手へはオークションに負けたことを通知します。

しかし、昨今のエコシステムははるかに複雑です。ヘッダービディングが極めて一般的になったことで、配信者やユーザーエージェント、あるいはその近くに新たな裁定点が生まれ、取引所をもはや唯一の裁定者ではありません。さらに、複数のサプライチェーン仲介者を持つことが一般的となりました。中間事業者あるいは取引所によっては、直接的に接続しているデマンドに限らず、別の取引所をデマンドソースとして使用します。

これらの構造は、次の参照モデル図で示されています。取引所は上流の仲介者(向かって左)に対して、入札を行うデマンドソースとして振る舞うことが可能です。また、下流の取引所および DSP(向かって右)をデマンドソースとして使用することができます。ただしこの図は、N 個の取引所あるいはサプライ仲介者を一般的なケースにおいて示したもので、実務上の考慮事項(例:レイテンシ、レベニューシェアの連続など)によって自然な範囲での制限が課されることがあるでしょう。

 

 

OpenRTB の入札リクエスト、入札レスポンス、およびイベントはこれら主体の各ペア間で実装できます。しかし配信者間の接続については、ここでは配信者から Exchange 1 へ示されていますが、一般に標準化されていません。所与の主体がより大きなサプライチェーンを認識しているかもしれませんし、そうでないかもしれませんが、少なくともこのチェーンが配信者によって異なることがあることを考慮しています。いずれにせよ OpenRTB は、少なくとも所与のトランザクションにおいて、所与の主体が左(サプライ側; 上流)および右(デマンド側; 下流)に隣接する直接的に実装された主体とのビジネス関係のみを有すると仮定します。

これの意味するところは、イベントの伝搬と非公開市場取引において説明できます。この参照モデル上で主体の立場から主観的に話すと:

・私が受信した全ての保留、請求、敗北イベントは、私のサプライ側パートナー(私のすぐ左の主体)から来ている、もしくはその完全な権限を有しているものとみなします。
・私には、保留、請求、敗北イベントを私のデマンド側パートナー(私のすぐ右の直接接続された主体)に対してのみ送信する責任があります。
・私は、サプライ側パートナー(私のすぐ左の主体)とデマンド側パートナー(私のすぐ右の主体)の間の取引を、仲介および実行します。さらにチェーンの上流もしくは下流へ私の取引を伝搬する責務は、OpenRTB の下で他の主体にありません。

 

プロトコルレイヤ

異なる仕様間におけるオブジェクトの再利用を支援し、仕様の個々の面が各自のペースで発展できるように、OpenRTB v3.0 以降では階層化アプローチが採用されています。このモデルを次に図示します。形式はらずに表現すれば、レイヤ1は当事者間でバイトデータを移動し、レイヤ2はこのバイトデータの言語を表現し、レイヤ3はこの言語を使ったトランザクション(売買の執行)を指定し、レイヤ4はトランザクション処理される商品について説明しています。

 

 

こういった階層化された概念を踏まえて、IAB テックラボは「Open Media」として関連仕様を包括的に構成する定義をしています。仕様の概要とプロトコルレイヤへどのように落としこまれているかは、次に説明しています。

 

 

次の節では、OpenRTB 仕様に関係するこれらのレイヤについて指定します。明示的に指定されておらず、任意であるという注釈が付けられておらず、かつベストプラクティスとして言及されていなければ、これらの節のすべての重要な点は OpenRTB 準拠の要件になります。

 

レイヤ1:転送

■コミュニケーション

取引所とそのデマンドソースとの間の基本プロトコルは HTTP です。 特に、入札リクエストを HTTP GET よりも大きなペイロードに対応し、かつバイナリ表現の使用を容易にするために HTTP POST が必要とされます。 通知イベントは、取引所の裁量で POST または GET のいずれでも構いません。

コンテンツを返す呼び出し(例:入札レスポンス)には、 HTTP コード 200 が返るべきです。有効なリクエストへのレスポンスにコンテンツを返さない呼び出し(例:非入札やイベント通知を示す一つの方法である空の入札レスポンス)には、HTTP 204 が返るべきです。無効な呼び出し(例:不正な形式や壊れたペイロードを含む入札リクエスト)には、コンテンツ無しで HTTP 400 が返るべきです。


■バージョンヘッダ

OpenRTB のバージョンは、入札リクエストのヘッダの中でカスタムヘッダパラメータとして渡さなければなりません。 これによって入札者はリクエストを解析し始める前に、含まれているメッセージのバージョンを認識することができます。 バージョンは <major>.<minor> として指定するべきです。


x-openrtb-version: 3.0

さらにレスポンスは、応答者が実装したプロトコルバージョンと同じ形式の HTTP ヘッダを含むことが、任意ではあるものの推奨されます。 しかし、すべてのレスポンスはリクエストのバージョンと互換性があり、そのバージョンのサポートは当事者間で事前に議論されているものと想定されます。

ベストプラクティス: 接続パフォーマンスを向上させる最も簡単で効果的な方法の1つは、キープアライブとして知られる HTTP 永続接続を有効にすることです。 インタフェイスの両側での接続管理オーバーヘッドと CPU 使用率を削減することによって、全体的なパフォーマンスに大きな影響を与えます。


■転送セキュリティ

OpenRTB v3.0 は準拠に Transport Layer Security(TLS)が必須であり、OpenRTB プロトコルが動作するすべての接続は HTTPS でなければなりません。 セキュアでない HTTP を未だに使用している従来の接続は、もはや準拠しているとはみなされません。

 

レイヤ2:形式

■表現

JSON(JavaScript Object Notation)は、入札リクエストと入札レスポンスのデータペイロードのためのデフォルト形式です。 JSONは、人間の読みやすさとコンパクトさを組み合わせたものです。

取引所は任意で、バイナリ形式(例:圧縮 JSON、ProtoBuf、Avro など)を提供しても構いません。これは送信時間や帯域幅といった点で効率的になることがあります。IAB テックラボは、これらの形式もしくは他の形式のリファレンス実装を提供することがあります。可能であれば接続の差異を減らすために、IAB リファレンス実装の使用を強く推奨します。

入札リクエストでは Content-Type HTTP ヘッダを使用し、MIME タイプとしてその表現を指定します。標準的な JSON 表現を表す MIME タイプは application/json です。入札レスポンスの形式は、入札リクエストと同じでなければなりません。


Content-Type: application/json

標準とは別のバイナリ形式が使用される場合、取引所または SSP は Content-Type を適切に指定すべきです。例えば「Content-Type: avro/binary」もしくは「Content-Type: application/x-protobuf」とします。 Content-Type が見つからない場合は、取引所によって別のデフォルト形式が選択されていないかぎり、入札者は application/json であると想定すべきです。


■エンコーディング

取引所とデマンドソース間で送られるデータを圧縮することは非常に有益です。圧縮により転送されるデータのサイズが大幅に縮小され、取引所およびデマンドソースの双方でネットワーク帯域幅が節約されます。 この節約を完全に実現するために、取引所から送られる入札リクエストとデマンドソースら返される入札レスポンスの双方に対して、圧縮を有効にすべきです。

標準的な HTTP 1.1 機構を用いて、入札レスポンスにおける圧縮を有効にすることができます。多くの Web サーバは既にレスポンス情報の gzip 圧縮をサポートしており、それは理想的な選択です。取引所が圧縮されたレスポンスを欲していることを伝えるには、HTTP 1.1 Accept-Encoding ヘッダを設定すべきです。エンコーディング値は gzip が用いられるべきです。


Accept-Encoding: gzip

このヘッダは、gzip エンコーディングされたレスポンスを受け入れることができるという取引所の指示を、デマンドソースに提示します。デマンドソースサーバがこれをサポートし正しく構成されていれば、gzipでエンコードされた情報で自動的に応答します。これは HTTP 1.1 Content-Encoding ヘッダを用いて示されます。


Content-Encoding: gzip

入札リクエストに対して圧縮を有効にするには、まず取引所とデマンドソース間でこれをサポートされていることが合意されなければなりません。取引所が入札リクエストを送信する前に形式とエンコーディングの両方を知っていなければならないので、カスタムデータ形式が用いられる場合と似ています。デマンドソースがサポートしている場合、取引所は HTTP 1.1 Content-Encoding ヘッダを設定して、gzip 圧縮した入札リクエストを送信していることを示すべきです。用いられるエンコーディング値は gzip であるべきです。


Content-Encoding: gzip

このヘッダが設定されていない場合、リクエスト情報はエンコードされていないものとみなされます。HTTP 1.1 では、通常 Content-Encoding ヘッダはレスポンス情報にのみに用いられます。しかしこのヘッダをリクエスト情報に用いることで、用いられるデータ形式に関係なくリクエストが圧縮されていることを示すことができます。これはバイナリデータ形式であっても、圧縮されることで恩恵を受けることができて便利です。

 

レイヤ3:トランザクション

トランザクションレイヤは OpenRTB を含むリアルタイム入札プロトコルの心臓です。取引所とその入札者、より一般的にはサプライチェーン仲介者とその接続されたデマンドソースとの間の通商プロトコルを定義しています。

全詳細を知りたければ、このドキュメントの「仕様」の章を参考にしてください。

 

レイヤ4:ドメイン

ドメインレイヤは、トランザクションレイヤが動作するオブジェクトを定義していて、これはつまりメディアの取引を指しています。典型的な広告オークションでは、入札リクエストは二つの場所にドメインオブジェクトを含みます。まず一つ目に、サイト/アプリ、デバイス、ユーザーといった、販売に関する情報を記述するドメインオブジェクトが全てのリクエストに含まれます。二つ目に、インプレッションや配置の詳細、仕様、制限といった商品を定義するドメインオブジェクトが販売提供されている各商品に含まれます。そして、入札レスポンスもドメインオブジェクトを含んでいて、これはオークションに勝利した場合にユーザーに配信されるメディアを定義しています。

ドメインレイヤの仕様のバージョンは、トランザクションレイヤとは独立して変わることがあります。なので、トランザクションレイヤのルートオブジェクトには、ドメイン仕様とバージョン情報が含まれます。実際、異なるバージョン同士のサポートは、取引所やデマンドソースごとに時間の経過とともに変わるので、こういった点でも非常に重要です。

OpenRTB にとって、広告共通オブジェクトモデル (Advertising Common Object Model; AdCOM) はデフォルトのドメインレイヤです。

 

仕様

この章は、詳細な OpenRTB のトランザクションレイヤの仕様を含んでいます。明示的に指定されている、任意であるという注釈がある、もしくはベストプラクティスから参照されている場合を除いて、この章の全ての事柄が OpenRTB 準拠に必須となります。

オブジェクトモデル

次の UML クラス図は、リクエストおよびレスポンスオブジェクトが含むペイロードの全体構造を図示しています。ペイロードは Openrtb という名前のついたオブジェクトをルートとし、Openrtb オブジェクトは RequestResponse の共通のルートになります。そして、RequestResponse はペイロードのタイプを決める2番目のルートです。

 

 

この章を通して、属性を「必須」もしくは「推奨」として指定することがあります。その属性を省略してしまうことでプロトコルが壊れてしまい、ビジネス価値の指標として保証できなくなる属性を「必須」と指定します。また、その属性を省略してもプロトコルは壊れないものの、ビジネス価値が大きく損なわれる属性を「推奨」と指定します。

仕様準拠の観点から見れば、「推奨」か否かに関わらず「必須」と示されていない全ての属性は任意になります。任意の属性は、省略された場合にそれとみなすことができるデフォルト値を持つことがあります。デフォルト値が指定されていない場合、慣習的には値の省略を「不明」として解釈するべきです。また、空の文字列やヌル値が指定されている場合、省略されている場合と同じように解釈するべきです。(指定されていればデフォルト値、そうでなければ「不明」)

ベストプラクティス: 取引所とデマンドソースは、それがもつ拡張仕様上でどういったオブジェクトや属性を任意のオブジェクトとしてサポートしているかを、パートナーに公開することを勧めます。

 

オブジェクト:Openrtb

このトップレベルオブジェクトは、リクエストとレスポンス両方のペイロードにとってのルートです。バージョン情報と、トランザクションのベースとなるレイヤ4ドメインモデルへの参照を含みます。OpenRTB で使われるドメインモデルは、デフォルトで広告共通オブジェクトモデル(AdCOM)となります。

注釈:このドキュメント上でのルールとして、Java のようなプログラム言語のクラス名の共通ルールに沿い、定義されるオブジェクトは大文字の頭文字で示されます。一方で、オブジェクトの実インスタンスと、ペイロード上のそこへの参照は小文字で示されます。

属性 定義
ver 文字列 OpenRTB レイヤ3仕様のバージョン(例: "3.0")。
domainspec 文字列;
デフォルト “adcom”
販売中の商品、入札に対応するメディアなどを定義するために使われる、レイヤ4ドメインモデルの ID。
domainver 文字列; 必須 domainspec 属性で参照されるレイヤ4ドメインモデル仕様のバージョン。
request オブジェクト; 必須 ※ 入札リクエストのコンテナ。※リクエストのペイロードにのみ必須。オブジェクト:Request を参考のこと。
response オブジェクト; 必須 ※ 入札レスポンスのコンテナ。※レスポンスのペイロードにのみ必須。オブジェクト:Response を参考のこと。

属性の中には、任意指定のものも含まれます。例えば ver 属性は、このペイロードで用いられる OpenRTB 仕様のバージョンを指定します。これは HTTP ヘッダを介して、レイヤ1上でも伝えられます。実行時トランザクション情報外でペイロードをより自己文書化することで、特定の手助けとなるために有用です。

しかし domainver 属性は、レイヤ4の構造がそのバージョンの間で変わるかもしれないので、実行時ユーティリティを持ちません。この属性は、ドメインオブジェクトのパーサもしくはアンマーシャリング実装を、正しく呼び出すのに役立つものです。

 

入札リクエストペイロード

リクエストオブジェクトは、最低限の高レベル属性(例:ID、テストモード、オークションタイプ、最大オークション時間、買い手の制限など)と、リクエスト元および実際の販売提供をカバーする下位オブジェクトを含みます。下位オブジェクトは、提供されている商品とそれに該当する取引全てを含みます。

このモデルには、レイヤ4ドメインオブジェクトとの橋渡しとなる二つのポイントがあります。それは、Request オブジェクトと Item オブジェクトです。Request オブジェクト配下のドメインオブジェクトは、提供の全体情報を保持するオブジェクトを含むでしょう。これらは、サイト/アプリ、デバイス、ユーザなどを記したオブジェクトを含むでしょう。一方 Item オブジェクト配下のドメインオブジェクトは、提供されている商品の詳細(例:インプレッション機会)と、入札と関係するメディア上での仕様・制限を指定しているでしょう。

 

オブジェクト:Request

Request オブジェクトは、グローバルにユニークな入札リクエスト ID を含みます。これは ID 属性と呼ばれる必須なもので、一つ以上のオブジェクトを含む Item 配列(例:一つ以上の販売商品)です。そして、その他の属性は提供されている全商品に適用されるルールと制限を示しています。このオブジェクトは、ユーザ、デバイス、サイト/アプリなどといった情報を持つ、レイヤ4ドメインオブジェクトとの橋渡しもしています。

属性 定義
id 文字列; 必須 その入札リクエストにおけるユニークな ID。取引所から提供される。
test 整数;
デフォルト値 0
オークションが入札できないテストモード中であるかを示す指示値。0 のとき本番モードで、1のときテストモード。
tmax 整数 取引所が入札の受信に許容するミリ秒最大値で、タイムアウトを避けるためにインターネットレイテンシを含んでいる。この値は、取引所から事前にあるガイダンスに取って代わるものである。取引所が仲介者として振る舞う場合、レイテンシと追加のインターネットホップを考慮して、受信する値よりも受け渡す tmax 値を減らすべきである。
at 整数;
デフォルト値 2
オークションタイプ。1 のときファーストプライスで、2 のときセカンドプライス。それ以外に、取引所固有のオークションタイプとして 500 より大きい値が使われることがある。
cur 文字列 配列;
デフォルト値 [“USD”]
ISO-4217 のアルファベットコードを使った、この入札リクエストに対する入札に認められる通貨の配列指定。特に取引所が複数の通貨を受け付ける場合は、指定が推奨される。省略された場合は、"USD" が単一の通貨として想定される。
seat 文字列 配列 この商品の入札における買い手シートの制限リスト。顧客やシート ID といった買い手に関する情報は、事前に当事者間で周知されていなければならない。なお、指定の省略は制限がないことを意味する。
wseat 整数;
デフォルト値 1
seat 配列による制限指定の解釈を決めるフラグ。0 のときブロックリストで、1 のときホワイトリスト。
cdata 文字列 取引所がサポートしていれば、入札者は取引所の cookie の代わりとしてデータセットを取得できる(オブジェクト: Response の cdata を参考のこと)。また、文字列は base85 の cookie セーフ文字でなければならない。
source オブジェクト 在庫元とどの主体が最終決定を下すかというデータを提供する Source オブジェクト。オブジェクト: Source を参考のこと。
item オブジェクト 配列;
必須
(一つ以上の)item オブジェクトの配列で、提供されている商品を構成している。オブジェクト: Itemを参考のこと。
package 整数 ロードブロッキングをサポートするために、提供されている商品が手に入れられる商品のうちの全て(例:Web ページ上での全インプレッション、プレ/ミッド /ポストロールといった全動画スポット)であることを、取引所が確認できるかを示すフラグ。0 のとき確認できない、1 のとき確認できる。
context オブジェクト; 推奨 提供されている商品の情報を保持するレイヤ4ドメインオブジェクト構造。openrtb.domainspecopenrtb.domainver で参照される仕様およびバージョンに準拠している。
AdCOM v1.x において許可されているオブジェクトは全て任意指定で、DistributionChannel サブタイプの一つ(SiteApp もしくは Dooh)、UserDeviceRegsRestrictions、そして AdCOM 指定の下位オブジェクトである。
ext オブジェクト 取引所固有の拡張仕様を任意指定する。

 

オブジェクト:Source

このオブジェクトはトランザクションの送信元についてのデータを保持していて、トランザクション自体のユニーク ID、送信元認証情報、CoC を含んでいます。

注意:dsdsmapcertdigest 属性は、 Ads.cert: 署名済み入札リクエスト仕様(訳注:原文よりリンク先を修正) として定義された、デジタル署名済みの入札リクエストをサポートしています。Ads.cert 仕様はまだベータ段階であり、これらの属性についてもそれに近い段階であるということを考慮すべきです。

属性 定義
tid 文字列; 推奨 このトランザクションにおける全サプライチェーンを通じて、参加者全体で共通でなければならないトランザクション ID。これは、ヘッダービディングやそれに似た配信者中心のブロードキャスト配信を通じても、参加する取引所全体で適用される。
ts 整数; 推奨 Unix フォーマット(エポックからのミリ秒)による、サプライチェーンの始まりでリクエストが発生した時点のタイムスタンプ。この値は後続の仲介者を通じて、不変に保たれなければならない。
ds 文字列; 推奨 入札リクエスト上に見つかる不変な属性のセットで構成されるダイジェスト文字列から、配信者もしくは配信者が信頼する代理人によって計算された、このリクエストの生成元を認証するために使われるデジタル署名。より詳細については「在庫認証」の章を参考のこと。
dsmap 文字列 ダイジェストを作成するために使用される属性を示す ID の順序つきリスト。このマップは、入札リクエストからダイジェストを再作成するための重要な指示を提供していて、これは ds 属性のデジタル署名を検査する時に必要とされる手順である。より詳細については「在庫認証」の章を参考のこと。
cert 文字列; 推奨 ds 属性のデジタル署名を生成するために使われる証明書(公開鍵)のファイル名。より詳細については「在庫認証」の章を参考のこと。
digest 文字列 デジタル署名を生成するために署名された全ダイジェスト文字列。より詳細については「在庫認証」の章を参考のこと。
注意:これは必要に応じてデバッグを行う目的でのみ用意されたものです。帯域幅への影響があるので、通常の本番トラフィックのために用意されたものではありません。
pchain 文字列 TAG 請求 ID プロトコルで記述された埋め込みシンタックスを含む請求 ID チェーン文字列。
注意:「ads.txt」仕様と結合した Source オブジェクトの認証機能によって、この属性が廃止されるかもしれません。
ext オブジェクト 取引所固有の拡張仕様を任意指定する。

 

オブジェクト:Item

このオブジェクトは、公開市場もしくは非公開市場取引のいずれの上でも販売提供されている商品の枠を表します。同じ入札リクエストの中に複数の提供商品が存在してもかまいませんが、各入札は興味のある特定の商品を参照しなければならないので、id 属性が必須となります。このオブジェクトは、提供商品のより深い仕様(例:インプレッション)におけるレイヤ4ドメインオブジェクトとの橋渡しを担っています。

属性 定義
id 文字列; 必須 特定の提供におけるこの商品のユニークな ID。(通常1から始まり順に増加する)
qty 整数;
デフォルト値 1
この提供商品のインスタンス数。(例:屋外デジタル配信における複数の同一インプレッション)
seq 整数 複数の商品が同じ入札リクエスト上で提供されているとき、シーケンス番号があることで配送の協調が可能になる。
flr 浮動小数点数 CPM で表されるこの商品の最小入札価格。
flrcur 文字列;
デフォルト値 “USD”
ISO-4217 のアルファベットコードを使って指定される flr 属性の通貨。
exp 整数 オークションからフルフィルメントまでの許容経過秒数についての通告。
dt 整数 Unix フォーマット(エポックからのミリ秒)による、商品のフルフィルメントが期待される時間のタイムスタンプ。(例:いつ DOOH インプレッションが表示されるか)
dlvy 整数;
デフォルト値 0
商品(例:広告オブジェクト)の求められる配送方法。0 のときいずれかの方法で、1 のとき商品はトランザクションの一部として送信されなければならず(例:入札自体の値による方法、入札に含まれる URL で取得される方法)、2 のとき事前に取引所にアップロードされているある商品をその ID で参照しなければならない。ちなみに、取引所が事前アップロードをサポートしていないと参照可能な商品がないかもしれず、デフォルト値の 0 は 1 と同じ意味になる。
metric オブジェクト 配列 Metric オブジェクトの配列。オブジェクト: Metric を参考のこと。
deal オブジェクト 配列 この商品に適用可能な特別な協約事項を伝える Deal オブジェクトの配列。オブジェクト: Deal を参考のこと。
private 整数;
デフォルト値 0
Deal オブジェクトで指定される、シートがオークションに適格であるかに関する指標。0 のとき全入札を受け付け、1 のとき入札は取引(deal)としての指定とその協約事項に制限されます。
spec オブジェクト; 必須 提供されている商品を指定するレイヤ4ドメインオブジェクト構造。openrtb.domainspecopenrtb.domainver で参照される仕様およびバージョンに準拠している。AdCOM v1.x において許可されているオブジェクトは Placement と AdCOM 指定の下位オブジェクトである。
ext オブジェクト 取引所固有の拡張仕様を任意指定する。

 

オブジェクト:Deal

このオブジェクトは、売り手と買い手の間で事前に取り決められた特定の取引を構成します。取引が存在する場合、この商品がその取引の協約事項の元で有効であることを示します。

属性 定義
id 文字列; 必須 その取引におけるユニークな ID。
flr 浮動小数点数 CPM で表されるこの商品の最小取引価格。
flrcur 文字列;
デフォルト値 "USD"
ISO-4217 のアルファベットコードを使って指定される flr 属性の通貨。
at 整数 リクエストの全オークションタイプを任意で上書きする指定。1 のときファーストプライス、2 のときセカンドプライスプラス、3 のとき flr で渡される値が取引価格として合意されたものとなる。また、500 以上の値を使って、追加のオークションタイプが取引所により定義されることがある。
wseat 文字列 配列 この取引での入札を許可する買い手シートのホワイトリスト。シートの ID や買い手が参照する顧客といった情報は、入札者と取引所の間で事前に周知されていなければならない。なお、指定の省略は制限がないことを意味する。
wadomain 文字列 配列 この取引での入札が可能な広告主ドメイン(例:advertiser.com)の配列。指定の省略は制限がないことを意味する。
ext オブジェクト 取引所固有の拡張仕様を任意指定する。

 

オブジェクト:Metric

このオブジェクトは、メトリックの配列として商品に関連づけられています。これらのメトリックは最近の平均ビューアビリティや CTR などの、意思決定を支援するための洞察を提供します。各メトリックはそのタイプによって識別され、メトリックの値を報告し、値を計測した送信元もしくはベンダーを任意で識別します。

属性 定義
type 文字列; 必須 事前に入札者へ公開されるべきである取引所管理の文字列名を使って渡される、メトリックのタイプの指定。
value 浮動小数点数;
必須
メトリックの値を表す数値。確率値は 0.0~1.0 の範囲内でなければならない。
vendor 文字列; 推奨 事前に入札者へ公開されるべきである取引所管理の文字列名を使って渡される、送信元の指定。取引所自体がサードパーティにとって送信元である場合は、「EXCHANGE」値が推奨される。
ext オブジェクト 取引所固有の拡張仕様を任意指定する。

 

入札レスポンスペイロード

レスポンスオブジェクトは、最低限の高水準属性(例:リクエスト ID への参照、入札通貨など)とシート入札の配列を含みます。シート入札とは、それぞれが入札の集合である買い手シートに代わるものです。

個々の入札は、リクエスト内の関連商品と購入情報を参照します。購入情報とは、価格、適用可能である場合には取引 ID、通知 URL といったものを指します。入札に関連するメディアは、各入札に含まれるレイヤ4ドメインオブジェクト(広告クリエイティブ、マークアップ)を介して伝えられます。

 

オブジェクト:Response

このオブジェクトは、Openrtb ルートの下にある入札レスポンスオブジェクトです。オブジェクトの id 属性は、入札リクエスト ID と同一になります。bidid 属性は、入札者のための任意レスポンストラッキング ID です。指定されている場合、それをマークアップや通知 URL 内に置かれる置換マクロで使用可能になるでしょう。少なくとも一つの Seatbid オブジェクトが必須であり、ある商品を表す Bid を少なくとも一つ含みます。そして、それ以外の属性は任意指定になります。

最もコンパクトに「非入札」を表すには、HTTP 204 と空レスポンスを返してください。その一方で入札者が入札しない理由を伝えたい場合は、nbr 属性に理由を表すコードを指定した Response オブジェクトを返すことが可能です。

属性 定義
id 文字列; 必須 このオブジェクトでレスポンスしている入札リクエストの ID。request.id 属性と一致していなければならない。
bidid 文字列 ロギング、トラッキングを支援するために入札者が生成するレスポンス ID。
nbr 整数 該当する場合、入札しない理由を示す(リスト: 非入札理由コード を見ること)。ちなみに、多くの取引所が非入札を示すためにシンプルな HTTP 204 レスポンスを好んでいるものの、理由コードを示すレスポンスはデバッグが必要な場面で便利なことがある。
cur 文字列;
デフォルト値 「USD」
ISO-4217 アルファベットコードを使った、入札通貨の指定。
cdata 文字列 取引所がサポートする場合に、入札リクエスト上から取得可能な取引所の cookie に、入札者がデータをセットすることを許容する。(オブジェクト: Requestcdata)文字列は base85 の cookie セーフ文字で構成されていなければならない。
seatbid オブジェクト 配列 Seatbid オブジェクトの配列で、入札をする場合は一つ以上必要。オブジェクト: Seatbid を参考のこと。
ext オブジェクト デマンドソース固有の拡張仕様を任意指定する。

 

オブジェクト:Seatbid

入札レスポンスは、複数の Seatbid オブジェクトを含むことが可能です。それぞれが別の買い手シートを表していて、それぞれが個々の入札を複数含んでいます。そして、複数の商品がリクエスト上にある場合に、シートは勝利できるインプレッションを全て受け付けたいか(デフォルト)、それともグループとして全ての商品で勝利できる場合にのみ興味があるのかを指定するのに、package 属性が使われます。

属性 定義
seat 文字列; 推奨 この入札を生成した買い手シートの ID。
package 整数;
デフォルト値 0
複数の商品が提供されている場合に、このフラグは入札者が全入札の一部の勝利でも受け付けたいか、それともパッケージとしてグループ全体での勝利を求めているかを示している。0 のとき個々の勝利を、1 のときパッケージでの勝利か敗北のどちらかだけを受け付ける
bid オブジェクト 配列;
必須
それぞれが一つの商品と関連づけられた、一つ以上の Bid オブジェクトの配列。複数の入札が同じ商品と関連づくこともある。オブジェクト: Bid を参考のこと。
ext オブジェクト デマンドソース固有の拡張仕様を任意指定する。

 

オブジェクト:Bid

Seatbid オブジェクトは、一つ以上の Bid オブジェクトを含んでいます。それぞれが入札リクエストで提供される特定の商品と item 属性を介して関連しており、所与の価格による商品の購入提供を構成しております。

属性 定義
id 文字列; 推奨 ロギング、トラッキングを支援するために入札者が生成する入札 ID。
item 文字列; 必須 関連入札リクエストの商品オブジェクト ID で、具体的には item.id である。
price 浮動小数点数;
必須
CPM で表される入札価格。しかし、実際のトランザクションは枠の商品だけである。なお、型は浮動小数点数となっているが、通貨を扱う場合は整数値が高く推奨される。(例:Java の BigDecimal)
deal 文字列 この入札が非公開市場取引と関連する場合に、入札リクエストから取引への参照を表す。具体的には deal.id である。
cid 文字列 キャンペーン ID もしくは類似したブランド関連広告グループ。一般に、監査手続きの効率を上げるために使用される。
tactic 文字列 入札が確定した時の戦略を取引所に報告するために、買い手が入札にラベルづけをするための戦術 ID。具体的な使用方法と戦術 ID の意味は、買い手と取引所の間で事前に合意しておく。
purl 文字列 OpenRTB 準拠のサプライチェーン(ヘッダービディングのような順序していない意思決定が存在するかもしれない)の範囲内で、入札者が決まった時に取引所から呼ばれる保留通知 URL。置換マクロが含まれることがある。
burl 文字列; 推奨 取引所固有のビジネスポリシーに基づいて請求可能となったとき(例:マークアップが描画された)、取引所から呼ばれる請求通知 URL。置換マクロが含まれることがある。
lurl 文字列 入札に負けたことがわかったとき、取引所から呼び出される敗北通知 URL。置換マクロが含まれることがある。ただし、取引所固有のポリシーにより敗北通知のサポートや清算価格の開示が阻まれ、その結果 ${OPENRTB_PRICE} マクロが削除(長さ 0 の文字列に置き換え)されることがある。
exp 整数 オークションからフルフィルメントの間に買い手が待つ意思のある秒数についての通告。
mid 文字列 ドメインオブジェクトに値として内包されるより以前にメディアが取引所にアップロードされているとき、メディアを参照で指定できるようにするための ID。
macro オブジェクト 配列 入札の特定の値でマークアップを置換できるようにするための Macro オブジェクトの配列。mid 属性を通して参照される、事前アップロードされるメディアにおいて、特に有効である。オブジェクト:Macroを参考のこと。
media オブジェクト 入札に勝った場合にメディアに表示されるメディアを指定するレイヤ4ドメインオブジェクト構造。openrtb.domainspecopenrtb.domainver で参照される仕様およびバージョンに準拠している。AdCOM v1.x において許可されているオブジェクトは、「Ad」と AdCOM 指定の下位オブジェクトである。
ext オブジェクト デマンドソース固有の拡張仕様を任意指定する。

 

オブジェクト:Macro

このオブジェクトは、動的な値をメディアマークアップに挿入するのに使われる、買い手定義のキーバリューペアを構成します。どのように伝えられるかに関わらずどんなメディアマークアップにも適用されますが、基本的には、トランザクションと入札で参照される以前(例:クリエイティブ品質レビューのために事前登録された)に取引所にアップロードされたメディアで使うためのものです。そして、実行時に置換されるマクロの完全な形式は ${CUSTOM_KEY} で、「KEY」 は key 属性で与えられる名前です。OpenRTB 標準マクロとのコンフリクトは、起こらないことが確約されています。

属性 定義
key 文字列; 必須 買い手固有マクロの名前。
value 文字列 マークアップ内で見つかった各マクロの実体と置換する値。
ext オブジェクト デマンドソース固有の拡張仕様を任意指定する。

 

置換マクロ

イベント通知 URL とその形式は、デマンドソースによって定義されています。そして、取引所が特定の情報(例:清算価格)を伝えられるように、多くのマクロをこれらの URL に挿入することが出来ます。取引所にはその URL を呼び出す前に、マクロを解決する責任があります。置換処理はシンプルで、正しいマクロが見つかるいかなる箇所において、シンタックスが正しいかどうかに関係なく行われます。さらに、元となる値が任意指定のパラメータで、かつそれが指定されていないとき、マクロは単に削除(長さ0の文字列との置換)されるでしょう。

入札システムの実装担当者の判断で、カスタムマクロがサポートされることもあります。事前アップロード済みの広告を参照することで入札が行われる場合、動的にデータ挿入を行うカスタムマクロのサポートは一般的に必要になるでしょう。カスタムマクロは ${CUSTOM_KEY} という形式で使用され、「KEY」は大文字小文字などの変更なしに「Macro」オブジェクトで指定される特定の文字列を表します。詳細は「Macro」オブジェクトを見てください。なお、取引所はカスタムマクロをサポートするか否かを選ぶことが出来ますが、事前アップロード済み広告の配信機能を提供する取引所ではサポートされることが期待されます。

こういった置換マクロと同じものを、広告マークアップ上にも置くことが出来ます。取引所は、前述の通知 URL で行われたのと同じようなデータ置換を行うでしょう。これはマークアップをどのように取得するかに依らず行われます。例えばユースケースの一つとして、清算価格といったデータをマークアップ上に埋め込まれたトラッキング URL に挿入することがあります。

次の表では、標準的な置換マクロを定義しています。OpenRTB に準拠する取引所は、データが利用可能な全マクロをサポートしなければならず、さらにマークアップと通知 URL どちらに対する置換もサポートしなければなりません。

マクロ 定義
${OPENRTB_ID} 入札リクエストの ID; request.id 属性より。
${OPENRTB_BID_ID} 入札の ID; response.bidid 属性より。
${OPENRTB_ITEM_ID} 勝利した商品の ID; item.id 属性より。
${OPENRTB_SEAT_ID} 入札者シートの ID; seatbid.seat 属性より。
${OPENRTB_MEDIA_ID} 事前登録済みの配信メディアの ID; bid.mid 属性より。
${OPENRTB_PRICE} 入札と同じ通貨による清算価格。
${OPENRTB_CURRENCY} (明示的もしくは暗黙に)入札で使われる通貨; 確認のためだけのもの。
${OPENRTB_MBR} 「清算価格 / 入札価格」で定義される市場入札率。
${OPENRTB_LOSS} 敗北理由コード(リスト:敗北理由コード を見よ)。

試験あるいは広告品質目的でマークアップが描画される場合、マクロによって値がわからないことがあります(例:清算価格)。こういった場合は、マクロ値として AUDIT を置換してください。

マクロ値は事前に様々な難読化・暗号化アルゴリズムを使って、セキュリティ目的でエンコードされていても構いません。これは特に、価格情報が取引所から配信者を通じて送られ、マークアップ内のトラッキングピクセルを介してデバイスのブラウザに届くようなユースケースで興味深いでしょう。

特定のマクロはエンコードされた状態で指定されています。:X というサフィックスがマクロ名に付いているはずで、X は使用されているアルゴリズムを指し示す文字列です。アルゴリズム選択についてこの仕様で定義されていることはありませんが、当事者間で相互に合意されていなければなりません。例えば、価格マクロは Base64 でエンコードされており、B64 というコードで合意されているとします。その時、マクロは次に書かれたようになるでしょう:


${OPENRTB_PRICE:B64}

 

イベント通知

本仕様内において後述のイベントを定義します。これとは別に、ドメインオブジェクト固有のレイヤ4でイベントが定義されることがあります。イベント URL を呼び出す全主体は、まず先に OpenRTB 標準の全置換マクロの解決を確認しなければなりません。

 

イベント:保留

保留通知は、ある入札が OpenRTB 準拠のサプライチェーン内で勝者として選ばれていることを示します。これは、一つの取引所が唯一の意思決定者であるようなシンプルなサプライチェーンでは、オークションに勝利したことと同義になります。複雑なサプライチェーンにおいては、このイベントはまず、OpenRTB を介してその結果を伝えていないパブリッシャーに最も近い取引所から開始されます。しかし、OpenRTB に準拠していない(例:ヘッダービディング)上流の意思決定が未だ存在するかもしれないので、このイベントを必ずしも勝利とみなすことは出来ません。取引所はこのイベントを伝えるために、bid.purl 属性でデマンドソースから提供される URL を呼び出します。

注意: このイベントは案内(入札がサプライチェーン上の全ての OpenRTB 準拠の関門をパスした)としてのみ解釈されるべきです。決して、いかなる形のフルフィルメントや請求を示すものではありません。

 

イベント:請求

請求イベントは、トランザクション結果として、取引所もしくはその他の仲介者からデマンドサイドパートナーの一つへ金銭的請求が発生する場合を指します。このイベントには取引所が決めているビジネスポリシーが適用され、ビジネスポリシーはデマンドパートナーに対して明確に伝えられるべきです。さらに DSP にとって、このイベントは関連キャンペーンに対する支出を減らすことが出来ることを示します。取引所はこのイベントを伝えるために、bid.burl 属性でデマンドソースから提供される URL を呼び出します。

注意: 清算価格マクロは、マークアップ上の DSP トラッカーと同じように他のイベントで解決されても構いませんが、この URL が正しく実装されていれば、OpenRTB プロトコル上で請求イベントを伝える唯一の公式手段になります。

ベストプラクティス: 請求イベント URL の呼び出しは、取引所とそのデマンドパートナー間のビジネストランザクションのフルフィルメントを表します。クライアント用ピクセルを含んでいるので他の当事者へ委譲されるべきではありませんが、ピクセルをもって取引所が請求の開始を伝えることがあります。

ベストプラクティス: 請求可能なイベントが発生したと判断したら(例:クライアント側で発生した描画信号の受信)、取引所とそのデマンドソース間の不一致を出来るかぎり抑えるために、取引所が収益を計上する最もサーバサイドから近い箇所で請求通知を呼び出すべきです。

ベストプラクティス: 潜在的に複数のオークション決定ポイントが存在するような、複雑なサプライチェーンにおいて最も一貫性のあるアプローチとして、取引所はクライアント側で発生した描画イベント、もしくは請求イベントを元にしたそれに相当するもので標準化されることが強く勧められます。

ベストプラクティス: インターネットはノイズが多いものですが、このイベントは会計上非常に重要です。請求通知を呼び出す主体が HTTP 200 もしくは 204 以外のレスポンスを受け取った場合、リトライ方式(例:10 秒ごとに 1 分間)を検討すべきです。その逆に請求通知を受け取る主体は、二重計算を避けるためにエンドポイントを冪等になるように努めるべきです。

VAST 動画においては、IAB が VAST インプレッションイベントを、インプレッションを請求可能とする公式の信号として規定しています。bid.burl 属性が指定されている場合、取引所がこのポリシーに従うのであれば同じタイミングでそれも呼び出されるべきです。しかし、小さな技術的問題で不一致が生まれるかもしれませんので、入札者はこういったシナリオを避けるために注意してください。一つのオプションは、動画のサプライソースに最も近い取引所が請求シグナルとしてインプレッショントラッカーを使い、それからさらに前述の請求通知を使うべきです。

 

イベント:敗北

敗北イベントは、取引所が入札に対して勝利の可能性がないと決定した場合を指します。取引所はここで、bid.lurl 属性でデマンドソースから提供された URL を呼び出すことがあります。

注意: 敗北通知がなかったからといって、勝利したことにはなりません。

取引所による敗北通知実行のサポートは、OpenRTB 準拠に必須ではありません。デマンドパートナーはサプライサイドパートナーに確認することを勧めます。さらに、取引所固有のポリシーによって敗北通知のサポートもしくは勝利した清算価格の開示が排除されることがあり、その結果 ${OPENRTB_PRICE} マクロは削除(長さ0の文字列との置換)されます。

 

複雑なイベント連鎖

複雑なサプライチェーンの例では、仲介者はこれらのイベントに参加するか(受信、処理して受け渡す)、もしくは迂回させるかを選ぶことができます。例えば、入札リクエストのトラフィックシェイパーのような仲介者は、イベントを直接下流に迂回させるかどうかを選択しますし、レベニューシェアに携わる完全な取引所では介入の必要があるかもしれません。

迂回に対して介入を行う動機は、イベントタイプによっても変わることがあるでしょう。例えば、ある仲介者はほぼ常に請求通知に対して介入を行います。しかし敗北通知については、介入を行う仲介者も行わない仲介者もいます。ある取引所が、ある入札を放棄し(フロアプライス以下、ブロックリスト違反など)、入札レスポンスに含まれる残りの入札を含めるように決定することを検討すると、上流を負かすものもあるでしょう。これらの敗北を本質的に宣言しているので、その入札を放棄するもののために敗北通知を呼ぶべきですが、次の入札のサブセットを放棄すると決定した時、上流の主体が敗北通知を直接下流に呼び出せるように選んでも構いません。

所与の入札に対するイベントへの介入を行う場合、仲介者は元 URL 上のマクロを解決して、潜在的に新しいマクロのセットと合わせて(例:上流の清算価格を学ぶため)それ自身を差し戻すように、その URL を新しい URL のパラメータとしてエンコードします。、上流に返却された入札でこの新しい URL を指定します。このイベント URL を受信すると、仲介者はイベントを処理して、受信、デコード、そして元 URL の呼び出しを行います。イベントを迂回するようにした場合、仲介者は単純に上流から返された入札に含まれる元 URL を維持するでしょう。

 

在庫認証

入札リクエストを署名することで「在庫枠が主張通りのものである」ということを買い手に保証することが出来ます(例えば、domain-spoofer.comdomain.com に見せ掛けることを出来なくします)。そしてこの方法は、複雑なサプライチェーンにおいて買い手が全ての仲介者と信頼関係を持っているとは限らないような場合に特に重要になります。「ads.cert」として参照されるこの機能は単独で使用することも可能ですが、IAB ads.txt 仕様と組み合わせるのが最も効果的です。(iabtechlab.com/ads-txt を参考のこと)

併せて使用することで、取引所は「私は domain.dom の配信者の在庫を売ることを許可されていて、この在庫枠は本当に domain.com のものです」という保証とともに、入札リクエストを各買い手に送信することが出来ます。

 

Ads.cert 基本

デジタル署名は、配信者もしくはそれに信頼された代理人のいずれかによって、生成されなければなりません。以降、署名者は単に配信者と記すものとします。在庫認証を行うには、事前に配信者が公開鍵と秘密鍵のペアを生成しておく必要があります。秘密鍵は署名を行うために配信者によって使用されますが、秘匿にしておかなければなりません。公開鍵は ads.text 標準の指定にしたがって、アクセスを公開した同一 Web ディレクトリ上に配置する必要があります。

正当なユースケースとして仲介者によってリクエストの一部が書き換えられること(例:在庫に対する追加データ、プライバシーポリシーに基づいた IP アドレスや地理情報のボヤかし)があるので、入札リクエスト全体を署名することは出来ません。代わりに、どの仲介者によっても変更されることのないはずの在庫認証にとって重要な属性(例:配信者のサイトドメインやアプリのバンドル情報)が選択されます。そしてこれらの属性は、シンプルながら非常に特殊な方法で「ダイジェスト」と呼ばれる文字列へ変換されます。

さらに、ダイジェストはリプレイ攻撃を避けるために、これとこのトランザクションのみをデジタル署名に関連づけるための要素を含んでいなければなりません。したがって、ダイジェストはトランザクション ID (Source.tid 属性)と/もしくは少なくとも、リクエストの開始時間(Source.ts 属性)を含まなければなりません。

いずれのインプレッションリクエストにおいても配信者はダイジェストを作成し、秘密鍵と併せて使用することでデジタル署名文字列を生成します。この署名は取引所、より一般的には Source.ds 属性の存在する最初のサプライチェーンにおいて、使用可能となります。Source オブジェクトはさらに、ads.txt ディレクトリ上に置かれている配信者の公開鍵名(Source.cert 属性)と、署名済み文字列を生成するために使用したダイジェスト構造のマップ(Source.dsmap 属性)を含んでいなければなりません。

この情報を使用することで、リクエストの認証を望んでいる買い手もしくは下流の仲介者は、ダイジェストマップの規定に基づいて入札リクエスト上のフィールドからダイジェストを再生成し、その公開鍵を使ってデジタル署名を検証することが出来ます。

この属性を持つ入札リクエストを受信した仲介者は、下流の全入札リクエストにおいて不変なこの署名を、構成する全ての重要な属性とともに含めることを義務付けられています。これが出来なかった場合、在庫枠が認証できず買い手の拒否対象となるでしょう。

 

詳細実装ガイド

これらの概念を実践するためには、配信者もしくはそれが信頼する代理人が、どのように公開鍵・秘密鍵のペアを生成するか、トランザクションをダイジェスト文字列に署名するか、ダイジェストと関連する情報を直接の取引パートナーに伝えるかを知っていなければなりません。リクエストの認証を希望する配信者とそのベンダーの両方が、入札リクエストの属性からダイジェスト文字列を生成する正確な方法と、どのように与えられた公開鍵から署名を検証するかを知っていなければなりません。

詳細については、ads.cert ベータ仕様 を参照してください。

 

列挙子

以降のリストでは、ペイロードオブジェクト内の各属性が参照する列挙子を定義します。

 

リスト:非入札理由コード

次の表では、商品への入札を行わなかった理由を、入札者が取引所へ知らせるために使用する選択肢を挙げます。

定義
0 未知のエラー
1 技術的なエラー
2 無効なリクエスト
3 既知の Web クローラ
4 人間によるものでない疑いのあるトラフィック
5 クラウド、データセンター、もしくはプロキシ IP
6 サポート外のデバイス
7 ブロック済みの配信者もしくはサイト
8 一致しないユーザ
9 1日当たりの上限にユーザが達した
10 1日当たりの上限にドメインが達した
11 Ads.txt 認証が利用できない
12 Ads.txt 認証に違反している
13 Ads.cert 認証が利用できない
14 Ads.cert 認証に違反している
15 オークション時間が足りなかった
500+ 取引所固有の値。この値は事前に買い手と打ち合わせておくべきである。

 

リスト:敗北理由コード

次の表では、商品を勝ち取ることが出来なかった理由を、取引所が入札者へ知らせるために使用する選択肢を挙げます。

定義
0 入札が勝利した
1 内部エラー
2 インプレッション機会が失効している
3 不当な入札レスポンス
4 不当な取引 ID
5 不当なオークション ID
6 不当な広告主ドメイン
7 マークアップが指定されていない
8 クリエイティブ ID が指定されていない
9 入札価格が指定されていない
10 最小クリエイティブ承認日時が指定されていない
100 入札がオークションのフロアプライス以下だった
101 入札が取引のフロアプライス以下だった
102 より高い入札に負けた
103 取引の入札に負けた
104 買い手シートがブロックされている
200 クリエイティブが除外された - 全般(理由不明)
201 クリエイティブが除外された - 取引所により処理が保留されている(承認、エンコード変換など)
202 クリエイティブが除外された - 取引所により承認されなかった
203 クリエイティブが除外された - 許容されないサイズである
204 クリエイティブが除外された - 誤ったクリエイティブフォーマット
205 クリエイティブが除外された - 広告主に基づく除外
206 クリエイティブが除外された - セキュアでない
207 クリエイティブが除外された - 言語に基づく除外
208 クリエイティブが除外された - カテゴリに基づく除外
209 クリエイティブが除外された - クリエイティブ属性に基づく除外
210 クリエイティブが除外された - 広告タイプに基づく除外
211 クリエイティブが除外された - アニメーションが長すぎる
212 クリエイティブが除外された - 取引において許容されない
500+ 取引所固有の値。この値は事前に買い手と打ち合わせておくべきである。

 

JSON を使って表現されたリクエスト・レスポンスペイロードのレイヤ3の例は、次の通りです。

 

入札リクエスト

販売提供された単一商品とそれに関連する単一非公開市場取引を含んだ、入札リクエストのレイヤ3の例です。簡潔にするために、一部の任意指定の属性は省略されています。speccontent は AdCOM 指定のドメインオブジェクトへのインタフェイスとなっています。spec オブジェクトは、この商品において提供されているインプレッションの詳細を運ぶ placement オブジェクトを一つ持つべきです。context オブジェクトは、deviceuserregsrestrictions のいずれか複数と、site(例で示されている)、appdooh のいずれかを多くとも一つ持つことができます。

{
   "openrtb": {
      "ver": "3.0",
      "domainspec": "adcom",
      "domainver": "1.0",
      "request": {
         "id": "0123456789ABCDEF",
         "tmax": 150,
         "at": 2,
         "cur": [ "USD", "EUR" ],
         "source": {
            "tid": "FEDCBA9876543210",
            "ts": 1541796182157,
            "ds": "AE23865DF890100BECCD76579DD4769DBBA9812CEE8ED90BF",
            "dsmap": "...",
            "cert": "ads-cert.1.txt",
            "pchain": "..."
         },
         "package": 0,
         "item": [
            {
               "id": "1",
               "qty": 1,
               "private": 0,
               "deal": [
                  {
                     "id": "1234",
                     "flr": 1.50
                  }
               ],
               "spec": {
                  "placement": {   }
               }
            }
         ],
         "context": {
            "site": {  AdCOM 仕様を参考のこと。 },
            "user": {  AdCOM 仕様を参考のこと。 },
            "device": {  AdCOM 仕様を参考のこと。 },
            "regs": {  AdCOM 仕様を参考のこと。 },
            "restrictions": {  AdCOM 仕様を参考のこと。 }
         }
      }
   }
}

 

入札レスポンス

入札レスポンスのレイヤ3の例です。response.idrequest.id と一致していることで、先述の入札リクエストの例を参照しており、bit の下にある bid.item 属性はリクエストの item.id を参照しており、bid.deal が含む取引の参照は、リクエスト内で提供される取引 deal.id を指しています。なお、media は AdCOM で指定されたドメインオブジェクトへのインタフェイスです。「media」オブジェクトは、入札が勝利した場合に配信される広告の詳細を保持する ad オブジェクトを一つ持つべきです。

この例では説明のために、動的な値を与えるマクロを含んだ事前アップロード済みメディアを参照する mid パラメータと、domain オブジェクトによる参照の両方を示しています。実際に、メディアは値(詳細をドメインオブジェクトに含んで)もしくは参照(メディア ID と任意指定のマクロを用いて)のいずれかの方法で受け渡されます。

{
   "openrtb": {
      "ver": "3.0",
      "domainspec": "adcom",
      "domainver": "1.0",
      "response": {
         "id": "0123456789ABCDEF",
         "bidid": "0011223344AABBCC",
         "seatbid": [
            {
               "seat": "XYZ",
               "bid": [
                  {
                     "id": "yaddayadda",
                     "item": "1",
                     "deal": "1234",
                     "price": 1.50,
                     "tactic": "...",
                     "purl": "...",
                     "burl": "...",
                     "lurl": "...",
                     "mid": "...",
                     "macro": [
                        {
                           "key": "TIMESTAMP",
                           "value": "1127987134"
                        },
                        {
                           "key": "CLICKTOKEN",
                           "value": "A7D800F2716DB"
                        }
                     ],
                     "media": {
                        "ad": {  AdCOM 仕様を参考のこと。  }
                     }
                  }
               ]
            }
         ]
      }
   }
}

付録 A:追加リソース

インタラクティブ広告局テクノロジーラボ(IAB テックラボ)
www.iabtechlab.com

クリエティブコモンズ・帰属ライセンス
creativecommons.org/licenses/by/3.0

GitHub の AdCOM プロジェクト
https://github.com/InteractiveAdvertisingBureau/AdCOM

OpenRTB v3.0 仕様
https://github.com/InteractiveAdvertisingBureau/openrtb

ads.cert 仕様
ads.cert ベータ仕様

ads.text 仕様
iabtechlab.com/ads-txt

JavaScript オブジェクト記法(JSON)
www.json.org/

Apache Avro
Avro.apache.org

Protocol Buffers (Protobuf)
github.com/google/protobuf

付録 B:変更履歴

この付録では、現行から過去のバージョンにおける仕様変更の索引を提供します。仕様の実質的な変更を対象としていて、定常的な文書整形、情報構成や技術的なインパクトのない内容に関する変更は含みません。

OpenRTB v3.0 は大幅な改訂のため、変更履歴は省略されます。

皆川 祥
皆川 祥Minagawa Sho
株式会社LOB DSP開発チームエンジニア


株式会社セガに新卒入社、PS3/PSPタイトルのプロジェクトに参加し車両物理・UIシステムの開発を経験する。 その後、株式会社インターネットイニシアティブで6年間勤務。 法人向けメールセキュリティサービスの開発チームで、レポート配信・全文検索システムの設計/実装を担当する。 2018年9月、楽天プラットフォーム上での広告システム構築という熱いミッションに惹かれ、LOB(※)に入社。新規機能開発やディレクション業務を担当。

 

※株式会社LOB:2016年4月設立、2018年7月、楽天グループの一員に。楽天の広告事業におけるテクノロジー部分を担うアドテク企業。楽天のデータを活用した広告プラットフォームの開発など、“流通のケタ“を変えるグローバルなプロダクト開発に挑んでいる。

INQUIRY楽天広告プロダクトに関するお問い合わせ