# Facebook Custom Audience Export Integration Treasure Data のジョブ結果を、Facebook Custom Audience に直接書き込むことができます。 Custom Audience をアップロードまたは作成する際、Facebook では Custom Audience Terms への同意が必要です。カスタマーファイルをターゲットとする広告オブジェクトをエクスポートする場合、または Value-based Custom Audiences をエクスポートする場合に通知が表示されます。Facebook Custom Audience の利用規約に関する通知は、その後 90 日ごとに表示されます。詳細については、[Better Facebook Ads ROI with Data-Driven Custom Audiences](https://blog.treasuredata.com/blog/2017/04/04/facebook-custom-audiences/) を参照してください。 ジョブ結果を Facebook Custom Audience に書き込む方法のサンプルワークフローについては、[Treasure Boxes](https://github.com/treasure-data/treasure-boxes/tree/master/td/facebook_custom_audience) を参照してください。 ## 前提条件 - [TD Toolbelt](https://toolbelt.treasuredata.com/) を含む Treasure Data の基本知識 - Facebook 広告アカウント - Facebook 広告アカウントへの Treasure Data Facebook アプリのアクセス許可 - 広告アカウントの役割として、管理者または広告主が必要です - オプション: Access Token および App Secret ### (オプション) Access Token の取得または生成 このセクションは、OAuth 認証を使用する場合はオプションです。 #### System User Access Token 1. Facebook Business Manager にログインし、システムユーザーを作成します。 2. 新しいシステムユーザーを選択し、そのユーザー用の新しいトークンを生成します。 Treasure Data では、「有効期限なし」のトークンを生成することを推奨しています。 ![](/assets/screen-shot-2021-06-16-at-11.08.52.abe8711d04dec42ce11016dcece5ade7090aae63ef46e5d0202ac2e3a5d1e744.40636315.png) 1. 以下の権限を付与します: - ads_management - ads_read - pages_manage_ads - pages_manage_metadata - pages_read_engagement - pages_read_user_content - read_insights Facebook への接続用の Access Token を生成できない場合は、[System Users on Business Management APIs](https://developers.facebook.com/docs/marketing-api/system-users/) を参照してください。 ## サポートされている Facebook データの正規化とハッシュ化の要件 Facebook にデータを送信する前に、データは **ソルトなしの SHA256 でハッシュ化する** 必要があります (ソルトとは、データをハッシュ化する一方向関数への追加入力として使用されるランダムデータです)。この要件は、External Identifiers、App User IDs、および Page Scoped User IDs を除くすべてのデータに適用されます。 データを送信する前にデータの準備 (正規化とハッシュ化) を行う場合は、オプション **No need to normalize and hash records** を **True** に設定できます。 Treasure Data の結果出力は、[Facebook の正規化ルール](https://developers.facebook.com/docs/marketing-api/audiences-api#hash)に従って値を自動的に正規化します。 Facebook にアップロードしてマッチングを行うすべての値は、Facebook の正規化ルールを使用して正規化する必要があります。正規化されていない場合、値のマッチング機会が失われます。データを手動で正規化する必要がある場合は、出力結果を生成する前に独自の正規化を適用してください。 [Facebook の Marketing API のパラメータ](https://developers.facebook.com/docs/marketing-api/conversions-api/parameters/customer-information-parameters#ph)に渡される顧客情報の値について詳しく学んでください。 データタイプに応じて、結果出力の作成中に以下の変換動作が適用されます。 | **パラメータ** | **説明** | | --- | --- | | **EXTERN_ID (External ID)** | アクションは不要です。 | | **PAGEUID** | アクションは不要です。 | | **MADID (Mobile advertiser ID)** | すべての文字を小文字に変換し、ハイフンを保持します。 | | **EMAIL (Email addresses)** | 先頭と末尾の空白をトリミングし、すべての文字を小文字に変換します。 Meta の[ハッシュ化と正規化の要件](https://developers.facebook.com/docs/marketing-api/audiences/guides/custom-audiences#hash)について詳しく学んでください。 | | **PHONE (Phone numbers)** | 数字以外の文字と先頭のゼロを削除します。 | | **GEN (Gender)** | 先頭と末尾の空白をトリミングし、すべての文字を小文字に変換します。結果が "m" または "f" と一致しない場合、空の文字列が使用されます (無効な値であるため、マッチングを試みても無駄です)。 | | **DOBY (Birth Year)** | 数字以外の文字を削除し、最初の 4 桁を取得します。 | | **DOBM (Birth Month) および DOBD (Birthday)** | 数字以外の文字を削除し、最初の 2 桁を取得します。 | | **FN (First Name) および LN (Last Name)** | 先頭と末尾の空白をトリミングし、すべての文字を小文字に変換します。すべての句読点を削除します。UTF-8 エンコーディングの特殊文字をサポートします。 | | **FI (First Initial)** | First Name と同じ処理を適用し、最初の文字を取得します。 | | **CT (City)** | すべての文字を小文字に変換し、アルファベット (a-z) 以外の文字を削除します。 | | **ST (States)** | すべての文字を小文字に変換し、英数字 (a-z および 0-9) 以外の文字を削除します。 値が米国の州の場合は、2 文字の ANSI 略語コードを使用します。Treasure Data プラットフォームは、米国外の州をサポートする必要があるため、入力文字列を (2 文字に) 切り詰めません。 | | **ZIP (Zip code)** | 先頭と末尾の空白をトリミングし、すべての文字を小文字に変換し、結果から英数字または空白以外の文字を削除します。 値が米国の郵便番号の場合は、正確に 5 桁を使用します。Treasure Data プラットフォームは、英国の郵便番号形式をサポートする必要があるため、入力文字列を (5 文字に) 切り詰めません。 | | **LOOKALIKE_VALUE** | Long または double 値。null または空の値は 0 として送信されます。このカラムは Value-based Custom Audience のみでサポートされます。 | ## TD Console を使用する ### 新しい Connection の作成 Treasure Data では、クエリを実行する前にデータコネクションを作成して設定する必要があります。データコネクションの一部として、インテグレーションにアクセスするための認証を提供します。 ターゲットプラットフォームにデータをエクスポートする前に、Facebook Custom Audience の認証を確立する必要があります。認証を作成する手順は次のとおりです。 1. **TD Console** を開きます。 2. **Integrations Hub** > **Catalog** に移動します。 3. **Facebook Custom Audiences** を検索して選択します。 ![](/assets/image2021-7-8_16-20-34.69d630eff436179447108c78ef84e2befaa0f8df75b381dd88daddd506d0d38b.40636315.png) 4. **Create Authentication** を選択します。 5. Authentication Method で **Access Token** または **Oauth** のいずれかを選択します。 ![](/assets/create_auth_new.50fe9f436df55f173760cefe3d492c452d58af34bcc51bc93e18c6a62c052e4d.40636315.png) 6. - **Access Token:** Access Token と App Secret を入力します。 - **Oauth:** Facebook Custom Audiences の既存の OAuth 接続を選択するか、OAuth connection の下にある **Click here** リンクを選択して新しい接続を作成します。Facebook アカウントへのログインと Treasure Data コネクターアプリケーションへのアクセス許可を求められます。 - **Allow fetching Ads Account**: このオプションを有効にすると、アクティベーション作成時に事前に入力されたドロップダウンから Ads Account を選択できます。 Catalog にリダイレクトされた後、新しい OAuth 接続を選択します。 7. **Continue** を選択します。 8. 接続に名前を付けます。 9. **Done** を選択します。 ### クエリの定義 カラム名は大文字と小文字を区別しません。たとえば、email または EMAIL を使用できます。 出力結果は [Facebook User schema](https://developers.facebook.com/docs/marketing-api/reference/custom-audience/users/) に従う必要があります。サポートされているカラム名は次のとおりです。 - **EXTERN_ID**: External ID - **MADID**: Mobile advertiser ID - **EMAIL**: メールアドレス - **PHONE**: 電話番号 - **GEN**: 性別 - **DOBY**: 生年（年） - **DOBM**: 生月（月） - **DOBD**: 誕生日（日） - **LN**: 姓 - **FN**: 名 - **FI**: 名のイニシャル - **CT**: 市区町村 - **ST**: 都道府県 - **ZIP**: 郵便番号 - **COUNTRY**: 国コード - **PAGEUID**: Page scope user id - **LOOKALIKE_VALUE**: value-based Custom Audience の値 クエリ結果にサポートされているカラムが見つからない場合は、エラーが発生します。 ### クエリデータの宛先へのエクスポート 1. [Creating a Destination Integration](https://docs.treasuredata.com/smart/project-product-documentation/creating-a-destination-integration) の手順を完了します。 2. **Data Workbench > Queries** に移動します。 3. データをエクスポートするクエリを選択します。 4. クエリを実行して結果セットを検証します。 5. **Export Results** を選択します。 6. 既存の Integration Authentication を選択します。 ![](/assets/image2020-12-18_13-44-6.09e8af43184e33e337bef7c546600eaaa5be9f010b690af1d591c7c2b4bb2df3.c27c97ee.png) 7. 追加の Export Results の詳細を定義します。エクスポート統合コンテンツで、統合パラメータを確認します。 たとえば、Export Results 画面が異なる場合や、入力する追加の詳細がない場合があります。 ![](/assets/image2023-5-17_14-42-52.d2483b20e117c4abf1aaa32c5071595644e4c6b9d987ef4ea4ce4a2038171b85.c27c97ee.png) 8. **Done** を選択します。 9. クエリを実行します。 10. 指定した宛先にデータが移動したことを検証します。 ### Facebook Custom Audiences の統合パラメータ | パラメータ | 説明 | | --- | --- | | **Ad Account ID** (必須) | act_ プレフィックスなしの Ad Account ID です。API パラメータ: ad_account_id | | **Action** | Custom Audience からユーザーを **Add、Replace** または **Remove** を選択します。注意: Facebook では、低い Audience サイズ（1000 ユーザー未満）からユーザーを削除すること、またはユーザーを削除すると Audience サイズが低くなる場合は許可されず、エラー `You cannot remove users from this audience because it will result in a low audience size.` が表示されます。API パラメータ: `action` (ADD_USERS または REMOVE_USERS、デフォルト: ADD_USER) | | **Custom Audience Name** (必須) | **重要な注意**: この入力と同じ名前の Custom Audience が多数ある場合、最新の Custom Audience Name が使用されます。Custom Audience には一意の名前を付けることをお勧めします。 - Add: 指定された名前の Custom Audience が存在しない場合、その名前で新しい Custom Audience を作成します。エクスポートされた結果はターゲット Audience に追加（付加）されます。 - Replace: 指定された名前の Custom Audience のレコードを新しくアップロードされたレコードに置き換えます。一度に 1 つのカスタム Audience を置き換えるジョブを処理できます。TD 側でジョブが完了した後、Instagram 側でさらに時間がかかります。その間、他のユーザーはそのカスタム Audience を置き換えることができません。 - Remove: このフィールドを空白にすると、すべての Custom Audiences からユーザーが削除され、それ以外の場合はこの名前からユーザーが削除されます。 API パラメータ: output_name | | **Custom Audience Description** | Custom Audience のオプションの説明。API パラメータ: output_description | | **No need to normalize and hash records** (デフォルト false) | データがすでに正規化およびハッシュ化されているかどうかを示します。そうでない場合、TD は自動的にレコードを正規化してハッシュ化します。 API パラメータ: pre_hashed | | **Is Value Based?** | Value-Based Custom Audience を作成または更新します。このフィールドは、データに LookAlike_Value カラムがある場合に必要です | | **Page ID** | Page scope user id を収集するために使用される Facebook ページ。このフィールドは、`pageuid` カラムを指定してユーザーを追加または削除する場合に必要です。API パラメータ: page_id | | **Source of customer data** | このファイルに収集されたユーザー情報のソースを指定します。このフィールドは、**Action** が **Add** ユーザーで、Custom Audience Name が存在しない場合に必要です。 API パラメータ: customer_file_source (デフォルト: null、値: USER_PROVIDED_ONLY, PARTNER_PROVIDED_ONLY, BOTH_USER_AND_PARTNER_PROVIDED) | | **Initial intervals in milliseconds between retries** (オプション、デフォルト 60000) | 回復可能なエラーが発生した場合に再試行する間隔（ミリ秒単位）。 | | **Retry limit** (オプション、デフォルト 5) | 試行が終了するまでの再試行回数。 | | **Sending large audiences** | このオプションを有効にすると、Audience に大量のユーザーを送信できます。デフォルトは false です（Replace アクションの場合のみ）。デフォルト: False。 | ![](/assets/queries-untitled-query-treasure-data-2.30f519bc9515f1b3250e87929b69d61e6d00a2135041d44ddfae22a3efc216ac.40636315.png) ### Audience Studio での Facebook Custom Audiences の Ad Account ドロップダウンメニュー Audience Studio のアクティベーション作成/編集画面で、Ad Account ID フィールドに手動入力の代わりに便利なドロップダウンメニューが追加されました。ユーザーがフィールドを選択すると、アクセス権のある Facebook Ad アカウントのリストが自動的に表示されます。ドロップダウンの各エントリには、簡単に識別できるように Ad Account ID とそれに関連付けられた名前（例: "106640720131327 - Nhien An"）の両方が表示されます。ユーザーは ID を手動で入力するのではなく、リストから目的のアカウントをクリックするだけでよく、入力エラーが減り、ユーザーエクスペリエンスが向上します。 #### クエリの例 クエリでエイリアスを使用して、クエリ結果のカラム名を変更できます。例： ```sql SELECT an_email_column AS EMAIL, another_phone_column AS PHONE FROM your_table; ``` 以下は、クエリ結果の出力*前*のオーディエンスリストの例です： ![](/assets/image-20191009-220341.88aa3bf1b1539bdd376d0da58ad4bc47dda538d61aecfbfe06aabc5546087427.40636315.png) Treasure Dataから、Facebook Custom Audienceへの接続に結果を出力して、以下のクエリを実行します： ```SQL SELECT email, fn, ln FROM ( VALUES ('demo1@example.com', 'John', 'Doe'), ('demo2@example.com', 'Isaac', 'Miceli'), ('demo3@example.com', 'Christopher', 'Agar') ) tbl (email, fn, ln) ``` またはPage scope user IDの場合： ```sql SELECT pageuid FROM ( VALUES('2018728488162687') , ('1785406501565085') , ('2341287802551031') , ('2487019361340533') , ('1093039407464499') ) tbl (pageuid) ``` このクエリは実際のユーザーとは一致しません。デモ目的のみです。また、このクエリはソーステーブルを必要としませんが（この機能をテストしやすくするため）、データベースを選択する必要がありますので、「sample_datasets」または他の任意のテーブルを選択してください。Page scope user IDをアップロードするには、ページIDが必要です。例：ページID：`136400506505739` クエリは数秒で完了するはずです。その後、オーディエンスリストを確認してください： ![](/assets/image-20191009-220428.ac9853c3dfd6616b987777e178bd3c13253b082e97a569a7174bd5b48f71dff6.40636315.png) ### (オプション) 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 を有効にすることで、クエリの開始時刻を遅延させることができます。 ## 広告配置の編集 Instagram Custom Audienceにユーザーリストを出力した後、 1. Facebook/Instagram Ads Managerを開いて広告配置を編集します。デフォルトでは、FacebookはInstagram広告内に表示することを選択します。 ![](/assets/image-20191017-152524.064bc1dbbeb0ecf64152ae4461bf71f76eca63dd0f0bc8b6cebeba57f6afb39c.40636315.png) 2. 自動配置（デフォルト）： 3. 配置の編集： ![](/assets/image-20191017-152759.d7ddf43c63f911343db6bd54b1706a98c81d3be6c2d092f7023ea0ac9d4b7697.40636315.png) ## Business Managerへの広告アカウント追加エラーメッセージのトラブルシューティング 次のエラーが表示された場合： `This ad account is not connected to Business Manager. To create or edit a customer file Custom Audience, your admin needs to connect this ad account to a business account.` 広告アカウントをBusiness Managerアカウントに追加する必要があります。 以下の手順に従ってください： 1. Business Managerアカウントを作成：[https://www.facebook.com/business/help/1710077379203657](https://www.facebook.com/business/help/1710077379203657) 2. 広告アカウントを追加：[https://www.facebook.com/business/help/910137316041095](https://www.facebook.com/business/help/910137316041095) ![](/assets/image-20191009-221101.cd209babc4fda8f0357843fbd7d309bb67ba53b5ab266ea9fb58fcbd6b508329.40636315.png) 3. 以下のいずれかを選択： | **パラメータ** | **説明** | | --- | --- | | **広告アカウントを追加** | 広告アカウントを追加すると、アカウントは永続的にBusiness Managerに移行されます。広告アカウントを追加するには、広告アカウントの所有者であり、かつBusiness Managerの管理者である必要があります。広告アカウントを追加してBusiness Managerに移行した場合、その操作を元に戻すことはできません。また、広告アカウントのすべての管理は、Business Managerプロファイル内で完了する必要があることに注意してください。別のBusiness Managerが所有する広告アカウントは追加できません。それでも別のビジネスが所有する広告アカウントで作業したい場合は、そのアカウントへのアクセスをリクエストできます。 | | **広告アカウントへのアクセスをリクエスト** | Business Manager内の広告アカウントへのアクセスをリクエストすると、そのBusiness Managerの管理者がそのアカウントで作業する権限を付与できます。 | | **新しい広告アカウントを作成** | Business Managerで新しい広告アカウントを作成すると、そのアカウントは永続的にそのBusiness Managerに属します。Business Manager内で作成された広告アカウントは、Business Managerロールを所有していない個人の所有者に譲渡することはできません。 | ## Workflowでのエクスポート結果の構成（オプション） Treasure Workflow内では、このデータコネクタを使用してデータをエクスポートするように指定できます。 詳細については、[TD Toolbeltを使用したWorkflowによるデータエクスポート](https://api-docs.treasuredata.com/en/tools/cli/api/#workflow-commands)を参照してください。