# Tiktok Marketing API Export Integration

TikTokは、短編動画に焦点を当てたグローバルなソーシャルネットワーキングサービスで、世界中で10億人のアクティブな月間ユーザーがいると報告されています。TikTokのMarketing APIを使用して、カスタムセグメントを作成することで顧客をターゲティングできます。

Treasure Dataの[TikTok](https://ads.tiktok.com/marketing_api/homepage) Integrationを使用すると、カスタムオーディエンスを使用して、Treasure DataからTikTok Marketingにジョブ結果を直接送信できます。

## この統合で何ができますか？

- オーディエンスセグメントをTikTokに送信して、既存顧客を再ターゲティングし、より多くの類似オーディエンスを引き付けるための最適なキャンペーンを構築します。
- エンドユーザーが明示的にオプトアウト同意を与えた場合、ターゲティングを停止します。


## 前提条件

- Treasure Dataの基本的な知識。
- [TikTok Ads ManagerとTikTok Marketing API](https://ads.tiktok.com/marketing_api/docs?id=1701890905779201)の基本的な知識。
- トークンベースの認証方法を選択する場合（Oauthメソッドには不要）：
  - [TikTok Marketing API](https://ads.tiktok.com/marketing_api/homepage)の[開発者アカウント](https://ads.tiktok.com/marketing_api/docs?id=1701890911024129)と承認されたアプリケーション。
  - APIリクエストを行うための好みのツールを使用してTikTokからアクセストークンを取得します。


## 要件と制限事項

- アップロードできる最大ファイルサイズは、ファイルあたり50MB、オーディエンスあたり500ファイルです。つまり、最大50MB * 500ファイル = 25000 MB〜25GBのアップロードのみをサポートします。プラグインの制限により、実際のサイズは約20GBです。
- オーディエンスを作成した後、オーディエンスは1時間以内にアクセス可能になります。
- カスタムオーディエンスの最大数は400です。
- ハッシュ化前のデータは、すべて大文字または小文字である必要があります。
- 広告グループでカスタムオーディエンスをターゲティングするには、最小オーディエンスサイズ1,000が必要です。
- オーディエンスサイズは、TikTokのAds ManagerのAudiencesページで**24〜48時間**以内に更新されます。
- **OAuth認証**方法を使用する場合、Tiktok OAuthアプリケーションのAPIクォータのために、クォータ警告が表示される場合があります。コネクタが一定期間後に自動的に再試行してジョブを続行する間、遅延が予想されます。
- **トークンベースの認証**方法を使用する場合は、TikTok担当者に連絡して、特定のAPIアクセス（Streaming APIなど）をホワイトリストに登録してください。


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

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

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

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


![](/assets/72058435.63bec4373dea4cd0dd6afbda613b3ddf95503b4d8d6531cd08cf56eab184175d.1ee14251.png)

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


推奨：OAuthフローを使用する 次の理由から、OAuthフローの使用を強くお勧めします：

1. シンプルさと利便性：OAuthフローは、開発者認証情報を管理する必要なく、TikTok Adsアカウントを迅速かつ簡単に承認できるように、ユーザーフレンドリーに設計されています。
2. セキュリティ：OAuthは、承認のための安全な業界標準です。認証情報が保護されることを保証し、機密情報の露出リスクを軽減します。
3. メンテナンスフリー：OAuthを使用することで、独自の開発者アプリの管理に伴う継続的なメンテナンスと更新の必要性を回避できます。TreasureDataがすべての複雑さを処理し、マーケティングキャンペーンに集中できます。
4. 時間の節約とエラーが少ない：開発者アカウントを作成してからアクセストークンを取得するためのアプリを開発するのは、時間のかかるプロセスです。アプリの設定、キーの管理、TikTokのポリシーへのコンプライアンスの確保など、複数のステップが含まれ、エラーが発生しやすく面倒です。


**認証モードとしてOauthを選択**

- ブラウザでTikTokアカウントにログインし（以前にログインしていない場合）、**Confirm**を選択して**Treasure Data - TikTok Data Connector**に権限を付与します


![](/assets/83511415.feac7ceb07b448482adb3a602148907fe9dcacea3d7d66bfea35b80f4bb70761.1ee14251.png)

- 確認後、Catalogページにリダイレクトされます。Tiktokを選択すると、新しく作成されたOauth接続で**Continue**を選択できます。


**Access Token - 認証モードを選択**

- 認証するためにアクセストークンを入力し、**Continue**を選択します。
  - Tiktok Access Tokenを作成するには、[こちら](/ja/int/guides-for-creating-tiktok-marketing-api-developer-account-and-application)のガイドを参照してください。


![](/assets/72058434.6ce9159a70716fd1d8b603a8525451ebc84cc2e31c9a56b4b2b295cf86993146.1ee14251.png)

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


### クエリを定義する

クエリにはidカラムが必要です。

1. [destination integrationの作成](https://docs.treasuredata.com/smart/project-product-documentation/creating-a-destination-integration)の手順を完了します。
2. **Data Workbench > Queries**に移動します。
3. データをエクスポートするクエリを選択します。
4. クエリを実行して結果セットを検証します。
5. **Export Results**を選択します。
6. 既存の統合認証を選択します。
![](/assets/72058432.09e8af43184e33e337bef7c546600eaaa5be9f010b690af1d591c7c2b4bb2df3.1ee14251.png)
7. 追加のExport Results詳細を定義します。エクスポート統合コンテンツで、統合パラメータを確認します。


たとえば、Export Results画面が異なる場合や、完了する追加の詳細がない場合があります。
![](/assets/72058430.dbfc46347631c97a7b8a5007fe3124805c3b8bec4a47ef692b0b3cf31991f1ca.1ee14251.png)

1. **Done**を選択します。
2. クエリを実行します。
3. データが指定した宛先に移動したことを検証します。


### TikTokの統合パラメータ

| Parameter | Types  | Description  |
|  --- | --- | --- |
| auth_method | Enum：- oauth
- access_token

 | このコネクタは2つの認証方法をサポートします： - **OAuth**認証 - ユーザーはUIでaccess_tokenを直接入力できます - 独自のTiktok Appを作成する必要があります。[こちら](https://docs.treasuredata.com/display/INT/TikTok+Marketing+API+Export+Integration#TikTokMarketingAPIExportIntegration-CreatingYourOwnTikTokMarketingAPIDeveloperAccountandApplication)を参照してください。 |
| access_token | String | Access Tokenモードのみ。 |
| use_sandbox | boolean | Access Tokenモードのみ。セグメントをTikTokのサンドボックス環境にプッシュしようとしていることを示すフラグ。 |
| api_mode | Enum、サポートされる値： - CUSTOMER_FILE - STREAMING | サポートされるTikTok APIモード。- **推奨：Streaming APIを使用する** 次の理由から、Streaming APIの使用を強くお勧めします：
  1. **リアルタイムデータ更新**：Streaming APIはリアルタイムのデータ更新を可能にし、顧客データが常に最新であることを保証します。これは、最新の情報でオーディエンスをアクティブ化し、キャンペーンを開始するために重要です。
  2. **大容量データのスループットの向上**：大量のデータを処理する場合、Streaming APIはより良いスループットを提供し、大容量データの同期をより効率的で信頼性の高いものにします。
  3. **将来性**：TikTokはCustomer File APIを廃止する予定です。今Streaming APIを選択することで、将来の移行の必要性を回避し、時間と労力を節約できます。

 |
| advertiser_id | String | TikTokでの広告主のID。 |
| audience_name | String | オーディエンスの名前。**注：**この設定キーはCUSTOMER_FILEモードのみで使用されます。 |
| encryption_type | Enum (FIRST_SHA256, FIRST_MD5, EMAIL_SHA256, PHONE_SHA256, IDFA_SHA256, IDFA_MD5, GAID_SHA256, GAID_MD5) | IDタイプ。
**注：**この設定キーはCUSTOMER_FILEモードのみで使用されます。 |
| audience_action | Enum- APPEND
- REMOVE,
- REPLACE

 | オーディエンスのアクション（REMOVE、REPLACE、ADD）。
**注：**この設定キーはCUSTOMER_FILEモードのみで使用されます。 |
| streaming_action | Enum、サポートされる値：- ADD
- DELETE
- DELETE_AUDIENCE

 | Streamingエクスポートモード。デフォルト値はADDです。
**注：**この設定キーはSTREAMINGモードのみで使用されます。 |
| audience_names | String | カンマで区切られたセグメントオーディエンス名のリスト。
**注：**この設定キーはSTREAMINGモードのみで使用されます。 |
| audience_ids | String | カンマで区切られたオーディエンスIDのリスト。
**注：**この設定キーはSTREAMINGモードのみで使用されます。 |
| skip_invalid_record | boolean | - true：無効なレコードをスキップしてジョブを続行する
- false：無効なレコードを処理するときにジョブを停止する

 |
| thread_count | Integer | TikTokへの並列リクエストを設定可能。デフォルト値は5です。**注：**この設定キーはSTREAMINGモードのみで使用されます。 |


### クエリ例

CUSTOMER_FILEモードでは、**id**という名前の1つのカラム/エイリアスのみをサポートします


```sql
SELECT id
FROM my_table
```

Streamingモードは、複数のカラム/エイリアスをサポートできます：**email, email_sha256, phone, phone_sha256, idfa, idfa_md5, idfa_sha256, aaid, aaid_md5, aaid_sha256**


```sql
SELECT email, phone, idfa, aaid
FROM my_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) を参照してください。

## TD CLIの例


```bash
td query \
  -d my_database \
  -r '{
    "accessToken": "__SAVED__",
    "useSandbox": true,
    "advertiserId": "12345678901234567890",
    "apiVersion": "v1.2",
    "audienceAction": "REPLACE",
    "audienceName": "test",
    "encryptionType": "FIRST_NORMAL"
  }' \
  "SELECT id FROM my_table" \
  -T presto
```