# Facebook Offline Conversions

2025-03-10更新 Metaは、現在のFacebook Offline ConversionsアプリケーションがOffline Conversions API（OCAPI）を廃止することを発表しました。また、Metaは新しいオフラインイベントセット（OES）の作成を無効にします。Metaは、OCAPIが2025年5月1日に廃止されることを予想しています。参照：[https://www.facebook.com/business/help/1835755323554976](https://www.facebook.com/business/help/1835755323554976)    この変更に備えて、Treasure DataはMeta Conversion APIコネクターでオフラインコンバージョンのサポートを追加しました：   - [https://docs.treasuredata.com/articles/#!int/facebook-conversions-api-export-integration](/ja/int/facebook-conversions-api-export-integration)  これら2つのAPI間のフィールド名の違いを確認してください：   - [https://docs.treasuredata.com/articles/int/migration-guide-to-facebook-conversion-connector](/ja/int/migration-guide-to-facebook-conversion-connector)   ユーザーは、Facebook Offline Conversionsアプリケーションへの今後の変更に備えて、今日からコネクターに切り替えることができます。

Facebook Offline Conversionsを使用して、Treasure DataからFacebookに直接ジョブ結果（オフラインイベントデータの形式）を送信し、Facebook広告が店舗での購入、電話注文、予約などの実際の成果にどれだけつながるかを測定できます。

## 前提条件

- Treasure Dataの基本的な知識
- Facebook Offline ConversionsとFacebook Offline Eventの基本的な知識
- イベントデータをアップロードするには、Facebook上で次のいずれかへのアクセスが必要です：
  - Business Manager管理者
  - オフラインイベントセットを作成した管理者システムユーザー
  - オフラインイベントセットに接続された`ad_account`の管理者


## Offline Event Set ID

1. Business Managerダッシュボードを開き、Event Managerを選択します。
2. **Event Set**を選択します。
3. **Settings**を選択すると、Offline event set IDが表示されます。


![](/assets/image-20200916-125520.871f138abf2ac583105cd7a6388da2fef20b40ab55f783cc84fa22394da6955e.105d1a9c.png)

## TD Consoleを使用して接続を作成する

### 新しい接続を作成する

Treasure Dataでは、クエリを実行する前に、エクスポート中に使用するデータ接続を作成して構成する必要があります。データ接続の一部として、統合にアクセスするための認証を提供します。

1. TD Consoleを開きます。
2. **Integrations Hub** > **Catalog**に移動します。
3. **Facebook Offline Conversions**を検索して選択します。
4. 次のダイアログが開いたら、認証方法のタイプを選択します。これについては、次のセクションで詳しく説明します。


![](/assets/image-20200913-011149.0ff5d47236e5f84f2e24d951f852b97cb42e65b7aebd1ed7a0d28ff02f4ff20e.105d1a9c.png)

1. 接続の名前を入力します。
2. **Done**を選択します。


### 接続の認証

Treasure DataをFacebookで認証する方法によって、データコネクターがFacebookにアクセスできるようにするための手順が異なります。次の方法で認証を選択できます：

- Access Token
- OAuth


#### Access Tokenを使用した認証

Access Tokenを使用して認証するには、アクセストークンとクライアントシークレットが必要です。長期有効なユーザーアクセストークンまたはシステムユーザーアクセストークンが推奨されます。[長期有効なアクセストークン](https://www.sociablekit.com/get-facebook-long-lived-user-access-token/)または[システムアクセストークン](https://developers.facebook.com/docs/audience-network/guides/reporting/system-user/)を作成する必要がある場合があります。

access_tokenに`ads_management`権限を割り当てる必要があります。

#### OAuthを使用した認証

OAuthは最も一般的な認証方法です。認証には、Treasure DataアカウントをFacebook Adsアカウントに手動で接続する必要があります。
認証するには、次の手順を実行します：

1. **Click here**を選択して新しいアカウントを接続します。まだログインしていない場合は、Facebookにログインするためにリダイレクトされるか、Treasure Dataへのアクセスを許可する同意ページに移動します。


![](/assets/image-20200913-030209.a9b9a438d4dc4a9a15d2db5b21f980d016a40bfecb507e21ecd649b31596b80d.105d1a9c.png)

1. ポップアップウィンドウでFacebookアカウントにログインし、Treasure Dataアプリケーションへのアクセスを許可します。TD Consoleにリダイレクトされます。


![](/assets/data-connector-facebook-login.ffc61a088d2fba0cad93ac39afbcb5c2cf06e120c8fdf113b84fe3855bd8b04d.105d1a9c.png)

1. 最初のステップ（新しい接続を作成する）を繰り返し、新しいOAuth接続を選択します。


![](/assets/image-20200913-030623.f479d771e5df0a0ead39bade8109c76d67ccba05579d884d2b47a6da366130dc.105d1a9c.png)

1. 新しいFacebook Offline Conversions接続に名前を付けます。
2. **Done**を選択します。


### データ接続でエクスポート結果を構成する

このステップでは、クエリを作成または再利用します。クエリで、データ接続を構成します。

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

さらに、**match_keys**列とそのデータは、Facebookに送信される前にハッシュ化/正規化されます。[ハッシュ化と正規化の要件](https://developers.facebook.com/docs/marketing-api/audiences/guides/custom-audiences#hash)の詳細をご覧ください。エクスポート結果を構成するには、少なくとも1つの**match_keys**列が必要です。

| **Column name** | **Data type** | **Match Key** | **Required** | **Multiple** | **Example** |
|  --- | --- | --- | --- | --- | --- |
| `email` | string | Yes | No | Yes | foo@fb.com |
| `phone` | string | Yes | No | Yes | 1-202-555-0192 |
| `gen` | string | Yes | No | No | M |
| `doby` | string | Yes | No | No | 1990 |
| `dobm` | string | Yes | No | No | 10 |
| `dobd` | string | Yes | No | No | 20 |
| `ln` | string | Yes | No | No | Bar |
| `fn` | string | Yes | No | No | Foo |
| `fi` | string | Yes | No | No | L |
| `ct` | string | Yes | No | No | Long Beach |
| `st` | string | Yes | No | No | California |
| `zip` | string | Yes | No | No | 90899 |
| `country` | string | Yes | No | No | US |
| `madid` | string | Yes | No | No | aece52e7-03ee-455a-b3c4-e57283 |
| `extern_id` | string | Yes | No | No |  |
| `lead_id` | string | Yes | No | No | 12399829922 |
| `event_time` | long | No | Yes | No | 1598531676 |
| `event_name` | string | No | Yes | No | Purchase |
| `currency` | string | No | Yes | No | USD |
| `value` | double | No | Yes | No | 100.00 |
| `content_type` | string | No | No | No |  |
| `contents` | json string | No | No | Yes | {"id": "b20", "quantity": 100} |
| `custom_data` | json string | No | No | No | {"a":12, "b":"c"} |
| `order_id` | string | No | No | No | OD123122 |
| `item_number` | string | No | No | No |  |


[Data Processing Options](https://developers.facebook.com/docs/marketing-apis/data-processing-options)を含めるには、クエリでこれらの列マッピングを指定します。

| **Column name** | **Data Type** | **Required** | **Multiple** | **Example** |
|  --- | --- | --- | --- | --- |
| `data_processing_options` | string | No | No | "LDU" |
| `data_processing_options_country` | long | No | No | 1 |
| `data_processing_options_state` | long | No | No | 1000 |


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


```SQL
SELECT home_email as email, work_email as email, first_name as fn, last_name as ln
FROM table my_table
```

### パラメータを指定して接続を構成する

1. TD Consoleを開きます。
2. **Data Workbench** > **Queries**に移動します。
3. データをエクスポートするために使用する予定のクエリを選択します。
4. クエリエディターの上部にある「Export Results」を選択します。
5. **Choose Integration**ダイアログが開きます。
6. 結果をエクスポートするために使用する接続を選択する際に、既存の接続を使用するか、最初に新しい接続を作成するかの2つのオプションがあります。


#### 既存の接続を使用する

1. 検索ボックスに接続名を入力してフィルタリングします。
2. 接続を選択します。
3. 次のパラメータを設定します。


| **Parameter** | **Description** |
|  --- | --- |
| **Offline Event Set ID**（必須） | FacebookオフラインイベントセットID。Offline Event Set IDについては付録を参照してください。 |
| **Upload Tag**（必須） | イベントのアップロードを追跡するために使用します |
| **Namespace ID**（オプション） | `extern_id`または`tpid`を解決するために使用されるスコープ。別のデータセットまたはデータパートナーIDにすることができます。例：`12345` |
| **Match Keys**（必須） | Facebook上の人々とマッチングするために使用される識別情報。値はカンマ区切りの文字列です。例：`email,phone,fn,ln,st,country…` |
| **Skip Invalid Data**（オプション） | 無効なレコードが検出されたときにジョブを終了する（元に戻さずに）ために使用されます。たとえば、レコードに必須列（`event_name`、`event_time...`など）がない場合です。 |


サンプル構成は次のとおりです：

![](/assets/image-20200916-024823.38c88f7c6235bf6dc4b3dfb5451a59e998bbc0c4cdfba20e8b1202570ae69bd3.105d1a9c.png)

### オフラインイベントデータを入力するクエリの例

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

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



```SQL
SELECT
  an_email_column       AS EMAIL,
  a_phone_column        AS PHONE,
  an_event_time_column  AS EVENT_TIME,
  an_event_name_column  AS EVENT_NAME,
  a_double_column       AS VALUE,
  a_currency_column     AS CURRENCY
FROM your_table;
```

- 複数の値のために複数のemailおよびphone列をクエリします。



```SQL
SELECT
  'elizabetho@fb.com' as email,
  'olsene@fb.com'     as email,
  '1-(650)-561-5622'  as phone,
  '1-(650)-782-5622'  as phone,
  'Elizabeth'         as fn,
  'Olsen'             as ln,
  '94046'             as zip,
  'Menlo Park'        as st,
  'US'                as country,
  '1896'              as doby,
  'Purchase'          as event_name,
  1598531676          as event_time,
  150.01              as value,
  'USD'               as currency
```

- 複数の`contents`を含むクエリ



```
SELECT
  'elizabetho@fb.com' as email,
  'Purchase'          as event_name,
  1598531676          as event_time,
  150.01              as value,
  'USD'               as currency
  '{"id": "b20", "quantity": 100}' as contents
  '{"id": "b21", "quantity": 200}' as contents
```

- `custom_data`列をクエリする



```
SELECT
  'elizabetho@fb.com' as email,
  'Purchase'          as event_name,
  1598531676          as event_time,
  150.01              as value,
  'USD'               as currency
  '{"a":12, "b":"c"}' as 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 を有効にすることで、クエリの開始時刻を遅延させることができます。


## ワークフローでエクスポート結果をオプションで構成する

Treasure Workflow内で、このデータコネクターを使用してデータをエクスポートすることを指定できます。


```yaml
timezone: UTC

_export:
  td:
    database: sample_datasets

+td-result-into-target:
  td>: queries/sample.sql
  result_connection: facebook_offline_conversions
  result_settings:
    event_set_id: 361738844830373
    upload_tag: purcharse_event_upload
    match_keys: email,phone,ln,fn
```

ワークフローでデータコネクターを使用してデータをエクスポートする方法の詳細については、[Exporting Data with Parameters](https://docs.treasuredata.com/smart/project-product-documentation/exporting-data-with-parameters)を参照してください。