AdCP — sync_event

コンバージョントラッキングのためにセラーアカウントにイベントソースを設定します。ソースは、ウェブサイトピクセル、モバイル SDK、サーバー間フィード、CRM インポートのようなバイヤー管理の連携でも、チャンネル、プロフィール、フィード、ポッドキャスト、ニュースレターリストのようなセラーやプラットフォームネイティブの自社プロパティでもかまいません。アップサートセマンティクス、セラー管理ソース、セットアップ手順をサポートします。 レスポンス時間: 約1秒（同期設定） リクエストスキーマ: /schemas/v3/media-buy/sync-event-sources-request.json レスポンススキーマ: /schemas/v3/media-buy/sync-event-sources-response.json

クイックスタート

購入トラッキング用のイベントソースを設定します：

import { testAgent } from "@adcp/sdk/testing";
import { SyncEventSourcesResponseSchema } from "@adcp/sdk";

const result = await testAgent.syncEventSources({
  account: { account_id: "acct_12345" },
  event_sources: [
    {
      event_source_id: "website_pixel",
      name: "Main Website Pixel",
      event_types: ["purchase", "lead", "add_to_cart"],
      allowed_domains: ["www.example.com", "shop.example.com"],
    },
  ],
});

if (!result.success) {
  throw new Error(`Request failed: ${result.error}`);
}

// レスポンスをスキーマに対して検証する
const validated = SyncEventSourcesResponseSchema.parse(result.data);

// まず操作レベルのエラーを確認する（判別共用体）
if ("errors" in validated && validated.errors) {
  throw new Error(`Operation failed: ${JSON.stringify(validated.errors)}`);
}

if ("event_sources" in validated) {
  for (const source of validated.event_sources) {
    console.log(`${source.event_source_id}: ${source.action}`);
    if (source.setup?.snippet) {
      console.log(`  Install: ${source.setup.snippet_type}`);
    }
  }
}

import asyncio
from adcp.testing import test_agent

async def main():
    result = await test_agent.simple.sync_event_sources(
        account={'account_id': 'acct_12345'},
        event_sources=[{
            'event_source_id': 'website_pixel',
            'name': 'Main Website Pixel',
            'event_types': ['purchase', 'lead', 'add_to_cart'],
            'allowed_domains': ['www.example.com', 'shop.example.com']
        }]
    )

    # まず操作レベルのエラーを確認する
    if hasattr(result, 'errors') and result.errors:
        raise Exception(f"Operation failed: {result.errors}")

    for source in result.event_sources:
        print(f"{source.event_source_id}: {source.action}")
        if source.setup and source.setup.snippet:
            print(f"  Install: {source.setup.snippet_type}")

asyncio.run(main())

リクエストパラメータ

パラメータ	型	必須	説明
`account`	account-ref	はい	アカウント参照。`{ "account_id": "..." }` を渡すか、セラーが暗黙的な解決をサポートしている場合は `{ "brand": {...}, "operator": "..." }` を渡します。
`event_sources`	EventSource[]	いいえ	同期するイベントソース。省略した場合、呼び出しはディスカバリーのみとなり、変更なしに既存のすべてのイベントソースを返します。
`delete_missing`	boolean	いいえ	true の場合、このリクエストに含まれていないアカウント上のバイヤー管理イベントソースが削除されます（デフォルト: false）。

イベントソースオブジェクト

フィールド	型	必須	説明
`event_source_id`	string	はい	このイベントソースの一意の識別子
`name`	string	いいえ	人が読める名前
`event_types`	EventType[]	いいえ	このソースが処理するイベントタイプ。省略した場合、すべてのイベントタイプを受け入れる。
`action_source`	ActionSource	いいえ	互換性のためのフラットなソースカテゴリ（`website`、`app`、`system_generated` など）。フラット値が粗すぎる場合は `surface` と組み合わせます。
`allowed_domains`	string[]	いいえ	このソースへのイベント送信が許可されたドメイン
`surface`	EventSurface	いいえ	このソースが表す構造化されたサーフェス（自社チャンネル、プロフィール、フィード、ポッドキャスト、ニュースレターリスト、ウェブサイト、アプリ、店舗など）

レスポンス

成功レスポンス:

event_sources - 同期済みのソースとアカウント上のセラー管理ソースの両方を含む、各イベントソースの結果

エラーレスポンス:

errors - 操作レベルのエラーの配列（認証失敗、アカウントが見つからないなど）

注意: レスポンスは判別共用体を使用しており、成功フィールドまたはエラーのいずれかが返され、両方が同時に返されることはない。 成功レスポンス内の各イベントソースには以下が含まれます:

すべてのリクエストフィールド
seller_id - このイベントソースのセラー割り当て識別子
action - 実行された操作: created、updated、unchanged、deleted、failed
action_source - イベントソースの種別（ウェブサイトピクセル、アプリ SDK など）
surface - フラットな action_source が粗すぎる場合に、このソースが表す構造化されたサーフェス
managed_by - このソースの管理者: buyer または seller
setup - 実装の詳細（スニペット、手順）
health - イベントソースの健全性評価（セラーが健全性スコアリングをサポートする場合）
errors - ソースごとのエラー（action: "failed" の場合のみ）
ext - ソースごとの拡張メタデータ（プラットフォームネイティブのコンバージョン ID、アトリビューションウィンドウのハンドル、生の起点文字列など）

完全なフィールド一覧はスキーマを参照: sync-event-sources-response.json

イベントソースの健全性

イベントソースの品質を評価するセラーは、レスポンスの各ソースに health オブジェクトを含めます。これは Snap の Event Quality Score や Meta の Event Match Quality に相当します——バイヤーのイベント連携が最適化に十分な程度に機能しているかを伝えます。

フィールド	型	説明
`status`	string	AdCP 標準の健全性レベル: `insufficient`、`minimum`、`good`、`excellent`。セラー横断の判断に使用します。
`detail`	object	セラー固有のスコアリング（任意）。`score`、`max_score`、任意の `label` を含みます。セラーがネイティブな品質スコアを持つ場合にのみ存在します。
`match_rate`	number	広告インタラクションに一致したイベントの割合（0.0〜1.0）。
`last_event_at`	date-time	受信した最新イベントのタイムスタンプ。
`evaluated_at`	date-time	この健全性評価が計算された時刻。レポートデータから計算するセラーでは古くなります。
`events_received_24h`	integer	過去 24 時間に受信したイベント数（0 = 発火していない）。
`issues`	array	severity（`error`、`warning`、`info`）とメッセージを持つ実行可能な問題。severity でソートすること——配列の位置に頼らないこと。

test=false

{
  "event_sources": [
    {
      "event_source_id": "web_pixel",
      "action": "unchanged",
      "managed_by": "buyer",
      "health": {
        "status": "good",
        "detail": { "score": 7.2, "max_score": 10, "label": "Event Match Quality" },
        "match_rate": 0.72,
        "last_event_at": "2026-03-23T14:22:00Z",
        "evaluated_at": "2026-03-23T14:30:00Z",
        "events_received_24h": 14200,
        "issues": [
          {
            "severity": "warning",
            "message": "Missing hashed_email parameter on 38% of purchase events. Adding this improves match rate for cross-device attribution."
          }
        ]
      }
    }
  ]
}

バイヤーエージェントは、detail.score ではなく status を判断の基準にすべきです。四段階のステータスはすべてのセラー間で比較可能です——バイヤーエージェントは、どこでも機能する一つのルール（「DR プロダクトには good 以上を要求する」）を書きます。detail オブジェクトは人間向けダッシュボードや高度な診断のためのものです。バイヤーエージェントは健全性データを次のように活用できます:

イベント品質でプロダクト選択をゲートする（例: DR プロダクトには good 以上を要求）
キャンペーンのローンチ前にセットアップの問題をバイヤーに提示する
どのイベントソースを最初に修正すべきか優先順位付けする

よくある使用例

ディスカバリーのみ

変更を加えずにアカウント上のすべてのイベントソース（セラー管理ソースを含む）を検出します。セラーが常時オンのアトリビューションを提供するプラットフォーム管理のコンバージョントラッキングに便利：

import { testAgent } from "@adcp/sdk/testing";
import { SyncEventSourcesResponseSchema } from "@adcp/sdk";

const result = await testAgent.syncEventSources({
  account: { account_id: "acct_12345" },
});

if (!result.success) {
  throw new Error(`Request failed: ${result.error}`);
}

const validated = SyncEventSourcesResponseSchema.parse(result.data);

if ("errors" in validated && validated.errors) {
  throw new Error(`Operation failed: ${JSON.stringify(validated.errors)}`);
}

if ("event_sources" in validated) {
  for (const source of validated.event_sources) {
    console.log(`${source.event_source_id} (${source.managed_by}): ${source.name}`);
  }
}

import asyncio
from adcp.testing import test_agent

async def main():
    result = await test_agent.simple.sync_event_sources(
        account={'account_id': 'acct_12345'}
    )

    if hasattr(result, 'errors') and result.errors:
        raise Exception(f"Operation failed: {result.errors}")

    for source in result.event_sources:
        print(f"{source.event_source_id} ({source.managed_by}): {source.name}")

asyncio.run(main())

複数のイベントソース

ウェブサイトとアプリ用に個別のソースを設定します：

import { testAgent } from "@adcp/sdk/testing";
import { SyncEventSourcesResponseSchema } from "@adcp/sdk";

const result = await testAgent.syncEventSources({
  account: { account_id: "acct_12345" },
  event_sources: [
    {
      event_source_id: "web_pixel",
      name: "Website Pixel",
      event_types: ["purchase", "lead", "add_to_cart", "view_content"],
      allowed_domains: ["www.example.com"],
    },
    {
      event_source_id: "app_sdk",
      name: "Mobile App SDK",
      event_types: ["purchase", "app_install", "app_launch"],
    },
  ],
});

if (!result.success) {
  throw new Error(`Request failed: ${result.error}`);
}

const validated = SyncEventSourcesResponseSchema.parse(result.data);

if ("errors" in validated && validated.errors) {
  throw new Error(`Operation failed: ${JSON.stringify(validated.errors)}`);
}

if ("event_sources" in validated) {
  for (const source of validated.event_sources) {
    console.log(`${source.event_source_id} (${source.managed_by}): ${source.action}`);
  }
}

import asyncio
from adcp.testing import test_agent

async def main():
    result = await test_agent.simple.sync_event_sources(
        account={'account_id': 'acct_12345'},
        event_sources=[
            {
                'event_source_id': 'web_pixel',
                'name': 'Website Pixel',
                'event_types': ['purchase', 'lead', 'add_to_cart', 'view_content'],
                'allowed_domains': ['www.example.com']
            },
            {
                'event_source_id': 'app_sdk',
                'name': 'Mobile App SDK',
                'event_types': ['purchase', 'app_install', 'app_launch']
            }
        ]
    )

    if hasattr(result, 'errors') and result.errors:
        raise Exception(f"Operation failed: {result.errors}")

    for source in result.event_sources:
        print(f"{source.event_source_id} ({source.managed_by}): {source.action}")

asyncio.run(main())

セラー管理ソースの検出

セラーは常時オンのイベントソース（例: Amazon 売上アトリビューション）を提供する場合があります。これらはバイヤー管理ソースと並んで managed_by: "seller" としてレスポンスに表示されます：

test=false

{
  "event_sources": [
    {
      "event_source_id": "web_pixel",
      "name": "Website Pixel",
      "seller_id": "px_abc123",
      "action": "created",
      "managed_by": "buyer",
      "setup": {
        "snippet": "<script src=\"https://seller.example/pixel/px_abc123.js\"></script>",
        "snippet_type": "javascript",
        "instructions": "Place this tag in the <head> of all pages where you want to track events."
      }
    },
    {
      "event_source_id": "seller_sales_attribution",
      "name": "Sales Attribution",
      "seller_id": "internal_attr",
      "action": "unchanged",
      "managed_by": "seller",
      "action_source": "in_store"
    }
  ]
}

conversion_tracking.platform_managed: true を持つプロダクトは、セラーがこれらのソースを提供していることを示しています。

クリエイターおよび自社プロパティのソース

セラー管理のクリエイターまたは自社プロパティのソースは、互換性のためのフラットな action_source と構造化されたコンテキストのための surface を伴って、同じ event_sources 配列を使います:

test=false

{
  "event_sources": [
    {
      "event_source_id": "creator_channel",
      "name": "Creator Channel Events",
      "seller_id": "creator_attr_001",
      "event_types": ["follow", "content_view", "watch_milestone"],
      "action_source": "system_generated",
      "surface": {
        "category": "owned_property",
        "property_type": "channel",
        "namespace": "video_platform",
        "property_id": "channel_123"
      },
      "managed_by": "seller",
      "action": "unchanged",
      "ext": {
        "video_platform": {
          "native_origin": "owned_channel"
        }
      }
    }
  ]
}

チャンネル、プロフィール、フィード、リスト、ポッドキャストへの無料で継続的なオプトインには follow を使います。有料の購読または有料のメンバーシップにのみ subscribe を使います。

delete_missing によるクリーン同期

アカウント上のすべてのバイヤー管理イベントソースを置き換える：

import { testAgent } from "@adcp/sdk/testing";
import { SyncEventSourcesResponseSchema } from "@adcp/sdk";

const result = await testAgent.syncEventSources({
  account: { account_id: "acct_12345" },
  delete_missing: true,
  event_sources: [
    {
      event_source_id: "unified_pixel",
      name: "Unified Tracking Pixel",
    },
  ],
});

if (!result.success) {
  throw new Error(`Request failed: ${result.error}`);
}

const validated = SyncEventSourcesResponseSchema.parse(result.data);

if ("errors" in validated && validated.errors) {
  throw new Error(`Operation failed: ${JSON.stringify(validated.errors)}`);
}

if ("event_sources" in validated) {
  for (const source of validated.event_sources) {
    if (source.action === "deleted") {
      console.log(`Removed: ${source.event_source_id}`);
    } else {
      console.log(`Active: ${source.event_source_id} (${source.action})`);
    }
  }
}

import asyncio
from adcp.testing import test_agent

async def main():
    result = await test_agent.simple.sync_event_sources(
        account={'account_id': 'acct_12345'},
        delete_missing=True,
        event_sources=[{
            'event_source_id': 'unified_pixel',
            'name': 'Unified Tracking Pixel'
        }]
    )

    if hasattr(result, 'errors') and result.errors:
        raise Exception(f"Operation failed: {result.errors}")

    for source in result.event_sources:
        if source.action == 'deleted':
            print(f"Removed: {source.event_source_id}")
        else:
            print(f"Active: {source.event_source_id} ({source.action})")

asyncio.run(main())

セットアップ手順

レスポンスには各イベントソースのセットアップ詳細が含まれます。setup オブジェクトはソースのアクティベート方法を示しています：

`snippet_type`	説明	必要なアクション
`javascript`	ウェブサイトページ用の JavaScript タグ	トラッキング対象ページの `<head>` 内に配置する
`html`	HTML ピクセル / iframe	`</body>` の直前に配置する
`pixel_url`	イベント発生時に呼び出す URL	各イベント時に GET リクエストを送信する
`server_only`	クライアントサイドのタグ不要	`log_event` API を直接使用する

エラーハンドリング

エラーコード	説明	対処方法
`ACCOUNT_NOT_FOUND`	アカウントが存在しない	アカウント設定の `account_id` を確認する
`INVALID_EVENT_TYPE`	認識できないイベントタイプ	`get_adcp_capabilities` でセラーの `supported_event_types` を確認する
`DUPLICATE_EVENT_SOURCE_ID`	リクエスト内に同じ ID を持つ複数のソースがある	一意の `event_source_id` 値を使用する
`RATE_LIMITED`	同期リクエストが多すぎる	指数バックオフで待機してリトライする

ベストプラクティス

ログ送信前に同期する — log_event でイベントを送信する前に、必ずイベントソースを設定しなければなりません。未設定のソースへのイベント送信は拒否されます。
わかりやすい ID を使用する — 不明瞭な識別子ではなく、意味のある event_source_id 値（例: web_pixel、app_sdk、crm_import）を選ぶべきです。
event_types を指定する — より良いバリデーションとデバッグのために、各ソースを関連するイベントタイプに限定すべきです。
セラーの機能を確認する — イベントソースを設定する前に、get_adcp_capabilities を使用してサポートされているイベントタイプ、UID タイプ、アクションソースを確認すべきです。
セットアップスニペットをインストールする — レスポンスに setup 手順が含まれている場合、イベントをログに記録する前に提供されたスニペットをインストールしなければなりません。サーバーオンリーソース（snippet_type: "server_only"）はこの手順をスキップしてよいです。
セラー管理ソースを処理する — レスポンスには自分が設定していない managed_by: "seller" のソースが含まれる場合があります。これらは常時オンであり、追加のアトリビューションデータを提供します。

次のステップ

コンバージョントラッキング — データモデル、最適化目標、エンドツーエンドのフロー
log_event — 設定済みイベントソースにマーケティングイベントを送信します
create_media_buy — イベントソースを参照するパッケージに最適化目標を設定します
get_media_buy_delivery — デリバリーレポートでコンバージョン指標を監視します

はじめに

AdCP で構築する

プロトコル

FAQ

トラストとセキュリティ

リファレンス

AAO

認定

sync_event_sources

クイックスタート

リクエストパラメータ

イベントソースオブジェクト

レスポンス

イベントソースの健全性

よくある使用例

ディスカバリーのみ

複数のイベントソース

セラー管理ソースの検出

クリエイターおよび自社プロパティのソース

delete_missing によるクリーン同期

セットアップ手順

エラーハンドリング

ベストプラクティス

次のステップ

​クイックスタート

​リクエストパラメータ

​イベントソースオブジェクト

​レスポンス

​イベントソースの健全性

​よくある使用例

​ディスカバリーのみ

​複数のイベントソース

​セラー管理ソースの検出

​クリエイターおよび自社プロパティのソース

​delete_missing によるクリーン同期

​セットアップ手順

​エラーハンドリング

​ベストプラクティス

​次のステップ

クイックスタート

リクエストパラメータ

イベントソースオブジェクト

レスポンス

イベントソースの健全性

よくある使用例

ディスカバリーのみ

複数のイベントソース

セラー管理ソースの検出

クリエイターおよび自社プロパティのソース

delete_missing によるクリーン同期

セットアップ手順

エラーハンドリング

ベストプラクティス

次のステップ