> ## 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.
# Ruby SDK
> Kameleoon Ruby SDK を統合して、Ruby バックエンドサーバーや Rails アプリケーションで実験を実行し、機能フラグを有効化します。
Ruby SDK を使用すると、バックエンドの Ruby サーバーで実験を実行し、機能フラグを有効化できます。SDK を Web アプリケーションに統合するのは容易で、フットプリント(メモリおよびネットワーク使用量)も低く抑えられています。
**はじめに**: 開始方法については、[開発者ガイド](#開発者ガイド)を参照してください。
**変更履歴**: Ruby SDK の最新バージョン: 3.20.0 [変更履歴](https://github.com/Kameleoon/client-ruby/blob/master/CHANGELOG.md)。
**SDK メソッド**: Ruby SDK の完全なリファレンスドキュメントは、[リファレンス](#リファレンス)セクションを参照してください。
## 開発者ガイド
このセクションでは、SDK を統合し、Ruby アプリケーションで実験を開始する方法を説明します。このチュートリアルに従って、異なるバリエーションに基づいて推奨製品の数を変更する簡単な A/B テストを設定します。
### はじめに
#### SDK のインストール
SDK は、公式の RubyGems リポジトリでホストされている標準的な gem パッケージを使用してインストールします。インストールするには、次のコマンドを実行します。
```cli theme={null}
gem install kameleoon-client-ruby
```
#### クライアントの設定
Ruby SDK の認証情報は設定ファイルで提供します。このファイルを使用して SDK の動作をカスタマイズすることもできます。[サンプル設定ファイル](/assets/developer-docs/sdks/web-sdks/client-configs/client-ruby.yaml)から始めることができます。このファイルはデフォルトのパス `/etc/kameleoon/client-ruby.yaml` に追加することを推奨します。別の場所を使用する場合は、初期化中に `Kameleoon::KameleoonClientFactory.Create()` メソッドへの引数としてパスを渡す必要があります。最新の 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 がアクティブな実験と機能フラグの設定を取得する更新間隔(分単位)を指定します。この値によって、機能フラグの有効化/無効化や実験の起動などの変更が本番サーバーに反映されるまでの最大時間が決まります。さらに、サーバー送信イベント (SSE) を使用して、新しい設定を SDK に自動的にプッシュし、遅延なくリアルタイムに新しい設定を適用する[ストリーミングモード](/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` ミリ秒(デフォルト)、最大値は `5000` ミリ秒です。 | `1000` ミリ秒 |
| `environment` (*任意*) | 機能フラグの設定を使用する環境です。値は `production`、`staging`、`development` のいずれかです。詳細は[環境の管理](/user-manual/experimentation/feature-experimentation/configure-your-feature-flags/manage-environments)の記事を参照してください。 | `production` |
| `top_level_domain` *(ハイブリッドモードでは必須)* | あなたのウェブサイトの現在のトップレベルドメイン。`example.com` の形式を使用します。`https://`、`www`、その他のサブドメインは含めないでください。Kameleoon はこの情報を使用して、トップレベルドメインに対応するクッキーを設定します。 | `nil` |
| `network_domain` (*任意*) | SDK が送信リクエスト(プロキシ用途など)に使用するカスタムドメイン。有効なドメイン(例: example.com または sub.example.com)である必要があります。形式が無効な場合は、Kameleoon のデフォルト値が使用されます。 | `nil` |
| `verbose_mode` *(非推奨)* | ネットワークリクエストやデバッグ情報を含む追加のログ出力を有効にするブール値(`true` または `false`)。このフィールドは非推奨であり、SDK バージョン `4.0.0` で削除されます。代わりに [`KameleoonLogger.setLogLevel`](#ログレベル) を使用してください。 | `nil` |
Kameleoon Ruby SDK は Automation API を使用し、OAuth 2.0 のクライアントクレデンシャルフローに従います。
#### クライアントの初期化
SDK をアプリケーションにインストールし、正しい認証情報(`/etc/kameleoon/client-ruby.yaml` または `Kameleoon::KameleoonClientConfig` 内)を設定したら、Kameleoon アプリでサーバーサイドの実験を設定する必要があります。
次のステップは、アプリケーションコード内で Kameleoon クライアントを作成することです。以下のコードは Kameleoon クライアントの作成例です。`Kameleoon::KameleoonClient` は、アプリケーションと Kameleoon の間のブリッジとして機能するシングルトンオブジェクトです。実験を実行するために必要なすべてのメソッドとプロパティが含まれています。
Kameleoon で A/B テストを実装する際、開発者はアプリケーションコードの正しいロジックを確保する責任があります。ベストプラクティスとしては、実験がまだ起動されていない場合に訪問者が実験から除外される可能性があると常に想定することです。これはデフォルトまたはリファレンスバリエーションのロジック(常に存在するべきもの)と整合するため、実装は容易です。次のセクションのコードサンプルはこのアプローチを示しています。
```ruby theme={null}
# external settings file
require "kameleoon"
site_code = "a8st4f59bj"
kameleoon_client = Kameleoon::KameleoonClientFactory.create(site_code)
kameleoon_client = Kameleoon::KameleoonClientFactory.create(site_code, config_path: '/etc/kameleoon/client-ruby.yaml')
# internal KameleoonClientConfig object
require 'kameleoon'
require 'kameleoon/kameleoon_client_config'
kameleoon_config = Kameleoon::KameleoonClientConfig.new(
'client_id', # required
'client_secret', # required
refresh_interval_minute: configuration_refresh_interval, # (in minutes) optional, default: 60 minutes
session_duration_minute: session_duration, # (in minutes) optional, default: 30 minutes
default_timeout_millisecond: default_timeout, # (in milliseconds) optional, default: 2000 milliseconds
tracking_interval_millisecond: tracking_interval, # (in milliseconds) optional (1000 ms by default)
environment: environment, # optional, possible values: "production" / "staging" / "development" / "staging", default: "production"
top_level_domain: 'example.com',
verbose_mode: verbose_mode, # optional, default: false
network_domain: 'example.com' # optional
)
kameleoon_client = Kameleoon::KameleoonClientFactory.create(site_code, config: kameleoon_config)
```
Ruby on Rails を使用している場合は、application.rb ファイルでサーバー起動時に Kameleoon クライアントを初期化することをお勧めします。
```ruby theme={null}
require_relative 'boot'
require 'rails/all'
require 'kameleoon'
Bundler.require(*Rails.groups)
module App
class Application < Rails::Application
# Initialize configuration defaults for originally generated Rails version.
config.load_defaults 6.1
if defined?(Rails::Server)
config.after_initialize do
site_code = 'a8st4f59bj'
kameleoon_config = Kameleoon::KameleoonClientConfig.new('client_id', 'client_secret')
config.kameleoon_client = Kameleoon::KameleoonClientFactory.create(site_code, config: kameleoon_config)
end
end
end
end
```
その後、コントローラ内で Kameleoon クライアントにアクセスできます。
```ruby theme={null}
class YourController < ApplicationController
def index
kameleoon_client = App::Application.config.kameleoon_client
# Your controller code, using the kameleoon_client
end
end
```
#### 機能フラグの有効化
##### ユーザーへの一意な ID の割り当て
ユーザーに一意な ID を割り当てるには、[`get_visitor_code()`](#get_visitor_code) メソッドを使用できます。**visitor code** が存在しない場合(リクエストヘッダーのクッキーから)、メソッドはランダムな一意の ID を生成するか、あなたが生成した `default_visitor_code` を使用します。その後、ID はレスポンスヘッダーのクッキーに設定されます。
Kameleoon を[ハイブリッドモード](/developer-docs/feature-experimentation/get-started/hybrid-experimentation)で使用している場合、`get_visitor_code()` メソッドを呼び出すと、一意の ID(**visitor code**)がアプリケーションファイルの `engine.js`(以前は `kameleoon.js` という名前でした)と SDK の間で共有されます。
##### フラグ設定の取得
コードに機能フラグを実装するには、まず Kameleoon アカウントで機能フラグを作成する必要があります。
特定のユーザーに対する機能フラグのステータスまたはバリエーションを判定するには、[`get_variation()`](#get_variation) または [`feature_active?()`](#feature_active) メソッドを使用して、`feature_key` に基づいて設定を取得します。
`get_variation()` メソッドは、ON/OFF 状態のシンプルな機能フラグと、複数のバリエーションを持つより複雑なフラグの両方を処理します。このメソッドは、機能ルールをチェックし、バリエーションを割り当て、`feature_key` と `visitor_code` に基づいて適切なバリエーションをユーザーに対して返します。
`feature_active?()` メソッドは、複数のバリエーションやターゲティングオプションを持つより複雑な機能フラグではなく、ON または OFF 状態のみを持つシンプルな機能フラグの設定を取得したい場合に使用できます。
機能フラグに関連付けられた変数がある(各バリエーションに紐づく特定の動作など)場合、`get_variation()` を使用すると、[`Variation`](#variation) オブジェクトにもアクセスでき、割り当てられたバリエーションとそれに関連する実験の詳細を提供します。このメソッドは、ユーザーがターゲットされているかどうかをチェックし、訪問者に割り当てられたバリエーションを見つけ、ストレージに保存します。`track=true` の場合、SDK は SDK の [`tracking_interval_millisecond`](#クライアントの設定) に基づいて自動的にトリガーされる次のトラッキングリクエストで、指定された実験への露出イベントを送信します。デフォルトでは、この間隔は 1000 ミリ秒(1 秒)に設定されています。
`get_variation()` メソッドでは、トラッキングを行うかどうかを制御できます。`track=false` の場合、SDK は露出イベントを送信しません。これは、SDK を介してデータをトラッキングしたくない場合や、たとえば Kameleoon エンジンによって管理されるクライアントサイドのトラッキングに依存したい場合に便利です。さらに、`get_variations()` メソッドを使用する際、トラッキングイベントをトリガーせずにすべてのフラグのバリエーションのみが必要な場合に、`track=false` の設定が役立ちます。トラッキングの仕組みについて詳しく知りたい場合は、[こちらの記事](/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()` メソッドは、分析ソリューションに露出イベントを送信するために必要な一意のトラッキングコードを取得します。このメソッドを使用すると、イベントを記録し、希望の分析プラットフォームに送信できます。
### クロスデバイス実験
複数のデバイスからアプリにアクセスする訪問者をサポートするために、Kameleoon はクロスデバイス実験を通じて、訪問者の各デバイス間で以前に収集された訪問者データを同期し、デバイス間で訪問履歴を統合できるようにします。Kameleoon がデバイス間でデータを処理する方法に関するケーススタディと詳細な情報は、[クロスデバイス実験に関する記事](/developer-docs/cross-device-experimentation)で確認できます。
#### デバイス間でのカスタムデータの同期
カスタムマッピングの同期は、デバイス間で訪問者データを整合させるために使用されますが、必ずしも必要ではありません。以下にカスタムマッピングの同期が必要ない 2 つのシナリオを示します。
**デバイス間で同一のユーザー ID**
すべてのデバイスで同じユーザー ID が一貫して使用されている場合、カスタムマッピングの同期なしで同期が自動的に処理されます。複数のデバイス間で収集されたデータを同期したいときに `get_remote_visitor_data()` メソッドを呼び出すだけで十分です。
**一貫した ID を持つマルチサーバーインスタンス**
複数のサーバー(例: 分散サーバーインスタンス)を含む複雑な設定では、サーバー間で同じユーザー ID が利用可能な場合、追加のカスタムマッピング同期なしにサーバー間の同期(`get_remote_visitor_data()` を使用)で十分です。
追加のデータが必要なお客様は、[`get_remote_visitor_data()`](#get_remote_visitor_data) メソッドの説明を参照して詳細なガイダンスを得てください。以下のコードでは、正確なデータ取得のために、2 つのデバイス間で同じ一意の識別子(この場合、`userId` とも呼ばれる `visitor_code`)が一貫して使用されていることを前提としています。
収集したデータをリアルタイムで同期したい場合、カスタムデータのスコープに **Visitor** を選択する必要があります。
```ruby 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.new(VISITOR_SCOPE_CUSTOM_DATA_INDEX, 'your data'))
kameleoon_client.flush(visitor_code)
```
```ruby 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) を呼び出すことで、特定のユーザーの既知のすべてのデータを取得できます。
同じ識別子を持つセッションは、実験で常に同じバリエーションが表示されます。実験結果ページのビジター ビューでは、これらのセッションは単一の訪問者として表示されます。
SDK の構成により、関連付けられたセッションが常に同じ実験のバリエーションを表示することが保証されます。ただし、クロスデバイスのバリエーション割り当てに関するいくつかの制限事項があります。これらの制限は[こちら](/developer-docs/cross-device-experimentation#critical-points-and-practical-insights)で説明されています。
[クロスデバイスの履歴整合の有効化](#クロスデバイス実験)ガイドに従って、Kameleoon プラットフォームでカスタムデータを設定してください。
その後、SDK を通常どおりに使用できます。セッションマージの文脈で役立つメソッドは次のとおりです。
* `get_remote_visitor_data()` に `UniqueIdentifier(true)` を追加 - すべてのリンクされた訪問者のデータを取得します。
* [`track_conversion()`](#track_conversion) または [`flush()`](#flush) に `UniqueIdentifier(true)` データを追加 - 別の訪問者に関連付けられた特定の訪問者のデータをトラッキングします。
識別子として使用するカスタムデータは **Visitor スコープ** に設定する必要があるため、[クロスデバイスのカスタムデータ同期](/developer-docs/cross-device-experimentation)を使用して、各デバイスで [`get_remote_visitor_data()`](#get_remote_visitor_data) メソッドにより識別子を取得する必要があります。
セッションマージのためにカスタムデータを使用する方法の例を以下に示します。
```ruby 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.new(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.new(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 製品や、同じ組織のすべてのユーザーを同じバリエーションに割り当てたいシナリオでは、`accountId` などの識別子を使用できます。チームや会社全体に影響を与える機能を A/B テストする際に、カスタムバケッティングキーは極めて重要です。
カスタムバケッティングキーを実装することで、実験における整合性と精度が向上し、より信頼性の高い結果と、より良いユーザー体験が得られます。
#### 技術的な詳細
機能フラグにカスタムバケッティングキーを設定すると、アプリケーションのデータから特定の識別子を Kameleoon に提供することになります。
```ruby theme={null}
bucketing_key = Kameleoon::CustomData.new(index, 'new_visitor_code')
kameleoon_client.add_data(visitor_code, bucketing_key)
```
* **カスタムキーの提供:** [`add_data()`](#add_data) メソッドを使用して、選択したカスタム識別子を 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)を参照してください。
* **バケッティングロジック:** `add_data()` メソッドを通じてカスタムバケッティングキーが提供されると、ユーザーをバリエーションに割り当てるためのすべてのハッシュ計算では、デフォルトの `visitor_code` の代わりにこの `newVisitorCode`(カスタムキー)が使用されます。`newVisitorCode` を使用することで、バケッティングの決定がカスタム識別子に紐付けられ、その識別子が存在するさまざまなコンテキストで一貫した割り当てが保証されます。
* **データトラッキングと分析:** 重要な点として、`newVisitorCode`(カスタムキー)はバケッティングの判断に使用されますが、**それ以降のすべてのデータ(トラッキングイベントやコンバージョンなど)は、*元の* `visitor_code` で送信および関連付けられます。** この分離により、(アカウントなどの)より高いレベルや、複数のデバイス/セッション間でバケッティングが実行される場合でも、分析が実験のより広いコンテキスト内で個々のユーザージャーニーとインタラクションを正確に反映します。元の訪問者データは、包括的なレポートのためにそのまま保持されます。
#### 技術的要件
カスタムバケッティングキーを効果的に使用するには:
* キーは `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 は、ログレベルによるログ出力の制限の設定をサポートしています。
```ruby theme={null}
require 'kameleoon/logging/kameleoon_logger'
# The `NONE` log level does not allow logging.
Kameleoon::Logging::KameleoonLogger.log_level = Kameleoon::Logging::LogLevel::NONE
# The `ERROR` log level only allows logging issues that may affect the SDK's main behaviour.
Kameleoon::Logging::KameleoonLogger.log_level = Kameleoon::Logging::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.
Kameleoon::Logging::KameleoonLogger.log_level = Kameleoon::Logging::LogLevel::WARNING
# The `INFO` log level allows logging general information on the SDK's internal processes.
# It extends the `WARNING` log level.
Kameleoon::Logging::KameleoonLogger.log_level = Kameleoon::Logging::LogLevel::INFO
# The `DEBUG` level logs additional details about the SDK’s internal processes and extends the `INFO` level
# with more granular. diagnostic output.
# This information is not intended for end-user interpretation but can be sent to our support team
# to assist with internal troubleshooting.
Kameleoon::Logging::KameleoonLogger.log_level = Kameleoon::Logging::LogLevel::DEBUG
```
#### ログのカスタムハンドリング
SDK はデフォルトでログをコンソール出力に書き込みます。この動作は上書き可能です。
ログレベルによるログ出力の制限は、ログ処理ロジックとは別に実行されます。
```ruby theme={null}
require 'logger'
require 'kameleoon/logging/logger'
module Kameleoon
class CustomLogger < Kameleoon::Logging::Logger
def initialize
@internal_logger = Logger.new(STDOUT)
end
def log(level, message)
case level
when Kameleoon::Logging::LogLevel::ERROR
@internal_logger.error(message)
when Kameleoon::Logging::LogLevel::WARNING
@internal_logger.warn(message)
when Kameleoon::Logging::LogLevel::INFO
@internal_logger.info(message)
when Kameleoon::Logging::LogLevel::DEBUG
@internal_logger.debug(message)
end
end
end
end
# 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.
Kameleoon::Logging::KameleoonLogger.log_level = Kameleoon::Logging::LogLevel::DEBUG # Optional, defaults to `Kameleoon::Logging::LogLevel::WARNING`.
Kameleoon::Logging::KameleoonLogger.logger = CustomLogger.new
```
## リファレンス
Ruby SDK の完全なリファレンスドキュメントです。
### 初期化
#### create()
SDK の使用を開始するには、初期化のステップから始めます。SDK とのすべてのやり取りは、Kameleoon::KameleoonClient という名前のオブジェクトを介して行われるため、このオブジェクトを作成する必要があります。
```ruby theme={null}
kameleoon_config = Kameleoon::KameleoonClientConfig.new('client_id', 'client_secret')
kameleoon_client = Kameleoon::KameleoonClientFactory.create('a8st4f59bj', config: kameleoon_config)
kameleoon_client = Kameleoon::KameleoonClientFactory.create('a8st4f59bj', config_path: '/etc/kameleoon/client-ruby.yaml')
```
##### 引数
| 名前 | 型 | 説明 |
| ------------------------- | -------------------------------- | ---------------------------------------------------------------------------------------------------- |
| site\_code | String | これは、SDK で使用している Kameleoon プロジェクトの[一意のキー](/user-manual/faq#how-do-i-find-my-sitecode)です。このフィールドは必須です。 |
| configuration\_file\_path | String | SDK 設定ファイルへのパス。このフィールドはオプションで、デフォルトでは `/etc/kameleoon/client-ruby.yaml` に設定されています。 |
| config | Kameleoon::KameleoonClientConfig | 設定ファイルを使う代わりに渡せる SDK 設定オブジェクト。このフィールドはオプションです。 |
##### スローされる例外
| 型 | 説明 |
| ------------------------------------- | ----------------------------------- |
| Kameleoon::Exception::SiteCodeIsEmpty | 指定された site code が無効な空文字列であることを示す例外。 |
#### wait\_init()
`wait_init` は Kameleoon クライアントの初期化を待機します。このメソッドを使用すると、他の操作に進む前にクライアントが正常に初期化されたかどうかを確認できます。
クライアントが初期化されると、`wait_init` は直ちに戻ります。初期構成の取得が失敗した場合、クライアントはバックグラウンドで再試行を続けるため、`wait_init` はいずれかの取得が成功した時点で戻ります。待機は常にタイムアウトによって制限されるため、無期限にブロックすることはありません。構成が読み込まれる前にタイムアウトが経過した場合、`wait_init` は `false` を返します。
```ruby theme={null}
kameleoon_client = Kameleoon::KameleoonClientFactory.create('a8st4f59bj')
if kameleoon_client.wait_init
# The SDK has been initialized;
end
# Wait up to 5 seconds for the SDK to become ready.
if kameleoon_client.wait_init(5000)
# The SDK has been initialized;
end
```
##### 引数
| 名前 | 型 | 説明 | デフォルト |
| ---------------------------- | --------- | ------------ | ------------------------------------------- |
| `timeout_millisecond` (*任意*) | `Integer` | 最大待機時間(ミリ秒)。 | [`default_timeout_millisecond`](#クライアントの設定) |
##### 戻り値
| 型 | 説明 |
| --------- | ------------------------------------------------------------------------------------------ |
| `Boolean` | Kameleoon クライアントインスタンスが正常に初期化された場合は `true`、それ以外の場合は `false`(たとえば、初期化が完了する前にタイムアウトが経過した場合)。 |
### 機能フラグとバリエーション
#### feature\_active?()
* 📨 *Kameleoon にトラッキングデータを送信します(`track` パラメータに依存)*
以前は `activate_feature` と呼ばれていました - SDK バージョン `3.0.0` 以降削除されました。
このメソッドは、**visitor\_code** と **feature\_key** を必須引数として受け取り、指定された機能がユーザーに対してアクティブになるかどうかを確認します。
そのようなユーザーがこの機能フラグに関連付けられたことがない場合、SDK はランダムにブール値を返します(ユーザーがこの機能を持つべきなら **true**、そうでなければ **false**)。指定された **visitor\_code** のユーザーがこの機能フラグで既に登録されている場合、以前の **FeatureFlag** 値を検出します。
潜在的な例外をキャッチするために、右の例に示すようにコードに適切なエラー処理が設定されていることを確認する必要があります。
`visitor_code` を指定すると、`feature_active?` メソッドは `visitor_code` を一意の訪問者識別子として使用します。これは[クロスデバイス実験](/developer-docs/cross-device-experimentation)で便利です。`visitor_code` を指定し、`is_unique_identifier` パラメータを `true` に設定すると、SDK はフラッシュされたデータを指定された識別子に関連付けられた訪問者にリンクします。
`is_unique_identifier` パラメータは非推奨です。代わりに [`UniqueIdentifier`](#uniqueidentifier) を使用してください。
`is_unique_identifier` は、もともと訪問者に割り当てられた匿名の `visitorCode` にアクセスできないが、セッションマージ機能を使用して匿名訪問者と接続された内部 ID にアクセスできる場合など、他のエッジケースシナリオでも役立ちます。
```ruby theme={null}
visitor_code = kameleoon_client.get_visitor_code(cookies)
feature_key = "new_checkout"
has_new_checkout = false
begin
has_new_checkout = kameleoon_client.feature_active?(visitor_code, feature_key)
# disabling tracking
has_new_checkout = kameleoon_client.feature_active?(visitor_code, feature_key, track: false)
rescue Kameleoon::Exception::FeatureNotFound
# The user will not be counted in the experiment, but should see the reference variation.
has_new_checkout = false
end
if has_new_checkout
# Implement new checkout code here
end
```
`feature_active?()` メソッドは、配信されたバリアントを評価するもので、マスターフラグの状態を評価するものではありません。ルールを除外する場合、メソッドは **その他のすべてに対して配信** のデフォルトの状態を使用します。このデフォルトの状態に対して **Off** を選択した場合、マスター機能フラグが **On** であっても、メソッドは常に `false` を返します。
##### 引数
| 名前 | 型 | 説明 |
| ---------------------------- | --------- | ---------------------------------------------------------- |
| visitor\_code | `String` | ユーザーの一意の識別子。このフィールドは必須です。 |
| feature\_key | `String` | ユーザーに公開したい機能のキー。このフィールドは必須です。 |
| is\_unique\_identifier (非推奨) | `Boolean` | `true` に設定すると、SDK はフラッシュされたデータを指定された識別子に関連付けられた訪問者にリンクします。 |
| track | `Boolean` | 機能評価のトラッキングを有効/無効にするオプションのパラメータ(デフォルトは `true`)。 |
##### 戻り値
| 型 | 説明 |
| --------- | ---------------------------------------- |
| `Boolean` | 指定された **visitor\_code** に対して登録されている機能の値。 |
##### スローされる例外
| 型 | 説明 |
| ---------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| Kameleoon::Exception::FeatureNotFound | リクエストされた feature ID が SDK の内部設定で見つからなかったことを示す例外。これは通常の状況であり、機能フラグが Kameleoon 側でまだ有効化されていないことを意味します(ただし、機能を実装するコードは Web アプリケーション側で既にデプロイされています)。 |
| Kameleoon::Exception::VisitorCodeInvalid | 指定された訪問者コードが無効(空、または 255 文字を超える)であることを示す例外。 |
#### get\_variation()
* 📨 *Kameleoon にトラッキングデータを送信します(`track` パラメータに依存)*
特定の機能フラグについて、指定された訪問者に割り当てられた [`Variation`](#variation) を取得します。
このメソッドは、`visitor_code` と `feature_key` を必須引数として受け取ります。`track` 引数はオプションで、デフォルトは `true` です。
訪問者に割り当てられた `Variation` を返します。訪問者が機能フラグのルールに関連付けられていない場合、メソッドは指定された機能フラグのデフォルト `Variation` を返します。
潜在的な例外を管理するために、コードに適切なエラー処理が実装されていることを確認してください。
デフォルトバリエーションとは、訪問者が機能フラグの事前定義された配信ルールのいずれにも一致しない場合に割り当てられるバリエーションを指します。つまり、特定のルールでターゲティングされていないすべてのユーザーに適用されるフォールバックバリエーションです。これは管理画面の「その他のすべてに対して...」セクションのバリエーションとして表されます。
```ruby theme={null}
feature_key = "new_checkout"
begin
variation = kameleoon_client.get_variation(visitor_code, feature_key)
# disabling tracking
variation = kameleoon_client.get_variation(visitor_code, feature_key, track: false)
rescue Kameleoon::Exception::FeatureNotFound
# The error has occurred; the feature flag isn't found in the current configuration.
rescue Kameleoon::Exception::FeatureEnvironmentDisabled
# The feature flag is disabled for the environment
rescue Kameleoon::Exception::VisitorCodeInvalid
# The visitor code you passed to the method is invalid and can't be accepted by SDK
end
# Fetch a variable value for the assigned variation
title = variation.variables['title'].value
case variation.key
when 'on'
# Main variation key is selected for visitorCode
when 'alternative_variation'
# Alternative variation key
else
# Default variation key
end
```
##### 引数
| 名前 | 型 | 説明 | デフォルト |
| -------------------- | -------- | -------------------------------- | ------ |
| visitor\_code (*必須*) | `String` | 訪問者の一意の識別子。 | |
| feature\_key (*必須*) | `String` | 訪問者に公開したい機能のキー。 | |
| track (*任意*) | `Bool` | 機能評価のトラッキングを有効/無効にするオプションのパラメータ。 | `true` |
##### 戻り値
| 型 | 説明 |
| ----------- | ------------------------------------------------------- |
| `Variation` | 特定の機能フラグに対して指定された訪問者に割り当てられた [`Variation`](#variation)。 |
##### スローされる例外
| 型 | 説明 |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `VisitorCodeInvalid` | 指定された訪問者コードが有効でないことを示す例外。空、または 255 文字を超える可能性があります。 |
| `FeatureNotFound` | リクエストされた feature key が SDK の内部設定で見つからなかったことを示す例外。通常、これは機能フラグが Kameleoon アプリで有効化されていないことを意味します(ただし、機能を実装するコードはアプリケーションで既にデプロイされています)。 |
| `FeatureEnvironmentDisabled` | 機能フラグが訪問者の現在の環境(本番、ステージング、開発など)で無効であることを示す例外。 |
#### get\_variations()
* 📨 *Kameleoon にトラッキングデータを送信します(`track` パラメータに依存)*
すべての機能フラグについて、指定された訪問者に割り当てられた [`Variation`](#variation) オブジェクトのマップを取得します。
このメソッドは利用可能なすべての機能フラグを反復処理し、指定された訪問者に関連付けられた各フラグの割り当てられた `Variation` を返します。`visitor_code` を必須引数として受け取り、`only_active` と `track` はオプションです。
* `only_active` を `true` に設定した場合、`get_variations()` メソッドは、ユーザーが `off` バリエーションにバケッティングされていない機能フラグのバリエーションを返します。
* `track` パラメータは、メソッドがバリエーション割り当てをトラッキングするかどうかを制御します。デフォルトでは `true` に設定されています。`false` に設定すると、トラッキングは無効になります。
返されるマップは、機能フラグのキーをキーとし、対応する `Variation` を値として持ちます。機能フラグにバリエーションが割り当てられていない場合、メソッドはそのフラグのデフォルト `Variation` を返します。
潜在的な例外を管理するために適切なエラー処理を実装する必要があります。
デフォルトバリエーションとは、訪問者が機能フラグの事前定義された配信ルールのいずれにも一致しない場合に割り当てられるバリエーションを指します。つまり、特定のルールでターゲティングされていないすべてのユーザーに適用されるフォールバックバリエーションです。これは管理画面の「その他のすべてに対して...」セクションのバリエーションとして表されます。
```ruby theme={null}
begin
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)
rescue Kameleoon::Exception::VisitorCodeInvalid
# Handle exception
end
```
##### 引数
| 名前 | 型 | 説明 | デフォルト |
| -------------------- | -------- | ----------------------------------------------------------------------------- | ------- |
| visitor\_code (*必須*) | `String` | 訪問者の一意の識別子。 | |
| only\_active (*任意*) | `Bool` | アクティブな機能フラグのバリエーション(`true`)を返すか、すべての機能フラグのバリエーション(`false`)を返すかを示すオプションのパラメータ。 | `false` |
| track (*任意*) | `Bool` | 機能評価のトラッキングを有効/無効にするオプションのパラメータ。 | `true` |
##### 戻り値
| 型 | 説明 |
| ------------------------- | --------------------------------------------------------------------- |
| `Hash` | 対応する機能のキーを使用して機能フラグの割り当てられた [`Variation`](#variation) オブジェクトを格納するマップ。 |
##### スローされる例外
| 型 | 説明 |
| -------------------- | -------------------------------------------------- |
| `VisitorCodeInvalid` | 指定された訪問者コードが有効でないことを示す例外。空、または 255 文字を超える可能性があります。 |
#### set\_forced\_variation()
このメソッドを使用すると、標準の評価プロセスをバイパスして、特定の [`Variation`](#variation) をプログラム的にユーザーに割り当てることができます。これは、通常の評価ロジックが不要、またはスキップしなければならない制御された実験で特に価値があります。デバッグやカスタムテストなどのシナリオでも役立ちます。
**強制** バリエーションが設定されると、Kameleoon のリアルタイム評価ロジックが上書きされます。セグメンテーション、ターゲティング条件、アルゴリズム計算などのプロセスはスキップされます。実験中にセグメンテーションとターゲティング条件を保持するには、代わりに `force_targeting=false` を設定します。
**シミュレート** されたバリエーションは、実行順序で常に優先されます。**シミュレート** バリエーション計算がトリガーされた場合、それが最初に完全に処理され完了します。
強制バリエーションは、評価済みのバリエーションと同じように扱われます。標準の評価済みバリエーションと同様に、アナリティクスでトラッキングされ、ユーザーコンテキストに保存されるため、レポートの一貫性が確保されます。
このメソッドは特定の条件下で例外をスローする可能性があります(例: 無効なパラメータ、ユーザーコンテキスト、または内部の問題)。アプリケーションの安定性と回復力を確保するためには、適切な例外処理が不可欠です。
**強制** バリエーションを **[シミュレート](#get_visitor_code)** バリエーションと区別することが重要です。
* **強制バリエーション**: 個別の実験に固有のものです。
* **シミュレートバリエーション**: 全体的な **機能フラグ** の結果に影響します。
```ruby theme={null}
experiment_id = 9516
begin
# 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', force_targeting: false)
# Resetting the forced variation for the experiment 9516 for the visitor
kameleoon_client.set_forced_variation(visitor_code, experiment_id, nil)
rescue Kameleoon::Exception::KameleoonError => ex
# Handling the exception
end
```
##### 引数
| 名前 | 型 | 説明 | デフォルト | |
| ----------------------- | --------- | --------------------------------------------------------------- | ------------------------------------------------------------------------------------- | - |
| visitor\_code (*必須*) | `String` | 訪問者の一意の識別子。 | | |
| experiment\_id (*必須*) | `Integer` | 評価プロセス中にターゲットされ選択される **Experiment Id**。 | | |
| variation\_key (*必須*) | \`String | NilClass\` | 実験の戻り値として強制されるべき `Variation` に対応する **Variation Key**。値が `nil` の場合、強制バリエーションがリセットされます。 | |
| force\_targeting (*任意*) | `Bool` | 実験のターゲティングを強制してスキップする(`true`)か、標準の評価プロセスとして適用する(`false`)かを示します。 | `true` | |
##### スローされる例外
| 型 | 説明 |
| --------------------------- | ------------------------------------------------------------------------------------------------------------ |
| `VisitorCodeInvalid` | 指定された訪問者コードが有効でないことを示す例外。空、または 255 文字を超える可能性があります。 |
| `FeatureExperimentNotFound` | リクエストされた experiment id が SDK の内部設定で見つからなかったことを示す例外。これは通常正常で、ルールに対応する実験が Kameleoon 側でまだ有効化されていないことを意味します。 |
| `FeatureVariationNotFound` | リクエストされたバリエーションキー (id) が SDK の内部設定で見つからなかったことを示す例外。これは通常正常で、バリエーションに対応する実験が Kameleoon 側でまだ有効化されていないことを意味します。 |
ほとんどの場合、例に示すように基本的なエラーである `KameleoonError` のみを処理する必要があります。ただし、異なる種類のエラーに対応する必要がある場合は、特定の要件に基づいて個別に処理してください。さらに、信頼性を高めるためには、`StandardError` を含めることで一般的な言語エラーを処理できます。
#### evaluate\_audiences()
* 📨 *Kameleoon にトラッキングデータを送信します*
このメソッドは、Audiences Explorer のすべてのセグメントに対して訪問者を評価し、一致する訪問者をトラッキングします。
`evaluate_audiences()` は、**関連するすべての訪問者データが設定または更新された後**、かつ機能バリエーションを取得する、または機能フラグをチェックする**直前**に呼び出す必要があります。このアプローチにより、訪問者が利用可能な最新のデータに対して評価され、すべての基準に基づいた正確なオーディエンス割り当てが可能になります。
このメソッドを呼び出した後、Audiences Explorer でセグメントのパフォーマンスを詳細に分析できます。
```ruby theme={null}
begin
kameleoon_client.evaluate_audiences(visitor_code)
rescue Kameleoon::Exception::KameleoonError => ex
# Handling the exception
end
```
##### 引数
| 名前 | 型 | 説明 |
| -------------------- | -------- | ----------- |
| visitor\_code (*必須*) | `String` | 訪問者の一意の識別子。 |
##### スローされる例外
| 型 | 説明 |
| -------------------- | -------------------------------------------------- |
| `VisitorCodeInvalid` | 指定された訪問者コードが有効でないことを示す例外。空、または 255 文字を超える可能性があります。 |
ほとんどの場合、例に示すように基本的なエラーである `KameleoonError` のみを処理する必要があります。ただし、異なる種類のエラーに対応する必要がある場合は、特定の要件に基づいて個別に処理してください。さらに、信頼性を高めるためには、`StandardError` を含めることで一般的な言語エラーを処理できます。
#### get\_data\_file()
すべての機能フラグを評価するには、[`get_variations()`](#get_variations) を使用します。このメソッドは、`DataFile` を呼び出して [`get_variation()`](#get_variation) でフラグを反復処理するよりも効率的です。
現在の SDK 設定を [`DataFile`](#datafile) オブジェクトとして返します。
```ruby theme={null}
begin
datafile = kameleoon_client.get_data_file
rescue StandardError => e
# Recommended (but optional) safeguard for unexpected exceptions from third-party libraries
end
```
##### 戻り値
| 型 | 説明 |
| ---------- | --------------------------------- |
| `DataFile` | SDK 設定を含む [`DataFile`](#datafile) |
### 訪問者データ
#### get\_visitor\_code()
以前は `obtain_visitor_code` と呼ばれていました - SDK バージョン `3.0.0` 以降削除されました。
`get_visitor_code` ヘルパーメソッドを呼び出して、現在の訪問者の Kameleoon **visitor\_code** を取得します。このメソッドは、ユーザー識別の精度を保証する必要があるフロントエンドとバックエンドの混在環境で Kameleoon を使用する場合に重要です。実装ロジックは以下のとおりです。
1. 現在の HTTP リクエストに関連付けられた **kameleoonVisitorCode** クッキーまたはクエリパラメータをチェックします。見つかった場合、これを訪問者識別子として使用します。
2. クッキーまたはパラメータが見つからない場合、**default\_visitor\_code** 引数をチェックします。見つかった場合、これを識別子として使用します。`default_visitor_code_` により、顧客が独自の識別子を訪問者コードとして使用したい場合に使用でき、マッチングテーブルでの追加のルックアップなしに、Kameleoon の訪問者と顧客自身のユーザーをマッチングするという追加のメリットがあります。
3. クッキー、パラメータ、または引数が見つからない場合、一意の識別子をランダムに生成します。
すべての場合において、サーバーサイド(HTTP ヘッダー経由)の **kameleoonVisitorCode** クッキーがその値で設定されます。後の訪問では、設定した識別子がメソッドが返す値となります。
詳細については、[こちらの記事](/developer-docs/feature-experimentation/get-started/hybrid-experimentation/)を参照してください。
独自の `visitor_code` を提供する場合、その一意性を保証する必要があります(SDK は確認できません)。また、`visitor_code` の長さは **255** 文字に制限されていることに注意してください。それを超える文字は例外をスローします。
`get_visitor_code()` メソッドを使用すると、訪問者に対して **シミュレート** バリエーションを設定できます。クッキー(**リクエスト** または **ドキュメント** から)に `kameleoonSimulationFFData` というキーが含まれている場合、標準の評価プロセスはバイパスされます。代わりに、メソッドは提供されたデータに基づいて [`Variation`](#variation) を直接返します。
シミュレーションは 2 つの方法で適用できます。
* **自動(推奨):** Kameleoon Web Experimentation または SDK を[ハイブリッドモード](/developer-docs/feature-experimentation/get-started/hybrid-experimentation#linking-feature-experiments-with-front-end-tracking-code)で使用している場合、[シミュレーションパネル](/user-manual/experimentation/feature-experimentation/using-the-rollout-planner/validation-and-rollback/using-simulation-mode)を使用してバリアントの表示をシミュレートすると、クッキーは自動的に作成されます。
* **手動:** `kameleoonSimulationFFData` クッキーを手動で設定します。
**シミュレート** バリエーションを **[強制](#set_forced_variation)** バリエーションと区別することが重要です。
* **シミュレートバリエーション**: 全体的な **機能フラグ** の結果に影響します。
* **強制バリエーション**: 個別の実験に固有のものです。
⚙️ **手動セットアップ**
`kameleoonSimulationFFData` クッキーは次の形式に従っていることを確認してください。
* `kameleoonSimulationFFData={"featureKey":{"expId":10,"varId":20}}`: 指定された `featureKey` に対して、実験 `expId` のバリエーション `varId` をシミュレートします。
* `kameleoonSimulationFFData={"featureKey":{"expId":0}}`: 指定された `featureKey` に対するデフォルトバリエーション(**Then, for everyone else in Production, serve** セクションで定義)をシミュレートします。
⚠️ 適切な機能を確保するために、クッキー値は [`encodeURIComponent`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/encodeURIComponent) のようなメソッドを使用して URI コンポーネントとしてエンコードする必要があります。
```ruby theme={null}
visitor_code = kameleoon_client.get_visitor_code(cookies)
visitor_code = kameleoon_client.get_visitor_code(cookies, default_visitor_code)
```
##### 引数
| 名前 | 型 | 説明 |
| ---------------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------- |
| cookies | Hash | 現在の HTTP リクエストのクッキーは、Hash オブジェクト(`{:cookie_name => cookie_value}`)として渡す必要があります。Rails を使用している場合は、**cookies** 変数を渡せます。このフィールドは必須です。 |
| default\_visitor\_code | String | このパラメータは、リクエストに既存の **kameleoonVisitorCode** クッキーが見つからない場合に **visitor\_code** として使用されます。このフィールドはオプションで、デフォルトではランダムな **visitor\_code** が生成されます。 |
##### 戻り値
| 型 | 説明 |
| ------ | -------------------------------------------------------- |
| String | この特定のユーザーに関連付けられ、ほとんどの SDK メソッドで使用される **visitor\_code**。 |
#### add\_data()
`add_data()` メソッドは、他のメソッドが現在の訪問者をターゲットするかどうかを判断するために使用できるよう、[ターゲティングデータ](#データ型)をストレージに追加します。
`add_data()` メソッドは値を返さず、独立して Kameleoon バックエンドサーバーと通信することもありません。代わりに、宣言されたすべてのデータは、後で [`flush()`](#flush) メソッドを使用して送信するために保存されます。このアプローチは、データが通常 `flush()` でトリガーされる単一のサーバー呼び出しにまとめられるため、サーバー呼び出しの数を削減します。
[`track_conversion()`](#track_conversion) メソッドも、`flush()` と同様に、以前に関連付けられたデータを送信します。[`get_variation()`](#get_variation) および [`get_variations()`](#get_variations) メソッドでも、実験ルールがトリガーされた場合に同じことが当てはまります。
ほとんどのデータ型については、各訪問者は関連付けられたデータのインスタンスを 1 つしか持てません。ただし、[`CustomData`](#customdata) は例外です。訪問者はインデックスごとに関連付けられた `CustomData` のインスタンスを 1 つ持つことができます。
```ruby theme={null}
require "kameleoon"
require "kameleoon/data"
# Add a single data item (tracked by default)
kameleoon_client.add_data(visitor_code, Kameleoon::Browser.new(Kameleoon::BrowserType::CHROME))
# Add multiple data items (tracked by default)
kameleoon_client.add_data(
visitor_code,
Kameleoon::PageView.new("https://url.com", "title", [3]),
Kameleoon::UserAgent("UserAgent")
)
# Add multiple data items stored locally for targeting only (not sent to the Kameleoon Data API)
kameleoon_client.add_data(
visitor_code,
Kameleoon::Data::PageView.new("https://url.com", "title", [3]),
Kameleoon::Data::UserAgent.new("UserAgent"),
track: false
)
```
##### 引数
| 名前 | 型 | 説明 | デフォルト値 |
| -------------------- | -------- | ------------------------------------------------------------------------------------------------------------ | ------ |
| visitor\_code (*必須*) | `String` | 訪問者の一意の識別子。 | |
| data (*必須*) | `*Data` | Kameleoon データ型のコレクション。 | |
| track (*任意*) | `Bool` | 追加されたデータがトラッキング対象であるかどうかを指定します。`false` に設定すると、データはローカルに保存され、ターゲティング評価にのみ使用されます。Kameleoon Data API には送信されません。 | `true` |
##### 例外
| 型 | 説明 |
| -------------------- | -------------------------------------------------- |
| `VisitorCodeInvalid` | 指定された訪問者コードが有効でないことを示す例外。空、または 255 文字を超える可能性があります。 |
#### flush()
* 📨 *Kameleoon にトラッキングデータを送信します*
`flush()` は、訪問者に関連付けられた Kameleoon データと、以前に `add_data` メソッドを使用して追加したすべてのデータのうち、[これらのメソッド](/developer-docs/feature-experimentation/technical-reference/faq-global#when-does-the-sdk-send-a-tracking-request-for-analytics)のいずれかを呼び出した際にまだ送信されていないデータを取り、トラッキングリクエストを送信します。`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` は、もともと訪問者に割り当てられた匿名の `visitorCode` にアクセスできないが、セッションマージ機能を使用して匿名訪問者と接続された内部 ID にアクセスできる場合など、他のエッジケースシナリオでも役立ちます。
```ruby theme={null}
require "kameleoon"
require "kameleoon/data"
visitor_code = kameleoon_client.get_visitor_code(cookies)
kameleoon_client.add_data(visitor_code, Kameleoon::Browser.new(Kameleoon::BrowserType::CHROME))
kameleoon_client.add_data(
visitor_code,
Kameleoon::PageView.new("https://url.com", "title", [3]),
Kameleoon::Interest.new(0)
)
kameleoon_client.add_data(visitor_code, Kameleoon::Conversion.new(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(Kameleoon::UniqueIdentifier.new(true))
kameleoon_client.flush(visitor_code)
```
##### 引数
| 名前 | 型 | 説明 |
| ---------------------- | ------- | ---------------------------------------------------------------------------------- |
| visitor\_code | String | ユーザーの一意の識別子。このフィールドは必須です。 |
| is\_unique\_identifier | Boolean | `true` の場合、SDK はフラッシュされたデータを指定された識別子に関連付けられた訪問者にリンクします。 |
| instant | Boolean | データを即座に送信するか(`true`)、スケジュールされたトラッキング間隔に従って送信するか(`false`)を示すブールフラグ。このフィールドはオプションです。 |
#### get\_remote\_data()
以前は `retrieve_data_from_remote_source` と呼ばれていました - SDK バージョン `3.0.0` 以降削除されました。
`get_remote_data()` メソッドを使用すると、リモート Kameleoon サーバーに保存されている指定された **siteCode**(`Kameleoon::KameleoonClientFactory.create()` で指定)について、引数として渡された **key** に基づいてデータを取得できます。通常、データは Data API を使用してリモートサーバーに保存されます。このメソッドは、この目的のために高度にスケーラブルなサーバーが利用可能であることと相まって、訪問者/ユーザーごとに取得できる大量のデータを保存する便利な方法を提供します。
```ruby theme={null}
kameleoon_client.get_remote_data('test') # default timeout
kameleoon_client.get_remote_data('test', 1000) # 1000 milliseconds timeout
begin
kameleoon_client.get_remote_data('test')
rescue => e
#catch error
end
```
##### 引数
| 名前 | 型 | 説明 |
| ------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| key | String | 取得しようとしているデータに関連付けられたキー。このフィールドは必須です。 |
| timeout | Integer | タイムアウト(ミリ秒単位)。このパラメータは、結果を待つためにメソッドがブロックできる最大時間を指定します。このフィールドはオプションで、指定されていない場合は、設定ファイルからの `default_timeout` 値、またはファイルで指定されていない場合は 2000 ミリ秒を使用します。 |
##### 戻り値
| 型 | 説明 |
| ---- | ------------------------------------------ |
| Hash | 特定の **key** に対するデータ取得に関連付けられた Hash オブジェクト。 |
##### スローされる例外
| 型 | 説明 |
| ----- | ------------------------------------------------------------ |
| Error | リクエストがタイムアウトしたか、取得したデータが `JSON.parse()` メソッドで解析できないことを示すエラー。 |
#### get\_remote\_visitor\_data()
`get_remote_visitor_data()` は、Kameleoon Data API から `visitor_code` の Kameleoon 訪問データを取得する非同期メソッドです。このメソッドは、ターゲティングの判断を行う際に他のメソッドが使用できるようにデータを保存します。
このメソッドを使用して取得したデータは、次のような場合に重要な役割を果たします。
* 他のデバイスから収集したデータを使用する。
* 過去の訪問中に訪問したページなど、ユーザーの履歴にアクセスする。
* データレイヤー変数やフロントエンドでのみ変換するゴールなど、クライアントサイドからのみアクセス可能なデータを使用する。
可能なユースケースをより理解するために、[こちらの記事](/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` は、もともと訪問者に割り当てられた匿名の `visitorCode` にアクセスできないが、セッションマージ機能を使用して匿名訪問者と接続された内部 ID にアクセスできる場合など、他のエッジケースシナリオでも役立ちます。
```ruby theme={null}
visitor_code = 'visitorCode'
# Visitor data will be fetched and automatically added for `visitor_code`
data_array = kameleoon_client.get_remote_visitor_data(visitor_code) # default timeout
data_array = kameleoon_client.get_remote_visitor_data(visitor_code, 1000) # 1 second timeout
# If you only want to fetch data and add it yourself manually, set `add_data` to `false`
data_array = kameleoon_client.get_remote_visitor_data(visitor_code, add_data: false) # default timeout
data_array = kameleoon_client.get_remote_visitor_data(visitor_code, 1000, add_data: false) # 1 second timeout
# If you want to fetch custom list of data types
filter = RemoteVisitorDataFilter(25, customData: false, conversions: true, experiments: true)
data_array = kameleoon_client.get_remote_visitor_data(visitor_code, filter: filter)
# If you want to the SDK to link the extracted data with the visitor associated with the specified identifier
kameleoon_client.add_data(Kameleoon::UniqueIdentifier.new(true))
data_array = kameleoon_client.get_remote_visitor_data(visitor_code)
```
##### 引数
| 名前 | 型 | 説明 |
| ---------------------------- | ------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| visitor\_code | String | 割り当てられたデータを取得したい訪問者コード。このフィールドは必須です。 |
| timeout | Integer | タイムアウト(ミリ秒単位)。このパラメータは、結果を待つためにメソッドがブロックできる最大時間を指定します。このフィールドはオプションで、指定されていない場合は、設定ファイルからの `default_timeout` 値、またはファイルで指定されていない場合は 2000 ミリ秒を使用します。 |
| add\_data | Boolean | メソッドが取得したデータを訪問者に対して自動的に追加するかどうかを示すブール値。指定されていない場合、デフォルト値は **true** です。このフィールドはオプションです。 |
| filter | `Kameleoon::Types::RemoteVisitorDataFilter` | 訪問から取得するデータを指定するフィルター。デフォルトでは、現在および直近の前回訪問から `CustomData` のみが取得されます(`RemoteVisitorDataFilter.new(previousVisitAmount: 1, currentVisit: true, customData: true)` または `RemoteVisitorDataFilter.new`)。その他のフィルターパラメータは `false` に設定されます。このフィールドはオプションです。 |
| is\_unique\_identifier (非推奨) | Boolean | visitorCode が一意の識別子であるかどうかを指定するためのオプションパラメータ。指定されていない場合、デフォルト値は `false` です。このフィールドはオプションです。 |
##### 戻り値
| 型 | 説明 |
| ----- | ----------------------- |
| Array | 指定された訪問者に割り当てられたデータの配列。 |
##### get\_remote\_visitor\_data() でのパラメータの使用
`get_remote_visitor_data()` メソッドは、訪問者データを取得する際にさまざまなパラメータを定義することで柔軟性を提供します。ゴール、実験、バリエーションに基づいてターゲティングする場合でも、すべてのデータ型に同じアプローチが適用されます。
たとえば、「注文取引」というゴールを完了した訪問者のデータを取得したいとします。`get_remote_visitor_data()` メソッド内でパラメータを指定することで、ターゲティングを絞り込めます。たとえば、過去 5 回の訪問でこのゴールを変換したユーザーのみをターゲットにしたい場合、`previous_visit_amount` パラメータを 5 に設定し、`conversions` を true に設定できます。
この例で示される柔軟性はゴールデータに限定されません。`get_remote_visitor_data()` メソッド内のパラメータを使用して、さまざまな訪問者の行動に関するデータを取得できます。
利用可能な `Kameleoon::Types::RemoteVisitorDataFilter` のオプションのリストは以下のとおりです。
| 名前 | 型 | 説明 | デフォルト |
| ------------------------------ | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| previous\_visit\_amount (*任意*) | `Integer` | データを取得する過去の訪問数。`1` から `25` の間の数値 | `1` |
| current\_visit (*任意*) | `Boolean` | true の場合、現在の訪問データが取得されます | `true` |
| custom\_data (*任意*) | `Boolean` | true の場合、カスタムデータが取得されます。 | `true` |
| page\_views (*任意*) | `Boolean` | true の場合、ページデータが取得されます。 | `false` |
| geolocation (*任意*) | `Boolean` | true の場合、ジオロケーションデータが取得されます。 | `false` |
| device (*任意*) | `Boolean` | true の場合、デバイスデータが取得されます。 | `false` |
| browser (*任意*) | `Boolean` | true の場合、ブラウザデータが取得されます。 | `false` |
| operating\_system (*任意*) | `Boolean` | true の場合、オペレーティングシステムのデータが取得されます。 | `false` |
| conversions (*任意*) | `Boolean` | true の場合、コンバージョンデータが取得されます。 | `false` |
| experiments (*任意*) | `Boolean` | true の場合、実験データが取得されます。 | `false` |
| kcs (*任意*) | `Boolean` | true の場合、Kameleoon Conversion Score (KCS) が取得されます。[AI 予測ターゲティングアドオン](/user-manual/ai-predictive-targeting/target-users-based-on-likelihood-to-convert)が必要です | `false` |
| visitor\_code (*任意*) | `Boolean` | true の場合、Kameleoon は直近の訪問から `visitorCode` を取得し、現在の訪問に使用します。これは、訪問者がその `visitorCode` で識別され、[クロスデバイス実験](/developer-docs/cross-device-experimentation)で訪問全体にわたって常に同じバリエーションを受け取ることを保証したい場合に必要です。 | `true` |
| personalization (*任意*) | `Boolean` | true の場合、パーソナライゼーションデータが取得されます。これはパーソナライゼーション条件に必要です。 | `false` |
| cbs (*任意*) | `Boolean` | 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` オブジェクトを返し、データが訪問者に追加され、ターゲティングの目的で使用可能であることを確認します。
```ruby theme={null}
begin
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, 1000) # 1 second timeout
warehouse_audience_data = kameleoon_client.get_visitor_warehouse_audience(visitor_code, custom_data_index, warehouse_key: warehouse_key) # default timeout
warehouse_audience_data = kameleoon_client.get_visitor_warehouse_audience(visitor_code, custom_data_index, 1000, warehouse_key: warehouse_key) # 1 second timeout
# Your custom code
rescue => e
# Handle exception
end
```
##### 引数
| 名前 | 型 | 説明 |
| ------------------- | ------- | -------------------------------------------------------------------------------------- |
| visitor\_code | String | 一意の訪問者識別文字列。長さは 255 文字を超えることはできません。 |
| custom\_data\_index | Integer | BigQuery Audiences のターゲットに使用したいカスタムデータのインデックスを表す整数。 |
| warehouse\_key | String | ウェアハウスデータを識別するための一意のキー(通常は内部ユーザー ID)。このフィールドはオプションです。 |
| timeout | Integer | タイムアウト(ミリ秒単位)。このパラメータは、結果を待つ最大時間を指定します。このフィールドはオプションです。指定されていない場合、デフォルト値は 10000 ミリ秒です。 |
##### 戻り値
| 型 | 説明 |
| ----------------------- | ----------------------------------------- |
| `Kameleoon::CustomData` | データが訪問者に追加されたことを確認する `CustomData` インスタンス。 |
##### スローされる例外
| 型 | 説明 |
| ---------------------------------------- | ------------------------------------------- |
| Kameleoon::Exception::VisitorCodeInvalid | 指定された訪問者コードが無効(空、または 255 文字を超える)であることを示す例外。 |
| StandardError | リクエストがタイムアウトしたか、その他の理由で失敗したことを示す例外。 |
#### set\_legal\_consent()
このメソッドを使用して、訪問者が個人データの使用について法的同意を与えたかどうかを指定する必要があります。`consent` パラメータを `false` に設定すると、トラッキングリクエストに含められるデータの種類が制限されます。このメソッドは、訪問者データを責任を持って管理しながら、法的要件や規制要件を遵守するのに役立ちます。個人データの詳細については、[同意管理ポリシー](/user-manual/project-management/consent-management-policy)を参照してください。
```ruby theme={null}
visitor_code = kameleoon_client.get_visitor_code(cookies)
kameleoon_client.set_legal_consent(visitor_code, true, cookies)
```
##### 引数
| 名前 | 型 | 説明 |
| ------------- | ------ | ---------------------------------------------------------------------------------------------------- |
| visitor\_code | String | ユーザーの一意の識別子。このフィールドは必須です。 |
| consent | Bool | 法的同意ステータスを表すブール値。`true` は訪問者が法的同意を与えたことを示し、`false` は訪問者が法的同意を一度も提供していない、または撤回したことを示します。このフィールドは必須です。 |
| cookies | Hash | クッキーの値が法的同意ステータスに基づいて調整される HTTP レスポンス。このフィールドはオプションです。 |
##### スローされる例外
| 型 | 説明 |
| ---------------------------------------- | -------------------------------------------------- |
| Kameleoon::Exception::VisitorCodeInvalid | 指定された訪問者コードが無効であることを示す例外。空、または 255 文字を超える可能性があります。 |
##### 同意取り消し時の動作
`consent=false` で `set_legal_consent()` を呼び出すと、SDK は `kameleoonVisitorCode` クッキーを削除しません。代わりに、クッキーの有効期限の延長を停止し、自然に期限切れになるまでクッキーが保持されることを許可します。
コンプライアンス要件によりオプトアウト時にクッキーファイルを即座に削除する必要がある場合は、フレームワークのネイティブクッキー管理メソッドを使用して手動で削除する必要があります。SDK は自動的にファイルを削除しません。
### ゴールとサードパーティ分析
#### track\_conversion()
* 📨 *Kameleoon にトラッキングデータを送信します*
このメソッドを使用して、特定の[ゴール](/user-manual//assets/goals/create-a-goal)とユーザーのコンバージョンをトラッキングします。このメソッドは `visitor_code` と `goal_id` を必要とします。さらに、このメソッドはオプションの `revenue`、`negative`、`metadata` 引数も受け入れます。`visitor_code` は通常、実験をトリガーする際に使用したものと同じです。
`track_conversion()` メソッドは値を返しません。このメソッドはサーバー呼び出しが非同期で実行されるため、非ブロッキングです。
`isUniqueIdentifier` パラメータは非推奨です。代わりに [`UniqueIdentifier`](#uniqueidentifier) を使用してください。
`isUniqueIdentifier` は、もともと訪問者に割り当てられた匿名の `visitor_code` にアクセスできないが、セッションマージ機能を使用して匿名訪問者と接続された内部 ID にアクセスできる場合など、他のエッジケースシナリオでも役立ちます。
```ruby theme={null}
require "kameleoon"
require "kameleoon/data/page_view"
require "kameleoon/data/browser"
require "kameleoon/data/conversion"
visitor_code = kameleoon_client.get_visitor_code(cookies)
goal_id = 83023
kameleoon_client.add_data(visitor_code, Kameleoon::Conversion.new(32, 10, false))
kameleoon_client.track_conversion(visitor_code, goal_id)
# Add metadata
cd = Kameleoon::CustomData.new(1, "metadata");
kameleoon_client.track_conversion(visitorCode, goalId, metadata: [cd])
```
##### 引数
| 名前 | 型 | 説明 | デフォルト |
| -------------------------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| visitor\_code (*必須*) | `String` | 訪問者の一意の識別子。 | |
| goal\_id (*必須*) | `Integer` | ゴールの ID。 | |
| revenue (*任意*) | `Float` | コンバージョンの収益。 | `0` |
| negative (*任意*) | `Bool` | 収益がプラスかマイナスかを定義します。 | `false` |
| metadata (*任意*) | `Array` | Kameleoon アプリでゴールのメタデータとして定義されたカスタムデータに対して特定の値を設定できます。例: `[CustomData{id: 5, value: "Payment Type"}, CustomData{id: 6, value: "Delivery Method"}]`。この例では、`5` と `9` はカスタムデータのインデックスです(5 = "Payment Type"、9 = "Delivery Method")。 | `nil` |
| isUniqueIdentifier *(非推奨)* | `Bool` | visitor\_code が一意の識別子であるかどうかを指定するためのオプションのパラメータ。 | `false` |
metadata の値には、[生データのエクスポート](/user-manual/experiment-analytics/analyze-results/results-page/results-page-actions#Export)および[結果ページ](/user-manual/experiment-analytics/analyze-results/data-and-metrics/goal-metadata)を通じてアクセスできます。
`metadata` パラメータが指定されている場合、Kameleoon は、[`add_data()`](#add_data) メソッドを使用して以前に収集したものではなく、現在のコンバージョンにこれらの指定された値を使用します。パラメータが省略された場合、Kameleoon はコンバージョン前および同じ訪問内のこれらの [`CustomData`](#customdata) の最後にトラッキングされた値を使用します。
Kameleoon は、`track_conversion()` メソッドに明示的にパラメータとして渡されたメタデータ値のみを考慮します。
以下の例では、Kameleoon は明示的にパラメータとして提供されたカスタムデータ値(ここでは値 'Amex Credit Card' を持つインデックス 5)のみとコンバージョンを関連付けます。
```ruby theme={null}
kameleoon_client.add_data(visitor_code, Kameleoon::CustomData.new(5, "Credit Card"), Kameleoon::CustomData.new(9, "Express Delivery"))
kameleoon_client.track_conversion(visitor_code, 10, metadata: [Kameleoon::CustomData.new(5, "Amex Credit Card")])
```
##### 例外
| 型 | 説明 |
| -------------------- | -------------------------------------------------- |
| `VisitorCodeInvalid` | 指定された訪問者コードが有効でないことを示す例外。空、または 255 文字を超える可能性があります。 |
#### get\_engine\_tracking\_code()
Kameleoon は、Mixpanel、Google Analytics 4、Segment を含むいくつかの分析ソリューションと統合されています。サーバーサイドの実験を正しくトラッキングするには、訪問者が実験をトリガーした後に `get_engine_tracking_code()` メソッドを呼び出します。SDK は、訪問者が過去 5 秒間にトリガーした実験に対する JavaScript キューコマンドを返します。このコードをページに挿入すると、Engine.js がコマンドを処理し、アクティブな分析統合を通じて露出イベントを送信します。
このメソッドの実装に関する詳細については、[ハイブリッド実験](/developer-docs/feature-experimentation/get-started/hybrid-experimentation)を参照してください。
```ruby theme={null}
engine_tracking_code = kameleoon_client.get_engine_tracking_code(visitor_code)
```
* この機能を使用するには、Ruby SDK と Kameleoon の [Engine.js](/developer-docs/web-experimentation/implementation-and-deployment/standard-implementation) の両方を実装します。このフローでは Engine.js はトラッキングにのみ使用されるため、非同期タグを `` の終了タグ直前にインストールできます。
* Kameleoon でのみ実験をトラッキングしたく、サードパーティの分析ツールに露出イベントを送信する必要がない場合は、[JavaScript / TypeScript SDK](/developer-docs/sdks/web-sdks/js-sdk) を使用してください。このオプションは[サーバーレスエッジコンピュートプラットフォーム](/developer-docs/feature-experimentation/implementation-and-deployment/serverless-edge-compute-starter-kits)に適しています。JavaScript / TypeScript SDK は、[`getVisitorCode`](/developer-docs/sdks/web-sdks/js-sdk#getvisitorcode) を呼び出すと、対応する実験割り当てを `window.kameleoonQueue` に追加する限り、バリエーションを自動的にトラッキングします。
* 返されたトラッキングコードは、HTML の `