> ## 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.
# Java SDK
> Kameleoon Java SDK を統合して、Java EE または Jakarta EE アプリケーションサーバー上で実験を実行し、フィーチャーフラグを有効化します。
Kameleoon Java SDK を使用すると、Java EE / Jakarta EE アプリケーションサーバー上で実験を実行し、フィーチャーフラグを有効化できます。
**はじめに**: 開始方法については、[開発者ガイド](#developer-guide) を参照してください。
**変更履歴**: Java SDK の最新バージョン: 4.22.0 [Changelog](https://github.com/Kameleoon/client-java/blob/master/CHANGELOG.md)。
**SDK メソッド**: Java SDK の完全なリファレンスドキュメントについては、[リファレンス](#reference) セクションを参照してください。
## 開発者ガイド
このガイドは、SDK を数分で統合し、Java アプリケーションで実験の実行を開始できるようにすることを目的としています。
### はじめに
#### スターターキット
Kameleoon は、SDK をテストするためのスターターキットとデモアプリケーションを提供しています。スターターキットには、アプリ内で SDK メソッドをどのように使用するかを示す例を含む、完全に構成されたアプリが含まれています。スターターキット、デモアプリケーション、および詳細な手順は [Java 用スターターキット](https://github.com/Kameleoon/java-examples) で入手できます。
#### Java クライアントのインストール
インストールパッケージは Maven Central リポジトリで入手できます。Java SDK は、右側の例に示すように、プロジェクトの `pom.xml` ファイルに依存関係を追加することでインストールできます。別のプロジェクト管理システムを使用している場合は、追加の例について [統合](https://search.maven.org/artifact/com.kameleoon/kameleoon-client-java) ページを参照してください。
```java title="pom.xml" theme={null}
com.kameleoon
kameleoon-client-java
4.16.0
```
```java title="pom.xml" theme={null}
com.kameleoon
kameleoon-client-java-jakarta
4.16.0
```
#### 追加の構成
認証情報を提供し、SDK の動作をカスタマイズするために、`.properties` 構成ファイルを作成します。[サンプル構成ファイル](/assets/developer-docs/sdks/web-sdks/client-configs/client-java.properties) をダウンロードすることもできます。
このファイルはデフォルトのパス `/etc/kameleoon/client-java.conf` に保存することを推奨しますが、`kameleoon-client-java.properties` としてクラスパス内のどこにでも保存できます。
次の表は、設定可能なプロパティを示しています:
| キー | 説明 | デフォルト値 |
| -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------ |
| `clientId` / `client_id` (*必須*) | Kameleoon サービスへの認証に必要です。`client_id` を確認するには、[API 認証情報](/user-manual/account-and-team-management/users-and-teams/api-credentials) のドキュメントを参照してください。 | |
| `clientSecret` / `client_secret` (*必須*) | Kameleoon サービスへの認証に必要です。`client_secret` を確認するには、[API 認証情報](/user-manual/account-and-team-management/users-and-teams/api-credentials) のドキュメントを参照してください。 | |
| `sessionDuration` / `session_duration_minute` (*オプション*) | Kameleoon が訪問者とその関連データをメモリ (RAM) に保存する所定の時間間隔を指定します。セッション時間を長くすると、訪問者データを保存するために割り当てる必要のある RAM の量が増加することに注意してください。 | `30` 分 |
| `refreshInterval` / `refresh_interval_minute` (*オプション*) | SDK がアクティブな実験とフィーチャーフラグの構成を取得するリフレッシュ間隔を分単位で指定します。この値は、フィーチャーフラグの有効化/無効化や実験の開始などの変更を本番サーバーに反映するためにかかる最大時間を決定します。さらに、[ストリーミングモード](/developer-docs/feature-experimentation/technical-reference/technical-considerations/#streaming-premium-option) も提供しています。これは server-sent events (SSE) を使用して、新しい構成を自動的に SDK にプッシュし、遅延なしでリアルタイムに新しい構成を適用します。 | `60` 分 |
| `defaultTimeout` / `default_timeout_millisecond` (*オプション*) | SDK からのネットワークリクエストのタイムアウトをミリ秒単位で指定します。安定した接続がない場合は、値を 30 秒以上に設定してください。一部のメソッドには、その特定のメソッドのデフォルトタイムアウトを上書きするために使用できる追加のパラメータがあります。メソッドのタイムアウトを明示的に指定しない場合、SDK はこのデフォルト値を使用します。 | `10000` ミリ秒 |
| `trackingInterval` / `tracking_interval_millisecond` (*オプション*) | トラッキングリクエストの間隔をミリ秒単位で指定します。Kameleoon がフィーチャーフラグについて評価した、またはデータがフラッシュされたすべての訪問者がこのトラッキングリクエストに含まれ、SDK は間隔ごとに 1 回実行されます。最小値は `1000` ms (デフォルトでもあります)、最大値は `5000` ms です。 | `1000` ミリ秒 |
| `environment` / `environment` (*オプション*) | フィーチャーフラグの構成を使用する環境です。値は `production`、`staging`、`development` のいずれかです。詳細については [環境の管理](/user-manual/experimentation/feature-experimentation/configure-your-feature-flags/manage-environments) の記事を参照してください。 | `production` |
| `topLevelDomain` / `top_level_domain` *(ハイブリッドモードで必須)* | あなたの Web サイトの現在のトップレベルドメイン。形式: `example.com` を使用します。`https://`、`www`、その他のサブドメインは含めないでください。Kameleoon はこの情報を使用して、トップレベルドメインに対応するクッキーを設定します。 | `null` |
| `proxyHost` / `proxy_host` (*オプション*) | SDK によるすべての送信サーバー呼び出しのプロキシホストを設定します。 | `null` |
| `networkDomain` / `network_domain` (*オプション*) | SDK が送信リクエストに使用するカスタムドメインで、主にプロキシ用途で使用されます。有効なドメイン (例: example.com または sub.example.com) である必要があります。無効な形式の場合、Kameleoon のデフォルト値が使用されます。 | `null` |
#### Kameleoon クライアントの初期化
アプリケーションに SDK をインストールし、認証情報と SDK の動作 (`/etc/kameleoon/client-java.conf` 内) を構成したら、次のステップはアプリケーションコードで Kameleoon クライアントを作成することです。例:
```java theme={null}
import com.kameleoon.KameleoonClientFactory;
String siteCode = "a8st4f59bj";
try {
KameleoonClient kameleoonClient = KameleoonClientFactory.create(siteCode, "custom/file/path/client-java.properties");
} catch (KameleoonException.SiteCodeIsEmpty e) {
// indicates that provided site code is empty
} catch (KameleoonException.ConfigCredentialsInvalid exception) {
// indicates that provided clientId / clientSecret are not valid
}
try {
KameleoonClientConfig config = new KameleoonClientConfig.Builder()
.clientId("") // mandatory
.clientSecret("") // mandatory
.refreshInterval(60) // in minutes, optional (60 minutes by default)
.sessionDuration(30) // in minutes, optional (30 minutes by default)
.defaultTimeout(10_000) // in milliseconds, optional (10000 ms by default)
.trackingInterval(1000) // in milliseconds, optional (1000 ms by default)
.topLevelDomain("example.com") // mandatory if you use hybrid mode (engine or web experiments)
.environment("development") // optional
.proxyHost(new HttpHost("192.168.0.25", 8080, "http")) // optional
.networkDomain("example.com") // optional
.build();
KameleoonClientFactory.create(siteCode, config);
} catch (KameleoonException.SiteCodeIsEmpty e) {
// indicates that provided site code is empty
} catch (KameleoonException.ConfigCredentialsInvalid exception) {
// indicates that provided clientId / clientSecret are not valid
}
```
KameleoonClient は、アプリケーションと Kameleoon プラットフォームを橋渡しするシングルトンオブジェクトです。実験を実行するために必要なすべてのメソッドとプロパティが含まれています。Java SDK では HTTP プロキシの使用もサポートしていることに注意してください (詳細については [`create()` メソッドリファレンス](#create) を参照)。
Kameleoon を通じた A/B テストのコンテキストにおいて、アプリケーションコードの適切なロジックを保証するのは、あなたの責任です。良い慣行として、実験をまだ開始していない場合に、現在の訪問者を実験から除外できることを常に想定するべきです。この除外は、デフォルトおよびリファレンスバリエーションロジックの実装に対応しているため、簡単です。
これで、実験の作成と実装、およびフィーチャーフラグの設定を開始する準備が整いました。
#### フィーチャーフラグの有効化
##### ユーザーへの一意の ID の割り当て
ユーザーに一意の ID を割り当てるには、[`getVisitorCode()`](#getvisitorcode) メソッドを使用できます。**visitor code** が存在しない場合 (リクエストヘッダーのクッキーから)、メソッドはランダムな一意の ID を生成するか、生成済みの `defaultVisitorCode` を使用します。その後、その ID はレスポンスヘッダーのクッキーに設定されます。
Kameleoon を [ハイブリッドモード](/developer-docs/feature-experimentation/get-started/hybrid-experimentation) で使用している場合、`getVisitorCode()` メソッドを呼び出すことで、一意の ID (**visitor code**) がアプリケーションファイル `engine.js` (以前は `kameleoon.js` という名前) と SDK の間で共有されることが保証されます。
##### フラグ構成の取得
コード内でフィーチャーフラグを実装するには、まず Kameleoon アカウントでフィーチャーフラグを作成する必要があります。
特定のユーザーに対するフィーチャーフラグのステータスまたはバリエーションを判別するには、[`getVariation()`](#getvariation) または [`isFeatureActive()`](#isfeatureactive) メソッドを使用して、`featureKey` に基づいて構成を取得します。
`getVariation()` メソッドは、ON/OFF 状態のシンプルなフィーチャーフラグと、複数のバリエーションを持つより複雑なフラグの両方を処理します。このメソッドは、フィーチャールールをチェックし、バリエーションを割り当てて、`featureKey` と `visitorCode` に基づいてそれを返すことで、ユーザーに適切なバリエーションを取得します。
`isFeatureActive()` メソッドは、複数のバリエーションやターゲティングオプションを持つより複雑なフィーチャーフラグとは対照的に、ON または OFF 状態のみを持つシンプルなフィーチャーフラグの構成を取得したい場合に使用できます。
フィーチャーフラグに関連する変数がある場合 (各バリエーションに紐付けられた特定の動作など)、`getVariation()` は [`Variation`](#variation) オブジェクトへのアクセスも可能にし、割り当てられたバリエーションとその関連実験の詳細を提供します。このメソッドは、ユーザーがターゲットになっているかどうかを確認し、訪問者の割り当てられたバリエーションを見つけて、ストレージに保存します。`track=true` の場合、SDK は次のトラッキングリクエストで指定された実験に対する露出イベントを送信します。これは SDK の [`tracking_interval_millisecond`](#additional-configuration) に基づいて自動的にトリガーされます。デフォルトでは、この間隔は 1000 ミリ秒 (1 秒) に設定されています。
`getVariation()` メソッドでは、トラッキングを行うかどうかを制御できます。`track=false` の場合、SDK は露出イベントを送信しません。これは、SDK 経由でデータをトラッキングするのではなく、Kameleoon エンジンによって管理されるクライアントサイドのトラッキングに依存することを希望する場合に便利です。さらに、`track=false` を設定することは、すべてのフラグのバリエーションを取得するだけでトラッキングイベントをトリガーしたくない場合に `getVariations()` メソッドを使用するときに役立ちます。トラッキングの仕組みについて詳しく知りたい場合は、[この記事](/developer-docs/feature-experimentation/technical-reference/faq-global#when-does-the-sdk-send-a-tracking-request-for-analytics) を参照してください。
##### ユーザーをターゲティングしたり、レポートで訪問をフィルタリング/分解するためにデータポイントを追加する
ユーザーをターゲットにするには、フィーチャーのバリエーションを取得したりフラグがアクティブかどうかをチェックする前に、関連するデータポイントをそのプロファイルに追加するようにしてください。[`addData()`](#adddata) メソッドを使用して、これらのデータポイントをユーザーのプロファイルに追加します。
他のデバイスで収集されたデータポイントを取得したり、過去のユーザーデータ (Kameleoon をハイブリッドモードで使用している場合にクライアントサイドで収集) にアクセスしたりするには、[`getRemoteVisitorData()`](#getremotevisitordata) メソッドを使用します。このメソッドは非同期的にサーバーからデータを取得します。バリエーションを取得したりフィーチャーフラグがアクティブかどうかをチェックしたりする *前に* `getRemoteVisitorData()` を呼び出すことが重要です。このデータは、ユーザーを特定のバリエーションに割り当てるために必要になる可能性があるためです。
利用可能なターゲティング条件についての詳細は、[このトピックに関する詳細な記事](/developer-docs/feature-experimentation/targeting-and-segmentation/native-segmentation) を参照してください。
さらに、訪問者プロファイルに追加するデータポイントは、実験を分析する際に利用できるため、デバイスやブラウザーなどの要素で結果をフィルタリングしたり分解したりできます。Kameleoon ハイブリッドモードは、クライアントサイドで多くのデータポイントを自動的に収集するため、これらの事前収集されたデータポイントに基づいて結果を簡単に分解できます。完全なリストは [こちら](/ja/user-manual/experiment-analytics/analyze-results/results-page/results-page-settings#オーディエンスの分割) を参照してください。
自動的に収集されるもの以外の追加データポイントを追跡する必要がある場合は、Kameleoon の [カスタムデータ機能](#customdata) を使用できます。カスタムデータを使用すると、実験に関連する特定の情報を取得して分析できます。収集したデータを分析のために Kameleoon サーバーに送信するために、[`flush()`](#flush) メソッドを呼び出すことを忘れないでください。
結果を正確にするためには、[`UserAgent`](#useragent) データタイプを使用してボットをフィルタリングすることを推奨します。
##### ゴールコンバージョンのトラッキング
ユーザーが目的のアクション (購入など) を完了すると、それはコンバージョンとして記録されます。コンバージョンをトラッキングするには、[`trackConversion()`](#trackconversion) メソッドを使用し、必須の `visitorCode` および `goalId` パラメータを指定します。
コンバージョントラッキングリクエストは、次にスケジュールされたトラッキングリクエストとともに送信されます。これは SDK が ([`tracking_interval_millisecond`](#additional-configuration) で定義された) 定期的な間隔で送信します。リクエストを即座に送信したい場合は、パラメータ `instant=true` を指定して [`flush()`](#flush) メソッドを使用します。
##### 分析ソリューションへのイベント送信
コンバージョンをトラッキングし、顧客の分析ソリューションに露出イベントを送信するには、まず Kameleoon を [ハイブリッドモード](/developer-docs/feature-experimentation/get-started/hybrid-experimentation/) で実装する必要があります。その後、[`getEngineTrackingCode()`](#getenginetrackingcode) メソッドを使用します。
`getEngineTrackingCode()` メソッドは、分析ソリューションに露出イベントを送信するために必要な一意のトラッキングコードを取得します。このメソッドを使用すると、イベントを記録し、希望する分析プラットフォームに送信できます。
### カスタムバケットキーの使用
デフォルトでは、Kameleoon は一意の匿名訪問者 ID (`visitorCode`) を使用して、フィーチャーフラグバリエーションにユーザーを割り当てます。この ID は通常、ユーザーのデバイス上で生成および保存されます (クライアントサイドおよびサーバーサイドの SDK ではブラウザクッキー内、モバイル SDK では永続ストレージ内)。ただし、特定のシナリオでは、同じ組織のすべてのユーザーがフィーチャーフラグの同じバリアントを見ることを保証する必要があるかもしれません。
**カスタムバケットキー** オプションを使用すると、独自のカスタムバケット識別子を提供することで、このデフォルトの動作を上書きできます。この上書きにより、Kameleoon の割り当てロジックがデフォルトの `visitorCode` の代わりに指定したキーを使用することが保証されます。
#### ユースケース
カスタムバケットキーを使用することは、特に次のような状況において、フィーチャーフラグの割り当ての一貫性と正確性を維持するために不可欠です:
* **アカウントレベルまたは組織の実験:** B2B 製品や、同じ組織のすべてのユーザーを同じバリエーションに割り当てたいシナリオでは、`accountId` のような識別子を使用できます。カスタムバケットキーは、チーム全体または会社全体に影響を与える機能の A/B テストにとって重要です。
カスタムバケットキーを実装することで、実験における一貫性と正確性が向上し、より信頼性の高い結果とより良いユーザー体験につながります。
#### 技術的な詳細
フィーチャーフラグのカスタムバケットキーを構成する際、アプリケーションのデータから特定の識別子を Kameleoon に提供します:
```java theme={null}
kameleoonClient.addData(visitorCode, new CustomData(index, "newVisitorCode"));
```
* **カスタムキーの提供:** [`addData()`](#adddata) メソッドを使用して、Kameleoon SDK にカスタム識別子を提供します。このメソッドでは、選択したカスタムバケットキーを [`CustomData`](#customdata) オブジェクトとして渡します。ここで、`newVisitorCode` はバケットに使用したい識別子 (たとえば、新しい `userId` または `accountId`) を指します。
カスタムバケットキーが正しく機能するには、フラグの作成または編集プロセス中にフィーチャーフラグに対しても定義および構成されている必要があります。対応する構成がない場合、SDK のバケットはカスタムキーを適用しません。Kameleoon でこれを設定する方法の詳細な手順については、[この記事](/user-manual/experimentation/feature-experimentation/create-and-manage-flags/create-a-feature-flag#Advanced_Flag_Settings) を参照してください。
* **バケットロジック:** `addData()` メソッドを介してカスタムバケットキーが提供されると、ユーザーをバリエーションに割り当てるためのすべてのハッシュ計算で、デフォルトの `visitorCode` の代わりに `newVisitorCode` (カスタムキー) が使用されます。`newVisitorCode` を使用することは、バケット決定がカスタム識別子に紐付けられることを意味し、その識別子が存在するさまざまなコンテキストにわたって一貫した割り当てが保証されます。
* **データトラッキングと分析:** `newVisitorCode` (カスタムキー) はバケット決定に使用されますが、**後続のすべてのデータ (たとえば、トラッキングイベントやコンバージョン) は *元の* `visitorCode` と関連付けて送信される** ことに注意することが重要です。この分離により、バケットがより高いレベル (アカウントなど) で、または複数のデバイス/セッションにわたって実行された場合でも、分析が実験のより広いコンテキスト内で個々のユーザージャーニーやインタラクションを正確に反映することが保証されます。元の訪問者データは、包括的なレポートのために完全に保持されます。
#### 技術要件
カスタムバケットキーを効果的に使用するには:
* キーは `String` である必要があります。
* バケットしたいエンティティに対して一意である必要があります (たとえば、`userId` を使用する場合、各ユーザーの ID は一意である必要があります)。
* キーは、そのユーザーまたはリクエストに対してフィーチャーフラグの決定が評価される正確な瞬間に SDK で利用可能である必要があります。
### ターゲティング条件
Kameleoon SDK は、キャンペーンでユーザーをターゲットにするために使用できるさまざまな事前定義されたターゲティング条件をサポートしています。この SDK がサポートする条件のリストについては、[訪問履歴を使ってユーザーをターゲットにする](/developer-docs/feature-experimentation/targeting-and-segmentation/native-segmentation) を参照してください。
また、独自の [外部データを使ってユーザーをターゲットにする](/developer-docs/apis/data-api-rest/tutorials/storing-and-retrieving-external-data-to-target-users) こともできます。
### クロスデバイス実験
複数のデバイスからアプリにアクセスする訪問者をサポートするために、Kameleoon は以前に収集された訪問者データを各訪問者のデバイス間で同期させ、クロスデバイス実験を通じてデバイス間で訪問履歴を統合できるようにします。Kameleoon がデバイス間でデータを処理する方法に関するケーススタディと詳細情報は、[クロスデバイス実験に関する記事](/developer-docs/cross-device-experimentation) で入手できます。
#### デバイス間でのカスタムデータの同期
カスタムマッピング同期は、デバイス間で訪問者データを揃えるために使用されますが、常に必要というわけではありません。カスタムマッピング同期が不要な 2 つのシナリオを以下に示します:
**デバイス間で同じユーザー ID**
すべてのデバイスで同じユーザー ID が一貫して使用されている場合、カスタムマッピング同期なしで自動的に同期が処理されます。複数のデバイス間で収集されたデータを同期したい場合は、`getRemoteVisitorData()` メソッドを呼び出すだけで十分です。
**一貫した ID を持つマルチサーバーインスタンス**
複数のサーバーが関与する複雑なセットアップ (たとえば、分散サーバーインスタンス) で、サーバー間で同じユーザー ID が利用可能な場合、追加のカスタムマッピング同期なしに、サーバー間の同期 (`getRemoteVisitorData()` による) で十分です。
追加データが必要なお客様は、[`getRemoteVisitorData()`](#getremotevisitordata) メソッドの説明を参照してください。以下のコードでは、データを正確に取得するために、2 つのデバイス間で同じ一意の識別子 (この場合は `visitorCode` で、`userId` とも呼ばれます) が一貫して使用されていることを前提としています。
収集したデータをリアルタイムで同期したい場合、カスタムデータのスコープに **Visitor** を選択する必要があります。
```java title="Device A" theme={null}
// In this example, a Custom data with index `90` was set to "Visitor" scope in Kameleoon.
final int VISITOR_SCOPE_CUSTOM_DATA_INDEX = 90;
kameleoonClient.addData(visitorCode, new CustomData(VISITOR_SCOPE_CUSTOM_DATA_INDEX, "your data"));
kameleoonClient.flush(visitorCode);
```
```java title="Device B" theme={null}
// Before working with the data, call the `getRemoteVisitorData` method.
kameleoonClient.getRemoteVisitorData(visitorCode).get();
// After calling the method, the SDK on Device B will have access to CustomData of Visitor scope defined on Device A.
// So, "your data" will be available for targeting and tracking the visitor.
```
#### セッション統合のためのカスタムデータの使用
[クロスデバイス実験](/developer-docs/cross-device-experimentation) では、訪問者の履歴を各デバイス間で統合できます (履歴の照合)。履歴の照合により、異なる訪問者セッションを 1 つに統合できます。訪問履歴を統合するには、[`CustomData`](#customdata) を使用して訪問者の一意の識別子を提供します。詳細については、[専用ドキュメント](/developer-docs/cross-device-experimentation/#activating-cross-device-history-reconciliation) を参照してください。
クロスデバイス照合が有効になった後、パラメータ `userId` を指定して [`getRemoteVisitorData()`](#getremotevisitordata) を呼び出すと、特定のユーザーに関する既知のすべてのデータが取得されます。
同じ識別子を持つセッションには、実験において常に同じバリエーションが表示されます。実験の結果ページの訪問者ビューでは、これらのセッションは単一の訪問者として表示されます。
SDK の構成により、関連付けられたセッションは常に実験の同じバリエーションを見ることが保証されます。ただし、クロスデバイスバリエーション割り当てにはいくつかの制限があります。これらの制限は [こちら](/developer-docs/cross-device-experimentation#critical-points-and-practical-insights) に概説されています。
Kameleoon プラットフォームでカスタムデータをセットアップするには、[クロスデバイス履歴照合の有効化](#cross-device-experimentation) ガイドに従ってください。
その後、通常どおりに SDK を使用できます。セッション統合のコンテキストで役立つ可能性のあるメソッドは以下のとおりです:
* `getRemoteVisitorData()` に `UniqueIdentifier(true)` を追加 - すべての関連付けられた訪問者のデータを取得します。
* [`trackConversion()`](#trackconversion) または [`flush()`](#flush) に `UniqueIdentifier(true)` データを追加 - 別の訪問者に関連付けられた特定の訪問者の一部のデータをトラッキングします。
識別子として使用するカスタムデータは **Visitor スコープ** に設定する必要があるため、各デバイス上で [`getRemoteVisitorData()`](#getremotevisitordata) メソッドを使用して識別子を取得するには、[クロスデバイスカスタムデータ同期](/developer-docs/cross-device-experimentation) を使用する必要があります。
セッション統合のためのカスタムデータの使用方法の例を以下に示します。
```java theme={null}
// In this example, 91 represents the Custom Data's index configured as a unique identifier in Kameleoon.
final int MAPPING_INDEX = 91;
final String FEATURE_KEY = "ff123";
// 1. Before the visitor is authenticated
// Retrieve the variation for an unauthenticated visitor.
// Assume anonymousVisitorCode is the randomly generated ID for that visitor.
Variation anonymousVariation = kameleoonClient.getVariation(anonymousVisitorCode, FEATURE_KEY);
// 2. After the visitor is authenticated
// Assume `userId` is the visitor code of the authenticated visitor.
kameleoonClient.addData(anonymousVisitorCode, new CustomData(MAPPING_INDEX, userId));
kameleoonClient.flush(true, anonymousVisitorCode);
// Indicate that `userId` is a unique identifier.
kameleoonClient.addData(userId, new UniqueIdentifier(true));
// 3. After the visitor was authorized
// Retrieve the variation for the `userId`, which will match the anonymous visitor code's variation.
Variation userVariation = kameleoonClient.getVariation(userId, FEATURE_KEY);
boolean isSameVariation = userVariation.getKey().equals(anonymousVariation.getKey()); // true
// `userId` and `anonymousVisitorCode` are now linked and can be tracked as a single visitor.
kameleoonClient.trackConversion(userId, 123, 10.0);
// Additionally, the linked visitors share all fetched previously tracked remote data.
kameleoonClient.getRemoteVisitorData(userId).get();
```
この例では、アプリケーションにログインページがあります。ログイン時にユーザー ID が不明なため、[`getVisitorCode()`](#getvisitorcode) メソッドによって生成された匿名訪問者識別子が使用されます。ユーザーがログインした後、匿名訪問者がユーザー ID と関連付けられ、訪問者の一意の識別子として使用されます。
### ロギング
SDK は、内部のさまざまなプロセスや問題を反映するログを生成します。
#### ログレベル
SDK は、ログレベルによるログの制限の構成をサポートしています。
```java theme={null}
// The `NONE` log level does not allow logging.
com.kameleoon.logging.KameleoonLogger.setLogLevel(com.kameleoon.logging.LogLevel.NONE);
// The `ERROR` log level only allows logging issues that may affect the SDK's primary behaviour.
com.kameleoon.logging.KameleoonLogger.setLogLevel(com.kameleoon.logging.LogLevel.ERROR);
// The `WARNING` log level allows logging issues which may require an attention.
// It extends the `ERROR` log level.
// The `WARNING` log level is a default log level.
com.kameleoon.logging.KameleoonLogger.setLogLevel(com.kameleoon.logging.LogLevel.WARNING);
// The `INFO` log level allows logging general information on the SDK's internal processes.
// It extends the `WARNING` log level.
com.kameleoon.logging.KameleoonLogger.setLogLevel(com.kameleoon.logging.LogLevel.INFO);
// The `DEBUG` level logs additional details about the SDK’s internal processes and extends the `INFO` level
// with more granular. diagnostic output.
// This information is not intended for end-user interpretation but can be sent to our support team
// to assist with internal troubleshooting.
com.kameleoon.logging.KameleoonLogger.setLogLevel(com.kameleoon.logging.LogLevel.DEBUG);
```
#### ログのカスタムハンドリング
SDK は、デフォルトでログをコンソール出力に書き込みます。この動作は上書きできます。
ログレベルによるロギング制限は、ログハンドリングロジックとは別に実行されます。
```java theme={null}
public class CustomLogger implements com.kameleoon.logging.Logger {
private final java.util.logging.Logger inner;
public CustomLogger(java.util.logging.Logger inner) {
this.inner = inner;
}
// `log` method accepts logs from the SDK
@Override
public void log(com.kameleoon.logging.LogLevel level, String message) {
// Custom log handling logic here. For example:
switch (level) {
case ERROR:
inner.log(java.util.logging.Level.SEVERE, message);
break;
case WARNING:
inner.log(java.util.logging.Level.WARNING, message);
break;
case INFO:
inner.log(java.util.logging.Level.INFO, message);
break;
case DEBUG:
inner.log(java.util.logging.Level.FINE, message);
break;
}
}
}
// Log level filtering is applied separately from log handling logic.
// The custom logger will only accept logs that meet or exceed the specified log level.
// Ensure the log level is set correctly.
com.kameleoon.logging.KameleoonLogger.setLogLevel(com.kameleoon.logging.LogLevel.DEBUG); // Optional; defaults to `LogLevel.WARNING`.
com.kameleoon.logging.KameleoonLogger.setLogger(new CustomLogger());
```
## リファレンス
これは Java SDK の完全なリファレンスドキュメントです。
### 初期化
#### create()
SDK を使用するには、初期化を完了する必要があります。アプリケーションは、`KameleoonClient` クラスのオブジェクトを通じて SDK とのすべてのやり取りを行います。`KameleoonClientFactory` の静的メソッド `create()` を使用してこのオブジェクトを作成します。
```java theme={null}
import com.kameleoon.KameleoonClientFactory;
String siteCode = "a8st4f59bj";
try {
KameleoonClient kameleoonClient = KameleoonClientFactory.create(siteCode, "custom/file/path/client-java.properties");
} catch (KameleoonException.SiteCodeIsEmpty e) {
// indicates that provided site code is empty
} catch (KameleoonException.ConfigCredentialsInvalid exception) {
// indicates that provided clientId / clientSecret are not valid
}
try {
KameleoonClientConfig config = new KameleoonClientConfig.Builder()
.clientId("") // mandatory
.clientSecret("") // mandatory
.refreshInterval(60) // in minutes, optional (60 minutes by default)
.sessionDuration(30) // in minutes, optional (30 minutes by default)
.defaultTimeout(10_000) // in milliseconds, optional (10000 ms by default)
.trackingInterval(1000) // in milliseconds, optional (1000 ms by default)
.topLevelDomain("example.com") // mandatory if you use hybrid mode (engine or web experiments)
.environment("development") // optional
.proxyHost(new HttpHost("192.168.0.25", 8080, "http")) // optional
.networkDomain("example.com") // optional
.build();
KameleoonClientFactory.create(siteCode, config);
} catch (KameleoonException.SiteCodeIsEmpty e) {
// indicates that provided site code is empty
} catch (KameleoonException.ConfigCredentialsInvalid exception) {
// indicates that provided clientId / clientSecret are not valid
}
```
##### 引数
| 名前 | 型 | 説明 | デフォルト値 |
| --------------------------- | ----------------------- | ------------------------------------------------------------------------------------- | --------------------------------- |
| siteCode (*必須*) | `String` | SDK で使用している Kameleoon プロジェクトの [一意のキー](/user-manual/faq#how-do-i-find-my-sitecode) です。 | |
| configurationPath (*オプション*) | `String` | SDK 構成ファイルへのパス。 | `/etc/kameleoon/client-java.conf` |
| kameleoonConfig (*オプション*) | `KameleoonClientConfig` | 構成ファイルを使用する代わりに渡すことができる構成 SDK オブジェクト。 | `null` |
##### 戻り値
| 型 | 説明 |
| ----------------- | ---------------------------------------------------------------- |
| `KameleoonClient` | アプリケーションが実験とフィーチャーフラグを管理するために使用できる `KameleoonClient` クラスのインスタンス。 |
##### スローされる例外
| 型 | 説明 |
| ------------------------------------------- | --------------------------------------------------- |
| KameleoonException.ConfigCredentialsInvalid | 要求された認証情報が提供されなかった (構成ファイル内またはメソッドへの引数として) ことを示す例外。 |
| KameleoonException.SiteCodeIsEmpty | 指定されたサイトコードが無効な値である空の文字列であることを示す例外。 |
#### waitInit()
`waitInit()` は、`KameleoonClient` の初期化を待機します。このメソッドを使用すると、他の操作に進む前に SDK がクライアントを正常に初期化したかどうかを確認できます。
`waitInit()` メソッドが失敗した場合、初期化プロセスは中断されることなく続行されます。`waitInit()` メソッドへの後続の呼び出しは、`KameleoonClient` の現在の状態を反映した結果を返します。したがって、SDK のステータスをチェックするために `waitInit()` メソッドを複数回呼び出すことができます。
```java theme={null}
// Synchronized approach
try {
kameleoonClient.waitInit().get();
} catch (InterruptedException | ExecutionException exception) {
// Indicates that the client could not be initialized due to the thrown exception.
}
// Asynchronous approach
kameleeoonClient.waitInit().handle((res, ex) -> {
if (ex != null) {
// Indicates that the client could not be initialized due to the thrown exception.
}
return res;
});
```
##### 戻り値
| 型 | 説明 |
| ------------------------- | ----------------------------- |
| `CompletableFuture` | クライアントが正常に初期化されたときにタスクが完了します。 |
##### スローされる例外
| 型 | 説明 |
| ----------- | ------------------------------------ |
| SDKNotReady | クライアントが正しく初期化されておらず、まだ使用できないことを示す例外。 |
### フィーチャーフラグとバリエーション
#### isFeatureActive()
* *📨 Kameleoon にトラッキングデータを送信します (`track` パラメータに依存)*
このメソッドは以前 `activeFeature` と呼ばれており、SDK バージョン `4.0.0` で削除されました。
指定されたユーザーに対してフィーチャーフラグがアクティブであるべきかどうかをチェックするには、このメソッドを呼び出します。このメソッドは、フィーチャーがユーザーに対してアクティブかどうかをチェックするために、`visitorCode` と `featureKey` を必須引数として受け取ります。
ユーザーがこのフィーチャーフラグに関連付けられていない場合、SDK はランダムなブール値 (このフィーチャーにユーザーを追加するには `true`、ユーザーをフィーチャーから除外するには `false`) を返します。指定された `visitorCode` を持つユーザーがすでにこのフィーチャーフラグに登録されている場合、SDK は以前の `featureFlag` 値を検出します。
潜在的な例外をキャッチして処理するようにしてください。
`visitorCode` を指定すると、`isFeatureActive()` メソッドはこれを一意の訪問者識別子として使用します。これは [クロスデバイス実験](/developer-docs/cross-device-experimentation) に役立ちます。`visitorCode` を指定して `isUniqueIdentifier` パラメータを `true` に設定すると、SDK はフラッシュされたデータを指定された識別子に関連付けられた訪問者にリンクします。
パラメータ `isUniqueIdentifier` は非推奨です。代わりに [`UniqueIdentifier`](#uniqueidentifier) を使用してください。
`isUniqueIdentifier` は特殊な状況で役立ちます。たとえば、訪問者に付与された匿名の `visitorCode` にアクセスできないが、セッション統合を通じてその訪問者にリンクされている内部 ID を使用できる場合などです。
```java theme={null}
String visitorCode = kameleoonClient.getVisitorCode(httpServletRequest, httpServletResponse);
String featureKey = "new_checkout";
Boolean hasNewCheckout = false;
try {
hasNewCheckout = kameleoonClient.isFeatureActive(visitorCode, featureKey);
// disabling tracking
hasNewCheckout = kameleoonClient.isFeatureActive(false, visitorCode, featureKey);
} catch (KameleoonException.FeatureNotFound e) {
// Feature toggle not yet activated on Kameleoon's side - we consider the feature inactive.
hasNewCheckout = false;
} catch (Exception e) {
// This is a generic exception handler that handles all exceptions.
System.out.println("Exception occurred");
}
if (hasNewCheckout)
{
// Implement new checkout code here
}
```
##### 引数
| 名前 | 型 | 説明 |
| ------------------------ | --------- | -------------------------------------------------------------------------------------------- |
| track | `boolean` | フィーチャー評価のトラッキングを有効または無効にするためのオプションのパラメータ (デフォルトは `true`)。 |
| visitorCode | `String` | ユーザーの一意の識別子。このフィールドは必須です。 |
| featureKey | `String` | ユーザーのステータスをチェックしたいフィーチャーのキー。このフィールドは必須です。 |
| isUniqueIdentifier (非推奨) | `boolean` | visitorCode が一意の識別子であるかどうかを指定するためのオプションのパラメータ。指定されていない場合、デフォルト値は `false` です。このフィールドはオプションです。 |
##### 戻り値
| 型 | 説明 |
| --------- | ---------------------------------------- |
| `boolean` | 指定された `visitorCode` に対して登録されているフィーチャーの値。 |
##### スローされる例外
| 型 | 説明 |
| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| KameleoonException.FeatureNotFound | 要求されたフィーチャー ID が SDK の内部構成で見つからなかったことを示す例外。この例外は通常、フィーチャーフラグが Kameleoon 側でまだ有効化されていない (ただし、フィーチャーを実装するコードはアプリケーションにすでにデプロイされている) ことを意味します。 |
| KameleoonException.VisitorCodeInvalid | 提供された訪問者コードが有効ではないことを示す例外。空であるか、255 文字を超えています。 |
#### getVariation()
* 📨 *Kameleoon にトラッキングデータを送信します (`track` パラメータに依存)*
特定のフィーチャーフラグに対して、特定の訪問者に割り当てられた [`Variation`](#variation) を取得します。
このメソッドは、`visitorCode` と `featureKey` を必須引数として受け取ります。`track` 引数はオプションで、デフォルトは `true` です。
訪問者に割り当てられた `Variation` を返します。訪問者がフィーチャーフラグのルールに関連付けられていない場合、メソッドは指定されたフィーチャーフラグのデフォルトの `Variation` を返します。
潜在的な例外を管理するために、コードに適切なエラー処理が実装されていることを確認してください。
デフォルトのバリエーションとは、訪問者がフィーチャーフラグの事前定義された配信ルールのいずれにも一致しないときに、訪問者に割り当てられるバリエーションを指します。言い換えれば、特定のルールでターゲットにされていないすべてのユーザーに適用されるフォールバックのバリエーションです。これは、管理インターフェイスの「それ以外のすべての人については…」セクションのバリエーションとして表されます。
```java theme={null}
String visitorCode = kameleoonClient.getVisitorCode(httpServletRequest, httpServletResponse);
String featureKey = "new_checkout";
Variation variation;
try {
variation = kameleoonClient.getVariation(visitorCode, featureKey);
// disabling tracking
variation = kameleoonClient.getVariation(visitorCode, featureKey, false);
} catch (KameleoonException.FeatureNotFound e) {
// The error has occurred; the feature flag isn't found in the current configuration.
} catch (KameleoonException.FeatureEnvironmentDisabled e) {
// The feature flag is disabled for the environment.
} catch (KameleoonException.VisitorCodeInvalid e) {
// The visitor code you passed to the method is invalid and can't be accepted by SDK.
} catch (KameleoonException ex) {
// Handle the common Kameleoon Exception
}
// Fetch a variable value for the assigned variation
String title = (String) variation.getVariables().get("title").getValue();
switch (variation.getKey()) {
case 'on':
// Main variation key is selected for visitorCode
break;
case 'alternative_variation':
// Alternative variation key
break;
default:
// Default variation key
break;
}
```
##### 引数
| 名前 | 型 | 説明 | デフォルト |
| ------------------ | --------- | ----------------------------------------- | ------ |
| visitorCode (*必須*) | `String` | 訪問者の一意の識別子。 | |
| featureKey (*必須*) | `String` | 訪問者に公開したいフィーチャーのキー。 | |
| track (*オプション*) | `boolean` | フィーチャー評価のトラッキングを有効または無効にするためのオプションのパラメータ。 | `true` |
##### 戻り値
| 型 | 説明 |
| ----------- | ---------------------------------------------------------- |
| `Variation` | 特定のフィーチャーフラグに対して、特定の訪問者に割り当てられた [`Variation`](#variation)。 |
##### スローされる例外
| 型 | 説明 |
| ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `VisitorCodeInvalid` | 提供された訪問者コードが有効ではないことを示す例外。空であるか、255 文字を超えています。 |
| `FeatureNotFound` | 要求されたフィーチャーキーが SDK の内部構成で見つからなかったことを示す例外。通常、これはフィーチャーフラグが Kameleoon アプリで有効化されていない (ただし、フィーチャーを実装するコードはアプリケーションにすでにデプロイされている) ことを意味します。 |
| `FeatureEnvironmentDisabled` | フィーチャーフラグが訪問者の現在の環境 (本番、ステージング、開発など) で無効になっていることを示す例外。 |
#### getVariations()
* 📨 *Kameleoon にトラッキングデータを送信します (`track` パラメータに依存)*
すべてのフィーチャーフラグにわたって、特定の訪問者に割り当てられた [`Variation`](#variation) オブジェクトのマップを取得します。
このメソッドは、利用可能なすべてのフィーチャーフラグを反復処理し、指定された訪問者に関連付けられた各フラグの割り当てられた `Variation` を返します。`visitorCode` を必須引数として受け取り、`onlyActive` と `track` はオプションです。
* `onlyActive` が `true` に設定されている場合、メソッド `getVariations()` は、ユーザーが `off` バリエーションでバケットされていないことを条件として、フィーチャーフラグのバリエーションを返します。
* `track` パラメータは、メソッドがバリエーションの割り当てをトラッキングするかどうかを制御します。デフォルトでは `true` に設定されています。`false` に設定されている場合、トラッキングは無効になります。
返されるマップは、フィーチャーフラグキーをキー、対応する `Variation` を値として構成されます。フィーチャーフラグに割り当てられたバリエーションがない場合、そのフラグのデフォルトの `Variation` を返します。
潜在的な例外を管理するために、適切なエラー処理を実装する必要があります。
デフォルトのバリエーションとは、訪問者がフィーチャーフラグの事前定義された配信ルールのいずれにも一致しないときに、訪問者に割り当てられるバリエーションを指します。言い換えれば、特定のルールでターゲットにされていないすべてのユーザーに適用されるフォールバックのバリエーションです。これは、管理インターフェイスの「それ以外のすべての人については…」セクションのバリエーションとして表されます。
```java theme={null}
try {
Map variations = kameleoonClient.getVariations(visitorCode);
// only active variations
Map variations = kameleoonClient.getVariations(visitorCode, true);
// disable tracking
Map variations = kameleoonClient.getVariations(visitorCode, true, false);
} catch (VisitorCodeInvalid e) {
// Handle exception
}
```
##### 引数
| 名前 | 型 | 説明 | デフォルト |
| -------------------- | --------- | ------------------------------------------------------------------------- | ------- |
| visitorCode (*必須*) | `String` | 訪問者の一意の識別子。 | |
| onlyActive (*オプション*) | `boolean` | アクティブな (`true`) またはすべての (`false`) フィーチャーフラグのバリエーションを返すかどうかを示すオプションのパラメータ。 | `false` |
| track (*オプション*) | `boolean` | フィーチャー評価のトラッキングを有効または無効にするためのオプションのパラメータ。 | `true` |
##### 戻り値
| 型 | 説明 |
| ------------------------ | ---------------------------------------------------------------------------- |
| `Map` | 対応するフィーチャーのキーを使用して、フィーチャーフラグの割り当てられた [`Variation`](#variation) オブジェクトを含むマップ。 |
##### スローされる例外
| 型 | 説明 |
| -------------------- | ---------------------------------------------- |
| `VisitorCodeInvalid` | 提供された訪問者コードが有効ではないことを示す例外。空であるか、255 文字を超えています。 |
#### setForcedVariation()
このメソッドを使用すると、標準的な評価プロセスをバイパスして、特定の [`Variation`](#variation) をユーザーにプログラム的に割り当てることができます。これは、通常の評価ロジックが不要、またはスキップする必要がある制御された実験で特に有用です。デバッグやカスタムテストなどのシナリオでも役立ちます。
**強制** バリエーションが設定されると、Kameleoon のリアルタイム評価ロジックが上書きされます。セグメンテーション、ターゲティング条件、アルゴリズム的計算などのプロセスはスキップされます。実験中にセグメンテーションとターゲティング条件を保持するには、代わりに `forceTargeting=false` を設定します。
**シミュレートされた** バリエーションは、常に実行順序で優先されます。**シミュレートされた** バリエーション計算がトリガーされると、それが最初に完全に処理され完了します。
強制バリエーションは、評価されたバリエーションと同じように扱われます。これは分析でトラッキングされ、標準的な評価されたバリエーションと同様にユーザーコンテキストに保存されるため、レポート作成における一貫性が保証されます。
特定の条件 (たとえば、無効なパラメータ、ユーザーコンテキスト、または内部の問題) の下で、メソッドは例外をスローする可能性があります。アプリケーションが安定し、回復力を保つために、適切な例外処理が不可欠です。
**強制** バリエーションと **[シミュレートされた](#getvisitorcode)** バリエーションを区別することが重要です:
* **強制バリエーション**: 個別の実験に固有です。
* **シミュレートされたバリエーション**: 全体的な **フィーチャーフラグ** の結果に影響します。
```java theme={null}
try {
// Forcing the variation "on" for the feature flag "featureKey1" for the visitor
final int experimentId = 9516;
kameleoonClient.setForcedVariation(visitorCode, experimentId, "on");
// Resetting the forced variation for the feature flag "featureKey1" for the visitor
kameleoonClient.setForcedVariation(visitorCode, experimentId, null);
} catch (KameleoonException ex) {
// Handle the common Kameleoon Exception
}
```
##### 引数
| 名前 | 型 | 説明 | デフォルト |
| ------------------------ | --------- | -------------------------------------------------------------------------------------- | ------ |
| visitorCode (*必須*) | `String` | 訪問者の一意の識別子。 | |
| experimentId (*必須*) | `int` | 評価プロセス中にターゲットおよび選択される **Experiment Id**。 | |
| variationKey (*必須*) | `String` | 実験の返される値として強制すべき `Variation` に対応する **Variation Key**。値が `null` の場合、強制バリエーションはリセットされます。 | |
| forceTargeting (*オプション*) | `boolean` | 実験のターゲティングを強制してスキップするか (`true`)、標準の評価プロセスのように適用するか (`false`) を示します。 | `true` |
##### スローされる例外
| 型 | 説明 |
| --------------------------- | ---------------------------------------------------------------------------------------------------------- |
| `VisitorCodeInvalid` | 提供された訪問者コードが有効ではないことを示す例外。空であるか、255 文字を超えています。 |
| `FeatureExperimentNotFound` | 要求された実験 ID が SDK の内部構成で見つからなかったことを示す例外。通常はこれは正常で、ルールに対応する実験が Kameleoon 側でまだ有効化されていないことを意味します。 |
| `FeatureVariationNotFound` | 要求されたバリエーションキー (ID) が SDK の内部構成で見つからなかったことを示す例外。通常はこれは正常で、バリエーションに対応する実験が Kameleoon 側でまだ有効化されていないことを意味します。 |
ほとんどの場合、例で示されているように、基本的なエラー `KameleoonException` のみを処理する必要があります。ただし、異なるタイプのエラーに対する応答が必要な場合は、特定の要件に基づいて個別に処理してください。さらに、信頼性を向上させるために、`Exception` を含めることで一般的な言語エラーを処理できます。
#### evaluateAudiences()
* 📨 *Kameleoon にトラッキングデータを送信します*
このメソッドは、利用可能なすべての Audiences Explorer セグメントに対して訪問者を評価し、一致する訪問者をトラッキングします。
`evaluateAudiences()` は、**関連するすべての訪問者データが設定または更新された後**、フィーチャーバリエーションを取得したりフィーチャーフラグをチェックする **直前** に呼び出す必要があります。このアプローチにより、訪問者は利用可能な最新のデータに対して評価され、すべての基準に基づいた正確なオーディエンス割り当てが可能になります。
このメソッドを呼び出した後、Audiences Explorer でセグメントのパフォーマンスの詳細な分析を実行できます。
```java theme={null}
try {
kameleoonClient.evaluateAudiences(visitorCode);
} catch (KameleoonException ex) {
// Handle the common Kameleoon Exception
}
```
##### 引数
| 名前 | 型 | 説明 |
| ------------------ | -------- | ----------- |
| visitorCode (*必須*) | `String` | 訪問者の一意の識別子。 |
##### スローされる例外
| 型 | 説明 |
| -------------------- | ---------------------------------------------- |
| `VisitorCodeInvalid` | 提供された訪問者コードが有効ではないことを示す例外。空であるか、255 文字を超えています。 |
ほとんどの場合、例で示されているように、基本的なエラー `KameleoonException` のみを処理する必要があります。ただし、異なるタイプのエラーに対する応答が必要な場合は、特定の要件に基づいて個別に処理してください。さらに、信頼性を向上させるために、`Exception` を含めることで一般的な言語エラーを処理できます。
#### getFeatureList()
このメソッドは以前 `obtainFeatureList` と呼ばれており、SDK バージョン `4.0.0` で削除されました。
現在 SDK で利用可能なフィーチャーフラグキーのリストを返します。
```java theme={null}
List allFeatureFlagKey = kameleoonClient.getFeatureList();
```
##### 戻り値
| 型 | 説明 |
| -------------- | --------------- |
| `List` | フィーチャーフラグキーのリスト |
#### getDataFile()
すべてのフィーチャーフラグを評価するには、[`getVariations()`](#getvariations) を使用してください。このメソッドは、`DataFile` を呼び出してフラグを [`getVariation()`](#getvariation) で反復処理するよりも効率的です。
現在の SDK 構成を [`DataFile`](#datafile) オブジェクトとして返します。
```java theme={null}
try {
DataFile dataFile = kameleoonClient.getDataFile();
} catch (Exception e) {
// Recommended (but optional) safeguard for unexpected exceptions from third-party libraries
}
```
##### 戻り値
| 型 | 説明 |
| ---------- | --------------------------------- |
| `DataFile` | SDK 構成を含む [`DataFile`](#datafile) |
### 訪問者データ
#### getVisitorCode()
このメソッドは以前 `obtainVisitorCode` と呼ばれており、SDK バージョン `4.0.0` で削除されました。
現在の訪問者の Kameleoon `visitorCode` を取得するために、`getVisitorCode()` メソッドを呼び出す必要があります。このメソッドは、ユーザー識別の一貫性を保証する必要があるフロントエンドとバックエンドの混合環境で Kameleoon を使用する場合に特に重要です。実装ロジックは以下のとおりです:
1. 現在の HTTP リクエストに関連付けられた `kameleoonVisitorCode` クッキーまたはクエリパラメータが見つかるかどうかを確認します。見つかった場合、この `kameleoonVisitorCode` を訪問者識別子として使用します。
2. 現在のリクエストでクッキー/パラメータが見つからない場合、新しい識別子をランダムに生成するか、`defaultVisitorCode` 引数が渡されている場合はそれを識別子として使用します。このプロセスにより、お客様が自分の識別子を訪問者コードとして使用したい場合に、それを使用できます。この柔軟性は、マッチングテーブルでの追加検索なしに、Kameleoon の訪問者を自社のユーザーとマッチングできるという追加のメリットがあります。
3. いずれにせよ、サーバーサイド (HTTP ヘッダー経由) で `kameleoonVisitorCode` クッキーが該当する値で設定されます。その後、メソッドはこの識別子の値を返します。
詳細については、[この記事](/developer-docs/feature-experimentation/get-started/hybrid-experimentation/) を参照してください。
`visitorCode` を提供する場合、その一意性はあなたの側で保証する必要があります。SDK ではチェックできません。また、`visitorCode` の長さは `255` 文字に制限されています。それを超える文字があると例外がスローされます。
`getVisitorCode()` メソッドを使用すると、訪問者に **シミュレートされた** バリエーションを設定できます。クッキー (**リクエスト** または **ドキュメント** から) に `kameleoonSimulationFFData` キーが含まれていると、標準的な評価プロセスがバイパスされます。代わりに、メソッドは提供されたデータに基づいて [`Variation`](#variation) を直接返します。
シミュレーションは 2 つの方法で適用できます:
* **自動 (推奨):** Kameleoon Web Experimentation を使用しているか、SDK を [ハイブリッドモード](/developer-docs/feature-experimentation/get-started/hybrid-experimentation#linking-feature-experiments-with-front-end-tracking-code) で使用している場合、[Simulation Panel](/user-manual/experimentation/feature-experimentation/using-the-rollout-planner/validation-and-rollback/using-simulation-mode) を使用してバリアントの表示をシミュレートするときに、クッキーが自動的に作成されます。
* **手動:** `kameleoonSimulationFFData` クッキーを手動で設定します。
**シミュレートされた** バリエーションと **[強制](#setforcedvariation)** バリエーションを区別することが重要です:
* **シミュレートされたバリエーション**: 全体的な **フィーチャーフラグ** の結果に影響します。
* **強制バリエーション**: 個別の実験に固有です。
⚙️ **手動セットアップ**
`kameleoonSimulationFFData` クッキーが次の形式に従っていることを確認してください:
* `kameleoonSimulationFFData={"featureKey":{"expId":10,"varId":20}}`: 指定された `featureKey` に対して、実験 `expId` の `varId` のバリエーションをシミュレートします。
* `kameleoonSimulationFFData={"featureKey":{"expId":0}}`: 指定された `featureKey` に対するデフォルトのバリエーション (本番の **Then, for everyone else in Production, serve** セクションで定義) をシミュレートします。
⚠️ 正しく機能させるために、クッキー値は [`encodeURIComponent`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/encodeURIComponent) などの方法を使用して URI コンポーネントとしてエンコードする必要があります。
```java theme={null}
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
String visitorCode = kameleoonClient.getVisitorCode(httpServletRequest, httpServletResponse);
String visitorCode = kameleoonClient.getVisitorCode(httpServletRequest, httpServletResponse, defaultVisitorCode);
```
##### 引数
| 名前 | 型 | 説明 |
| ------------------- | --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| httpServletRequest | `HttpServletRequest` | 現在の HttpServletRequest オブジェクトを最初のパラメータとして渡す必要があります。このフィールドは必須です。 |
| httpServletResponse | `HttpServletResponse` | 現在の HttpServletResponse オブジェクトを 2 番目のパラメータとして渡す必要があります。このフィールドは必須です。 |
| defaultVisitorCode | `String` | 既存の `kameleoonVisitorCode` クッキーがリクエストで見つからない場合、このパラメータが `visitorCode` として使用されます。このフィールドはオプションです。指定されていない場合、既存の `kameleoonVisitorCode` クッキーがない場合、SDK はランダムな `visitorCode` を生成します。 |
##### 戻り値
| 型 | 説明 |
| -------- | ---------------------------------------------------- |
| `String` | この特定のユーザーに関連付けられ、SDK のほとんどのメソッドで使用される `visitorCode`。 |
#### addData()
`addData()` メソッドは、現在の訪問者をターゲットにするかどうかを他のメソッドが決定する際に使用できるように、[ターゲティングデータ](#data-types) をストレージに追加します。
`addData()` メソッドは値を返さず、それ自体では Kameleoon バックエンドサーバーとやり取りしません。代わりに、宣言されたすべてのデータは、[`flush()`](#flush) メソッドを使用した将来の送信のために保存されます。このアプローチにより、データは通常、`flush()` によってトリガーされる単一のサーバー呼び出しにグループ化されるため、サーバー呼び出しの数が減少します。
[`trackConversion()`](#trackconversion) メソッドも、`flush()` と同様に、以前に関連付けられたデータを送信します。実験ルールがトリガーされた場合の [`getVariation()`](#getvariation) と [`getVariations()`](#getvariations) メソッドにも同じことが言えます。
ほとんどのデータタイプでは、各訪問者は関連付けられたデータのインスタンスを 1 つしか持つことができません。ただし、[`CustomData`](#customdata) は例外です。訪問者は、インデックスごとに 1 つの関連付けられた `CustomData` インスタンスを持つことができます。
```java theme={null}
// Add a single data item (tracked by default)
kameleoonClient.addData(visitorCode, Browser.chrome());
// Add multiple data items (tracked by default)
kameleoonClient.addData(visitorCode, new PageView("https://url.com", "title"), new UserAgent("UserAgent"));
// Add multiple data items stored locally for targeting only (not sent to the Kameleoon Data API)
kameleoonClient.addData(visitorCode, false, new PageView("https://url.com", "title"), new UserAgent("UserAgent"));
```
##### 引数
| 名前 | 型 | 説明 | デフォルト値 |
| ------------------ | --------- | ------------------------------------------------------------------------------------------------------------- | ------ |
| visitorCode (*必須*) | `String` | 訪問者の一意の識別子。 | |
| track (*オプション*) | `boolean` | 追加されたデータがトラッキングの対象であるかどうかを指定します。`false` に設定すると、データはローカルに保存され、ターゲティング評価にのみ使用されます。Kameleoon Data API には送信されません。 | `true` |
| data (*必須*) | `Data...` | Kameleoon データタイプのコレクション。 | |
##### 例外
| 型 | 説明 |
| -------------------- | ---------------------------------------------- |
| `VisitorCodeInvalid` | 提供された訪問者コードが有効ではないことを示す例外。空であるか、255 文字を超えています。 |
#### flush()
* *📨 Kameleoon にトラッキングデータを送信します*
`flush()` メソッドは、訪問者にリンクされた Kameleoon データを収集します。次に、`addData` メソッドを使用して追加されたが、[これらのメソッド](/developer-docs/feature-experimentation/technical-reference/faq-global#when-does-the-sdk-send-a-tracking-request-for-analytics) のいずれかを使用してまだ送信されていないすべてのデータと共に、トラッキングリクエストを送信します。`flush()` はサーバー呼び出しが非同期で行われるため、非ブロッキングです。
`flush` を使用すると、特定の `visitorCode` に関連付けられたデータがサーバーに送信されるタイミングを制御できます。たとえば、`addData()` を 12 回呼び出した場合、`addData()` が呼び出されるたびにサーバーにデータを送信するのは非効率的です。そのため、`flush()` を 1 回呼び出すだけで済みます。
`visitorCode` を指定すると、`flush()` メソッドはこのコードを一意の訪問者識別子として使用します。これは [クロスデバイス実験](/developer-docs/cross-device-experimentation) に役立ちます。`visitorCode` を指定して `isUniqueIdentifier` パラメータを `true` に設定すると、SDK はフラッシュされたデータを指定された識別子に関連付けられた訪問者にリンクします。
パラメータ `isUniqueIdentifier` は非推奨です。代わりに [`UniqueIdentifier`](#uniqueidentifier) を使用してください。
`isUniqueIdentifier` は特殊な状況で役立ちます。たとえば、訪問者に付与された匿名の `visitorCode` にアクセスできないが、セッション統合を通じてその訪問者にリンクされている内部 ID を使用できる場合などです。
```java theme={null}
try {
kameleoonClient.flush(visitorCode); // Interval tracking (most performant tracking method)
kameleoonClient.flush(true, visitorCode); // Instant tracking
} catch (VisitorCodeInvalid e) {
// Catch exception
}
```
##### 引数
| 名前 | 型 | 説明 |
| ------------------------ | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| instant | `boolean` | データを即座に送信するか (`true`)、SDK パラメータ [`tracking_interval_millisecond`](#additional-configuration) で設定されたデフォルトのトラッキング間隔に従って送信するか (`false`) を示すブール値フラグ。このフィールドはオプションです。 |
| visitorCode | `String` | ユーザーの一意の識別子。このフィールドは必須です。 |
| isUniqueIdentifier (非推奨) | `boolean` | visitorCode が一意の識別子であるかどうかを指定するためのオプションのパラメータ。訪問者に `isUniqueIdentifier` を適用するには、`visitorCode` を提供し、`null` ではない必要があります。そうでない場合、無視されます。指定されていない場合、デフォルト値は `false` です。このフィールドはオプションです。 |
#### getRemoteData()
このメソッドは以前 `retrieveDataFromRemoteSource` と呼ばれており、SDK バージョン `4.0.0` で削除されました。
`getRemoteData()` メソッドを使用すると、Kameleoon サーバーに保存された指定された `siteCode` に対して、引数として渡された `key` に従ってデータを取得できます。サイトコードは `KameleoonClientFactory.create()` で指定します。通常、データは Data API を使用してリモートサーバーに保存されます。このメソッドは、スケーラブルなサーバーが利用可能であることと併せて、後でアプリで取得できる追加データを保存するための便利な方法を提供します。
```java theme={null}
CompletableFuture data = kameleoonClient.getRemoteData("key");
try {
JsonObject test = kameleoonClient.getRemoteData("key").get(5_000, TimeUnit.MILLISECONDS);
} catch (InterruptedException | ExecutionException | TimeoutException e) {
// Catch exception
}
```
##### 引数
| 名前 | 型 | 説明 |
| --- | -------- | ---------------------------------- |
| key | `String` | 取得されたデータに関連付けられているキー。このフィールドは必須です。 |
##### 戻り値
| 型 | 説明 |
| ------------------------------- | ----------------------------------------------- |
| `CompletableFuture` | 特定の **key** に対するデータの取得に関連付けられた将来の `JsonObject`。 |
#### getRemoteVisitorData()
`getRemoteVisitorData()` は、Kameleoon Data API から `visitorCode` の Kameleoon 訪問データを取得するための非同期メソッドです。このメソッドは、ターゲティングの決定を行う際に他のメソッドが使用できるように、データをストレージに追加します。
このメソッドを使用して取得したデータは、次のような場合に重要な役割を果たします:
* 他のデバイスから収集されたデータを使用する。
* 過去の訪問中に訪問されたページなど、ユーザーの履歴にアクセスする。
* データレイヤー変数やフロントエンドでコンバージョンするゴールなど、クライアントサイドでのみアクセス可能なデータを使用する。
ユースケースをより良く理解するには、[この記事](/developer-docs/feature-experimentation/targeting-and-segmentation/native-segmentation) を読んでください。
デフォルトでは、`getRemoteVisitorData()` は `scope=Visitor` を持つ最新の保存されたカスタムデータを自動的に取得し、`addData()` メソッドを呼び出すことなく訪問者にアタッチします。これは、[複数のデバイス間でカスタムデータを同期する](/developer-docs/sdks/web-sdks/nodejs-sdk#synchronizing-custom-data-across-devices) ために特に役立ちます。
パラメータ `isUniqueIdentifier` は非推奨です。代わりに [`UniqueIdentifier`](#uniqueidentifier) を使用してください。
`isUniqueIdentifier` は特殊な状況で役立ちます。たとえば、訪問者に付与された匿名の `visitorCode` にアクセスできないが、セッション統合を通じてその訪問者にリンクされている内部 ID を使用できる場合などです。
```java theme={null}
String visitorCode = "visitorCode";
// Visitor data will be fetched and automatically added for `visitorCode`
CompletableFuture> visitorData = kameleoonClient.getRemoteVisitorData(visitorCode);
// If you only want to fetch data and add it yourself manually, set addData == `false`
CompletableFuture> visitorData = kameleoonClient.getRemoteVisitorData(visitorCode, false);
// If you want to fetch custom list of data types
RemoteVisitorDataFilter filter = RemoteVisitorDataFilter.builder()
.previousVisitAmount(25)
.customData(false)
.conversions(true)
.build();
CompletableFuture> visitorData = kameleoonClient.getRemoteVisitorData(visitorCode, filter, true, false);
try {
List visitorData = kameleoonClient.getRemoteVisitorData(visitorCode).get(5_000, TimeUnit.MILLISECONDS);
// Your custom code
} catch (CancellationException | InterruptedException | ExecutionException | TimeoutException e) {
// Catch exception
}
```
##### 引数
| 名前 | 型 | 説明 |
| ------------------------ | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| visitorCode | string | 取得したいデータの訪問者コード。このフィールドは必須です。 |
| filter | `RemoteVisitorDataFilter` | 訪問から取得すべきデータを指定するためのフィルター。デフォルトでは、`CustomData` のみが現在および最新の前回訪問から取得されます (`RemoteVisitorDataFilter.builder().build()` または `new RemoteVisitorDataFilter()`)。他のフィルターパラメータは `false` に設定されます。このフィールドはオプションです。 |
| addData | `boolean` | メソッドが訪問者のために取得したデータを自動的に追加するかどうかを示すブール値。このフィールドはオプションです。 |
| isUniqueIdentifier (非推奨) | `boolean` | `visitorCode` が一意の識別子であるかどうかを指定するためのオプションのパラメータ。指定されていない場合、デフォルト値は `false` です。このフィールドはオプションです。 |
##### 戻り値
| 型 | 説明 |
| ------------------------------- | ------------------------------- |
| `CompletableFuture>` | 特定の訪問者に関連付けられた将来の `List`。 |
##### getRemoteVisitorData() でのパラメータの使用
`getRemoteVisitorData()` メソッドは、訪問者に関するデータを取得するときにさまざまなパラメータを定義できる柔軟性を提供します。ゴール、実験、バリエーションに基づいてターゲティングする場合でも、同じアプローチがすべてのデータタイプに適用されます。
たとえば、ゴール「Order transaction」を完了した訪問者に関するデータを取得したいとします。`getVisitorData()` メソッド内でパラメータを指定して、ターゲティングを絞り込めます。たとえば、最後の 5 回の訪問でゴールでコンバージョンしたユーザーのみをターゲットにしたい場合は、`previousVisitAmount` パラメータを 5 に、`conversions` を true に設定できます。
この例で示される柔軟性は、ゴールデータに限定されません。`getRemoteVisitorData()` メソッド内でパラメータを使用して、さまざまな訪問者行動に関するデータを取得できます。
利用可能な `kameleoon.types.RemoteVisitorDataFilter` オプションのリストは以下のとおりです:
| 名前 | 型 | 説明 | デフォルト |
| ----------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------- |
| previousVisitAmount (*オプション*) | `int` | データを取得する前回の訪問数。`1` ～ `25` の数値 | `1` |
| currentVisit (*オプション*) | `boolean` | true の場合、現在の訪問データが取得されます | `true` |
| customData (*オプション*) | `boolean` | true の場合、カスタムデータが取得されます。 | `true` |
| pageViews (*オプション*) | `boolean` | true の場合、ページデータが取得されます。 | `false` |
| geolocation (*オプション*) | `boolean` | true の場合、ジオロケーションデータが取得されます。 | `false` |
| device (*オプション*) | `boolean` | true の場合、デバイスデータが取得されます。 | `false` |
| browser (*オプション*) | `boolean` | true の場合、ブラウザーデータが取得されます。 | `false` |
| operatingSystem (*オプション*) | `boolean` | true の場合、オペレーティングシステムデータが取得されます。 | `false` |
| conversions (*オプション*) | `boolean` | true の場合、コンバージョンデータが取得されます。 | `false` |
| experiments (*オプション*) | `boolean` | true の場合、実験データが取得されます。 | `false` |
| kcs (*オプション*) | `boolean` | true の場合、Kameleoon Conversion Score (KCS) が取得されます。[AI Predictive Targeting アドオン](/user-manual/ai-predictive-targeting/target-users-based-on-likelihood-to-convert) が必要です | `false` |
| visitorCode (*オプション*) | `boolean` | true の場合、Kameleoon は最新の訪問から `visitorCode` を取得し、現在の訪問でそれを使用します。これは、[クロスデバイス実験](/developer-docs/cross-device-experimentation) のために、`visitorCode` で識別される訪問者が常に訪問にわたって同じバリエーションを受け取ることを保証したい場合に必要です。 | `true` |
| personalization (*オプション*) | `boolean` | true の場合、パーソナライゼーションデータが取得されます。これは、パーソナライゼーション条件に必要です。 | `false` |
| cbs (*オプション*) | `boolean` | true の場合、Contextual Bandit スコアデータが取得されます。 | `false` |
#### getVisitorWarehouseAudience()
このメソッドは、指定された `visitorCode` と `warehouseKey` を使用して、データウェアハウス内で訪問者に関連付けられたすべてのオーディエンスデータを取得します。`warehouseKey` は通常、内部ユーザー ID です。`customDataIndex` パラメータは、Kameleoon が訪問者をターゲットにするために使用する Kameleoon カスタムデータに対応します。詳細については、[ウェアハウスターゲティングドキュメント](/user-manual/integrations/data-warehouses/bigquery/use-bigquery-as-a-source-audience-targeting) を参照してください。メソッドは結果を `CustomData` オブジェクトとして返される future に渡し、データが訪問者に追加され、ターゲティングの目的で利用可能であることを確認します。
```java theme={null}
CompletableFuture warehouseAudienceDataCF =
kameleoonClient.getVisitorWarehouseAudience(visitorCode, warehouseKeyValue, customDataIndex);
// If you need to specify warehouse key
CompletableFuture warehouseAudienceDataCF =
kameleoonClient.getVisitorWarehouseAudience(visitorCode, customDataIndex);
try {
CustomData warehouseAudienceData = warehouseAudienceDataCF.get(5_000, TimeUnit.MILLISECONDS);
// Your custom code
} catch (CancellationException | InterruptedException | ExecutionException | TimeoutException e) {
// Catch exception
}
```
##### 引数
| 名前 | 型 | 説明 |
| --------------- | -------- | ------------------------------------------------------ |
| visitorCode | `String` | データを取得して追加したい訪問者の一意の識別子。 |
| warehouseKey | `String` | ウェアハウスデータを識別するための一意のキー (通常、内部ユーザー ID)。このフィールドはオプションです。 |
| customDataIndex | `int` | BigQuery オーディエンスをターゲットにするために使用するカスタムデータのインデックスを表す整数。 |
##### 戻り値
| 型 | 説明 |
| ------------------------------- | -------------------------------------------- |
| `CompletableFuture` | データが訪問者に追加されたことを確認する将来の `CustomData` インスタンス。 |
##### スローされる例外
| 型 | 説明 |
| -------------------- | ------------------------------------------------ |
| `VisitorCodeInvalid` | 提供された訪問者コードが有効ではないことを示す例外 (空であるか、255 文字を超えています)。 |
#### setLegalConsent()
このメソッドを使用して、訪問者が個人データの使用に対して法的同意を与えたかどうかを指定する必要があります。`legalConsent` パラメータを `false` に設定すると、トラッキングリクエストに含めることができるデータタイプが制限されます。このメソッドは、訪問者データを責任を持って管理しながら、法律および規制要件を遵守するのに役立ちます。個人データに関する詳細は、[同意管理ポリシー](/user-manual/project-management/consent-management-policy) をご覧ください。
```java theme={null}
// if you do not need to set the visitor code in a cookie to respond
kameleoonClient.setLegalConsent(visitorCode, true);
String visitorCode = kameleoonClient.getVisitorCode(httpServletRequest, httpServletResponse);
kameleoonClient.setLegalConsent(visitorCode, true, httpServletResponse);
```
##### 引数
| 名前 | 型 | 説明 |
| ------------ | ------------------- | ----------------------------------------------------------------------------------------------------- |
| visitorCode | `String` | ユーザーの一意の識別子。このフィールドは必須です。 |
| legalConsent | `boolean` | 法的同意のステータスを表すブール値。`true` は訪問者が法的同意を与えたことを示し、`false` は訪問者が法的同意を提供したことがない、または取り消したことを示します。このフィールドは必須です。 |
| response | HttpServletResponse | 法的同意ステータスに基づいてクッキー内の値が調整される HTTP サーブレットレスポンス。このフィールドはオプションです。 |
##### スローされる例外
| 型 | 説明 |
| ------------------------------------- | --------------------------------------------- |
| KameleoonException.VisitorCodeInvalid | 提供された訪問者コードが無効であることを示す例外。空であるか、255 文字を超えています。 |
##### 同意取り消しの動作
`legalConsent=false` を指定して `setLegalConsent()` を呼び出した場合、SDK は `kameleoonVisitorCode` クッキーを削除しません。代わりに、クッキーの有効期限を延長しなくなるため、クッキーは自然に期限が切れるまで持続します。
コンプライアンス要件としてオプトアウト時にクッキーファイルを直ちに削除することが必要な場合は、フレームワークのネイティブクッキー管理メソッドを使用して手動で削除する必要があります。SDK は自動的にファイルを削除しません。
### ゴールとサードパーティ分析
#### trackConversion()
* 📨 *Kameleoon にトラッキングデータを送信します*
このメソッドを使用して、特定の [ゴール](/user-manual//assets/goals/create-a-goal) とユーザーのコンバージョンをトラッキングします。このメソッドには `visitorCode` と `goalId` が必要です。さらに、このメソッドはオプションの `revenue`、`negative`、`metadata` 引数も受け取ります。`visitorCode` は通常、実験をトリガーする際に使用したものと同一です。
`trackConversion()` メソッドは値を返しません。このメソッドは、サーバー呼び出しが非同期で行われるため、非ブロッキングです。
パラメータ `isUniqueIdentifier` は非推奨です。代わりに [`UniqueIdentifier`](#uniqueidentifier) を使用してください。
`isUniqueIdentifier` は他のエッジケースのシナリオでも有用です。たとえば、もともと訪問者に割り当てられた匿名の `visitorCode` にアクセスできないが、セッション統合機能を使用して匿名訪問者に接続された内部 ID にアクセスできる場合などです。
```java theme={null}
String visitorCode = kameleoonClient.getVisitorCode(httpServletRequest, httpServletResponse);
int goalId = 83023;
kameleoonClient.trackConversion(visitorCode, goalId);
// Add metadata
CustomData cd = new CustomData(1, "metadata");
kameleoonClient.trackConversion(visitorCode, goalId, cd);
```
##### 引数
| 名前 | 型 | 説明 | デフォルト |
| -------------------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------- |
| visitorCode (*必須*) | `String` | 訪問者の一意の識別子。 | |
| goalId (*必須*) | `int` | ゴールの ID。 | |
| revenue (*オプション*) | `float` | コンバージョンの収益。 | `0` |
| negative (*オプション*) | `boolean` | 収益が正か負かを定義します。 | `false` |
| metadata (*オプション*) | `CustomData...` | Kameleoon アプリでゴールのメタデータとして定義されているカスタムデータに特定の値を設定できます。例: `[CustomData{id: 5, value: "Payment Type"}, CustomData{id: 6, value: "Delivery Method"}]`。この例では、`5` と `9` はカスタムデータのインデックスです (5 = 「Payment Type」、9 = 「Delivery Method」)。 | `new CustomData[0]` |
| isUniqueIdentifier *(非推奨)* | `boolean` | visitorCode が一意の識別子であるかどうかを指定するためのオプションのパラメータ。 | `false` |
メタデータ値は、[生データエクスポート](/user-manual/experiment-analytics/analyze-results/results-page/results-page-actions#Export) および [結果ページ](/user-manual/experiment-analytics/analyze-results/data-and-metrics/goal-metadata) を介してアクセスできます。
`metadata` パラメータが提供されている場合、Kameleoon はこれらの指定された値を現在のコンバージョンに使用し、[`addData()`](#adddata) メソッドを使用して以前に収集されたものに代わります。パラメータが省略されている場合、Kameleoon はコンバージョン前および同じ訪問内で、それらの [`CustomData`](#customdata) のために最後にトラッキングされた値を使用します。
Kameleoon は、`trackConversion()` メソッドのパラメータとして明示的に渡されたメタデータ値のみを考慮します。
以下の例では、Kameleoon は、パラメータとして明示的に提供されたカスタムデータ値 (ここでは: 値が 'Amex Credit Card' のインデックス 5) のみとコンバージョンを関連付けます。
```java theme={null}
kameleoonClient.addData(visitorCode, new CustomData(5, "Credit Card"), new CustomData(9, "Express Delivery"));
kameleoonClient.trackConversion(visitorCode, 1000, new CustomData(5, "Amex Credit Card"));
```
##### 例外
| 型 | 説明 |
| -------------------- | ---------------------------------------------- |
| `VisitorCodeInvalid` | 提供された訪問者コードが有効ではないことを示す例外。空であるか、255 文字を超えています。 |
#### getEngineTrackingCode()
Kameleoon は、Mixpanel、Google Analytics 4、Segment などのいくつかの分析ソリューションと統合されています。サーバーサイド実験を正しくトラッキングするには、訪問者が実験をトリガーした後に `getEngineTrackingCode()` メソッドを呼び出します。SDK は、訪問者が前の 5 秒間にトリガーした実験の JavaScript キューコマンドを返します。このコードをページに挿入すると、Engine.js はコマンドを処理し、アクティブな分析統合を介して露出イベントを送信します。
このメソッドの実装に関する詳細については、[ハイブリッド実験](/developer-docs/feature-experimentation/get-started/hybrid-experimentation) を参照してください。
```java theme={null}
String engineTrackingCode = kameleoonClient.getEngineTrackingCode(visitorCode);
```
* この機能を使用するには、Java SDK と Kameleoon [Engine.js](/developer-docs/web-experimentation/implementation-and-deployment/standard-implementation) の両方を実装します。このフローでは Engine.js はトラッキングにのみ使用されるため、終了 `` タグの前に非同期タグをインストールできます。
* Kameleoon でのみ実験をトラッキングしたく、サードパーティ分析ツールに露出イベントを送信する必要がない場合は、[JavaScript / TypeScript SDK](/developer-docs/sdks/web-sdks/js-sdk) を使用してください。このオプションは [サーバーレスエッジコンピュートプラットフォーム](/developer-docs/feature-experimentation/implementation-and-deployment/serverless-edge-compute-starter-kits) に適しています。JavaScript / TypeScript SDK は、対応する実験割り当てを `window.kameleoonQueue` に追加していれば、[`getVisitorCode`](/developer-docs/sdks/web-sdks/js-sdk#getvisitorcode) を呼び出すときにバリエーションを自動的にトラッキングします。
* 返されたトラッキングコードを HTML `