> ## 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.
# PHP SDK
> Kameleoon PHP SDK を統合して、PHP バックエンドサーバーで実験を実行し、機能フラグを有効化します。オプションで cron ジョブによるトラッキングにも対応しています。
PHP SDK を使用すると、バックエンド PHP サーバー上で実験を実行し、機能フラグを有効化できます。SDK を Web アプリケーションに統合するのは簡単で、メモリやネットワーク使用量などのフットプリントも小さく抑えられています。
**はじめに**: 始め方については [開発者ガイド](#開発者ガイド) を参照してください。
**変更履歴**: PHP SDK の最新バージョン: 4.23.0 [変更履歴](https://github.com/Kameleoon/client-php/blob/master/CHANGELOG.md)。
**SDK メソッド**: PHP SDK の完全なリファレンスドキュメントは [リファレンス](#リファレンス) セクションを参照してください。
## 開発者ガイド
このガイドは、SDK をアプリケーションコードに統合するための手引きです。
### はじめに
まず SDK をインストールする必要があります。解凍すると、**kameleoon/** と **job/** の2つのディレクトリが表示されます。
#### PHP クライアントのインストール(Composer パッケージ)
[cron ジョブのインストール](#installing-the-cron-job) および [cron ジョブを使用しない PHP SDK の使用方法](#using-the-php-sdk-without-a-cron-job) のセクションを必ずお読みください。
インストールパッケージは [Packagist](https://packagist.org/packages/kameleoon/kameleoon-client-php) で入手できます。Composer を使って依存関係として追加することで、PHP SDK をインストールできます:
```json title="composer.json" theme={null}
{
"require": {
"kameleoon/kameleoon-client-php": "^4.18.0"
}
}
```
最後に、以下のコマンドを実行してオートローダーを再生成します:
```bash theme={null}
composer install
```
#### cron ジョブを使用する(推奨)
cron を設定すると、PHP SDK の [addData()](#adddata) メソッドで追加されたデータのトラッキングが可能になります。ただし、cron をインストールできない場合は、[こちらのガイド](#without-a-cron-job) に従って、フロントエンドでのトラッキングを実装することもできます。
**job/** ディレクトリには、標準的なジョブスケジューラ(cron など)を介して実行する必要があるジョブが含まれています。
スクリプトは `/usr/local/opt/kameleoon/kameleoon-client-php-process-queries.sh` にインストールし、デフォルトで提供されている crontab エントリを使用することを推奨します。ただし、別の場所にインストールし、それに応じて crontab エントリを変更することもできます。
##### cron ジョブを使用しない場合
cron ジョブをインストールできない場合は、Kameleoon を [ハイブリッドモード](/developer-docs/feature-experimentation/get-started/hybrid-experimentation) で使用することで、Kameleoon Application Engine の `engine.js`(以前の名称は `kameleoon.js`)のトラッキング機能を利用できます。SDK は [`getEngineTrackingCode()`](#getenginetrackingcode) メソッドを提供しており、これにより Web サイトで使用している Kameleoon やその他の分析ソリューションに露出イベントを送信できます。
このアプローチでは、PHP SDK の [addData()](#adddata) メソッドで追加されたデータを**トラッキングできません**。
言い換えれば、PHP SDK がサーバーサイドで実験データを収集・処理する**唯一**の方法は **cron ジョブ**を使うことです。
ハイブリッドモードはトラッキング目的には有用ですが、**バックエンドでのデータ収集は有効にしません**。
#### 追加の設定
PHP SDK の動作は、設定ファイルを介してカスタマイズできます。SDK アーカイブには `client-php.json.sample` という名前のサンプル設定ファイルが含まれています。[サンプル設定ファイルをダウンロード](/assets/developer-docs/sdks/web-sdks/client-configs/client-php.json) することもできます。このファイルはデフォルトのパス `/tmp/kameleoon/client-php.json` にインストールすることを推奨します。設定可能なプロパティは以下のとおりです:
| キー | 説明 | デフォルト値 |
| --------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------- |
| `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) のドキュメントを参照してください。 | |
| `kameleoonWorkDir` / `kameleoon_work_dir` (*オプション*) | PHP クライアントの作業ディレクトリ(このディレクトリにファイルを作成します)を指定します。このディレクトリは PHP ユーザーによって書き込み可能である必要があります。 | `/tmp/kameleoon/client-php/` |
| `refreshIntervalMinute` / `refresh_interval_minute` (*オプション*) | SDK がアクティブな実験と機能フラグの設定を取得する間隔(分単位)を指定します。この値によって、機能フラグの有効化/無効化や実験の開始などの変更が本番サーバーに反映されるまでの最大時間が決まります。 | `60` 分 |
| `defaultTimeoutMillisecond` / `default_timeout_millisecond` (*オプション*) | SDK からのネットワークリクエストのタイムアウト(ミリ秒単位)を指定します。安定した接続がない場合は、`30` 秒以上に設定してください。一部のメソッドでは追加のパラメータでデフォルトのタイムアウトを上書きできます。明示的に指定しない場合、SDK はこのデフォルト値を使用します。 | `10000` ミリ秒 |
| `cookieOptions->topLevelDomain` / `cookie_options.domain` *(ハイブリッドモードでは必須)* | Web サイトの現在のトップレベルドメイン。形式: `example.com` を使用してください。`https://`、`www`、その他のサブドメインは含めないでください。Kameleoon はこの情報を使用してトップレベルドメインに対応する cookie を設定します。 | `null` |
| `cookieOptions->secure` / `cookie_options.secure` (*オプション*) | **Secure** cookie 属性を制御します。 | `false` |
| `cookieOptions->httpOnly` / `cookie_options.http_only` (*オプション*) | **HttpOnly** cookie 属性を制御します。 | `false` |
| `cookieOptions->sameSite` / `cookie_options.samesite` (*オプション*) | **SameSite** cookie 属性を制御します。 | `Lax` |
| `environment` / `environment` (*オプション*) | 機能フラグの設定の使用元となる環境。値は `production`、`staging`、`development` のいずれかです。詳細は [環境の管理](/user-manual/experimentation/feature-experimentation/configure-your-feature-flags/manage-environments) の記事を参照してください。 | `production` |
| `networkDomain` / `network_domain` (*オプション*) | SDK が送信リクエストに使用するカスタムドメイン。プロキシ用途でよく使用されます。有効なドメインである必要があります(例: example.com または sub.example.com)。無効な形式の場合は Kameleoon の値がデフォルトとなります。 | `null` |
| `requestBodySizeLimitBytes` / `request_body_size_limit_bytes` *(オプション)* | トラッキングパッケージのサイズ(バイト単位)を制限します。これは cron ジョブの実行間で収集されたデータを保存するファイルです。サーバーやネットワークの制限により、パッケージサイズを縮小することが必要な場合があります。許可される最大値は 2.5 MB(`2621440` バイト)です。 | `2621440` |
| `debugMode` / `debug_mode` *(非推奨)* | このパラメータは、問題の分析を支援するためにトラッキングサーバーに追加情報を送信します。通常はオフ(**false**)にしておく必要がありますが、オン(**true**)にしても SDK のパフォーマンスには影響しません。このフィールドは非推奨であり、SDK バージョン `5.0.0` で削除されます。代わりに [`KameleoonLogger::setLogLevel`](#ログレベル) を使用してください。 | `false` |
設定ファイルにデフォルトのパス(`/tmp/kameleoon/client-php.json`)を使用しない場合は、以下が必要です:
* 設定ファイルのパスを `KameleoonClientFactory::create()` メソッドの第3引数として渡す;
* ジョブスクリプトに --conf 引数を追加するように crontab エントリを変更する(例えば、`bash /usr/local/opt/bin/kameleoon-client-php-process-queries.sh --conf /my/path/kameleoon.json` のようになります)。
`client_id` と `client_secret` の詳細、およびそれらの取得方法については、[API クレデンシャル](/user-manual/account-and-team-management/users-and-teams/api-credentials) の記事を参照してください。Kameleoon PHP SDK は Automation API を使用しており、OAuth 2.0 クライアントクレデンシャルフローに従います。
#### Kameleoon クライアントの初期化
アプリケーションに SDK をインストールし、正しいクレデンシャル(`/tmp/kameleoon/client-php.json` 内)を設定したら、次のステップはアプリケーションコード内で Kameleoon クライアントを作成することです。例:
```php theme={null}
require "vendor/autoload.php";
use Kameleoon\KameleoonClientConfig;
use Kameleoon\KameleoonClientFactory;
use Kameleoon\Exception\ConfigCredentialsInvalid;
use Kameleoon\Exception\KameleoonException;
use Kameleoon\Exception\SiteCodeIsEmpty;
$siteCode = "a8st4f59bj";
try {
// Read from default configuration path: "/tmp/kameleoon/php-client/"
$kameleoonClient = KameleoonClientFactory::create($siteCode);
} catch (SiteCodeIsEmpty $ex) {
// indicates that provided site code is empty
} catch (ConfigCredentialsInvalid $ex) {
// indicates that provided clientId / clientSecret are not valid
} catch (KameleoonException $ex) {
// probably indicates that the SDK is unable to access the **Kameleoon working directory**
}
try {
$kameleoonClient = KameleoonClientFactory::create($siteCode, "custom/file/path/client-php.json");
} catch (SiteCodeIsEmpty $ex) {
// indicates that provided site code is empty
} catch (ConfigCredentialsInvalid $ex) {
// indicates that provided clientId / clientSecret are not valid
} catch (KameleoonException $ex) {
// probably indicates that the SDK is unable to access the **Kameleoon working directory**
}
try {
$cookieOptions = KameleoonClientConfig::createCookieOptions(
"example.com", // domain: optional, but strictly recommended
false, // secure: optional (false by default)
false, // httponly: optional (false by default)
"Lax" // samesite: optional (Lax by default)
);
$config = new KameleoonClientConfig(
"", // clientId: mandatory
"", // clientSecret: mandatory
"/tmp/kameleoon/php-client/", // kameleoonWorkDir: optional / ("/tmp/kameleoon/php-client/" by default)
60, // refreshIntervalMinute: in minutes, optional (60 minutes by default)
10_000, // defaultTimeoutMillisecond: in milliseconds, optional (10_000 ms by default)
false, // debugMode: optional (false by default)
$cookieOptions, // cookieOptions: optional
"development", // environment: optional ("production" by default)
"example.com", // networkDomain: optional (null by default)
1024*1024, // requestBodySizeLimitBytes: optional (2560 * 1024 by default)
);
$kameleoonClient = KameleoonClientFactory::createWithConfig($siteCode, $config);
} catch (SiteCodeIsEmpty $ex) {
// indicates that provided site code is empty
} catch (ConfigCredentialsInvalid $ex) {
// indicates that provided clientId / clientSecret are not valid
} catch (KameleoonException $ex) {
// probably indicates that the SDK is unable to access the **Kameleoon working directory**
}
```
KameleoonClient は、アプリケーションと Kameleoon プラットフォームの橋渡しをするシングルトンオブジェクトです。実験を実行するために必要なすべてのメソッドとプロパティが含まれています。SDK は [設定ファイル](#追加の設定) から設定を取得することに注意してください。デフォルトではパス `/tmp/kameleoon/client-php.json` が使用されますが、`KameleoonClientFactory::create()` メソッドにオプションの第3引数を指定することで、別のパスを設定ファイルに使用できます。
Kameleoon を介した A/B テストのコンテキストで、アプリケーションコード内で正しいロジックを使用するのはアプリケーション開発者の責任です。良い慣行は、実験がまだ開始されていないために現在の訪問者が実験から除外される可能性があると常に想定することです。現在の訪問者を除外するのは簡単で、デフォルト/参照バリエーションのロジックを実装することに対応します。次の段落のコードサンプルは、このようなアプローチの例を示しています。
#### 機能フラグの有効化
##### ユーザーに一意の ID を割り当てる
ユーザーに一意の ID を割り当てるには、[`getVisitorCode()`](#getvisitorcode) メソッドを使用できます。**訪問者コード**が存在しない場合(リクエストヘッダーの cookie から)、メソッドはランダムな一意の ID を生成するか、あなたが生成した `defaultVisitorCode` を使用します。ID はレスポンスヘッダーの cookie に設定されます。
Kameleoon を [ハイブリッドモード](/developer-docs/feature-experimentation/get-started/hybrid-experimentation) で使用している場合、`getVisitorCode()` メソッドを呼び出すことで、一意の ID(**訪問者コード**)がアプリケーションファイル `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 は次のトラッキングリクエストの際に指定された実験に露出イベントを送信します。これは cron ジョブによって自動的に実行されます。デフォルトでは、その間隔は 1 分です。
`getVariation()` メソッドでは、トラッキングを行うかどうかを制御できます。`track=false` の場合、SDK によって露出イベントが送信されません。これは、SDK 経由でデータをトラッキングするのではなく、例えば Kameleoon エンジンによって管理されるクライアントサイドのトラッキングに依存したい場合に便利です。また、`getVariations()` メソッドを使用する際にも、`track=false` を設定するのが便利です。すべてのフラグのバリエーションのみが必要で、トラッキングイベントを発生させる必要がない場合があります。トラッキングの仕組みについて詳しく知りたい場合は、[こちらの記事](/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 の [Custom Data 機能](#customdata) を使用できます。Custom Data を使用すると、実験に関連する特定の情報をキャプチャして分析できます。収集したデータを分析のために Kameleoon サーバーに送信するには、[`flush()`](#flush) メソッドの呼び出しを忘れないでください。
結果の正確性を保証するために、[`UserAgent`](#useragent) データタイプを使用してボットを除外することを推奨します。
##### 目標のコンバージョンをトラッキングする
ユーザーが希望するアクション(例えば購入など)を完了すると、それはコンバージョンとして記録されます。コンバージョンをトラッキングするには、[`trackConversion()`](#trackconversion) メソッドを使用し、必須の `visitorCode` と `goalId` パラメータを指定します。
コンバージョンのトラッキングリクエストは、SDK が定期的に送信する(インターバルトラッキング crontab で定義された)次の予定されたトラッキングリクエストとともに送信されます。リクエストを即座に送信したい場合は、`instant=true` パラメータを指定した [`flush()`](#flush) メソッドを使用します。
##### 分析ソリューションにイベントを送信する
コンバージョンをトラッキングし、顧客分析ソリューションに露出イベントを送信するには、まず Kameleoon を [ハイブリッドモード](/developer-docs/feature-experimentation/get-started/hybrid-experimentation/) で実装する必要があります。その後、[`getEngineTrackingCode()`](#getenginetrackingcode) メソッドを使用します。
`getEngineTrackingCode()` メソッドは、分析ソリューションに露出イベントを送信するために必要な一意のトラッキングコードを取得します。このメソッドを使用すると、イベントを記録し、目的の分析プラットフォームに送信できます。
### クロスデバイス実験
複数のデバイスからアプリにアクセスする訪問者をサポートするために、Kameleoon は、以前に収集された訪問者データを各デバイス間で同期し、クロスデバイス実験を通じてデバイス間の訪問履歴を統合することを可能にします。Kameleoon がデバイス間でデータをどのように扱うかに関するケーススタディや詳細情報は、[クロスデバイス実験に関する記事](/developer-docs/cross-device-experimentation) で確認できます。
#### デバイス間でのカスタムデータの同期
カスタムマッピングの同期は、デバイス間で訪問者データを揃えるために使用されますが、常に必要というわけではありません。以下に、カスタムマッピング同期が不要な2つのシナリオを示します:
**デバイス間で同じユーザー ID**
すべてのデバイスで同じユーザー ID が一貫して使用されている場合、同期はカスタムマッピング同期なしで自動的に処理されます。複数のデバイスで収集されたデータを同期したいときは、`getRemoteVisitorData()` メソッドを呼び出すだけで十分です。
**一貫した ID を持つマルチサーバーインスタンス**
複数のサーバー(例えば、分散サーバーインスタンス)を含む複雑なセットアップで、サーバー間で同じユーザー ID が利用可能な場合、追加のカスタムマッピング同期なしに、サーバー間の同期(`getRemoteVisitorData()` を使用)で十分です。
追加のデータが必要な顧客は、詳細なガイダンスのために [`getRemoteVisitorData()`](#getremotevisitordata) メソッドの説明を参照してください。以下のコードでは、正確なデータ取得のために、2つのデバイス間で同じ一意の識別子(この場合は `visitorCode`、`userId` とも呼ばれます)が一貫して使用されていると仮定しています。
収集されたデータをリアルタイムで同期したい場合は、カスタムデータのスコープに **Visitor** を選択する必要があります。
```php title="Device A" theme={null}
// In this example, Custom data with index `90` was set to "Visitor" scope on Kameleoon.
const VISITOR_SCOPE_CUSTOM_DATA_INDEX = 90;
$kameleoonClient->addData($visitorCode, new CustomData(VISITOR_SCOPE_CUSTOM_DATA_INDEX, "your data"));
$kameleoonClient->flush($visitorCode);
```
```php title="Device B" theme={null}
// Call the `getRemoteVisitorData` method before working with the data.
$kameleoonClient->getRemoteVisitorData($visitorCode);
// After the call, the SDK on Device B will have access to CustomData of Visitor scope defined on Device A.
// So, "your data" will be available to target and track the visitor.
```
#### セッションのマージにカスタムデータを使用する
[クロスデバイス実験](/developer-docs/cross-device-experimentation) を使用すると、訪問者の履歴を各デバイスにわたって統合できます(履歴の統合)。履歴の統合により、異なる訪問者セッションを1つにまとめることができます。訪問履歴を統合するには、訪問者の一意の識別子を提供するために [`CustomData`](#customdata) を使用します。詳細については、[専用のドキュメント](/developer-docs/cross-device-experimentation/#activating-cross-device-history-reconciliation) を参照してください。
クロスデバイスの統合が有効化された後、`userId` パラメータを指定して [`getRemoteVisitorData()`](#getremotevisitordata) を呼び出すと、指定されたユーザーの既知のすべてのデータが取得されます。
同じ識別子を持つセッションは、実験中に常に同じバリエーションが表示されます。実験結果ページの訪問者ビューでは、これらのセッションは1人の訪問者として表示されます。
SDK の設定により、関連付けられたセッションは常に実験の同じバリエーションを表示します。ただし、クロスデバイスのバリエーション割り当てに関しては、いくつかの制限があります。これらの制限については [こちら](/developer-docs/cross-device-experimentation#critical-points-and-practical-insights) で説明されています。
Kameleoon プラットフォームでカスタムデータをセットアップするには、[クロスデバイス履歴の統合を有効化する](#クロスデバイス実験) ガイドに従ってください。
その後、SDK を通常通り使用できます。セッションのマージのコンテキストで役立つ可能性のあるメソッドは以下のとおりです:
* `UniqueIdentifier(true)` を追加した `getRemoteVisitorData()` - リンクされたすべての訪問者のデータを取得します。
* `UniqueIdentifier(true)` データを追加した [`trackConversion()`](#trackconversion) または [`flush()`](#flush) - 他の訪問者と関連付けられた特定の訪問者の一部データをトラッキングします。
識別子として使用するカスタムデータは **Visitor スコープ** に設定する必要があるため、各デバイスで [`getRemoteVisitorData()`](#getremotevisitordata) メソッドを使用して識別子を取得するには、[クロスデバイスカスタムデータ同期](/developer-docs/cross-device-experimentation) を使用する必要があります。
セッションのマージにカスタムデータを使用する例は以下のとおりです。
```php theme={null}
// In this example, `91` represents the Custom Data's index
// configured as a unique identifier in Kameleoon.
const MAPPING_INDEX = 91;
const 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.
$anonymousVariation = $kameleoonClient->getVariation($anonymousVisitorCode, FEATURE_KEY);
// 2. After the visitor is authenticated
// Assume `userId` is the authenticates visitor's visitor code.
$kameleoonClient->addData($anonymousVisitorCode, new CustomData(MAPPING_INDEX, $userId));
$kameleoonClient->flush($anonymousVisitorCode, null, null, true);
// Indicate that `userId` is a unique identifier.
$kameleoonClient->addData($userId, new UniqueIdentifier(true));
// 3. After the visitor has been authenticated
// Retrieve the variation for the `userId`, which will match the anonymous visitor code's variation.
$userVariation = $kameleoonClient->getVariation($userId, FEATURE_KEY);
$isSameVariation = $userVariation->key == $anonymousVariation->key; // true
// The `userId` and `anonymousVisitorCode` are now linked and tracked as a single visitor.
$kameleoonClient->trackConversion($userId, 123, 10.0);
// Additionally, the linked visitors will share all fetched remote visitor data.
$kameleoonClient->getRemoteVisitorData($userId);
```
この例では、アプリケーションにログインページがあります。ログイン時点ではユーザー ID が不明であるため、[`getVisitorCode()`](#getvisitorcode) メソッドで生成された匿名訪問者識別子が使用されます。ユーザーがログインした後、匿名訪問者はユーザー ID と関連付けられ、その訪問者の一意の識別子として使用されます。
### カスタムバケットキーの使用
デフォルトでは、Kameleoon は機能フラグのバリエーションをユーザーに割り当てるために、一意の匿名訪問者 ID(`visitorCode`)を使用します。この ID は通常、ユーザーのデバイス(クライアントサイドおよびサーバーサイド SDK の場合はブラウザの cookie、モバイル SDK の場合は永続ストレージ)で生成・保存されます。ただし、特定のシナリオでは、同じ組織のすべてのユーザーが機能フラグの同じバリアントを見ることを保証する必要がある場合があります。
**カスタムバケットキー** オプションを使用すると、独自のカスタム識別子をバケット化に提供することで、このデフォルトの動作を上書きできます。この上書きにより、Kameleoon の割り当てロジックがデフォルトの `visitorCode` の代わりに指定されたキーを使用することが保証されます。
#### ユースケース
カスタムバケットキーの使用は、特に以下の状況において、機能フラグの割り当ての一貫性と精度を維持するために不可欠です:
* **アカウントレベルまたは組織の実験:** B2B 製品や、同じ組織のすべてのユーザーを同じバリエーションに割り当てたいシナリオでは、`accountId` などの識別子を使用できます。カスタムバケットキーは、チーム全体や会社全体に影響する機能の A/B テストにとって重要です。
カスタムバケットキーを実装することで、実験における一貫性と精度がより高まり、より信頼性の高い結果と優れたユーザー体験につながります。
#### 技術的詳細
機能フラグにカスタムバケットキーを設定すると、アプリケーションのデータから特定の識別子を Kameleoon に提供します:
```php theme={null}
$kameleoonClient->addData($visitorCode, new Kameleoon\Data\CustomData(1, "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) することもできます。
### ロギング
SDK は、さまざまな内部プロセスや問題を反映するログを生成します。
#### ログレベル
SDK は、ログレベルによるロギングの制限の設定をサポートしています。
```php theme={null}
use Kameleoon\logging\KameleoonLogger;
use Kameleoon\logging\LogLevel;
// The `NONE` log level does not allow logging.
KameleoonLogger::setLogger(LogLevel::NONE);
// The `ERROR` log level only allows logging issues that may affect the SDK's primary behavior.
KameleoonLogger::setLogger(LogLevel::ERROR);
// The `WARNING` log level allows logging issues which may require additional attention.
// It extends the `ERROR` log level.
// The `WARNING` log level is a default log level.
KameleoonLogger::setLogger(LogLevel::WARNING);
// The `INFO` log level allows logging general information on the SDK's internal processes.
// It extends the `WARNING` log level.
KameleoonLogger::setLogger(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.
KameleoonLogger::setLogger(LogLevel::DEBUG);
```
#### ログのカスタム処理
SDK はデフォルトでログをコンソール出力に書き込みます。この動作は上書きできます。
ログレベルによるロギングの制限は、ログ処理ロジックとは別に実行されます。
```php theme={null}
use Kameleoon\logging\KameleoonLogger;
use Kameleoon\logging\Logger;
use Kameleoon\logging\LogLevel;
use Monolog\Logger as MonologLogger;
public class CustomLogger implements Logger {
// Monolog logger
private MonologLogger $inner;
public function __construct(MonologLogger $inner)
{
$this->inner = $inner;
}
// `log` method accepts logs from the SDK
public function log($level, string $message): void
{
// Custom log handling logic here. For example:
switch ($level) {
case LogLevel::ERROR:
$this->inner->error($message);
break;
case LogLevel::WARNING:
$this->inner->warning($message);
break;
case LogLevel::INFO:
$this->inner->info($message);
break;
case LogLevel::DEBUG:
$this->inner->debug($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.
KameleoonLogger::setLogLevel(LogLevel::DEBUG); // Optional; defaults to `LogLevel::WARNING`.
KameleoonLogger::setLogger(new CustomLogger($inner));
```
## リファレンス
これは PHP SDK の完全なリファレンスドキュメントです。
### 初期化
#### create()
`Kameleoon\KameleoonClientFactory` のこのメソッドは、設定ファイル内に SDK 構成を提供することで `KameleoonClient` インスタンスを作成します。他の SDK メソッドを使用する前に、この `KameleoonClient` インスタンスを作成して SDK を初期化する必要があります。SDK とのすべてのインタラクションは、この `KameleoonClient` インスタンスを使用します。代わりに `KameleoonClientConfig` オブジェクトとして設定を提供するには、[`createWithConfig`](#createWithConfig) メソッドを参照してください。
```php theme={null}
require "vendor/autoload.php";
use Kameleoon\KameleoonClientFactory;
use Kameleoon\Exception\ConfigCredentialsInvalid;
use Kameleoon\Exception\KameleoonException;
use Kameleoon\Exception\SiteCodeIsEmpty;
$siteCode = "a8st4f59bj";
try {
// Read from default configuration path: "/tmp/kameleoon/php-client/"
$kameleoonClient = KameleoonClientFactory::create($siteCode);
} catch (SiteCodeIsEmpty $ex) {
// indicates that provided site code is empty
} catch (ConfigCredentialsInvalid $ex) {
// indicates that provided clientId / clientSecret are not valid
} catch (KameleoonException $ex) {
// probably indicates that the SDK is unable to access the **Kameleoon working directory**
}
try {
$kameleoonClient = KameleoonClientFactory::create($siteCode, "custom/file/path/client-php.json");
} catch (SiteCodeIsEmpty $ex) {
// indicates that provided site code is empty
} catch (ConfigCredentialsInvalid $ex) {
// indicates that provided clientId / clientSecret are not valid
} catch (KameleoonException $ex) {
// probably indicates that the SDK is unable to access the **Kameleoon working directory**
}
```
##### 引数
| 名前 | 型 | 説明 |
| --------------------- | ------ | -------------------------------------------------------------------------------------------------- |
| siteCode | String | SDK で使用している Kameleoon プロジェクトの [一意のキー](/user-manual/faq#how-do-i-find-my-sitecode) です。このフィールドは必須です。 |
| configurationFilePath | String | SDK 設定ファイルへのパス。このフィールドはオプションで、デフォルトでは `/tmp/kameleoon/client-php.json` に設定されています。 |
##### 戻り値
| 型 | 説明 |
| ------------------------- | ----------------------------------------------------- |
| Kameleoon\KameleoonClient | 実験と機能フラグを管理するために使用される **KameleoonClient** クラスのインスタンス。 |
##### スローされる例外
| 型 | 説明 |
| ------------------------ | ------------------------------------------------------------------- |
| SiteCodeIsEmpty | 要求されたクレデンシャルが提供されなかったことを示す例外です(設定ファイルを使用するか、メソッドの config パラメータを使用)。 |
| ConfigCredentialsInvalid | 要求されたクレデンシャルが提供されなかったことを示す例外です(設定ファイルを使用するか、メソッドの config パラメータを使用)。 |
| KameleoonException | SDK が **Kameleoon 作業ディレクトリ** にアクセスできない可能性を示す例外です。 |
#### createWithConfig()
`Kameleoon\KameleoonClientFactory` のこのメソッドは `KameleoonClient` インスタンスを作成し、SDK 設定を `KameleoonClientConfig` オブジェクトとして渡すことができます。他の SDK メソッドを使用する前に、この `KameleoonClient` インスタンスを作成して SDK を初期化する必要があります。SDK とのすべてのインタラクションは、この `KameleoonClient` インスタンスを使用します。代わりにファイルで SDK 設定を提供するには、[`create`](#create) メソッドを使用してください。
```php theme={null}
require "vendor/autoload.php";
use Kameleoon\KameleoonClientConfig;
use Kameleoon\KameleoonClientFactory;
use Kameleoon\Exception\ConfigCredentialsInvalid;
use Kameleoon\Exception\KameleoonException;
use Kameleoon\Exception\SiteCodeIsEmpty;
$siteCode = "a8st4f59bj";
try {
$cookieOptions = KameleoonClientConfig::createCookieOptions(
"example.com", // domain: optional, but strictly recommended
false, // secure: optional (false by default)
false, // httponly: optional (false by default)
"Lax" // samesite: optional (Lax by default)
);
$config = new KameleoonClientConfig(
"", // clientId: mandatory
"", // clientSecret: mandatory
"/tmp/kameleoon/php-client/", // kameleoonWorkDir: optional / ("/tmp/kameleoon/php-client/" by default)
60, // refreshIntervalMinute: in minutes, optional (60 minutes by default)
10_000, // defaultTimeoutMillisecond: in milliseconds, optional (10_000 ms by default)
false, // debugMode: optional (false by default)
$cookieOptions, // cookieOptions: optional
"development", // environment: optional ("production" by default)
"example.com", // networkDomain: optional (null by default)
1024*1024, // requestBodySizeLimitBytes: optional (2560 * 1024 by default)
);
$kameleoonClient = KameleoonClientFactory::create($siteCode, $config);
} catch (SiteCodeIsEmpty $ex) {
// indicates that provided site code is empty
} catch (ConfigCredentialsInvalid $ex) {
// indicates that provided clientId / clientSecret are not valid
} catch (KameleoonException $ex) {
// probably indicates that the SDK is unable to access the **Kameleoon working directory**
}
```
##### 引数
| 名前 | 型 | 説明 |
| --------------- | --------------------- | --------------------------------------------------------------------- |
| siteCode | String | 実験を実行したい Web サイトのコード。この一意のコード ID は Kameleoon アプリで確認できます。このフィールドは必須です。 |
| kameleoonConfig | KameleoonClientConfig | 渡す SDK 設定オブジェクト。このフィールドはオプションです。 |
##### 戻り値
| 型 | 説明 |
| --------------- | ---------------------------------------------------- |
| KameleoonClient | 実験と機能フラグを管理するために使用する **KameleoonClient** クラスのインスタンス。 |
##### スローされる例外
| 型 | 説明 |
| ------------------------ | ------------------------------------------------------------------- |
| SiteCodeIsEmpty | 要求されたクレデンシャルが提供されなかったことを示す例外です(設定ファイルを使用するか、メソッドの config パラメータを使用)。 |
| ConfigCredentialsInvalid | 要求されたクレデンシャルが提供されなかったことを示す例外です(設定ファイルを使用するか、メソッドの config パラメータを使用)。 |
| KameleoonException | SDK が **Kameleoon 作業ディレクトリ** にアクセスできない可能性を示す例外です。 |
### 機能フラグとバリエーション
#### isFeatureActive()
* 📨 *Kameleoon にトラッキングデータを送信(`track` パラメータに依存)*
このメソッドは以前 `activateFeature` と呼ばれていましたが、SDK バージョン `4.0.0` で削除されました。
このメソッドは、指定された機能が特定のユーザーに対してアクティブかどうかをチェックするために、必須の引数として **visitorCode** と **featureKey** を受け取ります。
そのようなユーザーがこの機能フラグに関連付けられたことがない場合、SDK はランダムにブール値を返します(ユーザーがこの機能を持つべきなら **true**、そうでないなら **false**)。指定された **visitorCode** を持つユーザーが既にこの機能フラグに登録されている場合、以前の **FeatureFlag** 値を検出します。
潜在的な例外をキャッチするために、右の例に示すように、コードに適切なエラー処理が設定されていることを確認する必要があります。
`visitorCode` を指定すると、`isFeatureActive()` メソッドはそれを一意の訪問者識別子として使用します。これは [クロスデバイス実験](/developer-docs/apis/data-api-rest/tutorials/storing-and-retrieving-external-data-to-target-users) に役立ちます。`visitorCode` を指定し、`isUniqueIdentifier` パラメータを `true` に設定すると、SDK はフラッシュされたデータを指定された識別子に関連付けられた訪問者にリンクします。
`isUniqueIdentifier` パラメータは非推奨です。代わりに [`UniqueIdentifier`](#uniqueidentifier) を使用してください。
`isUniqueIdentifier` は、もともと訪問者に割り当てられた匿名の `visitorCode` にアクセスできないが、セッションマージ機能を使って匿名訪問者に接続された内部 ID にアクセスできる場合など、その他のエッジケースのシナリオでも役立つことがあります。
Kameleoon は、`isFeatureActive()`、`getVariation()`、`getVariations()` などの特定のメソッドを呼び出した際に、セッションと訪問者をカウントするためにトラッキングを使用します。
訪問者をバリエーションに露出させてカウントする必要がある場合は、`track` パラメータにデフォルトの `true` 値を使用してください。訪問者を露出させる前にこれらのメソッドを呼び出す場合のみ、`track` パラメータを `false` に設定してください。
例えば、訪問者を露出させる前に `getVariations()` を呼び出してすべてのバリエーションを取得する場合は、`track` パラメータを `false` に設定します。この設定により、Kameleoon がセッションを早期にカウントすることを防げます。その後、明示的に訪問者を露出させたときにトラッキングをトリガーできます。
Kameleoon はデフォルトで毎秒トラッキングデータを送信します。トラッキング間隔の設定オプションを使用して、この間隔を最大5秒に設定できます。Kameleoon は、イベント間の間隔が30分未満である限り、トラッキングイベントを1つのセッションにグループ化します。トラッキングイベント間に30分以上経過した場合、Kameleoon はイベントを別のセッションとしてカウントします。訪問は、セッション内の最後に記録されたイベントから30分後にレポートに表示されます。
```php theme={null}
$visitorCode = $kameleoonClient->getVisitorCode();
$featureKey = "new_checkout";
$hasNewCheckout = false;
try {
$hasNewCheckout = $kameleoonClient->isFeatureActive($visitorCode, $featureKey, $timeout);
// disabling tracking
$hasNewCheckout = $kameleoonClient->isFeatureActive($visitorCode, $featureKey, $timeout, null, false);
} catch (Kameleoon\Exception\FeatureNotFound $e) {
// Feature toggle not yet activated on Kameleoon's side - we consider the feature inactive.
$hasNewCheckout = false;
} catch (Kameleoon\Exception\VisitorCodeInvalid $e) {
// VisitorCode, which you passed to a method, is invalid and can't be accepted.
} catch (Kameleoon\Exception\DataFileInvalid $e) {
// It appears that the configuration has not been loaded and
// there is no previously saved version of the configuration available.
} catch (Exception $e) {
// This is a generic Exception handler which will handle all exceptions.
echo "Exception: ", $e->getMessage(), "\n";
}
if ($hasNewCheckout) {
// Implement new checkout code here.
}
```
`isFeatureActive()` メソッドは、マスターフラグの状態ではなく、配信されたバリアントを評価します。ルールを除外すると、メソッドは **その他すべての人に対しては** のデフォルト状態を使用します。このデフォルト状態に **Off** を選択すると、マスター機能フラグが **On** であっても、メソッドは常に `false` を返します。
##### 引数
| 名前 | 型 | 説明 |
| ------------------------ | ------ | ---------------------------------------------------------------------------------------------------------------------------------------- |
| visitorCode | string | ユーザーの一意の識別子。このフィールドは必須です。 |
| featureKey | string | ユーザーに公開したい機能のキー。このフィールドは必須です。 |
| timeout | ?int | タイムアウト(ミリ秒単位)。このパラメータは、結果を待つためにメソッドがブロックできる最大時間を指定します。このフィールドはオプションです。タイムアウト値が提供されない場合、SDK は設定で指定された [`default_timeout`](#追加の設定) を使用します。 |
| isUniqueIdentifier (非推奨) | ?bool | visitorCode が一意の識別子かどうかを指定するためのオプションパラメータ。提供されない場合、デフォルト値は `null` です。このフィールドはオプションです。 |
| track | bool | 機能評価のトラッキングを有効または無効にするためのオプションパラメータ(デフォルトは `true`)。 |
##### 戻り値
| 型 | 説明 |
| ---- | ----------------------------------------- |
| bool | 指定された **visitorCode** に対して登録されている機能フラグの値。 |
##### スローされる例外
| 型 | 説明 |
| ------------------ | -------------------------------------------------------------------------------------------------------------------------- |
| FeatureNotFound | 要求された機能 ID が SDK の内部設定で見つからなかったことを示す例外です。これは通常、機能フラグが Kameleoon 側でまだ有効化されていないことを意味します(機能を実装するコードはすでに Web アプリ側にデプロイされています)。 |
| VisitorCodeInvalid | 提供された訪問者コードが有効でないことを示す例外です(空、または255文字より長い)。 |
| DataFileInvalid | 設定がロードされておらず、以前に保存されたバージョンの設定が利用できないことを示す例外です。 |
#### getVariation()
* 📨 *Kameleoon にトラッキングデータを送信(`track` パラメータに依存)*
特定の機能フラグに対して特定の訪問者に割り当てられた [`Variation`](#variation) を取得します。
このメソッドは必須引数として `visitorCode` と `featureKey` を受け取ります。`track` 引数はオプションで、デフォルトは `true` です。
訪問者に割り当てられた `Variation` を返します。訪問者がいかなる機能フラグルールにも関連付けられていない場合、メソッドは指定された機能フラグのデフォルトの `Variation` を返します。
潜在的な例外を管理するために、コードに適切なエラー処理が実装されていることを確認してください。
デフォルトバリエーションとは、訪問者が機能フラグの事前定義された配信ルールのいずれにも一致しない場合に割り当てられるバリエーションを指します。言い換えれば、特定のルールでターゲットされていないすべてのユーザーに適用されるフォールバックバリエーションです。これは管理インターフェースの「その他すべての人に対しては...」セクションに表示されるバリエーションとして表現されます。
```php theme={null}
$featureKey = "new_checkout";
try {
$variation = $kameleoonClient->getVariation($visitorCode, $featureKey);
// disabling tracking
$variation = $kameleoonClient->getVariation($visitorCode, $featureKey, false);
} catch (Kameleoon\Exception\FeatureNotFound $e) {
// An error has occurred; the feature flag isn't found in the current configuration.
} catch (Kameleoon\Exception\FeatureEnvironmentDisabled $e) {
// The feature flag is disabled for the environment.
} catch (Kameleoon\Exception\VisitorCodeInvalid $e) {
// The visitor code you passed to the method is invalid and can't be accepted by the SDK.
}
// Fetch a variable value for the assigned variation
$title = $variation->variables["title"]->value;
switch ($variation->key) {
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 (*オプション*) | `bool` | 機能評価のトラッキングを有効または無効にするためのオプションパラメータ。 | `true` |
##### 戻り値
| 型 | 説明 |
| ----------- | ------------------------------------------------------- |
| `Variation` | 特定の機能フラグに対して指定された訪問者に割り当てられた [`Variation`](#variation)。 |
##### スローされる例外
| 型 | 説明 |
| ---------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| `VisitorCodeInvalid` | 提供された訪問者コードが有効でないことを示す例外です。空、または255文字より長いです。 |
| `FeatureNotFound` | 要求された機能キーが SDK の内部設定で見つからなかったことを示す例外です。これは通常、機能フラグが Kameleoon アプリで有効化されていないことを意味します(機能を実装するコードはすでにアプリケーションにデプロイされています)。 |
| `FeatureEnvironmentDisabled` | 訪問者の現在の環境(例えば、production、staging、development)で機能フラグが無効になっていることを示す例外です。 |
#### getVariations()
* 📨 *Kameleoon にトラッキングデータを送信(`track` パラメータに依存)*
すべての機能フラグにわたって、指定された訪問者に割り当てられた [`Variation`](#variation) オブジェクトのマップを取得します。
このメソッドは、利用可能なすべての機能フラグを反復処理し、指定された訪問者に関連付けられた各フラグに割り当てられた `Variation` を返します。必須引数として `visitorCode` を受け取り、`onlyActive` と `track` はオプションです。
* `onlyActive` が `true` に設定されている場合、`getVariations()` メソッドは、ユーザーが `off` バリエーションにバケット化されていないことを条件に、機能フラグのバリエーションを返します。
* `track` パラメータは、メソッドがバリエーションの割り当てをトラッキングするかどうかを制御します。デフォルトでは `true` に設定されています。`false` に設定すると、トラッキングは無効になります。
返されるマップは、機能フラグキーをキーとし、対応する `Variation` を値として構成されます。機能フラグにバリエーションが割り当てられていない場合、メソッドはそのフラグのデフォルトの `Variation` を返します。
潜在的な例外を管理するために、適切なエラー処理を実装する必要があります。
デフォルトバリエーションとは、訪問者が機能フラグの事前定義された配信ルールのいずれにも一致しない場合に割り当てられるバリエーションを指します。言い換えれば、特定のルールでターゲットされていないすべてのユーザーに適用されるフォールバックバリエーションです。これは管理インターフェースの「その他すべての人に対しては...」セクションに表示されるバリエーションとして表現されます。
```php theme={null}
try {
$variations = $kameleoonClient->getVariations($visitorCode);
// only active variations
$variations = $kameleoonClient->getVariations($visitorCode, true);
// disable tracking
$variations = $kameleoonClient->getVariations($visitorCode, $onlyActive, false);
} catch (Kameleoon\Exception\VisitorCodeInvalid $e) {
// Handle exception
}
```
##### 引数
| 名前 | 型 | 説明 | デフォルト |
| -------------------- | -------- | --------------------------------------------------------------------- | ------- |
| visitorCode (*必須*) | `string` | 訪問者の一意の識別子。 | |
| onlyActive (*オプション*) | `bool` | アクティブな(`true`)機能フラグまたはすべての(`false`)機能フラグのバリエーションを返すかどうかを示すオプションパラメータ。 | `false` |
| track (*オプション*) | `bool` | 機能評価のトラッキングを有効または無効にするためのオプションパラメータ。 | `true` |
##### 戻り値
| 型 | 説明 |
| -------------------------------- | -------------------------------------------------------------------- |
| `array` | 対応する機能のキーを使用して、機能フラグの割り当てられた [`Variation`](#variation) オブジェクトを含むマップ。 |
##### スローされる例外
| 型 | 説明 |
| -------------------- | -------------------------------------------- |
| `VisitorCodeInvalid` | 提供された訪問者コードが有効でないことを示す例外です。空、または255文字より長いです。 |
#### setForcedVariation()
このメソッドを使用すると、標準の評価プロセスをバイパスして、ユーザーに特定の [`Variation`](#variation) をプログラム的に割り当てることができます。これは、通常の評価ロジックが不要であるか、スキップする必要がある制御された実験で特に価値があります。デバッグやカスタムテストなどのシナリオでも役立ちます。
**強制** バリエーションが設定されると、Kameleoon のリアルタイム評価ロジックを上書きします。セグメンテーション、ターゲティング条件、アルゴリズム計算などのプロセスはスキップされます。実験中のセグメンテーションとターゲティング条件を保持するには、代わりに `forceTargeting=false` を設定してください。
**シミュレートされた** バリエーションは、実行順序で常に優先されます。**シミュレートされた** バリエーション計算がトリガーされると、まず完全に処理され完了します。
強制バリエーションは、評価されたバリエーションと同じように扱われます。標準の評価されたバリエーションと同様に、分析でトラッキングされ、ユーザーコンテキストに保存されるため、レポートの一貫性が保証されます。
特定の条件下(例えば、無効なパラメータ、ユーザーコンテキスト、内部問題)では、メソッドが例外をスローすることがあります。アプリケーションを安定して回復力のあるものに保つために、適切な例外処理が不可欠です。
**強制** バリエーションを **[シミュレートされた](#getvisitorcode)** バリエーションと区別することが重要です:
* **強制バリエーション**: 個別の実験に固有のものです。
* **シミュレートされたバリエーション**: 全体的な **機能フラグ** の結果に影響します。
```php theme={null}
$experimentId = 9516;
try {
// Forcing the variation "on" for the experiment 9516 for the visitor
$kameleoonClient->setForcedVariation($visitorCode, $experimentId, "on");
// Forcing the variation "on" while preserving segmentation and targeting conditions during the experiment
$kameleoonClient->setForcedVariation($visitorCode, $experimentId, "on", false);
// Resetting the forced variation for the experiment 9516 for the visitor
$kameleoonClient->setForcedVariation($visitorCode, $experimentId, null);
} catch (Kameleoon\Exception\KameleoonException $e) {
// Handling the error
}
```
##### 引数
| 名前 | 型 | 説明 | デフォルト |
| ------------------------ | --------- | ------------------------------------------------------------------------------------------------------------------------ | ------ |
| visitorCode (*必須*) | `string` | 訪問者の一意の識別子。 | |
| experimentId (*必須*) | `int` | 評価プロセス中にターゲットされ、選択される **実験 ID**。 | |
| variationKey (*必須*) | `?string` | 実験の戻り値として強制される必要がある `Variation` に対応する **バリエーションキー**。値が `null` の場合、強制バリエーションはリセットされます。 | |
| forceTargeting (*オプション*) | `bool` | 実験のターゲティングが強制されてスキップされるか(`true`)、標準の評価プロセスのように適用されるか(`false`)を示します。 | `true` |
| timeout (*オプション*) | `?int` | タイムアウト(ミリ秒単位)。このパラメータは、結果を待つためにメソッドがブロックできる最大時間を指定します。タイムアウト値が提供されない場合、SDK は設定で指定された [`default_timeout`](#追加の設定) を使用します。 | `null` |
##### スローされる例外
| 型 | 説明 |
| --------------------------- | ------------------------------------------------------------------------------------------------------ |
| `VisitorCodeInvalid` | 提供された訪問者コードが有効でないことを示す例外です。空、または255文字より長いです。 |
| `FeatureExperimentNotFound` | 要求された実験 ID が SDK の内部設定で見つからなかったことを示す例外です。これは通常、ルールに対応する実験が Kameleoon 側でまだ有効化されていないことを意味します。 |
| `FeatureVariationNotFound` | 要求されたバリエーションキー(id)が SDK の内部設定で見つからなかったことを示す例外です。これは通常、バリエーションに対応する実験が Kameleoon 側でまだ有効化されていないことを意味します。 |
ほとんどの場合、例で示すように、基本のエラーである `KameleoonException` のみを処理する必要があります。ただし、異なるタイプのエラーへの対応が必要な場合は、特定の要件に基づいてそれぞれを個別に処理してください。さらに、信頼性を高めるために、`Exception` を含めて一般的な言語エラーを処理することもできます。
#### evaluateAudiences()
* 📨 *Kameleoon にトラッキングデータを送信*
このメソッドは、利用可能なすべての Audiences Explorer セグメントに対して訪問者を評価し、一致する訪問者をトラッキングします。
`evaluateAudiences()` は、**すべての関連する訪問者データが設定または更新された後**、および機能バリエーションを取得したり機能フラグをチェックする **直前** に呼び出す必要があります。このアプローチにより、訪問者が利用可能な最新のデータに対して評価され、すべての基準に基づく正確なオーディエンス割り当てが可能になります。
このメソッドを呼び出した後、Audiences Explorer でセグメントパフォーマンスの詳細な分析を実行できます。
```php theme={null}
try {
$kameleoonClient->evaluateAudiences($visitorCode);
} catch (Kameleoon\Exception\KameleoonException $e) {
// Handling the exception
}
```
##### 引数
| 名前 | 型 | 説明 | デフォルト |
| ------------------ | -------- | ------------------------------------------------------------------------------------------------------------------------ | ------ |
| visitorCode (*必須*) | `string` | 訪問者の一意の識別子。 | |
| timeout (*オプション*) | `?int` | タイムアウト(ミリ秒単位)。このパラメータは、結果を待つためにメソッドがブロックできる最大時間を指定します。タイムアウト値が提供されない場合、SDK は設定で指定された [`default_timeout`](#追加の設定) を使用します。 | `null` |
##### スローされる例外
| 型 | 説明 |
| -------------------- | -------------------------------------------- |
| `VisitorCodeInvalid` | 提供された訪問者コードが有効でないことを示す例外です。空、または255文字より長いです。 |
ほとんどの場合、例で示すように、基本のエラーである `KameleoonException` のみを処理する必要があります。ただし、異なるタイプのエラーへの対応が必要な場合は、特定の要件に基づいてそれぞれを個別に処理してください。さらに、信頼性を高めるために、`Exception` を含めて一般的な言語エラーを処理することもできます。
#### getDataFile()
すべての機能フラグを評価するには、[`getVariations()`](#getvariations) を使用してください。このメソッドは、`DataFile` を呼び出して [`getVariation()`](#getvariation) でフラグを反復処理するよりも効率的です。
現在の SDK 設定を [`DataFile`](#datafile) オブジェクトとして返します。
```php theme={null}
try {
$dataFile = $kameleoonClient->getDataFile();
} catch (Kameleoon\Exception\KameleoonException $e) {
// Recommended (but optional) safeguard for unexpected exceptions from third-party libraries
}
```
##### 引数
| 名前 | 型 | 説明 |
| ----------------- | ------ | ------------------------------------------------------------------------------------------------------------------------ |
| timeout (*オプション*) | `?int` | タイムアウト(ミリ秒単位)。このパラメータは、結果を待つためにメソッドがブロックできる最大時間を指定します。タイムアウト値が提供されない場合、SDK は設定で指定された [`default_timeout`](#追加の設定) を使用します。 |
##### 戻り値
| 型 | 説明 |
| ---------- | --------------------------------- |
| `DataFile` | SDK 設定を含む [`DataFile`](#datafile) |
### 訪問者データ
#### getVisitorCode()
このメソッドは以前 `obtainVisitorCode` と呼ばれていましたが、SDK バージョン `4.0.0` で削除されました。
このメソッドを呼び出して、現在の訪問者の Kameleoon **visitorCode** を取得します。この呼び出しは特に、フロントエンドとバックエンドの混合環境で Kameleoon を使用する際、ユーザー識別の一貫性を保証する必要がある場合に重要です。実装ロジックは以下のとおりです:
1. まず、現在の HTTP リクエストに **kameleoonVisitorCode** cookie またはクエリパラメータが関連付けられているかどうかを確認します。もしあれば、これを訪問者識別子として使用します。
2. 現在のリクエストに cookie やパラメータが存在しない場合、識別子を生成する2つのオプションがあります。1つのオプションは新しい識別子をランダムに作成することで、もう1つは **defaultVisitorCode** 引数が提供されている場合にそれを使用することです。この機能により、お客様が独自の識別子を訪問者コードとして入力でき、これは有益です。Kameleoon の訪問者を独自のユーザーとシームレスにマッチさせることができ、マッチングテーブルでの追加検索の必要がなくなります。
3. いずれの場合も、サーバーサイド(HTTP ヘッダー経由)の **kameleoonVisitorCode** cookie にその値が設定されます。メソッドはこの訪問者の値を返します。
詳細については、[こちらの記事](/developer-docs/feature-experimentation/get-started/hybrid-experimentation/) を参照してください。
独自の `visitorCode` を提供する場合、その一意性はあなた側で保証する必要があります。SDK はそれを確認できません。また、`visitorCode` の長さは **255** 文字に制限されていることに注意してください。それを超える文字があると例外がスローされます。
`getVisitorCode()` メソッドを使用すると、訪問者の **シミュレートされた** バリエーションを設定できます。cookie(**リクエスト** または **ドキュメント** から)に `kameleoonSimulationFFData` キーが含まれている場合、標準の評価プロセスはバイパスされます。代わりに、メソッドは提供されたデータに基づいて直接 [`Variation`](#variation) を返します。
シミュレーションは2つの方法で適用できます:
* **自動(推奨):** Kameleoon Web Experimentation または SDK を [ハイブリッドモード](/developer-docs/feature-experimentation/get-started/hybrid-experimentation#linking-feature-experiments-with-front-end-tracking-code) で使用している場合、[シミュレーションパネル](/user-manual/experimentation/feature-experimentation/using-the-rollout-planner/validation-and-rollback/using-simulation-mode) を使用してバリアントの表示をシミュレートすると、cookie は自動的に作成されます。
* **手動:** `kameleoonSimulationFFData` cookie を手動で設定します。
**シミュレートされた** バリエーションを **[強制](#setforcedvariation)** バリエーションと区別することが重要です:
* **シミュレートされたバリエーション**: 全体的な **機能フラグ** の結果に影響します。
* **強制バリエーション**: 個別の実験に固有のものです。
⚙️ **手動セットアップ**
`kameleoonSimulationFFData` cookie が以下の形式に従っていることを確認してください:
* `kameleoonSimulationFFData={"featureKey":{"expId":10,"varId":20}}`: 指定された `featureKey` に対して、実験 `expId` の `varId` を持つバリエーションをシミュレートします。
* `kameleoonSimulationFFData={"featureKey":{"expId":0}}`: 指定された `featureKey` のデフォルトバリエーション(**Production の他すべての人に対しては** セクションで定義されている)をシミュレートします。
⚠️ 正しく機能させるには、cookie の値が [`encodeURIComponent`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/encodeURIComponent) などのメソッドを使用して URI コンポーネントとしてエンコードされている必要があります。
```php theme={null}
require "vendor/autoload.php";
// The cookie's domain must be provided in the configuration file if no argument is given.
$visitorCode = $kameleoonClient->getVisitorCode();
// default visitor code provided
$visitorCode = $kameleoonClient->getVisitorCode($defaultVisitorCode);
```
##### 引数
| 名前 | 型 | 説明 |
| ------------------ | ------ | ---------------------------------------------------------------------------------------------------------------------------------------- |
| defaultVisitorCode | String | このパラメータは、リクエストに既存の **kameleoonVisitorCode** cookie がない場合に **visitorCode** として使用されます。このフィールドはオプションで、デフォルトではランダムな **visitorCode** が生成されます。 |
| timeout | ?int | タイムアウト(ミリ秒単位)。このパラメータは、結果を待つためにメソッドがブロックできる最大時間を指定します。このフィールドはオプションです。タイムアウト値が提供されない場合、SDK は設定で指定された [`default_timeout`](#追加の設定) を使用します。 |
##### 戻り値
| 型 | 説明 |
| ------ | ------------------------------------------------------ |
| String | この特定のユーザーに関連付けられ、SDK のほとんどのメソッドで使用される **visitorCode**。 |
##### スローされる例外
| 型 | 説明 |
| ------------------------ | ------------------------------------------------------------------------------ |
| InvalidArgumentException | cookie のドメイン値が提供されなかったことを示す例外です(設定ファイル経由、またはメソッドの **topLevelDomain** パラメータ経由)。 |
#### addData()
`addData()` メソッドは、他のメソッドが現在の訪問者をターゲットするかどうかを判断するために使用できるように、[ターゲティングデータ](#データタイプ) をストレージに追加します。
`addData()` メソッドは値を返さず、それ自体で Kameleoon バックエンドサーバーと通信しません。代わりに、宣言されたすべてのデータは [`flush()`](#flush) メソッドによる将来の送信のために保存されます。このアプローチにより、データは通常 `flush()` によってトリガーされる単一のサーバーコールにグループ化されるため、サーバーコールの数が削減されます。
[`trackConversion()`](#trackconversion) メソッドも、`flush()` と同様に、以前に関連付けられたデータを送信します。実験ルールがトリガーされた場合、[`getVariation()`](#getvariation) および [`getVariations()`](#getvariations) メソッドにも同じことが当てはまります。
ほとんどのデータタイプでは、各訪問者は関連付けられたデータのインスタンスを1つだけ持てます。ただし、[`CustomData`](#customdata) は例外です。訪問者はインデックスごとに関連付けられた `CustomData` のインスタンスを1つ持てます。
```php theme={null}
// Add a single data item (tracked by default)
$kameleoonClient->addData($visitorCode, new Kameleoon\Data\Browser(Kameleoon\Data\Browser::CHROME));
// Add multiple data items (tracked by default)
$kameleoonClient->addData(
$visitorCode,
new Kameleoon\Data\PageView("https://url.com", "title", [3]),
new Kameleoon\Data\UserAgent("UserAgent")
);
// Add multiple data items stored locally for targeting only (not sent to the Kameleoon Data API)
$kameleoonClient->addData(
$visitorCode,
false,
new Kameleoon\Data\PageView("https://url.com", "title", [3]),
new Kameleoon\Data\UserAgent("UserAgent")
);
```
##### 引数
| 名前 | 型 | 説明 | デフォルト値 |
| ------------------ | --------- | ---------------------------------------------------------------------------------------------------------- | ------ |
| visitorCode (*必須*) | `string` | 訪問者の一意の識別子。 | |
| track (*オプション*) | `bool` | 追加されたデータがトラッキングの対象かどうかを指定します。`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()` は非ブロッキングで、`instant` パラメータが `true` に設定されていない限り、サーバーコールは非同期で行われます。
`flush()` 関数を使用すると、特定の `visitorCode` にリンクされたデータがいつサーバーに送信されるかを決定できます。例えば、`addData()` を複数回(例えば10回)呼び出した場合、コールするたびにデータをサーバーに送信するのは非効率です。代わりに、最初にすべてのデータを集めてから、最後に `flush()` を1回呼び出して、すべてを一度に送信できます。
`visitorCode` を指定すると、`flush()` メソッドはそれを一意の訪問者識別子として使用します。これは [クロスデバイス実験](/developer-docs/cross-device-experimentation) に役立ちます。`visitorCode` を指定し、`isUniqueIdentifier` パラメータを `true` に設定すると、SDK はフラッシュされたデータを指定された識別子に関連付けられた訪問者にリンクします。
`isUniqueIdentifier` パラメータは非推奨です。代わりに [`UniqueIdentifier`](#uniqueidentifier) を使用してください。
`isUniqueIdentifier` は、訪問者に与えられた匿名の `visitorCode` にアクセスできないが、セッションマージを通じてその訪問者にリンクされた内部 ID を使用できる場合など、独特な状況で役立つことがあります。
```php theme={null}
$visitorCode = $kameleoonClient->getVisitorCode();
$kameleoonClient->addData(
$visitorCode,
new Kameleoon\Data\Browser(Kameleoon\Data\Browser::CHROME).
new Kameleoon\Data\PageView("https://url.com", "title", array(3)),
new Kameleoon\Data\Conversion(32, 10, false)
);
$kameleoonClient->flush($visitorCode); // Interval tracking, non-blocking operation
$kameleoonClient->flush($visitorCode, null, null, true); // Instant tracking, blocking operation
// if you operate with unique ID
$kameleoonClient->addData($visitorCode, new Kameleoon\Data\UniqueIdentifier(true));
$kameleoonClient->flush($visitorCode);
```
##### 引数
| 名前 | 型 | 説明 |
| ------------------------ | ------ | ---------------------------------------------------------------------------------------------------------------------------------------- |
| visitorCode | string | ユーザーの一意の識別子。このフィールドは必須です。 |
| timeout | ?int | タイムアウト(ミリ秒単位)。このパラメータは、結果を待つためにメソッドがブロックできる最大時間を指定します。このフィールドはオプションです。タイムアウト値が提供されない場合、SDK は設定で指定された [`default_timeout`](#追加の設定) を使用します。 |
| isUniqueIdentifier (非推奨) | ?bool | visitorCode が一意の識別子かどうかを指定するためのオプションパラメータ。提供されない場合、デフォルト値は `null` です。このフィールドはオプションです。 |
| instant | bool | データを即座に送信する(`true`)か、予定されたトラッキング間隔に従って送信する(`false`)かを示すブール値フラグ。提供されない場合、デフォルト値は `false` です。このフィールドはオプションです。 |
#### getRemoteData()
このメソッドは以前 `retrieveDataFromRemoteSource` と呼ばれていましたが、SDK バージョン `4.0.0` で削除されました。
`getRemoteData()` メソッドを使用すると、特定の **siteCode**(`KameleoonClientFactory.create()` で設定)に対して提供する **キー** に基づいてデータを取得できます。Kameleoon サーバーがこのデータを保存します。Data API は通常、リモートサーバーにこのデータを保存するために使用されます。このメソッドは、スケーラブルなサーバーと組み合わせることで、大量のデータを簡単に保存できるようにします。その後、訪問者またはユーザーごとにこのデータにアクセスできます。
```php theme={null}
$test_value = $kameleoonClient->getRemoteData("test"); // default timeout will be used
$test_value = $kameleoonClient->getRemoteData("test", 1000); // 1000 milliseconds timeout
try {
$test_value = $kameleoonClient->getRemoteData("test");
} catch (Exception $e) {
// Timeout or Json Decoding Exception
}
```
##### 引数
| 名前 | 型 | 説明 |
| ------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------- |
| key | string | 取得しようとしているデータが関連付けられているキー。このフィールドは必須です。 |
| timeout | ?int | タイムアウト(ミリ秒単位)。このパラメータは、結果を待つためにメソッドがブロックできる最大時間を指定します。このフィールドはオプションです。タイムアウト値が提供されない場合、SDK は設定で指定された [`default_timeout`](#追加の設定) を使用します。 |
##### 戻り値
| 型 | 説明 |
| ------ | ------------------------------------- |
| Object | 特定の **キー** のデータを取得することに関連付けられたオブジェクト。 |
##### スローされる例外
| 型 | 説明 |
| --------- | --------------------------------------------------------------- |
| Exception | リクエストがタイムアウトしたか、取得されたデータを `json_decode` メソッドでデコードできないことを示す例外です。 |
#### getRemoteVisitorData()
`getRemoteVisitorData()` は、Kameleoon Data API から `visitorCode` の Kameleoon Visits Data を取得する非同期メソッドです。このメソッドは、ターゲティング決定を行う際に他のメソッドが使用するために、データをストレージに追加します。
このメソッドを使用して取得されたデータは、以下のような場合に重要な役割を果たします:
* 他のデバイスから収集されたデータを使用する場合。
* ユーザーの履歴(過去の訪問中に閲覧したページなど)にアクセスする場合。
* データレイヤー変数やフロントエンドでのみコンバージョンする目標など、クライアントサイドでのみアクセス可能なデータを使用する場合。
可能なユースケースをより理解するには、[こちらの記事](/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 を使用できる場合など、独特な状況で役立つことがあります。
```php theme={null}
$visitorCode = "visitorCode";
// Visitor data will be fetched and automatically added for `visitorCode`
$dataArray = $kameleoonClient->getRemoteVisitorData($visitorCode, null); // default timeout will be used
$dataArray = $kameleoonClient->getRemoteVisitorData($visitorCode, 1000); // 1000 milliseconds timeout
// If you only want to fetch data and add it yourself manually, set shouldAddData == `false`
$dataArray = $kameleoonClient->getRemoteVisitorData($visitorCode, null, false); // default timeout will be used
$dataArray = $kameleoonClient->getRemoteVisitorData($visitorCode, 1000, false); // 1000 milliseconds timeout
```
##### 引数
| 名前 | 型 | 説明 |
| ------------------------ | ----------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| visitorCode | `string` | 割り当てられたデータを取得したい訪問者コード。このフィールドは必須です。 |
| timeout | `?int` | タイムアウト(ミリ秒単位)。このパラメータは、結果を待つためにメソッドがブロックできる最大時間を指定します。このフィールドはオプションです。タイムアウト値が提供されない場合、SDK は設定で指定された [`default_timeout`](#追加の設定) を使用します。 |
| addData | `bool` | メソッドが訪問者の取得データを自動的に追加するかどうかを示すブール値。指定されない場合、デフォルト値は **true** です。このフィールドはオプションです。 |
| filter | `Kameleoon\Types\RemoteVisitorDataFilter` | 訪問から取得するデータを指定するフィルター。デフォルトでは、`CustomData` のみが現在および最新の前回の訪問から取得されます(`new RemoteVisitorDataFilter(1, true, true)` または `new RemoteVisitorDataFilter()`)。他のフィルターパラメータは `false` に設定されます。このフィールドはオプションです。 |
| isUniqueIdentifier (非推奨) | `?bool` | visitorCode が一意の識別子かどうかを指定するためのオプションパラメータ。提供されない場合、デフォルト値は `null` です。このフィールドはオプションです。 |
##### 戻り値
| 型 | 説明 |
| ----------------------- | ------------------------ |
| `array` | 指定された訪問者に割り当てられたデータのリスト。 |
##### getRemoteVisitorData() でのパラメータの使用
`getRemoteVisitorData()` メソッドは、訪問者のデータを取得する際にさまざまなパラメータを定義できる柔軟性を提供します。目標、実験、バリエーションに基づいてターゲティングする場合、すべてのデータタイプに同じアプローチが適用されます。
例えば、「注文取引」という目標を達成した訪問者のデータを取得したいとします。`getRemoteVisitorData()` メソッド内でパラメータを指定して、ターゲティングを絞り込むことができます。例えば、過去5回の訪問で目標にコンバージョンしたユーザーのみをターゲットにする場合、`previousVisitAmount` パラメータを 5 に、`conversions` を true に設定できます。
この例で示された柔軟性は、目標データに限定されません。`getRemoteVisitorData()` メソッド内でパラメータを使用することで、さまざまな訪問者の行動に関するデータを取得できます。
利用可能な `Kameleoon\Types\RemoteVisitorDataFilter` オプションのリストは以下のとおりです:
| 名前 | 型 | 説明 | デフォルト |
| ----------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------- |
| previousVisitAmount (*オプション*) | `int` | データを取得する前回の訪問数。`1` から `25` の間の数値 | `1` |
| currentVisit (*オプション*) | `bool` | true の場合、現在の訪問データが取得されます | `true` |
| customData (*オプション*) | `bool` | true の場合、カスタムデータが取得されます。 | `true` |
| pageViews (*オプション*) | `bool` | true の場合、ページデータが取得されます。 | `false` |
| geolocation (*オプション*) | `bool` | true の場合、位置情報データが取得されます。 | `false` |
| device (*オプション*) | `bool` | true の場合、デバイスデータが取得されます。 | `false` |
| browser (*オプション*) | `bool` | true の場合、ブラウザデータが取得されます。 | `false` |
| operatingSystem (*オプション*) | `bool` | true の場合、オペレーティングシステムデータが取得されます。 | `false` |
| conversions (*オプション*) | `bool` | true の場合、コンバージョンデータが取得されます。 | `false` |
| experiments (*オプション*) | `bool` | true の場合、実験データが取得されます。 | `false` |
| kcs (*オプション*) | `bool` | true の場合、Kameleoon Conversion Score(KCS)が取得されます。[AI 予測ターゲティングアドオン](/user-manual/ai-predictive-targeting/target-users-based-on-likelihood-to-convert) が必要です | `false` |
| visitorCode (*オプション*) | `bool` | true の場合、Kameleoon は最新の訪問から `visitorCode` を取得し、現在の訪問に使用します。これは、訪問者(`visitorCode` で識別される)が [クロスデバイス実験](/developer-docs/cross-device-experimentation) のために、訪問にわたって常に同じバリエーションを受け取ることを保証したい場合に必要です。 | `true` |
| cbs (*オプション*) | `bool` | true の場合、Contextual Bandit スコアデータが取得されます。 | `false` |
| personalization (*オプション*) | `bool` | true の場合、パーソナライゼーションデータが取得されます。これはパーソナライゼーション条件に必要です。 | `false` |
#### getVisitorWarehouseAudience()
このメソッドは、指定された `visitorCode` と `warehouseKey` を使用して、データウェアハウス内の訪問者に関連付けられたすべてのオーディエンスデータを取得します。`warehouseKey` は通常、内部のユーザー ID です。`customDataIndex` パラメータは、Kameleoon が訪問者をターゲットするために使用する Kameleoon カスタムデータに対応します。詳細については、[ウェアハウスターゲティングのドキュメント](/user-manual/integrations/data-warehouses/bigquery/use-bigquery-as-a-source-audience-targeting) を参照してください。メソッドは結果を返された future に `CustomData` オブジェクトとして渡し、データが訪問者に追加され、ターゲティング目的で利用可能であることを確認します。
```php theme={null}
$warehouseAudienceCustomData = $kameleoonClient->getVisitorWarehouseAudience($visitorCode, $customDataIndex);
// If you need to specify warehouse key
$warehouseAudienceCustomData = $kameleoonClient->getVisitorWarehouseAudience(
$visitorCode, $customDataIndex, $warehouseKeyValue
);
// If you need to specify warehouse key & timeout
$warehouseAudienceCustomData = $kameleoonClient->getVisitorWarehouseAudience(
$visitorCode, $customDataIndex, $warehouseKeyValue, 2000
);
```
##### 引数
| 名前 | 型 | 説明 |
| --------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------- |
| visitorCode | string | データを取得して追加したい訪問者の一意の識別子。 |
| customDataIndex | int | BigQuery オーディエンスのターゲティングに使用したいカスタムデータのインデックスを表す整数。 |
| warehouseKey | string | ウェアハウスデータを識別する一意のキー(通常は内部のユーザー ID)。このフィールドはオプションです。 |
| timeout | ?int | タイムアウト(ミリ秒単位)。このパラメータは、結果を待つためにメソッドがブロックできる最大時間を指定します。このフィールドはオプションです。タイムアウト値が提供されない場合、SDK は設定で指定された [`default_timeout`](#追加の設定) を使用します。 |
##### 戻り値
| 型 | 説明 |
| ------------- | --------------------------------------------------------------------------------------------- |
| `?Customdata` | データが訪問者に追加されたことを確認する `CustomData` インスタンス。値が `null` の場合、リクエストは失敗し、`CustomData` は訪問者に追加されていません。 |
##### スローされる例外
| 型 | 説明 |
| -------------------- | ------------------------------------------- |
| `VisitorCodeInvalid` | 提供された訪問者コードが有効でないことを示す例外です(空、または255文字より長い)。 |
#### setLegalConsent()
訪問者が個人データの使用に法的同意をしたかどうかを指定するには、このメソッドを使用する必要があります。`legalConsent` パラメータを `false` に設定すると、トラッキングリクエストに含めることができるデータのタイプが制限されます。このメソッドは、訪問者のデータを責任を持って管理しながら、法的および規制上の要件に従うのに役立ちます。個人データに関する詳細は、[同意管理ポリシー](/user-manual/project-management/consent-management-policy) を参照してください。
```php theme={null}
$visitorCode = $kameleoonClient->getVisitorCode();
$kameleoonClient->setLegalConsent($visitorCode, true);
```
##### 引数
| 名前 | 型 | 説明 |
| ------------ | ------ | ------------------------------------------------------------------------------------------------- |
| visitorCode | string | ユーザーの一意の識別子。このフィールドは必須です。 |
| legalConsent | bool | 法的同意の状況を表すブール値。`true` は訪問者が法的同意を与えたことを示し、`false` は訪問者が法的同意を提供したことがない、または撤回したことを示します。このフィールドは必須です。 |
##### スローされる例外
| 型 | 説明 |
| ------------------ | ------------------------------------------- |
| VisitorCodeInvalid | 提供された訪問者コードが有効でないことを示す例外です(空、または255文字より長い)。 |
##### 同意撤回時の動作
`setLegalConsent()` を `legalConsent=false` で呼び出した場合、SDK は `kameleoonVisitorCode` cookie を削除しません。代わりに、cookie の有効期限の延長を停止し、cookie が自然に有効期限切れになるまで持続することを許可します。
コンプライアンス要件でオプトアウト時に cookie ファイルを即座に削除する必要がある場合は、フレームワークのネイティブ cookie 管理メソッドを使用して手動で削除する必要があります。SDK はファイルを自動的に削除しません。
### 目標とサードパーティ分析
#### getEngineTrackingCode()
Kameleoon は、Mixpanel、Google Analytics 4、Segment などのいくつかの分析ソリューションと統合しています。サーバーサイド実験を正しくトラッキングするには、訪問者が実験をトリガーした後に `getEngineTrackingCode()` メソッドを呼び出してください。SDK は、訪問者が前の5秒間にトリガーした実験用の JavaScript キューコマンドを返します。このコードをページに挿入すると、Engine.js がコマンドを処理し、アクティブな分析統合を通じて露出イベントを送信します。
このメソッドの実装の詳細については、[ハイブリッド実験](/developer-docs/feature-experimentation/get-started/hybrid-experimentation) を参照してください。
```php theme={null}
$engineTrackingCode = $kameleoonClient->getEngineTrackingCode($visitorCode);
```
* この機能を使用するには、PHP 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 は、[`getVisitorCode`](/developer-docs/sdks/web-sdks/js-sdk#getvisitorcode) を呼び出すと、`window.kameleoonQueue` に対応する実験の割り当てを追加していれば、自動的にバリエーションをトラッキングします。
* 返されたトラッキングコードを HTML `