Skip to main content

​
概要

サンドボックスモードを使用すると、バイヤーは実際のプラットフォームコールや実際の費用なしに、メディア購入のライフサイクル全体 — 発見、キャンペーン作成、クリエイティブ、配信 — をテストできます。レスポンスにはシミュレートされたが現実的なデータが含まれます。 サンドボックスはリクエストごとではなくアカウントレベルで機能します。リクエストがサンドボックスアカウントを参照すると、リクエスト全体がサンドボックスとして扱われる。これにより、マルチステップフローで実際のトラフィックとテストトラフィックを誤って混在させるリスクを排除します。

​
ケイパビリティの発見

セラーは get_adcp_capabilities でサンドボックスサポートを宣言する: 
{
  "account": {
    "sandbox": true
  }
}
サンドボックスモードを使用する前にこれを確認します。account.sandbox が宣言されていないか false の場合、セラーはサンドボックスをサポートしていません。

​
サンドボックスへの2つの経路

サンドボックスモードへの入り方は、セラーのアカウントモデル（require_operator_auth）によって異なります。2つの経路はまったく異なる — 正しい方に従うようにすること。

​
暗黙的アカウント（require_operator_auth: false）

セラーはエージェントを信頼し、オペレーターごとの認証を必要としません。サンドボックスはナチュラルキーの一部だ — 同じブランド/オペレーターのペアがプロダクションとサンドボックスの両方のアカウントを持つことができ、sandbox: true で区別されます。 セットアップ: アカウントエントリに sandbox: true を付けて sync_accounts でサンドボックスアカウントを宣言する: 
// sync_accounts — サンドボックスアカウントを宣言する
{
  "accounts": [{
    "brand": { "domain": "acme-corp.com" },
    "operator": "acme-corp.com",
    "billing": "operator",
    "sandbox": true
  }]
}
使用方法: すべてのリクエストで sandbox: true を付けたナチュラルキーでサンドボックスアカウントを参照する: 
// get_products — 暗黙的サンドボックス
{
  "account": {
    "brand": { "domain": "acme-corp.com" },
    "operator": "acme-corp.com",
    "sandbox": true
  },
  "brief": "Premium CTV inventory for Q2 campaign"
}

​
明示的アカウント（require_operator_auth: true）

セラーは各オペレーターが直接認証することを要求します。サンドボックスアカウントはセラーのプラットフォーム上の既存のテストアカウントだ — Stripe のテストモード、Google Ads サンドボックスアカウント、Snap のテスト広告主アカウントのようなもの。作成するのではなく、発見します。 セットアップ: sandbox: true フィルターを使って list_accounts でサンドボックスアカウントを発見する: 
// list_accounts — サンドボックスアカウントを探す
{
  "sandbox": true
}
セラーは既存のテストアカウントを返します: 
{
  "accounts": [{
    "account_id": "acct_sandbox_acme_001",
    "name": "Acme Test Account",
    "status": "active",
    "sandbox": true
  }]
}
使用方法: すべてのリクエストで account_id でサンドボックスアカウントを参照する: 
// get_products — 明示的サンドボックス
{
  "account": { "account_id": "acct_sandbox_acme_001" },
  "brief": "Premium CTV inventory for Q2 campaign"
}

​
クイックリファレンス

暗黙的（require_operator_auth: false）明示的（require_operator_auth: true）
サンドボックスアカウントバイヤーが sync_accounts で宣言セラーのプラットフォームに既存
発見方法N/A — バイヤーが作成sandbox: true で list_accounts
アカウント参照sandbox: true を持つナチュラルキーaccount_id
実世界の類似セルフサービステストモードStripe テストモード、Google Ads サンドボックス

​
レスポンスの確認

成功レスポンスには sandbox: true が含まれ、リクエストがサンドボックスモードで処理されたことを確認します: 
{
  "products": [...],
  "sandbox": true
}

​
完全なライフサイクルの例（暗黙的アカウント）

この例は暗黙的アカウントのパスを示します。明示的アカウントの場合、各ステップのナチュラルキーアカウント参照を { "account_id": "acct_sandbox_acme_001" } に置き換える。

​
1. 商品の発見

// get_products
{
  "account": {
    "brand": { "domain": "acme-corp.com" },
    "operator": "acme-corp.com",
    "sandbox": true
  },
  "brief": "CTV inventory for brand awareness"
}

​
2. メディアバイの作成

// create_media_buy
{
  "account": {
    "brand": { "domain": "acme-corp.com" },
    "operator": "acme-corp.com",
    "sandbox": true
  },
  "proposal_id": "prop_abc",
  "total_budget": { "amount": 50000, "currency": "USD" },
  "brand": { "domain": "acme-corp.com" },
  "start_time": { "start_type": "asap" },
  "end_time": "2026-04-01T00:00:00Z"
}
セラーはリアルな ID、パッケージ、クリエイティブ締め切りを持つシミュレートされたメディアバイを返す — 実際のプラットフォームには何も予約されない。

​
3. クリエイティブのアップロード

// sync_creatives
{
  "account": {
    "brand": { "domain": "acme-corp.com" },
    "operator": "acme-corp.com",
    "sandbox": true
  },
  "creatives": [{
    "creative_id": "hero_video_30s",
    "name": "Brand Hero Video 30s",
    "format_id": {
      "agent_url": "https://creative.adcontextprotocol.org",
      "id": "video_standard_30s"
    },
    "assets": {
      "video": {
        "url": "https://cdn.example.com/hero.mp4",
        "width": 1920,
        "height": 1080,
        "duration_ms": 30000
      }
    }
  }],
  "assignments": {
    "hero_video_30s": ["pkg_001"]
  }
}

​
4. 配信の確認

// get_media_buy_delivery
{
  "account": {
    "brand": { "domain": "acme-corp.com" },
    "operator": "acme-corp.com",
    "sandbox": true
  },
  "media_buy_ids": ["mb_sandbox_123"]
}
セラーはシミュレートされた配信メトリクス — インプレッション、スペンド、ペーシング — をキャンペーンが実行中であるかのように返します。

​
サンドボックス vs ドライラン

一部のタスク（例: sync_creatives）は dry_run パラメータもサポートします。これらは異なる目的を持ちます:
サンドボックスアカウントdry_run
意味何も実際ではない変更を適用せずにプレビュー
スコープすべてのタスクsync_creatives のみ
副作用なし（シミュレート）なし（プレビューのみ）
ユースケース完全なライフサイクルのテスト同期が何を変えるかを確認

​
セラーの実装

リクエストがサンドボックスアカウントを参照する場合（ナチュラルキーの sandbox: true またはサンドボックスの account_id を通じて）:
  • 実際の広告プラットフォーム API コール（実際の注文、ラインアイテムなど）を行わない
  • 実際のお金を請求したり、実際の請求レコードを作成しない
  • プロダクションと同じ方法で入力を検証する（無効な予算、不正な日付などを拒否します）
  • シミュレートされたデータを含むリアルなレスポンスシェイプを返す
  • 成功レスポンスに sandbox: true を含めるべきだ (SHOULD)
サンドボックスのエラーは実際の検証エラーです。バイヤーがサンドボックスアカウントを使用して無効な予算を送信した場合、実際のエラーを返す — 偽のエラーをシミュレートしません。 明示的アカウントのセラー: プラットフォームに list_accounts が sandbox: true でフィルタリングした際に返すことができる既存のサンドボックス/テストアカウントがあることを確認します。 暗黙的アカウントのセラー: sync_accounts とアカウント参照でナチュラルキーの一部として sandbox: true を受け入れる。(brand, operator, sandbox: true) を (brand, operator) とは別のアカウントとして扱います。

​
プロトコルコンプライアンス

ケイパビリティで account.sandbox: true を宣言するセラーは以下をしなければなりません (MUST):
  • アカウントモデルに適したサンドボックスアカウントを受け入れる
  • サンドボックスアカウントを参照するすべてのリクエストにサンドボックスセマンティクスを適用します
  • 通常の入力検証を適用する（サンドボックスは検証をバイパスしない）
セラーはサンドボックスアカウントリクエストを処理する際に成功レスポンスに sandbox: true を含めるべきだ (SHOULD)。