キュレーションされた取引ライン アイテム API セットアップ ガイド

取引をターゲットとするキュレーションされた取引ライン アイテムの API 実装を設定するには、さまざまな API オブジェクトにさまざまなプロパティを構成する必要があります。 このガイドでは、API を使用してキュレーションされた取引ライン アイテムを作成および構成するプロセスについて説明します。

概要

キュレーションされた取引は、キュレーターの独自の資産と Xandr Marketplace の供給を組み合わせた、購入者とキュレーターの間の交渉による契約を表します。 これらの独自の資産には、対象ユーザー データ、優先在庫アクセス、特別に交渉された料金、最適化の人材、投資戦略、および取引供給を強化し、独自のサービスを作成するその他の機能が含まれます。 取引キュレーターは、Xandr プラットフォーム上に独自のメンバー シートを持ち、それを使用して、供給と自分の資産を購入者向けにキュレーションされた取引 ID にパッケージ化します。 Xandr 取引所に統合されている DSP は、キュレーションされた取引を購入できます。

キュレーションされた取引ライン アイテムを設定するには、通常、次の API サービス エンドポイントに要求を行い、対応する API オブジェクトにアクセスまたは作成する必要があります:

このガイドでは、すべてのリクエストについて cURL の例を使用します。 他の API リクエスト ツール ( Postman など) を使用することもできますが、その後適宜例を調整する必要があります。

前提条件

このセットアップを開始する前に、「API はじめに」を必ずお読みください。 テスト環境、使用上の制約、API セマンティクス (コマンドの実行、フィルター処理、並べ替えなど)、ベスト プラクティスに関する情報を提供します。

操作の順序

API オブジェクトは他の API オブジェクトに依存していることが多く、キュレーションされた取引品目を作成する際には、オブジェクトの作成またはアクセスにおいて従わなければならない順序があります。 たとえば、 advertiser、 insertion-order、 deal、 profile の API オブジェクトの ID を指定する必要があります。 これらのオブジェクトの ID を取得するには、それらを作成するか、既にアクセス権を持っている必要があります。 このガイドの手順は、キュレーションされた取引品目を作成するために必要な一般的な操作の順序に従います。

ベスト プラクティス

API を操作する際に従うベスト プラクティスの一般的な一覧については、「 API のベスト プラクティス」を参照してください。 以下は、キュレーションされた取引ライン アイテムの設定に固有のいくつかのベスト プラクティスです:

• 品目が完全に構成され、テストの準備が整うまで、キュレーションされた取引品目の state フィールドを "inactive" に設定します。
• 作成するオブジェクトの ID をメモします。 作成したオブジェクトの ID は、要求の応答本文で返されます。 多くの場合、これらの ID は後で必要になるため、返されたときにコピーすることで、ID を取得するために行う必要のある追加の GET 要求の数を減らすことができます。
• キュレーションされた取引品目内でキュレーションされた取引をターゲットにしないでください。 この構成はサポートされておらず、配信の問題が発生する可能性があります。

セットアップ手順

次の手順では、一般的な構成でキュレーションされた取引品目を設定するプロセスを説明します:

• 手順 1 - 承認トークンを取得する
• 手順 2 - 広告主を作成またはアクセスする
• ステップ 3 - 広告掲載オーダーを作成またはアクセスする
• 手順 4 - 取引を作成する
• 手順 5 - キュレーションされた取引ライン アイテム プロファイルを作成する
• 手順 6 - キュレーションされた取引品目を作成する

手順 1 - 承認トークンを取得する

まず、承認トークンを取得する必要があります。 その後、この承認トークンを後続のすべての要求に含める必要があります (詳細については 、「認証サービス 」を参照してください)。 承認トークンを取得するには、次の手順を実行します。

1. ユーザー名とパスワードを含む JSON ファイルを作成します。

   {
       "auth": {
           "username" : "USERNAME",
           "password" : "PASSWORD"
       }
   }
   

2. 要求本文にこの JSON ファイルを含め、/auth エンドポイントにPOST要求を行います (詳細については、「認証サービス」を参照してください)。 次のcURL要求では、返された承認トークンは "cookies" ファイルに格納されます。

   curl -c cookies -X POST -d @authentication.json 'https://api.appnexus.com/auth'
   

3. 要求の応答本文を確認します (下記 の応答の例 を参照)。 要求が成功した場合は、"status" が "OK" になり、"token" フィールドに認証トークンの値が入力されます。
   
   応答の例

   {
      "response" : {
         "token" : "authn:225692:2d787d1838283:lax1",
         "status" : "OK"      
      }
   }
   

手順 2 - 広告主を作成またはアクセスする

キュレーションされた取引ライン アイテムを作成するには、広告主を作成するか、広告主にアクセスする必要があります。 拡張広告申込情報の場合と同じ方法で、キュレーションされた取引ライン アイテムの広告主を設定します。

使用する広告主がまだない場合は、次の手順を実行して広告主を作成します (詳細については、「 広告主サービス 」を参照してください)。

1. 広告主の JSON を作成します。

   $ cat advertiser.json
   {
       "advertiser": {
           "name": "Curated Deal Line Item Example Advertiser",
           "timezone": "US/Pacific"
       }
   }
   

2. この広告主の JSON と適切なmember_idを使用して、https://api.appnexus.com/advertiser エンドポイントにPOST要求を行います。

   $ curl -b cookies -c cookies -X POST -d @advertiser.json 'https://api.appnexus.com/advertiser?member_id=2378'
   

3. 要求の応答本文を確認します。 要求が成功した場合は、"OK" の "status" が表示され、行った更新が表示されます。

4. 手順 6 - キュレーションされた取引品目を作成するでキュレーションされた取引品目を作成するときに使用できるように、応答本文の広告主 ID をメモします。

広告主用の JSON フィールド (必須フィールドと役立つオプション フィールド)

ステップ 3 - 広告掲載オーダーを作成またはアクセスする

キュレーションされた取引ライン アイテムを作成するには、広告掲載オーダーを作成するか、広告掲載オーダーにアクセスする必要があります。 キュレーションされた取引ライン アイテムには、シームレスな広告掲載オーダーが必要です (以下の 必須 フィールドを参照してください)。

使用する広告掲載オーダーがまだない場合は、次の手順を実行して広告掲載オーダーを作成します (詳細については、「 広告掲載オーダー サービス 」を参照してください)。

1. 広告掲載オーダー JSON を作成する:

   JSON の例: 終了日なし、予算なし

   $ cat insertion-order-noenddate.json
   {
       "insertion-order": {
           "name": "Curated Deal Line Item Example IO",
           "budget_intervals": [{
               "start_date": "2019-10-10 00:00:00",
               "end_date": null,
               "daily_budget": null,
               "daily_budget_imps": null,
               "enable_pacing": true,
               "lifetime_budget": null,
               "lifetime_budget_imps": null,
               "lifetime_pacing": false
           }],
           "budget_type": "impression"
       }
   }
   

2. この広告掲載オーダー JSON と適切なadvertiser_idとmember_idを使用して、https://api.appnexus.com/insertion-order エンドポイントにPOST要求を行います。

   要求の例: 終了日なし、予算なし

   $ curl -b cookies -c cookies -X POST -d @insertion-order-noenddate.json 'https://api..com/insertion-order?advertiser_id=2605036&member_id=2378'
   

3. 要求の応答本文を確認します。 要求が成功した場合は、"OK" の "status" が表示され、行った更新が表示されます。

4. 手順 6 - キュレーションされた取引ライン アイテムの作成でキュレーションされた取引ライン アイテムを作成するときに使用できるように、応答本文の広告掲載オーダー ID をメモします。

シームレスな広告掲載オーダーの JSON フィールド

手順 4 - 取引を作成する

キュレーションされた取引品目に関連付ける取引を作成する必要があります。

取引を作成するには、次の手順を実行します (詳細については、「 取引サービス 」を参照してください)。

1. 取引 JSON の作成:

   $ cat deal.json
   {
       "deal": {
           "name": "Curated Deal",
           "buyer": {
               "id": 2379
           },
           "type": {
               "id": 5,
               "name": "Curated"
           },
           "version": 2
       }
   }
   

2. この取引 JSON と適切なmember_idを使用して、https://api.appnexus.com/deal エンドポイントにPOST要求を行います。

   $ curl -b cookies -c cookies -X POST -d @deal.json 'https://api.appnexus.com/deal?member_id=2378'
   

3. 要求の応答本文を確認します。 要求が成功した場合は、"OK" の "status" が表示され、行った更新が表示されます。

4. 手順 6 - キュレーションされた取引品目の作成で取引品目を作成するときに使用できるように、応答本文の取引 ID をメモします。

取引の JSON フィールド

便利なオプションの JSON フィールド

許可されているクリエイティブの JSON フィールド

ブランド ( 「ブランド サービス」を参照)

ブランドの例

"brand_restrict": true,
            "brands": [
                {
                    "id": 2,
                    "name": "1800Flowers",
                    "override": true
                },
                {
                    "id": 4,
                    "name": "Acura",
                    "override": false
                }
            ] 

Media type ( 「Media Subtype Service 」および 「Media Type Service」を参照)

メディア タイプの例

"allowed_media_subtypes": [
                 {
                     "id": 2,
                     "last_modified": "2015-09-17 19:19:21",
                     "media_type": {
                         "id": 2,
                         "media_type_group_id": 2,
                         "name": "Pop",
                         "uses_sizes": "sometimes"
                     },
                     "name": "Popup",
                     "native_assets": null,
                     "permitted_sizes": null
                 }
             ],
 "allowed_media_types": [
                 {
                     "id": 1,
                     "last_modified": "2012-03-16 21:36:10",
                     "media_type_group_id": 1,
                     "name": "Banner",
                     "uses_sizes": "always"
                 },
                 {
                     "id": 4,
                     "last_modified": "2016-08-22 16:23:12",
                     "media_type_group_id": 1,
                     "name": "Video",
                     "uses_sizes": "never"
                 }
             ]

手順 5 - キュレーションされた取引ライン アイテム プロファイルを作成する

次に、キュレーションされた取引品目によるターゲティングに使用するキュレーションされた取引品目プロファイルを作成します。 後で使用できるように、このプロファイルの ID を必ずメモしておいてください。 詳細については 、「プロファイル サービス」 を参照してください。

キュレーションされた取引ライン アイテム プロファイルを作成するには、次の手順を実行します (詳細については、「 プロファイル サービス 」を参照してください)。

1. キュレーションされた取引ライン アイテム プロファイル JSON を作成します:

   例: 国とビュー レートの完了率のしきい値を含むプロファイル作成

   $ cat profile.json
   
   {
           "profile": {
                   "country_action": "include",
                   "country_targets": [{
                           "active": true,
                           "code": "US",
                           "id": 233,
                           "name": "United States"
                   }],
                   "engagement_rate_targets": [{
                                   "engagement_rate_pct": 25,
                                   "engagement_rate_type": "video_completion"
                           },
                           {
                                   "engagement_rate_pct": 50,
                                   "engagement_rate_type": "predicted_iab_video_view_rate"
                           }
                   ],
                   "platform_publisher_targets": [{
                           "action": "include",
                           "deleted": false,
                           "id": 1238721,
                           "name": "test_publisher"
                   }],
                   "platform_placement_targets": [{
                                   "action": "include",
                                   "deleted": false,
                                   "id": 5126395
                           },
                           {
                                   "action": "include",
                                   "deleted": false,
                                   "id": 5301719
                           }
                   ],
                   "platform_content_category_targets": [{
                           "action": "include",
                           "deleted": false,
                           "id": 19062,
                           "is_system": false,
                           "name": "1"
                   }]
           }
   }
   

   例: ターゲティングなしのプロフィール作成

   > cat profile.json
   
   {
       "profile": {
       }
   }
   

2. このキュレーションされた取引プロファイル JSON と適切なadvertiser_idを使用して、https://api.appnexus.com/profile エンドポイントにPOST要求を行います。

   例: 国とビュー レートの完了率のしきい値を含むプロファイル作成

   > curl -b cookies -c cookies -X POST -d @profile.json 'https://api.appnexus.com/profile?advertiser_id=3410892&member_id=2378'
   

   例: ターゲティングなしのプロフィール作成

   > curl -b cookies -c cookies -X POST -d @profile.json 'https://api.appnexus.com/profile?advertiser_id=3410892&member_id=2378'
   

3. 要求の応答本文を確認します。 要求が成功した場合は、"OK" の "status" が表示され、行った更新が表示されます。

4. 手順 6 - キュレーションされた取引品目を作成するでキュレーションされた取引品目を作成するときに使用できるように、応答本文のプロファイル ID をメモします。

取引ライン アイテム プロファイルのオプションの JSON フィールド

キュレーションされた取引ライン アイテム プロファイルには、キュレーションされた取引ライン項目でターゲット設定するために使用できるオプション フィールドが多数あります。 たとえば、インベントリ、インベントリの種類、許可リスト、ブロックリスト、デバイスの種類などに関連するプロパティをターゲットにすることができます。 使用可能なフィールドについて詳しくは、 プロファイルサービス を参照してください。

手順 6 - キュレーションされた取引品目を作成する

最後に、キュレーションされた取引ライン アイテムを作成して、取引 ID と 、手順 5 - キュレーションされた取引ライン アイテム プロファイルの作成で作成したキュレーションされた取引ライン アイテム プロファイルを関連付ける必要があります。

キュレーションされた取引ライン アイテムを作成するには、次の手順を実行します (詳細については 、「ライン アイテム サービス 」を参照してください)。

1. キュレーションされた取引品目 JSON を作成します (既存の広告主 ID、広告掲載オーダー ID、取引 ID、プロフィール ID が必要です)。

   JSON の例: キュレーションされた取引ライン アイテムに予算がない

   > cat curated_deal_line_item.json
   {
           "line-item": {
                   "ad_types": ["video"],
                   "auction_event": {
                           "kpi_auction_type_id": 1,
                           "payment_auction_type_id": 1,
                           "revenue_auction_type_id": 1
                   },
                   "budget_intervals": [{
                           "start_date": "2019-10-11 12:00:00"
                   }],
                   "deals": [{
                           "id": 628539
                   }],
                   "insertion_orders": [{
                           "id": 1363850
                   }],
                   "line_item_subtype": "standard_curated",
                   "name": "Curated Deal Line Item Example Line Item",
                   "revenue_type": "vcpm",
                   "revenue_value": null,
                   "supply_strategies": {
                           "managed": false,
                           "deals": true,
                           "rtb": false
                   },
                   "profile_id": 113067333,
                   "valuation": {
                           "min_revenue_value": 10
                   }
           }
   }
   

   JSON の例: キュレーションされた取引ライン アイテムの 1 日あたりの収益予算

   > cat curated_deal_line_item_daily.json
   {
           "line-item": {
                   "ad_types": ["video"],
                   "auction_event": {
                           "kpi_auction_type_id": 1,
                           "payment_auction_type_id": 1,
                           "revenue_auction_type_id": 1
                   },
                   "budget_intervals": [{
                           "daily_budget_imps": 270,
                           "end_date": "2019-10-18 23:59:59",
                           "start_date": "2019-10-11 12:00:00",
                           "timezone": "US/Pacific"
                   }],
                   "deals": [{
                           "id": 618159
                   }],
                   "insertion_orders": [{
                           "id": 1363850
                   }],
                   "line_item_subtype": "standard_curated",
                   "name": "Curated Deal Line Item Example Line Item",
                   "revenue_type": "vcpm",
                   "revenue_value": null,
                   "supply_strategies": {
                           "managed": true,
                           "deals": true,
                           "rtb": false
                   },
                   "profile_id": 113067333,
                   "valuation": {
                           "min_revenue_value": 10
                   }
           }
   }
   

2. この取引ライン アイテム JSON と適切なadvertiser_idを使用して、https://api.appnexus.com/line-itemエンドポイントにPOST要求を行います。

   要求の例: キュレーションされた取引ライン アイテムの予算なし

   > curl -b cookies -c cookies -X POST -d @curated_deal_line_item.json 'https://api.appnexus.com/line-item?member_id=2378&advertiser_id=3410892'
   

   要求の例: キュレーションされた取引ライン アイテムの 1 日あたりの収益予算

   > curl -b cookies -c cookies -X POST -d @curated_deal_line_item_daily.json 'https://api.appnexus.com/line-item?member_id=2378&advertiser_id=3410892'
   

3. 要求の応答本文を確認します。 要求が成功した場合は、"OK" の "status" が表示され、行った更新が表示されます。

4. このキュレーションされた取引ライン アイテムを後で特定して、その state (active または inactive) を変更したり変更したりできるように、応答本文のライン アイテム ID をメモします。

キュレーションされた取引品目の JSON フィールド

フィールド line_item_subtype メモ

line_item_subtypeフィールドを "standard_curated" に設定すると、これらの関連フィールドに次の値が自動的に割り当てられます。

"line_item_type": "standard_v2",
"bid_object_type": "deal",
"delivery_model_type": "standard",
"supply_strategies": {
"managed": false,
"programmatic_guaranteed": false
}

line_item_subtypeフィールド (および関連するフィールド/配列) は、明細行品目の作成後は変更できません。

キュレーションされた取引ライン アイテムに便利なオプションの JSON フィールド

関連トピック

• API はじめに
• API のベスト プラクティス
• API セマンティクス
• ディール サービス
• ライン アイテム サービス (ALI)
• プロファイル サービス