# LinkedIn Conversions API エクスポート連携

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

## 概要

LinkedIn Conversions API (CAPI) コネクターは、B2Bマーケティングキャンペーンのコンバージョンイベントのサーバーサイドトラッキングと測定を可能にします。LinkedInのEvents Managerと直接連携することで、このコネクターは企業がキャンペーンのパフォーマンスを測定し、9億人以上のグローバルプロフェッショナルのネットワーク全体で広告配信をより効果的に最適化するのに役立ちます。

## 主な機能:

- **ウェブイベント**: ピクセルデータを補完するサーバーサイドトラッキングにより、フォーム送信、コンテンツダウンロード、デモリクエストなどのB2Bリードジェネレーション測定を強化
- **リードジェネレーションイベント**: 複雑なB2B販売サイクルにおける適格リードと下流のコンバージョンイベントを追跡するための直接連携
- **プロフェッショナルターゲティングデータ**: 職種、企業名、業界セグメントなどのプロフェッショナル識別子と属性の追跡をサポート
- **データ検証**: LinkedIn CAPI仕様への自動イベント検証とフォーマット化により、プロフェッショナルコンバージョンイベントの正確な追跡を保証


このサーバーサイド連携は、クライアントサイドソリューション単独と比較して、より信頼性の高いコンバージョントラッキングと改善されたB2Bキャンペーンパフォーマンス測定を提供します。これは、プロフェッショナルオーディエンスをターゲットとし、より長い販売サイクルを測定する企業にとって特に価値があります。

## 前提条件

- TD Toolbeltを含むTreasure Dataの基本知識
- LinkedIn Adsの基本知識


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

- イベント時刻の制限: 90日以上前のイベント(`event_time`に基づく)は、処理中にスキップされます
- イベント時刻の検証は、エポック変換にUTCタイムゾーンを使用します


## 新しい接続の作成

クエリを実行する前に、TD Console上でデータ接続を作成して設定する必要があります。データ接続の一部として、連携にアクセスするための認証を提供します。以下の手順を実行してください。

![](/assets/linkedin1.5ff47b4294087e568df2efc1f6e8cb6e9b19d555d07ecfaa29b26bfb52ceab0d.fe495661.png)

1. TD Consoleを開きます。
2. **Integrations Hub > Catalog**に移動します。
3. **LinkedIn Ads Conversions API**を検索して選択します。アイコンにカーソルを合わせて**Create Authentication**を選択します。
4. **Credentials**タブが選択されていることを確認し、**Click here**を選択してOAuth認証フローを開始します。認証が完了すると、新しいOAuth接続が作成され、ドロップダウンで利用可能になります。
![](/assets/linkedin2.01f4c883ba1d7eb50b9e239b600c461895beb49e3df580be5f8162a74cfc08c7.0efdb04c.png)
5. **Continue**を選択して新しい接続を作成します。


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

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

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


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

![](/assets/linkedin3.97f5303ec693abd59354a83683686bbd5494f4abfa7def9d90d59daaa5a5f32a.b90d17e3.png)

| フィールド | 説明 |
|  --- | --- |
| Ad Account ID | コンバージョンデータがアップロードされるLinkedIn Adsアカウント識別子。有効なLinkedIn Ad Account IDを含む必要がある必須フィールドです。 |
| Conversion Rule | LinkedIn Ad Accountから既存のコンバージョンルールを指定するための入力フィールド。このフィールドは、「Use Conversion Rule ID」または「Create New Conversion Rule」オプションのいずれも選択されていない場合にのみ使用できます。 |
| Use Conversion Rule ID | 有効にすると、コンバージョンルールIDを直接入力できます。詳細については、以下の「コンバージョンルールIDを使用した設定」セクションを参照してください。 |
| Create New Conversion Rule | 有効にすると、カスタム設定で新しいコンバージョンルールを作成できます。詳細については、以下の「新しいコンバージョンルールを使用した設定」セクションを参照してください。 |
| Skip Invalid Records | チェックすると、コネクターはジョブ全体を失敗させる代わりに、検証に失敗したレコードをスキップします。このオプションはすべての設定モードで利用可能です。 |


### コンバージョンルールIDを使用した設定

![](/assets/screenshot2.84d97b18b64bb6ad7338685d18625c6b754dd901d2649087c311e1c365d452fa.b90d17e3.png)

| フィールド | 説明 |
|  --- | --- |
| Ad Account ID | コンバージョンルールが存在するLinkedIn Adsアカウント識別子。 |
| Conversion Rule ID | コンバージョンデータがアップロードされる既存のコンバージョンルールの特定の識別子。このフィールドは、「Use Conversion Rule ID」が有効になっている場合に表示されます。 |
| Skip Invalid Records | チェックすると、コネクターはジョブ全体を失敗させる代わりに、検証に失敗したレコードをスキップします。 |


Ad Account IDとConversion Ruleは、選択した認証に基づいて自動的に入力されます。入力されない場合は、認証が正しいかどうかを確認してください。

### 新しいコンバージョンルールを使用した設定

![](/assets/screenshot3.2ff015b2b2a7adc0c57ccc93ab522f4c0c5035d755d8b3269c8670da8fe518ea.b90d17e3.png)

| フィールド | 説明 |
|  --- | --- |
| Ad Account ID | 新しいコンバージョンルールが作成されるLinkedIn Adsアカウント識別子。 |
| Conversion Rule Name | 作成される新しいコンバージョンルールの一意の名前。このフィールドは、「Create New Conversion Rule」が有効になっている場合に表示されます。 |
| Conversion Type | 追跡するコンバージョンイベントのタイプ(例: 例のADD_TO_CART)。このルールが追跡するユーザーアクションの種類を定義します。 |
| Post Click Attribution Window (Days) | ユーザーが広告をクリックした後、そのコンバージョンが広告に帰属する日数(デフォルト値: 30日)。 |
| View Through Attribution Window (Days) | ユーザーが広告を閲覧した後、そのコンバージョンが広告に帰属する日数(デフォルト値: 7日)。 |
| Attribution Type | キャンペーンへのコンバージョンの帰属方法を決定します(デフォルト値: LAST_TOUCH_BY_CAMPAIGN)。 |
| Campaign Auto Association | このコンバージョンルールが関連付けられるキャンペーンを定義します(デフォルト値: ALL_CAMPAIGNS) |
| Skip Invalid Records | チェックすると、コネクタはジョブ全体を失敗させる代わりに、検証に失敗したレコードをスキップします |


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

LinkedInにイベントデータをアップロードするには、LinkedInのCAPIガイドラインに準拠したデフォルトフィールドとカスタムフィールドの組み合わせを含むデータエクスポートクエリを構築する必要があります。デフォルトフィールドの場合、カラム名が「Field/Column-Level Specifications」セクションにリストされているものと一致していることを確認してください。コネクタは自動的にカラム名を正規化してLinkedInの必須フォーマットに合わせるため、大文字小文字の区別を気にする必要はありません。

例えば、デフォルトフィールド「conversionHappenedAt」の場合、エクスポートクエリのカラム名は「CONVERSIONHAPPENEDAT」、「conversionhappenedat」、「ConversionHappenedAt」など、任意の大文字小文字で記述できます。コネクタはカラム名を「conversionHappenedAt」に標準化してLinkedIn CAPIの要件に合わせます。

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

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


### Export Query Specifications

| 仕様 | 説明 |
|  --- | --- |
| **Required Identifier** | 次の識別子のうち少なくとも1つが存在する必要があります: `SHA256_EMAIL`、`LINKEDIN_FIRST_PARTY_ADS_TRACKING_UUID`、`ACXIOM_ID`、`ORACLE_MOAT_ID`、または(firstNameとlastNameの組み合わせ)または(externalIds) |
| **Null Value Columns** | NULL値を持つカラムはエクスポート時に無視されます |
| **Duplicated Columns** | エクスポートクエリ内で重複するカラム名は許可されません |
| **Date-Time Handling** | `conversionHappenedAt timestamp field`の場合: - Integer型: ミリ秒単位のEpochタイムスタンプの場合はそのまま使用されます - ISO 8601文字列: ミリ秒単位のEpochタイムスタンプに変換されます - Timestampキャスト: ミリ秒単位のEpochタイムスタンプに変換されます - その他の形式: データ例外をスローします |
| **Time Range Limit** | コンバージョンイベントは過去90日以内である必要があります |


### Field or Column-Level Specifications

#### Standard Event Parameters

| フィールド | 説明 | 必須 | データ型 | 追加仕様 | 例 |
|  --- | --- | --- | --- | --- | --- |
| conversion | コンバージョンルールのURN | Yes | String | - コネクタは次のパターンに従ってコンバージョンルールのフォーマットを処理します:`urn:lla:llaPartnerConversion:id` - Conversion RulesはConfiguration UIとQuery Resultの両方で指定できます。値選択の優先順位: 1. Query resultのカラム値(存在する場合) 2. Configuration UIの値(query resultがnullの場合) 3. 両方がnull/存在しない場合はエラー | Query result値: `123` Config UI値: `456`  *クエリに値がある場合:* `urn:lla:llaPartnerConversion:123`を使用 *クエリがnullの場合:* `urn:lla:llaPartnerConversion:456`を使用 *両方nullの場合*: エラーをスロー |
| conversionHappenedAt | コンバージョンイベントのタイムスタンプ | Yes | Integer | - ミリ秒単位である必要があります - 過去90日以内である必要があります | `1590739275000` |
| eventId | 重複排除のための一意の識別子 | No | String | 重複排除に使用されます | `abc12345` |


#### User Identification Parameters

| フィールド | 説明 | 必須 | データ型 | 正規化仕様 | ハッシュ化仕様 | 例 |
|  --- | --- | --- | --- | --- | --- | --- |
| SHA256_EMAIL | ハッシュ化されたメールアドレス | 条件付き* | String | コネクタは次の正規化を処理します - 小文字に変換 - 空白を削除 | コネクタはハッシュ化されていない場合、SHA-256ハッシュ化を処理します | 入力: `User@Example.com` 正規化: `user@example.com` ハッシュ化: `bad8677b6...` |
| LINKEDIN_FIRST_PARTY_ADS_TRACKING_UUID | LinkedInのcookieクリックID | 条件付き* | String | なし | なし | `df5gf5-gh6t7-ph4j7h-fgf6n1` |
| ACXIOM_ID | LiveRamp identity ID | 条件付き* | String | なし | なし | N/A |
| ORACLE_MOAT_ID | Oracle MOAT Identity | 条件付き* | String | なし | なし | N/A |


少なくとも1つの識別子が存在するか、firstName + lastNameの組み合わせが提供されるか、externalIdsが提供される必要があります。

### User Information Parameters

| フィールド | 説明 | 必須 | データ型 | 追加仕様 | 例 |
|  --- | --- | --- | --- | --- | --- |
| firstName | 連絡先の名 | 条件付き* | String | 空にすることはできません | `Mike` |
| lastName | 連絡先の姓 | 条件付き* | String | 空にすることはできません | `Smith` |
| companyName | 連絡先の会社 | No | String | オプション | `Microsoft` |
| title | 連絡先の役職 | No | String | オプション | `Software Engineer` |
| countryCode | ISO国コード | No | String | 有効なISOコードである必要があります | `US` |
| lead | Lead Gen Form Response ID | No | String | 形式: `urn:li:leadGenFormResponse:id` | `urn:li:leadGenFormResponse:123` |
| externalIds | 広告主の識別子 | 条件付き* | Array of strings | 最大1項目 | `["user_id_123"]` |


### Conversion Value Parameters

| フィールド | 説明 | 必須 | データ型 | 追加仕様 | 例 |
|  --- | --- | --- | --- | --- | --- |
| currencyCode | 通貨コード | Yes* | String | 有効なISO 4217コードである必要があります | `"USD"` |
| amount | 金額 | Yes* | String | - 文字列としての10進数である必要があります - 小数点以下最大2桁 - 桁区切り記号なし | `"50.00"` |


[currencyCodeとamount]のうち少なくとも1つがクエリ結果に含まれている場合にのみ必須です。

### Special Field Handling

#### Handling Date-Time

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

**Handling Date-Time Custom Field Columnsの例**

**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型としてキャストします:



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

**2. ISO-8601日時文字列を使用する**

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



```sql
ALTER TABLE source_data_table ADD COLUMN date_time_field VARCHAR;
```

- そのカラムに日時値の文字列を挿入します。"T"区切り文字と末尾の"Z"を含むISO-8601形式でフォーマットされていることを確認してください:



```sql
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');
```

- クエリで直接カラムを使用します:



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

## 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)を使用してLinkedIn Conversion CAPIに結果をエクスポートすることもできます。

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

オプションのフォーマットはJSONで、一般的な構造は以下の通りです。


```yaml
out:
  type: linkedin_ads_conversion_api
  client_id: your client id
  client_secret: your client secret
  refresh_token: your refresh token
  ad_account_id: your ad account id
  conversion_rule_id: your conversion rule id
  use_conversion_rule_id: true
  skip_invalid_records: true
```

### パラメータ

| 名前 | 説明 | 値 | デフォルト値 | 必須 |
|  --- | --- | --- | --- | --- |
| type | コネクタタイプ | linkedin_ads_conversion_api | N/A | はい |
| client_id | アプリのクライアントID | アプリのクライアントID | N/A | はい |
| client_secret | アプリのクライアントシークレット | アプリのクライアントシークレット | N/A | はい |
| refresh_token | OAuth 2.0を使用したリフレッシュトークン | OAuth 2.0を使用したリフレッシュトークン | N/A | はい |
| ad_account_id | AD Account ID | 自分のad account id | N/A | はい |
| conversion_rule | Conversion Rule名 | 自分のconversion rule名 | N/A | 既存のconversion ruleを使用しない場合、または新しいconversion ruleを作成する場合は必須 |
| use_conversion_rule_jd | Conversion Rule IDを使用するフラグ | true/false  conversion rule名の代わりにconversion rule idを使用するかどうか | false | いいえ |
| conversion_rule_id | Conversion Rule ID | 自分のconversion rule id | N/A | いいえ |
| create_new_conversion_rule | 新しいConversion Ruleを作成 | 新しいConversion Ruleを作成 | false | いいえ |
| conversion_rule_name | Conversion Rule名。新しいconversion ruleを作成するために使用されます | Conversion Rule名。新しいconversion ruleを作成するために使用されます | N/A | 新しいconversion ruleを作成する場合は必須 |
| conversion_type | Conversion Type。新しいconversion ruleを作成するために使用されます | Conversion Type。新しいconversion ruleを作成するために使用されます | add_to_cart | 新しいconversion ruleを作成する場合は必須 |
| post_click_attribution_window | Post Click Attribution Window。新しいconversion ruleを作成するために使用されます | Post Click Attribution Window。新しいconversion ruleを作成するために使用されます | 30 | 新しいconversion ruleを作成する場合は必須 |
| view_through_attribution_window | View Through Attribution Window。新しいconversion ruleを作成するために使用されます | View Through Attribution Window。新しいconversion ruleを作成するために使用されます | 7 | 新しいconversion ruleを作成する場合は必須 |
| attribution_type | Attribution Type。新しいconversion ruleを作成するために使用されます | Attribution Type。新しいconversion ruleを作成するために使用されます | last_touch_by_campaign | 新しいconversion ruleを作成する場合は必須 |
| campaign_auto_association | Campaign Auto Asociation。新しいconversion ruleを作成するために使用されます | Campaign Auto Asociation。新しいconversion ruleを作成するために使用されます | all_campaings | 新しいconversion ruleを作成する場合は必須 |
| skip_invalid_records | 無効なレコードを処理する際にジョブを続行するか停止するかのフラグ | true/false | true | いいえ |


### 使用例

OAuth認証


```bash
td query --result '{"type":"linkedin_ads_conversion_api","client_id":"client_id","client_secret":"client_secret","refresh_token":"refresh_token,"ad_account_id":"ad_account_id", "conversion_rule_id":conversion_rule_id,"use_conversion_rule_id":true,"skip_invalid_records":true}' -d sample_database "select conversion,conversionhappenedat,currencycode,amount,sha256_email,linkedin_first_party_ads_tracking_uuid,acxiom_id,oracle_moat_id,firstName,title,lastName,companyname,countrycode,externalids as externalIds,lead,eventid from conversion" -T presto
```

## 関連記事

#### その他の設定

- Result Exportは、定期的にターゲット宛先にデータをアップロードするために[スケジュール設定](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)を参照してください。
- APIドキュメント: [Microsoft Conversion API](https://learn.microsoft.com/en-us/linkedin/marketing/integrations/ads-reporting/conversions-api?view=li-lms-2024-10&tabs=http)
- Authorization Code Flow: [Microsoft Authorization Code Flow (3-legged OAuth)](https://learn.microsoft.com/en-us/linkedin/shared/authentication/authorization-code-flow?view=li-lms-2024-10&tabs=HTTPS1)