> ## 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. # Flutter SDK > Kameleoon Flutter SDK を統合して、Flutter フレームワークが対象とするすべてのプラットフォーム上で実験を実行し、機能フラグを有効化します。 Kameleoon Flutter SDK を使用すると、Flutter アプリケーションフレームワークが対象とするすべてのプラットフォームで実験を実行し、機能フラグを有効化できます。SDK をアプリケーションに統合するのは簡単で、メモリやネットワーク使用量の面でもフットプリントは小さいです。 **はじめに**: 始め方については、[開発者ガイド](#開発者ガイド)を参照してください。 **変更履歴**: Flutter SDK の最新バージョン: 3.7.0 [変更履歴](https://github.com/Kameleoon/client-flutter/blob/master/CHANGELOG.md)。 **SDK メソッド**: Flutter SDK メソッドの完全なリファレンスドキュメントについては、[リファレンス](#リファレンス)セクションを参照してください。 ## 開発者ガイド ### はじめに このガイドでは、SDK を統合し、Flutter アプリケーションで実験を実行する方法を説明します。このチュートリアルでは、異なるバリエーションに基づいて推奨商品の数を変更する単純な A/B テストのセットアップについて説明します。 #### Flutter クライアントのインストール Kameleoon Flutter クライアントをインストールするには、`pubspec.yaml` ファイルに依存関係を宣言します。 ```ruby theme={null} kameleoon_client_flutter: ^3.0.0 ``` **release** モードでは、JS ライブラリは自動的に読み込まれます。ただし、**debug** モードでは、(Dart Development Compiler により) JS ライブラリのインポート時に問題が発生する可能性があります。潜在的な問題を回避するため、JS ライブラリを明示的にインポートすることを強く推奨します。 `index.html` の `` セクションに次のスクリプト行を追加してください。 ```html theme={null} ``` #### Kameleoon クライアントの初期化 SDK をアプリケーションにインストールし、Kameleoon アプリでサーバーサイド実験をセットアップしたら、次のステップは Kameleoon クライアントの作成です。 `KameleoonClient` は (`siteCode` ごとに) シングルトンオブジェクトであり、アプリケーションと Kameleoon プラットフォームの間のブリッジとして機能します。実験を実行するために必要なすべてのメソッドとプロパティが含まれています。 ```dart theme={null} import 'package:kameleoon_client_flutter/kameleoon_client_flutter.dart'; class _HomePage extends State { KameleoonClient kameleoonClient @override void initState() { super.initState(); try { // pass client configuration and visitorCode as arguments final config = KameleoonClientConfig( refreshIntervalMinutes: 15, // 60 minutes by default, optional defaultTimeoutMilliseconds: 10000, // 10_000 milliseconds by default, optional dataExpirationIntervalMinutes: 1440 * 365, // infinity by default, optional trackingIntervalMilliseconds: 500, // 1000 milliseconds by default, optional environment: "staging", // optional isUniqueIdentifier: false, // false by default, optional domain: "example.com", // web only option, optional networkDomain: "company.com", // web only option, optional defaultDataFile: "{...}" // optional ); final visitorCode = "yourVisitorCode"; final kameleoonClient = KameleoonClientFactory.create(siteCode, visitorCode: visitorCode, config: config); // or, if you want, visitor code will be generated automatically final kameleoonClient = KameleoonClientFactory.create(siteCode, config: config); } on SiteCodeIsEmpty catch (ex) { // Exception indicates that the provided siteCode is empty } on VisitorCodeInvalid catch (ex) { // Exception indicates that the provided visitorCode is invalid } on Exception catch (ex) { // Any other error } } } ``` `KameleoonClientFactory.create()` メソッドは実行時にクライアントを初期化しますが、Kameleoon クライアントは Kameleoon リモートサーバーから機能フラグの現在の構成 (およびそのトラフィック配分) を取得する必要があるため、すぐに使用できる状態にはなりません。この取得にはネットワークアクセスが必要であり、常に利用できるとは限りません。Kameleoon クライアントが完全に準備できるまで、Kameleoon Android SDK の他のメソッドを実行しようとしないでください。なお、機能フラグの最初の構成が取得されると、定期的に更新されますが、何らかの理由で更新が失敗しても、Kameleoon クライアントは以前の構成を使用して引き続き機能します。 [`isReadyAsync()`](#isreadyasync) メソッドを使用して、Kameleoon クライアントの初期化が完了したかどうかを確認できます。 または、**ヘルパーコールバック**で機能フラグのトリガーとバリエーション実装のロジックをカプセル化できます。最適なアプローチ ([`isReadyAsync()`](#isreadyasync) または **コールバック**) は、好みや具体的なユースケースによって異なります。SDK がすぐに使用可能になる見込みがある場合は [`isReadyAsync()`](#isreadyasync) を使用してください。たとえば、アプリ内のナビゲーション開始から数秒〜数分の間にユーザーがアクセスする可能性が低いダイアログ上で機能フラグを実行する場合は、`isReadyAsync()` が適しています。SDK が依然として初期化中である可能性が高い場合は、コールバックの使用を推奨します。たとえば、アプリケーション起動時に画面に表示される機能フラグでは、SDK が準備完了になるか指定したタイムアウトが経過するまでアプリケーションを待機させるコールバックを使用するべきです。 Kameleoon を使用した A/B テストの文脈の中でアプリケーションコードのロジックが正しいことを保証するのは、アプリ開発者であるあなたの責任です。良い慣行として、Kameleoon クライアントがまだ準備できていない場合、アプリケーションユーザーが機能フラグから除外される可能性があると常に想定することです。この除外は、デフォルトまたはリファレンスバリエーションのロジック実装に対応するため、簡単に実装できます。次の段落のコードサンプルは、このアプローチの例を示しています。 これで、機能管理と機能フラグを実装する準備が整いました。追加のメソッドの詳細については、[リファレンス](#リファレンス)セクションを参照してください。 #### 機能フラグの有効化 ##### フラグ構成の取得 コード内に機能フラグを実装するには、まず Kameleoon アカウントで [機能フラグ](/user-manual/experimentation/feature-experimentation/create-and-manage-flags/create-a-feature-flag) を作成する必要があります。 特定のユーザーに対して機能フラグがアクティブかどうかを判定するには、その構成を取得する必要があります。[`getFeatureVariationKey()`](#getfeaturevariationkey) または [`isFeatureActive()`](#isfeatureactive) メソッドを使用して、`featureKey` に基づいて構成を取得します。 複数のバリエーションやターゲティングオプションを持つより複雑な機能フラグとは対照的に、ON または OFF の状態のみを持つ単純な機能フラグの構成を取得したい場合は、`isFeatureActive()` メソッドを使用してください。 `getFeatureVariationKey()` メソッドは、複数の機能バリエーションを持つ機能実験の構成を取得します。このメソッドを使用して、必須の引数として `visitorCode` と `featureKey` を指定することにより、特定のユーザーのバリエーションキーを取得できます。 機能フラグには、その動作をカスタマイズするために使用される関連変数を持たせることができます。これらの変数を取得するには、ユーザーの `variationKey` を取得する必要があるため、`getFeatureVariationKey()` を呼び出した後に [`getFeatureVariationVariables()`](#getfeaturevariationvariables) メソッドを使用してください。 機能フラグがアクティブかどうかを確認するには、**1 つの**メソッドのみを使用すれば十分です。機能フラグがオンかオフかを知りたい場合は `isFeatureFlagActive` を選択してください。機能の動作を動的に変更するなど、より複雑なシナリオには `getFeatureFlagVariables` を使用してください。 ##### ユーザーをターゲットしたり、レポート内で訪問をフィルター/分解するためのデータポイントの追加 ユーザーをターゲットするには、機能バリエーションを取得したりフラグがアクティブかどうかを確認したりする前に、関連するデータポイントをそのプロフィールに追加していることを確認してください。これらのデータポイントをユーザーのプロフィールに追加するには [`addData()`](#adddata) メソッドを使用します。 他のデバイスで収集されたデータポイントを取得する、または過去のユーザーデータ (Kameleoon をハイブリッドモードで使用しているときにクライアントサイドで収集) にアクセスするには、[`getRemoteVisitorData()`](#getremotevisitordata) メソッドを使用します。このメソッドは、サーバーから非同期にデータを取得します。このデータは、機能フラグの特定のバリエーションへのユーザー割り当てに必要となる可能性があるため、バリエーションを取得したり機能フラグがアクティブかどうかを確認したりする**前に** `getRemoteVisitorData()` を呼び出してください。 利用可能なターゲティング条件の詳細については、[このトピックの詳細記事](/developer-docs/feature-experimentation/targeting-and-segmentation/native-segmentation)を参照してください。 さらに、訪問者プロフィールに追加するデータポイントは、実験を分析する際に利用できるため、デバイスやブラウザなどの要素で結果をフィルタリングおよび分解することができます。保存されたデータを Kameleoon サーバーに送信するには、`flush()` メソッドを呼び出すことを忘れないでください。 自動的に収集されるもの以外の追加データポイントを追跡する必要がある場合は、Kameleoon の [カスタムデータ機能](#customdata)を使用できます。カスタムデータを使用すると、実験に関連する特定の情報をキャプチャして分析できます。収集したデータを分析のために Kameleoon サーバーに送信するには、`flush()` メソッドを呼び出すのを忘れないでください。 ##### フラグの露出とゴールコンバージョンの追跡 Kameleoon は、次のいずれかのメソッドを呼び出すとすぐに、訪問者のフラグへの露出を自動的に追跡します。 * `getFeatureVariationKey()` * `getFeatureVariable()` * `isFeatureActive()` ユーザーが目的のアクション (たとえば、購入) を完了すると、コンバージョンとしてカウントされます。コンバージョンを追跡するには、[`trackConversion()`](#trackconversion) メソッドを使用し、`visitorCode` と `goalId` パラメータを指定する必要があります。 ### カスタムバケッティングキーの使用 デフォルトでは、Kameleoon は一意の匿名訪問者 ID (`visitorCode`) を使用して、ユーザーを機能フラグのバリエーションに割り当てます。この ID は通常、ユーザーのデバイス上で生成および保存されます (クライアントサイドおよびサーバーサイド SDK ではブラウザ Cookie に、モバイル SDK では永続ストレージに保存)。ただし、特定のシナリオでは、同じ組織のすべてのユーザーが機能フラグの同じバリアントを見るようにする必要がある場合があります。 **カスタムバケッティングキー**オプションを使用すると、独自のカスタムバケッティング識別子を提供することで、このデフォルトの動作をオーバーライドできます。このオーバーライドにより、Kameleoon の割り当てロジックがデフォルトの `visitorCode` ではなく、指定したキーを使用するようになります。 #### ユースケース カスタムバケッティングキーの使用は、特に次のような状況において、機能フラグの割り当ての一貫性と正確性を維持するために不可欠です。 * **アカウントレベルまたは組織レベルの実験:** B2B 製品や、同じ組織のすべてのユーザーを同じバリエーションに割り当てたいシナリオでは、`accountId` のような識別子を使用できます。カスタムバケッティングキーは、チームや会社全体に影響を与える機能の A/B テストには不可欠です。 カスタムバケッティングキーを実装することにより、実験の一貫性と正確性が向上し、より信頼性の高い結果と優れたユーザーエクスペリエンスが得られます。 #### 技術的な詳細 機能フラグにカスタムバケッティングキーを設定する際は、アプリケーションのデータから特定の識別子を Kameleoon に提供します。 ```dart theme={null} try { await kameleoonClient.addData(CustomData.withIndex(index, values: ["newVisitorCode"])) } on KameleoonException { // Generic exception in native plugin integration occurred. } ``` * **カスタムキーの提供:** [`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 は、ログレベルによるロギングの制限の設定をサポートしています。 ```dart theme={null} // The `none` log level does not allow logging. KameleoonLogger.setLogLevel(LogLevel.none); // The `error` log level only allows logging issues that may affect the SDK's main behaviour. KameleoonLogger.setLogLevel(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.setLogLevel(LogLevel.warning); // The `info` log level allows logging general information on the SDK's internal processes. // It extends the `warning` log level. KameleoonLogger.setLogLevel(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 support // to assist with internal troubleshooting. KameleoonLogger.setLogLevel(LogLevel.debug); ``` #### ログのカスタムハンドリング SDK はデフォルトでログをコンソール出力に書き込みます。この動作はオーバーライドできます。 ログレベルによるロギング制限は、ログハンドリングロジックとは別に実行されます。 ```dart theme={null} import 'package:logging/logging.dart' as logging; class CustomLogger extends Logger { final logger = logging.Logger("CustomLogger"); // `log` method accepts logs from the SDK @override void log(LogLevel level, String message) { // Custom log handling logic here. For example: switch (level) { case LogLevel.error: logger.severe(message); break; case LogLevel.warning: logger.warning(message); break; case LogLevel.info: logger.info(message); break; case LogLevel.debug: logger.fine(message); break; default: 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(CustomLogger()); ``` ### エラーハンドリング エラーをハンドリングすることは、アプリケーションをより安定させ、技術的な問題を回避するためのベストプラクティスとされています。ほとんどの `KameleoonClient` メソッドは `KameleoonException` エラーをスローする可能性があります。 Android クライアント側で SDK のバージョンをパッチするのが難しい場合があるため、その他の致命的なエラーを防ぐために、`KameleoonException` および `Throwable` エラータイプをキャッチする `try` 句で各 SDK メソッドを囲むことを推奨します。 例: ```dart theme={null} try { // Calling a method of the SDK } on KameleoonException { // Handling expected exceptions } on Exception { // Any other error } ``` ## リファレンス これは Flutter SDK の完全なリファレンスドキュメントです。 ### 初期化 アプリケーションに [SDK をインストール](#flutter-クライアントのインストール)したら、Kameleoon を初期化する必要があります。実験のトリガーなど、アプリケーションと SDK の間のすべてのやり取りは、この Kameleoon クライアントオブジェクトを使用して行われます。 #### create() SDK を初期化するために、他のどのメソッドよりも先にこのメソッドを呼び出します。このメソッドは `KameleoonClientFactory` に含まれています。アプリは、このメソッドが作成する `KameleoonClient` オブジェクトを使用して SDK とのすべてのやり取りを行います。 [設定オブジェクト](#additional-configuration)を提供することで、SDK の動作 (たとえば、環境や認証情報など) をカスタマイズできます。それ以外の場合、SDK は設定ファイルを検出して代わりに使用しようとします。 ```dart theme={null} import 'package:kameleoon_client_flutter/kameleoon_client_flutter.dart' final siteCode = "a8st4f59bj"; try { // pass client configuration and visitorCode as arguments final config = KameleoonClientConfig( refreshIntervalMinutes: 15, // 60 minutes by default, optional defaultTimeoutMilliseconds: 10000, // 10_000 milliseconds by default, optional dataExpirationIntervalMinutes: 1440 * 365, // infinity by default, optional trackingIntervalMilliseconds: 500, // 1000 milliseconds by default, optional environment: "staging", // optional isUniqueIdentifier: false, // false by default, optional domain: "example.com" // web only option, optional networkDomain: "company.com", // web only option, optional defaultDataFile: "{...}" // optional ); final visitorCode = "yourVisitorCode"; final kameleoonClient = KameleoonClientFactory.create(siteCode, visitorCode: visitorCode, config: config); } on SiteCodeIsEmpty catch (ex) { // Exception indicates that the provided siteCode is empty } on VisitorCodeInvalid catch (ex) { // Exception indicates that the provided visitorCode is invalid } on Exception catch (ex) { // Any other error } try { // generate visitorCode automatically and use default Kameleoon client config final kameleoonClient = KameleoonClientFactory.create(siteCode); } on SiteCodeIsEmpty catch (ex) { // Exception indicates that the provided siteCode is empty } on Exception catch (ex) { // Any other error } ``` ##### 引数 | 名前 | 型 | 説明 | デフォルト | | ------------------ | ----------------------- | ------------------------------------------------------------------------------------- | ----- | | siteCode (*必須*) | `String` | SDK で使用される Kameleoon プロジェクトを識別する [一意のキー](/user-manual/faq#how-do-i-find-my-sitecode)。 | | | visitorCode (*任意*) | `String` | 任意の訪問者識別子。利用可能な場合は、内部の **ユーザー ID** を使用してください。それ以外の場合は、SDK が自動的に生成します。 | `nil` | | config (*任意*) | `KameleoonClientConfig` | SDK 設定が提供されない場合、SDK は自動的にデフォルト設定を使用します。 | `nil` | ##### 戻り値 | 型 | 説明 | | ----------------- | ------------------------------------------------------- | | `KameleoonClient` | アプリが実験や機能フラグを管理するために使用できる `KameleoonClient` クラスのインスタンス。 | ##### スローされる例外 | 型 | 説明 | | -------------------- | --------------------------------------------- | | `VisitorCodeInvalid` | 提供された訪問者コードが有効でないことを示す例外。空であるか、255 文字を超えています。 | | `SiteCodeIsEmpty` | 指定されたサイトコードが無効な値である空文字列であることを示す例外。 | #### isReadyAsync() モバイル SDK の場合、Kameleoon クライアントはアクティブな機能フラグの現在の構成を取得するためにサーバーコールを実行する必要があるため、すぐには初期化できません。機能フラグをトリガーする前にこのメソッドを呼び出して、SDK の準備ができているかどうかを確認するには、`isReadyAsync()` を使用します。 または、コールバックを使用することもできます (詳細は [`runWhenReady()`](#runwhenready) メソッドを参照してください)。 ```dart theme={null} final ready = kameleoonClient.isReadyAsync(); ``` ##### 戻り値 | 名前 | 型 | 説明 | | ----- | ---- | -------------------------------------------- | | ready | bool | SDK のステータス (適切に初期化されているか、まだ使用できないか) を表すブール値。 | #### runWhenReady() モバイル SDK の場合、Kameleoon クライアントはすべてのアクティブな機能フラグの現在の構成を取得するためにサーバーコールを実行する必要があるため、すぐには初期化できません。SDK が使用可能になり次第実行されるコールバックを渡すには、`KameleoonClient` クラスの [`runWhenReady()`](#runwhenready) メソッドを使用します。タイムアウトも設定できます。 このメソッドの最初の引数として与えられるコールバックは、`Function(bool ready)` のタイプのインスタンスでなければなりません。`ready` が `true` の場合、Kameleoon クライアントは準備完了であり、機能フラグをトリガーしてバリエーションを実装するコードを含む必要があります。それ以外の場合、クライアントが初期化される前に指定されたタイムアウトが発生します。タイムアウトが発生するとユーザーは機能フラグから除外されるため、コールバックにはリファレンスバリエーションを実装するコードを含める必要があります。 ```dart theme={null} kameleoonClient.runWhenReady((ready) async { final defaultProductsNumber = 5; if (ready) { late int recommendedProductsNumber; try { recommendedProductsNumber = await kameleoonClient.getFeatureVariable("feature_key", "product_number"); } on Exception { recommendedProductsNumber = defaultProductsNumber; } } else { recommendedProductsNumber = defaultProductsNumber; } setState(() { _recommendedProductsNumber = recommendedProductsNumber; }); }, 2000); ``` ##### 引数 | 名前 | 型 | 説明 | | --------------- | ---------------- | ------------------------------------------------------------------------------------------------------ | | callback (*必須*) | `Function(bool)` | `ready` フラグを持つコールバックオブジェクト。 | | timeout (*任意)* | `Duration` | タイムアウト (ミリ秒単位)。指定されない場合は、デフォルト値の `defaultTimeoutMilliseconds` (`KameleoonClientConfig` から) ミリ秒が使用されます。 | ### 機能フラグとバリエーション #### isFeatureActive() * 📨 *Kameleoon にトラッキングデータを送信します* 機能トグルを有効化するには、このメソッドを呼び出します。このメソッドは、指定した機能が訪問者に対してアクティブかどうかを確認するために、必須の引数として `featureKey` を受け取ります。 訪問者がこれまでこの機能フラグに関連付けられていない場合、メソッドはランダムなブール値 (訪問者にこの機能を表示する必要がある場合は `true`、それ以外の場合は `false`) を返します。訪問者がすでにこの機能フラグに登録されている場合、このメソッドは以前の機能フラグの値を返します。 例コードに示されているように、潜在的な例外をキャッチするための適切なエラーハンドリングを設定してください。 Kameleoon は、`isFeatureActive()`、`getVariation()`、`getVariations()` などの特定のメソッドを呼び出すと、セッションと訪問者をカウントするためにトラッキングを使用します。 訪問者をバリエーションに露出させて、カウントする必要がある場合は、`track` パラメータにデフォルトの `true` 値を使用してください。訪問者を露出させる前にこれらのメソッドを呼び出す場合にのみ、`track` パラメータを `false` に設定してください。 たとえば、訪問者を露出させる前にすべてのバリエーションを取得するために `getVariations()` を呼び出す場合、`track` パラメータを `false` に設定してください。この設定により、Kameleoon がセッションを早期にカウントすることを防ぎます。その後、訪問者を明示的に露出させる際に、後でトラッキングをトリガーできます。 Kameleoon はデフォルトで 1 秒ごとにトラッキングデータを送信します。トラッキング間隔の設定オプションを使用して、最大 5 秒までこの間隔を設定できます。Kameleoon は、イベント間の間隔が 30 分未満である限り、トラッキングイベントを 1 つのセッションとしてグループ化します。トラッキングイベント間で 30 分以上経過すると、Kameleoon はイベントを個別のセッションとしてカウントします。訪問は、セッションで最後に記録されたイベントから 30 分後にレポートに表示されます。 ```dart theme={null} String featureKey = "new_checkout"; bool hasNewCheckout = false; try { hasNewCheckout = await kameleoonClient.isFeatureActive(featureKey); } on SDKNotReady { // Exception indicates that the SDK has not completed its initialization yet. } on FeatureNotFound { // The error has occurred; feature flag isn't found in current configuration. } on KameleoonException { // Generic exception in native plugin integration occurred. } on Exception { // Any other error } if (hasNewCheckout) { // Implement new checkout code here } ``` `isFeatureActive()` メソッドは、マスターフラグの状態ではなく、配信されるバリアントを評価します。ルールを除外する場合、メソッドは **その他すべての訪問者に対して提供する** デフォルト状態を使用します。このデフォルト状態に **Off** を選択している場合、マスター機能フラグが **On** であっても、メソッドは常に `false` を返します。 ##### 引数 | 名前 | 型 | 説明 | | ---------- | -------- | ----------------------------------------------- | | featureKey | `String` | ユーザーに公開したい機能の一意のキー。このフィールドは必須です。 | | track | `bool` | 機能評価のトラッキングを有効または無効にする任意のパラメータ (デフォルトは `true`)。 | ##### 戻り値 | 型 | 説明 | | -------------- | ----------------- | | `Future` | 訪問者に対して登録された機能の値。 | ##### スローされる例外 | 型 | 説明 | | ----------------- | ---------------------------------------------------------------------------------------------------------------------------- | | SDKNotReady | SDK が初期化を完了していないことを示す例外。 | | FeatureNotFound | 要求された機能 ID が SDK の内部設定で見つからなかったことを示す例外。この例外は通常、機能フラグが Kameleoon 側で有効化されていない (ただし、機能を実装するコードはすでにアプリケーションにデプロイされている) ことを意味します。 | | PlatformException | ネイティブプラグインの統合が正しく機能していないことを示す例外。 | #### getVariation() * 📨 *Kameleoon にトラッキングデータを送信します (`track` パラメータによる)* 特定の機能フラグについて、指定された訪問者に割り当てられた [`Variation`](#variation) を取得します。 このメソッドは、`visitorCode` と `featureKey` を必須の引数として受け取ります。`track` 引数は任意で、デフォルトは `true` です。 訪問者に割り当てられた `Variation` を返します。訪問者が機能フラグルールに関連付けられていない場合、メソッドは指定された機能フラグのデフォルト `Variation` を返します。 潜在的な例外を管理するための適切なエラーハンドリングをコードに実装してください。 デフォルトバリエーションとは、訪問者が機能フラグの事前定義された配信ルールのいずれにも一致しない場合に割り当てられるバリエーションを指します。言い換えれば、特定のルールでターゲットされていないすべてのユーザーに適用されるフォールバックバリエーションです。これは、管理インターフェースの「その他すべての訪問者に対しては...」セクションのバリエーションとして表されます。 ```dart theme={null} final String featureKey = "featureKey"; Variation? variation; try { variation = await client.getVariation(featureKey); // disabling tracking variation = await client.getVariation(featureKey, track: false); } on SDKNotReady { // Exception indicating that the SDK has not completed its initialization yet. } on FeatureNotFound { // The feature key is not in the configuration file that has been fetched by the SDK. } on FeatureEnvironmentDisabled { // The feature flag is disabled for the environment. } String? 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` | ##### 戻り値 | 型 | 説明 | | ------------------- | ------------------------------------------------------- | | `Future` | 特定の機能フラグについて指定された訪問者に割り当てられた [`Variation`](#variation)。 | ##### スローされる例外 | 型 | 説明 | | ---------------------------- | -------------------------------------------------------------------------------------------------------------------------- | | `VisitorCodeInvalid` | 提供された訪問者コードが有効でないことを示す例外。空であるか、255 文字を超えています。 | | `FeatureNotFound` | 要求された機能キーが SDK の内部設定で見つからなかったことを示す例外。これは通常、機能フラグが Kameleoon アプリで有効化されていない (ただし、機能を実装するコードはすでにアプリケーションにデプロイされている) ことを意味します。 | | `FeatureEnvironmentDisabled` | 訪問者の現在の環境 (たとえば、production、staging、development) で機能フラグが無効になっていることを示す例外。 | #### getVariations() * 📨 *Kameleoon にトラッキングデータを送信します (`track` パラメータによる)* すべての機能フラグにわたって、指定された訪問者に割り当てられた [`Variation`](#variation) オブジェクトのマップを取得します。 このメソッドは、利用可能なすべての機能フラグを反復処理し、指定された訪問者に関連付けられた各フラグに割り当てられた `Variation` を返します。任意の引数として `onlyActive` と `track` を取ります。 * `onlyActive` が `true` に設定されている場合、`getVariations()` メソッドは、ユーザーが `off` バリエーションにバケッティングされていない限り、機能フラグのバリエーションを返します。 * `track` パラメータは、メソッドがバリエーション割り当てをトラッキングするかどうかを制御します。デフォルトでは `true` に設定されています。`false` に設定すると、トラッキングは無効化されます。 返されるマップは、機能フラグキーをキーとし、対応する `Variation` を値として持ちます。機能フラグにバリエーションが割り当てられていない場合、メソッドはそのフラグのデフォルト `Variation` を返します。 潜在的な例外を管理するために、適切なエラーハンドリングを実装する必要があります。 デフォルトバリエーションとは、訪問者が機能フラグの事前定義された配信ルールのいずれにも一致しない場合に割り当てられるバリエーションを指します。言い換えれば、特定のルールでターゲットされていないすべてのユーザーに適用されるフォールバックバリエーションです。これは、管理インターフェースの「その他すべての訪問者に対しては...」セクションのバリエーションとして表されます。 ```dart theme={null} try { Map variations = await kameleoonClient.getVariations(); // only active variations Map variations = await kameleoonClient.getVariations(onlyActive: true); // disable tracking Map variations = await kameleoonClient.getVariations(onlyActive: false, track: false); } on SDKNotReady { // Exception indicating that the SDK has not completed its initialization yet. } ``` ##### 引数 | 名前 | 型 | 説明 | デフォルト | | ----------------- | ------ | ----------------------------------------------------------------------- | ------- | | onlyActive (*任意*) | `bool` | アクティブな (`true`) 機能フラグまたはすべての (`false`) 機能フラグのバリエーションを返すかどうかを示す任意のパラメータ。 | `false` | | track (*任意*) | `bool` | 機能評価のトラッキングを有効または無効にする任意のパラメータ。 | `true` | ##### 戻り値 | 型 | 説明 | | -------------------------------- | ------------------------------------------------------------------- | | `Future>` | 対応する機能のキーを使用して機能フラグの割り当てられた [`Variation`](#variation) オブジェクトを含むマップ。 | ##### スローされる例外 | 型 | 説明 | | ------------- | --------------------------- | | `SDKNotReady` | SDK がまだ完全に初期化されていないことを示します。 | #### getFeatureList() SDK で現在利用可能な機能フラグキーのリストを返します。 ```dart theme={null} try { final allFeatureFlagKeys = await kameleoonClient.getFeatureList(); } on KameleoonException { // Generic exception in native plugin integration occurred. } ``` ##### 戻り値 | 型 | 説明 | | ---------------------- | ----------- | | `Future>` | 機能フラグキーのリスト | #### getDataFile() すべての機能フラグを評価するには、[`getVariations()`](#getvariations) を使用します。このメソッドは、`DataFile` を呼び出してフラグを [`getVariation()`](#getvariation) で反復処理するよりも効率的です。 現在の SDK 設定を [`DataFile`](#datafile) オブジェクトとして返します。 ```dart theme={null} try { final dataFile = await kameleoonClient.getDataFile(); final dateModified = dataFile.dateModified; } on KameleoonException { // Generic exception in native plugin integration occurred. } ``` ##### 戻り値 | 型 | 説明 | | ---------- | --------------------------------- | | `DataFile` | SDK 設定を含む [`DataFile`](#datafile) | ##### スローされるエラー | 型 | 説明 | | ------------- | --------------------------- | | `SDKNotReady` | SDK がまだ完全に初期化されていないことを示します。 | #### setForcedVariation() このメソッドを使用すると、標準的な評価プロセスをバイパスして、特定の [`Variation`](#variation) をユーザーにプログラム的に割り当てることができます。これは、通常の評価ロジックが不要、またはスキップする必要がある制御された実験において特に有用です。デバッグやカスタムテストなどのシナリオでも役立ちます。 **強制**バリエーションが設定されると、Kameleoon のリアルタイム評価ロジックがオーバーライドされます。セグメンテーション、ターゲティング条件、アルゴリズム計算などのプロセスはスキップされます。実験中のセグメンテーションとターゲティング条件を維持するには、代わりに `forceTargeting=false` を設定してください。 強制バリエーションは、評価されたバリエーションと同様に扱われます。標準的に評価されたバリエーションと同様に分析データに追跡され、ユーザーコンテキストに保存されるため、レポートの一貫性が確保されます。 このメソッドは、特定の条件下 (例: 無効なパラメータ、ユーザーコンテキスト、内部の問題) で例外をスローする可能性があります。アプリケーションが安定して回復力を保つために、適切な例外処理が不可欠です。 ```dart theme={null} final experimentId = 9516; try { // Forcing the variation "on" for the experiment 9516 for the visitor await kameleoonClient.setForcedVariation(experimentId, "on") // Forcing the variation "on" while preserving segmentation and targeting conditions during the experiment await kameleoonClient.setForcedVariation(experimentId, "on", forceTargeting: false) // Resetting the forced variation for the experiment 9516 for the visitor await kameleoonClient.setForcedVariation(experimentId, null); } on KameleoonException { // Handling the exception } ``` ##### 引数 | 名前 | 型 | 説明 | デフォルト | | --------------------- | -------- | -------------------------------------------------------------------------------- | ------ | | experimentId (*必須*) | `int` | 評価プロセス中にターゲットされ、選択される **実験 ID**。 | | | variationKey (*必須*) | `String` | 実験の戻り値として強制される `Variation` に対応する **バリエーションキー**。値が `null` の場合、強制バリエーションがリセットされます。 | | | forceTargeting (*任意*) | `bool` | 実験のターゲティングを強制してスキップするか (`true`)、標準の評価プロセスのように適用するか (`false`) を示します。 | `true` | ##### スローされるエラー | 型 | 説明 | | --------------------------- | ----------------------------------------------------------------------------------------------------------- | | `SDKNotReady` | SDK がまだ完全に初期化されていないことを示します。 | | `FeatureExperimentNotFound` | 要求された実験 ID が SDK の内部設定で見つからなかったことを示す例外。これは通常正常であり、ルールに対応する実験が Kameleoon 側でまだ有効化されていないことを意味します。 | | `FeatureVariationNotFound` | 要求されたバリエーションキー (ID) が SDK の内部設定で見つからなかったことを示す例外。これは通常正常であり、バリエーションに対応する実験が Kameleoon 側でまだ有効化されていないことを意味します。 | ほとんどの場合、例で示されているように、基本的なエラー `KameleoonException` のみを処理すれば十分です。ただし、異なるタイプのエラーに対して応答が必要な場合は、具体的な要件に基づいてそれぞれを個別に処理してください。さらに、信頼性を高めるために、`Exception` を含めて一般的な言語エラーを処理することもできます。 #### evaluateAudiences() * 📨 *Kameleoon にトラッキングデータを送信します* このメソッドは、利用可能なすべての Audiences Explorer セグメントに対して訪問者を評価し、一致した訪問者を追跡します。 `evaluateAudiences()` は、**関連するすべての訪問者データが設定または更新された後**、そして機能バリエーションを取得したり機能フラグを確認したりする**直前に**呼び出す必要があります。このアプローチにより、訪問者が利用可能な最新データに対して評価され、すべての条件に基づいた正確なオーディエンス割り当てが可能になります。 このメソッドを呼び出した後、Audiences Explorer でセグメントパフォーマンスの詳細な分析を実行できます。 ```dart theme={null} try { await kameleoonClient.evaluateAudiences(); } on KameleoonException { // Handling the exception } ``` ##### スローされるエラー | 型 | 説明 | | ------------- | --------------------------- | | `SDKNotReady` | SDK がまだ完全に初期化されていないことを示します。 | ほとんどの場合、例で示されているように、基本的なエラー `KameleoonException` のみを処理すれば十分です。ただし、異なるタイプのエラーに対して応答が必要な場合は、具体的な要件に基づいてそれぞれを個別に処理してください。さらに、信頼性を高めるために、`Exception` を含めて一般的な言語エラーを処理することもできます。 ### ゴール #### trackConversion() * 📨 *Kameleoon にトラッキングデータを送信します* このメソッドを使用してコンバージョンを追跡します。このメソッドでは、特定の[ゴール](/user-manual//assets/goals/create-a-goal)でのコンバージョンを追跡するために `goalId` が必要です。さらに、このメソッドは `revenue`、`metadata`、`negative` 引数も受け取ります。 `trackConversion()` メソッドは値を返しません。サーバー呼び出しが非同期で行われるため、このメソッドはノンブロッキングです。 ```dart theme={null} kameleoonClient.trackConversion(goalId); // default revenue kameleoonClient.trackConversion(goalId, 10); // provided revenue == 10 // Add metadata kameleoonClient.trackConversionWithOptParams(goalId, metadata: [CustomData.withIndex(1, values: ["true"])]); kameleoonClient.trackConversionWithOptParams(goalId, revenue: 10, metadata: [CustomData.withIndex(1, values: ["true"])]); ``` ##### 引数 | 名前 | 型 | 説明 | デフォルト | | --------------- | ------------------ | ----------------------------------------------------------------------------------------------- | ------- | | goalId (*必須*) | `int` | ゴールの ID。 | | | revenue (*任意*) | `double` | コンバージョンの売上。 | `0` | | negative (*任意*) | `bool` | 売上が正か負かを定義します。 | `false` | | metadata (*任意*) | `List` | コンバージョンのメタデータ。[Kameleoon アプリで事前に定義する必要があります](/ja/user-manual/assets/goals/create-a-goal#メタデータ)。 | `[]` | メタデータの値は、[未加工データのエクスポート](/user-manual/experiment-analytics/analyze-results/results-page/results-page-actions#Export) および[結果ページ](/user-manual/experiment-analytics/analyze-results/data-and-metrics/goal-metadata)からアクセスできます。 `metadata` パラメータが提供された場合、Kameleoon は [`addData()`](#adddata) メソッドで以前収集された値の代わりに、これらの指定値を現在のコンバージョンに使用します。パラメータが省略された場合、Kameleoon はコンバージョン以前で同じ訪問内で追跡された最後の [`CustomData`](#customdata) の値を使用します。 Kameleoon は、`trackConversion()` メソッドのパラメータとして明示的に渡されたメタデータの値のみを考慮します。 以下の例では、Kameleoon はパラメータとして明示的に提供されたカスタムデータの値 (ここではインデックス 5、値 'Amex Credit Card') のみをコンバージョンに関連付けます。 ```dart theme={null} kameleoonClient.addData([ CustomData.withIndex(5, values: ["Credit Card"]), CustomData.withIndex(9, values: ["Express Delivery"]) ]); kameleoonClient.trackConversionWithOptParams(1000, metadata: [CustomData.withIndex(5, values: ["Amex Credit Card"])]); ``` ### イベント #### onUpdateConfiguration() このメソッドは以前 `updateConfigurationHandler` と呼ばれていましたが、SDK バージョン `3.0.0` のリリースで削除されました。 `onUpdateConfiguration()` メソッドを使用すると、構成データが更新されたイベントを処理できます。入力パラメータとして **handler** を 1 つ取ります。ハンドラーは、リアルタイム構成イベントを使用して構成が更新されたときに呼び出されます。 ```dart theme={null} kameleoonClient.onUpdateConfiguration((timestamp) { // timestamp value contains the value of Unix time (number of seconds elapsed since January 1, 1970) when configuration was updated. }); ``` ##### 引数 | 名前 | 型 | 説明 | | ------- | ---------------- | ---------------------------------------- | | handler | `Function(int)?` | リアルタイム構成イベントを使用して構成が更新されたときに呼び出されるハンドラー。 | ### 訪問者データ #### getVisitorCode() SDK で使用される一意の訪問者コードを返します。 ```dart theme={null} final visitorCode = await kameleoonClient.getVisitorCode(); ``` ##### 戻り値 | 型 | 説明 | | ---------------- | -------------------------- | | `Future` | SDK で使用される一意の訪問者コードを表す文字列。 | #### addData() `addData()` メソッドは、[ターゲティングデータ](#データ型)をストレージに追加し、他のメソッドが現在の訪問者をターゲットするかどうかを決定するためにそのデータを使用できるようにします。 `addData()` メソッドは値を返さず、自身では Kameleoon バックエンドサーバーとやり取りしません。代わりに、宣言されたすべてのデータは、[`flush()`](#flush) メソッドを使用した将来の送信のために保存されます。このアプローチにより、データは通常、`flush()` によってトリガーされる単一のサーバー呼び出しにグループ化されるため、サーバー呼び出しの数が削減されます。 [`trackConversion()`](#trackconversion) メソッドも、`flush()` と同様に、以前に関連付けられたデータを送信します。実験ルールがトリガーされた場合の [`getVariation()`](#getvariation) および [`getVariations()`](#getvariations) メソッドについても同様です。 各訪問者は、ほとんどのデータ型について、関連付けられたデータのインスタンスを 1 つしか持てません。ただし、[`CustomData`](#customdata) は例外です。訪問者はインデックスごとに関連付けられた `CustomData` のインスタンスを 1 つ持つことができます。 ```dart theme={null} try { await kameleoonClient.addData([ Device(Devices.phone), CustomData.withIndex(1, values: ["some custom value"]), Conversion(32, 10f, false), ]); } on KameleoonException { // Generic exception in native plugin integration occurred. } ``` ##### 引数 | 名前 | 型 | 説明 | デフォルト値 | | ------------ | ------------ | ------------------------------------------------------------------------------------------------------------ | ------ | | track (*任意*) | `bool` | 追加されたデータがトラッキング対象であるかどうかを指定します。`false` に設定すると、データはローカルに保存され、ターゲティング評価のみに使用されます。Kameleoon Data API には送信されません。 | `true` | | data (*必須*) | `List` | Kameleoon データ型のコレクション。 | | ##### 例外 | 型 | 説明 | | ------------------- | -------------------------------- | | `PlatformException` | ネイティブプラグインの統合が正しく機能していないことを示す例外。 | #### flush() * 📨 *Kameleoon にトラッキングデータを送信します* `addData()` メソッドを介して現在のユーザーに関連付けられたデータは、即座にサーバーに送信されません。これは `trackConversion()` メソッドによって自動的に送信されるか、`flush()` メソッドを呼び出すことで手動で送信されるまで保存・蓄積され、データをサーバーにフラッシュするタイミングを正確に制御できます。たとえば、`addData()` メソッドを 12 回呼び出した場合、各 `addData()` 呼び出し後にデータをサーバーに送信するのはリソースの浪費になります。最後に 1 回 `flush()` を呼び出してください。 `flush()` メソッドは値を返しません。サーバー呼び出しが非同期で行われるため、このメソッドはノンブロッキングです。 ```dart theme={null} kameleoonClient.flush(); // Interval tracking (most performant tracking method) kameleoonClient.flush(instant: true); // Instant tracking ``` ##### スローされる例外 | 型 | 説明 | | ----------------- | -------------------------------- | | PlatformException | ネイティブプラグインの統合が正しく機能していないことを示す例外。 | #### getRemoteData() このメソッドは以前 `retrieveDataFromRemoteSource` と呼ばれていましたが、SDK バージョン `3.0.0` のリリースで削除されました。 このメソッドを使用して、アクティブな `siteCode` と `key` 引数 (または `key` が省略された場合はアクティブな `visitorCode`) に基づいて、Kameleoon リモートサーバーからデータを取得します。`visitorCode` と `siteCode` は `KameleoonClientFactory.create()` で指定されます。Kameleoon Data API を使用すると、データを高度にスケーラブルなリモートサーバーに迅速かつ便利に保存できます。その後、アプリケーションはこのメソッドを使用してデータを取得できます。 サーバー呼び出しが必要なため、このメカニズムは非同期であることに注意してください。 ```dart theme={null} try { final data = await kameleoonClient.getRemoteData("test"); } on KameleoonException { // Generic exception in native plugin integration occurred. } on Exception { // Any other error (including network issues). } ``` ##### 引数 | 名前 | 型 | 説明 | | --- | ------ | --------------------------------------- | | key | String | 取得しようとしているデータに関連付けられているキー。このフィールドは任意です。 | ##### 戻り値 | 型 | 説明 | | ----------------- | ------------------------------------------------------------------ | | `Future` | 特定の `key` (または `key` が省略された場合は `visitorCode`) に対するデータを取得する Future。 | | 型 | 説明 | | ----------------- | -------------------------------- | | PlatformException | ネイティブプラグインの統合が正しく機能していないことを示す例外。 | | Exception | リクエストがタイムアウトしたか、その他の失敗理由を示す例外。 | #### 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)に特に有用です。 ```dart theme={null} // Visitor data will be fetched and automatically added for `visitorCode`. try { final visitorData = await kameleoonClient.getRemoteVisitorData(); } on KameleoonException { // Generic exception in native plugin integration occurred. } on Exception { // Any other error (including network issues). } // If you only want to fetch data and add it yourself manually, set addData == `false`. try { final visitorData = await kameleoonClient.getRemoteVisitorData(addData: false); } on KameleoonException { // Generic exception in native plugin integration occurred. } on Exception { // Any other error (including network issues). } // If you want to fetch custom list of data types final filter = RemoteVisitorDataFilter.withValues( previousVisitAmount: 25, currentVisit: true, conversions: true, ); try { final visitorData = await kameleoonClient.getRemoteVisitorData(filter: filter, addData: false); } on KameleoonException { // Generic exception in native plugin integration occurred. } on Exception { // Any other error (including network issues). } ``` ##### 引数 | 名前 | 型 | 説明 | | ------- | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | filter | `RemoteVisitorDataFilter` | 訪問履歴から取得するデータを選択するフィルター。デフォルトでは、`getRemoteVisitorData` は現在の訪問および直近の前回の訪問から `CustomData` を取得します (`RemoteVisitorDataFilter()`)。他のすべてのフィルターパラメータはデフォルトで `false` です。このフィールドは任意です。 | | addData | boolean | 訪問者に対して取得したデータをメソッドが自動的に追加するかどうかを示すブール値。指定されない場合、デフォルト値は **true** です。このフィールドは任意です。 | ##### 戻り値 | 型 | 説明 | | -------------------- | -------------------- | | `Future>` | 訪問者に対して取得したデータを含む配列。 | ##### スローされる例外 | 型 | 説明 | | ----------------- | -------------------------------- | | PlatformException | ネイティブプラグインの統合が正しく機能していないことを示す例外。 | | Exception | リクエストがタイムアウトしたか、その他の失敗理由を示す例外。 | ##### getRemoteVisitorData() でのパラメータの使用 `getRemoteVisitorData()` メソッドは、訪問者のデータを取得する際にさまざまなパラメータを定義できる柔軟性を提供します。ゴール、実験、バリエーションに基づくターゲティングを行う場合、すべてのデータ型に対して同じアプローチが適用されます。 たとえば、ゴール「Order transaction」を完了した訪問者のデータを取得したい場合を考えます。`getRemoteVisitorData()` メソッド内でパラメータを指定して、ターゲティングを絞り込むことができます。たとえば、最後の 5 回の訪問でゴールに対してコンバージョンしたユーザーのみをターゲットしたい場合、`previousVisitAmount` パラメータを `5`、`conversions` を `true` に設定できます。 この例で示される柔軟性はゴールデータに限られません。`getRemoteVisitorData()` メソッド内のパラメータを使用して、さまざまな訪問者の行動に関するデータを取得できます。 利用可能な `RemoteVisitorDataFilter` オプションの一覧は次のとおりです。 | 名前 | 型 | 説明 | デフォルト | | ------------------------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | | previousVisitAmount (*任意*) | `int` | データを取得する前回の訪問数。`1` から `25` の間の数 | `1` | | currentVisit (*任意*) | `boolean` | true の場合、現在の訪問データが取得されます。 | `true` | | customData (*任意*) | `boolean` | true の場合、カスタムデータが取得されます。 | `true` | | geolocation (*任意*) | `boolean` | true の場合、地理位置情報データが取得されます。 | `false` | | conversions (*任意*) | `boolean` | true の場合、コンバージョンデータが取得されます。 | `false` | | experiments (*任意*) | `boolean` | true の場合、実験データが取得されます。 | `false` | | pageViews (*任意*、*Web のみ*) | `boolean` | true の場合、ページデータが取得されます。 | `false` | | device (*任意*、*Web のみ*) | `boolean` | true の場合、デバイスデータが取得されます。 | `false` | | browser (*任意*、*Web のみ*) | `boolean` | true の場合、ブラウザデータが取得されます。 | `false` | | operatingSystem (*任意*、*Web のみ*) | `boolean` | true の場合、オペレーティングシステムデータが取得されます。 | `false` | | kcs (*任意*) | `boolean` | true の場合、Kameleoon Conversion Score (KCS) が取得されます。[AI Predictive Targeting アドオン](/user-manual/ai-predictive-targeting/target-users-based-on-likelihood-to-convert)が必要です。 | `false` | | visitorCode (*任意*) | `boolean` | true の場合、Kameleoon は直近の訪問から `visitorCode` を取得し、現在の訪問に使用します。これは、[クロスデバイス実験](/developer-docs/cross-device-experimentation)のために、訪問者がその `visitorCode` で識別されて、訪問を通して常に同じバリエーションを受け取るようにしたい場合に必要です。 | `true` | | cbs (*任意*) | `boolean` | true の場合、Contextual Bandit スコアデータが取得されます。 | `false` | #### getVisitorWarehouseAudience() データウェアハウス内で訪問者に関連付けられたすべてのオーディエンスデータを取得します。任意の `warehouseKey` パラメータは、通常は内部ユーザー ID です。`customDataIndex` パラメータは、Kameleoon が訪問者をターゲットするために使用する Kameleoon カスタムデータに対応します。詳細については、[ウェアハウスターゲティングドキュメント](/user-manual/integrations/data-warehouses/bigquery/use-bigquery-as-a-source-audience-targeting) を参照してください。このメソッドは `CustomData` オブジェクトとして結果を返し、データが訪問者に追加され、ターゲティングのために利用可能であることを確認します。 サーバー呼び出しが必要なため、このメカニズムは非同期です。 ```dart theme={null} try { final customData = await kameleoonClient.getVisitorWarehouseAudience(customDataIndex); } on KameleoonException { // Generic exception in native plugin integration occurred. } on Exception { // Any other error (including network issues). } // If you need to specify warehouse key try { final customData = await kameleoonClient.getVisitorWarehouseAudience(customDataIndex, "warehouseKey"); } on KameleoonException { // Generic exception in native plugin integration occurred. } on Exception { // Any other error (including network issues). } ``` ##### 引数 | 名前 | 型 | 説明 | | --------------- | ------ | ------------------------------------------------------- | | visitorCode | string | 一意の訪問者識別文字列で、255 文字を超えることはできません。 | | customDataIndex | int | BigQuery Audiences をターゲットするために使用したいカスタムデータのインデックスを表す整数。 | | warehouseKey | string | ウェアハウスデータを識別する一意のキー (通常は内部ユーザー ID)。このフィールドは任意です。 | ##### 戻り値 | 型 | 説明 | | -------------------- | ----------------------------------------- | | `Future` | データが訪問者に追加されたことを確認する `CustomData` インスタンス。 | ##### スローされる例外 | 型 | 説明 | | ----------------- | -------------------------------- | | PlatformException | ネイティブプラグインの統合が正しく機能していないことを示す例外。 | | Exception | リクエストがタイムアウトしたか、その他の失敗理由を示す例外。 | #### setLegalConsent() 訪問者が個人データの使用に法的同意を提供したかどうかを指定するために、このメソッドを使用する必要があります。`consent` パラメータを `false` に設定すると、トラッキングリクエストに含めることができるデータの種類が制限されます。このメソッドは、訪問者データを責任を持って管理しつつ、法律や規制要件に準拠するのに役立ちます。個人データに関する詳細情報は、[同意管理ポリシー](/user-manual/project-management/consent-management-policy)で確認できます。 ```dart theme={null} try { final customData = await kameleoonClient.setLegalConsent(true); } on KameleoonException { // Generic exception in native plugin integration occurred. } on Exception { // Any other error (including network issues). } ``` ##### 引数 | 名前 | 型 | 説明 | | ------- | ------- | ------------------------------------------------------------------------------------------------- | | consent | boolean | 法的同意のステータスを表すブール値。`true` は訪問者が法的同意を提供したことを示し、`false` は訪問者が法的同意を提供していないか、撤回したことを示します。このフィールドは必須です。 | ##### スローされる例外 | 型 | 説明 | | ----------------- | -------------------------------- | | PlatformException | ネイティブプラグインの統合が正しく機能していないことを示す例外。 | ##### 同意取り消し時の動作 これは Flutter Web SDK にのみ適用されます。 `setLegalConsent()` を `consent=false` で呼び出した場合、SDK は `kameleoonVisitorCode` Cookie を削除しません。代わりに、Cookie の有効期限の延長を停止し、Cookie が自然に期限切れになるまで保持されるようにします。 コンプライアンス要件によりオプトアウト時に Cookie ファイルの即時削除が必要な場合は、フレームワークのネイティブ Cookie 管理メソッドを使用して手動で削除する必要があります。SDK は自動的にファイルを削除しません。 ### データ型 このセクションでは、Kameleoon でサポートされる `Data` 型をリストします。いくつかの標準データ型が提供されているほか、カスタムデータ型を定義するための `CustomData` 型もあります。 #### Conversion ここに保存される `Conversion` データセットは、関連付けられている任意のゴールで実験およびパーソナライゼーションレポートをフィルタリングするために使用できます。 * 各訪問者は複数の `Conversion` オブジェクトを持つことができます。 * `goalId` は Kameleoon アプリで確認できます。 | 名前 | 型 | 説明 | デフォルト | | --------------- | ------------------ | -------------- | ------- | | goalId (*必須*) | `int` | ゴールの ID。 | | | revenue (*任意*) | `double` | コンバージョンの売上 | `0` | | negative (*任意*) | `bool` | 売上が正か負かを定義します。 | `false` | | metadata (*任意*) | `List` | コンバージョンのメタデータ。 | `[]` | ```dart theme={null} try { final conversion = Conversion(32, 10); final conversionMetadata = Conversion(32, 10, false, [CustomData.withIndex(1, values: ["true"])]); final conversionOptParams = Conversion.withOptParams(32, metadata: [CustomData.withIndex(1, values: ["true"])]); await kameleoonClient.addData([conversion, conversionMetadata, conversionOptParams]); } on KameleoonException { // Generic exception in native plugin integration occurred. } ``` #### CustomData このデータ型は、モバイル & Web の両方の SDK で利用可能です。 `CustomData` を使用すると、あらゆる種類のデータを各訪問者に簡単に関連付けることができます。`CustomData` は、[セグメント](/user-manual/assets/segments/create-a-segment/)のターゲティング条件として、または実験レポートのフィルター/分解として使用できます。 カスタムデータについての詳細は、こちらの [記事](/developer-docs/custom-data) を参照してください。 | 名前 | 型 | 説明 | | | ----------------- | -------------- | ----------------------------------------------------------------------------------------------------------------------------- | ------ | | index/name (*必須*) | `int`/`String` | カスタムデータのインデックスまたは名前。データを識別するために\*\*`index` または `name` のどちらかを指定する必要があります\*\*。 | | | overwrite (*任意*) | `bool` | 値の格納方法とレポートでの表示方法を明示的に制御するフラグ。[詳細を見る](/developer-docs/custom-data#default-logic-when-overwrite-parameter-is-false-or-omitted) | `true` | | values (*任意*) | `List` | 保存するカスタムデータの値。 | | * 各訪問者は、一意の `index` に対して 1 つの `CustomData` のみを持つことが許可されています。同じ `index` で別の `CustomData` を追加すると、既存の `CustomData` が置き換えられます。 * カスタムデータの `index` は、[カスタムデータダッシュボード](/user-manual/assets/custom-data/manage-custom-data)の「INDEX」列で確認できます。 * プライバシー上の理由から SDK が選択したインデックスのデータを Kameleoon サーバーに送信しないようにするには、カスタムデータの作成時に **このデータをターゲティング目的のみでローカルで使用する** オプションを有効にしてください。 * SDK インスタンスの設定が最新でない場合や、名前が登録されていない場合に名前で作成された `CustomData` インスタンスを追加すると、データは無視されます。 ```dart theme={null} try { await kameleoonClient.addData([CustomData.withIndex(1, values: ["some custom value"])]); // With several values await kameleoonClient.addData(CustomData.withIndex(1, values: ["value 1", "value 2"])) // To set the 'overwrite' flag to false await kameleoonClient.addData(CustomData.withIndex(1, overwrite: false, values: ["first value", "second value"])) // To use a name instead of the index await kameleoonClient.addData(CustomData.withName("my-custom-data", values: ["value"])) } on KameleoonException { // Generic exception in native plugin integration occurred. } ``` #### Device このデータ型は、モバイル & Web の両方の SDK で利用可能です。 ユーザーのデバイスに関する情報を保存します。 | 名前 | 型 | 説明 | | ------ | ------- | ------------------------------------------------- | | device | Devices | デバイスのリスト: `phone`、`table`、`desktop`。このフィールドは必須です。 | ```dart theme={null} try { await kameleoonClient.addData([Device(Devices.phone)]); } on KameleoonException { // Generic exception in native plugin integration occurred. } ``` #### Geolocation このデータ型は、モバイル & Web の両方の SDK で利用可能です。 `Geolocation` には、訪問者の地理位置情報の詳細が含まれます。 | 名前 | 型 | 説明 | | ----------------- | ---------------------- | --------------------------- | | country (*必須*) | `String` | 訪問者の国。 | | region (*任意*) | `String?` | 訪問者の地域。 | | city (*任意*) | `String?` | 訪問者の都市。 | | postalCode (*任意*) | `String?` | 訪問者の郵便番号。 | | latitude (*任意*) | `double?` | 訪問者の場所を表す緯度座標。座標数は十進度を表します。 | | longitude (*任意*) | `double?` | 訪問者の場所を表す経度座標。座標数は十進度を表します。 | * 各訪問者は、`Geolocation` を 1 つだけ持つことができます。2 つ目の `Geolocation` を追加すると、最初のものが上書きされます。 ```dart theme={null} try { await kameleoonClient.addData([Geolocation("France", region: "Île-de-France", city: "Paris")]); } on KameleoonException { // Generic exception in native plugin integration occurred. } ``` #### Browser このデータ型は Web SDK でのみ利用可能です ここに保存される `Browser` データセットは、関連付けられている任意の値で実験およびパーソナライゼーションレポートをフィルタリングするために使用できます。 | 名前 | 型 | 説明 | | -------------- | ---------- | ------------------------------------------------------------------------- | | browser (*必須*) | `Browsers` | ブラウザのリスト: `chrome`、`internetExplorer`、`firefox`、`safari`、`opera`、`other`。 | | version (*任意*) | `double?` | ブラウザのバージョン。浮動小数点数はブラウザのメジャーバージョンとマイナーバージョンを表します。 | ```dart theme={null} try { await kameleoonClient.addData([Browser(Browsers.chrome)]); await kameleoonClient.addData([Browser(Browsers.chrome, 10.0)]); } on KameleoonException { // Generic exception in native plugin integration occurred. } ``` #### PageView このデータ型は Web SDK でのみ利用可能です。 | 名前 | 型 | 説明 | | --------- | ----------- | --------------------------- | | url | String | 閲覧したページの URL。このフィールドは必須です。 | | title | String | 閲覧したページのタイトル。このフィールドは必須です。 | | referrers | `List` | 閲覧したページのリファラー。このフィールドは任意です。 | リファラーのインデックス (ID) は、Kameleoon アプリの取得チャネル設定ページで利用可能です。注意: このインデックスは 0 から始まるため、特定のサイトに対して作成する最初の[取得チャネル](/user-manual/assets/advanced-targeting-tools/create-an-acquisition-channel)の ID は 1 ではなく 0 になります。 ```dart theme={null} try { await kameleoonClient.addData([PageView("https://url.com", "title", [3])]); } on KameleoonException { // Generic exception in native plugin integration occurred. } ``` #### OperatingSystem このデータ型は Web SDK でのみ利用可能です。 `OperatingSystem` には、訪問者のデバイス上のオペレーティングシステムに関する情報が含まれます。 各訪問者は、`OperatingSystem` を 1 つだけ持つことができます。2 つ目の `OperatingSystem` を追加すると、最初のものが上書きされます。 | 名前 | 型 | 説明 | | ---- | ------------------ | -------------------------------------------------------------------------------------- | | type | `OperatingSystems` | オペレーティングシステムのリスト: `windows`、`mac`、`ios`、`linux`、`android`、`windowsPhone`。このフィールドは必須です。 | ```dart theme={null} try { await kameleoonClient.addData([OperatingSystem(OperatingSystem.linux)]); } on KameleoonException { // Generic exception in native plugin integration occurred. } ``` #### Cookie このデータ型は Web SDK でのみ利用可能です。 `Cookie` には、訪問者のデバイスに保存された Cookie に関する情報が含まれます。 | 名前 | 型 | 説明 | | ------- | --------------------- | -------------------------------------------- | | cookies | `Map` | Cookie のキーと値で構成される文字列オブジェクトマップ。このフィールドは必須です。 | 各訪問者は、`Cookie` を 1 つだけ持つことができます。2 つ目の `Cookie` を追加すると、最初のものが上書きされます。 ```dart theme={null} try { await kameleoonClient.addData([Cookie({ "my_key1": "my_value1", "my_key2": "my_value2" })]); } on KameleoonException { // Generic exception in native plugin integration occurred. } ``` ### 戻り値の型 #### DataFile `DataFile` には SDK 設定の詳細が含まれます。 クライアントから要求された場合、追加情報で拡張できます。詳細が必要な場合は、カスタマーサクセスマネージャーにお問い合わせください。 | 名前 | 型 | 説明 | | ------------ | -------------------------- | ------------------------------------------------------- | | featureFlags | `Map` | 機能フラグキーをキーとする [`FeatureFlag`](#featureflag) オブジェクトのマップ。 | | dateModified | `int` | `DataFile` が最後に変更された時刻を示すタイムスタンプ (ミリ秒単位)。 | ```dart theme={null} // Retrieves the map of feature flags from the DataFile. // The map is keyed by feature flag identifiers, with each value being a FeatureFlag object. final featureFlags = dataFile.featureFlags; // Retrieves the last modification timestamp of the DataFile. // The value is an int representing milliseconds since the Unix epoch. final dateModified = dataFile.dateModified; ``` #### FeatureFlag `FeatureFlag` は、機能フラグ自体を定義する一連のプロパティ — たとえば、その [`Variations`](#variation)、[`Rules`](#rule)、環境ステータス、その他関連する詳細 — を表します。 クライアントから要求された場合、追加情報で拡張できます。詳細が必要な場合は、カスタマーサクセスマネージャーにお問い合わせください。 | 名前 | 型 | 説明 | | ------------------- | ------------------------ | --------------------------------------- | | environmentEnabled | `bool` | 現在の環境で機能フラグが有効化されているかどうかを示します。 | | defaultVariationKey | `String` | 機能フラグに関連付けられたデフォルトバリエーションのキー。 | | variations | `Map` | バリエーションキーをキーとする `Variation` オブジェクトのマップ。 | | rules | `List` | `Rule` オブジェクトのリスト | ```dart theme={null} // Check whether the feature flag is enabled in the current environment final isEnvironmentEnabled = featureFlag.environmentEnabled // Retrieve the key of the default variation final defaultVariationKey = featureFlag.defaultVariationKey // Retrieve the default variation object final defaultVariation = featureFlag.defaultVariation // Retrieve all variations of the feature flag as a map (key = variation key, value = Variation object) final variations = featureFlag.variations // Retrieve all targeting rules associated with the feature flag final rules = featureFlag.rules ``` #### Rule `Rule` は、ルール自体を定義する一連のプロパティ — たとえば、その [`Variations`](#variation) — を表します。 クライアントから要求された場合、追加情報で拡張できます。詳細が必要な場合は、カスタマーサクセスマネージャーにお問い合わせください。 | 名前 | 型 | 説明 | | ---------- | ------------------------ | --------------------------------------- | | variations | `Map` | バリエーションキーをキーとする `Variation` オブジェクトのマップ。 | ```dart theme={null} // Retrieve all variations of the rule as a map (key = variation key, value = Variation object) final variations = rule.variations ``` #### Variation `Variation` には、訪問者に割り当てられたバリエーション (または、特定の割り当てがない場合はデフォルトバリエーション) に関する情報が含まれます。 | 名前 | 型 | 説明 | | ------------ | ----------------------- | ----------------------------------------------------------------------- | | name | `String` | バリエーションの名前。 | | key | `String` | バリエーションを識別する一意のキー。 | | id | `int?` | 割り当てられたバリエーションの ID (デフォルトバリエーションの場合は `null`)。 | | experimentId | `int?` | バリエーションに関連付けられた実験の ID (デフォルトの場合は `null`)。 | | variables | `Map` | 割り当てられたバリエーションの変数を含むマップ。変数名をキーとします。変数が関連付けられていない場合は空のコレクションになる可能性があります。 | * `Variation` オブジェクトは割り当てられたバリエーションとその関連実験の詳細を提供する一方、[`Variable`](#variable) オブジェクトはバリエーション内の各変数に関する具体的な詳細を含みます。 * コードが `id` または `experimentId` が `null` となる可能性に対応していることを確認してください。これはデフォルトバリエーションを示します。 * バリエーションに変数が関連付けられていない場合、`variables` マップが空になる可能性があります。 ```dart theme={null} // Retrieving the variation name var variationName = variation.name // Retrieving the variation key var variationKey = variation.key; // Retrieving the variation id var variationId = variation.id; // Retrieving the experiment id var experimentId = variation.experimentId; // Retrieving the variables map var variables = variation.variables; ``` #### Variable `Variable` には、割り当てられたバリエーションに関連付けられた変数に関する情報が含まれます。 | 名前 | 型 | 説明 | | ----- | --------- | ------------------------------------------------------------------------------------------------------------------------ | | key | `String` | 変数を識別する一意のキー。 | | type | `String` | 変数の型。可能な値: **BOOLEAN**、**NUMBER**、**STRING**、**JSON**。 | | value | `dynamic` | 変数の値。次の型を取り得ます: **bool**、**int**、**double**、**String**、**Map\** (json オブジェクト)、**\[dynamic]** (json 配列)。 | ```swift theme={null} // Retrieving the variables map var variables = variation.variables; // Variable type can be retrieved for further processing var type = variables["isDiscount"]?.type ?? ""; // Retrieving the variable value by key var isDiscount = variables["isDiscount"]?.value as bool? ?? false; // Variable value can be of different types var title = variables["title"]?.value as String? ?? ""; ``` ### 非推奨のメソッド これらのメソッドは非推奨であり、SDK バージョン `4.0.0` で削除されます。 #### isReady() 代わりに [`isReadyAsync()`](#isreadyasync) を使用してください。iOS と Android では、[`isReady()`](#isready) は、SDK が [`defaultDataFile`](#initialize-the-kameleoon-client) で初期化されている場合でも、誤った (`false`) 結果を返す可能性があります。 モバイル SDK の場合、Kameleoon クライアントはアクティブな機能フラグの現在の構成を取得するためにサーバーコールを実行する必要があるため、すぐには初期化できません。機能フラグをトリガーする前にこのメソッドを呼び出して、SDK の準備ができているかどうかを確認するには、`isReady()` を使用します。 または、コールバックを使用することもできます (詳細は [`runWhenReady()`](#runwhenready) メソッドを参照してください)。 ```dart theme={null} final ready = kameleoonClient.isReady(); ``` ##### 戻り値 | 名前 | 型 | 説明 | | ----- | ---- | -------------------------------------------- | | ready | bool | SDK のステータス (適切に初期化されているか、まだ使用できないか) を表すブール値。 | #### getFeatureVariationKey() * 📨 *Kameleoon にトラッキングデータを送信します* 代わりに [`getVariation()`](#getvariation) を使用してください。 このメソッドを使用して、訪問者の機能バリエーションキーを取得します。このメソッドは、指定したユーザーのバリエーションキーを取得するために必須の引数として `featureKey` を受け取ります。 訪問者がこれまでこの機能フラグに関連付けられていない場合、SDK はランダムに割り当てられたバリエーションキー (機能フラグルールに従って) を返します。訪問者がすでにこの機能フラグに登録されている場合、このメソッドは以前のバリエーションキーを返します。ユーザーがどのルールにも一致しない場合、お客様のアカウントで定義されているデフォルト値が返されます。 例コードに示されているように、潜在的な例外をキャッチするための適切なエラーハンドリングを設定してください。 ```dart theme={null} String featureKey = "new_checkout"; String variationKey = ""; try { variationKey = await kameleoonClient.getFeatureVariationKey(featureKey); } on SDKNotReady { // Exception indicates that the SDK has not completed its initialization yet. } on FeatureNotFound { // The error has occurred; feature flag isn't found in current configuration. } on FeatureEnvironmentDisabled { // The feature flag is disabled for the environment. } on KameleoonException { // Generic exception in native plugin integration occurred. } on Exception { // Any other error. } switch(variationKey) { case 'on': // Main variation key is selected for visitorCode break; case 'alternative_variation': // Alternative variation key break; default: // Default variation key break; } ``` ##### 引数 | 名前 | 型 | 説明 | | ---------- | ------ | ----------------------------- | | featureKey | String | ユーザーに公開したい機能のキー。このフィールドは必須です。 | ##### 戻り値 | 型 | 説明 | | ---------------- | ------------------------- | | `Future` | 訪問者に登録された機能フラグのバリエーションキー。 | ##### スローされる例外 | 型 | 説明 | | ----------------- | ---------------------------------------------------------------------------------------------------------------------------- | | SDKNotReady | SDK が初期化を完了していないことを示す例外。 | | FeatureNotFound | 要求された機能 ID が SDK の内部設定で見つからなかったことを示す例外。この例外は通常、機能フラグが Kameleoon 側で有効化されていない (ただし、機能を実装するコードはすでにアプリケーションにデプロイされている) ことを意味します。 | | PlatformException | ネイティブプラグインの統合が正しく機能していないことを示す例外。 | #### getActiveFeatures() * 代わりに [`getVariations()`](#getvariations) を使用してください。 * 以前は `getFeatureListForVisitorCode` と呼ばれていましたが、SDK バージョン `4.0.0` のリリースで削除されました。 `getActiveFeatures` メソッドは、訪問者が利用可能なアクティブな機能フラグに関する情報を取得します。 ```dart theme={null} try { final activeFeatures = await kameleoonClient.getActiveFeatures(); } on KameleoonException { // Generic exception in native plugin integration occurred. } ``` ##### 戻り値 | 型 | 説明 | | -------------------------------- | -------------------------------------------------- | | `Future>` | 対応するアクティブな機能のキーを使用したアクティブな機能の割り当てられたバリエーションを含むマップ。 | #### getFeatureVariable() * 📨 *Kameleoon にトラッキングデータを送信します* - 代わりに [`getVariation()`](#getvariation) を使用してください。 - このメソッドは以前 `obtainFeatureVariable` と呼ばれていましたが、SDK バージョン `3.0.0` で削除されました。 このメソッドは、特定のユーザーのバリエーションキーの変数値を取得します。`featureKey` と `variableKey` を必須の引数として受け取ります。 訪問者がこれまで `featureKey` に関連付けられていない場合、SDK は指定したバリエーションキー (機能フラグルールに従って) に対するランダムに割り当てられた変数値を返します。訪問者がすでにこの機能フラグに登録されている場合、このメソッドは以前に登録されたバリエーションの変数値を返します。ユーザーがどのルールにも一致しない場合、デフォルトの変数値が返されます。 例コードに示されているように、潜在的な例外をキャッチするための適切なエラーハンドリングを設定してください。 ```dart theme={null} String featureKey = "feature_key"; String variableKey = "product_number"; int recommendedProductsNumber = 5; try { recommendedProductsNumber = await kameleoonClient.getFeatureVariable(featureKey, variableKey); } on SDKNotReady { // Exception indicates that the SDK has not completed its initialization yet. } on FeatureNotFound { // The error has occurred; feature flag isn't found in current configuration. } on FeatureEnvironmentDisabled { // The feature flag is disabled for the environment. } on FeatureVariableNotFound { // Requested variable not defined in Kameleoon. } on KameleoonException { // Generic exception in native plugin integration occurred. } on Exception { // Any other error. } setState(() { _recommendedProductsNumber = recommendedProductsNumber; }); ``` ##### 引数 | 名前 | 型 | 説明 | | ----------- | ------ | ----------------------------- | | featureKey | String | ユーザーに公開したい機能のキー。このフィールドは必須です。 | | variableKey | String | 値を取得したい変数の名前。このフィールドは必須です。 | ##### 戻り値 | 型 | 説明 | | ----------------- | --------------------------------------------------------------------------------- | | `Future` | この機能フラグについて訪問者に登録されたバリエーションの変数値。可能な型: `bool`、`int`、`double`、`String`、`List`、`Map` | ##### スローされる例外 | 型 | 説明 | | -------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | | SDKNotReady | SDK が初期化を完了していないことを示す例外。 | | FeatureNotFound | 要求された機能 ID が SDK の内部設定で見つからなかったことを示す例外。この例外は通常、機能フラグが Kameleoon 側で有効化されていない (ただし、機能を実装するコードはすでにアプリケーションにデプロイされている) ことを意味します。 | | FeatureEnvironmentDisabled | 訪問者の現在の環境 (たとえば、production、staging、development) で機能フラグが無効になっていることを示す例外。 | | FeatureVariableNotFound | 指定された変数が見つからなかったことを示す例外。Kameleoon アプリの変数キーがコード内のキーと一致するか確認してください。 | | PlatformException | ネイティブプラグインの統合が正しく機能していないことを示す例外。 | #### getFeatureVariationVariables() * 代わりに [`getVariation()`](#getvariation) を使用してください。 * このメソッドは以前 `getFeatureAllVariables` と呼ばれていましたが、SDK バージョン `4.0.0` のリリースで削除されました。 機能のすべての変数を取得するには、このメソッドを呼び出します。Kameleoon アプリで機能の変数を変更できます。 このメソッドは 1 つの入力パラメータ `featureKey` を取ります。Kameleoon アプリで定義された通り、`Map` 型としてデータを返します。要求された機能が SDK の内部設定で見つからなかった場合は、例外 (`FeatureNotFound`) をスローします。 ```dart theme={null} final featureKey = "featureKey"; final variationKey = "variationKey"; try { final allVariables = await client.getFeatureVariationVariables(featureKey, variationKey); } on SDKNotReady { // Exception indicates that the SDK has not completed its initialization yet. } on FeatureNotFound { // The error has occurred; feature flag isn't found in current configuration. } on FeatureEnvironmentDisabled { // The feature flag is disabled for the environment. } on KameleoonException { // Generic exception in native plugin integration occurred. } on Exception { // Any other error. } ``` ##### 引数 | 名前 | 型 | 説明 | | ------------ | ------ | ----------------------------- | | featureKey | String | 取得したい機能の識別キー。このフィールドは必須です。 | | variationKey | String | 取得したいバリエーションのキー。このフィールドは必須です。 | ##### 戻り値 | 型 | 説明 | | ------------------------------ | -------------------------------------------------------------------------------------- | | `Future>` | この機能フラグに関連付けられたデータ。値は int、double、bool、String、List、または Map (Web インターフェースで定義された型による) です。 | ##### スローされる例外 | 型 | 説明 | | -------------------------- | ------------------------------------------------------------------------------------------------------- | | FeatureNotFound | 要求された機能が SDK の内部設定で見つからなかったことを示す例外。この例外は通常、機能フラグが Kameleoon 側で有効化されていないことを意味します。 | | FeatureEnvironmentDisabled | 訪問者の現在の環境 (たとえば、production、staging、development) で機能フラグが無効になっていることを示す例外。 | | FeatureVariationNotFound | 要求されたバリエーション ID が SDK の内部設定で見つからなかったことを示す例外。この例外は通常正常であり、バリエーションに対応する実験が Kameleoon 側で有効化されていないことを意味します。 | | PlatformException | ネイティブプラグインの統合が正しく機能していないことを示す例外。 |