> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kameleoon.com/llms.txt
> Use this file to discover all available pages before exploring further.

# カスタムデータ

> Kameleoonでカスタムデータを構成・利用して、属性に基づいて訪問者をターゲットし、データの内訳を用いて実験結果を分析します。

カスタムデータはKameleoonの最も強力な機能の1つです。カスタムデータを使用すると、任意のデータ型を各訪問者に関連付けることができ、次の2つの目的に使用されます。

1. 訪問者データに基づくターゲティングセグメントの生成（実験やパーソナライゼーションのための高度なセグメントの作成を含む）。

   カスタムデータの例としては、年齢、過去の購入履歴、現在のカート金額、お気に入りカテゴリーなどがあります。通常、カスタムデータはビジネスの特性と密接に結びついています。たとえば、マーケットプレイスのウェブサイトを運営している場合、訪問者が主に「買い手」または「売り手」のどちらであるかを示すカスタムデータを作成できます。

2. カスタムデータに基づいて結果を分解し、保存された任意のデータ値を使用して実験およびパーソナライゼーションのレポートをフィルタリングすることで、高度な分析レポートを提供します。

カスタムデータは、文字列、ブール値、または数値形式で、シングル、リスト、またはカウント付きリストのタイプを持つことができ、ページ、訪問、または訪問者のスコープを持つことができます。

この記事は、カスタムデータについて詳しく学び、効果的に使用する方法を学ぶための一般的なガイドとして機能します。Kameleoonプラットフォームでカスタムデータを作成することに興味がある場合は、以下の[ユーザーガイド](/user-manual/assets/custom-data/create-custom-data)を参照してください。

## 技術概要

カスタムデータの値が設定されると、サーバーサイドSDKまたはクライアントサイドSDKのいずれを使用しているかに応じて、サーバーまたはユーザーのデバイス上（アプリケーションファイル（engine.js）を含む）にローカルに保存され、リモートのKameleoonサーバーから取得することはありません。このストレージにより、同じ訪問の後続のページビューや、将来の訪問でデータを取得できます。Kameleoonが読み込まれると、書き込まれたカスタムデータは、Activation APIまたはSDKを介して後で自動的に使用可能になります。

<Note>
  Kameleoon Web Experimentationを使用している場合、LocalStorage実装が統一されているため、[サブドメインをまたいだ統合セッションデータ](./web-experimentation/technical-concepts/unify-session-data-storage-across-subdomains)の実装ガイドラインに従う限り、複数のサブドメインにまたがるユーザージャーニーがKameleoonによって自動的に処理されます。Kameleoonはカスタムデータの保存と読み込みも行い、同じウェブサイトの複数タブからの同時アクセスなどの複雑な問題を処理します。
</Note>

カスタムデータに設定された値は、標準のトラッキングプロセスの一部としてKameleoonデータ収集サーバーに送信することもでき、これは3つの目的を果たします。

1. データはレポーティング目的で利用可能になり、特定の属性（たとえばプロファイルタイプごとの訪問数または訪問者数）で訪問または訪問者データをフィルタリングまたは分解したり、データを分析（たとえば支払いタイプごとのコンバージョン）したりするために使用できます。メタデータ値に基づいてコンバージョンデータをフィルタリングまたは分解するには、カスタムデータをメタデータとして目標にリンクする必要があります。

<Note>
  カスタムデータが目標メタデータとして設定されている場合、Kameleoonは各目標コンバージョンのレポーティングで、最新にトラックされたカスタムデータの値を自動的に使用します。[Activation API](./apis/activation-api-js/api-reference/api-reference#processconversion)の `processConversion` メソッド、またはSDKの `trackConversion` メソッドの `metadata` パラメータを使用して、カスタムデータの値を手動で設定できます。
</Note>

2. データは、[AI予測ターゲティング](/user-manual/ai-predictive-targeting/overview) およびContextual Bandit実験のための機械学習アルゴリズムの入力として使用できます。
3. データはバックエンドサーバーに保存され、[Data API](/api-reference/visit/get-visitor-data) を使用して取得できます。

<Note>
  最新バージョン（2.3）のSafariブラウザのIntelligent Tracking Prevention（ITP）制限により、LocalStorageは7日後にクリアされるため、再訪問者が7日後に戻ってきた場合、Safariでカスタムデータのコンテンツをフェッチするためのサーバーへのシンクロナイゼーション呼び出しを回避できません。ただし、Kameleoonはこれらの呼び出しを最適化し、必要な場合（たとえば、7日の期間が経過した場合）にのみ実行します。ソリューションの詳細については、[ITP管理](./web-experimentation/technical-concepts/itp-management) の記事を参照してください。
</Note>

## 中核となる技術コンセプト: カスタムデータのスコープ

カスタムデータの **スコープ** は、ターゲティングのために値がどのように動作し、レポーティングでどのように保存・表示されるかを決定するため、極めて重要です。カスタムデータの構成は、実装タイプ（**Web Experimentation** または **Feature Experimentation (SDK)**）、そしてカスタムデータをいつどのように使用する予定かに依存します。

### ターゲティングのためのスコープ

ターゲティングにおいてカスタムデータがどのように動作するかは、Web ExperimentationとFeature Experimentationの間で大きく異なります。

#### Web Experimentation (engine.js)

**Web Experimentation** では、ターゲティングは通常、カスタムデータの値に基づいてページ上で1回評価されます。同じページでカスタムデータの値が変更されても再評価されません。カスタムデータのスコープは、ターゲティングにおけるその寿命を決定します。

* **ページ:** カスタムデータの値は各ページビューの後にリセットされます。
  * **ユースケース:** 特定のページタイプ（たとえば商品ページ）を閲覧している（または現在見ている）ユーザーをターゲットにする。
* **訪問:** カスタムデータの値は各訪問の後にリセットされます。同じ訪問内でユーザーがページ間を移動しても、カスタムデータは最後の値を保持します。
  * **ユースケース:** 現在の訪問中にニュースレターに登録した訪問者をターゲットにする。
* **訪問者:** カスタムデータの値はリセットされません。同じ訪問者からの複数の訪問にわたって最後の値を保持します。
  * **ユースケース:** 過去にサイトで3回購入したことがある訪問者をターゲットにする。

<Warning>
  カスタムデータの値がKameleoonの初期化と最初の関連ターゲティング実行の後に取得される可能性がある場合は、スコープを **`PAGE`** に設定してください。スコープが **`PAGE`** に設定されていない場合、現在のカスタムデータの値が「遅れる」可能性があり、特にカテゴリーページを閲覧した後に商品ページに移動した訪問者をターゲットとする実験を実行している場合や、数秒後に新しい値を取得する場合に、ターゲティングの問題を引き起こす可能性があります。**`PAGE`** スコープを使用すれば、この問題は発生しません。
</Warning>

#### Feature Experimentation (SDK)

Feature Experimentation用の **SDK** では、スコープに関して **「ページ」のコンセプトはありません**。カスタムデータの値は評価時に明示的に渡されます。ここでは、スコープは主に、カスタムデータがKameleoonサーバーにどのように保存され、どの値が自動的に取得されるか（たとえば `getRemoteVisitorData()` の使用による）を定義します。

デフォルトでは、APIは `VISITOR` スコープの値のみを取得します。これらの値は訪問者に関連付けられ、評価中に使用されます。

### カスタムデータのレポーティングと表示

レポートでカスタムデータがどのように表示されるかも、実験タイプ、カスタムデータのタイプとスコープ、`setCustomData()` でオプションの `overwrite` パラメータが使用されたかどうかによって異なります。

#### デフォルトロジック（overwriteパラメータがfalseまたは省略された場合）

##### Web Experimentationの場合（結果ページ）

Web Experimentationの結果ページでは、すべてのカスタムデータタイプが同じページや同じ訪問で複数の値を持つことができます。これらの値を表示するには、以下のルールが適用されます。

* **シングル型 & ページスコープ:** 訪問中に設定されたすべての値が結果ページに表示され、訪問を分解します。値が1回設定されても複数回設定されても、同じ表示になります（たとえば、訪問にその値のタグが付けられます）。
  * **ユースケース:** 閲覧したページのカテゴリーで訪問を分解する。
* **シングル型 & 訪問スコープ:** 結果ページは、訪問中に設定された **最後の** 値のみを表示し、訪問を分解します。
  * **ユースケース:** ユーザーのメンバーシップタイプで訪問を分解する。
* **シングル型 & 訪問者スコープ:** 結果ページで訪問者ビューを使用してカスタムデータで分解する場合、Kameleoonは選択された時間枠内で、実験に露出または影響を受けたすべての以前の訪問にわたってその訪問者について受信したカスタムデータのすべての値を表示します。
  * **ユースケース:** すべての訪問にわたってサイトで購入した数で訪問者を分解する。
* **タイプ/スコープのすべての組み合わせ（list、countList／ページ、訪問、訪問者）:** 訪問中に割り当てられたすべての値が結果ページに表示され、訪問の詳細な分解が可能になります。値が訪問に1回または繰り返し割り当てられた場合、一貫して表示され、訪問にその値のタグが付けられます。
  * **ユースケース:** ユーザーが登録したすべてのニュースレター、クリックしたナビゲーションメニューリンク、またはカテゴリーページで選択されたフィルターで訪問を分解する。

##### Feature Experimentationの場合（SDK）

Feature Experimentationの場合、SDK環境の性質上、通常はウェブブラウザのような「ページ」のコンセプトがないため、カスタムデータのレポーティングは異なります。

* **ページ** スコープはFeature Experimentationのレポーティング目的では適用されません。SDKは多くの場合サーバー側またはモバイル環境で実行され、そこではデータリセットを引き起こす明確な「ページ読み込み」イベントが本質的に存在しないためです。
* 任意のカスタムデータについて、Kameleoonは訪問中に受信した最後の値のみを保持してレポートします。このアプローチは、機能の決定に対して継続的なセッション内のユーザー属性の最新の状態が一般的に重要となる環境にとって効率的で適切です。
* **訪問** および **訪問者** スコープは、レポーティングで期待通りに動作し、それぞれ訪問内の最後の値による分解、または訪問者の複数の訪問にわたる分解が可能になります。

#### overwriteパラメータでデフォルト動作を上書きする

`setCustomData()` メソッドの `overwrite`（オプションの `boolean`）パラメータを使用すると、カスタムデータの値の保存方法、ひいてはレポートでの表示方法を明示的に制御できます。

* **`overwrite` が `true` の場合:** `setCustomData()` に提供された新しい値は、タイプ（シングル、リスト、カウントリスト）またはスコープ（ページ、訪問、訪問者）に関係なく、**現在のセッション／訪問内** で、そのカスタムデータキーの既存の値を **常に置き換え** ます。つまり、最後に設定された値のみがターゲティングとレポーティングで利用可能になります。
* **`overwrite` が `false` または省略された場合:** 上記のセクションで説明されている **デフォルトロジック** が適用されます。

<Note>
  目標を設定する際にカスタムデータをメタデータとして使用して、カスタムデータの値を各コンバージョンに添付し、レポーティングと分析の目的で使用できます。目標の作成について詳しくは、[新しい目標を作成する](/user-manual/assets/goals/create-a-goal) の記事を参照してください。

  デフォルトでは、カスタムデータはユーザーに関連する属性ですが、カスタムデータをコンバージョンのプロパティとして使用したい場合は、メタデータを使用できます。
</Note>

## 取得方法

Kameleoonはさまざまな統合をすぐに利用できる形で提供しており、以下に詳細を説明します。

### データレイヤー

これらの方法は、Google Tag Manager、Tealium、またはCommanders Actのデータレイヤーで指定された変数からカスタムデータの値を取得します。データレイヤー内の変数名を指定すると、ページのデータレイヤーが読み込まれるとすぐにKameleoonが統合を自動的に完了します。

<Check>
  Kameleoonはデータレイヤー内の複数レベルの階層と配列変数をサポートしています。たとえば、`product.category.name`、`cart["amount"]` または `purchases[3]` から値を取得できます。
</Check>

<Warning>
  Kameleoonは、ページ上にデータレイヤーが利用可能になってからしかカスタムデータの値を設定できません。これには（タグマネージャーをいつ読み込むかに応じて）数秒かかることがあります。A/Bテストのターゲティング条件としてカスタムデータを使用する場合、明らかなちらつき効果が発生する可能性があります。
</Warning>

### Activation API

[Activation API](./apis/activation-api-js/api-reference/api-reference#setcustomdata) を使用して、ブラウザ（クライアント側環境）でカスタムデータの値を設定します。ページ上の特定のDOM要素を見つけて、そのコンテンツをカスタムデータの値として使用します。たとえば、現在のカート金額がウェブページに表示されている場合は、その値を取得して対応するカスタムデータに入力します。

<Note>
  Activation APIのメソッド `setCustomData()` には、`overwriteIfCollection` というパラメータが含まれます。このメソッドの詳細については、Activation API [ドキュメント](./apis/activation-api-js/api-reference/api-reference) を参照してください。

  <Warning>
    `Kameleoon.API.Data.setCustomData()` メソッドは、カスタムデータがリストまたはカウント付きリストのタイプであり、3番目の引数が **false** の場合を除き、常にカスタムデータの既存の値を上書きします。その場合は、既存のリストに追加します。
  </Warning>
</Note>

### カスタムJavaScriptコード

このオプションを使用すると、アドホックなカスタムJavaScriptコードを書くことができます。カスタムデータを設定する際に従うべき主要なルールは、コードが2つのキー（`value` で提供したいこのカスタムデータの値と、（オプションの）`override` ブール値（デフォルトは **false**））を持つオブジェクトを返すことです。

まだ値がないが後でページで取得される予定がある場合は、何も値を返さないでください（nullまたはundefinedを返すことも許容されます）。システムは（最初の呼び出し後の最初の **3秒** は100ミリ秒ごと、それ以降は **3秒** ごと）コードを再実行します。慣例として、`{"value": null}` を返すとカスタムデータは設定されませんが、定期的な実行が停止します。

最初の実行はKameleoonターゲティングシステムがトリガーされる前に行われ、ターゲティングが実行される前にカスタムデータを設定する機会を提供します。

<Warning>
  可能であれば、この取得方法の使用は避けてください。Tag Manager、外部スクリプトファイル、またはHTMLコード内のインラインスクリプトコードなど、別の場所にJavaScriptコードを書き、その後Activation APIの取得方法を使用してカスタムデータを設定してください。
</Warning>

### SDKメソッド

**Feature Experimentation (SDK)** の場合、カスタムデータの値は **SDKメソッドを介してのみ取得されKameleoonに送信されます**。つまり、SDK統合を通じて明示的に渡されます（たとえば、特定のSDKに応じて `addData()` や `setCustomData()` のようなメソッドを使用）。

SDKでのカスタムデータの使用に関する詳細については、[訪問履歴の使用](./feature-experimentation/targeting-and-segmentation/native-segmentation) の記事を参照してください。

### Data API／サーバー間統合

サーバー間統合をセットアップする場合は、[Data API](./apis/data-api-rest/overview) が推奨アプローチです。Data APIの使用には、カスタムデータの名前と値、および **`visitorCode`** を指定して、KameleoonサーバーへのREST呼び出しを実装することが含まれます。

## 高度なオプション

### このデータをターゲティング目的でローカルにのみ使用する

このオプションを有効にすると、サーバー側SDKの1つを使用している場合は、カスタムデータの値をユーザーのデバイスまたはサーバーにローカルに保存できます。このデータはKameleoonサーバーに保存されないため、レポーティングでのアナリティクスには使用できません。この機能は、プライバシーまたは法的な理由で有益です。一部のお客様は、機密データを自社のシステム外部に保存しないように要求する場合がありますが、それでもそのデータに基づいて訪問者の体験をパーソナライズしたい場合があります。

### このカスタムデータをAI予測ターゲティングの入力として使用する

このオプションを有効にすると、機械学習アルゴリズムがこのカスタムデータを入力として使用できます。受け付けられるカスタムデータタイプは**数値**と**ブーリアン**のみです。この機能は、[AI予測ターゲティング](/user-manual/ai-predictive-targeting/overview) アドオンの購読時にのみ利用可能です。

### このカスタムデータをクロスデバイス履歴整合化の一意の識別子として使用する

有効化されると、Kameleoonはこのカスタムデータを訪問者の一意の識別子として扱い、クロスデバイス実験のために複数のKameleoon訪問を一意のユーザーにマップするために使用します。この機能の詳細については、[クロスデバイス実験](./cross-device-experimentation) の記事を参照してください。

## カスタムデータの使用

### セグメントのターゲティング条件

Kameleoonセグメントビルダーは、定義した任意のカスタムデータのターゲティング条件を自動的に追加します。プロセスは自動的で、カスタムデータの値があなたの条件に対応する場合、その特定の訪問者がセグメントに含まれます。

### Activation API経由

`Kameleoon.API.CurrentVisit.customData`（**PAGE** または **VISIT** スコープ）または `Kameleoon.API.Visitor.customData`（**VISITOR** スコープ）を介してカスタムデータの現在の値を取得できます。

### SDK経由

`getRemoteVisitorData()` メソッドは、現在の訪問者の以前の訪問中に収集されたすべてのカスタムデータを取得します。詳細については、[訪問履歴の使用](./feature-experimentation/targeting-and-segmentation/native-segmentation) の記事を参照してください。

### 分析目的

（ローカル限定としてマークされているものを除く）任意のカスタムデータは、実験やパーソナライゼーションの結果ページでフィルターまたは内訳オプションとして使用できます。この情報は、生データエクスポートツールによって作成されたレポートでも利用可能であり、カスタムデータを含む複雑なクエリを（専用のKameleoonデータクラスタを使用して）実行できます。

文字列型のカスタムデータを使用した内訳の場合、結果にはそのデータについて最も頻繁に使用される値が最大 **50** 個含まれます。

数値型のカスタムデータを使用した内訳の場合、結果も最大 **50** 個の可能な値で分解されます。数値カスタムデータの場合、この制限は必ずしも意味を成すとは限りません。

カスタムデータがメタデータとして目標にリンクされている場合、値は現在、生エクスポートを通じてのみアクセスできます。Q2後半に予定されているレポーティングページの更新により、メタデータを結果のフィルターとして直接使用できるようになります。

## 高度な設定

### このカスタムデータに関連付けられたターゲティング条件用のカスタムセレクトボックスコンポーネントを実装する

この機能は、カスタムデータの値をプレーンテキストフィールドではなくセレクトボックスで表示することで、ターゲティング条件でのカスタムデータ値の選択を簡略化し、エンドユーザーがターゲティング用の適切な値を選択するのをはるかに容易にします。考慮すべき重要なポイントが2つあります。

* 生の値は、説明的なラベルに関連付けることができます。
* ラベルと値は、ターゲティング条件インターフェースが表示されたときに動的に取得されます。

この機能は、DMPやCRMなどのサードパーティのデータプロバイダーとの統合に特に役立ちます。たとえば、カスタムデータがDMPからの外部セグメントを表す場合、ユーザーは通常「8ney4225y65a」のような複雑な文字列である内部IDの代わりに、「ロイヤルカスタマー」を選択できます。DMPで定義されているセグメントのリストは常にKameleoonのインターフェースで最新になっており、この機能は同期を自動的に処理します。

<Note>
  カスタムデータに関連付けられているラベルは、Kameleoonプラットフォームにアクセスできるユーザーのみが表示できます。これらはJavaScriptアプリケーションファイルに含まれていないため、ウェブサイトの訪問者はそれらを見ることができません。プロセスはユーザーから隠されています。
</Note>

特定のカスタムデータに対してこの機能を実装するには、可能な値とそのラベルを表すオブジェクトの配列を **同期的に** 返すJavaScriptコードを提供する必要があります。配列は以下の要件を満たす必要があります。

* 配列内のすべての要素はJavaScriptオブジェクトである必要があります。
* これらのオブジェクトには2つのキーが必要です: **value** キー（カスタムデータの実際の可能な値を含む）と **label** キー（この特定の値のテキスト説明を表す）です。
* **value** キーのコンテンツタイプは、カスタムデータの実際のタイプに対応している必要があります。**label** キーには、コンテンツとして文字列を提供する必要があります。

この機能の実用例については、以下のコードサンプルを参照してください。この例では、プラットフォーム上で定義されている利用可能なセグメントのリストを提供するサードパーティサーバー（通常はDMPまたは類似のプラットフォーム）にリモート呼び出しを行います。このコードは、Kameleoonエンドユーザーの選択インターフェースを構築するためにのみ使用されることに注意してください。

```js theme={null}
var xhr = new XMLHttpRequest();
xhr.open("GET", "https://third-party.dmp.com/get-segments?login=XXXX@XXXX.com&password=XXXX", false);

var segments = [];
xhr.onreadystatechange = function() {

    if (this.readyState === XMLHttpRequest.DONE && this.status === 200) {
        var data = JSON.parse(xhr.response);
        data.map(function (segment) {
          if (segment.segment_uuid && segment.name !== "undefined") {
            segments.push({"label": segment.name, "value": segment.segment_uuid});
          }
        });
    }
}

xhr.send();
return segments;
```

<Warning>
  コードが同期的に実行され、ブロッキング動作で値を返すようにしてください。非同期のリモートサーバー呼び出しは、機能の誤動作を引き起こす可能性があるため、避けてください。
</Warning>