# Snapchat Conversions API エクスポートインテグレーション

This feature is in BETA version. For more information, contact your Customer Success Representative.

## 概要

Snapchat Conversions API (CAPI) コネクタは、Web、モバイル、オフラインチャネル全体でのコンバージョンイベントのサーバーサイドトラッキングと測定を可能にします。Snapchatの Events Manager と直接統合することで、このコネクタは企業がキャンペーンのパフォーマンスを測定し、Snapchatの3億人以上のデイリーアクティブユーザー全体で広告配信をより効果的に最適化するのに役立ちます。

主な機能：

- **Web Events**: ピクセルデータを補完するサーバーサイドトラッキングにより、測定精度を向上
- **Mobile App Events**: アプリ内コンバージョンイベントの直接統合
- **Offline Events**: 店舗での購入など、非デジタルコンバージョンのサポート
- **Data Validation**: Snapchat の CAPI 仕様に合わせた自動イベント検証とフォーマット


このサーバーサイド統合は、クライアントサイドソリューション単独と比較して、より信頼性の高いコンバージョントラッキングと改善された広告パフォーマンス測定を提供します。

## 前提条件

- TD Toolbelt を含む Treasure Data の基本知識
- Snapchat Business の基本知識
- Snapchat Access Token または Snapchat Business アカウント


## 制限事項と既知の問題

- イベント時刻の制限
  - 7日以上前のイベント（`event_time` に基づく）は処理中にスキップされます
  - イベント時刻の検証は、エポック変換と7日間ウィンドウの計算に UTC タイムゾーンを使用します
- OAuth 認証と Conversion API トークン認証間の無効な Event Source ID エラーメッセージの相違
  - 異なる認証方法では、無効な `event_source_id` に対して異なるエラーレスポンスが生成されます：
    - Conversion API Token 認証を使用する場合、エラーメッセージは次のようになります：

```json
{  "status": "INVALID",  "reason": "Unauthorized resources" }
```
- OAuth 認証を使用する場合、エラーメッセージは次のようになります：

```json
{  "status": "INVALID",  "test_event": true,  "reason": "At least one of the events is invalid.",  "event_logs": [    {   "event": 1,     "status": "INVALID",     "errors": {       "codes": [         "523"       ],       "error_msgs": [         "The provided asset id must be valid UUID format."       ]            }  }}
```
- OAuth 認証を使用する場合、エラーレスポンスメッセージは無効な Event Source ID を明示的に示さず、代わりに無効な "asset id" を参照します。そのため、Event Source ID が不明な場合のより信頼性の高いエラー処理には、ジョブ実行時に Conversion API Token 認証を使用することをお勧めします。
- Anonymous ID フィールド（`anon_id`）：API ドキュメントの "User Data Parameter" セクション（[リンク](https://developers.snap.com/api/marketing-api/Conversions-API/Parameters#user-data-parameters)）で標準フィールドとして文書化されているにもかかわらず、`anon_id` は `user_data` オブジェクトに含めることができません
  - `user_data` で `anon_id` を使用しようとすると、次のエラーが発生します：

```json
{  "status": "INVALID",  "reason": "Request parsing failed. Ensure the request body is correctly formatted." }
```
  - そのため、回避策として、API エラーを避けるために `anon_id` を `user_data` オブジェクトではなく custom data オブジェクトにマッピングする必要があります。


## TD Console で新しい接続を作成する

クエリを実行する前に、TD Console でデータ接続を作成して設定する必要があります。データ接続の一部として、インテグレーションにアクセスするための認証を提供します。次の手順を完了してください。

![](/assets/screenshot-at-nov-04-14-12-04.fe86b4b30398f73429a8a1d2b60f0c25f33d3bb84415d80a62f48b4bf75586f5.fe495661.png)

1. TD Console を開きます。
2. **Integrations Hub > Catalog** に移動します。
3. **Snapchat Conversions API** を検索して選択します。アイコンにカーソルを合わせて **Create Authentication** を選択します。
4. **Credentials** タブが選択されていることを確認し、インテグレーションの認証情報を入力します。次のいずれかを選択します
  1. **OAuth 認証ワークフロー：**「Click here」リンクを選択して OAuth 認証フローを開始します。認証が完了すると、新しい OAuth 接続が作成され、ドロップダウンで利用できるようになります。
![](/assets/3.bed4eac368ecd5d69800b167de35e2416ac0e1c47c471c89966575eb44707e59.0efdb04c.png)
**Continue** を選択して新しい接続を作成します。
b. **Conversion API Token ワークフロー**：Snapchat Business Manager からアクセストークンを取得し、**Conversion API Token** フィールドに入力します。
![](/assets/4.81329c42404d19cb9ee812121d2dadbbe07437b0f2ceff5566c6851aea8ce0f4.0efdb04c.png)
#### **認証フィールド**
| Parameter | Description |
|  --- | --- |
| Authentication Mode | 認証方法。サポートされる値：  - oAuth Connection: OAuth 認証 - Conversions API Token: Snapchat Business Manager で生成される長期アクセストークン |
| Conversions API Token | Conversions API Token は Snapchat Business Manager から取得できます。このパラメータは Conversion API Token 認証方法でのみ利用可能です。 |
5. **Continue** を選択します。
6. 認証の名前を入力し、Done を選択します。


### エクスポート用のクエリ結果を設定する

TD Console は、データをエクスポートする複数の方法をサポートしています。Data Workbench からデータをエクスポートするには、次の手順に従ってください。

1. **Data Workbench** > **Queries** に移動します。
2. **New Query** を選択し、クエリを定義します。
3. **Export Results** を選択してデータエクスポートを設定します。
4. 既存の Snapchat CAPI 認証を選択するか、前述の手順で新しい認証を作成します
5. **Done** を選択します。


#### コネクタ設定パラメータ

| **Field** | **Description** |
|  --- | --- |
| **Event Source Type** | 使用している Snapchat イベントデータソースのタイプを選択します。サポートされるイベントソースタイプには以下が含まれます：   - Web Events - Mobile App Events - Offline Events |
| **Event Source ID** | Web Events/Offline Events の場合は pixel_id、Mobile App Events の場合は snap_app_id のいずれかを入力して、イベントデータをアップロードする特定のイベントソースを選択します。 |
| **Send test events** | 実際のトラフィックの代わりにテストイベントを送信する場合に有効にします。 |
| **Skip invalid records?** | チェックすると、ジョブは無効なレコードをスキップして次のレコードの処理を続行します。それ以外の場合、ジョブは停止します。 |


### クエリ結果データ仕様の詳細ガイド

Snapchat CAPIにイベントデータをアップロードするには、Snapchat CAPIのガイドラインに準拠した標準フィールドとカスタムフィールドの組み合わせを含むデータエクスポートクエリを構築する必要があります。標準フィールドの場合、カラム名が「フィールド/カラムレベルの仕様」セクションに記載されているものと一致していることを確認してください。コネクターは自動的にカラム名を正規化してSnapchat CAPIの必須形式に一致させるため、大文字・小文字の区別を気にする必要はありません。たとえば、デフォルトフィールド「event_name」の場合、エクスポートクエリのカラム名は「EVENT_NAME」、「event_name」、「Event_Id」など、任意の大文字・小文字で記述できます。コネクターは、Snapchat CAPIの要件を満たすために、カラム名を「event_name」に標準化します。

Snapchat CAPIにユーザープロファイルデータを正常にアップロード/変更するには、特定のデータ仕様に準拠したエクスポートクエリを構築する必要があります。これらの仕様は2つのレベルに分かれています。

- **エクスポートクエリ仕様**（またはデータセットレベルのデータ仕様）：このセクションでは、必須フィールドの存在や複数のフィールドにまたがるデータ検証ルールなど、クエリ結果データセット全体に適用される要件とルールについて説明します。
- **フィールド/カラムレベルの仕様**：このセクションでは、各フィールドのデータ型や形式など、データセット内の個々のフィールド/カラムの要件とルールについて詳しく説明します。


#### エクスポートクエリ仕様

| 仕様 | 説明 |
|  --- | --- |
| **ユーザーデータの条件付き必須フィールド** | エクスポートクエリには、以下の識別子フィールドのうち少なくとも1つが含まれている必要があります：- Email (`em`)
- Phone (`ph`)
- Snapchat click ID (`sc_click_id`)
- Client IP address (`client_ip_address`)/Client user agent (`client_user_agent`)
- Mobile advertiser ID (`madid`)

 |
| **PURCHASEイベントの条件付き必須フィールド** | エクスポートクエリにPURCHASEイベントが含まれている場合、以下のフィールドが必須です：- `currency`（有効なISO 4217コードである必要があります）
- `value`（数値である必要があります）

 |
| **標準フィールド名** | 標準フィールドのカラム名は任意の大文字・小文字で記述できます（例：「EVENT_NAME」、「event_name」、「Event_Name」）。コネクターは自動的にSnapchat CAPIの要件に合わせて標準化します。 |
| **Null値の処理** | NULL値を持つカラムはエクスポート中に無視されます。 |
| **重複カラム** | エクスポートクエリ内で重複するカラム名は許可されません。 |
| **カスタムフィールド** | 標準フィールドにリストされていないフィールドは、自動的に`custom_data`オブジェクトにマッピングされ、そのまま保持されます。正規化/フォーマットは行われません。 |
| **日時フォーマット** | `event_time`フィールドには、以下の形式が受け入れられます：- 10桁以上の整数（Unix エポックタイムスタンプ）
- ISO 8601形式の文字列
- Timestampデータ型

 |
| **配列フィールドのフォーマット**
 | 配列を受け入れるフィールド（例：`content_ids`、`content_category`、`suggested_destinations`）は、以下のいずれかの方法で構築できます：
1. 配列値を含む単一カラム、または
2. 数値サフィックス付きのフラット化されたカラム名

**フラット化されたカラムパターン：** `field_name_[index]` ここでインデックスは1から始まります
**例：** 3つの値を持つ配列フィールド`cont_id`を作成するには、以下のカラムを使用できます：
- `cont_id_1`
- `cont_id_2`
- `cont_id_3`

これらは自動的に次のように結合されます：`["value1", "value2", "value3"]`
 |
| **JSONオブジェクト配列の構築**
 | PURCHASEイベントの`contents`フィールドは、それぞれが以下のオプションフィールドを含むJSONオブジェクトのリストとしてフォーマットする必要があります：
- `id` (string)
- `quantity` (integer)
- `item_price` (float)
- `delivery_category` (string)

オブジェクトの配列は、次のパターンでフラット化されたカラム名を使用して構築できます：`field_name_property_name_[index]`
**例：** `data[].custom_data.contents`に`contents`オブジェクト配列を作成するには、以下を使用できます：
最初のオブジェクト：
- `content_id_1`
- `content_quantity_1`
- `content_item_price_1`
- `content_delivery_category_1`

2番目のオブジェクト：
- `content_id_2`
- `content_quantity_2`
- `content_item_price_2`
- `content_delivery_category_2`

これは自動的に次のように構築されます：

```json
[
  {
    "id": "ABC123",
    "quantity": 2,
    "item_price": 29.99,
    "delivery_category": "standard"
  },
  {
    "id": "XYZ789",
    "quantity": 1,
    "item_price": 49.99,
    "delivery_category": "express"
  }
]
```
 |
| **日付フィールド形式** | Custom Dataオブジェクトのcheckin_date日付フィールドは、以下の形式を使用できます：- YYYYMMDD
- YYYY-MM-DD

 |
| **アプリイベントの必須フィールド** | アプリイベントを送信する場合、エクスポートクエリに以下のフィールドが必要です：- `advertiser_tracking_enabled` (Boolean)
- `extinfo` (正確に16要素の配列)
- `app_id` (string)

 |
| **extinfo配列の要件** | `extinfo`フィールドは以下の条件を満たす必要があります：- 正確に16要素を含む
- 最初の要素として"i2"(iOS)または"a2"(Android)で始まる

 |
| **ハッシュ化されたフィールドの処理**
 | `user_data`オブジェクトでSHA256ハッシュ化が必要なフィールドについて、コネクタは以下のシナリオに対応します：
1. 既にハッシュ化されたデータ：
  - データが既にSHA256でハッシュ化されている場合(HEXパターンで検証)、そのまま使用されます
  - データがハッシュ化されているがSHA256でない場合、生データとして扱われ再ハッシュ化されます
2. 生データ：
  - Email (`em`)：メール形式で検証された後、正規化されハッシュ化されます
  - その他のフィールド (`ph`, `fn`, `ln`, など)：形式検証なしで正規化されハッシュ化されます

**注意**：コネクタはすべての正規化/ハッシュ化を自動的に処理します - 生データまたはSHA256ハッシュ化されたデータのいずれかを提供できます
 |


#### フィールド/カラムレベルの仕様

特別なフィールド処理があります

**Countryフィールド**

- `user_data`オブジェクトの場合：カラム名"country"を使用します(大文字小文字を区別しません)
- `custom_data`オブジェクトの場合：カラム名"custom_country"を使用します(大文字小文字を区別しません)


**句読点の削除**

特定のフィールドでは句読点の削除が必要です。この場合、以下の文字が削除されます：

- 基本的な句読点：`. , ! ? ; : - — " ' ( ) [ ] { } /  _`
- 特殊文字：`& * + = @ # $ % ^ ~ |`


**日付時刻の処理**

この統合では、日付時刻カスタムフィールドカラムに対して、timestampとしてキャストされた値またはISO-8601日付時刻文字列形式の値を処理できます。ISO-8601日付時刻文字列を使用する場合は、値の末尾に"Z"を含めることで、コネクタが日付時刻値を検出し、Snapchat CAPIのAPIコントラクトで要求されるUnix時刻値に変換できるようにしてください。

**日付時刻カスタムフィールドカラムの処理例**

**1. Timestampとしてキャスト**

- ソースデータテーブルにstring型のカラムを作成します：

```sql
ALTER TABLE source_data_table ADD COLUMN date_time_field VARCHAR;
```
- そのカラムに日付時刻値文字列を挿入します：

```sql
INSERT INTO source_data_table (id, date_time_field)VALUES(1, '2024-08-28'),(2, '2024-08-28 15:30:00'),(3, '2024-08-28T15:30:00');
```
- カラム値をtimestampとしてキャストします：

```
SELECT id, CAST(date_time_field AS timestamp) AS date_time_field FROM source_data_table;
```


**2. ISO-8601日付時刻文字列の使用**

- ソースデータテーブルにstring型のカラムを作成します：

```
ALTER TABLE source_data_table ADD COLUMN date_time_field VARCHAR;
```
- そのカラムに日付時刻値文字列を挿入します。"T"セパレータと末尾の"Z"を含むISO-8601形式でフォーマットされていることを確認してください：

```
INSERT INTO source_data_table (id, date_time_field)VALUES(1, '2024-08-28T00:00:00Z'),(2, '2024-05-28T15:30:00.123Z'),(3, '2024-02-28T15:30:00Z');
```
- クエリで直接カラムを使用します：

```
SELECT id, date_time_field FROM source_data_table;
```


#### サーバーパラメータの標準フィールド（トップレベルパラメータ）

| Field | Description | Required | Data Type | Additional Specifications |
|  --- | --- | --- | --- | --- |
| event_name | トラッキングされるイベントのタイプ* Yes | String | 以下のいずれかの値でなければなりません：- PURCHASE
- SAVE
- START_CHECKOUT
- ADD_CART
- VIEW_CONTENT
- ADD_BILLING
- SIGN_UP
- SEARCH
- PAGE_VIEW
- SUBSCRIBE
- AD_CLICK
- AD_VIEW
- COMPLETE_TUTORIAL
- LEVEL_COMPLETE
- INVITE
- LOGIN
- SHARE
- RESERVE
- ACHIEVEMENT_UNLOCKED
- ADD_TO_WISHLIST
- SPENT_CREDITS
- RATE
- START_TRIAL
- LIST_VIEW
- APP_INSTALL
- APP_OPEN
- CUSTOM_EVENT_1-5

 |
| event_time | イベント発生のタイムスタンプ | Yes | Integer/String/Timestamp | - Integer の場合：10桁以上の Unix エポックタイムスタンプでなければなりません
- String の場合：ISO 8601 形式でなければなりません
- Timestamp の場合：エポックミリ秒に変換されます
- 過去7日以上前であってはなりません

 |
| event_source_url
 | イベントが発生した URL
 | Yes（Webイベントの場合）
 | String
 | プロトコル（http/https）を含める必要があります
例：[https://example.com/page](https://example.com/page)
 |
| event_id | イベントの一意識別子 | No | String | 一意のイベントを表すために広告主が選択 |
| action_source | イベントのソース | Yes* | String | *設定画面の選択に基づいて自動的に設定されます：- WEB
- OFFLINE
- MOBILE_APP

 |
| data_processing_options | プライバシー処理オプション | No | Array of strings | 受け入れ可能な値：["LMU"]、["DELETE"] |
| advertiser_tracking_enabled | トラッキング許可インジケーター | No | Boolean | - OPT_IN の場合は 1
- OPT_OUT の場合は 0
- Webイベントの場合：トップレベルパラメータで使用
- アプリイベントの場合：app data オブジェクトで使用

 |


#### User Data オブジェクトの標準フィールド

以下のフィールドは、ユーザーとその属性を識別するために使用されます。email（em）、phone（ph）、sc_click_id、client_ip_address、client_user_agent、または mobile advertiser id（madid）のいずれか少なくとも1つの識別子フィールドが必要です。

| フィールド | 説明 | 必須 | データ型 | フォーマット要件 | 例 |
|  --- | --- | --- | --- | --- | --- |
| em | メールアドレス | 条件付き* | String/Array | - スペースはトリミングされます - 小文字に変換されます - 有効なメール形式でなければなりません - 自動的にハッシュ化されます | 入力：`Person@Example.com` 正規化後：`person@example.com` |
| ph | 電話番号 | 条件付き* | String/Array | - スペースが削除されます - 先頭の '00' と '0' が削除されます - 数字以外の文字、'+'、'-' は除外されます - 国コードを含める必要があります - 自動的にハッシュ化されます | 入力：`+44 844 412 4653` 正規化後：`448444124653` |
| sc_click_id | URL からの Snapchat クリック ID | 条件付き* | String | - UUID 形式でなければなりません - ランディングページ URL の ScCid パラメータにあります | `123e4567-e89b-12d3-a456-426614174000` |
| client_ip_address | デバイスの IP アドレス | 条件付き* | String | - IPv4 と IPv6 をサポート - サーバー IP ではなく、デバイス IP でなければなりません | `203.0.113.195` |
| client_user_agent | デバイスのユーザーエージェント | 条件付き* | String | 特別なフォーマットは不要 | `Chrome/87.0.4180.143` |
| madid | モバイル広告主 ID | 条件付き* | String | 自動的に小文字に変換されます | 入力：`123ABC` 正規化後：`123abc` |


*これらの識別子フィールドのうち、少なくとも1つが必要です。

##### オプションのユーザー属性

| フィールド | 説明 | データ型 | データ処理 |
|  --- | --- | --- | --- |
| fn | 名（ファーストネーム） | String/Array | - 小文字に変換されます - 句読点が削除されます - 特殊文字は UTF-8 エンコードされます - 自動的にハッシュ化されます |
| ln | Last name | String/Array | - 小文字に変換 - 句読点を削除 - 特殊文字をUTF-8エンコード - 自動的にハッシュ化されます |
| ge | Gender | String/Array | - 小文字に変換 - 受け入れられる値: 'f' (女性)、'm' (男性) - 自動的にハッシュ化されます |
| ct | City | String/Array | - 小文字に変換 - 句読点とスペースを削除 - 特殊文字をUTF-8エンコード - 自動的にハッシュ化されます |
| st | State | String/Array | - 米国: 2文字のANSIコードを使用 - 小文字に変換 - 句読点、特殊文字、スペースは不可 - 自動的にハッシュ化されます |
| zp | Zip/postal code | String/Array | - 小文字に変換 - スペースと'-'を削除 - 米国: 5桁を使用 - 自動的にハッシュ化されます |
| country | Country | String/Array | - 2文字のISO 3166-1 alpha-2コードに変換 - 小文字に変換 - 自動的にハッシュ化されます |


##### 追加の識別子フィールド

| フィールド | 説明 | 必須 | 備考 |
|  --- | --- | --- | --- |
| external_id | 一意の識別子 (例: ロイヤリティカードID) | いいえ | 自動的にハッシュ化されます |
| subscription_id | サブスクリプション識別子 | いいえ |  |
| lead_id | Snapchat Lead Ad識別子 | いいえ |  |
| anon_id | アプリインストール識別子 | いいえ | アプリイベントのみ、このフィールドはSnapchat APIエラーを回避するためにcustom_dataオブジェクトにマッピングされます |
| download_id | アプリダウンロード識別子 | いいえ |  |
| sc_cookie1 | Pixel SDKからのファーストパーティCookie | いいえ | UUID形式である必要があります |
| idfv | IDFV値 | いいえ | プレーンテキスト値 |


##### ユーザーデータに関する重要な注意事項:

1. **条件付き要件**: 条件付き識別子フィールド (em、ph、sc_click_id、client_ip_address、client_user_agent、またはmadid) のうち、少なくとも1つを含める必要があります。
2. **自動処理**: コネクタは以下を自動的に処理します:
  - フィールドの正規化 (小文字への変換、スペースの削除など)
  - 機密フィールドのハッシュ化
  - 必要に応じたUTF-8エンコード
3. **複数の値**: String/Arrayとマークされたフィールドは、単一の値または複数の値を受け入れることができます


#### Custom Dataオブジェクトの標準フィールド

##### Eコマース関連フィールド

| フィールド | 説明 | 必須 | データ型 | 追加仕様 |
|  --- | --- | --- | --- | --- |
| content_category | アイテムまたはカテゴリの分類 | いいえ | String/Array | - 単一の値または配列が可能 例: `"shoes"` または `["coats", "shoes", "umbrellas"]` |
| content_ids | 商品/カテゴリ識別子 | いいえ | Array | - 単一のIDまたはカンマ区切りのリストが可能 例: `"sku001"` または `["sku001", "sku002", "sku003"]` |
| content_name | ページ/商品名 | いいえ | String | 例: `"Running Shoes"` |
| content_type | コンテンツ識別子のタイプ | いいえ | String | - 受け入れられる値: `product`、`product_group` |
| contents | 詳細なアイテム購入情報 | いいえ | Array of Objects | - 各オブジェクトには以下が含まれる可能性があります: • id (string) • quantity (integer) • item_price (float) • delivery_category (string) 例: `[{"id": "123", "quantity": 2, "item_price": 29.99, "delivery_category": "standard"}]` |
| currency | 取引通貨 | PURCHASE時は必須 | String | - 標準のISO 4217コードである必要があります (例: USD、AED、AUD) |
| num_items | 合計アイテム数 | いいえ | String | 例: `"3"` |
| order_id | 注文識別子 | いいえ | String | 例: `"ORD12345"` |
| predicted_ltv | 予測ライフタイムバリュー | いいえ | Float | 例: `150.75` |
| value | イベントの金額的価値 | PURCHASE時は必須 | Float | 例: `99.99` |
| search_string | 検索クエリテキスト | いいえ | String | 例: `"running shoes"` |


##### 旅行関連フィールド

| フィールド | 説明 | 必須 | データ型 | 例 |
|  --- | --- | --- | --- | --- |
| checkin_date | ホテルチェックイン日 | いいえ | String | 形式: YYYY-MM-DD 例: `"2024-09-13"` |
| travel_start | 旅行開始日 | いいえ | String | 例: `"2024-09-13"` |
| travel_end | 旅行終了日 | いいえ | String | 例: `"2024-09-20"` |
| suggested_destinations | おすすめの目的地 | いいえ | String/Array | 例: `["destination1", "destination2"]` |
| destination_airport | 目的地のIATAコード | いいえ | String | 例: `"JFK"` |
| origin_airport | 出発地のIATAコード | いいえ | String | 例: `"LAX"` |


##### 場所関連フィールド

| フィールド | 説明 | 必須 | データ型 | 例 |
|  --- | --- | --- | --- | --- |
| country | 目的地の国 | いいえ | String | 例: `"US"` |
| city | 目的地の都市 | いいえ | String | 例: `"New York"` |
| region | 州/地区/地域 | いいえ | String | 例: `"NY"` |
| neighborhood | 特定の地域 | いいえ | String | 例: `"Brooklyn"` |
| postal_code | 郵便番号 | いいえ | String | 例: `"10001"` |


##### 旅行スケジュールフィールド

| フィールド | 説明 | 必須 | データ型 | 例 |
|  --- | --- | --- | --- | --- |
| departing_departure_date | 往路出発 | いいえ | String | 例: `"2024-09-13T08:00"` |
| departing_arrival_date | 往路到着 | いいえ | String | 例: `"2024-09-13T12:00"` |
| returning_departure_date | 復路出発 | いいえ | String | 例: `"2024-09-20T08:00"` |
| returning_arrival_date | 復路到着 | いいえ | String | 例: `"2024-09-20T12:00"` |


##### 宿泊関連フィールド

| フィールド | 説明 | 必須 | データ型 | 例 |
|  --- | --- | --- | --- | --- |
| num_adults | 大人の人数 | いいえ | Integer | 例: `2` |
| num_children | 子供の人数 | いいえ | Integer | 例: `1` |
| num_infants | 幼児の人数 | いいえ | Integer | 例: `0` |
| hotel_score | ホテル評価スコア | いいえ | String | 例: `"4.5"` |
| preferred_neighborhoods | 希望エリア | いいえ | String/Array | 例: `["neighbor1", "neighbor2"]` |
| preferred_star_ratings | ホテルの星評価範囲 | いいえ | String/Array | 例: `["star1", "star2"]` |
| suggested_hotels | おすすめのホテル | いいえ | String/Array | 例: `["hotel1", "hotel2"]` |
| destination_ids | カタログの目的地ID | いいえ | String/Array | 例: `["dest1", "dest2"]` |


#### App Dataオブジェクトの標準フィールド

| フィールド | 説明 | 必須 | データ型 | 追加仕様 |
|  --- | --- | --- | --- | --- |
| advertiser_tracking_enabled | ユーザートラッキングのオプトインステータス | はい | Boolean | - `1` でOPT_IN - `0` でOPT_OUT - iOS 14.5+の場合: ATT Authorization Statusに設定 |
| app_id | アプリケーション識別子 | はい | String | - iOS: 数値形式 (例: `447188370`) - Android: パッケージ名形式 (例: `com.snapchat.android`) |
| extinfo | デバイスとアプリの情報 | はい | Array | 特定の順序で正確に16個の要素を含める必要があります (以下の詳細仕様を参照) |


##### extinfo配列の仕様

`extinfo`配列は、以下の順序で正確に16個の要素を含む必要があります。コネクタが正確な配列を構築できるように、「列名」で指定された正確な列名を使用してください:

| インデックス | カラム名 | 説明 | データ型 | 要件 | 例 |
|  --- | --- | --- | --- | --- | --- |
| 0 | device_os | OS識別子 | String | "i2"(iOS)または"a2"(Android)である必要があります | `"i2"` |
| 1 | package_name | アプリパッケージ名 | String |  | `"com.snapchat.sdk"` |
| 2 | short_version | アプリショートバージョン | String/Integer |  | `"1.0"` |
| 3 | long_version | アプリロングバージョン | String |  | `"1.0"` |
| 4 | os_version | デバイスOSバージョン | String |  | `"10.3.1"` |
| 5 | device_model | デバイスモデル | String |  | `"iphone14"` |
| 6 | locale | デバイスロケール | String |  | `"En_US"` |
| 7 | timezone_abbr | タイムゾーン略称 | String |  | `"EDT"` |
| 8 | carrier | モバイルキャリア | String |  | `"AT&T"` |
| 9 | screen_width | 画面幅 | Integer | Int64である必要があります | `320` |
| 10 | screen_height | 画面高さ | Integer | Int64である必要があります | `568` |
| 11 | screen_density | 画面密度 | String |  | `"2"` |
| 12 | cpu_cores | CPUコア数 | Integer | Int64である必要があります | `2` |
| 13 | storage_size | 総ストレージ容量(GB) | Integer | Int64である必要があります | `15` |
| 14 | free_storage_size | 利用可能なストレージ容量(GB) | Integer | Int64である必要があります | `8` |
| 15 | timezone_location | デバイスタイムゾーン | String |  | `"USA/New York"` |


完全な`extinfo`配列の例:


```
["i2", "com.snapchat.sdk", "1.0", "1.0", "10.3.1", "iphone14", "En_US", "EDT", "AT&T", "320", "568", "2", "2", "15", "8", "USA/New York"]
```

##### アプリイベントの重要な注意事項:

1. アプリイベントでは、3つのフィールド(`advertiser_tracking_enabled`、`app_id`、`extinfo`)すべてが必須です
2. `extinfo`配列は上記で指定された正確な順序を維持する必要があります
3. `extinfo`内の整数値はInt64型として提供する必要があります
4. `extinfo`の最初の要素がプラットフォーム(iOS/Android)を決定します


### (オプション) 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) を参照してください。

## (オプション) CLIを使用したエクスポートインテグレーション

CLI(Toolbelt)を使用してSnapchat Conversion CAPIに結果をエクスポートすることもできます。

*`td query`*コマンドの`*--result`オプション*を使用して、Snapchatサーバーへのエクスポートに必要な情報を指定する必要があります。*`td query`*コマンドの詳細については、[こちらの記事](https://docs.treasuredata.com/display/PD/TD+Toolbelt+Job+and+Query+Command+Reference)を参照してください。

オプションの形式はJSONで、一般的な構造は次のとおりです。


```json
{
  "type": "snapchat_conversion",
  "auth_method": "oauth",
  "oauth_credentials_id": "xxxxxxxxxxx",
  "event_source_type": "web",
  "event_source_id": "xxxxxxxxxxx",
  "send_test_events": false,
  "skip_invalid_records": true
}
```


```json
{
  "type": "snapchat_conversion",
  "auth_method": "api_token",
  "api_token": "xxxxxxxxxxx",
  "event_source_type": "web",
  "event_source_id": "xxxxxxxxxxx",
  "send_test_events": false,
  "skip_invalid_records": true
}
```

### パラメータ

| 名前 | 説明 | 値 | デフォルト値 | 必須 |
|  --- | --- | --- | --- | --- |
| type | コネクタタイプ | snapchat_conversion | N/A | はい |
| auth_method | 認証方式 | サポートされる値:   - oauth - api_token | oauth | はい |
| api_token | Conversion Api Token | N/A | N/A | はい(認証方式がConversion Api Tokenの場合) |
| oauth_credentials_id | コンソールでOAuth認証方式によって作成された資格情報ID | N/A | N/A | はい(認証方式がoAuthの場合) |
| event_source_type | イベントソースタイプ | サポートされるイベントソース:   - WEB - MOBILE_APP - OFFLINE | WEB | はい |
| event_source_id | SnapchatダッシュボードのピクセルIDまたはアプリケーションID | N/A | N/A | はい |
| send_test_events | Validation APIにデータを送信 | true/false | false | いいえ |
| skip_invalid_records | 無効なレコードを処理する際にジョブを続行または停止するフラグ | true/false | true | いいえ |


### 使用例

OAuth認証


```bash
$ td query --result '{"type":"snapchat_conversion","auth_method":"oauth","oauth_credentials_id":"xxx","event_source_type":"WEB","event_source_id":"xxx", "send_test_events":false,"skip_invalid_records":true}' -d sample_datasets "select ........ from ........" -T presto
```

APIトークン認証


```bash
$ td query --result '{"type":"snapchat_conversion","auth_method":"api_token","api_token":"xxx","event_source_type":"WEB","event_source_id":"xxx", "send_test_events":false,"skip_invalid_records":true}' -d sample_datasets "select ........ from ........" -T presto
```

## 関連記事

#### その他の設定

- 結果エクスポートは、対象の宛先に定期的にデータをアップロードするように[スケジュール](https://docs.treasuredata.com/articles/pd/scheduling-jobs-using-td-console)できます。
- すべてのインポートおよびエクスポートインテグレーションは、[TD Workflow](https://docs.treasuredata.com/articles/pd/about-treasure-workflow)に追加できます。**td**データオペレーターは、クエリ結果を指定されたインテグレーションにエクスポートできます。詳細については、[Treasure Dataオペレーターのリファレンス](https://docs.treasuredata.com/articles/pd/reference-for-treasure-data-operators/a/h1_76525622)を参照してください。