Snapchat Conversions API エクスポートインテグレーション

Copy

• Copy for LLM

  Copy page as Markdown for LLMs
• View as Markdown

  Open this page as Markdown
• Open in ChatGPT

  Get insights from ChatGPT
• Open in Claude

  Get insights from Claude
• Cursorに接続

  CursorにMCPサーバーをインストール
• VS Codeに接続

  VS CodeにMCPサーバーをインストール

概要

Snapchat Conversions API (CAPI) コネクタは、Web、モバイル、オフラインチャネル全体でのコンバージョンイベントのサーバーサイドトラッキングと測定を可能にします。Snapchatの Events Manager と直接統合することで、このコネクタは企業がキャンペーンのパフォーマンスを測定し、Snapchatの3億人以上のデイリーアクティブユーザー全体で広告配信をより効果的に最適化するのに役立ちます。

主な機能：

• Web Events: ピクセルデータを補完するサーバーサイドトラッキングにより、測定精度を向上
• Mobile App Events: アプリ内コンバージョンイベントの直接統合
• Offline Events: 店舗での購入など、非デジタルコンバージョンのサポート
• Data Validation: Snapchat の CAPI 仕様に合わせた自動イベント検証とフォーマット

このサーバーサイド統合は、クライアントサイドソリューション単独と比較して、より信頼性の高いコンバージョントラッキングと改善された広告パフォーマンス測定を提供します。

前提条件

• TD Toolbelt を含む Treasure Data の基本知識
• Snapchat Business の基本知識
• Snapchat Access Token または Snapchat Business アカウント

制限事項と既知の問題

• イベント時刻の制限

  • 7日以上前のイベント（event_time に基づく）は処理中にスキップされます
  • イベント時刻の検証は、エポック変換と7日間ウィンドウの計算に UTC タイムゾーンを使用します

• OAuth 認証と Conversion API トークン認証間の無効な Event Source ID エラーメッセージの相違

  • 異なる認証方法では、無効な event_source_id に対して異なるエラーレスポンスが生成されます：
    • Conversion API Token 認証を使用する場合、エラーメッセージは次のようになります：
      {  "status": "INVALID",  "reason": "Unauthorized resources" }

• OAuth 認証を使用する場合、エラーメッセージは次のようになります：

  {  "status": "INVALID",  "test_event": true,  "reason": "At least one of the events is invalid.",  "event_logs": [    {   "event": 1,     "status": "INVALID",     "errors": {       "codes": [         "523"       ],       "error_msgs": [         "The provided asset id must be valid UUID format."       ]            }  }}

• OAuth 認証を使用する場合、エラーレスポンスメッセージは無効な Event Source ID を明示的に示さず、代わりに無効な "asset id" を参照します。そのため、Event Source ID が不明な場合のより信頼性の高いエラー処理には、ジョブ実行時に Conversion API Token 認証を使用することをお勧めします。

• Anonymous ID フィールド（anon_id）：API ドキュメントの "User Data Parameter" セクション（リンク）で標準フィールドとして文書化されているにもかかわらず、anon_id は user_data オブジェクトに含めることができません

  • user_data で anon_id を使用しようとすると、次のエラーが発生します：

    {  "status": "INVALID",  "reason": "Request parsing failed. Ensure the request body is correctly formatted." }

  • そのため、回避策として、API エラーを避けるために anon_id を user_data オブジェクトではなく custom data オブジェクトにマッピングする必要があります。

TD Console で新しい接続を作成する

クエリを実行する前に、TD Console でデータ接続を作成して設定する必要があります。データ接続の一部として、インテグレーションにアクセスするための認証を提供します。次の手順を完了してください。

1. TD Console を開きます。

2. Integrations Hub > Catalog に移動します。

3. Snapchat Conversions API を検索して選択します。アイコンにカーソルを合わせて Create Authentication を選択します。

4. Credentials タブが選択されていることを確認し、インテグレーションの認証情報を入力します。次のいずれかを選択します

   1. OAuth 認証ワークフロー：「Click here」リンクを選択して OAuth 認証フローを開始します。認証が完了すると、新しい OAuth 接続が作成され、ドロップダウンで利用できるようになります。

      

      Continue を選択して新しい接続を作成します。

      b. Conversion API Token ワークフロー：Snapchat Business Manager からアクセストークンを取得し、Conversion API Token フィールドに入力します。

      

      認証フィールド

      Parameter	Description
      Authentication Mode	認証方法。サポートされる値： - oAuth Connection: OAuth 認証 - Conversions API Token: Snapchat Business Manager で生成される長期アクセストークン
      Conversions API Token	Conversions API Token は Snapchat Business Manager から取得できます。このパラメータは Conversion API Token 認証方法でのみ利用可能です。

5. Continue を選択します。

6. 認証の名前を入力し、Done を選択します。

エクスポート用のクエリ結果を設定する

TD Console は、データをエクスポートする複数の方法をサポートしています。Data Workbench からデータをエクスポートするには、次の手順に従ってください。

1. Data Workbench > Queries に移動します。
2. New Query を選択し、クエリを定義します。
3. Export Results を選択してデータエクスポートを設定します。
4. 既存の Snapchat CAPI 認証を選択するか、前述の手順で新しい認証を作成します
5. Done を選択します。

コネクタ設定パラメータ

クエリ結果データ仕様の詳細ガイド

Snapchat CAPIにイベントデータをアップロードするには、Snapchat CAPIのガイドラインに準拠した標準フィールドとカスタムフィールドの組み合わせを含むデータエクスポートクエリを構築する必要があります。標準フィールドの場合、カラム名が「フィールド/カラムレベルの仕様」セクションに記載されているものと一致していることを確認してください。コネクターは自動的にカラム名を正規化してSnapchat CAPIの必須形式に一致させるため、大文字・小文字の区別を気にする必要はありません。たとえば、デフォルトフィールド「event_name」の場合、エクスポートクエリのカラム名は「EVENT_NAME」、「event_name」、「Event_Id」など、任意の大文字・小文字で記述できます。コネクターは、Snapchat CAPIの要件を満たすために、カラム名を「event_name」に標準化します。

Snapchat CAPIにユーザープロファイルデータを正常にアップロード/変更するには、特定のデータ仕様に準拠したエクスポートクエリを構築する必要があります。これらの仕様は2つのレベルに分かれています。

• エクスポートクエリ仕様（またはデータセットレベルのデータ仕様）：このセクションでは、必須フィールドの存在や複数のフィールドにまたがるデータ検証ルールなど、クエリ結果データセット全体に適用される要件とルールについて説明します。
• フィールド/カラムレベルの仕様：このセクションでは、各フィールドのデータ型や形式など、データセット内の個々のフィールド/カラムの要件とルールについて詳しく説明します。

エクスポートクエリ仕様

[
  {
    "id": "ABC123",
    "quantity": 2,
    "item_price": 29.99,
    "delivery_category": "standard"
  },
  {
    "id": "XYZ789",
    "quantity": 1,
    "item_price": 49.99,
    "delivery_category": "express"
  }
]

フィールド/カラムレベルの仕様

特別なフィールド処理があります

Countryフィールド

• user_dataオブジェクトの場合：カラム名"country"を使用します(大文字小文字を区別しません)
• custom_dataオブジェクトの場合：カラム名"custom_country"を使用します(大文字小文字を区別しません)

句読点の削除

特定のフィールドでは句読点の削除が必要です。この場合、以下の文字が削除されます：

• 基本的な句読点：. , ! ? ; : - — " ' ( ) [ ] { } / _
• 特殊文字：& * + = @ # $ % ^ ~ |

日付時刻の処理

この統合では、日付時刻カスタムフィールドカラムに対して、timestampとしてキャストされた値またはISO-8601日付時刻文字列形式の値を処理できます。ISO-8601日付時刻文字列を使用する場合は、値の末尾に"Z"を含めることで、コネクタが日付時刻値を検出し、Snapchat CAPIのAPIコントラクトで要求されるUnix時刻値に変換できるようにしてください。

日付時刻カスタムフィールドカラムの処理例

1. Timestampとしてキャスト

• ソースデータテーブルにstring型のカラムを作成します：

  ALTER TABLE source_data_table ADD COLUMN date_time_field VARCHAR;

• そのカラムに日付時刻値文字列を挿入します：

  INSERT INTO source_data_table (id, date_time_field)VALUES(1, '2024-08-28'),(2, '2024-08-28 15:30:00'),(3, '2024-08-28T15:30:00');

• カラム値をtimestampとしてキャストします：

  SELECT id, CAST(date_time_field AS timestamp) AS date_time_field FROM source_data_table;

2. ISO-8601日付時刻文字列の使用

• ソースデータテーブルにstring型のカラムを作成します：

  ALTER TABLE source_data_table ADD COLUMN date_time_field VARCHAR;

• そのカラムに日付時刻値文字列を挿入します。"T"セパレータと末尾の"Z"を含むISO-8601形式でフォーマットされていることを確認してください：

  INSERT INTO source_data_table (id, date_time_field)VALUES(1, '2024-08-28T00:00:00Z'),(2, '2024-05-28T15:30:00.123Z'),(3, '2024-02-28T15:30:00Z');

• クエリで直接カラムを使用します：

  SELECT id, date_time_field FROM source_data_table;

サーバーパラメータの標準フィールド（トップレベルパラメータ）

User Data オブジェクトの標準フィールド

以下のフィールドは、ユーザーとその属性を識別するために使用されます。email（em）、phone（ph）、sc_click_id、client_ip_address、client_user_agent、または mobile advertiser id（madid）のいずれか少なくとも1つの識別子フィールドが必要です。

*これらの識別子フィールドのうち、少なくとも1つが必要です。

オプションのユーザー属性

追加の識別子フィールド

ユーザーデータに関する重要な注意事項:

1. 条件付き要件: 条件付き識別子フィールド (em、ph、sc_click_id、client_ip_address、client_user_agent、またはmadid) のうち、少なくとも1つを含める必要があります。
2. 自動処理: コネクタは以下を自動的に処理します:
   • フィールドの正規化 (小文字への変換、スペースの削除など)
   • 機密フィールドのハッシュ化
   • 必要に応じたUTF-8エンコード
3. 複数の値: String/Arrayとマークされたフィールドは、単一の値または複数の値を受け入れることができます

Custom Dataオブジェクトの標準フィールド

Eコマース関連フィールド

旅行関連フィールド

場所関連フィールド

旅行スケジュールフィールド

宿泊関連フィールド

App Dataオブジェクトの標準フィールド

extinfo配列の仕様

extinfo配列は、以下の順序で正確に16個の要素を含む必要があります。コネクタが正確な配列を構築できるように、「列名」で指定された正確な列名を使用してください:

完全なextinfo配列の例:

["i2", "com.snapchat.sdk", "1.0", "1.0", "10.3.1", "iphone14", "En_US", "EDT", "AT&T", "320", "568", "2", "2", "15", "8", "USA/New York"]

アプリイベントの重要な注意事項:

1. アプリイベントでは、3つのフィールド(advertiser_tracking_enabled、app_id、extinfo)すべてが必須です
2. extinfo配列は上記で指定された正確な順序を維持する必要があります
3. extinfo内の整数値はInt64型として提供する必要があります
4. extinfoの最初の要素がプラットフォーム(iOS/Android)を決定します

(オプション) Query Export ジョブをスケジュールする

Scheduled Jobs と Result Export を使用して、指定したターゲット宛先に出力結果を定期的に書き込むことができます。

Treasure Data のスケジューラー機能は、高可用性を実現するために定期的なクエリ実行をサポートしています。

2 つの仕様が競合するスケジュール仕様を提供する場合、より頻繁に実行するよう要求する仕様が優先され、もう一方のスケジュール仕様は無視されます。

例えば、cron スケジュールが '0 0 1 * 1' の場合、「月の日」の仕様と「週の曜日」が矛盾します。前者の仕様は毎月 1 日の午前 0 時 (00:00) に実行することを要求し、後者の仕様は毎週月曜日の午前 0 時 (00:00) に実行することを要求するためです。後者の仕様が優先されます。

TD Console を使用してジョブをスケジュールする

1. Data Workbench > Queries に移動します

2. 新しいクエリを作成するか、既存のクエリを選択します。

3. Schedule の横にある None を選択します。

4. ドロップダウンで、次のスケジュールオプションのいずれかを選択します:

   ドロップダウン値	説明
   Custom cron...	Custom cron... の詳細を参照してください。
   @daily (midnight)	指定されたタイムゾーンで 1 日 1 回午前 0 時 (00:00 am) に実行します。
   @hourly (:00)	毎時 00 分に実行します。
   None	スケジュールなし。

Custom cron... の詳細

 *    *    *    *    *
 -    -    -    -    -
 |    |    |    |    |
 |    |    |    |    +----- day of week (0 - 6) (Sunday=0)
 |    |    |    +---------- month (1 - 12)
 |    |    +--------------- day of month (1 - 31)
 |    +-------------------- hour (0 - 23)
 +------------------------- min (0 - 59)

次の名前付きエントリを使用できます:

• Day of Week: sun, mon, tue, wed, thu, fri, sat.
• Month: jan, feb, mar, apr, may, jun, jul, aug, sep, oct, nov, dec.

各フィールド間には単一のスペースが必要です。各フィールドの値は、次のもので構成できます:

1. (オプション) Delay execution を有効にすることで、クエリの開始時刻を遅延させることができます。

クエリを実行する

クエリに名前を付けて保存して実行するか、単にクエリを実行します。クエリが正常に完了すると、クエリ結果は指定された宛先に自動的にエクスポートされます。

(オプション) Delay execution を有効にすることで、クエリの開始時刻を遅延させることができます。

Audience Studio で Segment をアクティベートする

Audience Studio で activation を作成することで、segment データをターゲットプラットフォームに送信することもできます。

1. Audience Studio に移動します。
2. parent segment を選択します。
3. ターゲット segment を開き、右クリックして、Create Activation を選択します。
4. Details パネルで、Activation 名を入力し、前述の Configuration Parameters のセクションに従って activation を設定します。
5. Output Mapping パネルで activation 出力をカスタマイズします。

• Attribute Columns
  • Export All Columns を選択すると、変更を加えずにすべての列をエクスポートできます。
  • + Add Columns を選択して、エクスポート用の特定の列を追加します。Output Column Name には、Source 列名と同じ名前があらかじめ入力されます。Output Column Name を更新できます。+ Add Columns を選択し続けて、activation 出力用の新しい列を追加します。
• String Builder
  • + Add string を選択して、エクスポート用の文字列を作成します。次の値から選択します:
    • String: 任意の値を選択します。テキストを使用してカスタム値を作成します。
    • Timestamp: エクスポートの日時。
    • Segment Id: segment ID 番号。
    • Segment Name: segment 名。
    • Audience Id: parent segment 番号。

6. Schedule を設定します。

• スケジュールを定義する値を選択し、オプションでメール通知を含めます。

7. Create を選択します。

(オプション) CLIを使用したエクスポートインテグレーション

CLI(Toolbelt)を使用してSnapchat Conversion CAPIに結果をエクスポートすることもできます。

td queryコマンドの*--resultオプションを使用して、Snapchatサーバーへのエクスポートに必要な情報を指定する必要があります。td query*コマンドの詳細については、こちらの記事を参照してください。

オプションの形式はJSONで、一般的な構造は次のとおりです。

{
  "type": "snapchat_conversion",
  "auth_method": "oauth",
  "oauth_credentials_id": "xxxxxxxxxxx",
  "event_source_type": "web",
  "event_source_id": "xxxxxxxxxxx",
  "send_test_events": false,
  "skip_invalid_records": true
}

{
  "type": "snapchat_conversion",
  "auth_method": "api_token",
  "api_token": "xxxxxxxxxxx",
  "event_source_type": "web",
  "event_source_id": "xxxxxxxxxxx",
  "send_test_events": false,
  "skip_invalid_records": true
}

パラメータ

使用例

OAuth認証

$ td query --result '{"type":"snapchat_conversion","auth_method":"oauth","oauth_credentials_id":"xxx","event_source_type":"WEB","event_source_id":"xxx", "send_test_events":false,"skip_invalid_records":true}' -d sample_datasets "select ........ from ........" -T presto

APIトークン認証

$ td query --result '{"type":"snapchat_conversion","auth_method":"api_token","api_token":"xxx","event_source_type":"WEB","event_source_id":"xxx", "send_test_events":false,"skip_invalid_records":true}' -d sample_datasets "select ........ from ........" -T presto

関連記事

その他の設定

• 結果エクスポートは、対象の宛先に定期的にデータをアップロードするようにスケジュールできます。
• すべてのインポートおよびエクスポートインテグレーションは、TD Workflowに追加できます。tdデータオペレーターは、クエリ結果を指定されたインテグレーションにエクスポートできます。詳細については、Treasure Dataオペレーターのリファレンスを参照してください。