# Facebook Conversions API Export Integration

Treasure Data から Facebook に直接ジョブ結果(イベントデータの形式)を送信するために Facebook Conversions API を使用できます。これにより、Facebook 広告が購入、登録、申し込み、その他のウェブコンバージョンなどの実世界での成果にどの程度つながっているかを測定できます。

Facebook Pixel が3rdパーティデータとして取り込むコンバージョンデータに加えて、1stパーティデータをコンバージョンデータとしてアップロードできます。

また、ウェブサーバーログから抽出した CV ログを Facebook Conversion API にアップロードすることもできます。

このインテグレーションを使用して、オフラインイベント(実店舗で行われたコンバージョン)をアップロードすることを推奨します。

![](/assets/image2021-6-10_15-33-31.3b1cc60814728dca0583915eb5f143639455b698840ae34d0320bb3ed76c452f.08eb519a.png)

## 前提条件

- Treasure Data の基本知識
- Facebook Conversions と Facebook Event の基本知識
- イベントデータをアップロードするには、Facebook の以下のいずれかへのアクセスが必要です:
  - Business Manager admin
  - イベントセットを作成した Admin system user
- イベントセットに接続されている ad_account の Admin
- [Facebook Pixel ID](https://www.facebook.com/business/help/952192354843755?id=1205376682832142)
- Facebook Access Token


## Facebook Pixel ID と Access Token の取得

1. Business Manager ダッシュボードを開き、Event Manager を選択します。


![](/assets/image2021-1-12_14-29-52.37077fd18222428750314607eaa28fd5af44e5c9def7c655ce7ba40361cf0a67.08eb519a.png)

1. Event Set を選択します。Settings を選択すると、Pixel ID が表示されます。


![](/assets/image2021-6-10_16-56-50.8c84e75d84d6a790a41ed7cc9a5a38fe1df541099fb5e6fb2fd6af71086d36b2.08eb519a.png)

1. Create Access Token を選択します。


![](/assets/image2021-6-10_16-58-8.43de3a484f74cdf93a8cd5820215946e61dcbc1da9cb7e2fac9c6ea8906fecdc.08eb519a.png)

1. Pixel を選択します。
2. Next を選択します。


![](/assets/image2021-6-10_17-1-37.8e91dc607e729934d2a2c9308b2a36baec30502f0eb1db2ff91a52c8a7f04a22.08eb519a.png)

1. Generate Access Token を選択します。


![](/assets/image2021-6-10_17-3-37.e93e67772d3204fe1a804e4824c1e4a92d575fb4ba3e1baac32308bd08353e35.08eb519a.png)

1. アクセストークンをコピーして保存します。セキュリティのため、サンプルではトークンを非表示にしています。
2. **Next** を選択します。


## アップロードの検証

アップロードテストを試すには、Test Events タブでテストコードを確認してください。

![](/assets/image2021-6-10_17-17-27.4701574ba551161d46afaf9f044da26f11714605fcd2c272932d3583dc4bc781.08eb519a.png)

## TD Console を使用した接続の作成

### 新しい接続の作成

Treasure Data では、クエリを実行する前に、エクスポート中に使用するデータ接続を作成して設定する必要があります。データ接続の一部として、インテグレーションにアクセスするための認証情報を提供します。

1. TD Console を開きます。
2. **Integrations Hub** > **Catalog** に移動します。
3. **Facebook Conversion API** を検索して選択します。


![](/assets/image2021-6-10_17-18-39.689ea9857c4f778f9a161f66875e6887624f1794bcfc66b9d40b422fe0afbc92.08eb519a.png)

1. **Create Authentication** を選択します。


以下のフィールドを入力します:

- Pixel ID
- Access Token
![](/assets/image2021-1-12_16-17-28.1d0def713122ca79a6a6cc26f4bf49722a12dd56e3c57ed75c1155e05cc5b20b.08eb519a.png)


1. **Continue** を選択します。接続名を入力し、**Done** を選択します。


### クエリの定義

クエリで列マッピングを定義する必要があります。クエリ内の列は、Facebook にアップロードされるイベントデータを表します。

Conversions API を使用して共有されるすべてのウェブサイトイベントには、以下のデータパラメータが必要です:

- client_user_agent
- action_source
- event_source_url


ただし、非ウェブイベントには action_source パラメータのみが必要です。

これらのパラメータは、広告配信に使用されるイベントの品質を向上させ、キャンペーンのパフォーマンスを改善する可能性があります。さらに、一部の列については、Facebook に送信される前にデータがハッシュ化および正規化されます。

エクスポート結果を設定するには、少なくとも1つの**顧客情報**列が必要です。[ハッシュ化と正規化の要件](https://developers.facebook.com/docs/marketing-api/audiences/guides/custom-audiences#hash)および Facebook Conversions API の詳細をご覧ください。

![](/assets/image2021-6-10_17-31-40.b1ff2839dd8f7db5e06e9167e79a8f64f280c1ef8d07c36aad1ddeab99ac32da.08eb519a.png)

### Facebook Conversions API のインテグレーションパラメータ

![](/assets/image2021-6-10_17-39-26.3092acb62aca28f2072e77ea492081fffdc2960e2df0b4df40b1bb4b3cf2201c.08eb519a.png)

| **パラメータ** | **説明** |
|  --- | --- |
| Test Event Code (optional) | Events Manager の Test Events 機能でサーバーイベントをテストするためのコード |
| Pre-hashed Columns | (オプション)SHA256 を使用してすでにハッシュ化されており、API の受け入れ要件を満たしているカンマ区切りの列 |
| Skip Invalid Data (オプション) | 無効なレコードが検出された際にジョブを終了（ロールバックなし）するために使用されます。例えば、レコードに必須カラム（event_name、event_time など）が欠けている場合などです。 |


### クエリの例

![](/assets/image2021-6-10_17-32-45.1dc34ffd053ae116249f4b51b7e4faac4ef5c2db7ccb73a555483c23a3ae9bad.08eb519a.png)

オフラインイベントの場合、action_source = physical_store となります。

**custom_data** に属する **currency** などのデータをエクスポートする場合は、JSON 形式でデータを設定する必要があります。

例えば、クエリは次のようになります：


```sql
WITH sample_data AS(
  SELECT
     *
  FROM
    (
    VALUES(
      1,
      'USD',
      104.2
    ),
    (
      2,
      'JPY',
      10000.2
    ),
    (
      3,
      'USD',
      103.4
    )
    ) AS t(
      id,
      currency,
      VALUE
    )
) SELECT
  CAST(
    MAP(
      ARRAY['currency',
      'value'],
      ARRAY[currency,
      CAST(
        VALUE AS VARCHAR
      ) ]
    ) AS JSON
  ) AS custom_data,
  id
FROM
  sample_data
```

同じ名前で複数の値をクエリするには、クエリ内で名前を複数回指定します。

![](/assets/image2021-6-10_17-44-20.c0b9ac826e9ce804925cacc3d5406758ce088d5fe7769a62e4ad5c50a4f0c90b.08eb519a.png)

### イベントデータを取得するクエリの例

Treasure Data から、Facebook Conversions への接続にエクスポート結果を出力する次のクエリを実行します：

- テーブルからの通常の SELECT クエリ



```sql
SELECT
  an_event_name_column AS event_name,
  an_event_time_column AS event_time,
  an_email_column AS em,
  a_country_column AS country
FROM your_table;
```

- custom_data カラムのクエリ



```sql
SELECT
  'PageView' as event_name,
  1598531676 as event_time,
  'elizabetho@fb.com' as em,
  '{"a":12, "b":"c"}' as custom_data
```

### App Data Event のクエリ例


```SQL
SELECT
  event_name,
  event_time,
  em,
  action_source,
  advertiser_tracking_enabled,
  application_tracking_enabled,
  campaign_ids,
  install_referrer,
  installer_package,
  url_schemes,
  vendor_id,
  windows_attribution_id,
  extinfo_version,
  app_package_name,
  short_version,
  long_version,
  os_version,
  device_model_name,
  locale,
  timezone_abbr,
  carrier,
  screen_width,
  screen_height,
  screen_density,
  cpu_core,
  external_storage_size,
  free_space_in_external_storage_size,
  device_time_zone,
  anon_id,
  madid,
  client_ip_address,
  client_user_agent
FROM
  conversion_table
```

### Facebook Conversions API の統合パラメータ

Treasure Data は、送信前にFacebook側のデータ要件に基づいて、統合内でデータの正規化とハッシュ化を処理します。

| **カラム名** | **データ型** | **必須** | **ハッシュ化必須?** | **説明** |
|  --- | --- | --- | --- | --- |
| ***サーバーイベント*** |  |  |  |  |
| `event_name` | String | ✅ |  |  |
| `event_time` | Long | ✅ |  |  |
| `custom_data` | String/JSON |  |  | カスタムプロパティの配列。詳細は[こちら](https://developers.facebook.com/docs/marketing-api/conversions-api/parameters/custom-data)を参照 |
| `event_source_url` | String |  |  |  |
| `opt_out` | Boolean |  |  |  |
| `event_id` | String |  |  |  |
| `action_source` | String |  |  | アプリイベントの場合、action_source の値は app である必要があります |
| `data_processing_options` | String |  |  | LDU 用 |
| `data_processing_options_country` | Long |  |  | LDU 用 |
| `data_processing_options_state` | Long |  |  | LDU 用 |
| `顧客情報（少なくとも1つのキーが必要）` |  |  |  |  |
| `em` | String |  | ✅ | メールアドレス |
| `ph` | String |  | ✅ | 電話番号 |
| `ge` | String |  | ✅ | 性別 |
| `db` | String |  | ✅ | 生年月日 |
| `ln` | String |  | ✅ | 姓 |
| `fn` | String |  | ✅ | 名 |
| `ct` | String |  | ✅ | 市区町村 |
| `st` | String |  | ✅ | 都道府県 |
| `zp` | String |  | ✅ | 郵便番号 |
| `country` | String |  | ✅ | 国 |
| `external_id` | String |  | ✅ | 外部ID |
| `client_ip_address` | String | 使用する場合両方必須 |  | クライアント IP アドレス |
| `client_user_agent` | String |  | クライアントユーザーエージェント |  |
| `fbc` | String |  |  | Facebook クリック ID |
| `fbp` | String |  |  | Facebook ブラウザ ID |
| `subscription_id` | String |  |  | サブスクリプション |
| `lead_id` | Long |  |  | リード ID |
| `fb_login_id` | Long |  |  | FB ログイン ID |
| anon_id | String |  |  | アプリイベント専用。インストール ID。このフィールドは一意のアプリケーションインストールインスタンスを表します。 |
| madid | String |  |  | アプリイベント専用。モバイル広告主 ID、Android デバイスからの広告 ID、または Apple デバイスからの広告識別子（IDFA）。 |
| アプリデータイベント |  |  |  |  |
| advertiser_tracking_enabled | String | ✅ |  | - 0: 無効 - 1: 有効 |
| application_tracking_enabled | String | ✅ |  | - 0: 無効 - 1: 有効 |
| extinfo_version | String | ✅ |  | - a2: Android - i2: iOS |
| app_package_name | String |  |  | アプリパッケージ名 |
| short_version | String |  |  | 短縮バージョン |
| long_version | String |  |  | 長いバージョン |
| os_version | String | ✅ |  | OS バージョン |
| device_model_name | String |  |  | デバイスモデル名 |
| locale | String |  |  | ロケール |
| timezone_abbr | String |  |  | タイムゾーン略称 |
| carrier | String |  |  | キャリア |
| screen_width | String |  |  | 画面幅 |
| screen_height | String |  |  | 画面高さ |
| screen_density | String |  |  | 画面密度 |
| cpu_core | String |  |  | CPU コア |
| external_storage_size | String |  |  | 外部ストレージサイズ（GB） |
| free_space_in_external_storage_size | String |  |  | 外部ストレージの空き容量（GB） |
| device_time_zone | String |  |  | デバイスのタイムゾーン |
| campaign_ids | String |  |  | ユーザーが Facebook からのリンクをクリックした際に、アウトバウンド URL（例：ad_destination_url）またはディープリンク（App Aggregated Event Manager の場合）に追加される暗号化された文字列と非ユーザーメタデータ。 |
| install_referrer | String |  |  | サードパーティインストールリファラー、現在 Android のみで利用可能 |
| installer_package | String |  |  | Android SDK で内部的に使用 |
| url_schemes | String |  |  | iOS および Android SDK で内部的に使用 |
| vendor_id | String |  |  | ベンダー ID |
| windows_attribution_id | String |  |  | Windows 10 で使用されるアトリビューショントークン |


詳細は [Facebook のコンテンツページ](https://developers.facebook.com/docs/marketing-api/conversions-api/parameters/custom-data)を参照してください。

### (オプション) 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 を選択します。
![](/assets/image2021-1-15_17-28-51.f1b242f6ecc7666a0097fdf37edd1682786ec11ef80eff68c66f091bc405c371.0f87d8d4.png)
4. ドロップダウンで、次のスケジュールオプションのいずれかを選択します:
![](/assets/image2021-1-15_17-29-47.45289a1c99256f125f4d887e501e204ed61f02223fde0927af5f425a89ace0c0.0f87d8d4.png)
| ドロップダウン値 | 説明 |
|  --- | --- |
| Custom cron... | [Custom cron... の詳細](#custom-cron-details)を参照してください。 |
| @daily (midnight) | 指定されたタイムゾーンで 1 日 1 回午前 0 時 (00:00 am) に実行します。 |
| @hourly (:00) | 毎時 00 分に実行します。 |
| None | スケジュールなし。 |


#### Custom cron... の詳細

![](/assets/image2021-1-15_17-30-23.0f94a8aa5f75ea03e3fec0c25b0640cd59ee48d1804a83701e5f2372deae466c.0f87d8d4.png)

| **Cron 値** | **説明** |
|  --- | --- |
| `0 * * * *` | 1 時間に 1 回実行します。 |
| `0 0 * * *` | 1 日 1 回午前 0 時に実行します。 |
| `0 0 1 * *` | 毎月 1 日の午前 0 時に 1 回実行します。 |
| "" | スケジュールされた実行時刻のないジョブを作成します。 |



```
 *    *    *    *    *
 -    -    -    -    -
 |    |    |    |    |
 |    |    |    |    +----- 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.


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

| フィールド値  | 例  | 例の説明  |
|  --- | --- | --- |
| 各フィールドに対して上記で表示された制限内の単一の値。 |  |  |
| フィールドに基づく制限がないことを示すワイルドカード
`'*'`。 | `'0 0 1 * *'` | 毎月 1 日の午前 0 時 (00:00) に実行するようにスケジュールを設定します。 |
| 範囲 `'2-5'`
フィールドの許可される値の範囲を示します。 | `'0 0 1-10 * *'` | 毎月 1 日から 10 日までの午前 0 時 (00:00) に実行するようにスケジュールを設定します。 |
| カンマ区切りの値のリスト `'2,3,4,5'`
フィールドの許可される値のリストを示します。 | `0 0 1,11,21 * *'` | 毎月 1 日、11 日、21 日の午前 0 時 (00:00) に実行するようにスケジュールを設定します。 |
| 周期性インジケータ `'*/5'`
フィールドの有効な値の範囲に基づいて、
スケジュールが実行を許可される頻度を表現します。 | `'30 */2 1 * *'` | 毎月 1 日、00:30 から 2 時間ごとに実行するようにスケジュールを設定します。
`'0 0 */5 * *'` は、毎月 5 日から 5 日ごとに午前 0 時 (00:00) に実行するようにスケジュールを設定します。 |
| `'*'`
ワイルドカードを除く上記の
いずれかのカンマ区切りリストもサポートされています
`'2,*/5,8-10'` | `'0 0 5,*/10,25 * *'` | 毎月 5 日、10 日、20 日、25 日の午前 0 時 (00:00) に実行するようにスケジュールを設定します。 |


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


### クエリを実行する

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

設定エラーにより継続的に失敗するスケジュールジョブは、複数回通知された後、システム側で無効化される場合があります。

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

## Workflow でエクスポート結果をオプションで設定する

Treasure Workflow 内で、この統合を使用してデータをエクスポートするように指定できます。

詳細は [パラメータを使用したデータのエクスポート](https://docs.treasuredata.com/smart/project-product-documentation/exporting-data-with-parameters)を参照してください。


```yaml
timezone: UTC

_export:
  td:
    database: sample_datasets

+td-result-into-target:
  td>: queries/sample.sql
  result_connection: facebook_conversions
  result_settings:
    test_event_code: 361738844830373
    skip_invalid: false
```