> ## 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.
# Rust SDK
> Kameleoon Rust SDK を統合して、Rust サービスや Web バックエンドで実験を実行し、フィーチャーフラグを有効化します。
Kameleoon Rust SDK を使用すると、Rust サービスや Web バックエンドで実験を実行し、フィーチャーフラグを有効化できます。
**はじめに**: 開始方法については、[開発者ガイド](#開発者ガイド) を参照してください。
**変更履歴**: Rust SDK の最新バージョン: 0.9.5 [Changelog](https://github.com/Kameleoon/client-rust/blob/master/CHANGELOG.md)。
**SDK メソッド**: Rust SDK の完全なリファレンスドキュメントについては、[リファレンス](#リファレンス) セクションを参照してください。
## 開発者ガイド
このガイドは、Rust SDK を迅速に統合し、Rust アプリケーションでフィーチャーフラグの評価を開始するのに役立つように設計されています。
### はじめに
#### Rust クライアントのインストール
現在のワークスペースで作業している場合、いくつかの SDK メソッドが非同期であるため、SDK を `tokio` と共にパス依存関係として追加します。
```toml title="Cargo.toml" theme={null}
[dependencies]
kameleoon-client = "0.9.4"
```
#### 追加の構成
認証情報を提供し、SDK の動作をカスタマイズするための `client-config.json` 構成ファイルを作成します。[サンプル構成ファイル](/assets/developer-docs/sdks/web-sdks/client-configs/client-config.json)をダウンロードすることもできます。
このファイルはデフォルトのパス `/etc/kameleoon/client-config.json` に保存することをお勧めしますが、クラスパス上の任意の場所に `client-config.json` として保存することもできます。
Rust SDK は、`create_with_path()` で使用される JSON ファイル、または `create_with_config()` を使用してコード内で直接 `KameleoonClientConfig` をビルドすることで構成できます。
次の表は、設定可能な利用可能なプロパティを示しています。
| キー (コード / 構成ファイル) | 説明 | デフォルト値 |
| -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------ |
| `client_id` / `clientId` (*必須*) | Kameleoon サービスへの認証に必要です。`client_id` を見つけるには、[API 認証情報](/user-manual/account-and-team-management/users-and-teams/api-credentials) のドキュメントを参照してください。 | |
| `client_secret` / `clientSecret` (*必須*) | Kameleoon サービスへの認証に必要です。`client_secret` を見つけるには、[API 認証情報](/user-manual/account-and-team-management/users-and-teams/api-credentials) のドキュメントを参照してください。 | |
| `session_duration` / `sessionDurationMinutes` (*オプション*) | SDK が訪問者とその関連データをメモリに保持する時間間隔(分)。 | `30` 分 |
| `refresh_interval` / `refreshIntervalMinutes` (*オプション*) | アクティブな実験とフィーチャーフラグの構成を更新するために使用される間隔(分)。 | `60` 分 |
| `default_timeout` / `defaultTimeoutMillis` (*オプション*) | SDK のネットワークリクエストのデフォルトタイムアウト(ミリ秒)。 | `10000` ミリ秒 |
| `tracking_interval` / `trackingIntervalMillis` (*オプション*) | トラッキングリクエストをバッチ処理するために使用される間隔(ミリ秒)。値は `[1000, 5000]` の範囲に制限されます。 | `1000` ミリ秒 |
| `environment` / `environment` (*オプション*) | フィーチャーフラグ構成を使用する環境。値は `production`、`staging`、または `development` です。 | `production` |
| `top_level_domain` / `topLevelDomain` (*オプション*) | あなたのウェブサイトの現在のトップレベルドメイン。プロトコルやサブドメインを含まない `example.com` 形式を使用してください。 | `None` |
| `proxy_host` / `proxyHost` (*オプション*) | 送信 SDK 呼び出し用のプロキシホスト。サポートされる形式: `https://my.prox`、`https://my.prox:4545`、`socks5://192.168.1.1:9000`。 | `None` |
| `network_domain` / `networkDomain` (*オプション*) | SDK が送信リクエストに使用するカスタムドメイン。多くの場合プロキシ用です。有効なドメイン(例: example.com または sub.example.com)である必要があります。無効な形式の場合、Kameleoon のデフォルト値が使用されます。 | `None` |
#### Kameleoon クライアントの初期化
SDK をインストールし、認証情報を構成した後、`KameleoonClientFactory` を使用して `KameleoonClient` を作成します。
```rust theme={null}
use std::time::Duration;
use kameleoon_client::config::KameleoonClientConfigBuilder;
use kameleoon_client::factory::KameleoonClientFactory;
async fn create_client() -> Result {
let site_code = "a8st4f59bj";
let client = KameleoonClientFactory::create_with_path(site_code, "/etc/kameleoon/client-config.json")?;
client.initialize().await?;
Ok(client)
}
```
```rust theme={null}
use std::time::Duration;
use kameleoon_client::config::KameleoonClientConfigBuilder;
use kameleoon_client::factory::KameleoonClientFactory;
async fn create_client() -> Result {
let site_code = "a8st4f59bj";
let config = KameleoonClientConfigBuilder::default()
.client_id("".to_owned()) // mandatory
.client_secret("".to_owned()) // mandatory
.refresh_interval(Duration::from_mins(60)) // optional (60 minutes by default)
.session_duration(Duration::from_mins(30)) // optional (30 minutes by default)
.default_timeout(Duration::from_millis(10_000)) // optional (10000 ms by default)
.tracking_interval(Duration::from_millis(1_000)) // optional (10000 ms by default)
.environment("development".to_owned()) // optional
.top_level_domain(".example.com") // mandatory if you use hybrid mode (engine or web experiments)
.proxy_host("http://192.168.0.25:8080".to_owned()) // optional
.network_domain("example.com".to_owned()) // optional
.build()
.unwrap();
let client = KameleoonClientFactory::create_with_config(site_code, config)?;
client.initialize().await?;
Ok(client)
}
```
`KameleoonClient` は、フィーチャーフラグの評価、訪問者データの追加、トラッキングリクエストの送信に使用される主要なオブジェクトです。
* `KameleoonClient` はアプリケーションと Kameleoon プラットフォームの間のブリッジとして機能するため、シングルトンオブジェクトとして使用することをお勧めします。実験を効率的に実行するために必要なすべてのメソッドとプロパティを公開しています。
* Rust SDK は非同期で初期化されます。本番コードでフィーチャー評価に依存する前に、[`initialize()`](#initialize) を呼び出す必要があります。
#### フィーチャーフラグの有効化
##### ユーザーへの一意の ID の割り当て
ユーザーに一意の ID を割り当てるには、[`get_visitor_code()`](#get_visitor_code) メソッドを使用できます。**訪問者コード**が存在しない場合(リクエストヘッダーのクッキーから)、メソッドはランダムな一意の ID を生成するか、生成しておいた `default_visitor_code` を使用します。ID はその後、レスポンスヘッダーのクッキーに設定されます。
Kameleoon を [ハイブリッドモード](/developer-docs/feature-experimentation/get-started/hybrid-experimentation) で使用している場合、`get_visitor_code()` メソッドを呼び出すと、一意の ID(**訪問者コード**)がアプリケーションファイル `engine.js`(以前は `kameleoon.js` と命名)と SDK 間で共有されます。
##### フラグ構成の取得
コードにフィーチャーフラグを実装するには、まず Kameleoon アカウントでフィーチャーフラグを作成する必要があります。
特定のユーザーに対するフィーチャーフラグのステータスまたはバリエーションを判断するには、[`get_variation()`](#get_variation) または [`is_feature_active()`](#is_feature_active) メソッドを使用して、`feature_key` に基づいて構成を取得する必要があります。
`get_variation()` メソッドは、ON/OFF 状態の単純なフィーチャーフラグと、複数のバリエーションを持つより複雑なフラグの両方を処理します。このメソッドは、フィーチャールールをチェックし、バリエーションを割り当て、`feature_key` と `visitor_code` に基づいて返すことにより、ユーザーに適したバリエーションを取得します。
`is_feature_active()` メソッドは、複数のバリエーションやターゲティングオプションを持つより複雑なフィーチャーフラグとは対照的に、ON または OFF 状態のみを持つ単純なフィーチャーフラグの構成を取得したい場合に使用できます。
フィーチャーフラグに関連付けられた変数(各バリエーションに関連付けられた特定の動作など)がある場合、`get_variation()` を使用すると、割り当てられたバリエーションとその関連実験の詳細を提供する [`Variation`](#variation) オブジェクトにアクセスすることもできます。このメソッドは、ユーザーがターゲットになっているかどうかを確認し、訪問者の割り当てられたバリエーションを見つけ、それをストレージに保存します。`track=true` の場合、SDK は次のトラッキングリクエストで指定された実験への露出イベントを送信します。これは、SDK の [`tracking_interval`](#追加の構成) に基づいて自動的にトリガーされます。デフォルトでは、この間隔は 1000 ミリ秒(1 秒)に設定されています。
`get_variation()` メソッドを使用すると、トラッキングが行われるかどうかを制御できます。`track=false` の場合、SDK によって露出イベントは送信されません。これは、SDK を通じてデータをトラッキングするのではなく、たとえば Kameleoon エンジンによって管理されるクライアントサイドのトラッキングに依存する場合に便利です。さらに、`track=false` を設定することは、`get_variations()` メソッドを使用する場合に役立ちます。この場合、トラッキングイベントをトリガーすることなく、すべてのフラグのバリエーションだけが必要になる可能性があります。トラッキングの仕組みについて詳しく知りたい場合は、[この記事](/developer-docs/feature-experimentation/technical-reference/faq-global#when-does-the-sdk-send-a-tracking-request-for-analytics) を参照してください。
##### ユーザーをターゲット化したり、レポートで訪問をフィルタリング/ブレークダウンするためのデータポイントの追加
ユーザーをターゲットにするには、フィーチャーバリエーションを取得したり、フラグがアクティブかどうかを確認したりする前に、関連するデータポイントをそのプロファイルに追加してください。これらのデータポイントをユーザーのプロファイルに追加するには、[`add_data()`](#add_data) メソッドを使用します。
他のデバイスで収集されたデータポイントを取得したり、過去のユーザーデータ(Kameleoon をハイブリッドモードで使用する場合、クライアントサイドで収集されたデータ)にアクセスしたりするには、[`get_remote_visitor_data()`](#get_remote_visitor_data) メソッドを使用します。このメソッドは、サーバーから非同期にデータを取得します。このデータは、ユーザーを特定のバリエーションに割り当てるために必要となる可能性があるため、バリエーションを取得したり、フィーチャーフラグがアクティブかどうかを確認する*前に* `get_remote_visitor_data()` を呼び出すことが重要です。
利用可能なターゲティング条件の詳細については、[このトピックに関する詳細な記事](/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) データ型を使用してボットをフィルタリングすることをお勧めします。
##### 目標コンバージョンのトラッキング
ユーザーが望ましいアクション(購入など)を完了すると、コンバージョンとして記録されます。コンバージョンを追跡するには、[`track_conversion()`](#track_conversion) メソッドを使用し、必要な `visitor_code` および `goal_id` パラメータを指定します。
コンバージョントラッキングリクエストは、SDK が定期的に送信する次のスケジュールされたトラッキングリクエスト([`tracking_interval`](#追加の構成) で定義)と共に送信されます。リクエストを即座に送信したい場合は、[`flush_instant()`](#flush) メソッドを使用してください。
##### 分析ソリューションへのイベント送信
コンバージョンをトラッキングし、露出イベントを顧客分析ソリューションに送信するには、まず Kameleoon を [ハイブリッドモード](/developer-docs/feature-experimentation/get-started/hybrid-experimentation/) で実装する必要があります。その後、[`get_engine_tracking_code()`](#get_engine_tracking_code) メソッドを使用します。
`get_engine_tracking_code()` メソッドは、露出イベントを分析ソリューションに送信するために必要な一意のトラッキングコードを取得します。このメソッドを使用すると、イベントを記録し、希望の分析プラットフォームに送信できます。
### カスタムバケットキーの使用
デフォルトでは、Kameleoon は一意の匿名訪問者 ID(`visitor_code`)を使用して、ユーザーをフィーチャーフラグバリエーションに割り当てます。この ID は通常、ユーザーのデバイスで生成され保存されます(クライアントサイドおよびサーバーサイド SDK の場合はブラウザクッキー内、モバイル SDK の場合は永続ストレージ内)。ただし、特定のシナリオでは、同じ組織のすべてのユーザーがフィーチャーフラグの同じバリアントを参照することを確認する必要がある場合があります。
**カスタムバケットキー**オプションを使用すると、バケッティング用の独自のカスタム識別子を提供することで、このデフォルトの動作を上書きできます。このオーバーライドにより、Kameleoon の割り当てロジックがデフォルトの `visitor_code` の代わりに指定されたキーを使用するようになります。
#### ユースケース
カスタムバケットキーの使用は、特に次のような状況において、フィーチャーフラグ割り当ての一貫性と正確性を維持するために不可欠です。
* **アカウントレベルまたは組織の実験:** B2B 製品や、同じ組織のすべてのユーザーを同じバリエーションに割り当てたいシナリオでは、`account_id` のような識別子を使用できます。カスタムバケットキーは、チームや会社全体に影響を与える機能の A/B テストにとって極めて重要です。
カスタムバケットキーを実装することで、実験の一貫性と正確性が向上し、より信頼性の高い結果とより良いユーザーエクスペリエンスにつながります。
#### 技術的な詳細
フィーチャーフラグのカスタムバケットキーを構成するときは、アプリケーションのデータから特定の識別子を Kameleoon に提供します。
```rust theme={null}
use kameleoon_client::data::CustomData;
client.add_data(visitor_code, [CustomData::new(42, vec!["new_visitor_code".to_owned()])])?;
```
* **カスタムキーの提供:** [`add_data()`](#add_data) メソッドを使用して、カスタム識別子を Kameleoon SDK に提供します。このメソッドでは、選択したカスタムバケットキーを [`CustomData`](#customdata) オブジェクトとして渡します。ここで、`new_visitor_code` は、バケッティングに使用したい識別子(たとえば、新しい `user_id` または `account_id`)を指します。
カスタムバケットキーが正しく機能するためには、フラグの作成または編集プロセス中に、フィーチャーフラグに対しても定義および構成される必要があります。これに対応する設定がないと、SDK のバケッティングはカスタムキーを適用しません。Kameleoon でこれを設定する方法の詳細については、この [記事](/user-manual/experimentation/feature-experimentation/create-and-manage-flags/create-a-feature-flag#Advanced_Flag_Settings) を参照してください。
* **バケッティングロジック:** `add_data()` メソッドを介してカスタムバケットキーが提供されると、ユーザーをバリエーションに割り当てるためのすべてのハッシュ計算は、デフォルトの `visitor_code` ではなく、この `new_visitor_code`(カスタムキー)を使用します。`new_visitor_code` を使用することは、バケッティングの決定がカスタム識別子に紐付けられることを意味し、その識別子が存在するさまざまなコンテキストにわたって一貫した割り当てを保証します。
* **データトラッキングと分析:** `new_visitor_code`(カスタムキー)がバケッティングの決定に使用される一方、**その後のすべてのデータ(たとえばトラッキングイベントやコンバージョン)は、*元の* `visitor_code` と共に送信および関連付けられる**ことに注意することが重要です。この分離により、バケッティングが上位レベル(アカウントなど)で実行されたり、複数のデバイス/セッションにまたがって実行されたりする場合でも、分析が個々のユーザージャーニーと、より広い実験コンテキスト内でのインタラクションを正確に反映するようになります。元の訪問者データは、包括的なレポートのために維持されます。
#### 技術要件
カスタムバケットキーを効果的に使用するには:
* キーは `&str` でなければなりません。
* バケッティングの対象となるエンティティに対して一意でなければなりません(たとえば、`user_id` を使用する場合、各ユーザーの 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 が一貫して使用されている場合、カスタムマッピング同期なしに同期が自動的に処理されます。複数のデバイス間で収集されたデータを同期したい場合は、`get_remote_visitor_data()` メソッドを呼び出すだけで十分です。
**一貫した ID を持つマルチサーバーインスタンス**
複数のサーバー(たとえば、分散サーバーインスタンス)を含む複雑な設定で、サーバー間で同じユーザー ID が利用可能な場合、サーバー間の同期(`get_remote_visitor_data()` を使用)で十分で、追加のカスタムマッピング同期は不要です。
追加データが必要なお客様は、詳細なガイダンスについて [`get_remote_visitor_data()`](#get_remote_visitor_data) メソッドの説明を参照してください。以下のコードでは、正確なデータ取得のために、2 つのデバイス間で同じ一意の識別子(この場合は `visitor_code`、`userId` とも呼ばれます)が一貫して使用されていることを前提としています。
収集したデータをリアルタイムで同期したい場合は、カスタムデータのスコープに **Visitor** を選択する必要があります。
```rust title="Device A" theme={null}
// In this example, a Custom data with index `90` was set to "Visitor" scope in Kameleoon.
use kameleoon_client::data::CustomData;
const VISITOR_SCOPE_CUSTOM_DATA_INDEX: u32 = 90;
client.add_data(visitor_code, [CustomData::new(VISITOR_SCOPE_CUSTOM_DATA_INDEX, vec!["your data".to_owned()])])?;
client.flush_instant(visitor_code).await?;
```
```rust title="Device B" theme={null}
// Before working with the data, call the `get_remote_visitor_data` method.
client.get_remote_visitor_data(visitor_code, None).await?;
// 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` を指定して [`get_remote_visitor_data()`](#get_remote_visitor_data) を呼び出すと、特定のユーザーに対するすべての既知のデータが取得されます。
同じ識別子を持つセッションは、実験において常に同じバリエーションが表示されます。実験結果ページの Visitor ビューでは、これらのセッションは単一の訪問者として表示されます。
SDK 構成により、関連するセッションは常に実験の同じバリエーションを参照することが保証されます。ただし、クロスデバイスのバリエーション割り当てに関するいくつかの制限があります。これらの制限の概要は、[こちら](/developer-docs/cross-device-experimentation#critical-points-and-practical-insights) に記載されています。
Kameleoon プラットフォームでカスタムデータを設定するには、[クロスデバイス履歴統合の有効化](#クロスデバイス実験) ガイドに従ってください。
その後、SDK を通常通り使用できます。次のメソッドはセッションマージのコンテキストで役立つ可能性があります:
* `UniqueIdentifier(true)` を追加した `get_remote_visitor_data()` - リンクされたすべての訪問者のデータを取得します。
* `UniqueIdentifier(true)` データを追加した [`track_conversion()`](#track_conversion) または [`flush()`](#flush) - 別の訪問者に関連付けられた特定の訪問者のデータを追跡します。
識別子として使用するカスタムデータは **Visitor スコープ** に設定する必要があるため、各デバイスで [`get_remote_visitor_data()`](#get_remote_visitor_data) メソッドを使用して識別子を取得するには、[クロスデバイスカスタムデータ同期](/developer-docs/cross-device-experimentation) を使用する必要があります。
以下に、セッションマージのためのカスタムデータの使用例を示します。
```rust theme={null}
// In this example, 91 represents the Custom Data's index configured as a unique identifier in Kameleoon.
use kameleoon_client::data::{CustomData, UniqueIdentifier};
const MAPPING_INDEX: u32 = 91;
const FEATURE_KEY: &str = "ff123";
let anonymous_visitor_code = "anonymous-visitor";
let user_id = "authenticated-user";
// 1. Before the visitor is authenticated
// Retrieve the variation for an unauthenticated visitor.
// Assume anonymousVisitorCode is the randomly generated ID for that visitor.
let anonymous_variation = client.get_variation(anonymous_visitor_code, FEATURE_KEY)?;
// 2. After the visitor is authenticated
// Assume `userId` is the visitor code of the authenticated visitor.
client.add_data(anonymous_visitor_code, [CustomData::new(MAPPING_INDEX, vec![user_id.to_owned()])])?;
client.flush_instant(anonymous_visitor_code).await?;
// Indicate that `userId` is a unique identifier.
client.add_data(user_id, [UniqueIdentifier::new(true)])?;
// 3. After the visitor was authorized
// Retrieve the variation for the `userId`, which will match the anonymous visitor code's variation.
let user_variation = client.get_variation(user_id, FEATURE_KEY)?;
let is_same_variation = user_variation.key.as_ref() == anonymous_variation.key.as_ref(); // true
// `userId` and `anonymousVisitorCode` are now linked and can be tracked as a single visitor.
client.track_conversion(user_id, 123)?;
// Additionally, the linked visitors share all fetched previously tracked remote data.
client.get_remote_visitor_data(user_id, None).await?;
```
この例では、アプリケーションにログインページがあります。ログイン時点ではユーザー ID が不明であるため、[`get_visitor_code()`](#get_visitor_code) メソッドによって生成された匿名訪問者識別子が使用されます。ユーザーがログインした後、匿名訪問者はユーザー ID に関連付けられ、訪問者の一意の識別子として使用されます。
### ロギング
SDK は、さまざまな内部プロセスや問題を反映するログを生成します。
#### ログレベル
SDK は、ログレベルによるロギングの制限の構成をサポートしています。
```rust theme={null}
use kameleoon_client::logging::{KameleoonLogger, LogLevel};
// The `None` log level does not allow logging.
KameleoonLogger::set_log_level(LogLevel::None);
// The `Error` log level only allows logging issues that may affect the SDK's primary behaviour.
KameleoonLogger::set_log_level(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.
KameleoonLogger::set_log_level(LogLevel::Warning);
// The `Info` log level allows logging general information on the SDK's internal processes.
// It extends the `WARNING` log level.
KameleoonLogger::set_log_level(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::set_log_level(LogLevel::Debug);
```
#### ログのカスタムハンドリング
SDK はデフォルトでログをコンソール出力に書き込みます。この動作はオーバーライドできます。
ログレベルによるロギング制限は、ログハンドリングロジックとは別に実行されます。
```rust theme={null}
use kameleoon_client::logging::{KameleoonLogger, LogLevel, Logger};
use log::{error, warn, info, debug};
pub struct CustomLogger;
impl Logger for CustomLogger {
// `log` method accepts logs from the SDK
fn log(&self, log_level: LogLevel, message: &str) {
// Custom log handling logic here. For example:
match log_level {
LogLevel::Error => error!("{}", message),
LogLevel::Warning => warn!("{}", message),
LogLevel::Info => info!("{}", message),
LogLevel::Debug => debug!("{}", message),
}
}
}
// 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::set_log_level(LogLevel::Debug); // Optional; defaults to `LogLevel.WARNING`.
KameleoonLogger::set_logger(Box::new(CustomLogger));
```
## リファレンス
これは Rust SDK の完全なリファレンスドキュメントです。
### 初期化
#### create()
SDK を使用するには、`KameleoonClientFactory::create_with_config()`/`KameleoonClientFactory::create_with_file()` を使用して `KameleoonClientConfig` インスタンスから `KameleoonClient` を作成します。
```rust theme={null}
use std::time::Duration;
use kameleoon_client::config::KameleoonClientConfigBuilder;
use kameleoon_client::factory::KameleoonClientFactory;
let config = KameleoonClientConfigBuilder::default()
.client_id("".to_owned()) // mandatory
.client_secret("".to_owned()) // mandatory
.refresh_interval(Duration::from_mins(60)) // optional (60 minutes by default)
.session_duration(Duration::from_mins(30)) // optional (30 minutes by default)
.default_timeout(Duration::from_millis(10_000)) // optional (10000 ms by default)
.tracking_interval(Duration::from_millis(1_000)) // optional (10000 ms by default)
.environment("development".to_owned()) // optional
.top_level_domain(".example.com") // mandatory if you use hybrid mode (engine or web experiments)
.proxy_host("http://192.168.0.25:8080".to_owned()) // optional
.network_domain("example.com".to_owned()) // optional
.build()
.unwrap();
let client = KameleoonClientFactory::create_with_config(site_code, config)?;
```
##### 引数
| 名前 | 型 | 説明 |
| ------------------ | ----------------------- | --------------------------------- |
| `site_code` (*必須*) | `&str` | SDK が使用する Kameleoon プロジェクトの一意のキー。 |
| `config` (*必須*) | `KameleoonClientConfig` | SDK 構成オブジェクト。 |
```rust theme={null}
use kameleoon_client::factory::KameleoonClientFactory;
let client = KameleoonClientFactory::create_with_file("a8st4f59bj", "/etc/kameleoon/client-config.json")?;
```
##### 引数
| 名前 | 型 | 説明 |
| -------------------- | ------ | --------------------------------- |
| `site_code` (*必須*) | `&str` | SDK が使用する Kameleoon プロジェクトの一意のキー。 |
| `config_path` (*必須*) | `&str` | JSON 構成ファイルへのパス。 |
##### 戻り値
| 型 | 説明 |
| ----------------------------------------- | ----------------------------- |
| `Result` | 成功時はクライアントインスタンス、それ以外は初期化エラー。 |
##### エラー
| 型 | 説明 |
| ------------------------------------- | ------------------ |
| `ErrorCode::ConfigCredentialsInvalid` | SDK の認証情報が欠落しています。 |
| `ErrorCode::SiteCodeIsEmpty` | 提供されたサイトコードが空です。 |
#### initialize()
Kameleoon クライアントの初期化を待ち、構成された [`default_timeout`](#追加の構成) または提供された `timeout` を使用します。このメソッドは、さらに操作を実行する前にクライアントが完全に初期化されていることを保証します。
```rust theme={null}
use std::time::Duration;
// Initializes the client using the configured default timeout
client.initialize().await?;
// Initializes the client with a custom timeout of 5 seconds
client.initialize_with_timeout(Duration::from_secs(5)).await?;
```
##### 引数
| 名前 | 型 | 説明 |
| ------------------- | ---------- | ----------- |
| `timeout` (*オプション*) | `Duration` | 初期化を待つ最大時間。 |
##### 戻り値
| 型 | 説明 |
| ---------------------------- | ------------------------- |
| `Result<(), KameleoonError>` | 初期化が成功したか、エラーが発生したかを示します。 |
##### エラー
| 型 | 説明 |
| --------------------------- | --------------------------- |
| `ErrorCode::Initialization` | SDK がまだ完全に初期化されていないことを示します。 |
#### is\_ready()
クライアントが初期化されているかどうかを確認します。
```rust theme={null}
if client.is_ready() {
// The client is ready
}
```
##### 戻り値
| 型 | 説明 |
| ------ | ------------------------------------- |
| `bool` | クライアントが使用可能な場合は `true`、それ以外は `false`。 |
#### forget()
指定された `site_code` に関連付けられたキャッシュされた SDK クライアントを削除します。
```rust theme={null}
use kameleoon_client::factory::KameleoonClientFactory;
// Removes the cached client for the given site code
KameleoonClientFactory::forget("a8st4f59bj")?;
// Removes the cached client for the given site code and environment
KameleoonClientFactory::forget_with_environment("a8st4f59bj", "production")?;
```
##### 引数
| 名前 | 型 | 説明 |
| ----------------------- | ------ | --------------------------- |
| `site_code` (*必須*) | `&str` | Kameleoon プロジェクトの一意の識別子。 |
| `environment` (*オプション*) | `&str` | キャッシュされたクライアントに関連付けられた環境キー。 |
##### 戻り値
| 型 | 説明 |
| ---------------------------- | ---------------------------------------- |
| `Result<(), KameleoonError>` | キャッシュされたクライアントが正常に削除されたか、エラーが発生したかを示します。 |
### フィーチャーフラグとバリエーション
#### is\_feature\_active()
* 📨 *Kameleoon にトラッキングデータを送信します(`track` オプションに応じて)*
特定のユーザーに対してフィーチャーフラグがアクティブかどうかを判断します。
訪問者がこのフィーチャーフラグに対してまだ評価されていない場合、SDK はターゲティングルールを評価して結果を返します。訪問者がすでに保存された評価を持っている場合、SDK は一貫性を確保するために既存の結果を再利用します。
Kameleoon は、`is_feature_active()`、`get_variation()` または `get_variations()` などの特定のメソッドを呼び出すときに、トラッキングを使用してセッションと訪問者をカウントします。
訪問者をバリエーションに公開し、それらをカウントする必要がある場合は、`track` パラメータにデフォルトの `true` 値を使用してください。訪問者を公開する前にこれらのメソッドを呼び出す場合のみ、`track` パラメータを `false` に設定してください。
たとえば、訪問者を公開する前にすべてのバリエーションを取得するために `get_variations()` を呼び出す場合、`track` パラメータを `false` に設定してください。この設定により、Kameleoon がセッションを早期にカウントするのを防ぎます。後で訪問者を明示的に公開するときにトラッキングをトリガーできます。
Kameleoon はデフォルトで毎秒トラッキングデータを送信します。tracking interval 構成オプションを使用して、この間隔を最大 5 秒まで設定できます。Kameleoon は、イベント間の間隔が 30 分未満である限り、トラッキングイベントを単一セッションにグループ化します。トラッキングイベント間に 30 分以上経過した場合、Kameleoon はイベントを別々のセッションとしてカウントします。訪問はセッションで最後に記録されたイベントから 30 分後にレポートに表示されます。
`is_feature_active()` メソッドは、マスターフラグ状態ではなく、提供されたバリアントを評価します。ルールを除外した場合、メソッドは **その他すべてに対して提供する** デフォルト状態を使用します。このデフォルト状態に **Off** を選択した場合、マスターフィーチャーフラグが **On** であってもメソッドは常に `false` を返します。
```rust theme={null}
use kameleoon_client::client::IsFeatureActiveOpts;
let feature_key = "new_checkout";
// Evaluates the feature flag and sends tracking data (default behavior)
let active = client.is_feature_active(visitor_code, feature_key)?;
// Evaluates the feature flag without sending tracking data
let active_without_tracking = client.is_feature_active_with_opts(
visitor_code,
feature_key,
IsFeatureActiveOpts::new().track(false),
)?;
```
##### 引数
| 名前 | 型 | 説明 | デフォルト |
| --------------------- | ------ | ---------------------------- | ------ |
| `visitor_code` (*必須*) | `&str` | ユーザーの一意の識別子。 | |
| `feature_key` (*必須*) | `&str` | ユーザーに対して評価するフィーチャーのキー。 | |
| `track` (*オプション*) | `bool` | フィーチャー評価のトラッキングを有効または無効にします。 | `true` |
##### 戻り値
| 型 | 説明 |
| ------------------------------ | ---------------------------------------------------------- |
| `Result` | 指定された `visitor_code` に対してフィーチャーフラグがアクティブかどうかを示すか、エラーを返します。 |
##### エラー
| 型 | 説明 |
| ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| `ErrorCode::Initialization` | SDK がまだ完全に初期化されていないことを示します。 |
| `ErrorCode::FeatureNotFound` | 要求されたフィーチャーキーが SDK の内部構成に見つからなかったことを示す例外。これは通常、フィーチャーフラグが Kameleoon アプリでアクティブ化されていない(ただし、フィーチャーを実装するコードはすでにアプリケーションにデプロイされている)ことを意味します。 |
| `ErrorCode::VisitorCodeInvalid` | 提供された訪問者コードが有効でないことを示す例外。空であるか、255 文字を超えています。 |
#### get\_variation()
* 📨 *Kameleoon にトラッキングデータを送信します(`track` パラメータに応じて)*
特定のフィーチャーフラグに対して、指定された訪問者に割り当てられた [`Variation`](#variation) を取得します。
このメソッドは、`visitor_code` と `feature_key` を必須引数として受け取ります。`track` 引数はオプションで、デフォルトは `true` です。
訪問者に割り当てられた `Variation` を返します。訪問者がどのフィーチャーフラグルールにも関連付けられていない場合、メソッドは指定されたフィーチャーフラグのデフォルト `Variation` を返します。
潜在的な例外を管理するため、コード内で適切なエラー処理を実装してください。
デフォルトバリエーションとは、訪問者がフィーチャーフラグの事前定義された配信ルールのいずれにも一致しない場合に割り当てられるバリエーションのことです。言い換えると、特定のルールでターゲット指定されていないすべてのユーザーに適用されるフォールバックバリエーションです。管理インターフェイスの「その他すべてのユーザーには...」セクションのバリエーションとして表されます。
```rust theme={null}
use kameleoon_client::client::GetVariationOpts;
let feature_key = "new_checkout";
// Retrieves the variation assigned to the visitor (with tracking enabled by default)
let variation = client.get_variation(visitor_code, feature_key)?;
// Retrieves the variation without sending tracking data
let variation_without_tracking = client.get_variation_with_opts(
visitor_code,
feature_key,
GetVariationOpts::new().track(false),
)?;
```
##### 引数
| 名前 | 型 | 説明 | デフォルト |
| -------------------- | ------ | -------------------------------------- | ------ |
| visitor\_code (*必須*) | `&str` | 訪問者の一意の識別子。 | |
| feature\_key (*必須*) | `&str` | 訪問者に公開したいフィーチャーのキー。 | |
| track (*オプション*) | `bool` | フィーチャー評価のトラッキングを有効または無効にするオプションのパラメータ。 | `true` |
##### 戻り値
| 型 | 説明 |
| ----------------------------------- | ------------------------------------------------------------------------ |
| `Result` | 成功時に特定のフィーチャーフラグに対して指定された訪問者に割り当てられた [`Variation`](#variation)、それ以外はエラー。 |
##### エラー
| 型 | 説明 |
| --------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| `ErrorCode::Initialization` | SDK がまだ完全に初期化されていないことを示します。 |
| `ErrorCode::VisitorCodeInvalid` | 提供された訪問者コードが有効でないことを示す例外。空であるか、255 文字を超えています。 |
| `ErrorCode::FeatureNotFound` | 要求されたフィーチャーキーが SDK の内部構成に見つからなかったことを示す例外。これは通常、フィーチャーフラグが Kameleoon アプリでアクティブ化されていない(ただし、フィーチャーを実装するコードはすでにアプリケーションにデプロイされている)ことを意味します。 |
| `ErrorCode::FeatureEnvironmentDisabled` | フィーチャーフラグが訪問者の現在の環境(たとえば、production、staging、または development)で無効になっていることを示す例外。 |
| `ErrorCode::FeatureEvaluationBlocked` | フィーチャー評価がブロックされていることを示す例外。理由はエラーメッセージに記述されています。これは通常、訪問者が法的同意を提供していない場合の GDPR 制限が原因で発生します。 |
#### get\_variations()
* 📨 *Kameleoon にトラッキングデータを送信します(`track` パラメータに応じて)*
特定の訪問者にすべてのフィーチャーフラグにわたって割り当てられた [`Variation`](#variation) オブジェクトのマップを取得します。
このメソッドは、利用可能なすべてのフィーチャーフラグを反復処理し、指定された訪問者に関連付けられた各フラグに割り当てられた `Variation` を返します。必須引数として `visitor_code` を取り、`only_active` と `track` はオプションです。
* `only_active` が `true` に設定されている場合、`get_variations()` メソッドは、ユーザーが `off` バリエーションでバケッティングされていないことを条件に、フィーチャーフラグのバリエーションを返します。
* `track` パラメータは、メソッドがバリエーション割り当てを追跡するかどうかを制御します。デフォルトでは `true` に設定されています。`false` に設定すると、トラッキングが無効になります。
返されるマップは、フィーチャーフラグキーをキーとし、対応する `Variation` を値として構成されています。フィーチャーフラグにバリエーションが割り当てられていない場合、メソッドはそのフラグのデフォルト `Variation` を返します。
潜在的な例外を管理するため、適切なエラー処理を実装する必要があります。
デフォルトバリエーションとは、訪問者がフィーチャーフラグの事前定義された配信ルールのいずれにも一致しない場合に割り当てられるバリエーションのことです。言い換えると、特定のルールでターゲット指定されていないすべてのユーザーに適用されるフォールバックバリエーションです。管理インターフェイスの「その他すべてのユーザーには...」セクションのバリエーションとして表されます。
```rust theme={null}
use kameleoon_client::client::GetVariationsOpts;
// Retrieves all variations assigned to the visitor (with default options)
let variations = client.get_variations(visitor_code)?;
// Retrieves only active variations for the visitor
let only_active_variations = client.get_variations_with_opts(
visitor_code,
GetVariationsOpts::new().only_active(true),
)?;
// Retrieves variations without sending tracking data
let variations_without_tracking = client.get_variations_with_opts(
visitor_code,
GetVariationsOpts::new().track(false),
)?;
```
##### 引数
| 名前 | 型 | 説明 | デフォルト |
| ---------------------- | ------ | ------------------------------------------------------------------------------ | ------- |
| visitor\_code (*必須*) | `&str` | 訪問者の一意の識別子。 | |
| only\_active (*オプション*) | `bool` | アクティブな(`true`)フィーチャーフラグまたはすべての(`false`)フィーチャーフラグのバリエーションを返すかどうかを示すオプションのパラメータ。 | `false` |
| track (*オプション*) | `bool` | フィーチャー評価のトラッキングを有効または無効にするオプションのパラメータ。 | `true` |
##### 戻り値
| 型 | 説明 |
| ------------------------------------------------------ | ---------------------------------------------------------------------------------------- |
| `Result, Variation>, KameleoonError>` | 成功時に対応するフィーチャーのキーを使用してフィーチャーフラグの割り当てられた [`Variation`](#variation) オブジェクトを含むマップ、それ以外はエラー。 |
##### エラー
| 型 | 説明 |
| ------------------------------- | --------------------------------------------- |
| `ErrorCode::Initialization` | SDK がまだ完全に初期化されていないことを示します。 |
| `ErrorCode::VisitorCodeInvalid` | 提供された訪問者コードが有効でないことを示す例外。空であるか、255 文字を超えています。 |
#### set\_forced\_variation()
このメソッドを使用すると、標準の評価プロセスをバイパスして、特定の [`Variation`](#variation) をユーザーにプログラム的に割り当てることができます。これは、通常の評価ロジックが不要であるか、スキップする必要がある制御された実験で特に役立ちます。デバッグやカスタムテストなどのシナリオでも役立ちます。
**強制**バリエーションが設定されると、Kameleoon のリアルタイム評価ロジックがオーバーライドされます。セグメンテーション、ターゲティング条件、アルゴリズム計算などのプロセスはスキップされます。実験中にセグメンテーションとターゲティング条件を保持するには、代わりに `force_targeting=false` を設定してください。
**シミュレートされた**バリエーションは、実行順序で常に優先されます。**シミュレートされた**バリエーション計算がトリガーされると、それが完全に処理され、最初に完了します。
強制バリエーションは、評価されたバリエーションと同じように扱われます。標準の評価されたバリエーションと同様に、分析でトラッキングされ、ユーザーコンテキストに保存され、レポートの一貫性が確保されます。
特定の条件下(たとえば、無効なパラメータ、ユーザーコンテキスト、または内部の問題)では、このメソッドが例外をスローする可能性があります。アプリケーションが安定し、回復力を維持するために、適切な例外処理が不可欠です。
**強制**バリエーションを **[シミュレートされた](#get_visitor_code)** バリエーションと区別することが重要です:
* **強制バリエーション**: 個々の実験に固有のものです。
* **シミュレートされたバリエーション**: 全体的な**フィーチャーフラグ**の結果に影響を与えます。
```rust theme={null}
use kameleoon_client::client::SetForcedVariationOpts;
let experiment_id = 202387;
// Forces the visitor into "variation_2" for the given experiment
client.set_forced_variation(visitor_code, experiment_id, Some("variation_2"))?;
// Removes any previously forced variation for the visitor in this experiment
client.set_forced_variation(visitor_code, experiment_id, None)?;
// Forces the visitor into "variation_2" with custom options
// In this case, targeting rules are respected (force_targeting = false)
client.set_forced_variation_with_opts(
visitor_code,
experiment_id,
Some("variation_2"),
SetForcedVariationOpts::new().force_targeting(false),
)?;
```
##### 引数
| 名前 | 型 | 説明 | デフォルト |
| -------------------------- | -------------- | ------------------------------------------------------------------------------------- | ------ |
| visitor\_code (*必須*) | `&str` | 訪問者の一意の識別子。 | |
| experiment\_id (*必須*) | `u32` | 評価プロセス中にターゲットされ、選択される **実験 ID**。 | |
| variation\_key (*必須*) | `Option<&str>` | 実験で返される値として強制される `Variation` に対応する **バリエーションキー**。値が `None` の場合、強制されたバリエーションはリセットされます。 | |
| force\_targeting (*オプション*) | `bool` | 実験のターゲティングを強制してスキップする(`true`)か、標準の評価プロセスのように適用する(`false`)かを示します。 | `true` |
##### 戻り値
| 型 | 説明 |
| ---------------------------- | ----------------------------------- |
| `Result<(), KameleoonError>` | 強制バリエーションが正常に設定されたか、エラーが発生したかを示します。 |
##### エラー
| 型 | 説明 |
| -------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| `ErrorCode::Initialization` | SDK がまだ完全に初期化されていないことを示します。 |
| `ErrorCode::VisitorCodeInvalid` | 提供された訪問者コードが有効でないことを示す例外。空であるか、255 文字を超えています。 |
| `ErrorCode::FeatureExperimentNotFound` | 要求された実験 ID が SDK の内部構成に見つからなかったことを示す例外。これは通常正常であり、ルールの対応する実験が Kameleoon 側でまだアクティブ化されていないことを意味します。 |
| `ErrorCode::FeatureVariationNotFound` | 要求されたバリエーションキー(ID)が SDK の内部構成に見つからなかったことを示す例外。これは通常正常であり、バリエーションの対応する実験が Kameleoon 側でまだアクティブ化されていないことを意味します。 |
#### evaluate\_audiences()
* 📨 *Kameleoon にトラッキングデータを送信します*
このメソッドは、利用可能なすべての Audiences Explorer セグメントに対して訪問者を評価し、一致する訪問者をトラッキングします。
`evaluate_audiences()` は、**関連するすべての訪問者データが設定または更新された後**、フィーチャーバリエーションを取得したりフィーチャーフラグをチェックしたりする **直前** に呼び出す必要があります。このアプローチにより、訪問者は利用可能な最新のデータに対して評価され、すべての基準に基づいて正確なオーディエンス割り当てが可能になります。
このメソッドを呼び出した後、Audiences Explorer でセグメントパフォーマンスの詳細な分析を実行できます。
```rust theme={null}
client.evaluate_audiences(visitor_code)?;
```
##### 引数
| 名前 | 型 | 説明 |
| -------------------- | ------ | ----------- |
| visitor\_code (*必須*) | `&str` | 訪問者の一意の識別子。 |
##### 戻り値
| 型 | 説明 |
| ---------------------------- | ------------------------------- |
| `Result<(), KameleoonError>` | オーディエンス評価が成功したか、エラーが発生したかを示します。 |
##### エラー
| 型 | 説明 |
| ------------------------------- | --------------------------------------------- |
| `ErrorCode::VisitorCodeInvalid` | 提供された訪問者コードが有効でないことを示す例外。空であるか、255 文字を超えています。 |
#### get\_datafile()
すべてのフィーチャーフラグを評価するには、[`get_variations()`](#get_variations) を使用してください。このメソッドは、`DataFile` を呼び出して [`get_variation()`](#get_variation) でフラグを反復処理するよりも効率的です。
現在の SDK 構成を [`DataFile`](#datafile) オブジェクトとして返します。
```rust theme={null}
let datafile = client.get_datafile()?;
```
##### 戻り値
| 型 | 説明 |
| --------------------------------------- | ------------------------------------------------ |
| `Result, KameleoonError>` | 成功時に SDK 構成を含む [`DataFile`](#datafile)、それ以外はエラー。 |
##### エラー
| 型 | 説明 |
| --------------------------- | --------------------------- |
| `ErrorCode::Initialization` | SDK がまだ完全に初期化されていないことを示します。 |
### 訪問者データ
#### get\_visitor\_code()
`get_visitor_code()` を使用して、現在の訪問者の Kameleoon `visitor_code` を取得します。このメソッドは、`CookieAccessor` トレイトを実装する任意のクッキーストアで動作します。
実装ロジックは次のとおりです:
1. SDK は、提供されたアクセサを通じて `kameleoonVisitorCode` クッキーがすでに利用可能かどうかを確認します。
2. クッキーが存在しない場合、SDK は提供された場合に `default_visitor_code` を使用します。
3. それ以外の場合、SDK は新しい訪問者コードを生成し、アクセサを介して保存します。
詳細については、[ハイブリッド実験](/developer-docs/feature-experimentation/get-started/hybrid-experimentation/) を参照してください。
独自の `visitor_code` を提供する場合、その一意性は自分の側で保証する必要があります。また、`visitor_code` の長さは `255` 文字に制限されていることに注意してください。
`get_visitor_code()` メソッドを使用すると、訪問者に **シミュレートされた** バリエーションを設定できます。クッキー(**リクエスト**または**ドキュメント**から)にキー `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) を使用してバリアントの表示をシミュレートすると、クッキーが自動的に作成されます。
* **手動で:** `kameleoonSimulationFFData` クッキーを手動で設定します。
**シミュレートされた**バリエーションを **[強制](#set_forced_variation)** バリエーションと区別することが重要です:
* **シミュレートされたバリエーション**: 全体的な**フィーチャーフラグ**の結果に影響を与えます。
* **強制バリエーション**: 個々の実験に固有のものです。
⚙️ **手動セットアップ**
`kameleoonSimulationFFData` クッキーが次の形式に従うようにしてください:
* `kameleoonSimulationFFData={"featureKey":{"expId":10,"varId":20}}`: 指定された `featureKey` の実験 `expId` のバリエーション `varId` をシミュレートします。
* `kameleoonSimulationFFData={"featureKey":{"expId":0}}`: 指定された `featureKey` のデフォルトバリエーション(**本番環境のその他全員に対して提供する** セクションで定義)をシミュレートします。
⚠️ 適切な機能を確保するため、クッキー値は [`encodeURIComponent`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/encodeURIComponent) などのメソッドを使用して URI コンポーネントとしてエンコードする必要があります。
```rust theme={null}
use std::collections::HashMap;
use kameleoon_client::cookies::CookieAccessor;
// A simple in-memory cookie store, useful for testing or non-HTTP environments
struct MemoryCookies {
values: HashMap,
}
impl CookieAccessor for MemoryCookies {
// Store the cookie value by key (max_age and top_level_domain are unused here)
fn set<'a>(&mut self, key: &str, value: &str, _max_age: u32, _top_level_domain: Option<&'a str>) {
self.values.insert(key.to_owned(), value.to_owned());
}
// Retrieve a cookie value by key
fn get(&self, key: &str) -> Option<&str> {
self.values.get(key).map(String::as_str)
}
}
// Generate or retrieve a visitor code using auto-generated value
let visitor_code = client.get_visitor_code(&mut cookies, None)?;
// Generate or retrieve a visitor code using a predefined user ID
let visitor_code = client.get_visitor_code(&mut cookies, Some("user_id"))?;
```
```rust theme={null}
use axum::{ extract::State, http::StatusCode, response::{IntoResponse, Response} };
use axum_extra::extract::cookie::{Cookie, CookieJar};
use kameleoon_client::client::KameleoonClient;
use kameleoon_client::cookies::CookieAccessor;
use time::Duration;
// Wrapper around Axum's CookieJar to implement the CookieAccessor trait
struct AxumCookies(CookieJar);
impl CookieAccessor for AxumCookies {
// Build and add a cookie with path, max_age, and optional domain, then insert into the jar
fn set<'a>(&mut self, key: &str, value: &str, max_age: u32, top_level_domain: Option<&'a str>) {
let mut builder =
Cookie::build((key.to_owned(), value.to_owned())).path("/").max_age(Duration::seconds(i64::from(max_age)));
if let Some(domain) = top_level_domain {
builder = builder.domain(domain.to_owned());
}
self.0 = std::mem::take(&mut self.0).add(builder.build());
}
// Retrieve a cookie value by key from the jar
fn get(&self, key: &str) -> Option<&str> {
self.0.get(key).map(|cookie| cookie.value())
}
}
async fn get_visitor_code(
State(client): State,
jar: CookieJar,
) -> Result<(StatusCode, CookieJar, String), Response> {
let mut cookies = AxumCookies(jar);
// Retrieve or generate a visitor code; map any SDK error to a 500 response
let visitor_code = client
.get_visitor_code(&mut cookies, None)
.map_err(|error| (StatusCode::INTERNAL_SERVER_ERROR, error.to_string()).into_response())?;
// Return the status, updated cookie jar, and visitor code in the response
Ok((StatusCode::OK, cookies.0, visitor_code))
}
```
```rust theme={null}
use actix_web::{ HttpRequest, HttpResponse, cookie::Cookie, http::{StatusCode, header}, web};
use kameleoon_client::client::KameleoonClient;
use kameleoon_client::cookies::CookieAccessor;
use kameleoon_client::error::KameleoonError;
use time::Duration;
// Holds both request cookies (read-only) and response cookies (to be set on the client)
struct ActixCookies<'a> {
request: Ref<'a, Vec>>,
response: Vec>,
}
impl CookieAccessor for ActixCookies<'_> {
// Build a cookie with path, max_age, and optional domain;
// update it if it already exists in the response, otherwise append it
fn set<'a>(&mut self, key: &str, value: &str, max_age: u32, top_level_domain: Option<&'a str>) {
let mut builder =
Cookie::build(key.to_owned(), value.to_owned()).path("/").max_age(Duration::seconds(i64::from(max_age)));
if let Some(domain) = top_level_domain {
builder = builder.domain(domain.to_owned());
}
let next_cookie = builder.finish();
match self.response.iter_mut().find(|cookie| cookie.name() == key) {
Some(cookie) => *cookie = next_cookie,
None => self.response.push(next_cookie),
}
}
// Check response cookies first, then fall back to request cookies
fn get(&self, key: &str) -> Option<&str> {
self.response
.iter()
.find(|cookie| cookie.name() == key)
.map(|cookie| cookie.value())
.or_else(|| self.request.iter().find(|cookie| cookie.name() == key).map(|cookie| cookie.value()))
}
}
fn get_visitor_code(client: web::Data, request: HttpRequest) -> Result {
// Parse cookies from the incoming request
let request_cookies = request.cookies().map_err(|error| error.to_string())?;
let mut cookies = ActixCookies {
request: request_cookies,
response: Vec::new(),
};
// Retrieve or generate a visitor code using the SDK
let visitor_code = client.get_visitor_code(&mut cookies, None)?;
// Attach any new/updated cookies to the response headers
let mut response = HttpResponse::build(StatusCode::OK);
for cookie in cookies.response {
response.append_header((header::SET_COOKIE, cookie.encoded().to_string()));
}
Ok(response.body(visitor_code))
}
```
##### 引数
| 名前 | 型 | 説明 |
| -------------------------------- | -------------------------- | -------------------------------- |
| `cookies` (*必須*) | `&mut impl CookieAccessor` | 訪問者クッキーの読み取りと保存に使用される可変クッキーアクセサ。 |
| `default_visitor_code` (*オプション*) | `Option<&str>` | クッキーが存在しない場合に使用する訪問者コード。 |
##### 戻り値
| 型 | 説明 |
| -------------------------------- | ---------------------------------------- |
| `Result` | 成功時に SDK で使用される一意の訪問者コードを表す文字列、それ以外はエラー。 |
#### add\_data()
`add_data()` メソッドは、[ターゲティングデータ](#データ型) をストレージに追加し、他のメソッドがデータを使用して現在の訪問者をターゲットにするかどうかを決定できるようにします。
`add_data()` メソッドは値を返さず、Kameleoon バックエンドサーバーとは独自に対話しません。代わりに、宣言されたすべてのデータは、[`flush()`](#flush) メソッドを使用して将来の送信のために保存されます。このアプローチでは、データは通常 `flush()` によってトリガーされる単一のサーバー呼び出しにグループ化されるため、サーバー呼び出しの数を減らすことができます。
[`track_conversion()`](#track_conversion) メソッドも、`flush()` と同様に、以前に関連付けられたデータを送信します。これは、実験ルールがトリガーされた場合の [`get_variation()`](#get_variation) および [`get_variations()`](#get_variations) メソッドにも同様に当てはまります。
ほとんどのデータ型では、各訪問者は関連付けられたデータのインスタンスを 1 つしか持てません。ただし、[`CustomData`](#customdata) は例外です。訪問者は、インデックスごとに関連付けられた `CustomData` のインスタンスを 1 つ持つことができます。
```rust theme={null}
use kameleoon_client::data::{Browser, BrowserKind, PageView, UserAgent};
client.add_data(visitor_code, [Browser::new(BrowserKind::Chrome, Some(123.0))])?;
client.add_data(
visitor_code,
[
PageView::new("https://example.com/pricing".to_owned(), Some("Pricing".to_owned()), vec![3]).into(),
UserAgent::new("Mozilla/5.0".to_owned()).into(),
],
)?;
client.add_data_with_track(
visitor_code,
vec![PageView::new("https://example.com/checkout".to_owned(), Some("Checkout".to_owned()), vec![])],
false,
)?;
```
##### 引数
| 名前 | 型 | 説明 | デフォルト値 |
| -------------------- | ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ | ------ |
| visitor\_code (*必須*) | `&str` | 訪問者の一意の識別子。 | |
| data (*必須*) | `impl IntoIterator- >` | Kameleoon データ型のコレクション。 | |
| track (*オプション*) | `bool` | 追加されたデータがトラッキング対象となるかどうかを指定します。`false` に設定すると、データはローカルに保存され、ターゲティング評価のみに使用されます。Kameleoon Data API には送信されません。 | `true` |
##### 戻り値
| 型 | 説明 |
| ---------------------------- | ----------------------------- |
| `Result<(), KameleoonError>` | データが正常に追加されたか、エラーが発生したかを示します。 |
##### エラー
| 型 | 説明 |
| ------------------------------- | --------------------------------------------- |
| `ErrorCode::Initialization` | SDK がまだ完全に初期化されていないことを示します。 |
| `ErrorCode::VisitorCodeInvalid` | 提供された訪問者コードが有効でないことを示す例外。空であるか、255 文字を超えています。 |
#### flush()
* *📨 Kameleoon にトラッキングデータを送信します*
`flush()` メソッドは、訪問者に関連付けられたすべての Kameleoon データを集約し、トラッキングリクエストをサーバーに送信します。このリクエストには、他のトラッキングメカニズム(詳細については参照されたメソッドを参照)を通じてまだ送信されていない、[`add_data`](#add_data) メソッドを介して以前に追加されたデータが含まれます。サーバー呼び出しは非同期で実行されるため、`flush()` 操作はノンブロッキングです。
このメソッドは、特定の `visitor_code` に関連付けられたデータがいつ送信されるかを制御します。たとえば、`add_data()` が複数回呼び出された場合、各呼び出し後にリクエストを送信するのは非効率的です。代わりに、これらの更新をバッチ処理し、`flush()` を 1 回呼び出して、すべての蓄積されたデータを単一のリクエストで送信できます。
`flush()` メソッドは、提供された `visitor_code` を一意の訪問者識別子として使用します。
* `flush()` — 構成されたトラッキング間隔に従ってフラッシュ操作をキューに入れます。
* `flush_instant()` — 間隔を待たずにトラッキングデータを即座に送信します。
```rust theme={null}
// Queues a flush operation for the given visitor_code.
// Data will be sent according to the configured tracking interval (non-blocking).
client.flush(visitor_code)?;
// Immediately sends all pending tracking data for the given visitor_code.
// This is an async operation and must be awaited.
client.flush_instant(visitor_code).await?;
```
##### 引数
| 名前 | 型 | 説明 |
| --------------------- | ------ | ----------- |
| `visitor_code` (*必須*) | `&str` | 訪問者の一意の識別子。 |
##### 戻り値
| 型 | 説明 |
| ---------------------------- | ------------------------------------- |
| `Result<(), KameleoonError>` | 操作が正常にスケジュールまたは実行されたか、エラーが発生したかを示します。 |
##### エラー
| 型 | 説明 |
| ------------------------------- | --------------------------------------------- |
| `ErrorCode::Initialization` | SDK がまだ完全に初期化されていないことを示します。 |
| `ErrorCode::VisitorCodeInvalid` | 提供された訪問者コードが有効でないことを示す例外。空であるか、255 文字を超えています。 |
#### get\_remote\_data()
`get_remote_data()` メソッドを使用すると、指定された `key` に対して Kameleoon サーバーに保存されているリモートデータを取得できます。ほとんどのセットアップでは、このデータは Kameleoon Data API を介して書き込まれ、追加のアプリケーションコンテキストが必要なときに後で Rust サービスによってフェッチされます。
このメソッドは、Kameleoon のリモートインフラストラクチャ上に構造化された情報を保持し、別個の取得メカニズムを維持することなくバックエンドから再利用したい場合に役立ちます。
```rust theme={null}
let data = client.get_remote_data("test-key").await?;
```
##### 引数
| 名前 | 型 | 説明 |
| ------------ | ------ | ----------------------- |
| `key` (*必須*) | `&str` | 取得したいリモートデータに関連付けられたキー。 |
##### 戻り値
| 型 | 説明 |
| -------------------------------- | ----------------------------------------------------------------------------- |
| `Result` | 成功時に指定された `key` に関連付けられたペイロード、それ以外はエラー。ほとんどの場合、ペイロードは文字列としてシリアライズされた JSON です。 |
##### エラー
| 型 | 説明 |
| --------------------------- | ------------------------------------------------- |
| `ErrorCode::Initialization` | SDK がまだ完全に初期化されていないことを示します。 |
| `ErrorCode::Network` | リモートデータリクエストが失敗するか、サーバーが非成功ステータスコードで応答した場合に返されます。 |
#### get\_remote\_visitor\_data()
`get_remote_visitor_data()` は、提供された `visitor_code` に対して Kameleoon 訪問データを取得するための非同期メソッドです。このメソッドはローカル訪問者ストレージにデータを追加し、他の SDK メソッドがターゲティングの決定にそれを使用できるようにします。
このメソッドを使用して取得したデータは、特に次の場合に役立ちます:
* 他のデバイスから収集されたデータを使用する。
* 過去の訪問から以前に表示されたページなど、訪問者の履歴にアクセスする。
* データレイヤー変数やフロントエンドの目標コンバージョンなど、クライアント側でのみ利用可能なデータを使用する。
可能なユースケースをよりよく理解するには、[この記事](/developer-docs/feature-experimentation/targeting-and-segmentation/native-segmentation) を読んでください。
デフォルトでは、`get_remote_visitor_data()` は `scope=Visitor` で最後に保存されたカスタムデータを自動的に取得し、[`add_data()`](#add_data) を呼び出さなくても訪問者にアタッチします。これは、[複数のデバイス間でのカスタムデータの同期](/developer-docs/cross-device-experimentation/) に特に役立ちます。
```rust theme={null}
use kameleoon_client::types::RemoteVisitorDataFilter;
// Fetch remote visitor data without any filter
// This will return all available data for the given visitor
client.get_remote_visitor_data(visitor_code, None).await?;
// Create a filter to limit the returned data
let filter = RemoteVisitorDataFilter {
// Include data from the last 5 visits
previous_visit_amount: 5,
// Include conversion events (e.g., goals, transactions)
conversions: true,
// Include page view history
page_views: true,
// Use default values for all other fields
..Default::default()
};
// Fetch remote visitor data using the specified filter
// This will return only the data matching the filter criteria
client.get_remote_visitor_data(visitor_code, Some(filter)).await?;
```
##### 引数
| 名前 | 型 | 説明 | デフォルト |
| --------------------- | --------------------------------- | ------------------------ | ------------------------------------ |
| `visitor_code` (*必須*) | `&str` | データをフェッチする訪問者コード。 | |
| `filter` (*オプション*) | `Option` | 取得するリモート訪問者データを記述するフィルタ。 | `RemoteVisitorDataFilter::default()` |
##### 戻り値
| 型 | 説明 |
| ---------------------------- | ---------------------------------------- |
| `Result<(), KameleoonError>` | データがフェッチされローカルに追加されたときに正常に戻ります。それ以外はエラー。 |
##### エラー
| 型 | 説明 |
| ------------------------------- | ------------------------------------------------------------ |
| `ErrorCode::Initialization` | SDK がまだ完全に初期化されていないことを示します。 |
| `ErrorCode::VisitorCodeInvalid` | 提供された訪問者コードが有効でないことを示す例外。空であるか、255 文字を超えています。 |
| `ErrorCode::Network` | リモート訪問者データリクエストが失敗するか、解析できないか、サーバーが非成功ステータスコードで応答した場合に返されます。 |
##### get\_remote\_visitor\_data() でのパラメータの使用
`get_remote_visitor_data()` メソッドを使用すると、訪問者に対してどのデータが取得されるかを制御できます。同じフィルタリングアプローチが、目標、実験、バリエーション、その他の訪問者データにわたって機能します。
たとえば、過去 5 回の訪問で目標にコンバージョンしたユーザーをターゲットにしたい場合、`previous_visit_amount` を `5` に、`conversions` を `true` に設定できます。
この例で示される柔軟性は、目標データに限定されません。フィルタを使用して、さまざまな訪問者の行動を取得し、Rust アプリケーションのターゲティングとレポーティングロジックで利用できるようにすることができます。
##### `RemoteVisitorDataFilter` フィールド
| 名前 | 型 | 説明 | デフォルト |
| ----------------------- | ------ | ------------------------------------------------- | ------- |
| `previous_visit_amount` | `u32` | データを取得する以前の訪問の数。 | `1` |
| `current_visit` | `bool` | `true` の場合、現在の訪問データが取得されます。 | `true` |
| `custom_data` | `bool` | `true` の場合、カスタムデータが取得されます。 | `true` |
| `visitor_code` | `bool` | `true` の場合、最新の訪問者コードが再利用されます。 | `true` |
| `page_views` | `bool` | `true` の場合、ページビューデータが取得されます。 | `false` |
| `geolocation` | `bool` | `true` の場合、地理位置情報データが取得されます。 | `false` |
| `device` | `bool` | `true` の場合、デバイスデータが取得されます。 | `false` |
| `browser` | `bool` | `true` の場合、ブラウザデータが取得されます。 | `false` |
| `operating_system` | `bool` | `true` の場合、オペレーティングシステムデータが取得されます。 | `false` |
| `conversions` | `bool` | `true` の場合、コンバージョンデータが取得されます。 | `false` |
| `experiments` | `bool` | `true` の場合、実験データが取得されます。 | `false` |
| `kcs` | `bool` | `true` の場合、Kameleoon Conversion Score データが取得されます。 | `false` |
| `personalizations` | `bool` | `true` の場合、パーソナライゼーションデータが取得されます。 | `false` |
| `cbs` | `bool` | true の場合、Contextual Bandit スコアデータが取得されます。 | `false` |
#### get\_visitor\_warehouse\_audience()
このメソッドは、指定された `visitor_code` と、オプションで `warehouse_key` を使用して、ウェアハウス統合内の訪問者に関連付けられたオーディエンスデータを取得します。`warehouse_key` は通常、内部ユーザー ID です。`custom_data_index` パラメータは、Kameleoon が訪問者をターゲットにするために使用する Kameleoon カスタムデータに対応します。
呼び出しが成功すると、SDK は返されたオーディエンスリストを [`CustomData`](#customdata) に変換し、訪問者にローカルに追加し、ターゲティング目的で利用可能にします。詳細については、[ウェアハウスターゲティングのドキュメント](/user-manual/integrations/data-warehouses/bigquery/use-bigquery-as-a-source-audience-targeting) を参照してください。
```rust theme={null}
// Fetch audience data for a visitor using only the visitor_code.
client.get_visitor_warehouse_audience(visitor_code, None, 98).await?;
// Fetch audience data for a visitor using both visitor_code and warehouse_key.
// Useful when your warehouse uses a different identifier than visitor_code.
client.get_visitor_warehouse_audience(visitor_code, Some("internal-user-id"), 98).await?;
```
##### 引数
| 名前 | 型 | 説明 | デフォルト |
| -------------------------- | -------------- | ----------------------------------------------------- | -------------- |
| `visitor_code` (*必須*) | `&str` | ウェアハウスオーディエンスを取得する訪問者。 | |
| `warehouse_key` (*オプション*) | `Option<&str>` | 外部ウェアハウスキー。通常は内部ユーザー ID。 | `visitor_code` |
| `custom_data_index` (*必須*) | `u32` | ウェアハウスオーディエンスターゲティング用に Kameleoon で構成されたカスタムデータインデックス。 | |
##### 戻り値
| 型 | 説明 |
| ---------------------------- | ------------------------------------------------------- |
| `Result<(), KameleoonError>` | ウェアハウスオーディエンスデータが取得され、ローカルに `CustomData` として保存されたときに成功。 |
##### エラー
| 型 | 説明 |
| ------------------------------- | --------------------------------------------------------------- |
| `ErrorCode::Initialization` | SDK がまだ完全に初期化されていないことを示します。 |
| `ErrorCode::VisitorCodeInvalid` | 提供された訪問者コードが有効でないことを示す例外。空であるか、255 文字を超えています。 |
| `ErrorCode::Network` | ウェアハウスオーディエンスリクエストが失敗するか、解析できないか、サーバーが非成功ステータスコードで応答した場合に返されます。 |
#### set\_legal\_consent()
このメソッドを使用して、訪問者が個人データの使用について法的同意を提供したかどうかを指定する必要があります。`legal_consent` を `false` に設定すると、トラッキングリクエストに含めることができるデータの種類が制限されます。これにより、訪問者データを責任を持って管理しながら、法的および規制要件を遵守できます。詳細については、[同意管理ポリシー](/user-manual/project-management/consent-management-policy) を参照してください。
クッキーアクセサを提供すると、SDK は同意ステータスに応じて訪問者のクッキーも更新します。
```rust theme={null}
// Set consent and update cookies
client.set_legal_consent(visitor_code, true, Some(&mut cookies))?;
// Set consent without updating cookies
client.set_legal_consent(visitor_code, true, None)?;
```
##### 引数
| 名前 | 型 | 説明 | デフォルト |
| ---------------------- | ---------------------------------- | ---------------------------------------------------------------------- | ------ |
| `visitor_code` (*必須*) | `&str` | ユーザーの一意の識別子。 | |
| `legal_consent` (*必須*) | `bool` | `true` は訪問者が法的同意を提供したことを示し、`false` は訪問者が法的同意を提供したことがない、または撤回したことを示します。 | |
| `cookies` (*オプション*) | `Option<&mut impl CookieAccessor>` | クッキーを更新するために使用されるオプションのクッキーアクセサ。 | `None` |
##### 戻り値
| 型 | 説明 |
| ---------------------------- | ------------------------------------ |
| `Result<(), KameleoonError>` | 訪問者の同意状態が正常に更新されたかどうかを示します。それ以外はエラー。 |
##### エラー
| 型 | 説明 |
| ------------------------------- | --------------------------------------------- |
| `ErrorCode::Initialization` | SDK がまだ完全に初期化されていないことを示します。 |
| `ErrorCode::VisitorCodeInvalid` | 提供された訪問者コードが有効でないことを示す例外。空であるか、255 文字を超えています。 |
##### 同意撤回時の動作
`legal_consent=false` で `set_legal_consent()` を呼び出した場合、SDK は `kameleoonVisitorCode` クッキーを削除しません。代わりに、クッキーの有効期限を延長することを停止し、クッキーが自然に期限切れになるまで保持されるようにします。
コンプライアンス要件によりオプトアウト時にクッキーファイルを直ちに削除する必要がある場合は、フレームワークのネイティブクッキー管理メソッドを使用して手動で削除する必要があります。SDK はファイルを自動的に削除しません。
### 目標とサードパーティ分析
#### track\_conversion()
* 📨 *Kameleoon にトラッキングデータを送信します*
このメソッドを使用して、特定の [目標](/user-manual//assets/goals/create-a-goal) とユーザーのコンバージョンをトラッキングします。このメソッドには `visitor_code` と `goal_id` が必要です。さらに、このメソッドはオプションの `revenue`、`negative`、`metadata` 引数も受け入れます。`visitor_code` は通常、実験をトリガーしたときに使用したものと同じです。
このメソッドは、サーバー呼び出しが非同期で行われるため、ノンブロッキングです。
```rust theme={null}
use kameleoon_client::client::TrackConversionOpts;
use kameleoon_client::data::CustomData;
// Track a goal
client.track_conversion(visitor_code, goal_id)?;
// Track a goal with revenue
client.track_conversion_with_opts(visitor_code, goal_id, TrackConversionOpts::new().revenue(100.0))?;
// Track a goal with negative revenue
client.track_conversion_with_opts(
visitor_code,
goal_id,
TrackConversionOpts::new().revenue(100.0).negative(true)
)?;
// Track a goal with custom metadata
client.track_conversion_with_opts(
visitor_code,
goal_id,
TrackConversionOpts::new().metadata(vec![CustomData::new(4, vec!["true".to_owned()])]),
)?;
```
##### 引数
| 名前 | 型 | 説明 | デフォルト |
| -------------------- | ----------------- | ------------------------------------------------------------------------------------------------ | -------- |
| visitor\_code (*必須*) | `&str` | 訪問者の一意の識別子。 | |
| goal\_id (*必須*) | `u32` | 目標の ID。 | |
| negative (*オプション*) | `bool` | 収益がプラスかマイナスかを定義します。 | `false` |
| revenue (*オプション*) | `f32` | コンバージョンの収益。 | `0` |
| metadata (*オプション*) | `Vec` | コンバージョンのメタデータ。[事前に Kameleoon アプリで定義する必要があります](/ja/user-manual/assets/goals/create-a-goal#メタデータ)。 | `vec![]` |
メタデータ値は [生データのエクスポート](/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 は [`add_data()`](#add_data) メソッドを使用して以前に収集された値ではなく、これらの指定された値を現在のコンバージョンに使用します。パラメータが省略されると、Kameleoon はコンバージョン前および同じ訪問内のそれらの [`CustomData`](#customdata) に対して最後にトラッキングされた値を使用します。
Kameleoon は、`track_conversion()` メソッドにパラメータとして明示的に渡されたメタデータ値のみを考慮します。
以下の例では、Kameleoon はパラメータとして明示的に提供されたカスタムデータ値(ここでは: 値 'Amex Credit Card' のインデックス 5)のみをコンバージョンに関連付けます。
```rust theme={null}
client.add_data(
visitor_code,
[
CustomData::new(5, vec!["Credit Card".to_owned()]),
CustomData::new(9, vec!["Express Delivery".to_owned()])
]
)?;
client.track_conversion_with_opts(
visitor_code,
goal_id,
TrackConversionOpts::new().metadata(vec![CustomData::new(5, vec!["Amex Credit Card".to_owned()])]),
)?
```
##### 戻り値
| 型 | 説明 |
| ---------------------------- | ---------------------------------------------------- |
| `Result<(), KameleoonError>` | コンバージョンが非同期トラッキングのために正常にキューに入れられたかどうかを示します。それ以外はエラー。 |
##### エラー
| 型 | 説明 |
| ------------------------------- | --------------------------------------------- |
| `ErrorCode::Initialization` | SDK がまだ完全に初期化されていないことを示します。 |
| `ErrorCode::VisitorCodeInvalid` | 提供された訪問者コードが有効でないことを示す例外。空であるか、255 文字を超えています。 |
#### get\_engine\_tracking\_code()
Kameleoon は、Mixpanel、Google Analytics 4、Segment など、いくつかの分析ソリューションと統合しています。サーバーサイド実験を正しくトラッキングするには、訪問者が実験をトリガーした後に `get_engine_tracking_code()` メソッドを呼び出します。SDK は、訪問者が過去 5 秒間にトリガーした実験の JavaScript キューコマンドを返します。このコードをページに挿入すると、Engine.js がコマンドを処理し、アクティブな分析統合を介して露出イベントを送信します。
このメソッドの実装に関する詳細は、[ハイブリッド実験](/developer-docs/feature-experimentation/get-started/hybrid-experimentation) を参照してください。
```rust theme={null}
let tracking_code = client.get_engine_tracking_code(visitor_code)?;
```
* この機能を使用するには、Rust 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 の `