> For the complete documentation index, see [llms.txt](https://help.citrusad.com/retail-media-interface/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.citrusad.com/retail-media-interface/integration/ja/brand-pages/brand-page-retailer-integration-guide/tracking-attribution.md).

# トラッキングとアトリビューション

## トラッキングURLの作成方法

レスポンスでは、組み合わせる3つのソースが提供されます:

* ページレベル `trackers.impression`: 例えば、ページインプレッションは次を使用します `type: "impression"` および `params` 以下を含む `ts` および `iabConsentString`.
* 共有 `trackingTemplates`: 1セットの `client`（相対）および `server` （絶対）URLテンプレート。すでにセッションとプレースメントのクエリパラメータが含まれています。
* ノード単位 `trackers.click` および/または `trackers.addToCart` モジュール、行、またはギャラリーアイテム上: `type`+ `params` その特定のイベント用（例えば、 `modId`, `rurl`, `productCode`).

### どのテンプレートか？

ノードの `tracking.type` を使用して以下を検索します `trackingTypes.<type>`。これにより、そのインタラクションに有効な `client.*` および `server.*` キーが定義されます（例えば、linkの場合: `client.clickRedirect`, `client.clickEvent`, `server.clickEvent)`.

### クライアント対サーバー

* クライアント（`trackingTemplates.client.*`）: 値は相対パス（クエリ文字列を含む）です。リバースプロキシのベースURL（`BASEURL`).
* サーバー（`trackingTemplates.server.`）: 値は Epsilon トラッキングホスト上の絶対URLテンプレートです。C2Sと同じ方法で最終URLを作成します: テンプレート + `"&"` + `queryString(trackers.<slot>params)`.

{% hint style="info" %}
テンプレートのホストやパスを変更しないでください。また、S2Sコールをリバースプロキシ経由で送信しないでください。
{% endhint %}

### 作業例（疑似コード）

#### HERO CTAのC2Sクリック

```
url = BASEURL + trackingTemplates.client.clickRedirect + "&" + queryString(trackers.click.params)
```

#### S2Sページインプレッション

```
url = trackingTemplates.server.impressionEvent + "&" + queryString(trackers.impression.params)
```

#### 商品行のS2Sカート追加

```
url = trackingTemplates.server.addToCartEvent + "&" + queryString(trackers.addToCart.params)
```

マクロ置換

* {TS} を現在のミリ秒タイムスタンプに、{RURL} を URL エンコードされた遷移先に置換し、 `{TCF}` 発火前に CMP からの現在の TCF v2 文字列に置換します。
* カート追加の場合は、{QTY} も発火時点でのカート内における該当 SKU の絶対数量（差分ではない）に置換し、{CONVERSION\_VALUE} をそれらのアイテムの絶対金銭価値（数量 × 単価、適用された割引を差し引いた額）に置換します。

{% hint style="info" %}

* のみが `trackingTemplates.client.impressionPixelUrls` 真のピクセル（1×1 GIF）です。
  * `clickRedirect` は 302 リダイレクトエンドポイントです。
  * `clickEvent` および `addToCartEvent` は 204 No Content を返すイベントビーコンです。
    {% endhint %}

{% hint style="danger" %}
同じ論理イベントに対して C2S と S2S の両方を発火させないでください（例えば、同じクリックに対して C2S クリックイベントと S2S クリック通知の両方を送信しないでください）。
{% endhint %}

## トラッキング – クライアントからサーバー（C2S）

C2S トラッキングは、構成された URL を使用してブラウザ内に実装されます。前に `BASEURL` を次のパスに追加します： `trackingTemplates.client` そして適切なものを末尾に追加します `trackers.<slot>params` （参照： [トラッキングURLの構成方法](#how-to-compose-a-tracking-url)）。

のみ `client.impressionPixelUrls` がピクセル（1×1 GIF）です。その他のクライアントテンプレートはピクセルではありません：

* `client.clickRedirect`：302 リダイレクトエンドポイント。 Epsilon はクリックを記録し、デコードされた rurl にブラウザをリダイレクトします。これをブラウザのナビゲーションターゲットとして使用します。
* `client.clickEvent`：**イベントビーコン**は 204 No Content を返します）。次を使用して発火させます： `navigator.sendBeacon` or `fetch({ keepalive: true })`。次のようにレンダリングしないでください： `<img>`.
* `client.addToCartEvent`：**イベントビーコン**（204 を返します）。と同じ発火パターンを使用します： `clickEvent`.

### 実装手順

1. API から返されたブランドページコンテンツをレンダリングします。
2. レンダリング後、ブラウザでインプレッションピクセルを発火させます（内のすべてのエントリ： `trackingTemplates.client.impressionPixelUrls`、1×1 画像として）。
3. ユーザーがトラッキング対象のノードをクリックした場合は、次のいずれかを行います：\
   (a) 構成された `client.clickRedirect` URL を経由してリダイレクトする、または\
   (b) 構成された `client.clickEvent` URL をイベントビーコンとして発火させ、自身で目的地に移動する。\
   クリックごとにいずれか一方のみを使用し、両方は使用しないでください。

### インプレッションピクセル

ブランドページがレンダリングされた後、各パスを発火させます： `trackingTemplates.client.impressionPixelUrls` 1×1 画像として (参照:[ トラッキング URL の構成方法](#how-to-compose-a-tracking-url)).

```html
<img src="https://www.retailer.com/epsilon/tracking/v3/impression/pixel/brandpage_djog...?...&ts=1737485823910"
     width="1" height="1" style="display:none" />
```

手順:

1. 内の各文字列について `trackingTemplates.client.impressionPixelUrls`の先頭に追加します: `BASEURL` (例: `https://www.retailer.com/epsilon`).
2. 末尾に追加します `&` + `queryString(trackers.impression.params)`を置換します `{TS}` 現在のミリ秒単位のタイムスタンプを使用し、 `{TCF}` CMP からの現在の同意文字列を使用します。
3. 1×1 として呼び出します `< img src="...">` ブラウザ内 (または同等の環境)。

### クリックトラッキング

#### オプション A: クリックリダイレクト (`client.clickRedirect`)

作成された URL を通じてユーザーを移動させます。 Epsilon クリックをログに記録し、デコードされた `rurl`に対して **HTTP 302** で応答します。このエンドポイントは **GET のみ** であり、 `rurl` は必須です;

#### オプション B: クリックイベントビーコン (`client.clickEvent`)

ビーコンとして呼び出し、自分で移動させます。GET または POST を受け付け、204 No Content を返します。画像ではないため、描画しないでください`<img>`.

### カート追加 (C2S)

ユーザーが商品をカートに追加したときに、 `trackingTemplates.client.addToCartEvent` を (ピクセルではなく) イベントビーコンとして呼び出します。GET または POST を受け付け、204 No Content を返します。

{% hint style="info" %}
同じカート操作に対して C2S と S2S のカート追加を組み合わせないでください。
{% endhint %}

## トラッキング – サーバー間 (S2S)

S2S トラッキングはバックエンドに実装されます。C2S と同じ方法で URL を作成します。適切な `trackingTemplates.server` 文字列から開始し、末尾に `trackers.<slot>params`を追加します。サーバーテンプレートはすでに絶対パスです — 追加する `BASEURL`はありません。(参照: [トラッキングURLの構成方法](#how-to-compose-a-tracking-url)).

{% hint style="info" %}
サーバーテンプレートからのホストやパスを変更しないでください。また、リバースプロキシ経由で S2S リクエストを送信しないでください。
{% endhint %}

### S2S トラッキングを使用するタイミング

* アーキテクチャでサーバー側のイベント呼び出しが必要です。
* クライアント側のピクセルが信頼できない環境でトラッキングが必要です。
* 戦略を組み合わせたい場合 - 例: C2S インプレッション + S2S カート追加。これはサポートされていますが、同じイベントに対して C2S と S2S の両方を呼び出さないでください。

### S2S インプレッション通知

ブランドページがレンダリングされた後、サーバーは作成されたインプレッション URL に対して **GET** または **POST** を発行します: `trackingTemplates.server.impressionEvent` + `trackers.impression.params` (送信前に `{TS}` および `{TCF}` を置換します)。

### S2S クリック通知

作成: `trackingTemplates.server.clickEvent` + `trackers.click.params` (送信前に `{TS}`、{RURL}、および `{TCF}`)、その後 GET または POST を発行します。

### S2S カート追加通知

作成: `trackingTemplates.server.addToCartEvent` + `trackers.addToCart.params` (送信前に `{TS}`、{QTY}、{CONVERSION\_VALUE}、および `{TCF}`)、その後 GET または POST を発行します。

### S2S パラメータ

| パラメータ                                                                               | ソース                         | メモ                                                                                 |
| ----------------------------------------------------------------------------------- | --------------------------- | ---------------------------------------------------------------------------------- |
| `catalogId`, `sessionId`, `customerId`, `dtmId`, `placementId`, `lsid`, `utcOffset` | `trackingTemplates` クエリ文字列  | リクエストを呼び出す際、これらの値はそのまま保持してください。削除や変更はしないでください。                                     |
| `modId`                                                                             | `trackers.<slot>.params`    | コンテンツモジュールまたは行識別子。                                                                 |
| `ts`                                                                                | `trackers.<slot>.params`    | 置換する `{TS}` リクエストを呼び出す前に、現在のミリ秒単位のタイムスタンプを使用します。                                   |
| `iabConsentString`                                                                  | `trackers.<slot>.params`    | 置換する `{TCF}` リクエストを呼び出す前に、CMP からの現在の TCF v2 同意文字列を使用します。値がすでに提供されている場合は、そのまま使用します。 |
| `rurl`                                                                              | `trackers.<slot>.params`    | URL エンコードされたリダイレクト先。存在するのに対し、 `{RURL}` を置換します。                                     |
| `productCode`, `sellerId`                                                           | `trackers.<slot>.params`    | 商品ノードから派生した値。                                                                      |
| `qty`                                                                               | `trackers.addToCart.params` | 置換する `{QTY}` リクエストが呼び出された時点でのカート内の SKU の絶対数量を使用します。数量の差分は使用しないでください。               |
| `conVal`                                                                            | `trackers.addToCart.params` | 置換する `{CONVERSION_VALUE}` 商品の合計金額 (数量 × 単価、適用される割引を差し引いた額) を使用します。                 |

## マクロリファレンス

| 記号                   | 説明                                                                                   | 含まれる場所                                    | 次で置換:                                                      |
| -------------------- | ------------------------------------------------------------------------------------ | ----------------------------------------- | ---------------------------------------------------------- |
| `BASEURL` (接頭辞)      | プロトコルとプロキシパスを含むサイトのベースURL - 各個別に先頭に追加してください `trackingTemplates.client.*` パス。         | C2Sトラッキング                                 | `https://www.retailer.com/epsilon`                         |
| `{TS}`               | キャッシュバスタータイムスタンプ（ミリ秒）                                                                | `trackers.<slot>.params`                  | `1737485823910`                                            |
| `{RURL}`             | URLエンコードされたリダイレクト先                                                                   | `trackers.<slot>.params.rurl`             | `https%3A%2F%2Fwww.retailer.com%2Fprodukt%2F9221200653341` |
| `{TCF}`              | IAB TCF v2同意文字列プレースホルダー。以下の場合に表示されます： `regs.consent` がリクエストで省略されました。                 | `trackers.<slot>.params.iabConsentString` | CMPからの現在のTC文字列、例：以下経由 `__tcfapi` `getTCData` → `tcString`  |
| `{QTY}`              | 発火時におけるカート内のこのSKUの絶対数量（デルタではありません。例：ショッパーが1つ持っていてもう1つ追加した場合は、以下を送信します： `2`).         | `trackers.addToCart.params.qty`           | `2`                                                        |
| `{CONVERSION_VALUE}` | それらのアイテムの絶対金銭的価値：数量 × 単価マイナス適用された割引。                                                 | `trackers.addToCart.params.conVal`        | `49.99`                                                    |
| `{RURL_KID}`         | リダイレクト署名キーID。以下に存在します： `trackers.click.redirectParams` プラットフォームのリダイレクト署名が有効になっている場合。 | `trackers.click.redirectParams.rurlKid`   | バッチ署名エンドポイントによって返される署名キーID                                 |
| `{RURL_SIG}`         | リダイレクト署名。以下に存在します： `trackers.click.redirectParams` プラットフォームのリダイレクト署名が有効になっている場合。     | `trackers.click.redirectParams.rurlSig`   | バッチ署名エンドポイントによって返されるEd25519署名（base64url）                   |

### URLエンコーディングリファレンス

エンコード時 `{RURL}`は、標準のパーセントエンコーディングを使用してください：

| 文字  | エンコード形式 |
| --- | ------- |
| `:` | `%3A`   |
| `/` | `%2F`   |
| `?` | `%3F`   |
| `=` | `%3D`   |
| `&` | `%26`   |

### redirectParamsとリダイレクト署名

プラットフォームのリダイレクト署名が有効になっている場合、 `trackers.click` には以下が含まれる場合があります： `redirectParams`オブジェクトと並行して `params`。内のキー `7`はのみにマージされます `client.clickRedirect` URL — にはマージされません `clickEvent`または任意のサーバーURL。

2つのケース：

**埋め込みリンク先**（URLが組み込まれています： `params.rurl`）：プラットフォームは配信時にリダイレクトに署名し、リテラルを出力します `rurlKid`および `rurlSig`内の値 `redirectParams`。これらをそのままに追加してください `clickRedirect` URL。

**リテールメディア管理のリダイレクト**（`params.rurl` が {RURL} の場合）： `redirectParams` にはマクロ {RURL\_KID} と {RURL\_SIG} が含まれています。バッチ署名エンドポイント（`redirectSigning.url` レスポンスから）を呼び出して、宛先URLのキーIDと署名を取得し、追加する前に置換します。

最上位の `redirectSigning`オブジェクトが存在する場合、バッチを提供します `POST /ads/v3/redirect/sign` エンドポイントURLと `maxUrls`バッチ制限。お問い合わせ先： Epsilon に連絡して、統合でリダイレクト署名が有効になっているかどうかを確認してください。

### redirectParamsを使用したclickRedirectの構成：

```
BASEURL + trackingTemplates.client.clickRedirect + "&" + queryString(trackers.click.params) + "&" + queryString(trackers.click.redirectParams)
```

<br>

## スタイルガイド

サイトでブランドページを有効にする前に、サイトのビジュアルアイデンティティをキャプチャする必要があります。以下の表にデザイン値を入力してください。私たちのチームはこれを使用して、ブランドページのプレビューエクスペリエンスを設定します。

#### ロゴ

| フィールド | 説明                    | あなたの値 |
| ----- | --------------------- | ----- |
| ロゴURL | サイトロゴへのURL（SVGまたはPNG） |       |

#### カラー

| フィールド          | 説明                             | あなたの値 |
| -------------- | ------------------------------ | ----- |
| プライマリカラー       | メインブランドカラー（16進数）               |       |
| 背景色            | ページの背景色（16進数）                  |       |
| サーフェスカラー       | カード/セクションの背景色（16進数）            |       |
| プライマリテキストカラー   | メインテキストカラー（16進数）               |       |
| セカンダリテキストカラー   | 控えめなテキストカラー（16進数）              |       |
| プライマリカラー上のテキスト | プライマリカラーの背景に使用されるテキストカラー（16進数） |       |
| ボーダーカラー        | デフォルトのボーダーカラー（16進数）            |       |

#### タイポグラフィ

| フィールド         | 説明                                          | あなたの値 |
| ------------- | ------------------------------------------- | ----- |
| ヘッダーフォントファミリー | ヘッダーに使用されるフォント（例：「Google Sans, sans-serif」） |       |
| 本文フォントファミリー   | 本文テキストに使用されるフォント（例：「Roboto, sans-serif」）    |       |
| 基本フォントサイズ     | デフォルトの本文フォントサイズ（例：16px）                     |       |

#### ボタン

| フィールド       | 説明                               | あなたの値 |
| ----------- | -------------------------------- | ----- |
| 主要ボタンの背景    | 主要ボタンの背景色                        |       |
| 主要ボタンのテキスト色 | 主要ボタンのテキスト色                      |       |
| 主要ボタンの角丸    | 角の丸み（例：8px）                      |       |
| 副次ボタンのスタイル  | 副次ボタンの外観（アウトライン、ゴーストなど）を説明してください |       |

## モジュールコンテンツ要件

ブランドページはコンテンツモジュールで構成されます。各モジュールタイプについて、サイトが要求するコンテンツ制約を提供してください。弊社のチームがこれらを使用してテンプレート検証ルールを設定します。

### IMAGE モジュール

| 要件             | 説明                                      | あなたの値 |
| -------------- | --------------------------------------- | ----- |
| 最小幅            | ピクセル単位の最小画像幅（例：1920）                    |       |
| 最小高さ           | ピクセル単位の最小画像高さ（例：500）                    |       |
| 最大ファイルサイズ      | MB 単位の最大ファイルサイズ（例：10）。4MB 未満である必要があります。 |       |
| 受け入れ可能な形式      | 受け入れ可能な画像形式（例：jpg、png、gif、svg）          |       |
| キャプションの最大文字数   | 画像キャプションの最大文字数（該当する場合）                  |       |
| `alt`タグのオプション性 | 画像で `alt` が必須かどうか。                      |       |

### TEXT モジュール

| 要件             | 説明                                                                                                                                                            | あなたの値 |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- |
| バリアント          | 「headline」、「tagline」、「body」、または「lines」。テキストが表示されるスタイルを決定します。                                                                                                  |       |
| 配置             | 「left」、「center」、または「right」。テキストの水平方向の配置を決定します。                                                                                                                |       |
| 「Lines」設定      | <p>複数行テキスト設定（variant = lines の場合）の設定。各テキスト行について、以下を提供してください。<br><br>- テキストフィールドの名前<br>- 「required」または「allowed」か？<br>- これが別の URL へのハイパーリンクであることを意図しているかどうか</p> |       |
| 見出しの最大文字数      | 見出しテキストの最大文字数                                                                                                                                                 |       |
| 説明の最大文字数       | 説明テキストの最大文字数                                                                                                                                                  |       |
| 本文/フッターの最大文字数  | 本文またはフッターテキストの最大文字数                                                                                                                                           |       |
| CTA ボタン        | 必須、オプション、または不要か？                                                                                                                                              |       |
| CTA テキストの最大文字数 | CTA ボタンラベルの最大文字数                                                                                                                                              |       |

### PRODUCT\_GRID モジュール

| 要件              | 説明               | あなたの値 |
| --------------- | ---------------- | ----- |
| 最小商品数           | 表示する最小商品数（例：4）   |       |
| 最大商品数           | 表示する最大商品数（例：12）  |       |
| セクションタイトル       | 必須かオプションか？       |       |
| セクションタイトルの最大文字数 | セクションタイトルの最大文字数  |       |
| セクションの説明        | 必須かオプションか？       |       |
| セクション説明の最大文字数   | セクション説明の最大文字数    |       |
| CTA ボタン         | 必須、オプション、または不要か？ |       |

### IMAGE\_GALLERY モジュール

画像ギャラリーモジュールは、IMAGE モジュールと同じ構成プロパティを継承します。さらに、以下のギャラリー固有のプロパティも受け入れます。

| 要件                  | 説明                                                                                                                                      | あなたの値 |
| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | ----- |
| 最小画像数               | ギャラリー画像の最小数（例: 2）                                                                                                                       |       |
| 最大画像数               | ギャラリー画像の最大数（例: 4）                                                                                                                       |       |
| セクションタイトル           | セクションタイトルのテキストが必須か任意か。                                                                                                                  |       |
| セクションの説明            | セクション説明のテキストが必須か任意か。                                                                                                                    |       |
| `alt` タグのオプション性     | 画像で `alt` が必須かどうか。                                                                                                                      |       |
| Call-to-action の任意性 | Call-to-action ボタンまたはリンクが必須か、許可されているか、無効化されているか。                                                                                        |       |
| 追加テキスト行             | <p>画像ギャラリー内の各画像に関連付ける追加テキストごとに、以下を指定します。<br><br>- テキストフィールドの名前<br>- 「required」または「allowed」か？<br>- テキストを別の URL へのハイパーリンクとして機能させるかどうか</p> |       |

### SPLIT\_LAYOUT モジュール

スプリットレイアウトモジュールを使用すると、2 つのモジュールを並べて表示できます。現在、テキストモジュールと画像モジュールのみがサポートされています。テキストモジュールと画像モジュールの個別の構成設定（上記のセクションで説明）に加えて、以下の追加プロパティが必要です。

| 要件      | 説明                         | あなたの値 |
| ------- | -------------------------- | ----- |
| レイアウト比率 | 列比率（50:50、33:67、または 67:33） |       |

## アイデンティティとプライバシー

### 許容される識別子

* セッション ID - 匿名セッション識別子（非 PII）
* 顧客 ID - 小売業者の顧客識別子（非 PII、例：ロイヤルティ ID のハッシュ）

{% hint style="danger" %}
ハッシュ化されたメールアドレス、電話番号、または PII をパラメータや URL に渡さないでください。
{% endhint %}

### プライバシー要件

小売業者は以下を行う必要があります：

* プライバシーポリシーで測定トラッキングについて開示する
* オプトアウトリンクを提供する：
  * NAI： <https://optout.networkadvertising.org/>
  * DAA： <https://optout.aboutads.info/>

### GDPR / 同意

次の場合には、 `regs`オブジェクトを `POST /ads/v3/brand-pages`:

* `regs.gdpr`: `1` に渡します：リクエストが GDPR の対象となる場合（お客様のポリシーに基づく EU/EEA/英国での取り扱い）。 `0`それ以外の場合。
* `regs.consent`： `gdpr` is `1`の場合、CMP からの現在の TCF v2 同意文字列を渡します（他の広告パートナーに表示するのと同じ値）。文字列を捏造したりハードコードしたりせず、ユーザーのブラウザ/アプリで同意されているものを使用してください。
* `iabConsentString`：これは `trackingTemplates`内ではなく、すべてのトラッカースロットの params に表示されます。 `regs.consent` が提供されていた場合、値は文字通りの TC 文字列であり、それ以上の対応は必要ありません。
* 次の場合: `regs.consent` が省略されていた場合、値は `{TCF}`マクロです。トラッキングリクエストを送信する前に、発火時に CMP からの現在の TCF v2 文字列に置換してください。


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://help.citrusad.com/retail-media-interface/integration/ja/brand-pages/brand-page-retailer-integration-guide/tracking-attribution.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.