# Pinterest Conversion Export Integration

この機能はベータ版です。詳細については、カスタマーサクセス担当者にお問い合わせください。

Pinterestは、画像や動画を通じてアイデアを発見・共有するために設計された人気のソーシャルメディアプラットフォームで、一般的にPinと呼ばれます。様々なマーケティング目標のため、企業はPinterest Adsに料金を支払い、ユーザーが最も目にしやすい目立つ位置にプロモートされたPinを配置できます。

Pinterest Conversions APIを使用することで、この連携により広告主はコンバージョンイベントをPinterestに直接送信し、キャンペーンの最適化、ターゲティング、コンバージョンレポート作成を行い、コンバージョンの可視性を向上させることができます。この連携は以下のコンバージョンタイプをサポートしています:

- Web
- In-App
- Offline conversions


ユーザー属性はマッチング目的で一緒にエクスポートされ、エクスポートにはカスタム属性(製品属性など)も含まれます。

## 前提条件

- Treasure Dataの基本知識
- Pinterest Ads Managerの基本知識
- [Pinterestビジネスアカウント](https://help.pinterest.com/en/business/article/get-a-business-account)
- Pinterest Conversion API用のアクセストークン。[Generate an access token for Pinterest Conversion API](/ja/int/pinterest-conversion-export-integration#h2_1482152047)を参照してください。


## 制限事項

- Conversion APIには、広告アカウントあたり1分間に5000回の呼び出しというレート制限があります。[Pinterest API Rate Limits](https://developers.pinterest.com/docs/reference/rate-limits/)を参照してください。
- イベントの重複排除は、使用する場合、48時間のウィンドウ内でのみ有効です。
- この連携はPinterestへのテストイベントの送信をサポートしていますが、アップロードされるイベント数を制限しません。Treasure Dataでは、大量のテストイベントを送信しないことを推奨します。


## TD Consoleを使用した接続の作成

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

### 新しい接続の作成

1. **TD Console**を開きます。
2. **Integrations Hub > Catalog**に移動します。
3. **Pinterest Conversion**を検索します。
4. **Create Authentication**を選択します。
![](/assets/pinterestconversion.4d2a091fab6048edfe6169d1e9e64c0f25795f899aa42de2ee91e79b6c77f2f8.61c90b26.png)
5. Pinterest Conversion Ads Manager用のアクセストークンを入力します。
6. **Continue**を選択します。
7. Authenticationの名前を入力し、**Done**を選択します。


| **フィールド** | **説明** |
|  --- | --- |
| **Access token** | アクセストークンはPinterest Conversion Ads Managerで生成されます。[Generate an access token for Pinterest Conversion API](/ja/int/pinterest-conversion-export-integration#reference-generate-an-access-token-for-conversion-api)を参照してください。 |


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

TD Consoleは、データをエクスポートする複数の方法をサポートしています。以下は、Data Workbenchからデータをエクスポートする手順です。

1. **Data Workbench > Queries**に移動します。
2. **New Query**を選択し、クエリを定義します。
3. **Export Results**を選択します。
4. 既存のPinterest Conversion認証を選択するか、新しく作成します([Create a New Connection](/ja/int/pinterest-conversion-export-integration#h3__1933218993)を参照)。
5. エクスポートパラメータを設定し、**Done**を選択します。


- Export Resultsパラメータ


| **フィールド** | **説明** |
|  --- | --- |
| Ad Account ID | PinterestのWebサイトで、「Business avatar」を選択し、「Ad accounts」を選択すると、利用可能な広告アカウントのリストが表示されます。アカウントIDはURLからも確認できます。例: `https://ads.pinterest.com/advertiser/549xxxxxx761/` |
| Test Event | (デフォルト: off) 有効にすると、クエリ結果はテストイベントとしてアップロードされ、ConversionsのTest eventsメニューで確認できます。Treasure Dataでは、少数のテストイベントの送信を推奨します。 |
| Skip invalid records | (デフォルト: on) チェックすると、必須データ要件とデータ形式を満たさないレコードはアップロードされません。チェックしない場合、連携は最初の無効なレコードに遭遇したときにエラーを発生させ、実行を停止します |


### コンバージョンイベントをアップロードするためのクエリの定義

- ハッシュ化—以下のHashing列でYesとマークされているフィールドは、小文字にしてSha256でハッシュ化する必要があります。平文で提供された場合、連携がハッシュ化します。
- 文字列の配列—Array of string型のフィールドは、フラット化された列名で複数の値を受け入れます。例えば、em、em_1、em_2は、ユーザーのメール文字列の配列を形成できます。
- アイテムオブジェクトの配列—Pinterestでは、ID、名前、数量、価格などの多くの属性を持つ複数の注文アイテムをアップロードできます。以下はアイテムオブジェクトの例です:
  - item_id, item_price,item_quantity
  - item_id_1, item_price_1, item_name_1
  - item_id_2, item_brand_2, item_category_2


| Name  | Type  | Value  | Required  | Hashing  |
|  --- | --- | --- | --- | --- |
| **Event data**  |  |  |  |  |
| event_name
 | String
 | イベントのタイプ
**Enum**: `add_to_cart`, `checkout`, `custom`, `lead`, `page_visit`, `search`, `signup`, `view_category`, `watch_video`
 | Yes
 |  |
| action_source
 | String
 | イベントが発生したソース
**Enum**: `app_android`, `app_ios`, `web`, `offline`
 | Yes
 |  |
| event_time | Int64 | イベントが発生した時刻。Unixタイムスタンプ(秒単位)です。 | Yes |  |
| event_id | String | APIとPinterestタグを介して取り込まれたイベント間の重複排除をサポートする一意のID文字列 | Yes |  |
| event_source_url | String | WebコンバージョンイベントのURL |  |  |
| opt_out | Boolean | 広告トラッキングに対するユーザーのオプトアウト。以下の場合にYESを送信:- `web`, `offline`: Webトラッキングをオプトアウトした場合
- `app_ios`: iOSでLimit Ad Trackingを有効にした場合
- `app_android`: AndroidでAds Personalizationをオプトアウトした場合

 |  |  |
| app_id | String | アプリストアのアプリID |  |  |
| app_name | String | アプリの名前 |  |  |
| app_version | String | アプリのバージョン |  |  |
| device_brand | String | ユーザーデバイスのブランド |  |
| device_carrier | String | ユーザーデバイスのモデル |  |
| device_type | String | ユーザーデバイスのタイプ |  |
| os_version | String | デバイスのオペレーティングシステムのバージョン |  |
| wifi | Boolean | イベントがWi-Fi使用中に発生したかどうか |  |
| language | String | ユーザーの言語（2文字の[ISO-639-1](https://www.loc.gov/standards/iso639-2/php/code_list.php)言語コード） |  |
| **User attributes - for matching purposes**  |  |
| em | Array of strings | マッチングに使用されるユーザーのメールアドレス | 以下のうち少なくとも1つが必要です：- em
- hashed_maids
- client_ip_address と client_user_agent のペア

 | Yes |
| hashed_maids | Array of strings | Google GAID または Apple IDFA |  | Yes |
| client_ip_address | String | ユーザーのIPアドレス（IPv4またはIPv6形式） |  |
| client_user_agent | String | ユーザーのWebブラウザのユーザーエージェント文字列 |  |
| ph | Array of strings | ユーザーの電話番号（国番号と市外局番を含む、数字のみ、先頭のゼロなし） |  | Yes |
| ge | Array of strings | ユーザーの性別（小文字）。`f`、`m`、または `n` のいずれか |  | Yes |
| db | Array of strings | ユーザーの生年月日（年、月、日） |  | Yes |
| ln | Array of strings | ユーザーの姓 |  | Yes |
| fn | Array of strings | ユーザーの名 |  | Yes |
| ct | Array of strings | ユーザーの都市（スペースや句読点なし） |  | Yes |
| st | Array of strings | ユーザーの州（2文字コード） |  | Yes |
| zp | Array of strings | ユーザーの郵便番号（数字のみ） |  | Yes |
| country | Array of strings | ユーザーの国（2文字の[ISO-3166コード](https://www.iso.org/obp/ui/#search)） |  | Yes |
| external_id | Array of strings | 広告主から提供される、広告主の領域でユーザーを識別する一意のID。例：ユーザーID、ロイヤルティIDなど |  | Yes |
| click_id | String | ドメインの _epik cookie またはURLの &epik= クエリパラメータに保存されている一意の識別子 |  |
| partner_id | String | サードパーティパートナーによって定義される訪問者の識別子 |  |
| **Custom data**  |  |
| currency | String | [ISO-4217](https://www.iso.org/iso-4217-currency-codes.html)通貨コード |  |  |  |
| value | String | イベントの合計金額。Treasure Dataでは税抜、送料抜きの金額を使用することを推奨しています |  |
| content_ids | Array of strings | 商品IDのリスト |  |
| content_name | String | イベントに関連するページまたは商品の名前 |  |
| content_category | String | イベントに関連するコンテンツのカテゴリ |  |
| content_brand | String | イベントに関連するコンテンツのブランド |  |
| item_id | String | 商品のID（`contents`オブジェクト配列のフィールド） |  |
| item_price | String | 商品の価格（`contents`オブジェクト配列のフィールド） |  |
| item_quantity | Int64 | 商品の数量（`contents`オブジェクト配列のフィールド） |  |
| item_name | String | 商品の名前（`contents`オブジェクト配列のフィールド） |  |
| item_category | String | 商品のカテゴリ（`contents`オブジェクト配列のフィールド） |  |
| item_brand | String | 商品のブランド（`contents`オブジェクト配列のフィールド） |  |
| num_items | Int64 | イベントの商品の合計数 |  |
| order_id | String | 注文ID。必要に応じて重複排除に使用できます |  |
| search_string | String | ユーザーコンバージョンイベントに関連する検索文字列 |  |
| opt_out_type
 | String
 | 異なるプライバシー権法に基づいて個人情報の共有をオプトアウトするためのカンマ区切りのフラグ。
現在、米国の一部の州のCPRA法に準拠するための`LDP`のみが受け入れられる値です。（統合による検証は実行されません。）
 |  |


#### サンプルクエリ

**最低限必要なフィールド**


```sql
SELECT
  'add_to_cart' AS event_name
  ,'app_android' AS action_source
  ,now() AS event_time
  ,'801470028' AS event_id
  ,'some_one@mail.com' AS em
FROM
  your_table
```

**文字列の配列**


```
SELECT 'add_to_cart' AS event_name  ,'app_android' AS action_source  ,now() AS event_time  ,'59930360' AS event_id    ,'some_one@mail.com' AS em  ,'another_one@gmail.com' AS em_1    ,'or123' AS order_id  ,'cook' AS search_string    ,'item 1' AS item_id_1  ,'10.4' AS item_price_1  ,20 AS item_quantity_1    ,'basket' AS item_name_2  ,'cat ' AS item_category_2  ,'tiny' AS item_brand_2 FROM your_table
```

## Audience Studioでセグメントをアクティブ化

## 

Audience Studioでアクティベーションを作成することにより、セグメントデータをターゲットプラットフォームに送信することもできます。

1. **Audience Studio**に移動します。
2. 親セグメントを選択します。
3. ターゲットセグメントを開き、右クリックして**Create Activation**を選択します。
4. **Details**パネルで、アクティベーション名を入力し、前のセクションの設定パラメータに従ってアクティベーションを設定します。
5. **Output Mapping**パネルでアクティベーション出力をカスタマイズします。


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

- Attribute Columns
  - **Export All Columns**を選択すると、変更を加えずにすべての列をエクスポートします。
  - **+ Add Columns**を選択して、エクスポート用の特定の列を追加します。Output Column Nameには、ソース列名と同じ名前が事前入力されます。Output Column Nameを更新できます。**+ Add Columns**を選択し続けて、アクティベーション出力用の新しい列を追加します。
- String Builder
  - **+ Add string**を選択して、エクスポート用の文字列を作成します。次の値から選択します：
    - String: 任意の値を選択します。テキストを使用してカスタム値を作成します。
    - Timestamp: エクスポートの日時。
    - Segment Id: セグメントID番号。
    - Segment Name: セグメント名。
    - Audience Id: 親セグメント番号。


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


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

- スケジュールを定義する値を選択し、必要に応じてメール通知を含めます。


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


## (オプション) CLI を使用したエクスポート連携

[TD Toolbelt](https://toolbelt.treasuredata.com/) を使用すると、CLI からクエリ結果のエクスポートをトリガーできます。エクスポートジョブのパラメータは、td query コマンドの --result オプションで指定する必要があります。詳細については、[コマンドラインから Treasure Data へのクエリとデータのインポート](https://docs.treasuredata.com/articles/pd/querying-and-importing-data-to-treasure-data-from-the-command-line)を参照してください。

以下は、オプションの一般的な構造と JSON 形式の例です:


```
{    "type": "pinterest_conversion",    "access_token": "pina_AIA2RFAxxx",    "ad_account_id": 549764609761,    "test_event": false,    "skip_invalid_record": true}
```

**CLI パラメータ**

| Name | Description | Value | Default Value | Required |
|  --- | --- | --- | --- | --- |
| access_token | Pinterest Ad Manager から取得した Pinterest conversion のアクセストークン | String | No | Yes |
| ad_account_id | Pinterest Ads アカウント ID | Number | No | Yes |
| test_event | テストまたは実際のイベントを Pinterest に送信するためのフラグ | Boolean | false | No |
| skip_invalid_record | 無効なレコードが検出された場合にジョブを続行するためのフラグ | Boolean | false | No |


**実際のイベントとテストイベントの送信例**

1. テストコンバージョンイベントを送信



```bash
td --database test_db \
--wait "SELECT event_name, action_source, event_time, event_id, event_source_url, opt_out, partner_name, app_id, app_name, app_version, device_brand, device_carrier, device_type, os_version, wifi, language, em, hashed_maids, client_ip_address, client_user_agent, ph, ge, db, ln, fn, ct, st, zp, country, external_id, click_id, partner_id, currency, value, content_ids, content_name, content_category, content_brand, item_id, item_id_1, item_id_2, item_price, item_price_1, item_price_2, item_name, item_name_1, item_name_2, item_category, item_category_1, item_category_2, item_brand, item_brand_1, item_brand_2, item_quantity, item_quantity_1, item_quantity_2, num_items, order_id, search_string, opt_out_type from test_table" \
--type presto \
--result '{"type":"pinterest_conversion","td_authentication_id": 12345, "access_token":"pina_AIA2RFAWACYNMAQA...", "ad_account_id": 5497xxx, "test_event": true, "skip_invalid_record":true}'
```

1. 実際のイベントを送信



```bash
td --database test_db \
--wait "SELECT event_name, action_source, event_time, event_id, event_source_url, opt_out, partner_name, app_id, app_name, app_version, device_brand, device_carrier, device_type, os_version, wifi, language, em, hashed_maids, client_ip_address, client_user_agent, ph, ge, db, ln, fn, ct, st, zp, country, external_id, click_id, partner_id, currency, value, content_ids, content_name, content_category, content_brand, item_id, item_id_1, item_id_2, item_price, item_price_1, item_price_2, item_name, item_name_1, item_name_2, item_category, item_category_1, item_category_2, item_brand, item_brand_1, item_brand_2, item_quantity, item_quantity_1, item_quantity_2, num_items, order_id, search_string, opt_out_type from test_table" \
--type presto \
--result '{"type":"pinterest_conversion","td_authentication_id": 12345, "access_token":"pina_AIA2RFAWACYNMAQA...", "ad_account_id": 5497xxx, "test_event": false, "skip_invalid_record":true}'
```

### その他の設定

- 結果エクスポートは[スケジュール設定](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)を参照してください。


## (リファレンス) Conversion API のアクセストークンを生成する

このセクションでは、Conversion API のアクセストークンを生成する方法の概要を説明します。Pinterest は事前の通知なく詳細な手順を変更する場合がありますのでご注意ください。

1. Pinterest Ad Manager から、メインメニューに移動し、**Conversions** を選択します。![](/assets/pinterest-conversion-export-integration-2024-10-23-5.570b432df3bf9dcad97abdd5c634ce1b4f3fdc24ad6a670bd5e5a2ee6ed806f3.61c90b26.png)
2. Conversions ページで、**Set up API** を選択し、**Generate new token** を選択します。
有効期限のないアクセストークン ``` pina_xxxxxxx が生成されます


![](/assets/pinterest-conversion-export-integration-2024-10-23-6.c8971410681597174d5e338fa04ccb60ce8de39f80266f5ae34fe7101d775f7f.61c90b26.png)

## 関連項目

- [Pinterest Send Conversion API](https://developers.pinterest.com/docs/api/v5/events-create/)