# Instagram Custom Audience Export Integration

ジョブの結果をInstagram Custom Audienceに直接書き込むことができます。InstagramはFacebookの一部であるため、これらの手順にはFacebookの技術仕様への参照が含まれています。

Custom Audienceは、Instagram上のユーザーの中から既存のオーディエンスを見つけることができる広告ターゲティングオプションです。顧客リスト、Webサイトやアプリのトラフィック、またはFacebookでのエンゲージメントなどのソースを使用して、既にビジネスを知っている人々のCustom Audienceを作成できます。

以下を作成できます:

- Website Custom Audiences
- App Activity Custom Audience
- Customer List Custom Audience
- Engagement Custom Audiences


## 前提条件

- [TD Toolbelt](https://toolbelt.treasuredata.com/)を含むTreasure Dataの基本知識
- Instagram Ad Account
- InstagramのBusiness Profile
- 自身のInstagram Ad AccountへのTreasure Data Facebookアプリケーションアクセスの承認


## Instagram Custom Audiencesのデータ正規化について

Treasure Dataの結果出力は、Facebookの正規化ルールに従って値を自動的に正規化します。[こちら](https://developers.facebook.com/docs/marketing-api/audiences-api#hash)を参照してください。

マッチングのためにFacebookにアップロードされるすべての値は、Facebookの正規化ルールで正規化する必要があります。正規化されていない場合、値はマッチングの機会を逃すことになります。データを手動で正規化する必要がある場合は、結果を出力する前に独自の正規化を適用してください。

正規化のために、結果出力時にデータタイプに応じて以下の変換動作が適用されます。

- **EXTERN_ID (External ID)**: アクションは不要です。
- **EMAIL (Email addresses)**: 先頭と末尾の空白をトリミングし、すべての文字を小文字に変換します。
- **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)以外のすべての文字を削除します。
  - **注**: 値がUS Stateの場合、2文字のANSI略語コードを使用してください。Treasure Dataプラットフォームは、米国外の州をサポートする必要があるため、入力文字列を(2文字に)切り捨てません。
- **ZIP (Zipcode)**: 先頭と末尾の空白をトリミングし、すべての文字を小文字に変換し、結果から英数字または空白以外のすべてを削除します。
  - **注**: 値がUS zip codeの場合、正確に5桁を使用してください。Treasure Dataプラットフォームは、UKのzip code形式をサポートする必要があるため、入力文字列を(5文字に)切り捨てません。
- **LOOKALIKE_VALUE**: LongまたはDouble値。null値または空の値は0として送信されます。このカラムは、value-based Custom Audienceによってのみサポートされます。


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

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

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

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


![](/assets/image2021-7-8_13-3-2.f647fc1af65383e5076d1c085b94372223d88e47a3e533b932bd4099ff45c772.119f8de3.png)

1. Create Authenticationを選択します。
![](/assets/image2021-7-8_13-4-28.2621d93ca49c5e8dd840d199f6e428fcdb5548bd52a52d750ebfc2c7b01a4011.119f8de3.png)
2. 接続を承認するか、**Click here**を選択します。
オプションで、プロンプトに従って別のFacebookアカウントにログインします。
![](/assets/image-20191015-211818.54de5701118ec4f312310823730398d37199015ac58602549d161a0cb3e1178c.119f8de3.png)


##### オプションで、Facebookアカウントにログインし、**Treasure Data**へのアクセスを許可します。

Catalogにリダイレクトされます。最初のステップ(新しい接続を作成する)を繰り返し、新しいOAuth接続を選択します。

1. **Continue**を選択します。
2. 接続に名前を付けます。
3. **Done**を選択します。


# クエリを定義する

カラム名は大文字と小文字を区別しません。つまり、emailまたはEMAILを使用できます。

以下は、クエリ結果の出力*前*のAudiencesリストの例です:

![](/assets/image-20191017-152453.30680b0d6b30ed0afd641edcedcebc3a72914dda7cf7cd1a08dfeb53a874dc36.119f8de3.png)

Treasure Dataから、Instagram 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)
```

上記のクエリは実際のユーザーとマッチせず、デモ目的のみです。また、このクエリはソーステーブルを必要としません(この機能のテストを容易にするため)が、データベースを選択する必要があるため、「sample_datasets」または他の任意のテーブルを選択してください。クエリは数秒で完了します。その後、Audience Listを確認してください:

![](/assets/image-20191019-001512.729b9e9a4c9c1d86304f914591ff6c372b16ce888be6f8d11ad943bb60308240.119f8de3.png)

## カラムの命名

出力結果は[Facebook User schema](https://developers.facebook.com/docs/marketing-api/reference/custom-audience/users/)に従う必要があります。カラム名は大文字と小文字を区別しません。つまり、emailまたはEMAILを使用できます。サポートされているカラム名は以下の通りです:

- **EXTERN_ID**: External ID
- **EMAIL**: Email addresses
- **PHONE**: Phone numbers
- **GEN**: Gender
- **DOBY**: Birth Year
- **DOBM**: Birth Month
- **DOBD**: Birthday
- **LN**: Last Name
- **FN**: First Name
- **FI**: First Initial
- **CT**: City
- **ST**: States
- **ZIP**: Zip code
- **MADID**: Mobile advertiser id
- **COUNTRY**: Country code
- **LOOKALIKE_VALUE**: value for value-based lookalike audience


クエリ結果からサポートされているカラムが見つからない場合、エラーがスローされます。

[Export Integrationを使用した結果のエクスポート](https://docs.treasuredata.com/articles/pd/exporting-results-using-export-integration)を参照してください。

## Instagram Custom Audiencesの統合パラメータ

![](/assets/image2021-7-8_13-26-29.cac8d47a93bb88cf4eb7c2a31afaf17047e7763db185e7b12b4b8a3929979b9a.119f8de3.png)

| パラメータ | 値 | 説明 |
|  --- | --- | --- |
| **Ad Account ID** | 必須 | act_プレフィックスなしのAd Account IDです |
| **API Version** | オプション、デフォルトv2.11 | Facebook/Instagram API Version。デフォルト値を維持することをお勧めします。 |
| **Action** | Add  Remove  Replace | - Add: Custom Audienceにレコードを追加 - Remove: Custom Audienceからレコードを削除 - Replace: Custom Audience内のレコードを置換。一度に処理できるcustom audienceを置換するジョブは1つに制限されています。TD側でジョブが完了した後、Instagram側でさらに時間がかかります。その間、他のユーザーはそのcustom audienceを置換できません。 |
| **Custom Audience Name** | 必須 | 作成/更新するCustom Audienceの名前。存在しない場合は、新しく作成されます。   - **重要な注意**: この入力と同じ名前のCustom Audienceがある場合、最新のものが使用されます。Custom Audienceにはユニークな名前を付けることをお勧めします |
| **Custom Audience Description** | オプション | Custom Audienceの説明。 |
| **Page ID** | オプション | アップロードされるユーザーが使用するPAGE ID。スキーマがFacebook UIDで、IDがPage webhook統合によって収集された場合に必須です。 |
| **Source of customer data** | User  Partner  Both | このファイルに収集されたユーザー情報のソースを指定します。 |
| **No need to normalize and hash records** | true  false | データがすでに正規化およびハッシュ化されているかどうかを示します。そうでない場合、TDは自動的にレコードを正規化してハッシュ化します。 |
| **Initial intervals in milliseconds between retries** | オプション、デフォルト60000 | 回復可能なエラーが発生した場合の再試行間隔(ミリ秒単位)。 |
| **Retry limit** | オプション、デフォルト5 | 諦めるまでの再試行回数。 |


## クエリの例


```SQL
SELECT typeof(online_followers_lifetime) FROM instagram_test_insight_1 WHERE online_followers_lifetime <> '0';
```

エイリアスを使用してクエリ結果のカラムの名前を変更できます。例:


```SQL
SELECT an_email_column AS EMAIL,
another_phone_column AS PHONE
FROM your_table;
```

### (オプション) 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 を有効にすることで、クエリの開始時刻を遅延させることができます。

## 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 出力をカスタマイズします。


![](/assets/ouput.b2c7f1d909c4f98ed10f5300df858a4b19f71a3b0834df952f5fb24018a5ea78.8ebdf569.png)

- 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 番号。


1. **Schedule** を設定します。


![](/assets/snippet-output-connector-on-audience-studio-2024-08-28.a99525173709da1eb537f839019fa7876ffae95045154c8f2941b030022f792c.8ebdf569.png)

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


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


batch journey の activation を作成する必要がある場合は、[Creating a Batch Journey Activation](/products/customer-data-platform/journey-orchestration/batch/creating-a-batch-journey-activation) を参照してください。

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

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

詳細については、[TD Toolbeltを使用したWorkflowでのデータのエクスポート](https://api-docs.treasuredata.com/en/tools/cli/api/#workflow-commands)を参照してください。

### Ad Placementを編集する

ユーザーリストをInstagram Custom Audienceに出力した後、

1. Facebook/Instagram Ads Managerを開いてad placementを編集します。デフォルトでは、FacebookはInstagram Ads内に表示することを選択します。
2. Automatic Placements(デフォルト): ![](/assets/image-20191017-152524.064bc1dbbeb0ecf64152ae4461bf71f76eca63dd0f0bc8b6cebeba57f6afb39c.119f8de3.png)
3. Edit Placement:


![](/assets/image-20191017-152759.d7ddf43c63f911343db6bd54b1706a98c81d3be6c2d092f7023ea0ac9d4b7697.119f8de3.png)