取引ライン アイテム API セットアップ ガイド

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

概要

ディール ライン アイテムは強力な機能であり、ネットワークとパブリッシャーのクライアントは、事前にパッケージ化されたユーザーフレンドリーな購入ツールを提供することで、購入者をより適切にサポートできます。

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

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

前提条件

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

操作の順序

API オブジェクトは他の API オブジェクトに依存していることが多く、ディール ライン アイテムを作成するときにオブジェクトの作成またはアクセスには従わなければならない順序があります。 たとえば、以下の API オブジェクトの ID を指定する必要があります。
- advertiser
- insertion-order
- deal
- profile.

これらのオブジェクトの 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 - 広告主を作成またはアクセスする

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

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

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

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

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

2. この広告主の JSON と適切なmember_idを使用して、https://api.appnexus.com/advertiser endpointに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 をメモします

広告掲載オーダー

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

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

シームレスな広告掲載オーダー用の JSON フィールド (必須フィールドと便利なオプション フィールド)

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

1. 広告掲載オーダーの JSON を作成します (2 つの例を次に示します):

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

   $ cat insertion-order-noenddate.json
   {
       "insertion-order": {
           "name": "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"
       }
   }
   

   JSON の例: フライト、インプレッション予算

   $ cat insertion-order-flights.json
   {
       "insertion-order": {
           "name": "Deal Line Item Example IO",
           "budget_intervals": [
   
               {
                   "start_date": "2019-10-10 00:00:00",
                   "end_date": "2019-10-12 23:59:59",
                   "daily_budget": null,
                   "daily_budget_imps": 10,
                   "enable_pacing": true,
                   "lifetime_budget": null,
                   "lifetime_budget_imps": 980,
                   "lifetime_pacing": false
               },
               {
                   "start_date": "2019-10-13 00:00:00",
                   "end_date": "2019-10-18 23:59:59",
                   "daily_budget": null,
                   "daily_budget_imps": 10,
                   "enable_pacing": true,
                   "lifetime_budget": null,
                   "lifetime_budget_imps": 100,
                   "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.appnexus.com/insertion-order?advertiser_id=2605036&member_id=2378'
   

   要求の例: フライト、インプレッション予算

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

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

4. 手順 6 - 取引品目の作成で取引品目を作成するときに使用できるように、応答本文の広告掲載オーダー ID をメモします。

Deal

手順 4 - 取引を作成する

取引品目に関連付ける取引を作成する必要があります。

取引の JSON フィールド

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

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

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

ブランドの例

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

言語 ( 「言語サービス」を参照)

言語の例

"language_restrict": true,
            "languages": [
                {
                    "id": 1,
                    "name": "English",
                    "override": false
                },
                {
                    "id": 2,
                    "name": "Chinese",
                    "override": true
                }
            ]

信頼レベル

信頼レベルの例

"audit_status_option": "max_trust" 

クリエイティブ カテゴリ

クリエイティブ カテゴリの例

"categories": [
                 {
                     "id": 1,
                     "name": "Airlines",
                     "override": false
                 },
                 {
                     "id": 2,
                     "name": "Apparel",
                     "override": true
                 }
             ],
             "category_restrict": true

特定のクリエイティブ

特定のクリエイティブの例

"creatives": [
                {
                    "id": 161501729,
                    "status": "banned"
                },
                {
                    "id": 161501882,
                    "status": "approved"
                }
            ]

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"
                 }
             ]

技術属性 ( 「技術属性サービス」を参照)

技術属性の例

"technical_attribute_restrict": false,
             "technical_attributes": [
                 {
                     "id": 1,
                     "name": "Image",
                     "override": true
                 }
             ]

取引データ保護用の JSON フィールド ( Visibility プロファイル サービスを参照)

ユーザー ID とデバイス ID

ユーザー ID とデバイス ID を保護する例

手順 1: 表示範囲プロファイルを作成する

> cat visibility_profile.json
{
    "visibility-profile": {
        "expose_device_id_default": false,
        "expose_user_id_default": false,
        "name": "Deal Visibility Profile"
    }
}
 
 
> curl -b cookies -c cookies -X POST -d @visibility_profile.json 'https://api.appnexus.com/visibility-profile?member_id=2378'

手順 2: 可視性プロファイルを取引に関連付け、データ保護を有効にする

> cat deal_data_protection.json
{
    "deal": {
        "visibility_profile_id": 29657,
        "data_protected": true
    }
}
 
 
> curl -b cookies -c cookies -X PUT -d @deal_data_protection.json 'https://api.appnexus.com/deal?id=549271'

IP アドレス

IP アドレスを保護する例

手順 1: 表示範囲プロファイルを作成する

> cat visibility_profile.json
{
    "visibility-profile": {
        "expose_ip_default": false,
        "ip_exposure_default": "truncated",
        "name": "Deal Visibility Profile - Hidden"
    }
}
 
 
> curl -b cookies -c cookies -X POST -d @visibility_profile.json 'https://api.appnexus.com/visibility-profile?member_id=2378'

手順 2: 可視性プロファイルを取引に関連付け、データ保護を有効にする

> cat deal_data_protection.json
{
    "deal": {
        "visibility_profile_id": 29657,
        "data_protected": true
    }
}
 
 
> curl -b cookies -c cookies -X PUT -d @deal_data_protection.json 'https://api.appnexus.com/deal?id=549271'

URL

ドメインの保護の例

手順 1: 表示範囲プロファイルを作成する

> cat visibility_profile.json
{
    "visibility-profile": {
        "name": "Deal Visibility Profile - Hidden",
        "url_exposure_default": "hidden"
    }
}
 
 
> curl -b cookies -c cookies -X POST -d @visibility_profile.json 'https://api.appnexus.com/visibility-profile?member_id=2378'

手順 2: 可視性プロファイルを取引に関連付け、データ保護を有効にする

> cat deal_data_protection.json
{
    "deal": {
        "visibility_profile_id": 29657,
        "data_protected": true
    }
}
 
 
> curl -b cookies -c cookies -X PUT -d @deal_data_protection.json 'https://api.appnexus.com/deal?id=549271'

セグメントに追加 ( ディール サービスを参照)

クリック時または表示時のセグメントへの追加を禁止する例の例

> cat add_segment.json
{
    "deal": {
        "allow_creative_add_on_click": false,
        "allow_creative_add_on_view": false
    }
}
 
 
> curl -b cookies -c cookies -X PUT -d @add_segment.json 'https://api.appnexus.com/deal?id=123456'

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

1. 取引 JSON の作成:

   $ cat deal.json
   {
       "deal": {
           "name": "Deal Line Item Example Deal",
           "buyer": {
               "id": 2379
           },
           "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 をメモします。

プロファイル

手順 5 - 取引ライン アイテム プロファイルの作成

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

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

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

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

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"
               }
           ],
           "max_day_imps": 10,
           "min_minutes_per_imp": 300
       }
   }
   

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

   > 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 をメモします。

ライン項目

手順 6 - 取引品目を作成する

最後に、取引品目を作成して、取引 ID と 、手順 5 - 取引品目プロファイルの作成で作成した取引品目プロファイルを関連付ける必要があります。

取引ライン アイテムの JSON フィールド

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

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

1. 取引広告申込情報 JSON を作成します (既存の広告主 ID、広告掲載オーダー ID、取引 ID、プロフィール ID が必要です)。

   JSON の例: 取引品目に予算がない

   > cat 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
           },
           "bid_object_type": "deal",
           "budget_intervals": [{
               "start_date": "2019-10-11 12:00:00"
           }],
           "deals": [{
               "id": 618159
           }],
           "insertion_orders": [{
               "id": 1363850
           }],
           "line_item_type": "standard_v2",
           "name": "Deal Line Item Example Line Item",
           "revenue_type": "vcpm",
           "revenue_value": null,
           "supply_strategies": {
               "managed": true
           },
           "profile_id": 112548354,
           "valuation": {
               "min_revenue_value": 10
           }
       }
   }
   

   JSON の例: 取引ライン アイテムの有効期間のインプレッション予算

   > cat deal_line_item_lifetime.json
   {
       "line-item": {
           "ad_types": ["video"],
           "auction_event": {
               "kpi_auction_type_id": 1,
               "payment_auction_type_id": 1,
               "revenue_auction_type_id": 1
           },
           "bid_object_type": "deal",
           "budget_intervals": [
                   {
                       "end_date": "2019-10-18 23:59:59",
                       "lifetime_budget_imps": 2586,
                       "start_date": "2019-10-11 12:00:00",
                       "timezone": "US/Pacific"
                   },
                   {
                       "end_date": "2019-10-25 23:59:59",
                       "lifetime_budget_imps": 2414,
                       "start_date": "2019-10-19 00:00:00",
                       "timezone": "US/Pacific"
                   }
               ],
           "deals": [{
               "id": 618159
           }],
           "insertion_orders": [{
               "id": 1363850
           }],
           "line_item_type": "standard_v2",
           "name": "Deal Line Item Example Line Item",
           "revenue_type": "vcpm",
           "revenue_value": null,
           "supply_strategies": {
               "managed": true
           },
           "profile_id": 112548354,
           "valuation": {
               "min_revenue_value": 10
           }
       }
   }
   

   JSON の例: 取引ライン アイテムの 1 日あたりの収益予算

   > cat 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
           },
           "bid_object_type": "deal",
           "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_type": "standard_v2",
           "name": "Deal Line Item Example Line Item",
           "revenue_type": "vcpm",
           "revenue_value": null,
           "supply_strategies": {
               "managed": true
           },
           "profile_id": 112548354,
           "valuation": {
               "min_revenue_value": 10
           }
       }
   }
   

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

     要求の例: 取引ライン アイテムに予算がない

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

     要求の例: 取引ライン アイテムの有効期間のインプレッション予算

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

     要求の例: 取引ライン アイテムの 1 日あたりの収益予算

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

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

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

関連トピック

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