> ## 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.
# Python SDK
> Kameleoon Python SDK を統合して、Django 環境を含む Python バックエンドサーバーで実験を実行し、機能フラグを有効化します。
Python SDK を使用すると、バックエンドの Python サーバーで実験を実行し、機能フラグを有効化できます。当社の SDK を Web アプリケーションに統合するのは簡単で、メモリやネットワーク使用量のフットプリントも低く抑えられています。
**はじめに**: 始め方のヘルプについては、[開発者ガイド](#開発者ガイド)を参照してください。
**変更履歴**: Python SDK の最新バージョン: 3.20.0 [変更履歴](https://github.com/Kameleoon/client-python/blob/main/CHANGELOG.md)。
**SDK メソッド**: Python SDK の完全なリファレンスドキュメントについては、[リファレンス](#リファレンス)セクションを参照してください。
## 開発者ガイド
このガイドは、当社の SDK を数分で統合し、Python アプリケーションで実験を開始できるように設計されています。このチュートリアルでは、異なるバリエーションに基づいて推奨商品の数を変更するシンプルな A/B テストの設定について説明します。
### はじめに
#### Python クライアントのインストール
SDK は Python pip パッケージを使用してインストールできます。当社のパッケージは公式の pip リポジトリでホストされているため、次のコマンドを実行するだけです。
```python theme={null}
pip install kameleoon-client-python
```
#### 追加の設定
Python SDK の認証情報は構成ファイルを介して提供する必要があり、これを使用して SDK の動作をカスタマイズすることもできます。サンプル構成ファイルは[こちらから入手できます](/assets/developer-docs/sdks/web-sdks/client-configs/client-python.yaml)。このファイルはデフォルトのパス `/etc/kameleoon/client-python.yaml` にインストールすることを推奨しますが、別の場所に配置して、`KameleoonClient()` コンストラクタメソッドの引数としてパスを渡すこともできます。現在のバージョンの Python SDK で利用可能なキーは次のとおりです。
| キー | 説明 | デフォルト値 |
| ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------- |
| `client_id` (*必須*) | Kameleoon サービスへの認証に必要です。**client id** を見つけるには、[API 認証情報](/user-manual/account-and-team-management/users-and-teams/api-credentials)のドキュメントを参照してください。 | |
| `client_secret` (*必須*) | Kameleoon サービスへの認証に必要です。**client secret** を見つけるには、[API 認証情報](/user-manual/account-and-team-management/users-and-teams/api-credentials)のドキュメントを参照してください。 | |
| `session_duration_minute` (*オプション*) | Kameleoon が訪問者とそれに関連するデータをメモリ (RAM) に保存する所定の時間間隔を指定します。セッション期間を長くすると、訪問者データを保存するために割り当てる必要のある RAM の量が増加することに注意してください。 | `30` 分 |
| `refresh_interval_minute` (*オプション*) | SDK がアクティブな実験と機能フラグの構成を取得するリフレッシュ間隔を分単位で指定します。この値は、機能フラグの有効化/無効化や実験の開始などの変更を本番サーバーに反映させるのに要する最大時間を決定します。さらに、当社では新しい構成を SDK に自動的にプッシュして遅延なくリアルタイムで適用する Server-Sent Events (SSE) を使用した[ストリーミングモード](/developer-docs/feature-experimentation/technical-reference/technical-considerations/#streaming-premium-option)も提供しています。 | `60` 分 |
| `default_timeout_millisecond` (*オプション*) | SDK からのネットワークリクエストのタイムアウトをミリ秒単位で指定します。安定した接続がない場合は、値を 30 秒以上に設定してください。一部のメソッドには、その特定のメソッドのデフォルトタイムアウトを上書きするために使用できる追加のパラメータがあります。メソッドに対してタイムアウトを明示的に指定しない場合、SDK はこのデフォルト値を使用します。 | `10000` ミリ秒 |
| `tracking_interval_millisecond` (*オプション*) | トラッキングリクエストの間隔をミリ秒単位で指定します。Kameleoon が機能フラグの評価を行った訪問者、またはデータがフラッシュされた訪問者はすべてこのトラッキングリクエストに含まれ、SDK は間隔ごとに 1 回実行します。最小値は `1000` ms (デフォルト値でもあります) で、最大値は `5000` ms です。 | `1000` ミリ秒 |
| `environment` (*オプション*) | 機能フラグの構成を使用する環境です。値は `production`、`staging`、`development` のいずれかです。詳細については、[環境の管理](/user-manual/experimentation/feature-experimentation/configure-your-feature-flags/manage-environments)の記事を参照してください。 | `production` |
| `top_level_domain` *(ハイブリッドモードでは必須)* | Web サイトの現在のトップレベルドメインです。`example.com` の形式を使用してください。`https://`、`www`、またはその他のサブドメインを含めないでください。Kameleoon はこの情報を使用して、対応するクッキーをトップレベルドメインに設定します。 | `""` |
| `network_domain` (*オプション*) | SDK が送信リクエストに使用するカスタムドメインです。多くの場合プロキシ用に使用されます。有効なドメインである必要があります (例: example.com または sub.example.com)。無効な形式の場合は Kameleoon のデフォルト値になります。 | `None` |
| `logger` *(非推奨)* | デフォルトの Python ロガーを上書きできます。このフィールドは非推奨であり、SDK バージョン `4.0.0` で削除されます。代わりに [`KameleoonLogger.set_logger()`](#ロギング) を使用してください。 | `logging.Logger` |
| `multi_threading` *(非推奨)* | ネットワークリクエストにスレッドを使用できるかどうかを示す `bool` 型のオプションです。デフォルトでは、(C)Python インタプリタが使用されている場合の GIL によるパフォーマンスの問題を回避するため、すべての処理は 1 つのスレッドで実行されます。可能な値: `True`、`False`。 | `None` |
あるいは、初期化時にパラメータとして `KameleoonClientConfig` 型の `configuration_object` を使用することもできます。これは構成ファイルと同じ引数のリストを持ちます。`configuration_object` は構成ファイルよりも優先され、その設定を上書きします。
#### Kameleoon クライアントの初期化
アプリケーションに SDK をインストールし、正しい認証情報を設定し (`/etc/kameleoon/client-python.yaml` 内)、Kameleoon のバックオフィスでサーバーサイド実験をセットアップしたら、次のステップはアプリケーションコード内で Kameleoon クライアントを作成することです。
右側のコードはわかりやすい例を示しています。`KameleoonClient` はシングルトンオブジェクトで、アプリケーションと Kameleoon プラットフォームの間のブリッジとして機能します。実験を実行するために必要なすべてのメソッドとプロパティが含まれています。
開発者は、Kameleoon で A/B テストを実装する際にアプリケーションコードの正しいロジックを保証する責任を負います。ベストプラクティスは、訪問者が実験から除外される可能性があると常に想定することです (実験がまだ開始されていない場合)。このプラクティスは実装が簡単で、常に存在すべきデフォルトまたはリファレンスバリエーションのロジックと一致します。次のセクションのコードサンプルは、このアプローチを示しています。
```python theme={null}
from kameleoon import KameleoonClient, KameleoonClientConfig, KameleoonClientFactory
SITE_CODE = 'a8st4f59bj'
# Option 1
kameleoon_client = KameleoonClientFactory.create(SITE_CODE, config_path='/etc/kameleoon/client-python.yaml')
# Option 2
configuration_object = KameleoonClientConfig.read_from_yaml('/etc/kameleoon/client-python.yaml')
configuration_object.set_top_level_domain("example.com")
kameleoon_client = KameleoonClientFactory.create(SITE_CODE, configuration_object)
# Option 3
configuration_object = KameleoonClientConfig(
"client_id", # required
"client_secret", # required
refresh_interval_minute=60, # (in minutes) optional, default: 60 minutes
session_duration_minute=30, # (in minutes) optional, default: 30 minutes
default_timeout_millisecond=10000, # (in milliseconds) optional, default: 10000 milliseconds
tracking_interval_millisecond=1000, # (in milliseconds) optional, default: 1000 milliseconds
environment="production", # optional, possible values: "production" / "staging" / "development" / "staging", default: None
top_level_domain="example.com",
multi_threading=False, # optional, default: False
logger=my_logger, # optional, default: standard kameleoon logger. This field is deprecated and will be removed in SDK version `4.0.0`. Use `KameleoonLogger.set_logger` instead.
network_domain="example.com", # optional
)
kameleoon_client = KameleoonClientFactory.create(SITE_CODE, configuration_object)
```
#### 機能フラグの有効化
##### ユーザーに一意の 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_millisecond`](#追加の設定) に基づいて自動的にトリガーされます。デフォルトでは、この間隔は 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_millisecond`](#追加の設定) で定義) で送信する次のスケジュールされたトラッキングリクエストと共に送信されます。リクエストを即座に送信したい場合は、`instant=True` のパラメータを指定して [`flush()`](#flush) メソッドを使用してください。
##### 分析ソリューションへのイベント送信
コンバージョンをトラッキングし、露出イベントを顧客分析ソリューションに送信するには、まず Kameleoon を[ハイブリッドモード](/developer-docs/feature-experimentation/get-started/hybrid-experimentation/)で実装する必要があります。次に、[`get_engine_tracking_code()`](#get_engine_tracking_code) メソッドを使用します。
`get_engine_tracking_code()` メソッドは、分析ソリューションに露出イベントを送信するために必要な一意のトラッキングコードを取得します。このメソッドを使用すると、イベントを記録し、希望する分析プラットフォームに送信できます。
### Django 環境での Kameleoon Python SDK の使用
Django を使用する場合は、Django アプリケーションの `apps.py` ファイル内でサーバー起動時に Kameleoon クライアントを初期化することをお勧めします。
`python manage.py runserver` を使用すると、Django は 2 つのプロセスを起動します。1 つは実際の開発サーバー用で、もう 1 つはコードが変更された際にアプリケーションをリロードするためです。
リロードオプションなしでサーバーを起動することもでき、その場合 1 つのプロセスのみが実行されているのが確認できます。プロセスは 1 回のみ実行されます。
`python manage.py runserver --noreload`
`ready()` メソッド内で RUN\_MAIN 環境変数をチェックすることもできます。
```python theme={null}
def ready(self):
if os.environ.get('RUN_MAIN', None) == 'true':
configuration_path = os.path.join(ROOT_DIR, 'path_to_config', 'config.yml')
self.kameleoon_client = KameleoonClientFactory.create(SITE_CODE, config_path=configuration_path)
```
これは、`python manage.py runserver` を使用するローカル開発時にのみ適用されます。本番環境では、`ready()` 関数内のコードは、アプリケーションが初期化される際に 1 回のみ実行されます。
```python theme={null}
from django.apps import apps
my_application = apps.get_app_config('your_app')
client = my_application.kameleoon_client
```
その後、アプリケーション内で Kameleoon クライアントにアクセスできます。
Django を使用するもう 1 つの利点は、SDK が HTTP リクエスト/レスポンスのクッキーを介して **visitor\_code** を自動的に読み書きすることです。クッキーメカニズムを使用して **visitor\_code** を永続化したい Web 環境で別のフレームワークを使用している場合は、`read_cookies()` および `write_cookies()` メソッドの実装を提供する必要があります。
### クロスデバイス実験
複数のデバイスからアプリにアクセスする訪問者をサポートするため、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) メソッドの説明を参照してください。以下のコードでは、正確なデータ取得のために、同じ一意の識別子 (この場合は `visitor_code`、`userId` とも呼ばれる可能性があります) が 2 つのデバイス間で一貫して使用されていることを前提としています。
収集したデータをリアルタイムで同期したい場合は、カスタムデータに対してスコープを **Visitor** に選択する必要があります。
```python title="Device A" theme={null}
# In this example, Custom data with index `90` was set to "Visitor" scope in Kameleoon.
VISITOR_SCOPE_CUSTOM_DATA_INDEX = 90
kameleoon_client.add_data(visitor_code, CustomData(VISITOR_SCOPE_CUSTOM_DATA_INDEX, "your data"))
kameleoon_client.flush(visitor_code)
```
```python title="Device B" theme={null}
# Before working with the data, call `get_remote_visitor_data`.
kameleoon_client.get_remote_visitor_data(visitor_code)
# After calling, the SDK on Device B will have access to CustomData of Visitor scope defined on Device A.
# So, "your data" will be available to target and track the visitor.
```
#### セッションマージのためのカスタムデータの使用
[クロスデバイス実験](/developer-docs/cross-device-experimentation)を使用すると、各デバイス間で訪問者の履歴を結合できます (履歴の照合)。履歴照合により、異なる訪問者セッションを 1 つにマージできます。訪問履歴を照合するには、[`CustomData`](#customdata) を使用して訪問者に一意の識別子を提供します。詳細については、[専用のドキュメント](/developer-docs/cross-device-experimentation/#activating-cross-device-history-reconciliation)を参照してください。
クロスデバイス照合が有効になった後、`userId` パラメータで [`get_remote_visitor_data()`](#get_remote_visitor_data) を呼び出すと、指定したユーザーの既知のすべてのデータが取得されます。
同じ識別子を持つセッションは、実験で常に同じバリエーションが表示されます。実験結果ページの Visitor ビューでは、これらのセッションは 1 人の訪問者として表示されます。
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 スコープ**に設定する必要があるため、[クロスデバイスのカスタムデータ同期](/developer-docs/cross-device-experimentation)を使用して、各デバイスで [`get_remote_visitor_data()`](#get_remote_visitor_data) メソッドで識別子を取得する必要があります。
セッションマージのためにカスタムデータを使用する方法の例を以下に示します。
```python theme={null}
# In this example, `91` represents the Custom Data's index configured as a unique identifier in Kameleoon.
MAPPING_INDEX = 91
FEATURE_KEY = "ff123"
# 1. Before the visitor is authenticated
# Retrieve the variation for an unauthenticated visitor.
# Assume `anonymous_visitor_code` is the randomly generated ID for that visitor.
anonymous_variation = kameleoon_client.get_variation(anonymous_visitor_code, FEATURE_KEY)
# 2. After the visitor is authenticated
# Assume `user_id` is the visitor code of the authenticated visitor.
kameleoon_client.add_data(anonymous_visitor_code, CustomData(MAPPING_INDEX, user_id))
kameleoon_client.flush(anonymous_visitor_code, instant=True)
# Indicate that `user_id` is a unique identifier.
kameleoon_client.add_data(user_id, UniqueIdentifier(True))
# 3. After the visitor has been authenticated
# Retrieve the variation for the `user_id`, which will match the anonymous visitor code's variation.
user_variation = kameleoon_client.get_variation(user_id, FEATURE_KEY)
is_same_variation = user_variation.key == anonymous_variation.key # True
# The `user_id` and `anonymous_visitor_code` are now linked and tracked as a single visitor.
kameleoon_client.track_conversion(user_id, 123, 10.0)
# Additionally, the linked visitors will share all fetched remote visitor data.
kameleoon_client.get_remote_visitor_data(user_id)
```
この例では、アプリケーションにログインページがあります。ログイン時にユーザー ID が不明なため、[`get_visitor_code()`](#get_visitor_code) メソッドで生成された匿名訪問者識別子が使用されます。ユーザーがログインした後、匿名訪問者はユーザー ID と関連付けられ、訪問者の一意の識別子として使用されます。
### カスタムバケットキーの使用
デフォルトでは、Kameleoon は一意の匿名訪問者 ID (`visitor_code`) を使用してユーザーを機能フラグのバリエーションに割り当てます。この ID は通常、ユーザーのデバイス上で生成および保存されます (クライアントサイドおよびサーバーサイド SDK の場合はブラウザクッキーに、モバイル SDK の場合は永続ストレージに)。ただし、特定のシナリオでは、同じ組織のすべてのユーザーが機能フラグの同じバリアントを確認するようにする必要がある場合があります。
**カスタムバケットキー**オプションを使用すると、独自のカスタム識別子をバケットに提供することで、このデフォルトの動作を上書きできます。この上書きにより、Kameleoon の割り当てロジックがデフォルトの `visitor_code` の代わりに指定したキーを使用するようになります。
#### ユースケース
カスタムバケットキーの使用は、特に次のような状況で、機能フラグの割り当てにおける一貫性と精度を維持するために不可欠です。
* **アカウントレベルまたは組織の実験:** B2B 製品の場合、または同じ組織のすべてのユーザーを同じバリエーションに割り当てたい場合、`account_id` のような識別子を使用できます。カスタムバケットキーは、チームまたは会社全体に影響を与える機能の A/B テストに不可欠です。
カスタムバケットキーを実装することで、実験における一貫性と精度を高め、より信頼性の高い結果とより良いユーザー体験につながります。
#### 技術詳細
機能フラグにカスタムバケットキーを構成する際、アプリケーションのデータから特定の識別子を Kameleoon に提供します。
```python theme={null}
from kameleoon.data import CustomData
kameleoon_client.add_data(visitor_code, CustomData(index, "new_visitor_code"))
```
* **カスタムキーの提供:** [`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)こともできます。
### ロギング
SDK は、さまざまな内部プロセスや問題を反映するためにログを生成します。
#### ログレベル
SDK は、ログレベルによるロギングの制限の構成をサポートしています。
```python theme={null}
from kameleoon.logging.log_level import LogLevel
from kameleoon.logging.kameleoon_logger import KameleoonLogger
# 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 main behaviour.
KameleoonLogger.set_log_level(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.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 はデフォルトでコンソール出力にログを書き込みます。この動作はオーバーライド可能です。
ログレベルによるロギングの制限は、ログハンドリングロジックとは別に実行されます。
```python theme={null}
from loguru import logger
from kameleoon.logging.log_level import LogLevel
from kameleoon.logging.logger import Logger
class CustomLogger(Logger):
"""Custom logger implementation using loguru."""
def log(self, level: LogLevel, message: str) -> None:
"""Accepts logs from the SDK"""
if level == LogLevel.ERROR:
logger.error(message)
elif level == LogLevel.WARNING:
logger.warning(message)
elif level == LogLevel.INFO:
logger.info(message)
elif level == LogLevel.DEBUG:
logger.debug(message)
from kameleoon.logging.kameleoon_logger import KameleoonLogger
# 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_logger(CustomLogger())
KameleoonLogger.set_log_level(LogLevel.DEBUG) # Optional, defaults to `LogLevel.WARNING`.
```
## リファレンス
これは Python SDK の完全なリファレンスドキュメントです。
#### create()
SDK の使用を開始するには、初期化を完了する必要があります。SDK とのすべてのやり取りは `Kameleoon::KameleoonClient` というオブジェクトを介して完了するため、最初にすべきことはこのオブジェクトを作成することです。
```python theme={null}
kameleoon_config = KameleoonClientConfig("client_id", "client_secret")
kameleoon_client = KameleoonClientFactory.create("a8st4f59bj", kameleoon_config)
kameleoon_client = KameleoonClientFactory.create("a8st4f59bj", config_path="/etc/kameleoon/client-ruby.yaml")
```
##### 引数
| 名前 | 型 | 説明 |
| ------------ | --------------------- | ------------------------------------------------------------------------------------------------ |
| site\_code | str | SDK で使用している Kameleoon プロジェクトの[一意のキー](/user-manual/faq#how-do-i-find-my-sitecode)です。このフィールドは必須です。 |
| config | KameleoonClientConfig | 構成ファイルの代わりに渡すことができる構成 SDK オブジェクトです。このフィールドはオプションです。 |
| config\_path | str | SDK 構成ファイルへのパスです。このフィールドはオプションです。デフォルト値は `/etc/kameleoon/client-ruby.yaml` です。 |
##### スローされる例外
| 型 | 説明 |
| ------------------ | --------------------------------------- |
| SiteCodeIsEmpty | 指定されたサイトコードが空文字列であることを示す例外です。これは無効な値です。 |
| ConfigFileNotFound | 構成ファイルが見つからなかったことを示す例外です。 |
#### wait\_init\_async()
`wait_init_async` は Kameleoon クライアントの初期化を非同期で待機します。このメソッドを使用すると、他の操作を進める前に、クライアントが正常に初期化されたかを確認できます。
```python theme={null}
kameleoon_client = KameleoonClientFactory.create('a8st4f59bj')
if await kameleoon_client.wait_init_async():
# The SDK has been initialized; you can fetch a feature flag / experiment configuration here.
```
##### 戻り値
| 型 | 説明 |
| -------------------------- | -------------------------------------------------------------------- |
| Coroutine\[Any, Any, bool] | Kameleoon クライアントインスタンスが正常に初期化された場合は `True`、それ以外は `False` を返すコルーチンです。 |
#### wait\_init()
`wait_init` は Kameleoon クライアントの初期化を同期で待機します。このメソッドを使用すると、他の操作を進める前に、クライアントが正常に初期化されたかを確認できます。
```python theme={null}
kameleoon_client = KameleoonClientFactory.create('a8st4f59bj')
if kameleoon_client.wait_init():
# The SDK has been initialized; you can fetch a feature flag / experiment configuration here.
```
##### 戻り値
| 型 | 説明 |
| ------ | ------------------------------------------------------------ |
| `bool` | Kameleoon クライアントインスタンスが正常に初期化された場合は `True`、それ以外は `False` です。 |
### 機能フラグとバリエーション
#### is\_feature\_active()
* 📨 *トラッキングデータを Kameleoon に送信します (`track` パラメータに依存)*
以前は `activate_feature` と呼ばれていました。SDK バージョン `2.1.0` 以降非推奨であり、今後のリリースで削除されます。
訪問者に対して機能フラグがアクティブかどうかを確認するには、`is_feature_active()` メソッドを呼び出します。
このメソッドは、指定したユーザーに対して機能がアクティブになるかを確認するために、**visitor\_code** および **feature\_key** を必須引数として受け取ります。
そのようなユーザーがこの機能フラグに関連付けられたことがない場合、SDK はランダムにブール値を返します (機能がユーザーに対してアクティブになる場合は **true**、そうでない場合は **false**)。指定された **visitor\_code** を持つユーザーが既にこの機能フラグに登録されている場合、以前の**機能フラグ**の値を検出します。
右側の例に示すように、潜在的な例外をキャッチするために、コードに適切なエラー処理が設定されていることを確認する必要があります。
`visitor_code` を指定すると、`is_feature_active()` メソッドは `visitor_code` を一意の訪問者識別子として使用します。これは[クロスデバイス実験](/developer-docs/cross-device-experimentation)に便利です。`visitor_code` を指定して `is_unique_identifier` パラメータを `true` に設定すると、SDK はフラッシュされたデータを指定された識別子に関連付けられた訪問者にリンクします。
パラメータ `is_unique_identifier` は非推奨です。代わりに [`UniqueIdentifier`](#uniqueidentifier) を使用してください。
`is_unique_identifier` は、もともと訪問者に割り当てられた匿名 `visitor_code` にアクセスできないが、セッションマージ機能を使用して匿名訪問者と接続されている内部 ID にアクセスできる場合など、他のエッジケースシナリオでも役立ちます。
Kameleoon は、`is_feature_active()`、`get_variation()`、`get_variations()` などの特定のメソッドを呼び出す際にセッションと訪問者をカウントするためにトラッキングを使用します。
訪問者をバリエーションに公開してカウントする必要がある場合は、`track` パラメータにデフォルトの `True` 値を使用します。訪問者を公開する前にこれらのメソッドを呼び出す場合のみ、`track` パラメータを `False` に設定してください。
たとえば、訪問者を公開する前にすべてのバリエーションを取得するために `get_variations()` を呼び出す場合は、`track` パラメータを `False` に設定します。この設定により、Kameleoon がセッションを早期にカウントすることを防ぎます。その後、訪問者を明示的に公開するときにトラッキングをトリガーできます。
Kameleoon はデフォルトでトラッキングデータを毎秒送信します。トラッキング間隔の構成オプションを使用して、この間隔を最大 5 秒まで構成できます。Kameleoon は、イベント間の間隔が 30 分未満である限り、トラッキングイベントを 1 つのセッションにグループ化します。トラッキングイベント間で 30 分以上経過すると、Kameleoon はイベントを別のセッションとしてカウントします。セッションの最後に記録されたイベントから 30 分後にレポートに訪問が表示されます。
```python theme={null}
visitor_code = kameleoon_client.get_visitor_code(request.COOKIES)
feature_key = "new_checkout"
has_new_checkout = False
try
has_new_checkout = kameleoon_client.is_feature_active(visitor_code, feature_key)
# disabling tracking
has_new_checkout = kameleoon_client.is_feature_active(visitor_code, feature_key, track=False)
except FeatureNotFound as ex:
# The user will not be counted in the experiment,
# but should see the reference variation.
has_new_checkout = False
except VisitorCodeInvalid as ex:
# The visitor code you passed to the method isn't valid and can't be accepted by SDK.
has_new_checkout = False
if has_new_checkout
# Implement new checkout code here
```
`is_feature_active()` メソッドは、マスターフラグの状態ではなく、提供されたバリアントを評価します。ルールを除外する場合、メソッドは**それ以外のすべての人に対しては、〇〇を提供する**デフォルトの状態を使用します。このデフォルトの状態に対して **Off** を選択する場合、マスター機能フラグが **On** であっても、メソッドは常に `false` を返します。
##### 引数
| 名前 | 型 | 説明 |
| ---------------------------- | --------------- | ---------------------------------------------------------- |
| visitor\_code | str | ユーザーの一意の識別子です。このフィールドは必須です。 |
| feature\_key | str | ユーザーに公開したい機能の ID またはキーです。このフィールドは必須です。 |
| is\_unique\_identifier (非推奨) | Optional\[bool] | `True` に設定すると、SDK はフラッシュされたデータを指定された識別子に関連付けられた訪問者にリンクします。 |
| track | bool | 機能評価のトラッキングを有効または無効にするオプションのパラメータです (デフォルトは `True`)。 |
##### 戻り値
| 型 | 説明 |
| ---- | ---------------------------------------- |
| bool | 指定された **visitor\_code** に対して登録された機能の値です。 |
##### スローされる例外
| 型 | 説明 |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------- |
| FeatureNotFound | 要求された機能 ID が SDK の内部構成で見つからなかったことを示す例外です。この例外は通常正常であり、機能フラグが Kameleoon 側でまだ有効化されていないことを意味します (ただし、機能を実装するコードはすでに Web アプリケーション側にデプロイされています)。 |
| VisitorCodeInvalid | 指定された訪問者コードが有効でない (空または 255 文字を超えている) ことを示す例外です。 |
#### get\_variation()
* 📨 *トラッキングデータを Kameleoon に送信します (`track` パラメータに依存)*
特定の機能フラグに対して指定された訪問者に割り当てられた [`Variation`](#variation) を取得します。
このメソッドは、必須引数として `visitor_code` および `feature_key` を受け取ります。`track` 引数はオプションで、デフォルトは `True` です。
訪問者に割り当てられた `Variation` を返します。訪問者がどの機能フラグルールにも関連付けられていない場合、メソッドは指定された機能フラグのデフォルト `Variation` を返します。
潜在的な例外を管理するために、コードに適切なエラー処理が実装されていることを確認してください。
デフォルトバリエーションは、訪問者が機能フラグの事前定義された配信ルールに一致しない場合に割り当てられるバリエーションを指します。つまり、特定のルールでターゲットされていないすべてのユーザーに適用されるフォールバックバリエーションです。管理インターフェースでは「それ以外のすべての人に対しては...」セクションのバリエーションとして表示されます。
```python theme={null}
feature_key = "new_checkout"
try:
variation = kameleoon_client.get_variation(visitor_code, feature_key)
# disabling tracking
variation = kameleoon_client.get_variation(visitor_code, feature_key, False)
except FeatureNotFound as ex:
# The error has occurred; the feature flag isn't found in current configuration.
except FeatureEnvironmentDisabled as ex:
# The feature flag is disabled for the environment.
except VisitoCodeNotValid as ex:
# The visitor code you passed to the method is invalid and can't be accepted by SDK.
# Fetch a variable value for the assigned variation
title = variation.variables["title"].value
if variation.key == "on":
# Main variation key is selected for visitorCode
elif variation.key == "alternative_variation":
# Alternative variation key
else:
# Default variation key
```
##### 引数
| 名前 | 型 | 説明 | デフォルト |
| -------------------- | ------ | ------------------------------------ | ------ |
| visitor\_code (*必須*) | `str` | 訪問者の一意の識別子です。 | |
| feature\_key (*必須*) | `str` | 訪問者に公開したい機能のキーです。 | |
| track (*オプション*) | `bool` | 機能評価のトラッキングを有効または無効にするオプションのパラメータです。 | `True` |
##### 戻り値
| 型 | 説明 |
| ----------- | ---------------------------------------------------------- |
| `Variation` | 特定の機能フラグに対して指定された訪問者に割り当てられた [`Variation`](#variation) です。 |
##### スローされる例外
| 型 | 説明 |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| `VisitorCodeInvalid` | 指定された訪問者コードが有効でないことを示す例外です。空または 255 文字を超えています。 |
| `FeatureNotFound` | 要求された機能キーが SDK の内部構成で見つからなかったことを示す例外です。通常、機能フラグが Kameleoon アプリで有効化されていないことを意味します (ただし、機能を実装するコードはすでにアプリケーションにデプロイされています)。 |
| `FeatureEnvironmentDisabled` | 機能フラグが訪問者の現在の環境 (たとえば、production、staging、または development) で無効化されていることを示す例外です。 |
#### get\_variations()
* 📨 *トラッキングデータを Kameleoon に送信します (`track` パラメータに依存)*
すべての機能フラグにわたって指定された訪問者に割り当てられた [`Variation`](#variation) オブジェクトのマップを取得します。
このメソッドは利用可能なすべての機能フラグを反復処理し、指定された訪問者に関連付けられた各フラグに割り当てられた `Variation` を返します。`visitor_code` を必須引数として受け取り、`only_active` と `track` はオプションです。
* `only_active` が `True` に設定されている場合、`get_variations()` メソッドは、ユーザーが `off` バリエーションにバケットされていないことを条件に、機能フラグのバリエーションを返します。
* `track` パラメータは、メソッドがバリエーションの割り当てをトラッキングするかどうかを制御します。デフォルトでは `True` に設定されています。`False` に設定されている場合、トラッキングは無効になります。
返されるマップは、キーとして機能フラグキー、値として対応する `Variation` で構成されます。機能フラグにバリエーションが割り当てられていない場合、メソッドはそのフラグのデフォルト `Variation` を返します。
潜在的な例外を管理するために適切なエラー処理を実装する必要があります。
デフォルトバリエーションは、訪問者が機能フラグの事前定義された配信ルールに一致しない場合に割り当てられるバリエーションを指します。つまり、特定のルールでターゲットされていないすべてのユーザーに適用されるフォールバックバリエーションです。管理インターフェースでは「それ以外のすべての人に対しては...」セクションのバリエーションとして表示されます。
```python theme={null}
try:
variations = kameleoon_client.get_variations(visitor_code)
# only active variations
variations = kameleoon_client.get_variations(visitor_code, only_active=True)
# disable tracking
variations = kameleoon_client.get_variations(visitor_code, track=False)
except VisitorCodeInvalid as ex:
# Handle exception
```
##### 引数
| 名前 | 型 | 説明 | デフォルト |
| ---------------------- | ------ | ----------------------------------------------------------------------- | ------- |
| visitor\_code (*必須*) | `str` | 訪問者の一意の識別子です。 | |
| only\_active (*オプション*) | `bool` | アクティブな (`True`) またはすべての (`False`) 機能フラグのバリエーションを返すかどうかを示すオプションのパラメータです。 | `False` |
| track (*オプション*) | `bool` | 機能評価のトラッキングを有効または無効にするオプションのパラメータです。 | `True` |
##### 戻り値
| 型 | 説明 |
| ---------------------- | ---------------------------------------------------------------------- |
| `Dict[str, Variation]` | 対応する機能のキーを使用して、機能フラグの割り当てられた [`Variation`](#variation) オブジェクトを含むマップです。 |
##### スローされる例外
| 型 | 説明 |
| -------------------- | ---------------------------------------------- |
| `VisitorCodeInvalid` | 指定された訪問者コードが有効でないことを示す例外です。空または 255 文字を超えています。 |
#### get\_data\_file()
すべての機能フラグを評価するには、[`get_variations()`](#get_variations) を使用します。このメソッドは、`DataFile` を呼び出して [`get_variation()`](#get_variation) でフラグを反復処理するよりも効率的です。
現在の SDK 構成を [`DataFile`](#datafile) オブジェクトとして返します。
```python theme={null}
data_file = kameleoon_client.get_data_file()
date_modified = data_file.date_modified
```
##### 戻り値
| 型 | 説明 |
| ---------- | ------------------------------------- |
| `DataFile` | SDK 構成を含む [`DataFile`](#datafile) です。 |
#### set\_forced\_variation()
このメソッドを使用すると、標準の評価プロセスをバイパスして、特定の [`Variation`](#variation) をユーザーにプログラム的に割り当てることができます。これは特に、通常の評価ロジックが不要またはスキップする必要がある制御された実験で価値があります。また、デバッグやカスタムテストなどのシナリオでも役立ちます。
**強制**バリエーションが設定されると、Kameleoon のリアルタイム評価ロジックを上書きします。セグメンテーション、ターゲティング条件、アルゴリズム計算などのプロセスはスキップされます。実験中にセグメンテーションとターゲティング条件を保持するには、代わりに `force_targeting=False` を設定します。
**シミュレートされた**バリエーションは、実行順序で常に優先されます。**シミュレートされた**バリエーションの計算がトリガーされた場合、最初に完全に処理されて完了します。
強制バリエーションは、評価されたバリエーションと同様に扱われます。分析でトラッキングされ、ユーザーコンテキストに保存され、標準の評価されたバリエーションと同様に、レポーティングの一貫性が保たれます。
このメソッドは、特定の条件下で例外をスローする場合があります (たとえば、無効なパラメータ、ユーザーコンテキスト、または内部の問題)。適切な例外処理は、アプリケーションが安定し、堅牢であることを保証するために不可欠です。
**強制**バリエーションと **[シミュレートされた](#get_visitor_code)** バリエーションを区別することが重要です:
* **強制バリエーション**: 個々の実験に固有です。
* **シミュレートされたバリエーション**: 全体的な**機能フラグ**の結果に影響します。
```python theme={null}
experiment_id = 9516
try:
# Forcing the variation "on" for the experiment 9516 for the visitor
kameleoon_client.set_forced_variation(visitor_code, experiment_id, "on")
# Forcing the variation "on" while preserving segmentation and targeting conditions during the experiment
kameleoon_client.set_forced_variation(visitor_code, experiment_id, "on", False)
# Resetting the forced variation for the experiment 9516 for the visitor
kameleoon_client.set_forced_variation(visitor_code, experiment_id, None)
except KameleoonError as e:
# Handling the error
```
##### 引数
| 名前 | 型 | 説明 | デフォルト |
| -------------------------- | --------------- | -------------------------------------------------------------------------------------------- | ------ |
| visitor\_code (*必須*) | `str` | 訪問者の一意の識別子です。 | |
| experiment\_id (*必須*) | `int` | 評価プロセス中にターゲットおよび選択される **Experiment Id** です。 | |
| variation\_key (*必須*) | `Optional[str]` | 実験に対して返される値として強制される `Variation` に対応する **Variation Key** です。値が `None` の場合、強制バリエーションはリセットされます。 | |
| force\_targeting (*オプション*) | `bool` | 実験のターゲティングを強制してスキップするか (`True`)、または標準の評価プロセスのように適用するか (`False`) を示します。 | `True` |
##### スローされる例外
| 型 | 説明 |
| --------------------------- | ----------------------------------------------------------------------------------------------------- |
| `VisitorCodeInvalid` | 指定された訪問者コードが有効でないことを示す例外です。空または 255 文字を超えています。 |
| `FeatureExperimentNotFound` | 要求された実験 ID が SDK の内部構成で見つからなかったことを示す例外です。通常、ルールに対応する実験が Kameleoon 側でまだ有効化されていないことを意味します。 |
| `FeatureVariationNotFound` | 要求されたバリエーションキー (ID) が SDK の内部構成で見つからなかったことを示す例外です。通常、バリエーションに対応する実験が Kameleoon 側でまだ有効化されていないことを意味します。 |
ほとんどの場合、例で示されているように、基本的なエラーである `KameleoonError` のみを処理すればよいです。ただし、異なる種類のエラーに対応する必要がある場合は、それぞれを特定の要件に基づいて個別に処理してください。さらに、信頼性を高めるために、`Exception` を含めることで一般的な言語エラーも処理できます。
#### evaluate\_audiences()
* 📨 *トラッキングデータを Kameleoon に送信します*
このメソッドは、利用可能なすべての Audiences Explorer セグメントに対して訪問者を評価し、一致するものをトラッキングします。
`evaluate_audiences()` は、**関連するすべての訪問者データが設定または更新された後**、機能バリエーションを取得したり機能フラグをチェックしたりする**直前**に呼び出してください。このアプローチにより、訪問者は利用可能な最新のデータに対して評価され、すべての基準に基づいて正確なオーディエンス割り当てが可能になります。
このメソッドを呼び出した後、Audiences Explorer でセグメントパフォーマンスの詳細な分析を実行できます。
```python theme={null}
try:
kameleoon_client.evaluate_audiences(visitor_code)
except KameleoonError as e:
# Handling the error
```
##### 引数
| 名前 | 型 | 説明 |
| -------------------- | ----- | ------------- |
| visitor\_code (*必須*) | `str` | 訪問者の一意の識別子です。 |
##### スローされる例外
| 型 | 説明 |
| -------------------- | ---------------------------------------------- |
| `VisitorCodeInvalid` | 指定された訪問者コードが有効でないことを示す例外です。空または 255 文字を超えています。 |
ほとんどの場合、例で示されているように、基本的なエラーである `KameleoonError` のみを処理すればよいです。ただし、異なる種類のエラーに対応する必要がある場合は、それぞれを特定の要件に基づいて個別に処理してください。さらに、信頼性を高めるために、`Exception` を含めることで一般的な言語エラーも処理できます。
### 訪問者データ
#### get\_visitor\_code()
このメソッドは以前 `obtain_visitor_code` と呼ばれていました。これは SDK バージョン `3.0.0` で削除されました。
`get_visitor_code()` ヘルパーメソッドは、現在の訪問者の Kameleoon **visitor\_code** を取得するために呼び出すべきです。このメソッドは、Kameleoon をフロントエンドとバックエンドの混合環境で使用する際に特に重要であり、ユーザー識別の一貫性を保証する必要があります。実装ロジックは以下のように記述されています。
1. 最初に、現在の HTTP リクエストに関連する **kameleoonVisitorCode** クッキーまたはクエリパラメータが見つかるかをチェックします。見つかった場合、これを訪問者識別子として使用します。
2. 現在のリクエストでクッキー/パラメータが見つからない場合、新しい識別子をランダムに生成するか、渡された場合は **default\_visitor\_code** 引数を識別子として使用します。これにより、顧客が独自の識別子を訪問者コードとして使用することができ、マッチングテーブルでの追加検索なしに、Kameleoon 訪問者と独自のユーザーをマッチさせるという追加の利点があります。
3. いずれの場合も、サーバーサイド (HTTP ヘッダー経由) で **kameleoonVisitorCode** クッキーに値が設定されます。その後、この識別子の値が最終的にメソッドによって返されます。
独自の `visitor_code` を提供する場合は、その一意性を保証する必要があります。SDK は引数として渡される値を検証しません。また、`visitor_code` の長さは **255** 文字に制限されていることに注意してください。この制限を超えると `VisitorCodeInvalid` 例外が発生します。
`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 コンポーネントとしてエンコードする必要があります。
```python theme={null}
### if you use KameleoonWSGIMiddleware service
visitor_code = kameleoon_client.get_visitor_code(cookies_readonly=request.COOKIES)
kameleoon_client.set_legal_consent(visitor_code, True)
### if you want to manage cookies manually
simple_cookies = SimpleCookie()
simple_cookies.load(cookie_header)
visitor_code = kameleoon_client.get_visitor_code(cookies=simple_cookies, default_visitor_code=default_visitor_code)
cookie_header = simple_cookies.output()
```
##### 引数
| 名前 | 型 | 説明 |
| ---------------------- | ----------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| cookies\_readonly | Optional\[Dict\[str, str]] | 読み取り専用のディクショナリで、通常は `request.COOKIES` です。`KameleoonWSGIMiddleware` サービスも使用している場合は、このパラメータを使用してください。このフィールドはオプションです。 |
| cookies | Optinal\[Dict\[str, http.cookies.Morsel\[str]]] | `KameleoonWSGIMiddleware` サービスなしで手動でクッキーを管理する場合、`Dict[str, http.cookies.Morsel[str]]` または `http.cookies.\|SimpleCookie[str]` オブジェクトとして現在の HTTP リクエスト上のクッキーを渡します。このフィールドはオプションです。 |
| default\_visitor\_code | str | リクエストに既存の **kameleoonVisitorCode** クッキーが見つからない場合、このパラメータが **visitor\_code** として使用されます。このフィールドはオプションで、デフォルトではランダムな **visitor\_code** が生成されます。 |
##### 戻り値
| 型 | 説明 |
| --- | ---------------------------------------------------------------- |
| str | この特定のユーザーに関連付けられる **visitor\_code** で、当社の SDK メソッドのほとんどで使用すべきです。 |
##### スローされる例外
| 型 | 説明 |
| ------------------ | ---------------------------------------------- |
| VisitorCodeInvalid | 指定された訪問者コードが無効であることを示す例外です。空または 255 文字を超えています。 |
#### 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) は例外です。訪問者はインデックスごとに 1 つの関連付けられた `CustomData` のインスタンスを持つことができます。
```python theme={null}
require "kameleoon"
require "kameleoon/data"
# Add a single data item (tracked by default)
kameleoon_client.add_data(visitor_code, Browser(BrowserType.CHROME))
# Add multiple data items (tracked by default)
kameleoon_client.add_data(
visitor_code,
PageView("https://url.com", "title", [3]),
UserAgent("UserAgent")
)
# Add multiple data items stored locally for targeting only (not sent to the Kameleoon Data API)
kameleoon_client.add_data(
visitor_code,
PageView("https://url.com", "title", [3]),
UserAgent("UserAgent"),
track=False
)
```
##### 引数
| 名前 | 型 | 説明 | デフォルト値 |
| -------------------- | ------- | ---------------------------------------------------------------------------------------------------------- | ------ |
| visitor\_code (*必須*) | `str` | 訪問者の一意の識別子です。 | |
| data (*必須*) | `*Data` | Kameleoon データタイプのコレクションです。 | |
| track (*オプション*) | `bool` | 追加されたデータがトラッキングの対象であるかを指定します。`False` に設定すると、データはローカルに保存され、ターゲティング評価にのみ使用されます。Kameleoon Data API には送信されません。 | `True` |
##### 例外
| 型 | 説明 |
| -------------------- | ---------------------------------------------- |
| `VisitorCodeInvalid` | 指定された訪問者コードが有効でないことを示す例外です。空または 255 文字を超えています。 |
#### flush()
* 📨 *トラッキングデータを Kameleoon に送信します*
`flush()` は訪問者に関連付けられた Kameleoon データと、[これらのメソッド](/developer-docs/feature-experimentation/technical-reference/faq-global#when-does-the-sdk-send-a-tracking-request-for-analytics)のいずれかを呼び出したときにまだ送信されていない、以前に `add_data` メソッドを使用して追加されたすべてのデータを取得し、トラッキングリクエストを送信します。`flush()` は非ブロッキングであり、サーバー呼び出しは非同期で行われます。
`flush()` を使用すると、指定された `visitor_code` に関連付けられたデータがサーバーに送信されるタイミングを制御できます。たとえば、`add_data()` を 12 回呼び出す場合、`add_data()` が呼び出されるたびにサーバーにデータを送信するのは非効率なので、最後に `flush()` を 1 回だけ呼び出せばよいのです。
`visitor_code` を指定すると、`flush()` メソッドはそれを一意の訪問者識別子として使用します。これは[クロスデバイス実験](/developer-docs/cross-device-experimentation)に便利です。`visitor_code` を指定して `is_unique_identifier` パラメータを `true` に設定すると、SDK はフラッシュされたデータを指定された識別子に関連付けられた訪問者にリンクします。
パラメータ `is_unique_identifier` は非推奨です。代わりに [`UniqueIdentifier`](#uniqueidentifier) を使用してください。
`is_unique_identifier` は、もともと訪問者に割り当てられた匿名 `visitor_code` にアクセスできないが、セッションマージ機能を使用して匿名訪問者と接続されている内部 ID にアクセスできる場合など、他のエッジケースシナリオでも役立ちます。
```python theme={null}
kameleoon_client.add_data(visitor_code, Browser(BrowserType.CHROME))
kameleoon_client.add_data(
visitor_code,
PageView("https://url.com", "title", [3]),
CustomData(0, "value")
)
kameleoon_client.add_data(visitor_code, Conversion(32, 10, false))
kameleoon_client.flush(visitor_code) # Interval tracking (most performant way for tracking)
kameleoon_client.flush(visitor_code, instant=True) # Instant tracking
# If you operate with unique ID
kameleoon_client.add_data(UniqueIdentifier(True))
kameleoon_client.flush(visitor_code)
```
##### 引数
| 名前 | 型 | 説明 |
| ---------------------------- | --------------- | ----------------------------------------------------------------------------------------------------------------------- |
| visitor\_code | String | ユーザーの一意の識別子です。このフィールドは必須です。 |
| is\_unique\_identifier (非推奨) | Optional\[bool] | `True` のとき、SDK はフラッシュされたデータを指定された識別子に関連付けられた訪問者にリンクします。 |
| instant | bool | データを即座に送信するか (`True`)、またはスケジュールされたトラッキング間隔に従って送信するか (`False`) を示すブール値フラグです。提供されない場合、デフォルト値は `False` です。このフィールドはオプションです。 |
#### get\_remote\_data()
* 以前は `retrieve_data_from_remote_source` と呼ばれていました。これは SDK バージョン `3.0.0` で削除されました。
* データを非同期で取得したい場合は、代わりに `get_remote_data_async` メソッドを使用してください (バージョン 2.3.0 以降で利用可能)。
`get_remote_data` メソッドは、リモート Kameleoon サーバーに保存されている指定された **site\_code** (`KameleoonClient.__init__` で指定) に対して、引数として渡された **キー** に従って、データを同期的に取得します。データは通常、当社の Data API を介してリモートサーバーに保存されます。このメソッドと、この目的のための高スケーラブルなサーバーの可用性が、訪問者/ユーザーごとに取得できる大量のデータを保存するための便利な方法を提供します。
```python theme={null}
kameleoon_client.get_remote_data('key1') # default timeout
kameleoon_client.get_remote_data('key2', 1.0) # 1 second timeout
```
##### 引数
| 名前 | 型 | 説明 |
| ------- | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| key | str | データに関連付けられているキーです。このフィールドは必須です。 |
| timeout | Optional\[float] | タイムアウト (秒単位) です。このパラメータは、メソッドが結果を待つために最大ブロックできる時間を指定します。このフィールドはオプションです。提供されない場合、構成ファイルの `default_timeout_millisecond` 値を使用するか、ファイルで指定されていない場合は 2 秒を使用します。 |
##### 戻り値
| 型 | 説明 |
| ----------- | -------------------------------------- |
| JSON object | 特定の**キー**のデータ取得に関連付けられた JSON オブジェクトです。 |
#### get\_remote\_data\_async()
`get_remote_data_async` メソッドを使用すると、リモート Kameleoon サーバーに保存されている指定された **site\_code** (`KameleoonClient.__init__` で指定) に対して、引数として渡された **キー** に従って、データを非同期で取得できます。データは通常、当社の Data API を介してリモートサーバーに保存されます。このメソッドと、この目的のための高スケーラブルなサーバーの可用性が、訪問者/ユーザーごとに取得できる大量のデータを保存するための便利な方法を提供します。
```python theme={null}
await kameleoon_client.get_remote_data_async('key1') # default timeout
await kameleoon_client.get_remote_data_async('key2', 1.0) # 1 second timeout
```
##### 引数
| 名前 | 型 | 説明 |
| ------- | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| key | str | データに関連付けられているキーです。このフィールドは必須です。 |
| timeout | Optional\[float] | タイムアウト (秒単位) です。このパラメータは、メソッドが結果を待つために最大ブロックできる時間を指定します。このフィールドはオプションです。提供されない場合、構成ファイルの `default_timeout_millisecond` 値を使用するか、ファイルで指定されていない場合は 2 秒を使用します。 |
##### 戻り値
| 型 | 説明 |
| ----------- | -------------------------------------- |
| JSON object | 特定の**キー**のデータ取得に関連付けられた JSON オブジェクトです。 |
#### get\_remote\_visitor\_data()
`get_remote_visitor_data()` は、Kameleoon Data API から `visitor_code` の Kameleoon Visits Data を取得する非同期メソッドです。このメソッドはデータをストレージに追加し、ターゲティングの決定を行う際に他のメソッドが使用できるようにします。
このメソッドで取得したデータは、次のような場合に重要な役割を果たします。
* 他のデバイスから収集されたデータを使用する場合。
* ユーザーの履歴 (過去の訪問中に閲覧したページなど) にアクセスする場合。
* データレイヤー変数やフロントエンドでのみコンバージョンするゴールなど、クライアントサイドでのみアクセス可能なデータを使用する場合。
可能なユースケースをよりよく理解するには、[この記事](/developer-docs/feature-experimentation/targeting-and-segmentation/native-segmentation)を読んでください。
デフォルトでは、`get_remote_visitor_data()` は `scope=visitor` の最新の保存済みカスタムデータを自動的に取得し、`add_data()` メソッドを呼び出すことなく訪問者に追加します。これは[複数のデバイス間でカスタムデータを同期する](/developer-docs/sdks/web-sdks/nodejs-sdk#synchronizing-custom-data-across-devices)場合に特に便利です。
パラメータ `is_unique_identifier` は非推奨です。代わりに [`UniqueIdentifier`](#uniqueidentifier) を使用してください。
`is_unique_identifier` は、もともと訪問者に割り当てられた匿名 `visitor_code` にアクセスできないが、セッションマージ機能を使用して匿名訪問者と接続されている内部 ID にアクセスできる場合など、他のエッジケースシナリオでも役立ちます。
```python theme={null}
visitor_code = 'visitorCode'
# Visitor data will be fetched and automatically added for `visitor_code`
data_list = kameleoon_client.get_remote_visitor_data(visitor_code) # default timeout
data_list = kameleoon_client.get_remote_visitor_data(visitor_code, timeout=1.0) # 1 second timeout
# If you only want to fetch data and add it yourself manually, set `add_data` to `False`
data_list = kameleoon_client.get_remote_visitor_data(visitor_code, False) # default timeout
data_list = kameleoon_client.get_remote_visitor_data(visitor_code, False, 1.0) # 1 second timeout
# If you want to fetch custom list of data types
data_filter = RemoteVisitorDataFilter(25, customData=False, conversions=True, experiments=True)
data_list = kameleoon_client.get_remote_visitor_data(visitor_code, data_filter=data_filter)
# If you want the SDK to link the extracted data with the visitor associated with the specified identifier.
kameleoon_client.add_data(UniqueIdentifier(True))
data_list = kameleoon_client.get_remote_visitor_data(visitor_code)
```
##### 引数
| 名前 | 型 | 説明 |
| ---------------------------- | ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| visitor\_code | str | 割り当てられたデータを取得したい訪問者コードです。このフィールドは必須です。 |
| add\_data | bool | 取得したデータを訪問者に自動的に追加すべきかを示すブール値です。指定されていない場合、デフォルト値は **True** です。このフィールドはオプションです。 |
| data\_filter | RemoteVisitorDataFilter | 訪問から取得すべきデータを指定するフィルタです。デフォルトでは、`CustomData` のみが現在および最新の以前の訪問から取得されます (`RemoteVisitorDataFilter(previousVisitAmount=1, currentVisit=True, customData=True)` または `RemoteVisitorDataFilter()`)。その他のフィルタパラメータは `False` に設定されます。このフィールドはオプションです。 |
| is\_unique\_identifier (非推奨) | Optional\[bool] | `visitorCode` が一意の識別子であるかを指定するオプションのパラメータです。指定されていない場合、デフォルト値は `False` です。このフィールドはオプションです。 |
| timeout | Optional\[float] | タイムアウト (秒単位) です。このパラメータは、メソッドが結果を待つために最大ブロックできる時間を指定します。このフィールドはオプションです。提供されない場合、構成ファイルの `default_timeout_millisecond` 値を使用するか、ファイルで指定されていない場合は 2 秒を使用します。 |
##### get\_remote\_visitor\_data() でのパラメータの使用
`get_remote_visitor_data()` メソッドは、訪問者に関するデータを取得する際にさまざまなパラメータを定義できるという柔軟性を提供します。ゴール、実験、またはバリエーションに基づいてターゲットを設定する場合でも、同じアプローチがすべてのデータタイプに適用されます。
たとえば、「Order transaction」というゴールを完了した訪問者のデータを取得したいとします。`get_remote_visitor_data()` メソッド内でパラメータを指定して、ターゲティングを絞り込むことができます。たとえば、過去 5 回の訪問でゴールを達成したユーザーのみをターゲットにしたい場合は、`previous_visit_amount` パラメータを 5 に、`conversions` を true に設定できます。
この例で示されている柔軟性は、ゴールデータに限定されていません。`get_remote_visitor_data()` メソッド内でパラメータを使用して、さまざまな訪問者の行動に関するデータを取得できます。
##### 戻り値
| 型 | 説明 |
| ----------- | -------------------------- |
| List\[Data] | 指定された訪問者に割り当てられたデータのリストです。 |
利用可能な `Kameleoon::Configuration::RemoteVisitorDataFilter` オプションのリストは次のとおりです。
| 名前 | 型 | 説明 | デフォルト |
| --------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| previous\_visit\_amount (*オプション*) | `int` | データを取得する以前の訪問回数。`1` から `25` までの数値 | `1` |
| current\_visit (*オプション*) | `bool` | True の場合、現在の訪問データが取得されます。 | `True` |
| custom\_data (*オプション*) | `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 (KCS) が取得されます。[AI Predictive Targeting アドオン](/user-manual/ai-predictive-targeting/target-users-based-on-likelihood-to-convert) が必要です | `False` |
| visitor\_code (*オプション*) | `bool` | true の場合、Kameleoon は最新の訪問から `visitorCode` を取得し、現在の訪問に使用します。これは、`visitorCode` で識別された訪問者が、[クロスデバイス実験](/developer-docs/cross-device-experimentation) の訪問間で常に同じバリエーションを受け取るようにしたい場合に必要です。 | `True` |
| cbs (*オプション*) | `bool` | true の場合、Contextual Bandit スコアデータが取得されます。 | `False` |
| personalization (*オプション*) | `bool` | True の場合、パーソナライゼーションデータが取得されます。これはパーソナライゼーション条件に必要です。 | `False` |
#### get\_remote\_visitor\_data\_async()
`get_remote_visitor_data_async` メソッドは、リモート Kameleoon サーバーに保存されている訪問者 (**visitor\_code** 引数で指定) のカスタムデータを非同期で取得します。**add\_data** が **True** の場合、このメソッドは取得したデータを訪問者に自動的に追加し、別途 `add_data` を呼び出す必要はありません。
以前に当社のリモートサーバーに保存されたデータが必要です。これは、SDK の次のトラッキング呼び出しのいずれかで追加できます。
* `flush`
* `get_feature_variation_key`
* `get_feature_variable`
* `is_feature_active`
`get_remote_visitor_data` メソッドを当社の高スケーラブルなサーバーの可用性と一緒に使用すると、訪問者のすべてのデバイス間で大量のデータにアクセスして同期する便利な方法が提供されます。
`visitor_code` を指定すると、`get_remote_visitor_data_async` メソッドは `visitor_code` を一意の訪問者識別子として使用します。これは[クロスデバイス実験](/developer-docs/cross-device-experimentation)に便利です。`visitor_code` を指定して `is_unique_identifier` パラメータを `true` に設定すると、SDK はフラッシュされたデータを指定された識別子に関連付けられた訪問者にリンクします。
パラメータ `is_unique_identifier` は非推奨です。代わりに [`UniqueIdentifier`](#uniqueidentifier) を使用してください。
`is_unique_identifier` は、もともと訪問者に割り当てられた匿名 `visitor_code` にアクセスできないが、セッションマージ機能を使用して匿名訪問者と接続されている内部 ID にアクセスできる場合など、他のエッジケースシナリオでも役立ちます。
```python theme={null}
visitor_code = 'visitorCode'
# Visitor data will be fetched and automatically added for `visitor_code`
data_list = await kameleoon_client.get_remote_visitor_data_async(visitor_code) # default timeout
data_list = await kameleoon_client.get_remote_visitor_data_async(visitor_code, timeout=1.0) # 1 second timeout
# If you only want to fetch data and add it yourself manually, set `add_data` to `False`
data_list = await kameleoon_client.get_remote_visitor_data_async(visitor_code, False) # default timeout
data_list = await kameleoon_client.get_remote_visitor_data_async(visitor_code, False, 1.0) # 1 second timeout
# If you want to fetch custom list of data types
data_filter = RemoteVisitorDataFilter(25, customData=False, conversions=True, experiments=True)
data_list = kameleoon_client.get_remote_visitor_data(visitor_code, data_filter=data_filter)
# If you want the SDK to link the extracted data with the visitor associated with the specified identifier.
kameleoon_client.add_data(UniqueIdentifier(True))
data_list = kameleoon_client.get_remote_visitor_data(visitor_code)
```
##### 引数
| 名前 | 型 | 説明 |
| ---------------------------- | ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| visitor\_code | str | 割り当てられたデータを取得したい訪問者コードです。このフィールドは必須です。 |
| add\_data | bool | 取得したデータを訪問者に自動的に追加すべきかを示すブール値です。指定されていない場合、デフォルト値は **True** です。このフィールドはオプションです。 |
| data\_filter | RemoteVisitorDataFilter | 訪問から取得すべきデータを指定するフィルタです。デフォルトでは、`CustomData` のみが現在および最新の以前の訪問から取得されます (`RemoteVisitorDataFilter(previousVisitAmount=1, currentVisit=True, customData=True)` または `RemoteVisitorDataFilter()`)。その他のフィルタパラメータは `False` に設定されます。このフィールドはオプションです。 |
| is\_unique\_identifier (非推奨) | Optional\[bool] | `visitorCode` が一意の識別子であるかを指定するオプションのパラメータです。指定されていない場合、デフォルト値は `False` です。このフィールドはオプションです。 |
| timeout | Optional\[float] | タイムアウト (秒単位) です。このパラメータは、メソッドが結果を待つために最大ブロックできる時間を指定します。このフィールドはオプションです。提供されない場合、構成ファイルの `default_timeout_millisecond` 値を使用するか、ファイルで指定されていない場合は 2 秒を使用します。 |
##### 戻り値
| 型 | 説明 |
| ----------- | --------------------- |
| List\[Data] | 訪問者に割り当てられたデータのリストです。 |
##### get\_remote\_visitor\_data\_async() でのパラメータの使用
`get_remote_visitor_data_async()` メソッドは、訪問者に関するデータを取得する際にさまざまなパラメータを定義できるという柔軟性を提供します。ゴール、実験、またはバリエーションに基づいてターゲットを設定する場合でも、同じアプローチがすべてのデータタイプに適用されます。
たとえば、「Order transaction」というゴールを完了した訪問者のデータを取得したいとします。`get_remote_visitor_data_async()` メソッド内でパラメータを指定して、ターゲティングを絞り込むことができます。たとえば、過去 5 回の訪問でゴールを達成したユーザーのみをターゲットにしたい場合は、`previous_visit_amount` パラメータを 5 に、`conversions` を true に設定できます。
この例で示されている柔軟性は、ゴールデータに限定されていません。`get_remote_visitor_data_async()` メソッド内でパラメータを使用して、さまざまな訪問者の行動に関するデータを取得できます。
利用可能な `Kameleoon::Configuration::RemoteVisitorDataFilter` オプションのリストは次のとおりです。
| 名前 | 型 | 説明 | デフォルト |
| --------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| previous\_visit\_amount (*オプション*) | `int` | データを取得する以前の訪問回数。`1` から `25` までの数値 | `1` |
| current\_visit (*オプション*) | `bool` | True の場合、現在の訪問データが取得されます。 | `True` |
| custom\_data (*オプション*) | `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 (KCS) が取得されます。[AI Predictive Targeting アドオン](/user-manual/ai-predictive-targeting/target-users-based-on-likelihood-to-convert) が必要です | `False` |
| visitor\_code (*オプション*) | `bool` | true の場合、Kameleoon は最新の訪問から `visitorCode` を取得し、現在の訪問に使用します。これは、`visitorCode` で識別された訪問者が、[クロスデバイス実験](/developer-docs/cross-device-experimentation) の訪問間で常に同じバリエーションを受け取るようにしたい場合に必要です。 | `True` |
| cbs (*オプション*) | `bool` | true の場合、Contextual Bandit スコアデータが取得されます。 | `False` |
#### get\_visitor\_warehouse\_audience()
指定された **visitor\_code** および **warehouse\_key** を使用して、データウェアハウス内の訪問者に関連付けられたすべてのオーディエンスデータを同期的に取得します。**warehouse\_key** は通常、内部ユーザー ID です。**custom\_data\_index** パラメータは、Kameleoon が訪問者をターゲットにするために使用する Kameleoon カスタムデータに対応します。追加の詳細については、[ウェアハウスターゲティングドキュメント](/user-manual/integrations/data-warehouses/bigquery/use-bigquery-as-a-source-audience-targeting)を参照してください。メソッドは `CustomData` オブジェクトを返し、データが訪問者に追加され、ターゲティング目的で利用可能であることを確認します。
データを非同期で取得したい場合は、代わりに `get_visitor_warehouse_audience_async` メソッドを使用してください。
```python theme={null}
try:
warehouse_audience_data = kameleoon_client.\
get_visitor_warehouse_audience(visitor_code, custom_data_index) # default timeout
warehouse_audience_data = kameleoon_client.\
get_visitor_warehouse_audience(visitor_code, custom_data_index, timeout=1.0) # 1 second timeout
warehouse_audience_data = kameleoon_client.\
get_visitor_warehouse_audience(visitor_code, custom_data_index, warehouse_key) # default timeout
warehouse_audience_data = kameleoon_client.\
get_visitor_warehouse_audience(visitor_code, custom_data_index, warehouse_key, 1.0) # 1 second timeout
# Your custom code
except VisitorCodeInvalid as e:
# Handle exception
```
##### 引数
| 名前 | 型 | 説明 |
| ------------------- | ---------------- | ------------------------------------------------------------------------------------- |
| visitor\_code | str | 一意の訪問者識別文字列です。255 文字を超えることはできません。このフィールドは必須です。 |
| custom\_data\_index | int | BigQuery Audiences をターゲットにするために使用したいカスタムデータのインデックスを表す整数です。このフィールドは必須です。 |
| warehouse\_key | Optional\[str] | ウェアハウスデータを識別する一意のキー (通常は内部ユーザー ID) です。このフィールドはオプションです。 |
| timeout | Optional\[float] | タイムアウト (秒単位) です。このパラメータは、結果を待つために最大の時間を指定します。このフィールドはオプションです。提供されない場合、デフォルト値は 10 秒です。 |
##### 戻り値
| 型 | 説明 |
| --------------------- | ------------------------------------------- |
| Optional\[CustomData] | データが訪問者に追加されたことを確認する `CustomData` インスタンスです。 |
##### スローされる例外
| 型 | 説明 |
| ------------------ | ---------------------------------------------- |
| VisitorCodeInvalid | 指定された訪問者コードが有効でないことを示す例外です。空または 255 文字を超えています。 |
#### get\_visitor\_warehouse\_audience\_async()
指定された **visitor\_code** および **warehouse\_key** を使用して、データウェアハウス内の訪問者に関連付けられたすべてのオーディエンスデータを非同期で取得します。**warehouse\_key** は通常、内部ユーザー ID です。**custom\_data\_index** パラメータは、Kameleoon が訪問者をターゲットにするために使用する Kameleoon カスタムデータに対応します。追加の詳細については、[ウェアハウスターゲティングドキュメント](/user-manual/integrations/data-warehouses/bigquery/use-bigquery-as-a-source-audience-targeting)を参照してください。メソッドは `CustomData` オブジェクトを返し、データが訪問者に追加され、ターゲティング目的で利用可能であることを確認します。
```python theme={null}
try:
warehouse_audience_data = await kameleoon_client.\
get_visitor_warehouse_audience_async(visitor_code, custom_data_index) # default timeout
warehouse_audience_data = await kameleoon_client.\
get_visitor_warehouse_audience_async(visitor_code, custom_data_index, timeout=1.0) # 1 second timeout
warehouse_audience_data = await kameleoon_client.\
get_visitor_warehouse_audience_async(visitor_code, custom_data_index, warehouse_key) # default timeout
warehouse_audience_data = await kameleoon_client.\
get_visitor_warehouse_audience_async(visitor_code, custom_data_index, warehouse_key, 1.0) # 1 second timeout
# Your custom code
except VisitorCodeInvalid as e:
# Handle exception
```
##### 引数
| 名前 | 型 | 説明 |
| ------------------- | ---------------- | ------------------------------------------------------------------------------------- |
| visitor\_code | str | 一意の訪問者識別文字列です。255 文字を超えることはできません。このフィールドは必須です。 |
| custom\_data\_index | int | BigQuery Audiences をターゲットにするために使用したいカスタムデータのインデックスを表す整数です。このフィールドは必須です。 |
| warehouse\_key | Optional\[str] | ウェアハウスデータを識別する一意のキー (通常は内部ユーザー ID) です。このフィールドはオプションです。 |
| timeout | Optional\[float] | タイムアウト (秒単位) です。このパラメータは、結果を待つために最大の時間を指定します。このフィールドはオプションです。提供されない場合、デフォルト値は 10 秒です。 |
##### 戻り値
| 型 | 説明 |
| --------------------- | ------------------------------------------- |
| Optional\[CustomData] | データが訪問者に追加されたことを確認する `CustomData` インスタンスです。 |
##### スローされる例外
| 型 | 説明 |
| ------------------ | ---------------------------------------------- |
| VisitorCodeInvalid | 指定された訪問者コードが無効であることを示す例外です。空または 255 文字を超えています。 |
#### set\_legal\_consent()
このメソッドを使用して、訪問者が個人データの使用に法的同意を与えているかを指定する必要があります。`consent` パラメータを `False` に設定すると、トラッキングリクエストに含めることができるデータタイプが制限されます。このメソッドは、訪問者データを責任を持って管理しながら法的および規制要件を遵守するのに役立ちます。個人データに関する詳細は、[同意管理ポリシー](/user-manual/project-management/consent-management-policy)を参照してください。
```python theme={null}
### if you use KameleoonWSGIMiddleware service
visitor_code = kameleoon_client.get_visitor_code(cookies_readonly=request.COOKIES)
kameleoon_client.set_legal_consent(visitor_code, True)
### if you want to manage cookies manually
cookies = http.cookies.SimpleCookie()
cookies.load(cookie_header)
visitor_code = kameleoon_client.get_visitor_code(cookies=cookies)
kameleoon_client.set_legal_consent(visitor_code, True, cookies)
cookie_header = cookies.output()
```
##### 同意の取り消し動作
`consent=False` で `set_legal_consent()` を呼び出した場合、SDK は `kameleoonVisitorCode` クッキーを削除しません。代わりに、クッキーの有効期限を延長することを停止し、クッキーが自然に期限切れになるまで保持されます。
コンプライアンス要件でオプトアウト時にクッキーファイルを即座に削除する必要がある場合は、フレームワークのネイティブクッキー管理メソッドを使用して手動で削除する必要があります。SDK はファイルを自動的に削除しません。
##### 引数
| 名前 | 型 | 説明 |
| ------------- | ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------ |
| visitor\_code | str | ユーザーの一意の識別子です。このフィールドは必須です。 |
| consent | bool | 法的同意のステータスを表すブール値です。`true` は訪問者が法的同意を与えていることを示し、`false` は訪問者が法的同意を一度も提供していないか撤回したことを示します。このフィールドは必須です。 |
| cookies | Optional\[Dict\[str, http.cookies.Morsel\[str]]] | 法的同意のステータスに基づいて調整されるクッキーを、`Dict[str, http.cookies.Morsel[str]]` または `http.cookies.SimpleCookie[str]` オブジェクトとして指定します。このフィールドはオプションです。 |
##### スローされる例外
| 型 | 説明 |
| ------------------ | ---------------------------------------------- |
| VisitorCodeInvalid | 指定された訪問者コードが無効であることを示す例外です。空または 255 文字を超えています。 |
#### forget()
`forget` メソッドは、指定された **site\_code** を持つ `KameleoonClient` インスタンスを `KameleoonClientFactory` から削除し、`KameleoonClient` インスタンスが使用するリソースを解放します。`forget` メソッドを呼び出した後は、`KameleoonClient` インスタンスを使用してはなりません。
`visitor_code` を指定すると、`track_conversion` メソッドは `visitor_code` を一意の訪問者識別子として使用します。これは[クロスデバイス実験](/developer-docs/cross-device-experimentation)に便利です。`visitor_code` を指定して `is_unique_identifier` パラメータを `true` に設定すると、SDK はフラッシュされたデータを指定された識別子に関連付けられた訪問者にリンクします。
`is_unique_identifier` は、もともと訪問者に割り当てられた匿名 `visitor_code` にアクセスできないが、セッションマージ機能を使用して匿名訪問者と接続されている内部 ID にアクセスできる場合など、他のエッジケースシナリオでも役立ちます。
```python theme={null}
require "kameleoon"
require "kameleoon/data"
visitor_code = kameleoon_client.get_visitor_code(request.COOKIES)
goal_id = 83023
kameleoon_client.add_data(visitor_code, Browser(BrowserType.CHROME))
kameleoon_client.add_data(
visitor_code,
PageView("https://url.com", "title", [3]),
CustomData(2, "value")
)
kameleoon_client.add_data(visitor_code, Conversion(32, 10, false))
kameleoon_client.track_conversion(visitor_code, goal_id)
```
##### 引数
| 名前 | 型 | 説明 |
| ---------------------- | ------ | ------------------------------------------------------- |
| visitor\_code | String | ユーザーの一意の識別子です。このフィールドは必須です。 |
| goal\_id | int | ゴールの ID です。このフィールドは必須です。 |
| revenue | float | コンバージョンの収益です。このフィールドはオプションです。 |
| is\_unique\_identifier | bool | `True` のとき、SDK はフラッシュされたデータを指定された識別子に関連付けられた訪問者にリンクします。 |
### ゴールとサードパーティ分析
#### 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)を参照してください。
```python theme={null}
engine_tracking_code = kameleoon_client.get_engine_tracking_code(visitor_code)
```
* この機能を使用するには、Python 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 の `