Yelp Conversions API エクスポート連携

Yelp Conversions API（CAPI）コネクタは、Yelp 広告キャンペーンのオフライン/サーバーサイドコンバージョンイベントのサーバーサイドトラッキングと測定を可能にします。Yelp の Conversions API と直接連携することで、マルチロケーション広告主がキャンペーンパフォーマンスの測定、広告アトリビューションの改善、ROAS（広告費用対効果）測定の最適化を実現します。

主な機能：

• オフラインコンバージョン: Yelp プラットフォーム外で発生した購入、リード、その他のコンバージョンイベントを追跡
• PII ハッシュ化: ユーザー識別子（メール、電話番号、名前など）の SHA-256 自動ハッシュ化によるプライバシー準拠のマッチング
• データ正規化: Yelp CAPI 仕様に準拠した自動フィールド正規化

このサーバーサイド連携により、広告主は Yelp 広告のクリックとダウンストリームコンバージョン間のアトリビューションループを閉じ、より完全な ROAS 測定を実現できます。

• Treasure AI の基本的な知識（TD Toolbelt を含む）。
• Yelp Ads が有効な Yelp Business アカウント。
• Yelp デベロッパーアプリの認証情報から取得した Yelp API キー（Bearer トークン）。

• 日次レート制限: 1日あたり50,000イベントの上限があり、大規模なエクスポートが制限される場合があります。複数日にわたるバッチ処理/スケジューリングが必要になる場合があります。
• レート制限: 1秒あたり100リクエスト。コネクタはスロットリングと指数バックオフを実装しています。
• 限定的なイベントタイプ: カスタムイベントは custom_ プレフィックスが必要で、英数字、アンダースコア、ハイフンのみ使用可能です。
• 単一値配列: ユーザーデータの配列フィールド（email、phone、country、state、zip_code、city、external_id）は、単一の値を持つ配列として送信されます。
• content_category/content_ids 非対応: custom_data.content_category、custom_data.content_ids、custom_data.contents、custom_data.event_labels は初期リリースではサポートされていません。

セキュリティポリシーで IP ホワイトリストが必要な場合は、接続を成功させるために Treasure Data の IP アドレスを許可リストに追加する必要があります。

リージョンごとに整理された静的 IP アドレスの完全なリストは、次のリンクにあります: IP Addresses for Integrations

Data Workbench では、クエリを実行する前にデータ接続を作成・設定する必要があります。データ接続の一部として、連携にアクセスするための認証を提供します。

1. Data Workbench を開きます。
2. Integrations Hub > Catalog に移動します。
3. Yelp Conversions API を検索して選択します。
4. Create Authentication を選択します。
5. 認証のための認証情報を入力します：

6. Continue を選択します。
7. 接続の名前を入力します。
8. Done を選択します。

1. Data Workbench > Queries に移動します。
2. New Query を選択します。
3. クエリを実行して結果セットを検証します。

SELECT
  transaction_id AS event_id,
  time AS event_time,
  'purchase' AS event_name,
  'website' AS action_source,
  email,
  first_name,
  last_name,
  phone,
  birthday,
  gender,
  country,
  state,
  zip_code,
  city,
  external_id,
  ip_address,
  user_agent,
  lead_id,
  total_amount AS value,
  'USD' AS currency,
  order_id
FROM
  my_database.conversions
WHERE
  TD_TIME_RANGE(time, TD_TIME_ADD(TD_SCHEDULED_TIME(), '-1d'), TD_SCHEDULED_TIME())
  AND email IS NOT NULL

4. クエリでカラムマッピングを定義する必要があります。クエリのカラムは Yelp Conversions API に送信されるデータを表します。

1. Export Results を選択します。
2. 既存の Yelp Conversions API 認証を選択するか、上記の手順で新しい認証を作成します。
3. エクスポートパラメータを設定します：

4. Done を選択します。

Yelp Conversions API にイベントデータをアップロードするには、Yelp CAPI ガイドラインに準拠した標準フィールドの組み合わせを含むデータエクスポートクエリを作成する必要があります。カラム名が「フィールド/カラムレベルの仕様」セクションに記載されたものと一致することを確認してください。

コネクタはカラム名を自動的に正規化します（大文字小文字を区別しないマッチング）。例えば、「event_name」フィールドの場合、エクスポートクエリのカラム名は「EVENT_NAME」、「event_name」、「Event_Name」のいずれでも記述できます。

Yelp CAPI にコンバージョンデータを正常にアップロードするには、特定のデータ仕様に準拠したエクスポートクエリを構築する必要があります。これらの仕様は2つのレベルに分かれています：

• エクスポートクエリ仕様（データセットレベルのデータ仕様）：必須フィールドの存在やクロスフィールドバリデーションルールなど、クエリ結果データセット全体に適用される要件とルール。
• フィールド/カラムレベルの仕様：データ型、フォーマット、正規化ルールなど、データセット内の個々のフィールド/カラムの要件とルール。

以下のフィールドは、コンバージョンマッチングのためにユーザーを識別するために使用されます。正確なマッチングには、少なくとも1つのユーザー識別子（email、phone、external_id、または lead_id）が推奨されます。

1. 電話番号のフォーマット: 電話番号には国コード、市外局番、番号を含める必要があります。コネクタは許可された文字（+、-、括弧、スペース）を除去し、数字のみを検証して、以下のルールを適用します：
   • 10桁：先頭に "1" を自動追加
   • "1" で始まる場合：正確に11桁である必要あり
   • その他の国コード：最大15桁
2. 自動処理: コネクタはすべての PII フィールドに対してフィールドの正規化（小文字化、トリム、句読点の除去）と SHA-256 ハッシュ化を自動的に処理します。
3. エラー収集: レコードのすべてのバリデーションエラーがまとめて収集・報告されるため、データの問題を診断しやすくなります。

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

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

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

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

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	スケジュールなし。

 *    *    *    *    *
 -    -    -    -    -
 |    |    |    |    |
 |    |    |    |    +----- 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 を有効にすることで、クエリの開始時刻を遅延させることができます。

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 を選択します。

Treasure Workflow 内でこの連携を使用してデータをエクスポートできます。

詳細については、TD Toolbelt を使用したワークフローでのデータエクスポートを参照してください。

_export:
  td:
    database: my_database

+yelp_conversions_export:
  td>: export_yelp_conversions.sql
  database: ${td.database}
  result_connection: {your_connection_name}
  result_settings:
    upload_mode: single_event
    skip_invalid_records: false
    test_event: false

CLI（Toolbelt）を使用して Yelp Conversions API へのエクスポートも可能です。

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

オプションのフォーマットは JSON で、一般的な構造は以下の通りです。

{
  "type": "yelp_conversion",
  "api_key": "your-yelp-api-key-here",
  "upload_mode": "single_event",
  "skip_invalid_records": false,
  "test_event": false
}

td query --result '{"type":"yelp_conversion","api_key":"your-api-key","upload_mode":"single_event","skip_invalid_records":false,"test_event":false}' -d my_database "SELECT transaction_id AS event_id, time AS event_time, 'purchase' AS event_name, 'website' AS action_source, email, total_amount AS value, 'USD' AS currency FROM conversions" -T presto

• Yelp Conversions API ドキュメント
• Yelp Conversions API ハッシュガイド
• Yelp Conversions API 正規化ガイド