> ## 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. # Elixir SDK > Kameleoon Elixir SDK を統合して、Elixir サービスや Web バックエンドで実験を実行し、フィーチャーフラグを有効化します。 Kameleoon Elixir SDK を使用すると、Elixir サービスや Web バックエンドで実験を実行し、フィーチャーフラグを有効化できます。 **はじめに**: 開始方法については、[開発者ガイド](#開発者ガイド)をご覧ください。 **バージョン**: Elixir SDK の最新バージョン: 0.8.6 [変更履歴](https://docs.kameleoon.com/developer-docs/sdks/web-sdks/elixir-sdk)。 **SDK メソッド**: Elixir SDK の完全なリファレンスドキュメントについては、[リファレンス](#リファレンス)セクションを参照してください。 ## 開発者ガイド このガイドは、Elixir SDK を迅速に統合し、Elixir アプリケーションでフィーチャーフラグの評価を開始するのに役立つように設計されています。 ### はじめに #### Elixir クライアントのインストール `mix.exs` ファイルに依存関係として SDK を追加します: ```elixir title="mix.exs" theme={null} def deps do [ {:kameleoon_client, "~> 0.8.6"} ] end ``` #### 追加設定 認証情報を提供し、SDK の動作をカスタマイズするための `client-elixir.conf` 設定ファイルを作成します。 このファイルをデフォルトパスである `/etc/kameleoon/client-elixir.conf` に保存することをお勧めします。設定オプションを渡さない場合、`Kameleoon.ClientFactory.create` はこのパスを自動的に使用します。ファイルを別の場所に保存する場合は、クライアントを作成するときに `config_path:` オプションでパスを渡してください。 Elixir SDK は、`Kameleoon.ClientFactory.create` が使用する設定ファイルか、`config:` オプションで `%Kameleoon.ClientConfig\{\}` 構造体を渡すかのいずれかで設定できます。 次の表は、設定できる利用可能なプロパティを示しています: | キー (コード / 設定ファイル) | 説明 | デフォルト値 | | --------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | ------------ | | `client_id` / `clientId` (*必須*) | Kameleoon サービスへの認証に必要です。`client_id` を確認するには、[API 認証情報](/user-manual/account-and-team-management/users-and-teams/api-credentials)のドキュメントを参照してください。 | | | `client_secret` / `clientSecret` (*必須*) | Kameleoon サービスへの認証に必要です。`client_secret` を確認するには、[API 認証情報](/user-manual/account-and-team-management/users-and-teams/api-credentials)のドキュメントを参照してください。 | | | `session_duration_minutes` / `sessionDurationMinutes` (*オプション*) | SDK が訪問者とその関連データをメモリに保持する時間間隔(分単位)。 | `30` 分 | | `refresh_interval_minutes` / `refreshIntervalMinutes` (*オプション*) | アクティブな実験とフィーチャーフラグの設定を更新するために使用される間隔(分単位)。 | `60` 分 | | `default_timeout_millis` / `defaultTimeoutMillis` (*オプション*) | SDK ネットワーク要求のデフォルトタイムアウト(ミリ秒単位)。 | `10000` ミリ秒 | | `tracking_interval_millis` / `trackingIntervalMillis` (*オプション*) | トラッキング要求をバッチ処理するために使用される間隔(ミリ秒単位)。値は `[1000, 5000]` の範囲にクランプされます。 | `1000` ミリ秒 | | `environment` / `environment` (*オプション*) | フィーチャーフラグ設定を使用する環境。値は `production`、`staging`、`development` のいずれかにできます。 | `production` | | `top_level_domain` / `topLevelDomain` (*オプション*) | あなたの Web サイトの現在のトップレベルドメイン。プロトコルやサブドメインなしの `example.com` 形式を使用してください。 | `nil` | | `proxy_host` / `proxyHost` (*オプション*) | 送信される SDK 呼び出しのプロキシホスト。サポートされている形式: `https://my.prox`、`https://my.prox:4545`、`socks5://192.168.1.1:9000`。 | `nil` | | `network_domain` / `networkDomain` (*オプション*) | SDK が送信リクエスト用に使用するカスタムドメイン(通常はプロキシ用)。有効なドメイン (例: example.com または sub.example.com) である必要があります。無効な形式の場合は、Kameleoon のデフォルト値が使用されます。 | `nil` | #### Kameleoon クライアントの初期化 SDK をインストールし、認証情報を設定した後、`Kameleoon.ClientFactory` を使用して `%Kameleoon.Client\{\}` を作成します。 ```elixir theme={null} alias Kameleoon.Client alias Kameleoon.ClientFactory site_code = "a8st4f59bj" {:ok, client} = ClientFactory.create(site_code, config_path: "/etc/kameleoon/client-elixir.conf") :ok = Client.initialize(client) ``` ```elixir theme={null} alias Kameleoon.Client alias Kameleoon.ClientConfig alias Kameleoon.ClientFactory site_code = "a8st4f59bj" config = %ClientConfig{ client_id: "", client_secret: "", refresh_interval_minutes: 60, session_duration_minutes: 30, default_timeout_millis: 10_000, tracking_interval_millis: 1_000, environment: "development", top_level_domain: ".example.com", proxy_host: "http://192.168.0.25:8080", network_domain: "example.com" } {:ok, client} = ClientFactory.create(site_code, config: config) :ok = Client.initialize(client) ``` `%Kameleoon.Client\{\}` は、フィーチャーフラグの評価、訪問者データの追加、およびトラッキング要求の送信に使用される主要なオブジェクトです。 * `%Kameleoon.Client\{\}` は、アプリケーションと Kameleoon プラットフォーム間のブリッジとして機能するため、シングルトンオブジェクトとして使用することをお勧めします。実験を効率的に実行するために必要なすべてのメソッドとプロパティを公開しています。 * Elixir SDK はネイティブの Core を介して初期化されます。本番コードでフィーチャー評価に依存する前に、[`initialize()`](#initialize) を呼び出す必要があります。 #### フィーチャーフラグの有効化 ##### ユーザーへの一意の ID の割り当て ユーザーに一意の ID を割り当てるには、[`Client.get_visitor_code`](#get_visitor_code) メソッドを使用できます。**訪問者コード**が存在しない場合(リクエストヘッダーの Cookie から)、このメソッドはランダムな一意の ID を生成するか、生成した `default_visitor_code` を使用します。その後、ID はレスポンスヘッダーの Cookie に設定されます。 Kameleoon を[ハイブリッドモード](/developer-docs/feature-experimentation/get-started/hybrid-experimentation)で使用している場合、`Client.get_visitor_code` メソッドを呼び出すと、一意の ID(**訪問者コード**)がアプリケーションファイル `engine.js`(以前の名前は `kameleoon.js`)と SDK の間で共有されることが保証されます。 ##### フラグ設定の取得 コードにフィーチャーフラグを実装するには、まず Kameleoon アカウントでフィーチャーフラグを作成する必要があります。 特定のユーザーに対するフィーチャーフラグのステータスまたはバリエーションを決定するには、[`Client.get_variation`](#get_variation) または [`Client.is_feature_active?`](#is_feature_active) メソッドを使用して `feature_key` に基づいて設定を取得する必要があります。 `Client.get_variation` メソッドは、ON/OFF 状態のシンプルなフィーチャーフラグと、複数のバリエーションを持つより複雑なフラグの両方を処理します。このメソッドは、フィーチャールールを確認し、バリエーションを割り当て、`feature_key` と `visitor_code` に基づいてバリエーションを返すことにより、ユーザーに適切なバリエーションを取得します。 `Client.is_feature_active?` メソッドは、複数のバリエーションやターゲティングオプションを持つ複雑なフィーチャーフラグとは対照的に、ON または OFF 状態のみを持つシンプルなフィーチャーフラグの設定を取得したい場合に使用できます。 フィーチャーフラグに関連付けられた変数がある場合(各バリエーションに紐づく特定の動作など)、`Client.get_variation` は、割り当てられたバリエーションとその関連する実験の詳細を提供する [`Variation`](#variation) オブジェクトにもアクセスできるようにします。このメソッドは、ユーザーがターゲットになっているかどうかを確認し、訪問者に割り当てられたバリエーションを見つけ、ストレージに保存します。`track=true` の場合、SDK は次のトラッキング要求で指定された実験への露出イベントを送信します。このトラッキング要求は、SDK の [`tracking_interval_millis`](#追加設定) に基づいて自動的にトリガーされます。デフォルトでは、この間隔は 1000 ミリ秒(1 秒)に設定されています。 `Client.get_variation` メソッドを使用すると、トラッキングを行うかどうかを制御できます。`track=false` の場合、SDK によって露出イベントは送信されません。これは、SDK を介してデータをトラッキングするのではなく、たとえば Kameleoon エンジンによって管理されるクライアントサイドのトラッキングに依存することを希望する場合に便利です。さらに、`track=false` の設定は、すべてのフラグのバリエーションのみが必要で、トラッキングイベントをトリガーしたくない場合の `Client.get_variations` メソッドの使用時にも役立ちます。トラッキングがどのように機能するかについて詳しく知りたい場合は、[この記事](/developer-docs/feature-experimentation/technical-reference/faq-global#when-does-the-sdk-send-a-tracking-request-for-analytics)をご覧ください。 ##### ユーザーをターゲティングしたり、レポートの訪問をフィルタリング/ブレイクダウンしたりするためのデータポイントの追加 ユーザーをターゲティングするには、フィーチャーバリエーションを取得したり、フラグがアクティブかどうかを確認する前に、関連するデータポイントをそのプロファイルに追加していることを確認してください。[`Client.add_data`](#add_data) メソッドを使用して、これらのデータポイントをユーザーのプロファイルに追加します。 他のデバイスで収集されたデータポイントを取得したり、過去のユーザーデータ(Kameleoon をハイブリッドモードで使用しているときにクライアントサイドで収集されたデータ)にアクセスしたりするには、[`Client.get_remote_visitor_data`](#get_remote_visitor_data) メソッドを使用します。このメソッドは、サーバーからデータを非同期に取得します。このデータは、ユーザーを特定のバリエーションに割り当てるために必要な場合があるため、バリエーションを取得したり、フィーチャーフラグがアクティブかどうかを確認する*前*に `Client.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 サーバーに送信するには、[`Client.flush`](#flush) メソッドを呼び出すことを忘れないでください。 結果の正確性を確保するために、[`UserAgent`](#useragent) データ型を使用してボットをフィルタリングすることをお勧めします。 ##### ゴール変換のトラッキング ユーザーが望ましいアクション(購入など)を完了すると、それは変換として記録されます。変換をトラッキングするには、[`Client.track_conversion`](#track_conversion) メソッドを使用し、必須の `visitor_code` および `goal_id` パラメーターを提供します。 変換トラッキング要求は、次にスケジュールされたトラッキング要求と一緒に送信されます。SDK は定期的な間隔([`tracking_interval_millis`](#追加設定) で定義)でこれを送信します。要求を即座に送信したい場合は、[`Client.flush_instant`](#flush) メソッドを使用してください。 ##### アナリティクスソリューションへのイベントの送信 変換をトラッキングし、露出イベントを顧客アナリティクスソリューションに送信するには、まず Kameleoon を[ハイブリッドモード](/developer-docs/feature-experimentation/get-started/hybrid-experimentation/)で実装する必要があります。次に、[`Client.get_engine_tracking_code`](#get_engine_tracking_code) メソッドを使用します。 `Client.get_engine_tracking_code` メソッドは、露出イベントをアナリティクスソリューションに送信するために必要な一意のトラッキングコードを取得します。このメソッドを使用すると、イベントを記録し、希望するアナリティクスプラットフォームに送信できます。 ### カスタムバケッティングキーの使用 デフォルトでは、Kameleoon は一意の匿名訪問者 ID(`visitor_code`)を使用して、ユーザーをフィーチャーフラグのバリエーションに割り当てます。この ID は通常、ユーザーのデバイスで生成され保存されます(クライアントサイドおよびサーバーサイド SDK のブラウザ Cookie、モバイル SDK の永続ストレージ内)。ただし、特定のシナリオでは、同じ組織のすべてのユーザーがフィーチャーフラグの同じバリアントを表示することを保証する必要がある場合があります。 **カスタムバケッティングキー**オプションを使用すると、独自のカスタム識別子をバケッティング用に提供することで、このデフォルトの動作をオーバーライドできます。このオーバーライドにより、Kameleoon の割り当てロジックがデフォルトの `visitor_code` の代わりに、指定したキーを使用することが保証されます。 #### ユースケース カスタムバケッティングキーの使用は、特に以下の状況において、フィーチャーフラグの割り当ての一貫性と正確性を維持するために不可欠です: * **アカウントレベルまたは組織の実験:** B2B 製品や、同じ組織のすべてのユーザーを同じバリエーションに割り当てたいシナリオでは、`account_id` などの識別子を使用できます。カスタムバケッティングキーは、チームや会社全体に影響を与えるフィーチャーの A/B テストにとって極めて重要です。 カスタムバケッティングキーを実装することで、実験における一貫性と正確性を高め、より信頼性の高い結果とより良いユーザーエクスペリエンスにつなげることができます。 #### 技術的詳細 フィーチャーフラグにカスタムバケッティングキーを設定する場合、アプリケーションのデータから特定の識別子を Kameleoon に提供します: ```elixir theme={null} alias Kameleoon.Client alias Kameleoon.Data.CustomData :ok = Client.add_data(client, visitor_code, CustomData.new!(42, ["new_visitor_code"])) ``` * **カスタムキーの提供:** [`Client.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)を参照してください。 * **バケッティングロジック:** カスタムバケッティングキーが `Client.add_data` メソッドを介して提供されると、ユーザーをバリエーションに割り当てるためのすべてのハッシュ計算は、デフォルトの `visitor_code` の代わりに、この `new_visitor_code`(カスタムキー)を使用します。`new_visitor_code` を使用することで、バケッティングの決定がカスタム識別子に紐づけられ、その識別子が存在するさまざまなコンテキストで一貫した割り当てが保証されます。 * **データトラッキングとアナリティクス:** `new_visitor_code`(カスタムキー)はバケッティングの決定に使用される一方で、**後続のすべてのデータ(トラッキングイベントや変換など)は、*元の* `visitor_code` で送信され、関連付けられる**ことに注意することが重要です。この分離により、バケッティングがより高いレベル(アカウントなど)で、または複数のデバイス/セッション間で実行された場合でも、アナリティクスが実験のより広いコンテキスト内での個々のユーザージャーニーとインタラクションを正確に反映することが保証されます。元の訪問者データは、包括的なレポートのためにそのまま残ります。 #### 技術要件 カスタムバケッティングキーを効果的に使用するには: * キーは `String.t()` である必要があります。 * バケッティングしようとしているエンティティに対して一意である必要があります(たとえば、`user_id` を使用する場合、各ユーザーの ID は一意である必要があります)。 * キーは、そのユーザーまたはリクエストに対してフィーチャーフラグの決定が評価される正確な瞬間に SDK で利用可能である必要があります。 ### ターゲティング条件 Kameleoon SDK は、キャンペーンでユーザーをターゲティングするために使用できるさまざまな事前定義されたターゲティング条件をサポートしています。この SDK がサポートする条件のリストについては、[訪問履歴を使用してユーザーをターゲティングする](/developer-docs/feature-experimentation/targeting-and-segmentation/native-segmentation)を参照してください。 [ユーザーをターゲットにするための外部データ](/developer-docs/apis/data-api-rest/tutorials/storing-and-retrieving-external-data-to-target-users)を独自に使用することもできます。 ### クロスデバイス実験 複数のデバイスからアプリにアクセスする訪問者をサポートするために、Kameleoon は以前に収集された訪問者データを訪問者の各デバイス間で同期し、クロスデバイス実験を通じてデバイス間で訪問履歴を一致させることができます。Kameleoon がデバイス間でデータを処理する方法に関するケーススタディと詳細情報は、[クロスデバイス実験に関する記事](/developer-docs/cross-device-experimentation)で参照できます。 #### デバイス間でのカスタムデータの同期 カスタムマッピングの同期はデバイス間で訪問者データを整合させるために使用されますが、常に必要なわけではありません。以下は、カスタムマッピングの同期が必要ない 2 つのシナリオです: **デバイス間で同じユーザー ID** すべてのデバイスで同じユーザー ID が一貫して使用されている場合、同期はカスタムマッピングの同期なしで自動的に処理されます。複数のデバイス間で収集されたデータを同期したい場合は、`Client.get_remote_visitor_data` メソッドを呼び出すだけで十分です。 **一貫した ID を持つ複数サーバーインスタンス** 複数のサーバー(たとえば、分散サーバーインスタンス)を含む複雑なセットアップで、同じユーザー ID がサーバー間で利用可能な場合、追加のカスタムマッピング同期なしで、サーバー間の同期(`Client.get_remote_visitor_data` を使用)で十分です。 追加のデータが必要なお客様は、詳細なガイダンスについては [`Client.get_remote_visitor_data`](#get_remote_visitor_data) メソッドの説明を参照してください。以下のコードでは、2 つのデバイス間で同じ一意の識別子(この場合、`visitor_code`、`userId` とも呼ばれる)が一貫して使用されていることを前提としています。 収集したデータをリアルタイムで同期したい場合は、カスタムデータのスコープとして **Visitor** を選択する必要があります。 ```elixir title="デバイス A" theme={null} # この例では、インデックス `90` のカスタムデータが Kameleoon で "Visitor" スコープに設定されています。 alias Kameleoon.Client alias Kameleoon.Data.CustomData visitor_scope_custom_data_index = 90 :ok = Client.add_data(client, visitor_code, CustomData.new!(visitor_scope_custom_data_index, ["your data"])) :ok = Client.flush_instant(client, visitor_code) ``` ```elixir title="デバイス B" theme={null} # データを操作する前に、`get_remote_visitor_data` メソッドを呼び出します。 :ok = Client.get_remote_visitor_data(client, visitor_code) # このメソッドを呼び出した後、デバイス B 上の SDK は、デバイス A で定義された Visitor スコープの CustomData にアクセスできるようになります。 # したがって、"your data" は、訪問者のターゲティングとトラッキングに利用できます。 ``` #### セッションマージにカスタムデータを使用する [クロスデバイス実験](/developer-docs/cross-device-experimentation)では、訪問者の履歴を各デバイス間で結合できます(履歴の一致)。履歴の一致により、異なる訪問者セッションを 1 つにマージできます。訪問履歴を一致させるには、[`CustomData`](#customdata) を使用して訪問者の一意の識別子を提供します。詳細については、[専用ドキュメント](/developer-docs/cross-device-experimentation/#activating-cross-device-history-reconciliation)を参照してください。 クロスデバイスの一致が有効になった後、`userId` パラメーターを指定して [`Client.get_remote_visitor_data`](#get_remote_visitor_data) を呼び出すと、特定のユーザーに関する既知のすべてのデータが取得されます。 同じ識別子を持つセッションは、実験で常に同じバリエーションが表示されます。実験結果ページの Visitor ビューでは、これらのセッションは単一の訪問者として表示されます。 SDK の設定により、関連付けられたセッションは常に実験の同じバリエーションが表示されます。ただし、クロスデバイスのバリエーション割り当てに関するいくつかの制限があります。これらの制限は[こちら](/developer-docs/cross-device-experimentation#critical-points-and-practical-insights)に概説されています。 [クロスデバイスの履歴一致を有効化する](#クロスデバイス実験)ガイドに従って、Kameleoon プラットフォーム上でカスタムデータを設定します。 その後、SDK を通常通り使用できます。セッションマージのコンテキストで役立つ次のメソッドがあります: * `UniqueIdentifier(true)` を追加した `Client.get_remote_visitor_data` - リンクされたすべての訪問者のデータを取得します。 * `UniqueIdentifier(true)` データを追加した [`Client.track_conversion`](#track_conversion) または [`Client.flush`](#flush) - 別の訪問者に関連付けられている特定の訪問者の一部データをトラッキングします。 識別子として使用するカスタムデータは **Visitor スコープ**に設定する必要があるため、各デバイスで [`Client.get_remote_visitor_data`](#get_remote_visitor_data) メソッドを使用して識別子を取得するには、[クロスデバイスカスタムデータ同期](/developer-docs/cross-device-experimentation)を使用する必要があります。 セッションマージにカスタムデータを使用する方法の例を以下に示します。 ```elixir theme={null} # この例では、91 は Kameleoon で一意の識別子として設定されたカスタムデータのインデックスを表します。 alias Kameleoon.Client alias Kameleoon.Data.CustomData alias Kameleoon.Data.UniqueIdentifier mapping_index = 91 feature_key = "ff123" anonymous_visitor_code = "anonymous-visitor" user_id = "authenticated-user" # 1. 訪問者が認証される前 # 認証されていない訪問者のバリエーションを取得します。 # anonymousVisitorCode はその訪問者用にランダムに生成された ID であると仮定します。 {:ok, anonymous_variation} = Client.get_variation(client, anonymous_visitor_code, feature_key) # 2. 訪問者が認証された後 # `userId` が認証された訪問者の訪問者コードであると仮定します。 :ok = Client.add_data(client, anonymous_visitor_code, CustomData.new!(mapping_index, [user_id])) :ok = Client.flush_instant(client, anonymous_visitor_code) # `userId` が一意の識別子であることを示します。 :ok = Client.add_data(client, user_id, UniqueIdentifier.new!(true)) # 3. 訪問者が承認された後 # `userId` のバリエーションを取得します。これは匿名訪問者コードのバリエーションと一致します。 {:ok, user_variation} = Client.get_variation(client, user_id, feature_key) is_same_variation = user_variation.key == anonymous_variation.key # true # `userId` と `anonymousVisitorCode` はリンクされ、単一の訪問者としてトラッキングできるようになります。 :ok = Client.track_conversion(client, user_id, 123) # さらに、リンクされた訪問者は以前にトラッキングされたリモートデータをすべて共有します。 :ok = Client.get_remote_visitor_data(client, user_id) ``` この例では、アプリケーションにログインページがあります。ログイン時点ではユーザー ID が不明であるため、[`Client.get_visitor_code`](#get_visitor_code) メソッドによって生成された匿名の訪問者識別子が使用されます。ユーザーがログインした後、匿名の訪問者はユーザー ID に関連付けられ、その訪問者の一意の識別子として使用されます。 ### ロギング SDK はさまざまな内部プロセスや問題を反映するログを生成します。 #### ログレベル SDK は、ログレベルによるロギングの制限の設定をサポートしています。 ```elixir theme={null} alias Kameleoon.Logger # `:none` ログレベルではロギングが許可されません。 :ok = Logger.set_log_level(:none) # `:error` ログレベルでは、SDK の主要な動作に影響する問題のみがロギングされます。 :ok = Logger.set_log_level(:error) # `:warning` ログレベルでは、注意が必要な問題のロギングが許可されます。 # `:error` ログレベルを拡張したものです。 # `:warning` ログレベルはデフォルトのログレベルです。 :ok = Logger.set_log_level(:warning) # `:info` ログレベルでは、SDK の内部プロセスに関する一般的な情報のロギングが許可されます。 # `:warning` ログレベルを拡張したものです。 :ok = Logger.set_log_level(:info) # `:debug` レベルでは、SDK の内部プロセスに関する追加の詳細がロギングされます。 :ok = Logger.set_log_level(:debug) ``` #### ログのカスタムハンドリング SDK はデフォルトでログをコンソール出力に書き込みます。この動作はオーバーライドできます。 ログレベルによるロギング制限は、ログ処理ロジックとは別に実行されます。 ```elixir theme={null} defmodule MyKameleoonLogger do @behaviour Kameleoon.Logger require Logger @impl true def log(level, message) do Logger.log(level, message) end end # ログレベルフィルタリングは、ログ処理ロジックとは別に適用されます。 # カスタムロガーは、指定されたログレベル以上のログのみを受け入れます。 :ok = Kameleoon.Logger.set_log_level(:debug) :ok = Kameleoon.Logger.set_logger(MyKameleoonLogger) ``` ## リファレンス これは Elixir SDK の完全なリファレンスドキュメントです。 ### 初期化 #### create() SDK を使用するには、`Kameleoon.ClientFactory.create` で `%Kameleoon.Client\{\}` を作成します。デフォルトでは、`create` は `/etc/kameleoon/client-elixir.conf` を読み取ります。`config:` を介して `%Kameleoon.ClientConfig\{\}` 構造体を指定するか、`config_path:` を介してカスタム設定ファイルパスを指定することもできます。 ```elixir theme={null} alias Kameleoon.ClientConfig alias Kameleoon.ClientFactory config = %ClientConfig{ client_id: "", client_secret: "", refresh_interval_minutes: 60, session_duration_minutes: 30, default_timeout_millis: 10_000, tracking_interval_millis: 1_000, environment: "development", top_level_domain: ".example.com", proxy_host: "http://192.168.0.25:8080", network_domain: "example.com" } {:ok, client} = ClientFactory.create(site_code, config: config) ``` ##### 引数 | 名前 | 型 | 説明 | | ------------------ | ---------------------------- | ---------------------------------- | | `site_code` (*必須*) | `String.t()` | SDK で使用される Kameleoon プロジェクトの一意のキー。 | | `config` (*必須*) | `Kameleoon.ClientConfig.t()` | SDK の設定構造体。 | ```elixir theme={null} alias Kameleoon.ClientFactory {:ok, client} = ClientFactory.create("a8st4f59bj", config_path: "/etc/kameleoon/client-elixir.conf") ``` ##### 引数 | 名前 | 型 | 説明 | | -------------------- | ------------ | ---------------------------------- | | `site_code` (*必須*) | `String.t()` | SDK で使用される Kameleoon プロジェクトの一意のキー。 | | `config_path` (*必須*) | `String.t()` | 設定ファイルへのパス。 | ##### 戻り値 | 型 | 説明 | | | ------------------------------ | -------------------------------- | -------------------------------- | | \`\{:ok, Kameleoon.Client.t()} | \{:error, Kameleoon.Error.t()}\` | 成功時はクライアントインスタンス、それ以外の場合は初期化エラー。 | ##### エラー | 型 | 説明 | | -------------------------- | ----------------- | | `ConfigCredentialsInvalid` | SDK 認証情報が欠落しています。 | | `SiteCodeIsEmpty` | 指定されたサイトコードが空です。 | #### initialize() 設定された [`default_timeout_millis`](#追加設定) または指定された `timeout` のいずれかを使用して、Kameleoon クライアントの初期化を待機します。このメソッドにより、それ以降の操作を実行する前にクライアントが完全に初期化されることが保証されます。 ```elixir theme={null} alias Kameleoon.Client # 設定されたデフォルトのタイムアウトを使用してクライアントを初期化します :ok = Client.initialize(client) # 5 秒のカスタムタイムアウトでクライアントを初期化します :ok = Client.initialize(client, timeout: 5_000) ``` ##### 引数 | 名前 | 型 | 説明 | | ------------------- | ------------------- | -------------------- | | `timeout` (*オプション*) | `non_neg_integer()` | 初期化を待機する最大時間(ミリ秒単位)。 | ##### 戻り値 | 型 | 説明 | | | ----- | -------------------------------- | ---------------------------- | | \`:ok | \{:error, Kameleoon.Error.t()}\` | 初期化が正常に完了したか、エラーが発生したかを示します。 | ##### エラー | 型 | 説明 | | ---------------- | --------------------------- | | `Initialization` | SDK がまだ完全に初期化されていないことを示します。 | #### is\_ready() クライアントが初期化されたかどうかを確認します。 ```elixir theme={null} {:ok, ready?} = Kameleoon.Client.is_ready?(client) if ready? do # クライアントは準備ができています end ``` ##### 戻り値 | 型 | 説明 | | | ------------------- | -------------------------------- | ----------------------------------------------------------------------- | | \`\{:ok, boolean()} | \{:error, Kameleoon.Error.t()}\` | クライアントが使用可能な場合は `\{:ok, true\}`、使用できない場合は `\{:ok, false\}`、それ以外の場合はエラー。 | #### forget() 指定された `site_code` に関連付けられたキャッシュされた SDK クライアントを削除します。 ```elixir theme={null} alias Kameleoon.ClientFactory # 指定されたサイトコードのキャッシュされたクライアントを削除します :ok = ClientFactory.forget("a8st4f59bj") # 指定されたサイトコードと環境のキャッシュされたクライアントを削除します :ok = ClientFactory.forget("a8st4f59bj", environment: "production") ``` ##### 引数 | 名前 | 型 | 説明 | | ----------------------- | ------------ | --------------------------- | | `site_code` (*必須*) | `String.t()` | Kameleoon プロジェクトの一意の識別子。 | | `environment` (*オプション*) | `String.t()` | キャッシュされたクライアントに関連付けられた環境キー。 | ##### 戻り値 | 型 | 説明 | | | ----- | -------------------------------- | ---------------------------------------- | | \`:ok | \{:error, Kameleoon.Error.t()}\` | キャッシュされたクライアントが正常に削除されたか、エラーが発生したかを示します。 | ### フィーチャーフラグとバリエーション #### is\_feature\_active() * 📨 *Kameleoon にトラッキングデータを送信します(`track` オプションによる)* 特定のユーザーに対してフィーチャーフラグがアクティブかどうかを判定します。 訪問者がまだこのフィーチャーフラグに対して評価されていない場合、SDK はターゲティングルールを評価し、結果を返します。訪問者がすでにそのフィーチャーに関する評価を保存している場合、SDK は既存の結果を再利用して一貫性を確保します。 Kameleoon は、`Client.is_feature_active?`、`Client.get_variation`、`Client.get_variations` などの特定のメソッドを呼び出すと、セッションと訪問者をカウントするためにトラッキングを使用します。 訪問者をバリエーションに露出させ、それらをカウントする必要がある場合は、`track` パラメーターのデフォルト値 `true` を使用してください。訪問者を露出させる前にこれらのメソッドを呼び出す場合のみ、`track` パラメーターを `false` に設定してください。 たとえば、訪問者を露出させる前にすべてのバリエーションを取得するために `Client.get_variations` を呼び出す場合は、`track` パラメーターを `false` に設定してください。この設定により、Kameleoon がセッションを早期にカウントしないようになります。その後、明示的に訪問者を露出させたときにトラッキングをトリガーすることができます。 Kameleoon はデフォルトで毎秒トラッキングデータを送信します。トラッキング間隔設定オプションを使用して、この間隔を最大 5 秒に設定できます。Kameleoon は、イベント間の間隔が 30 分未満である限り、トラッキングイベントを単一のセッションにグループ化します。トラッキングイベント間に 30 分以上経過すると、Kameleoon はそれらのイベントを別々のセッションとしてカウントします。訪問は、セッション内で最後に記録されたイベントの 30 分後にレポートに表示されます。 `Client.is_feature_active?` メソッドは、マスターフラグの状態ではなく、提供されたバリアントを評価します。ルールを除外する場合、メソッドは **その他全員に対しては、配信** のデフォルト状態を使用します。このデフォルト状態に **Off** を選択した場合、マスターフィーチャーフラグが **On** であっても、メソッドは常に `false` を返します。 ```elixir theme={null} alias Kameleoon.Client feature_key = "new_checkout" # フィーチャーフラグを評価し、トラッキングデータを送信します(デフォルト動作) {:ok, active?} = Client.is_feature_active?(client, visitor_code, feature_key) # トラッキングデータを送信せずにフィーチャーフラグを評価します {:ok, active_without_tracking?} = Client.is_feature_active?(client, visitor_code, feature_key, track: false) ``` ##### 引数 | 名前 | 型 | 説明 | デフォルト | | --------------------- | ------------ | ---------------------------- | ------ | | `visitor_code` (*必須*) | `String.t()` | ユーザーの一意の識別子。 | | | `feature_key` (*必須*) | `String.t()` | ユーザーに対して評価するフィーチャーのキー。 | | | `track` (*オプション*) | `boolean()` | フィーチャー評価のトラッキングを有効または無効にします。 | `true` | ##### 戻り値 | 型 | 説明 | | | ------------------- | -------------------------------- | ---------------------------------------------------------- | | \`\{:ok, boolean()} | \{:error, Kameleoon.Error.t()}\` | 指定された `visitor_code` に対してフィーチャーフラグがアクティブかどうかを示すか、エラーを返します。 | ##### エラー | 型 | 説明 | | -------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | | `Initialization` | SDK がまだ完全に初期化されていないことを示します。 | | `FeatureNotFound` | 要求されたフィーチャーキーが SDK の内部設定で見つからなかったことを示す例外。これは通常、フィーチャーフラグが Kameleoon アプリで有効化されていない(ただし、そのフィーチャーを実装するコードはすでにアプリケーションにデプロイされている)ことを意味します。 | | `VisitorCodeInvalid` | 指定された訪問者コードが無効であることを示す例外。空であるか、255 文字を超えています。 | #### get\_variation() * 📨 *Kameleoon にトラッキングデータを送信します(`track` パラメーターによる)* 特定のフィーチャーフラグに対して、特定の訪問者に割り当てられた [`Variation`](#variation) を取得します。 このメソッドは、`visitor_code` と `feature_key` を必須引数として受け取ります。`track` 引数はオプションで、デフォルトは `true` です。 訪問者に割り当てられた `Variation` を返します。訪問者がフィーチャーフラグのルールに関連付けられていない場合、メソッドは指定されたフィーチャーフラグのデフォルトの `Variation` を返します。 潜在的な例外を管理するために、コードで適切なエラーハンドリングが実装されていることを確認してください。 デフォルトのバリエーションとは、フィーチャーフラグの事前定義された配信ルールのいずれにも一致しない訪問者に割り当てられるバリエーションを指します。言い換えると、特定のルールでターゲットされていないすべてのユーザーに適用されるフォールバックバリエーションです。管理インターフェースの「その他全員に対しては、...」セクションのバリエーションとして表されます。 ```elixir theme={null} alias Kameleoon.Client feature_key = "new_checkout" # 訪問者に割り当てられたバリエーションを取得します(トラッキングはデフォルトで有効) {:ok, variation} = Client.get_variation(client, visitor_code, feature_key) # トラッキングデータを送信せずにバリエーションを取得します {:ok, variation_without_tracking} = Client.get_variation(client, visitor_code, feature_key, track: false) ``` ##### 引数 | 名前 | 型 | 説明 | デフォルト | | -------------------- | ------------ | -------------------------------------- | ------ | | visitor\_code (*必須*) | `String.t()` | 訪問者の一意の識別子。 | | | feature\_key (*必須*) | `String.t()` | 訪問者に公開したいフィーチャーのキー。 | | | track (*オプション*) | `boolean()` | フィーチャー評価のトラッキングを有効または無効にするオプションパラメーター。 | `true` | ##### 戻り値 | 型 | 説明 | | --------------------------------------------------------------------------- | ------------------------------------------------------------------------- | | `\{:ok, Kameleoon.Types.Variation.t()\} \| \{:error, Kameleoon.Error.t()\}` | 成功時は特定のフィーチャーフラグに対して特定の訪問者に割り当てられた [`Variation`](#variation)、それ以外の場合はエラー。 | ##### エラー | 型 | 説明 | | ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | | `Initialization` | SDK がまだ完全に初期化されていないことを示します。 | | `VisitorCodeInvalid` | 指定された訪問者コードが無効であることを示す例外。空であるか、255 文字を超えています。 | | `FeatureNotFound` | 要求されたフィーチャーキーが SDK の内部設定で見つからなかったことを示す例外。これは通常、フィーチャーフラグが Kameleoon アプリで有効化されていない(ただし、そのフィーチャーを実装するコードはすでにアプリケーションにデプロイされている)ことを意味します。 | | `FeatureEnvironmentDisabled` | 訪問者の現在の環境(たとえば、production、staging、development)に対してフィーチャーフラグが無効になっていることを示す例外。 | | `FeatureEvaluationBlocked` | フィーチャー評価がブロックされていることを示す例外。理由はエラーメッセージに記載されています。これは通常、訪問者が法的同意を提供していない場合の GDPR 制限により発生します。 | #### get\_variations() * 📨 *Kameleoon にトラッキングデータを送信します(`track` パラメーターによる)* すべてのフィーチャーフラグにわたって、特定の訪問者に割り当てられた [`Variation`](#variation) オブジェクトのマップを取得します。 このメソッドは、利用可能なすべてのフィーチャーフラグを反復処理し、指定された訪問者に関連付けられた各フラグの割り当てられた `Variation` を返します。`visitor_code` は必須引数として受け取り、`only_active` と `track` はオプションです。 * `only_active` が `true` に設定されている場合、`Client.get_variations` メソッドは、ユーザーが `off` バリエーションにバケッティングされていないフィーチャーフラグのバリエーションを返します。 * `track` パラメーターは、メソッドがバリエーション割り当てをトラッキングするかどうかを制御します。デフォルトでは `true` に設定されています。`false` に設定すると、トラッキングは無効になります。 返されるマップは、フィーチャーフラグのキーをキーとし、それに対応する `Variation` を値として構成されます。フィーチャーフラグにバリエーションが割り当てられていない場合、メソッドはそのフラグのデフォルトの `Variation` を返します。 潜在的な例外を管理するために、適切なエラーハンドリングを実装する必要があります。 デフォルトのバリエーションとは、フィーチャーフラグの事前定義された配信ルールのいずれにも一致しない訪問者に割り当てられるバリエーションを指します。言い換えると、特定のルールでターゲットされていないすべてのユーザーに適用されるフォールバックバリエーションです。管理インターフェースの「その他全員に対しては、...」セクションのバリエーションとして表されます。 ```elixir theme={null} alias Kameleoon.Client # 訪問者に割り当てられたすべてのバリエーションを取得します(デフォルトオプションを使用) {:ok, variations} = Client.get_variations(client, visitor_code) # 訪問者のアクティブなバリエーションのみを取得します {:ok, only_active_variations} = Client.get_variations(client, visitor_code, only_active: true) # トラッキングデータを送信せずにバリエーションを取得します {:ok, variations_without_tracking} = Client.get_variations(client, visitor_code, track: false) ``` ##### 引数 | 名前 | 型 | 説明 | デフォルト | | ---------------------- | ------------ | --------------------------------------------------------------------- | ------- | | visitor\_code (*必須*) | `String.t()` | 訪問者の一意の識別子。 | | | only\_active (*オプション*) | `boolean()` | アクティブな(`true`)またはすべての(`false`)フィーチャーフラグのバリエーションを返すかどうかを示すオプションパラメーター。 | `false` | | track (*オプション*) | `boolean()` | フィーチャー評価のトラッキングを有効または無効にするオプションパラメーター。 | `true` | ##### 戻り値 | 型 | 説明 | | ---------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | | `\{:ok, %\{String.t() => Kameleoon.Types.Variation.t()\}\} \| \{:error, Kameleoon.Error.t()\}` | 成功時は対応するフィーチャーのキーを使用してフィーチャーフラグの割り当てられた [`Variation`](#variation) オブジェクトを含むマップ、それ以外の場合はエラー。 | ##### エラー | 型 | 説明 | | -------------------- | --------------------------------------------- | | `Initialization` | SDK がまだ完全に初期化されていないことを示します。 | | `VisitorCodeInvalid` | 指定された訪問者コードが無効であることを示す例外。空であるか、255 文字を超えています。 | #### set\_forced\_variation() このメソッドを使用すると、標準の評価プロセスをバイパスして、特定の [`Variation`](#variation) をプログラムでユーザーに割り当てることができます。これは、通常の評価ロジックが不要であるか、スキップする必要がある制御された実験で特に有用です。デバッグやカスタムテストなどのシナリオでも役立つことがあります。 **強制**バリエーションが設定されると、Kameleoon のリアルタイム評価ロジックがオーバーライドされます。セグメンテーション、ターゲティング条件、アルゴリズム計算などのプロセスはスキップされます。実験中にセグメンテーションとターゲティング条件を保持するには、代わりに `force_targeting=false` を設定してください。 **シミュレート**されたバリエーションは、常に実行順序で優先されます。**シミュレート**されたバリエーションの計算がトリガーされた場合、最初に完全に処理および完了されます。 強制バリエーションは、評価されたバリエーションと同じように扱われます。標準の評価されたバリエーションと同様に、アナリティクスでトラッキングされ、ユーザーコンテキストに保存され、レポートの一貫性が保たれます。 このメソッドは、特定の条件下(例: 無効なパラメーター、ユーザーコンテキスト、または内部問題)で例外をスローする可能性があります。アプリケーションの安定性と回復力を確保するために、適切な例外処理が不可欠です。 **強制**バリエーションを **[シミュレート](#get_visitor_code)** バリエーションと区別することが重要です: * **強制バリエーション**: 個々の実験に固有のものです。 * **シミュレートされたバリエーション**: 全体的な**フィーチャーフラグ**結果に影響します。 ```elixir theme={null} alias Kameleoon.Client experiment_id = 202_387 # 指定された実験に対して訪問者を "variation_2" に強制します :ok = Client.set_forced_variation(client, visitor_code, experiment_id, "variation_2") # この実験で訪問者に対して以前に強制されたバリエーションを削除します :ok = Client.set_forced_variation(client, visitor_code, experiment_id, nil) # カスタムオプションで訪問者を "variation_2" に強制します。 # この場合、ターゲティングルールが尊重されます(force_targeting = false)。 :ok = Client.set_forced_variation( client, visitor_code, experiment_id, "variation_2", force_targeting: false ) ``` ##### 引数 | 名前 | 型 | 説明 | デフォルト | | -------------------------- | ------------------- | ---------------------------------------------------------------------------------- | ------ | | visitor\_code (*必須*) | `String.t()` | 訪問者の一意の識別子。 | | | experiment\_id (*必須*) | `non_neg_integer()` | 評価プロセス中にターゲティングおよび選択される **実験 ID**。 | | | variation\_key (*必須*) | `String.t() \| nil` | 実験に対して返される値として強制する `Variation` に対応する**バリエーションキー**。値が `nil` の場合、強制バリエーションはリセットされます。 | | | force\_targeting (*オプション*) | `boolean()` | 実験のターゲティングを強制してスキップするか(`true`)、標準の評価プロセスのように適用するか(`false`)を示します。 | `true` | ##### 戻り値 | 型 | 説明 | | | ----- | -------------------------------- | ----------------------------------- | | \`:ok | \{:error, Kameleoon.Error.t()}\` | 強制バリエーションが正常に設定されたか、エラーが発生したかを示します。 | ##### エラー | 型 | 説明 | | --------------------------- | ------------------------------------------------------------------------------------------------------- | | `Initialization` | SDK がまだ完全に初期化されていないことを示します。 | | `VisitorCodeInvalid` | 指定された訪問者コードが無効であることを示す例外。空であるか、255 文字を超えています。 | | `FeatureExperimentNotFound` | 要求された実験 ID が SDK の内部設定に見つからなかったことを示す例外。これは通常正常で、ルールに対応する実験が Kameleoon 側でまだ有効化されていないことを意味します。 | | `FeatureVariationNotFound` | 要求されたバリエーションキー(ID)が SDK の内部設定に見つからなかったことを示す例外。これは通常正常で、バリエーションに対応する実験が Kameleoon 側でまだ有効化されていないことを意味します。 | #### evaluate\_audiences() * 📨 *Kameleoon にトラッキングデータを送信します* このメソッドは、訪問者を利用可能なすべての Audiences Explorer セグメントに対して評価し、一致するものをトラッキングします。 `Client.evaluate_audiences` は、**関連するすべての訪問者データが設定または更新された後**、フィーチャーバリエーションの取得やフィーチャーフラグの確認の**直前に**呼び出す必要があります。このアプローチにより、訪問者は利用可能な最新のデータに対して評価され、すべての基準に基づいて正確なオーディエンス割り当てが可能になります。 このメソッドを呼び出した後、Audiences Explorer でセグメントパフォーマンスの詳細な分析を実行できます。 ```elixir theme={null} :ok = Kameleoon.Client.evaluate_audiences(client, visitor_code) ``` ##### 引数 | 名前 | 型 | 説明 | | -------------------- | ------------ | ----------- | | visitor\_code (*必須*) | `String.t()` | 訪問者の一意の識別子。 | ##### 戻り値 | 型 | 説明 | | | ----- | -------------------------------- | ------------------------------- | | \`:ok | \{:error, Kameleoon.Error.t()}\` | オーディエンス評価が成功したか、エラーが発生したかを示します。 | ##### エラー | 型 | 説明 | | -------------------- | --------------------------------------------- | | `VisitorCodeInvalid` | 指定された訪問者コードが無効であることを示す例外。空であるか、255 文字を超えています。 | #### get\_datafile() すべてのフィーチャーフラグを評価するには、[`Client.get_variations`](#get_variations) を使用します。このメソッドは、`DataFile` を呼び出して [`Client.get_variation`](#get_variation) でフラグを反復処理するよりも効率的です。 現在の SDK 設定を [`DataFile`](#datafile) オブジェクトとして返します。 ```elixir theme={null} {:ok, datafile} = Kameleoon.Client.get_datafile(client) ``` ##### 戻り値 | 型 | 説明 | | -------------------------------------------------------------------------- | --------------------------------------------------- | | `\{:ok, Kameleoon.Types.DataFile.t()\} \| \{:error, Kameleoon.Error.t()\}` | 成功時は SDK 設定を含む [`DataFile`](#datafile)、それ以外の場合はエラー。 | ##### エラー | 型 | 説明 | | ---------------- | --------------------------- | | `Initialization` | SDK がまだ完全に初期化されていないことを示します。 | ### 訪問者データ #### get\_visitor\_code() `get_visitor_code()` を使用して、現在の訪問者の Kameleoon `visitor_code` を取得します。このメソッドは、`Kameleoon.CookieAccessor` ビヘイビアを実装する任意の Cookie ストアで機能します。 実装ロジックは次のとおりです: 1. SDK は、`kameleoonVisitorCode` Cookie が提供されたアクセサーを通じてすでに利用可能かどうかを確認します。 2. Cookie が存在しない場合、SDK は提供された `default_visitor_code` を使用します。 3. それ以外の場合、SDK は新しい訪問者コードを生成し、アクセサーを通じて保存します。 詳細については、[ハイブリッド実験](/developer-docs/feature-experimentation/get-started/hybrid-experimentation/)を参照してください。 独自の `visitor_code` を提供する場合は、その一意性をあなた側で保証する必要があります。また、`visitor_code` の長さは `255` 文字までに制限されていることに注意してください。 `Client.get_visitor_code` メソッドを使用すると、訪問者に対して**シミュレート**されたバリエーションを設定できます。Cookie(**リクエスト**または**ドキュメント**から)にキー `kameleoonSimulationFFData` が含まれている場合、標準の評価プロセスはバイパスされます。代わりに、メソッドは提供されたデータに基づいて [`Variation`](#variation) を直接返します。 シミュレーションは 2 つの方法で適用できます: * **自動(推奨):** Kameleoon Web Experimentation または [ハイブリッドモード](/developer-docs/feature-experimentation/get-started/hybrid-experimentation#linking-feature-experiments-with-front-end-tracking-code)で SDK を使用している場合、[シミュレーションパネル](/user-manual/experimentation/feature-experimentation/using-the-rollout-planner/validation-and-rollback/using-simulation-mode)を使用してバリアントの表示をシミュレートすると、Cookie が自動的に作成されます。 * **手動:** `kameleoonSimulationFFData` Cookie を手動で設定します。 **シミュレート**されたバリエーションを **[強制](#set_forced_variation)** されたバリエーションと区別することが重要です: * **シミュレートされたバリエーション**: 全体的な**フィーチャーフラグ**結果に影響します。 * **強制バリエーション**: 個々の実験に固有のものです。 ⚙️ **手動セットアップ** `kameleoonSimulationFFData` Cookie が次の形式に従うようにしてください: * `kameleoonSimulationFFData={"featureKey":{"expId":10,"varId":20}}`: 指定された `featureKey` に対して、実験 `expId` の `varId` のバリエーションをシミュレートします。 * `kameleoonSimulationFFData={"featureKey":{"expId":0}}`: 指定された `featureKey` に対して、デフォルトバリエーション(**その他全員に対しては Production で、配信**セクションで定義されたもの)をシミュレートします。 ⚠️ 適切な機能を確保するために、Cookie 値は [`encodeURIComponent`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/encodeURIComponent) などのメソッドを使用して URI コンポーネントとしてエンコードする必要があります。 ```elixir theme={null} defmodule MemoryCookies do @behaviour Kameleoon.CookieAccessor @impl true def get(cookies, key), do: Map.get(cookies, key) @impl true def set(cookies, key, value, _max_age, _top_level_domain) do Map.put(cookies, key, value) end end cookies = {MemoryCookies, %{}} # 自動生成された値を使用して訪問者コードを生成または取得します。 {:ok, visitor_code, cookies} = Kameleoon.Client.get_visitor_code(client, cookies) # 事前定義されたユーザー ID を使用して訪問者コードを生成または取得します。 {:ok, visitor_code, cookies} = Kameleoon.Client.get_visitor_code(client, {MemoryCookies, cookies}, "user_id") ``` ```elixir theme={null} defmodule PlugConnCookies do @behaviour Kameleoon.CookieAccessor @impl true def get(conn, key), do: conn.req_cookies[key] @impl true def set(conn, key, value, max_age, top_level_domain) do opts = [path: "/", max_age: max_age] opts = if top_level_domain, do: Keyword.put(opts, :domain, top_level_domain), else: opts Plug.Conn.put_resp_cookie(conn, key, value, opts) end end def get_visitor_code(conn, client) do cookies = {PlugConnCookies, conn} with {:ok, visitor_code, conn} <- Kameleoon.Client.get_visitor_code(client, cookies) do {:ok, visitor_code, conn} end end ``` ##### 引数 | 名前 | 型 | 説明 | | | -------------------------------- | ---------------------- | ------------------------------------------------------------- | --------------------------- | | `cookies` (*必須*) | `\{module(), term()\}` | 訪問者 Cookie を読み取って保存するために使用される Cookie アクセサーモジュールとフレームワーク固有の状態。 | | | `default_visitor_code` (*オプション*) | \`String.t() | nil\` | Cookie が存在しない場合に使用する訪問者コード。 | アクセサーモジュールは `get` および `set` を実装する必要があります。`get` はアクセサーの状態から Cookie の値を読み取り、`set` は `key`、`value`、`max_age`、および `top_level_domain` を受け取った後、更新された状態を返します。 ##### 戻り値 | 型 | 説明 | | | ---------------------------- | -------------------------------- | ------------------------------------------- | | \`\{:ok, String.t(), term()} | \{:error, Kameleoon.Error.t()}\` | 成功時は SDK で使用される一意の訪問者コードを表す文字列、それ以外の場合はエラー。 | #### add\_data() `Client.add_data` メソッドは、[ターゲティングデータ](#データ型)をストレージに追加し、他のメソッドがそのデータを使用して現在の訪問者をターゲットにするかどうかを決定できるようにします。 `Client.add_data` メソッドは、いかなる値も返さず、それ自体で Kameleoon バックエンドサーバーと対話しません。代わりに、すべての宣言されたデータは、[`Client.flush`](#flush) メソッドを使用した将来の送信のために保存されます。このアプローチにより、データは通常、`Client.flush` によってトリガーされる単一のサーバー呼び出しにグループ化されるため、サーバー呼び出しの数が削減されます。 [`Client.track_conversion`](#track_conversion) メソッドも、`Client.flush` と同様に、以前に関連付けられたデータを送信します。実験ルールがトリガーされた場合、[`Client.get_variation`](#get_variation) と [`Client.get_variations`](#get_variations) メソッドにも同じことが当てはまります。 ほとんどのデータ型について、各訪問者は関連付けられたデータのインスタンスを 1 つしか持つことができません。ただし、[`CustomData`](#customdata) は例外です。訪問者は、インデックスごとに 1 つの関連付けられた `CustomData` のインスタンスを持つことができます。 ```elixir theme={null} alias Kameleoon.Client alias Kameleoon.Data.Browser alias Kameleoon.Data.PageView alias Kameleoon.Data.UserAgent :ok = Client.add_data(client, visitor_code, Browser.new!(:chrome, version: 123.0)) :ok = Client.add_data(client, visitor_code, [ PageView.new!("https://example.com/pricing", title: "Pricing", referrers: [3]), UserAgent.new!("Mozilla/5.0") ]) :ok = Client.add_data( client, visitor_code, PageView.new!("https://example.com/checkout", title: "Checkout"), track: false ) ``` ##### 引数 | 名前 | 型 | 説明 | デフォルト値 | | -------------------- | ------------------------ | --------------------------------------------------------------------------------------------------------- | ------ | | visitor\_code (*必須*) | `String.t()` | 訪問者の一意の識別子。 | | | data (*必須*) | `struct() \| [struct()]` | Kameleoon データ型のコレクション。 | | | track (*オプション*) | `boolean()` | 追加されたデータがトラッキング対象になるかを指定します。`false` に設定すると、データはローカルに保存され、ターゲティング評価のみに使用されます。Kameleoon Data API には送信されません。 | `true` | ##### 戻り値 | 型 | 説明 | | | ----- | -------------------------------- | ----------------------------- | | \`:ok | \{:error, Kameleoon.Error.t()}\` | データが正常に追加されたか、エラーが発生したかを示します。 | ##### エラー | 型 | 説明 | | -------------------- | --------------------------------------------- | | `Initialization` | SDK がまだ完全に初期化されていないことを示します。 | | `VisitorCodeInvalid` | 指定された訪問者コードが無効であることを示す例外。空であるか、255 文字を超えています。 | #### flush() * *📨 Kameleoon にトラッキングデータを送信します* `flush()` メソッドは、訪問者に関連付けられたすべての Kameleoon データを集約し、トラッキング要求をサーバーに送信します。この要求には、他のトラッキングメカニズム(詳細は参照されるメソッドを参照)を通じてまだ送信されていない、以前に [`add_data`](#add_data) メソッドを介して追加されたデータが含まれます。サーバー呼び出しは非同期的に実行されるため、`flush()` 操作はノンブロッキングです。 このメソッドは、特定の `visitor_code` に関連付けられたデータがいつ送信されるかを制御できます。たとえば、`add_data()` が複数回呼び出される場合、各呼び出し後に要求を送信するのは非効率的です。代わりに、これらの更新をバッチ処理し、`flush()` を 1 回呼び出して、累積されたすべてのデータを単一の要求で送信できます。 `flush()` メソッドは、提供された `visitor_code` を訪問者の一意の識別子として使用します。 * `flush()` — 設定されたトラッキング間隔に従ってフラッシュ操作をキューに入れます。 * `flush_instant()` — 間隔を待たずに、トラッキングデータを即座に送信します。 ```elixir theme={null} # 指定された visitor_code のフラッシュ操作をキューに入れます。 # データは、設定されたトラッキング間隔に従って送信されます。 :ok = Kameleoon.Client.flush(client, visitor_code) # 指定された visitor_code のすべての保留中のトラッキングデータを即座に送信します。 :ok = Kameleoon.Client.flush_instant(client, visitor_code) ``` ##### 引数 | 名前 | 型 | 説明 | | --------------------- | ------------ | ----------- | | `visitor_code` (*必須*) | `String.t()` | 訪問者の一意の識別子。 | ##### 戻り値 | 型 | 説明 | | | ----- | -------------------------------- | ------------------------------------- | | \`:ok | \{:error, Kameleoon.Error.t()}\` | 操作が正常にスケジュールまたは実行されたか、エラーが発生したかを示します。 | ##### エラー | 型 | 説明 | | -------------------- | --------------------------------------------- | | `Initialization` | SDK がまだ完全に初期化されていないことを示します。 | | `VisitorCodeInvalid` | 指定された訪問者コードが無効であることを示す例外。空であるか、255 文字を超えています。 | #### get\_remote\_data() `get_remote_data()` メソッドを使用すると、指定された `key` に対して Kameleoon サーバーに保存されているリモートデータを取得できます。ほとんどのセットアップでは、このデータは Kameleoon Data API を通じて書き込まれ、追加のアプリケーションコンテキストが必要なときに、後で Elixir サービスによって取得できます。 このメソッドは、構造化された情報を Kameleoon のリモートインフラストラクチャに保存し、別個の取得メカニズムを維持することなくバックエンドから再利用したい場合に役立ちます。 ```elixir theme={null} {:ok, data} = Kameleoon.Client.get_remote_data(client, "test-key") ``` ##### 引数 | 名前 | 型 | 説明 | | ------------ | ------------ | ----------------------- | | `key` (*必須*) | `String.t()` | 取得したいリモートデータに関連付けられたキー。 | ##### 戻り値 | 型 | 説明 | | | -------------------- | -------------------------------- | -------------------------------------------------------------------------------- | | \`\{:ok, String.t()} | \{:error, Kameleoon.Error.t()}\` | 成功時は指定された `key` に関連付けられたペイロード、それ以外の場合はエラー。ほとんどの場合、ペイロードは文字列としてシリアライズされた JSON です。 | ##### エラー | 型 | 説明 | | ---------------- | ------------------------------------------------ | | `Initialization` | SDK がまだ完全に初期化されていないことを示します。 | | `Network` | リモートデータ要求が失敗したか、サーバーが成功以外のステータスコードで応答した場合に返されます。 | #### get\_remote\_visitor\_data() `get_remote_visitor_data()` は、指定された `visitor_code` に対して Kameleoon の訪問データを取得します。このメソッドは、データをローカル訪問者ストレージに追加し、他の SDK メソッドがターゲティング決定に使用できるようにします。 このメソッドを使用して取得されたデータは、次のような場合に特に便利です: * 他のデバイスから収集されたデータを使用する。 * 過去の訪問で以前に閲覧されたページなど、訪問者の履歴にアクセスする。 * データレイヤー変数やフロントエンドのゴール変換など、クライアント側でのみ利用可能なデータを使用する。 可能なユースケースをより深く理解するために、[この記事](/developer-docs/feature-experimentation/targeting-and-segmentation/native-segmentation)を読んでください。 デフォルトでは、`get_remote_visitor_data()` は `scope=Visitor` の最新の保存済みカスタムデータを自動的に取得し、[`add_data()`](#add_data) を呼び出す必要なしに訪問者に添付します。これは、[複数デバイス間でのカスタムデータの同期](/developer-docs/cross-device-experimentation/)に特に便利です。 ```elixir theme={null} alias Kameleoon.Client alias Kameleoon.Types.RemoteVisitorDataFilter # フィルターなしでリモート訪問者データを取得します。 # 指定された訪問者の利用可能なすべてのデータが返されます。 :ok = Client.get_remote_visitor_data(client, visitor_code) # 返されるデータを制限するためにフィルターを作成します。 filter = %RemoteVisitorDataFilter{ previous_visit_amount: 5, conversions: true, page_views: true } # 指定されたフィルターを使用してリモート訪問者データを取得します。 # これは、フィルター基準に一致するデータのみを返します。 :ok = Client.get_remote_visitor_data(client, visitor_code, filter: filter) ``` ##### 引数 | 名前 | 型 | 説明 | デフォルト | | | --------------------- | --------------------------------------------- | --------------- | ------------------------- | ------------------------------ | | `visitor_code` (*必須*) | `String.t()` | データを取得する訪問者コード。 | | | | `filter` (*オプション*) | \`Kameleoon.Types.RemoteVisitorDataFilter.t() | nil\` | 取得するリモート訪問者データを記述するフィルター。 | `%RemoteVisitorDataFilter\{\}` | ##### 戻り値 | 型 | 説明 | | | ----- | -------------------------------- | ------------------------------------------ | | \`:ok | \{:error, Kameleoon.Error.t()}\` | データの取得とローカル追加が完了すると正常終了し、それ以外の場合はエラーを返します。 | ##### エラー | 型 | 説明 | | -------------------- | ----------------------------------------------------------------- | | `Initialization` | SDK がまだ完全に初期化されていないことを示します。 | | `VisitorCodeInvalid` | 指定された訪問者コードが無効であることを示す例外。空であるか、255 文字を超えています。 | | `Network` | リモート訪問者データ要求が失敗したか、解析できなかった場合、またはサーバーが成功以外のステータスコードで応答した場合に返されます。 | ##### get\_remote\_visitor\_data() でのパラメーターの使用 `get_remote_visitor_data()` メソッドを使用すると、訪問者に対してどのデータが取得されるかを制御できます。同じフィルタリングアプローチが、ゴール、実験、バリエーション、その他の訪問者データ全体で機能します。 たとえば、過去 5 回の訪問でゴールに変換したユーザーをターゲットにしたい場合、`previous_visit_amount` を `5` に、`conversions` を `true` に設定できます。 この例で示されている柔軟性はゴールデータに限定されません。フィルターを使用して、さまざまな訪問者の行動を取得し、Elixir アプリケーションのターゲティングおよびレポートロジックで利用可能にすることができます。 ##### `RemoteVisitorDataFilter` フィールド | 名前 | 型 | 説明 | デフォルト | | ----------------------- | ------------------- | ------------------------------------------------- | ------- | | `previous_visit_amount` | `non_neg_integer()` | データを取得する過去の訪問数。 | `1` | | `current_visit` | `boolean()` | `true` の場合、現在の訪問データが取得されます。 | `true` | | `custom_data` | `boolean()` | `true` の場合、カスタムデータが取得されます。 | `true` | | `visitor_code` | `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 データが取得されます。 | `false` | | `personalizations` | `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 のカスタムデータに対応します。 呼び出しが成功すると、SDK は返されたオーディエンスリストを [`CustomData`](#customdata) に変換し、ローカルで訪問者に追加し、ターゲティング目的で利用できるようにします。詳細については、[ウェアハウスターゲティングのドキュメント](/user-manual/integrations/data-warehouses/bigquery/use-bigquery-as-a-source-audience-targeting)を参照してください。 ```elixir theme={null} alias Kameleoon.Client # visitor_code のみを使用して訪問者のオーディエンスデータを取得します。 :ok = Client.get_visitor_warehouse_audience(client, visitor_code, 98) # visitor_code と warehouse_key の両方を使用して訪問者のオーディエンスデータを取得します。 # ウェアハウスが visitor_code とは異なる識別子を使用する場合に便利です。 :ok = Client.get_visitor_warehouse_audience(client, visitor_code, 98, warehouse_key: "internal-user-id") ``` ##### 引数 | 名前 | 型 | 説明 | デフォルト | | | -------------------------- | ------------------- | ------------------------------------------------------- | ------------------------ | -------------- | | `visitor_code` (*必須*) | `String.t()` | ウェアハウスのオーディエンスを取得する訪問者。 | | | | `custom_data_index` (*必須*) | `non_neg_integer()` | ウェアハウスのオーディエンスターゲティング用に Kameleoon で設定されたカスタムデータのインデックス。 | | | | `warehouse_key` (*オプション*) | \`String.t() | nil\` | 外部ウェアハウスキー、通常は内部ユーザー ID。 | `visitor_code` | ##### 戻り値 | 型 | 説明 | | | ----- | -------------------------------- | ----------------------------------------------------- | | \`:ok | \{:error, Kameleoon.Error.t()}\` | ウェアハウスのオーディエンスデータが取得され、`CustomData` としてローカルに保存されると成功。 | ##### エラー | 型 | 説明 | | -------------------- | ------------------------------------------------------------------ | | `Initialization` | SDK がまだ完全に初期化されていないことを示します。 | | `VisitorCodeInvalid` | 指定された訪問者コードが無効であることを示す例外。空であるか、255 文字を超えています。 | | `Network` | ウェアハウスのオーディエンス要求が失敗した、解析できなかった、またはサーバーが成功以外のステータスコードで応答した場合に返されます。 | #### set\_legal\_consent() このメソッドを使用して、訪問者が個人データの使用に法的同意を与えたかどうかを指定する必要があります。`legal_consent` を `false` に設定すると、トラッキング要求に含めることができるデータの種類が制限されます。これにより、訪問者データを責任を持って管理しながら、法的および規制要件に準拠するのに役立ちます。詳細については、[同意管理ポリシー](/user-manual/project-management/consent-management-policy)を参照してください。 Elixir SDK は、必要な `Kameleoon.CookieAccessor` アダプターを通じて訪問者 Cookie を更新し、更新されたアダプター状態を返します。 ```elixir theme={null} cookies = {PlugConnCookies, conn} # 同意を設定し、Cookie を更新します。 {:ok, conn} = Kameleoon.Client.set_legal_consent(client, visitor_code, true, cookies) ``` ##### 引数 | 名前 | 型 | 説明 | デフォルト | | --------------------- | ---------------------- | --------------------------------------------------------------------- | ----- | | `visitor_code` (*必須*) | `String.t()` | ユーザーの一意の識別子。 | | | `consent` (*必須*) | `boolean()` | `true` は訪問者が法的同意を与えたことを示し、`false` は訪問者が法的同意を提供したことがない、または撤回したことを示します。 | | | `cookies` (*必須*) | `\{module(), term()\}` | Cookie を更新するために使用される Cookie アクセサーモジュールとフレームワーク固有の状態。 | | ##### 戻り値 | 型 | 説明 | | | ---------------- | -------------------------------- | ---------------------------------------------------- | | \`\{:ok, term()} | \{:error, Kameleoon.Error.t()}\` | 訪問者の同意状態が正常に更新された場合は更新された Cookie の状態を返し、それ以外の場合はエラー。 | ##### エラー | 型 | 説明 | | -------------------- | --------------------------------------------- | | `Initialization` | SDK がまだ完全に初期化されていないことを示します。 | | `VisitorCodeInvalid` | 指定された訪問者コードが無効であることを示す例外。空であるか、255 文字を超えています。 | ##### 同意撤回の動作 `Client.set_legal_consent` を `legal_consent=false` で呼び出すと、SDK は `kameleoonVisitorCode` Cookie を削除しません。代わりに、Cookie の有効期限の延長を停止し、Cookie が自然に期限切れになるまで残るようにします。 コンプライアンス要件によりオプトアウト時に Cookie ファイルの即時削除が必要な場合は、フレームワークのネイティブな Cookie 管理メソッドを使用して手動で削除する必要があります。SDK はファイルを自動的に削除しません。 ### ゴールとサードパーティアナリティクス #### track\_conversion() * 📨 *Kameleoon にトラッキングデータを送信します* このメソッドを使用して、特定の[ゴール](/user-manual//assets/goals/create-a-goal)とユーザーに対する変換をトラッキングします。このメソッドには `visitor_code` と `goal_id` が必要です。さらに、このメソッドはオプションの `revenue`、`negative`、および `metadata` 引数も受け入れます。`visitor_code` は通常、実験をトリガーしたときに使用されたものと同じです。 このメソッドは、サーバー呼び出しが非同期的に行われるため、ノンブロッキングです。 ```elixir theme={null} alias Kameleoon.Client alias Kameleoon.Data.CustomData # ゴールをトラッキングします。 :ok = Client.track_conversion(client, visitor_code, goal_id) # 収益を伴うゴールをトラッキングします。 :ok = Client.track_conversion(client, visitor_code, goal_id, revenue: 100.0) # 負の収益を伴うゴールをトラッキングします。 :ok = Client.track_conversion(client, visitor_code, goal_id, revenue: 100.0, negative: true) # カスタムメタデータを伴うゴールをトラッキングします。 :ok = Client.track_conversion( client, visitor_code, goal_id, metadata: [CustomData.new!(4, ["true"])] ) ``` ##### 引数 | 名前 | 型 | 説明 | デフォルト | | --------------------- | --------------------------------- | -------------------------------------------------------------------------------------------- | ------- | | `visitor_code` (*必須*) | `String.t()` | 訪問者の一意の識別子。 | | | `goal_id` (*必須*) | `non_neg_integer()` | ゴールの ID。 | | | `revenue` (*オプション*) | `number() \| nil` | 変換の収益。 | `0` | | `negative` (*オプション*) | `boolean()` | 収益が正か負かを定義します。 | `false` | | `metadata` (*オプション*) | `[Kameleoon.Data.CustomData.t()]` | 変換のメタデータ。[事前に Kameleoon App で定義する必要があります](/ja/user-manual/assets/goals/create-a-goal#メタデータ)。 | `[]` | メタデータ値は、[生データのエクスポート](/user-manual/experiment-analytics/analyze-results/results-page/results-page-actions#Export)と[結果ページ](/user-manual/experiment-analytics/analyze-results/data-and-metrics/goal-metadata)からアクセス可能です。 `metadata` パラメーターが提供されている場合、Kameleoon は、[`Client.add_data`](#add_data) メソッドを使用して以前に収集されたものではなく、これらの指定された値を現在の変換に使用します。パラメーターが省略されている場合、Kameleoon は変換前および同じ訪問内でその [`CustomData`](#customdata) について最後にトラッキングされた値を使用します。 Kameleoon は、`Client.track_conversion` メソッドにパラメーターとして明示的に渡されたメタデータ値のみを考慮します。 以下の例では、Kameleoon は、パラメーターとして明示的に提供されたカスタムデータ値のみ(ここでは: インデックス 5 の値 'Amex Credit Card')と変換を関連付けます。 ```elixir theme={null} :ok = Client.add_data(client, visitor_code, [ CustomData.new!(5, ["Credit Card"]), CustomData.new!(9, ["Express Delivery"]) ]) :ok = Client.track_conversion( client, visitor_code, goal_id, metadata: [CustomData.new!(5, ["Amex Credit Card"])] ) ``` ##### 戻り値 | 型 | 説明 | | | ----- | -------------------------------- | --------------------------------------------- | | \`:ok | \{:error, Kameleoon.Error.t()}\` | 変換が非同期トラッキング用に正常にキューに入れられたか、それ以外の場合はエラーを示します。 | ##### エラー | 型 | 説明 | | -------------------- | --------------------------------------------- | | `Initialization` | SDK がまだ完全に初期化されていないことを示します。 | | `VisitorCodeInvalid` | 指定された訪問者コードが無効であることを示す例外。空であるか、255 文字を超えています。 | #### get\_engine\_tracking\_code() Kameleoon は、Mixpanel、Google Analytics 4、Segment など、いくつかのアナリティクスソリューションと統合されています。サーバーサイドの実験を正しくトラッキングするには、訪問者が実験をトリガーした後に `Client.get_engine_tracking_code` メソッドを呼び出します。SDK は、訪問者が前回 5 秒間にトリガーした実験用の JavaScript キューコマンドを返します。このコードをページに挿入すると、Engine.js がコマンドを処理し、アクティブなアナリティクス統合を介して露出イベントを送信します。 このメソッドの実装の詳細については、[ハイブリッド実験](/developer-docs/feature-experimentation/get-started/hybrid-experimentation)を参照してください。 ```elixir theme={null} {:ok, tracking_code} = Kameleoon.Client.get_engine_tracking_code(client, visitor_code) ``` * この機能を使用するには、Elixir 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 ` ``` この例では、`123456` と `234567` は実験 ID で、`7890` と `8901` はバリエーション ID です。実装では、SDK が返されたトラッキングコード内でこれらの値を生成します。 ##### 引数 | 名前 | 型 | 説明 | | -------------------- | ------------ | ----------- | | visitor\_code (*必須*) | `String.t()` | 訪問者の一意の識別子。 | ##### 戻り値 | 型 | 説明 | | | -------------------- | -------------------------------- | ---------------------------------------- | | \`\{:ok, String.t()} | \{:error, Kameleoon.Error.t()}\` | 成功時はページに挿入する JavaScript コード、それ以外の場合はエラー。 | ##### エラー | 型 | 説明 | | -------------------- | --------------------------------------------- | | `Initialization` | SDK がまだ完全に初期化されていないことを示します。 | | `VisitorCodeInvalid` | 指定された訪問者コードが無効であることを示す例外。空であるか、255 文字を超えています。 | ### イベント #### on\_datafile\_update() `Client.on_datafile_update` メソッドを使用すると、構成がデータを更新したときのイベントを処理できます。1 つの入力パラメーター **handler** を受け取ります。リアルタイム構成イベントを使用して構成が更新されたときに呼び出されるハンドラーです。 ```elixir theme={null} :ok = Kameleoon.Client.on_datafile_update(client, fn -> IO.puts("Kameleoon datafile updated") end) :ok = Kameleoon.Client.on_datafile_update(client, nil) ``` ##### 引数 | 名前 | 型 | 説明 | | ------- | ---------------------- | ---------------------------------------- | | handler | `(() -> any()) \| nil` | リアルタイム構成イベントを使用して構成が更新されたときに呼び出されるハンドラー。 | ### データ型 このセクションでは、`Kameleoon.Data` の下で利用可能な Elixir データ型を一覧表示します。 #### ApplicationVersion `ApplicationVersion` は、アプリケーションのセマンティックバージョン番号を表します。 **訪問者**は `ApplicationVersion` を 1 つしか持つことができません。2 番目のインスタンスを追加すると、最初のものが上書きされます。 | 名前 | 型 | 説明 | | -------------- | ------------ | ------------------------------------------------------------------------------------------------------------- | | version (*必須*) | `String.t()` | アプリケーションのバージョン。このフィールドは、セマンティックバージョニングに従う必要があります。受け入れられる形式は `major`、`major.minor`、または `major.minor.patch` です。 | ```elixir theme={null} alias Kameleoon.Client alias Kameleoon.Data.ApplicationVersion # major :ok = Client.add_data(client, visitor_code, ApplicationVersion.new!("10")) # major.minor :ok = Client.add_data(client, visitor_code, ApplicationVersion.new!("10.20")) # major.minor.patch :ok = Client.add_data(client, visitor_code, ApplicationVersion.new!("10.20.30")) ``` #### Browser ここに保存されている `Browser` データセットは、関連付けられた任意の値で実験およびパーソナライゼーションのレポートをフィルタリングするために使用できます。 | 名前 | 型 | 説明 | | ----------------- | ----------------- | -------------------------------------------------------------------------------- | | type (*必須*) | `atom()` | ブラウザのリスト: `:chrome`、`:internet_explorer`、`:firefox`、`:safari`、`:opera`、`:other`。 | | version (*オプション*) | `number() \| nil` | ブラウザのバージョン、浮動小数点数はブラウザのメジャーバージョンとマイナーバージョンを表します | ```elixir theme={null} alias Kameleoon.Client alias Kameleoon.Data.Browser # バージョン付きのブラウザデータ :ok = Client.add_data(client, visitor_code, Browser.new!(:safari, version: 26.4)) # バージョンなしのブラウザデータ :ok = Client.add_data(client, visitor_code, Browser.new!(:chrome)) ``` #### Conversion ここに保存されている `Conversion` データセットは、関連付けられた任意のゴールで実験およびパーソナライゼーションのレポートをフィルタリングするために使用できます。 * 各訪問者は複数の `Conversion` オブジェクトを持つことができます。 * `goal_id` は Kameleoon アプリで確認できます。 | 名前 | 型 | 説明 | デフォルト | | ------------------ | --------------------------------- | -------------- | ------- | | goal\_id (*必須*) | `non_neg_integer()` | ゴールの ID。 | | | revenue (*オプション*) | `number() \| nil` | 変換の収益。 | `nil` | | negative (*オプション*) | `boolean()` | 収益が正か負かを定義します。 | `false` | | metadata (*オプション*) | `[Kameleoon.Data.CustomData.t()]` | 変換のメタデータ。 | `[]` | ```elixir theme={null} alias Kameleoon.Client alias Kameleoon.Data.Conversion alias Kameleoon.Data.CustomData # ID 32 のシンプルな変換を追加します :ok = Client.add_data(client, visitor_code, Conversion.new!(32)) # 収益を含み、負としてマークされた ID 33 の変換を追加します :ok = Client.add_data(client, visitor_code, Conversion.new!(33, revenue: 10.0, negative: true)) # 収益、負フラグ、およびカスタムメタデータを含む ID 34 の変換を追加します :ok = Client.add_data( client, visitor_code, Conversion.new!(34, revenue: 10.0, negative: true, metadata: [ CustomData.new!(3, ["metadata1", "md2"]), CustomData.new!(5, ["md3"]) ] ) ) ``` #### Cookie `Cookie` には、訪問者のデバイスに保存されている Cookie に関する情報が含まれています。 | 名前 | 型 | 説明 | | ------- | ------------------------------- | ---------------------- | | cookies | `%\{String.t() => String.t()\}` | Cookie のキーと値を含む文字列マップ。 | 各訪問者は `Cookie` を 1 つしか持つことができません。2 番目の `Cookie` を追加すると、最初のものが上書きされます。 ```elixir theme={null} alias Kameleoon.Client alias Kameleoon.Data.Cookie :ok = Client.add_data(client, visitor_code, Cookie.new!(%{"segment" => "vip"})) ``` #### CustomData `CustomData` は、各訪問者と任意の種類のデータを関連付けることを可能にし、[セグメント](/user-manual/assets/segments/create-a-segment/)のターゲティング条件のための効果的なツールにします。さらに、実験レポートでフィルターまたはブレイクダウンとして使用できます。カスタムデータの詳細については、この[記事](/developer-docs/custom-data)を参照してください。 Kameleoon アプリまたは Data API でカスタムデータ型を定義し、SDK から使用します。 | 名前 | 型 | 説明 | デフォルト | | ------------------- | -------------------------------- | -------------------------------------------------------------------------------------------------------------------------- | ------ | | index/name (*必須*) | `non_neg_integer()`/`String.t()` | カスタムデータのインデックスまたは名前。データを識別するには **`index` または `name` のいずれかを指定する必要があります**。 | | | values (*必須*) | `[String.t()]` | 保存するカスタムデータの値。 | | | overwrite (*オプション*) | `boolean()` | 値の保存方法とレポートへの表示方法を明示的に制御するフラグ。[詳細](/developer-docs/custom-data#default-logic-when-overwrite-parameter-is-false-or-omitted) | `true` | * 各訪問者は、一意の `index`(`name`)ごとに `CustomData` を 1 つだけ持つことができます。同じ `index`(`name`)を持つ別の `CustomData` を追加すると、既存のものが置き換えられます。 * カスタムデータの「インデックス」は、[カスタムデータダッシュボード](/user-manual/assets/custom-data/manage-custom-data)の「INDEX」列で確認できます。 * プライバシー上の理由から、SDK が選択されたインデックスのデータを Kameleoon サーバーに送信しないようにするには、カスタムデータの作成時にオプション **このデータをターゲティング目的のみでローカルで使用する**を有効にします。 * SDK インスタンスが初期化されていないか、名前が登録されていないときに名前を使用して作成された `CustomData` インスタンスを追加すると、データが無視されます。 ```elixir theme={null} alias Kameleoon.Client alias Kameleoon.Data.CustomData :ok = Client.add_data(client, visitor_code, CustomData.new!(1, ["value"])) # 複数の値を使用 :ok = Client.add_data(client, visitor_code, CustomData.new!(1, ["value1", "value2"])) # `overwrite` フラグを false に設定する :ok = Client.add_data(client, visitor_code, CustomData.new!(1, ["value"], overwrite: false)) # インデックスの代わりに名前を使用する :ok = Client.add_data(client, visitor_code, CustomData.new_with_name!("my-custom-data", ["value"])) # インデックスの代わりに名前を使用し、`overwrite` フラグを false に設定する :ok = Client.add_data( client, visitor_code, CustomData.new_with_name!("my-custom-data", ["value"], overwrite: false) ) ``` #### Device デバイスデータを使用して、関連付けられた任意の値で実験およびパーソナライゼーションのレポートをフィルタリングできます。 | 名前 | 型 | 説明 | | | | ---- | -------- | ------- | ---------- | -------- | | type | \`:phone | :tablet | :desktop\` | デバイスタイプ。 | ```elixir theme={null} alias Kameleoon.Client alias Kameleoon.Data.Device :ok = Client.add_data(client, visitor_code, Device.new!(:desktop)) ``` #### Geolocation `Geolocation` には、訪問者の地理位置情報の詳細が含まれます。 | 名前 | 型 | 説明 | | ---------------------- | -------------------------------- | ---------------------------- | | country (*必須*) | `String.t()` | 訪問者の国。 | | region (*オプション*) | `String.t() \| nil` | 訪問者の地域。 | | city (*オプション*) | `String.t() \| nil` | 訪問者の市区町村。 | | postal\_code (*オプション*) | `String.t() \| nil` | 訪問者の郵便番号。 | | latitude (*オプション*) | `number() \| nil` | 訪問者の位置を表す緯度座標。座標数値は十進度を表します。 | | longitude (*オプション*) | `number() \| nil` | 訪問者の位置を表す経度座標。座標数値は十進度を表します。 | * 各訪問者は `Geolocation` を 1 つしか持つことができません。2 番目の `Geolocation` を追加すると、最初のものが上書きされます。 ```elixir theme={null} alias Kameleoon.Client alias Kameleoon.Data.Geolocation geolocation = Geolocation.new!("France", region: "Ile-de-France", city: "Paris", postal_code: "75009", latitude: 48.8720171, longitude: 2.3338352 ) :ok = Client.add_data(client, visitor_code, geolocation) ``` #### OperatingSystem `OperatingSystem` には、訪問者のデバイス上のオペレーティングシステムに関する情報が含まれます。 | 名前 | 型 | 説明 | | | | | | | ---- | ---------- | ---- | ---- | ------ | -------- | ----------------- | ------------------ | | type | \`:windows | :mac | :ios | :linux | :android | :windows\_phone\` | オペレーティングシステムファミリー。 | 各訪問者は `OperatingSystem` を 1 つしか持つことができません。2 番目の `OperatingSystem` を追加すると、最初のものが上書きされます。 ```elixir theme={null} alias Kameleoon.Client alias Kameleoon.Data.OperatingSystem :ok = Client.add_data(client, visitor_code, OperatingSystem.new!(:windows)) ``` #### PageView ページビューイベントを保存します。 | 名前 | 型 | 説明 | デフォルト | | | --------- | ------------- | ------------------------ | -------------- | ----- | | url | `String.t()` | 閲覧されたページの URL。 | | | | title | \`String.t() | nil\` | 閲覧されたページのタイトル。 | `nil` | | referrers | `[integer()]` | 以前に閲覧されたページのリファラーインデックス。 | `[]` | | リファラーインデックスは、Kameleoon アプリの[アクイジションチャネル構成](/user-manual/assets/advanced-targeting-tools/create-an-acquisition-channel)ページで確認できます。注意: インデックスは `0` から始まるため、最初に作成するアクイジションチャネルの ID は `1` ではなく `0` です。 ```elixir theme={null} alias Kameleoon.Client alias Kameleoon.Data.PageView # url、オプションのタイトル、およびリファラーを含む完全なコンストラクタ。 :ok = Client.add_data(client, visitor_code, PageView.new!("https://example.com", title: "Homepage", referrers: [3])) # URL のみを必要とする最小限のコンストラクタ。 :ok = Client.add_data(client, visitor_code, PageView.new!("https://example.com")) ``` #### UniqueIdentifier 訪問者に対して `UniqueIdentifier` を追加しない場合、`visitor_code` が一意の訪問者識別子として使用されます。これは[クロスデバイス実験](/developer-docs/cross-device-experimentation/)に便利です。`UniqueIdentifier(true)` を追加すると、SDK は指定された識別子に関連付けられた訪問者にフラッシュされたデータをリンクします。 これは、訪問者に元々割り当てられた匿名の `visitor_code` にアクセスできないものの、セッションマージを通じてその訪問者に接続されている内部識別子にアクセスできる状況で役立ちます。 | 名前 | 型 | 説明 | | ------- | ----------- | -------------------------------------- | | `value` | `boolean()` | 現在の `visitor_code` を一意の識別子として扱うべきかどうか。 | ```elixir theme={null} alias Kameleoon.Client alias Kameleoon.Data.UniqueIdentifier :ok = Client.add_data(client, visitor_code, UniqueIdentifier.new!(true)) ``` #### UserAgent サーバーサイドの実験は、クライアントサイドの実験よりもボットトラフィックの影響を受けやすくなります。Kameleoon は、IAB/ABC 国際スパイダーおよびボットリストを使用して既知のボットやスパイダーを認識し、`UserAgent` フィールドを使用して、変換指標を歪める可能性のあるその他の不要なトラフィックをフィルタリングします。詳細については、[ボットフィルタリング](/user-manual/faq#how-does-kameleoon-filter-bot-traffic-from-my-results)に関するヘルプ記事を参照してください。 内部ボットを使用している場合は、アナリティクスから除外するために、ユーザーエージェント値 `curl/8.0` を送信することをお勧めします。 | 名前 | 型 | 説明 | | ----- | ------------ | ---------------------------- | | value | `String.t()` | トラッキング要求と共に送信されるユーザーエージェント値。 | ```elixir theme={null} alias Kameleoon.Client alias Kameleoon.Data.UserAgent :ok = Client.add_data(client, visitor_code, UserAgent.new!("Mozilla/5.0")) ``` ### 戻り値の型 #### DataFile `DataFile` には SDK 設定の詳細が含まれます。 クライアントが必要とする場合は、追加情報で拡張できます。詳細が必要な場合は、カスタマーサクセスマネージャーにお問い合わせください。 | 名前 | 型 | 説明 | | -------------- | ---------------------------------------------------- | ------------------------------------------------------------ | | feature\_flags | `%\{String.t() => Kameleoon.Types.FeatureFlag.t()\}` | フィーチャーフラグのキーをキーとする [`FeatureFlag`](#featureflag) オブジェクトのマップ。 | | date\_modified | `non_neg_integer() \| nil` | `DataFile` が最後に変更された日時を示すタイムスタンプ(ミリ秒単位)。 | ```elixir theme={null} # DataFile からフィーチャーフラグのマップを取得します。 # マップはフィーチャーフラグ識別子をキーとし、各値は FeatureFlag 構造体です。 feature_flags = datafile.feature_flags # DataFile の最終変更タイムスタンプを取得します。 # 値は、Unix エポックからのミリ秒を表す整数です。 date_modified = datafile.date_modified ``` #### FeatureFlag `FeatureFlag` は、フィーチャーフラグそのものを定義する一連のプロパティを表します — たとえば、その [`Variations`](#variation)、[`Rules`](#rule)、環境ステータスなどの関連詳細です。 クライアントが必要とする場合は、追加情報で拡張できます。詳細が必要な場合は、カスタマーサクセスマネージャーにお問い合わせください。 | 名前 | 型 | 説明 | | ----------------------- | -------------------------------------------------- | ---------------------------------------- | | environment\_enabled | `boolean()` | フィーチャーフラグが現在の環境で有効かどうかを示します。 | | default\_variation\_key | `String.t()` | フィーチャーフラグに関連付けられたデフォルトのバリエーションのキー。 | | variations | `%\{String.t() => Kameleoon.Types.Variation.t()\}` | バリエーションのキーをキーとする `Variation` オブジェクトのマップ。 | | rules | `[Kameleoon.Types.Rule.t()]` | `Rule` オブジェクトのリスト | ```elixir theme={null} # フィーチャーフラグが現在の環境で有効になっているかどうかを確認します。 environment_enabled = feature_flag.environment_enabled # デフォルトバリエーションのキーを取得します。 default_variation_key = feature_flag.default_variation_key # デフォルトバリエーションの構造体を取得します。 default_variation = Kameleoon.Types.FeatureFlag.default_variation(feature_flag) # フィーチャーフラグのすべてのバリエーションをマップとして取得します(キー = バリエーションのキー、値 = Variation 構造体)。 variations = feature_flag.variations # フィーチャーフラグに関連付けられたすべてのターゲティングルールを取得します。 rules = feature_flag.rules ``` #### Rule `Rule` は、ルールそのものを定義する一連のプロパティを表します — たとえば、その [`Variations`](#variation) です。 クライアントが必要とする場合は、追加情報で拡張できます。詳細が必要な場合は、カスタマーサクセスマネージャーにお問い合わせください。 | 名前 | 型 | 説明 | | ---------- | -------------------------------------------------- | ---------------------------------------- | | variations | `%\{String.t() => Kameleoon.Types.Variation.t()\}` | バリエーションのキーをキーとする `Variation` オブジェクトのマップ。 | ```elixir theme={null} # ルールのすべてのバリエーションをマップとして取得します(キー = バリエーションのキー、値 = Variation 構造体)。 variations = rule.variations ``` #### Variation `Variation` には、訪問者に割り当てられたバリエーション、または特定の割り当てが存在しない場合のデフォルトバリエーションに関する情報が含まれます。 | 名前 | 型 | 説明 | | | -------------- | -------------------------------- | ----------------------------------------------------- | ------------------------------------------------ | | name | \`String.t() | nil\` | バリエーションの名前。 | | key | \`String.t() | nil\` | バリエーションを識別する一意のキー。 | | id | \`non\_neg\_integer() | nil\` | 割り当てられたバリエーションの ID、またはデフォルトバリエーションの場合は `nil`。 | | experiment\_id | \`non\_neg\_integer() | nil\` | バリエーションに関連付けられた実験の ID、またはデフォルトバリエーションの場合は `nil`。 | | variables | `[Kameleoon.Types.Variable.t()]` | バリエーションに関連付けられた変数。変数が添付されていない場合、このコレクションは空にすることができます。 | | * `Variation` は割り当てられたまたはデフォルトのバリエーションを記述し、[`Variable`](#variable) には各個別の変数の詳細が含まれます。 * `id` と `experiment_id` は `nil` になる可能性があり、これは特定の実験割り当てに紐づけられていないデフォルトバリエーションを示します。 追加のヘルパーメソッド: | メソッド | 戻り値の型 | 説明 | | ----------------------------------- | ----------- | ------------------------------- | | `Kameleoon.Types.Variation.active?` | `boolean()` | `off` バリエーションの場合 `false` を返します。 | ```elixir theme={null} # バリエーション名を取得します。 variation_name = variation.name # バリエーションキーを取得します。 variation_key = variation.key # バリエーション ID を取得します。 variation_id = variation.id # 実験 ID を取得します。 experiment_id = variation.experiment_id # 変数リストを取得します。 variables = variation.variables # バリエーションがアクティブかどうか(訪問者に現在配信されているかどうか)を確認します。 active? = Kameleoon.Types.Variation.active?(variation) # キーで変数を取得します。見つからない場合は nil を返します。 variable = Enum.find(variation.variables, &(&1.key == "title")) ``` #### Variable `Variable` には、割り当てられたバリエーションに関連付けられた変数に関する情報が含まれます。 | 名前 | 型 | 説明 | | | ----- | ------------------------------------- | ------------------------------------------------------------------- | ---------------------------------------------------------------------------- | | key | `String.t() \| nil` | 変数を識別する一意のキー。 | | | kind | `String.t() \| nil` | 変数の型。指定可能な値には、`BOOLEAN`、`NUMBER`、`STRING`、`JSON`、`JS`、`CSS` が含まれます。 | | | value | \`boolean() \| number() \| String.t() | nil\` | 変数の値。`kind` に応じて、ブール値、数値、文字列、JSON 文字列、JavaScript スニペット、または CSS スニペットを保持できます。 | ```elixir theme={null} # バリエーションに関連付けられた変数のリストを取得します。 variables = variation.variables # 条件付き処理のために変数の型(kind)にアクセスします。 kind = variable.kind # 値を数値として抽出します。 number = variable.value # 値をブール値として抽出します。 apply_discount? = variable.value # 値を文字列として抽出します。 title = variable.value ```