> ## 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.
# C# SDK
> Kameleoon C# SDK を統合して、.NET アプリケーションサーバー上でサーバーサイド実験を実行し、機能フラグを有効化します。
Kameleoon C# SDK の開発者ドキュメントへようこそ! 当社の SDK を使用して、バックエンドの .NET アプリケーションサーバー上で実験を実行できます。SDK は Web アプリケーションへの統合が容易で、メモリおよびネットワーク使用量が少なく抑えられています。
**はじめに**: 開始にあたっては、[開発者ガイド](#開発者ガイド) を参照してください。
**SDK メソッド**: C# SDK メソッドの完全なリファレンスドキュメントについては、[リファレンス](#リファレンス) セクションを参照してください。
**変更履歴**: C# SDK の最新バージョン: 4.22.0 [変更履歴](https://github.com/Kameleoon/client-csharp/blob/master/CHANGELOG.md)。
## 開発者ガイド
### はじめに
このガイドは、当社の SDK を C# アプリケーションに統合するのに役立つように設計されています。
#### スターターキット
開始にあたっての支援として、Kameleoon は SDK をテストするためのスターターキットとデモアプリケーションを提供しています。スターターキットには、SDK メソッドをアプリでどのように使用できるかを示す例を含む、完全に構成されたアプリが含まれています。スターターキット、デモアプリケーション、および詳細な手順は、[.NET 用スターターキット](https://github.com/Kameleoon/dotnet-examples) で入手できます。
#### C# クライアントのインストール
NuGet、.NET CLI、または Paket パッケージマネージャーを使用して C# クライアントをインストールできます。
```sh theme={null}
Install-Package KameleoonClient
```
```sh theme={null}
dotnet add package KameleoonClient
```
```sh theme={null}
paket add KameleoonClient
```
#### 追加の構成
認証情報を提供し、SDK の動作をカスタマイズするための `.properties` 構成ファイルを作成します。[サンプル構成ファイル](/assets/developer-docs/sdks/web-sdks/client-configs/client-csharp.conf) をダウンロードすることもできます。このファイルをデフォルトのパス `/etc/kameleoon/client-csharp.conf` に保存します。ファイルを別の場所に配置する場合は、`KameleoonClientFactory.Create()` の引数としてパスを渡す必要があります。現在のバージョンの C# SDK で使用可能なキーは以下のとおりです:
| キー | 説明 | デフォルト値 |
| -------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------ |
| `clientId` / `client_id` (*必須*) | Kameleoon サービスへの認証に必要です。`client_id` を確認するには、[API 認証情報](/user-manual/account-and-team-management/users-and-teams/api-credentials) のドキュメントを参照してください。 | |
| `clientSecret` / `client_secret` (*必須*) | Kameleoon サービスへの認証に必要です。`client_secret` を確認するには、[API 認証情報](/user-manual/account-and-team-management/users-and-teams/api-credentials) のドキュメントを参照してください。 | |
| `sessionDurationMinute` / `session_duration_minute` (*オプション*) | Kameleoon が訪問者とそれに関連するデータをメモリ (RAM) に保持する事前定義された時間間隔を指定します。セッション継続時間を長くすると、訪問者データを保持するために割り当てる必要のある RAM 量が増加することに注意してください。 | `30` 分 |
| `refreshIntervalMinute` / `refresh_interval_minute` (*オプション*) | SDK がアクティブな実験と機能フラグの構成を取得する更新間隔を分単位で指定します。この値により、機能フラグの有効化/無効化や実験の開始などの変更が本番サーバーに反映されるまでの最大時間が決まります。さらに、当社では、サーバー送信イベント (SSE) を使用して新しい構成を SDK に自動的にプッシュし、遅延なくリアルタイムで新しい構成を適用する [ストリーミングモード](/developer-docs/feature-experimentation/technical-reference/technical-considerations/#streaming-premium-option) を提供しています。 | `60` 分 |
| `defaultTimeoutMillisecond` / `default_timeout_millisecond` (*オプション*) | SDK からのネットワークリクエストのタイムアウトをミリ秒単位で指定します。安定した接続がない場合は、値を 30 秒以上に設定します。一部のメソッドには、その特定のメソッドのデフォルトタイムアウトを上書きするために使用できる追加のパラメータがあります。メソッドに対してタイムアウトを明示的に指定しない場合、SDK はこのデフォルト値を使用します。 | `10000` ミリ秒 |
| `trackingIntervalMilliseconds` / `tracking_interval_millisecond` (*オプション*) | トラッキングリクエストの間隔をミリ秒単位で指定します。任意の機能フラグについて Kameleoon が評価した訪問者、またはデータがフラッシュされた訪問者はすべて、このトラッキングリクエストに含まれます。SDK は、間隔ごとに 1 回このリクエストを実行します。最小値は `1000` ms (デフォルトでもあります)、最大値は `5000` ms です。 | `1000` ミリ秒 |
| `environment` / `environment` (*オプション*) | 機能フラグの構成を使用する環境です。値は `production`、`staging`、`development` のいずれかです。詳細については、[環境の管理](/user-manual/experimentation/feature-experimentation/configure-your-feature-flags/manage-environments) の記事を参照してください。 | `production` |
| `topLevelDomain` / `top_level_domain` *(ハイブリッドモードでは必須)* | Web サイトの現在のトップレベルドメインです。`example.com` の形式を使用します。`https://`、`www`、その他のサブドメインは含めないでください。Kameleoon はこの情報を使用して、トップレベルドメインに対応する Cookie を設定します。 | `null` |
| `proxyHost` / `proxy_host` (*オプション*) | SDK が行うすべての送信サーバー呼び出しのプロキシホストを設定します。 | `null` |
| `networkDomain` / `network_domain` (*オプション*) | SDK が送信リクエストに使用するカスタムドメインで、しばしばプロキシ用です。有効なドメイン (例: example.com または sub.example.com) である必要があります。無効な形式の場合は Kameleoon のデフォルト値が使用されます。 | `null` |
#### Kameleoon クライアントの初期化
SDK をインストールし、認証情報および SDK の動作を構成したら、アプリケーションコード内で Kameleoon クライアントを作成します。例:
```csharp theme={null}
using Kameleoon;
string siteCode = "a8st4f59bj";
try {
// Read from default configuration path: "/etc/kameleoon/client-csharp.conf"
IKameleoonClient kameleoonClient = KameleoonClientFactory.Create(siteCode);
} catch (KameleoonException.SiteCodeIsEmpty e) {
// indicates that provided site code is empty
} catch (KameleoonException.ConfigCredentialsInvalid exception) {
// indicates that provided clientId / clientSecret are not valid
}
try {
IKameleoonClient kameleoonClient = KameleoonClientFactory.Create(siteCode, "custom/file/path/client-csharp.conf");
} catch (KameleoonException.SiteCodeIsEmpty e) {
// indicates that provided site code is empty
} catch (KameleoonException.ConfigCredentialsInvalid exception) {
// indicates that provided clientId / clientSecret are not valid
}
try {
KameleoonClientConfig config = new KameleoonClientConfig(
clientId: "", // mandatory
clientSecret: "", // mandatory
refreshIntervalMinute: 60, // in minutes, optional (60 minutes by default)
sessionDurationMinute: 30, // in minutes, optional (30 minutes by default)
defaultTimeoutMillisecond: 10_000, // in milliseconds, optional (10000 ms by default)
trackingIntervalMilliseconds: 1000, // in milliseconds, optional (1000 ms by default)
environment: "development", // optional
topLevelDomain: "example.com", // mandatory if you use hybrid mode (engine or web experiments)
proxyHost: "proxy.host.com", // optional
networkDomain: "example.com", // optional
);
IKameleoonClient kameleoonClient = KameleoonClientFactory.Create(siteCode, config);
} catch (KameleoonException.SiteCodeIsEmpty e) {
// indicates that provided site code is empty
} catch (KameleoonException.ConfigCredentialsInvalid exception) {
// indicates that provided clientId / clientSecret are not valid
}
```
`IKameleoonClient` は、アプリを Kameleoon プラットフォームに接続するシングルトンオブジェクトです。実験の実行に必要なすべてのメソッドと機能が含まれています。
開発者として、Kameleoon での A/B テストにアプリが正しいロジックを使用していることを確認する必要があります。実験をまだ開始していない場合は、訪問者を実験から除外することがベストです。これはバリエーションのデフォルトロジックに適合するため、除外は簡単です。
#### 機能フラグの有効化
##### ユーザーへの一意の ID の割り当て
ユーザーに一意の ID を割り当てるには、[`GetVisitorCode()`](#getvisitorcode) メソッドを使用できます。**訪問者コード** が存在しない場合 (リクエストヘッダー Cookie から)、このメソッドはランダムな一意の ID を生成するか、生成済みの `defaultVisitorCode` を使用します。次に、ID はレスポンスヘッダー Cookie に設定されます。
Kameleoon を [ハイブリッドモード](/developer-docs/feature-experimentation/get-started/hybrid-experimentation) で使用している場合、`GetVisitorCode()` メソッドを呼び出すことで、一意の ID (**訪問者コード**) がアプリケーションファイル `engine.js` (以前は `kameleoon.js` と呼ばれていました) と SDK の間で共有されます。
##### フラグ構成の取得
コードに機能フラグを実装するには、まず Kameleoon アカウントで機能フラグを作成する必要があります。
特定のユーザーに対する機能フラグのステータスまたはバリエーションを判別するには、`featureKey` に基づいて構成を取得するために [`GetVariation()`](#getvariation) または [`IsFeatureActive()`](#isfeatureactive) メソッドを使用する必要があります。
`GetVariation()` メソッドは、ON/OFF 状態を持つ単純な機能フラグと、複数のバリエーションを持つより複雑なフラグの両方を処理します。このメソッドは、機能ルールをチェックし、バリエーションを割り当て、`featureKey` と `visitorCode` に基づいてバリエーションを返すことで、ユーザーに適切なバリエーションを取得します。
`IsFeatureActive()` メソッドは、複数のバリエーションやターゲティングオプションを持つより複雑な機能フラグではなく、ON または OFF の状態のみを持つ単純な機能フラグの構成を取得したい場合に使用できます。
機能フラグに関連付けられた変数 (各バリエーションに関連付けられた特定の動作など) がある場合、`GetVariation()` を使用して [`Variation`](#variation) オブジェクトにアクセスすることもできます。このオブジェクトは、割り当てられたバリエーションとそれに関連する実験の詳細を提供します。このメソッドは、ユーザーがターゲットになっているかどうかを確認し、訪問者に割り当てられたバリエーションを見つけ、ストレージに保存します。`track=true` の場合、SDK は次のトラッキングリクエストで指定された実験への露出イベントを送信します。これは SDK の [`tracking_interval_millisecond`](#追加の構成) に基づいて自動的にトリガーされます。デフォルトでは、この間隔は 1000 ミリ秒 (1 秒) に設定されています。
`GetVariation()` メソッドを使用すると、トラッキングを行うかどうかを制御できます。`track=false` の場合、SDK によって露出イベントは送信されません。これは、SDK を介してデータを追跡せず、Kameleoon エンジンによって管理されるクライアントサイドのトラッキングに依存することを希望する場合に便利です。さらに、`track=false` の設定は、`GetVariations()` メソッドを使用する場合に役立ちます。すべてのフラグのバリエーションのみが必要で、トラッキングイベントをトリガーする必要がない場合などです。トラッキングの仕組みの詳細については、[こちらの記事](/developer-docs/feature-experimentation/technical-reference/faq-global#when-does-the-sdk-send-a-tracking-request-for-analytics) をご覧ください。
##### ユーザーをターゲットにしたり、レポート内で訪問をフィルタリング/分類するためのデータポイントの追加
ユーザーをターゲットにするには、機能バリエーションを取得したり、フラグがアクティブかどうかを確認したりする前に、関連するデータポイントをそのプロファイルに追加していることを確認してください。これらのデータポイントをユーザーのプロファイルに追加するには [`AddData()`](#adddata) メソッドを使用します。
他のデバイスで収集されたデータポイントを取得したり、過去のユーザーデータ (Kameleoon をハイブリッドモードで使用する際にクライアントサイドで収集されたデータ) にアクセスするには、[`GetRemoteVisitorData()`](#getremotevisitordata) メソッドを使用します。このメソッドはサーバーから非同期にデータを取得します。このデータは、ユーザーを特定のバリエーションに割り当てるために必要になる可能性があるため、バリエーションを取得したり、機能フラグがアクティブかどうかを確認する *前に* `GetRemoteVisitorData()` を呼び出すことが重要です。
利用可能なターゲティング条件の詳細については、[このトピックに関する詳細な記事](/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) データ型を使用してボットをフィルタリングすることをお勧めします。
##### ゴールコンバージョンのトラッキング
ユーザーが目的のアクション (購入など) を完了すると、コンバージョンとして記録されます。コンバージョンを追跡するには、[`TrackConversion()`](#trackconversion) メソッドを使用し、必須の `visitorCode` および `goalId` パラメータを提供します。
コンバージョントラッキングリクエストは、SDK が定期的な間隔 ([`tracking_interval_millisecond`](#追加の構成) で定義) で送信する次の予定トラッキングリクエストとともに送信されます。すぐにリクエストを送信したい場合は、`instant=true` パラメータを使用して [`Flush()`](#flush) メソッドを使用してください。
##### 分析ソリューションへのイベントの送信
コンバージョンを追跡し、露出イベントを顧客分析ソリューションに送信するには、まず Kameleoon を [ハイブリッドモード](/developer-docs/feature-experimentation/get-started/hybrid-experimentation/) で実装する必要があります。次に、[`GetEngineTrackingCode()`](#getenginetrackingcode) メソッドを使用します。
`GetEngineTrackingCode()` メソッドは、分析ソリューションに露出イベントを送信するために必要な一意のトラッキングコードを取得します。このメソッドを使用すると、イベントを記録して目的の分析プラットフォームに送信できます。
### クロスデバイス実験
複数のデバイスからアプリにアクセスする訪問者をサポートするために、Kameleoon は以前に収集された訪問者データを訪問者の各デバイス間で同期し、クロスデバイス実験を通じてデバイス間で訪問履歴を統合することを可能にします。Kameleoon がデバイス間でデータをどのように処理するかについてのケーススタディと詳細情報は、[クロスデバイス実験に関する記事](/developer-docs/cross-device-experimentation) で利用できます。
#### デバイス間でのカスタムデータの同期
カスタムマッピング同期は、デバイス間で訪問者データを統合するために使用されますが、常に必要というわけではありません。以下は、カスタムマッピング同期が不要な 2 つのシナリオです:
**デバイス間で同じユーザー ID**
すべてのデバイスで同じユーザー ID が一貫して使用されている場合、カスタムマッピング同期なしで同期が自動的に処理されます。複数のデバイス間で収集されたデータを同期したい場合は、`GetRemoteVisitorData()` メソッドを呼び出すだけで十分です。
**一貫した ID を持つマルチサーバーインスタンス**
複数のサーバーが関係する複雑な設定 (例えば、分散型サーバーインスタンス) において、同じユーザー ID がサーバー間で利用可能な場合、追加のカスタムマッピング同期なしで、サーバー間の同期 (`GetRemoteVisitorData()` 経由) で十分です。
追加のデータを必要とする顧客は、さらなるガイダンスのために [`GetRemoteVisitorData()`](#getremotevisitordata) メソッドの説明を参照できます。以下のコードでは、2 つのデバイス間で同じ一意の識別子 (この場合は `visitorCode`、`userId` とも呼ばれます) が正確なデータ取得のために一貫して使用されていることが想定されています。
収集されたデータをリアルタイムで同期したい場合は、カスタムデータのスコープとして **Visitor** を選択する必要があります。
```csharp title="Device A" theme={null}
// In this example Custom data with index `90` was set to "Visitor" scope on Kameleoon Platform.
const int VisitorScopeCustomDataIndex = 90;
kameleoonClient.AddData(visitorCode, new CustomData(VisitorScopeCustomDataIndex, "your data"));
kameleoonClient.Flush(visitorCode);
```
```csharp title="Device B" theme={null}
// Before working with the data, call the `GetRemoteVisitorData` method.
await kameleoonClient.GetRemoteVisitorData(visitorCode);
// After calling the method, the SDK on Device B will have access to CustomData of Visitor scope as defined on Device A.
// So, "your data" will be available for targeting and tracking the visitor.
```
#### セッションマージのためのカスタムデータの使用
[クロスデバイス実験](/developer-docs/cross-device-experimentation) では、訪問者の履歴を各デバイス間で結合することができます (履歴の調整)。履歴の調整により、異なる訪問者のセッションを 1 つにマージできます。訪問履歴を調整するには、訪問者の一意の識別子を提供するために [`CustomData`](#customdata) を使用します。詳細については、[専用ドキュメント](/developer-docs/cross-device-experimentation/#activating-cross-device-history-reconciliation) を参照してください。
クロスデバイスの調整を有効にした後、`userId` パラメータを使用して [`GetRemoteVisitorData()`](#getremotevisitordata) を呼び出すと、特定のユーザーのすべての既知のデータを取得できます。
同じ識別子を持つセッションは、実験で常に同じバリエーションが表示されます。実験結果ページの訪問者ビューでは、これらのセッションは 1 人の訪問者として表示されます。
SDK 構成により、関連するセッションは常に実験の同じバリエーションを見ることが保証されます。ただし、クロスデバイスのバリエーション割り当てに関するいくつかの制限があります。これらの制限は [こちら](/developer-docs/cross-device-experimentation#critical-points-and-practical-insights) に概説されています。
[クロスデバイス履歴の調整の有効化](#クロスデバイス実験) ガイドに従って、Kameleoon プラットフォームでカスタムデータを設定してください。
その後、SDK を通常どおり使用できます。セッションマージのコンテキストで役立つ可能性のあるメソッドは次のとおりです:
* `UniqueIdentifier(true)` を追加した `GetRemoteVisitorData()` - すべてのリンクされた訪問者のデータを取得します。
* `UniqueIdentifier(true)` データを追加した [`TrackConversion()`](#trackconversion) または [`Flush()`](#flush) - 別の訪問者に関連付けられている特定の訪問者のいくつかのデータを追跡します。
識別子として使用するカスタムデータは **訪問者スコープ** に設定する必要があるため、各デバイスの [`GetRemoteVisitorData()`](#getremotevisitordata) メソッドで識別子を取得するには、[クロスデバイスカスタムデータ同期](/developer-docs/cross-device-experimentation) を使用する必要があります。
セッションマージのためのカスタムデータの使用方法の例を以下に示します。
```csharp theme={null}
// In this example, `91` represents the index of the Custom Data
// configured as a unique identifier in Kameleoon.
const int MappingIndex = 91;
const string FeatureKey = "ff123";
// 1. Before the visitor is authenticated
// Retrieve the variation for an unauthenticated visitor.
// Assume `anonymousVisitorCode` is the randomly generated ID for that visitor.
Variation anonymousVariation = kameleoonClient.GetVariation(anonymousVisitorCode, FeatureKey);
// 2. After the visitor is authenticated
// Assume `userId` is the visitor code of the authenticated visitor.
kameleoonClient.AddData(anonymousVisitorCode, new CustomData(MappingIndex, userId));
kameleoonClient.Flush(anonymousVisitorCode, instant=true);
// Indicate that `userId` is a unique identifier.
kameleoonClient.AddData(userId, new UniqueIdentifier(true));
// 3. After the visitor has been authenticated
// Retrieve the variation for the `userId`, which will match the anonymous visitor code's variation.
Variation userVariation = kameleoonClient.GetVariation(userId, FeatureKey);
bool isSameVariation = userVariation.Key == anonymousVariation.Key; // true
// The `userId` and `anonymousVisitorCode` are now linked and tracked as a single visitor.
kameleoonClient.TrackConversion(userId, 123, 10.0);
// Additionally, the linked visitors will share all fetched remote visitor data.
await kameleoonClient.GetRemoteVisitorData(userId);
```
この例では、アプリケーションにはログインページがあります。ログイン時点ではユーザー ID が不明なので、[`GetVisitorCode()`](#getvisitorcode) メソッドによって生成された匿名の訪問者識別子が使用されます。ユーザーがログインした後、匿名訪問者はユーザー ID に関連付けられ、訪問者の一意の識別子として使用されます。
### カスタムバケットキーの使用
デフォルトでは、Kameleoon は一意の匿名訪問者 ID (`visitorCode`) を使用して、ユーザーを機能フラグのバリエーションに割り当てます。この ID は通常、ユーザーのデバイス上で生成および保存されます (クライアントサイドおよびサーバーサイド SDK ではブラウザの Cookie に、モバイル SDK では永続的なストレージに)。ただし、特定のシナリオでは、同じ組織のすべてのユーザーが機能フラグの同じバリアントを見るようにする必要がある場合があります。
**カスタムバケットキー** オプションを使用すると、バケッティング用の独自のカスタム識別子を提供することで、このデフォルト動作を上書きできます。この上書きにより、Kameleoon の割り当てロジックがデフォルトの `visitorCode` の代わりに指定したキーを使用するようになります。
#### ユースケース
カスタムバケットキーの使用は、特に次の状況で、機能フラグの割り当ての一貫性と正確性を維持するために重要です:
* **アカウントレベルまたは組織の実験:** B2B 製品や、同じ組織のすべてのユーザーを同じバリエーションに割り当てたいシナリオでは、`accountId` のような識別子を使用できます。カスタムバケットキーは、チームや会社全体に影響を与える機能の A/B テストに重要です。
カスタムバケットキーを実装することにより、実験の一貫性と正確性が向上し、より信頼性の高い結果とより良いユーザーエクスペリエンスが得られます。
#### 技術的な詳細
機能フラグにカスタムバケットキーを設定する際、アプリケーションのデータから特定の識別子を Kameleoon に提供します:
```csharp theme={null}
kameleoonClient.AddData(visitorCode, new CustomData(index, "newVisitorCode"));
```
* **カスタムキーの提供:** [`AddData()`](#adddata) メソッドを使用して、カスタム識別子を Kameleoon SDK に提供します。このメソッドでは、選択したカスタムバケットキーを [`CustomData`](#customdata) オブジェクトとして渡します。ここで `newVisitorCode` は、バケッティングに使用したい識別子 (例えば、新しい `userId` または `accountId`) を指します。
カスタムバケットキーが正しく機能するためには、フラグの作成または編集プロセス中に機能フラグに対しても定義および構成する必要があります。対応する構成がない場合、SDK のバケッティングはカスタムキーを適用しません。Kameleoon でこれを設定する方法の詳細については、この [記事](/user-manual/experimentation/feature-experimentation/create-and-manage-flags/create-a-feature-flag#Advanced_Flag_Settings) を参照してください。
* **バケッティングロジック:** カスタムバケットキーが `AddData()` メソッドを介して提供されると、ユーザーをバリエーションに割り当てるためのすべてのハッシュ計算で、デフォルトの `visitorCode` の代わりにこの `newVisitorCode` (カスタムキー) が使用されます。`newVisitorCode` を使用すると、バケッティングの決定がカスタム識別子に関連付けられ、その識別子が存在するさまざまなコンテキストにわたって一貫した割り当てが保証されます。
* **データトラッキングと分析:** `newVisitorCode` (カスタムキー) はバケッティングの決定に使用されますが、**後続のすべてのデータ (例えば、トラッキングイベントとコンバージョン) は送信され、*元の* `visitorCode` に関連付けられる** ことに注意することが重要です。この分離により、バケッティングがより高いレベル (アカウントなど) で、または複数のデバイス/セッションにまたがって実行された場合でも、分析が実験の広範なコンテキスト内で個々のユーザージャーニーとインタラクションを正確に反映することが保証されます。元の訪問者データは包括的なレポートのためにそのまま残ります。
#### 技術要件
カスタムバケットキーを効果的に使用するには:
* キーは `string` でなければなりません。
* バケッティングしようとするエンティティに対して一意でなければなりません (例えば、`userId` を使用する場合、各ユーザーの ID は一意である必要があります)。
* キーは、そのユーザーまたはリクエストに対して機能フラグの決定が評価されるまさにその瞬間に SDK が利用できる必要があります。
### ターゲティング条件
Kameleoon SDK は、キャンペーンでユーザーをターゲットにするために使用できるさまざまな事前定義されたターゲティング条件をサポートしています。この SDK がサポートする条件のリストについては、[訪問履歴を使用してユーザーをターゲットにする](/developer-docs/feature-experimentation/targeting-and-segmentation/native-segmentation) を参照してください。
[ユーザーをターゲットにするための外部データ](/developer-docs/apis/data-api-rest/tutorials/storing-and-retrieving-external-data-to-target-users) を使用することもできます。
### ロギング
SDK はさまざまな内部プロセスや問題を反映するためにログを生成します。
#### ログレベル
SDK はログレベルによるロギング制限の構成をサポートしています。
```csharp theme={null}
// The `None` log level does not allow logging.
Kameleoon.Logging.KameleoonLogger.LogLevel = Kameleoon.Logging.LogLevel.None;
// The `Error` log level only allows logging issues that may affect the SDK's primary behavior.
Kameleoon.Logging.KameleoonLogger.LogLevel = 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.LogLevel = 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.LogLevel = 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.LogLevel = Kameleoon.Logging.LogLevel.Debug;
```
#### ログのカスタム処理
SDK はデフォルトではログをコンソール出力に書き込みます。この動作はオーバーライドできます。
ログレベルによるロギング制限はログ処理ロジックとは別に実行されます。
```csharp theme={null}
class CustomLogger : Kameleoon.Logging.ILogger
{
private readonly Microsoft.Extensions.Logging.ILogger inner;
public CustomLogger(Microsoft.Extensions.Logging.ILogger inner)
{
this.inner = inner;
}
// `Log` method accepts logs from the SDK
public void Log(Kameleoon.Logging.LogLevel level, string message)
{
// Custom log handling logic here. For example:
switch (level)
{
case Kameleoon.Logging.LogLevel.Error:
Microsoft.Extensions.Logging.LoggerExtensions.LogError(inner, message);
break;
case Kameleoon.Logging.LogLevel.Warning:
Microsoft.Extensions.Logging.LoggerExtensions.LogWarning(inner, message);
break;
case Kameleoon.Logging.LogLevel.Info:
Microsoft.Extensions.Logging.LoggerExtensions.LogInformation(inner, message);
break;
case Kameleoon.Logging.LogLevel.Debug:
Microsoft.Extensions.Logging.LoggerExtensions.LogDebug(inner, message);
break;
}
}
}
// Log level filtering is applied separately from log handling logic.
// The custom logger will only accept logs that meet or exceed the specified log level.
// Ensure the log level is set correctly.
Kameleoon.Logging.KameleoonLogger.LogLevel = Kameleoon.Logging.LogLevel.Debug; // Optional; defaults to `LogLevel.Warning`.
Kameleoon.Logging.KameleoonLogger.Logger = new CustomLogger();
```
## リファレンス
これは C# SDK の完全なリファレンスドキュメントです。
### 初期化
#### Create()
SDK の使用を開始するには、初期化する必要があります。アプリは `Kameleoon.IKameleoonClient` にある `KameleoonClient` クラスを介して SDK と対話します。このオブジェクトは、静的メソッド **Kameleoon.KameleoonClientFactory** `Create()` を使用して作成できます。
```csharp theme={null}
using Kameleoon;
string siteCode = "a8st4f59bj";
try {
// Read from default configuration path: "/etc/kameleoon/client-csharp.conf"
IKameleoonClient kameleoonClient = KameleoonClientFactory.Create(siteCode);
} catch (KameleoonException.SiteCodeIsEmpty e) {
// indicates that provided site code is empty
} catch (KameleoonException.ConfigCredentialsInvalid exception) {
// indicates that provided clientId / clientSecret are not valid
}
try {
IKameleoonClient kameleoonClient = KameleoonClientFactory.Create(siteCode, "custom/file/path/client-csharp.conf");
} catch (KameleoonException.SiteCodeIsEmpty e) {
// indicates that provided site code is empty
} catch (KameleoonException.ConfigCredentialsInvalid exception) {
// indicates that provided clientId / clientSecret are not valid
}
try {
KameleoonClientConfig config = new KameleoonClientConfig(
clientId: "", // mandatory
clientSecret: "", // mandatory
refreshIntervalMinute: 60, // in minutes, optional (60 minutes by default)
sessionDurationMinute: 30, // in minutes, optional (30 minutes by default)
defaultTimeoutMillisecond: 10_000, // in milliseconds, optional (10000 ms by default)
trackingIntervalMilliseconds: 1000, // in milliseconds, optional (1000 ms by default)
environment: "development", // optional
topLevelDomain: "example.com", // mandatory if you use hybrid mode (engine or web experiments)
proxyHost: "proxy.host.com" // optional
networkDomain: "example.com", // optional
);
IKameleoonClient kameleoonClient = KameleoonClientFactory.Create(siteCode, config);
} catch (KameleoonException.SiteCodeIsEmpty e) {
// indicates that provided site code is empty
} catch (KameleoonException.ConfigCredentialsInvalid exception) {
// indicates that provided clientId / clientSecret are not valid
}
```
##### 引数
| 名前 | 型 | 説明 | デフォルト |
| ------------------------------- | ----------------------- | ----------------------------------------------------------------------------------------- | ----------------------------------- |
| siteCode (*必須*) | `string` | これは SDK で使用している Kameleoon プロジェクトの [一意のキー](/user-manual/faq#how-do-i-find-my-sitecode) です。 | |
| configurationFilePath (*オプション*) | `string` | SDK 構成ファイルへのパスです。 | `/etc/kameleoon/client-csharp.conf` |
| kameleoonConfig (*オプション*) | `KameleoonClientConfig` | 構成ファイルを使用する代わりに渡すことができる構成 SDK オブジェクトです。 | `null` |
##### 戻り値
| 型 | 説明 |
| ------------------ | ------------------------------------------------------- |
| `IKameleoonClient` | **KameleoonClient** クラスのインスタンスで、実験と機能フラグを管理するために使用されます。 |
##### スローされる例外
| 型 | 説明 |
| --------------------------------------------- | ----------------------------------------------- |
| `KameleoonException.ConfigCredentialsInvalid` | 要求された認証情報が構成ファイルまたはメソッドの引数として提供されなかったことを示す例外です。 |
| `KameleoonException.SiteCodeIsEmpty` | 指定されたサイトコードが空文字列で、無効な値であることを示す例外です。 |
#### WaitInit()
`WaitInit()` は Kameleoon クライアントの初期化を待機します。このメソッドにより、他の操作に進む前にクライアントが正常に初期化されたことを確認できます。
```csharp theme={null}
using static Kameleoon;
try {
await kameleoonClient.WaitInit();
} catch (Exception exception) {
// indicates that client could not be initialized due to the thrown exception.
}
```
##### 戻り値
| 型 | 説明 |
| ---- | ---------------------------- |
| Task | クライアントが正常に初期化されると、タスクが完了します。 |
##### スローされる例外
| 型 | 説明 |
| --------- | -------------------------------------- |
| Exception | クライアントが正しく初期化されておらず、まだ使用できないことを示す例外です。 |
### 機能フラグとバリエーション
#### IsFeatureActive()
* 📨 *Kameleoon にトラッキングデータを送信します (`track` パラメータに依存)*
このメソッドは以前 `ActivateFeature` と呼ばれていましたが、SDK バージョン `4.0.0` で削除されました。
機能トグルを有効化するには、`IsFeatureActive` メソッドを呼び出します。
このメソッドは、ユーザーが特定の機能にアクセスできるかどうかを確認するために、**visitorCode** と **featureKey** (または **featureID**) を必要とします。
ユーザーがこの機能にリンクされたことがない場合、SDK はそれを有効化するかどうかをランダムに決定し、**true** (ユーザーは機能にアクセスできます) または **false** (ユーザーはアクセスできません) のいずれかを返します。指定された **visitorCode** を持つユーザーが既にこの機能にリンクされている場合、システムは **featureFlag** の以前の値を返します。
潜在的なエラーをキャッチするために、例に示されているように、コードに適切なエラー処理を含めるようにしてください。
`visitorCode` を指定すると、`IsFeatureActive()` メソッドはそれを一意の訪問者識別子として使用します。これは [クロスデバイス実験](/developer-docs/cross-device-experimentation) に役立ちます。`visitorCode` を指定し、`isUniqueIdentifier` パラメータを `true` に設定すると、SDK は指定された識別子に関連付けられた訪問者とフラッシュされたデータをリンクします。
パラメータ `isUniqueIdentifier` は非推奨です。代わりに [`UniqueIdentifier`](#uniqueidentifier) を使用してください。
`isUniqueIdentifier` は、特殊な状況で役立ちます。例えば、訪問者に付与された匿名の `visitorCode` にアクセスできないが、セッションマージを通じてその訪問者にリンクされた内部 ID を使用できる場合などです。
Kameleoon は、`IsFeatureActive()`、`GetVariation()`、`GetVariations()` などの特定のメソッドを呼び出すときに、トラッキングを使用してセッションと訪問者をカウントします。
訪問者をバリエーションに公開し、それらをカウントする必要があるときは、`track` パラメータにデフォルトの `true` 値を使用します。訪問者を公開する前にこれらのメソッドを呼び出す場合のみ、`track` パラメータを `false` に設定してください。
例えば、訪問者を公開する前にすべてのバリエーションを取得するために `GetVariations()` を呼び出す場合は、`track` パラメータを `false` に設定します。この設定により、Kameleoon がセッションを早期にカウントするのを防ぎます。その後、訪問者を明示的に公開するときにトラッキングを後でトリガーできます。
Kameleoon はデフォルトで 1 秒ごとにトラッキングデータを送信します。トラッキング間隔の構成オプションを使用して、この間隔を最大 5 秒まで構成できます。Kameleoon は、イベント間の間隔が 30 分未満である限り、トラッキングイベントを 1 つのセッションにグループ化します。トラッキングイベント間で 30 分を超える時間が経過すると、Kameleoon はイベントを別個のセッションとしてカウントします。訪問は、セッションで最後に記録されたイベントから 30 分後にレポートに表示されます。
```csharp theme={null}
string visitorCode = kameleoonClient.GetVisitorCode(Request, Response, "example.com");
string featureKey = "new_checkout";
bool hasNewCheckout = false;
try {
hasNewCheckout = kameleoonClient.IsFeatureActive(visitorCode, featureKey);
// disabling tracking
hasNewCheckout = kameleoonClient.IsFeatureActive(visitorCode, featureKey, track: false);
}
catch (KameleoonException.FeatureNotFound e) {
// Feature toggle not yet activated on Kameleoon's side - we consider the feature inactive.
hasNewCheckout = false;
}
catch (Exception e) {
// This is a generic Exception handler which will handle all exceptions.
Console.WriteLine("Exception occured");
}
if (hasNewCheckout)
{
// Implement new checkout code here.
}
```
`IsFeatureActive()` メソッドは、マスターフラグの状態ではなく、提供されたバリアントを評価します。ルールを除外すると、メソッドは **その後、他のすべての人には次を提供する** デフォルトの状態を使用します。このデフォルト状態に **Off** を選択した場合、マスター機能フラグが **On** であっても、メソッドは常に `false` を返します。
##### 引数
| 名前 | 型 | 説明 |
| ------------------------ | ------ | ---------------------------------------------------------------------------------------- |
| visitorCode | string | ユーザーの一意の識別子です。このフィールドは必須です。 |
| featureKey | string | ユーザーに公開したい機能のキーです。このフィールドは必須です。 |
| isUniqueIdentifier (非推奨) | bool | visitorCode が一意の識別子であるかどうかを指定するオプションのパラメータです。指定しない場合、デフォルト値は `false` です。このフィールドはオプションです。 |
| track | bool | 機能評価のトラッキングを有効または無効にするオプションのパラメータです (デフォルトは `true`)。 |
##### 戻り値
| 型 | 説明 |
| ---- | ------------------------------------- |
| bool | 指定された **visitorCode** に登録されている機能の値です。 |
##### スローされる例外
| 型 | 説明 |
| ------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| KameleoonException.VisitorCodeInvalid | 指定された訪問者コードが無効であることを示す例外です (空であるか、255 文字を超えています)。 |
| KameleoonException.FeatureNotFound | 要求された機能 ID が SDK の内部構成で見つからなかったことを示す例外です。これは通常正常で、機能フラグが Kameleoon 側でまだ有効化されていないことを意味します (機能を実装するコードは Web アプリケーション側に既にデプロイされています)。 |
#### GetVariation()
* 📨 *Kameleoon にトラッキングデータを送信します (`track` パラメータに依存)*
特定の機能フラグに対して、指定された訪問者に割り当てられた [`Variation`](#variation) を取得します。
このメソッドは、必須引数として `visitorCode` と `featureKey` を取ります。`track` 引数はオプションで、デフォルトは `true` です。
訪問者に割り当てられた `Variation` を返します。訪問者がどの機能フラグルールにも関連付けられていない場合、メソッドは指定された機能フラグのデフォルトの `Variation` を返します。
潜在的な例外を管理するために、コードに適切なエラー処理が実装されていることを確認してください。
デフォルトバリエーションとは、機能フラグに対して定義済みの配信ルールにマッチしない訪問者に割り当てられるバリエーションを指します。つまり、特定のルールでターゲットされていないすべてのユーザーに適用されるフォールバックバリエーションです。管理インターフェースの「その後、他のすべての人には...」セクションのバリエーションとして表示されます。
```csharp theme={null}
const string featureKey = "new_checkout";
Variation variation;
try
{
variation = kameleoonClient.GetVariation(visitorCode, featureKey);
// disabling tracking
variation = kameleoonClient.GetVariation(visitorCode, featureKey, false);
} catch (KameleoonException.FeatureNotFound e)
{
// The error has occurred; the feature flag isn't found in the current configuration.
} catch (KameleoonException.FeatureEnvironmentDisabled e)
{
// The feature flag is disabled for the environment.
} catch (KameleoonException.VisitorCodeInvalid e)
{
// The visitor code you passed to the method is invalid and can't be accepted by SDK.
}
// Fetch a variable value for the assigned variation.
string title = variation.Variables["title"].Value;
switch (variation.Key)
{
case "on":
// Main variation key is selected for visitorCode.
break;
case "alternative_variation":
// Alternative variation key
break;
default:
// Default variation key
break;
}
```
##### 引数
| 名前 | 型 | 説明 | デフォルト |
| ------------------ | -------- | ------------------------------------ | ------ |
| visitorCode (*必須*) | `string` | 訪問者の一意の識別子です。 | |
| featureKey (*必須*) | `string` | 訪問者に公開したい機能のキーです。 | |
| track (*オプション*) | `bool` | 機能評価のトラッキングを有効または無効にするオプションのパラメータです。 | `true` |
##### 戻り値
| 型 | 説明 |
| ----------- | ----------------------------------------------------------- |
| `Variation` | 特定の機能フラグに対して、指定された訪問者に割り当てられた [`Variation`](#variation) です。 |
##### スローされる例外
| 型 | 説明 |
| ---------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| `VisitorCodeInvalid` | 提供された訪問者コードが無効であることを示す例外です。空であるか、255 文字を超えています。 |
| `FeatureNotFound` | 要求された機能キーが SDK の内部構成で見つからなかったことを示す例外です。これは通常、機能フラグが Kameleoon アプリで有効化されていないことを意味します (機能を実装するコードはアプリケーションに既にデプロイされています)。 |
| `FeatureEnvironmentDisabled` | 訪問者の現在の環境 (例: 本番、ステージング、または開発) で機能フラグが無効になっていることを示す例外です。 |
#### GetVariations()
* 📨 *Kameleoon にトラッキングデータを送信します (`track` パラメータに依存)*
すべての機能フラグについて、指定された訪問者に割り当てられた [`Variation`](#variation) オブジェクトのマップを取得します。
このメソッドは、利用可能なすべての機能フラグを反復処理し、指定された訪問者に関連付けられた各フラグに割り当てられた `Variation` を返します。必須引数として `visitorCode` を取り、`onlyActive` と `track` はオプションです。
* `onlyActive` が `true` に設定されている場合、`GetVariations()` メソッドは、ユーザーが `off` バリエーションにバケットされていない場合に機能フラグのバリエーションを返します。
* `track` パラメータは、メソッドがバリエーションの割り当てを追跡するかどうかを制御します。デフォルトでは `true` に設定されています。`false` に設定すると、トラッキングは無効になります。
返されるマップは、キーとして機能フラグキー、値として対応する `Variation` で構成されます。機能フラグにバリエーションが割り当てられていない場合、メソッドはそのフラグのデフォルトの `Variation` を返します。
潜在的な例外を管理するために適切なエラー処理を実装する必要があります。
デフォルトバリエーションとは、機能フラグに対して定義済みの配信ルールにマッチしない訪問者に割り当てられるバリエーションを指します。つまり、特定のルールでターゲットされていないすべてのユーザーに適用されるフォールバックバリエーションです。管理インターフェースの「その後、他のすべての人には...」セクションのバリエーションとして表示されます。
```csharp theme={null}
IReadOnlyDictionary variations;
try
{
variations = kameleoonClient.GetVariations(visitorCode);
// only active variations
variations = kameleoonClient.GetVariations(visitorCode, true);
// disable tracking
variations = kameleoonClient.GetVariations(visitorCode, track: false);
}
catch (VisitorCodeInvalid e)
{
// Handle exception
}
```
##### 引数
| 名前 | 型 | 説明 | デフォルト |
| -------------------- | -------- | ----------------------------------------------------------------------- | ------- |
| visitorCode (*必須*) | `string` | 訪問者の一意の識別子です。 | |
| onlyActive (*オプション*) | `bool` | アクティブな (`true`) またはすべての (`false`) 機能フラグのバリエーションを返すかどうかを示すオプションのパラメータです。 | `false` |
| track (*オプション*) | `bool` | 機能評価のトラッキングを有効または無効にするオプションのパラメータです。 | `true` |
##### 戻り値
| 型 | 説明 |
| ---------------------------------------- | ---------------------------------------------------------------------- |
| `IReadOnlyDictionary` | 対応する機能のキーを使用して、機能フラグの割り当てられた [`Variation`](#variation) オブジェクトを含むマップです。 |
##### スローされる例外
| 型 | 説明 |
| -------------------- | ----------------------------------------------- |
| `VisitorCodeInvalid` | 提供された訪問者コードが無効であることを示す例外です。空であるか、255 文字を超えています。 |
#### GetFeatureList()
このメソッドは以前 `ObtainFeatureList()` と呼ばれていましたが、SDK バージョン `4.0.0` で削除されました。
SDK に現在利用可能な機能フラグキーのリストを返します。
```csharp theme={null}
const featureFlagIds = kameleoonClient.GetFeatureList()
```
##### 戻り値
| 型 | 説明 |
| -------------- | ----------- |
| `List` | 機能フラグキーのリスト |
#### SetForcedVariation()
このメソッドにより、標準の評価プロセスをバイパスして、特定の [`Variation`](#variation) をユーザーにプログラムで割り当てることができます。これは、通常の評価ロジックが必要ないか、スキップする必要がある制御された実験で特に価値があります。デバッグやカスタムテストなどのシナリオでも役立ちます。
**強制された** バリエーションが設定されると、Kameleoon のリアルタイム評価ロジックが上書きされます。セグメンテーション、ターゲティング条件、アルゴリズム計算などのプロセスはスキップされます。実験中のセグメンテーションとターゲティング条件を保持するには、代わりに `forceTargeting=false` を設定してください。
**シミュレートされた** バリエーションは、実行順序で常に優先されます。**シミュレートされた** バリエーションの計算がトリガーされた場合、それが最初に完全に処理および完了されます。
強制されたバリエーションは、評価されたバリエーションと同じように扱われます。分析でトラッキングされ、標準の評価されたバリエーションと同様にユーザーコンテキストに保存されるため、レポートの一貫性が確保されます。
このメソッドは、特定の条件下 (無効なパラメータ、ユーザーコンテキスト、または内部の問題など) で例外をスローする場合があります。アプリケーションの安定性と回復力を確保するためには、適切な例外処理が不可欠です。
**強制された** バリエーションを **[シミュレートされた](#getvisitorcode)** バリエーションと区別することが重要です:
* **強制バリエーション**: 個々の実験に固有のものです。
* **シミュレートバリエーション**: 全体的な **機能フラグ** の結果に影響します。
```csharp theme={null}
const int experimentId = 9516;
try
{
// Forcing the variation "on" in the experiment 9516 for the visitor
kameleoonClient.SetForcedVariation(visitorCode, experimentId, "on");
// Forcing the variation "on" while preserving segmentation and targeting conditions during the experiment
kameleoonClient.SetForcedVariation(visitorCode, experimentId, "on", false);
// Resetting the forced variation for the experiment 9516 for the visitor
kameleoonClient.SetForcedVariation(visitorCode, experimentId, null);
}
catch (KameleoonException ex)
{
// Handling the exception
}
```
##### 引数
| 名前 | 型 | 説明 | デフォルト |
| ------------------------ | -------- | -------------------------------------------------------------------------------------- | ------ |
| visitorCode (*必須*) | `string` | 訪問者の一意の識別子です。 | |
| experimentId (*必須*) | `int` | 評価プロセス中にターゲットおよび選択される **実験 Id** です。 | |
| variationKey (*必須*) | `string` | 実験の戻り値として強制される `Variation` に対応する **バリエーションキー** です。値が `null` の場合、強制されたバリエーションはリセットされます。 | |
| forceTargeting (*オプション*) | `bool` | 実験のターゲティングを強制してスキップする (`true`)、または標準の評価プロセスと同様に適用する (`false`) かを示します。 | `true` |
##### スローされる例外
| 型 | 説明 |
| --------------------------- | ----------------------------------------------------------------------------------------------------------- |
| `VisitorCodeInvalid` | 提供された訪問者コードが無効であることを示す例外です。空であるか、255 文字を超えています。 |
| `FeatureExperimentNotFound` | 要求された実験 ID が SDK の内部構成で見つからなかったことを示す例外です。これは通常正常で、ルールに対応する実験が Kameleoon 側でまだ有効化されていないことを意味します。 |
| `FeatureVariationNotFound` | 要求されたバリエーションキー (ID) が SDK の内部構成で見つからなかったことを示す例外です。これは通常正常で、バリエーションに対応する実験が Kameleoon 側でまだ有効化されていないことを意味します。 |
ほとんどの場合、例で示されているように、基本的なエラー `KameleoonException` のみを処理する必要があります。ただし、さまざまなタイプのエラーが応答を必要とする場合は、特定の要件に基づいて個別に処理してください。さらに、信頼性を向上させるために、一般的な言語エラーは `Exception` を含めることで処理できます。
#### EvaluateAudiences()
* 📨 *Kameleoon にトラッキングデータを送信します*
このメソッドは、利用可能なすべての Audiences Explorer セグメントに対して訪問者を評価し、マッチした訪問者を追跡します。
`EvaluateAudiences()` は、**関連するすべての訪問者データが設定または更新された後** に、また機能バリエーションを取得したり機能フラグを確認したりする **直前** に呼び出す必要があります。このアプローチにより、訪問者が利用可能な最新のデータに対して評価されることが保証され、すべての基準に基づいて正確なオーディエンス割り当てが可能になります。
このメソッドを呼び出した後、Audiences Explorer でセグメントパフォーマンスの詳細な分析を実行できます。
```csharp theme={null}
try
{
kameleoonClient.EvaluateAudiences(visitorCode);
}
catch (KameleoonException ex)
{
// Handling the exception
}
```
##### 引数
| 名前 | 型 | 説明 |
| ------------------ | -------- | ------------- |
| visitorCode (*必須*) | `string` | 訪問者の一意の識別子です。 |
##### スローされる例外
| 型 | 説明 |
| -------------------- | ----------------------------------------------- |
| `VisitorCodeInvalid` | 提供された訪問者コードが無効であることを示す例外です。空であるか、255 文字を超えています。 |
ほとんどの場合、例で示されているように、基本的なエラー `KameleoonException` のみを処理する必要があります。ただし、さまざまなタイプのエラーが応答を必要とする場合は、特定の要件に基づいて個別に処理してください。さらに、信頼性を向上させるために、一般的な言語エラーは `Exception` を含めることで処理できます。
#### GetDataFile()
```csharp theme={null}
DataFile dataFile = kameleoonClient.GetDataFile();
```
##### 戻り値
### 訪問者データ
#### GetVisitorCode()
このメソッドは以前 `ObtainVisitorCode` と呼ばれていましたが、SDK バージョン `4.0.0` で削除されました。
現在の訪問者の Kameleoon **visitorCode** を取得するには、`GetVisitorCode()` メソッドを使用します。このメソッドは、フロントエンドとバックエンドのシステムが一貫してユーザーを識別する必要がある環境で重要です。仕組みは以下のとおりです:
1. 現在の HTTP リクエストで **kameleoonVisitorCode** Cookie またはクエリパラメータをチェックします。見つかった場合は、それを訪問者識別子として使用し、次のステップをスキップします。
2. Cookie やパラメータが見つからない場合は、新しい識別子をランダムに作成するか、**defaultVisitorCode** 引数が提供されていればそれを使用します。これにより、自分の識別子を訪問者コードとして使用し、追加のルックアップなしで Kameleoon の訪問者を自分のユーザーに簡単に接続できます。
3. 識別子の値を使用して、サーバーサイドの **kameleoonVisitorCode** Cookie を設定します。メソッドはこの識別子の値を返します。
独自の `visitorCode` を提供する場合は、必ず一意であることを確認してください! また、`visitorCode` の長さは **255** 文字に制限されていることに注意してください。文字数が多すぎる識別子を使用すると例外が発生します。
`GetVisitorCode()` メソッドを使用すると、訪問者に対して **シミュレートされた** バリエーションを設定できます。Cookie (**リクエスト** または **ドキュメント** から) にキー `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) を使用してバリアントの表示をシミュレートする際に Cookie が自動的に作成されます。
* **手動:** `kameleoonSimulationFFData` Cookie を手動で設定します。
**シミュレートされた** バリエーションを **[強制された](#setforcedvariation)** バリエーションと区別することが重要です:
* **シミュレートバリエーション**: 全体的な **機能フラグ** の結果に影響します。
* **強制バリエーション**: 個々の実験に固有のものです。
⚙️ **手動セットアップ**
`kameleoonSimulationFFData` Cookie が以下の形式に従っていることを確認してください:
* `kameleoonSimulationFFData={"featureKey":{"expId":10,"varId":20}}`: 指定された `featureKey` に対して、実験 `expId` の `varId` を持つバリエーションをシミュレートします。
* `kameleoonSimulationFFData={"featureKey":{"expId":0}}`: 指定された `featureKey` に対して、デフォルトバリエーション (**その後、本番の他のすべての人には次を提供する** セクションで定義) をシミュレートします。
⚠️ 適切な機能を確保するため、Cookie の値は [`encodeURIComponent`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/encodeURIComponent) などのメソッドを使用して URI コンポーネントとしてエンコードする必要があります。
```csharp theme={null}
try
{
string visitorCode = kameleoonClient.GetVisitorCode(Request, Response);
string visitorCode = kameleoonClient.GetVisitorCode(Request, Response, defaultVisitorCode);
}
catch (VisitorCodeInvalid e)
{
// Handle exception
}
```
##### 引数
| 名前 | 型 | 説明 |
| ------------------ | ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| Request | Microsoft.AspNetCore.Http.HttpRequest / System.Web.HttpRequest | 現在の Request オブジェクトを最初のパラメータとして渡す必要があります。このフィールドは必須です。 |
| Response | Microsoft.AspNetCore.Http.HttpResponse / System.Web.HttpResponse | 現在の Response オブジェクトを 2 番目のパラメータとして渡す必要があります。このフィールドは必須です。 |
| defaultVisitorCode | string | リクエストに既存の **kameleoonVisitorCode** Cookie が見つからない場合、このパラメータが **visitorCode** として使用されます。このフィールドはオプションで、デフォルトではランダムな **visitorCode** が生成されます。 |
##### 戻り値
| 型 | 説明 |
| ------ | --------------------------------------------------------------- |
| string | この特定のユーザーに関連付けられた **visitorCode** で、SDK のほとんどのメソッドで使用する必要があります。 |
##### スローされる例外
| 型 | 説明 |
| ------------------------------------- | ------------------------------------------------- |
| KameleoonException.VisitorCodeInvalid | 提供された訪問者コードが無効であることを示す例外です (空であるか、255 文字を超えています)。 |
#### AddData()
`AddData()` メソッドは、他のメソッドが現在の訪問者をターゲットにするかどうかを決定するためにデータを使用できるように、[ターゲティングデータ](#データ型) をストレージに追加します。
`AddData()` メソッドは値を返さず、独自に Kameleoon バックエンドサーバーと対話しません。代わりに、宣言されたすべてのデータは、[`Flush()`](#flush) メソッドを使用した将来の送信のために保存されます。このアプローチでは、データが通常 1 つのサーバー呼び出しにグループ化され、`Flush()` によってトリガーされるため、行われるサーバー呼び出しの数が減ります。
[`TrackConversion()`](#trackconversion) メソッドも、`Flush()` と同様に、以前に関連付けられたデータを送信します。実験ルールがトリガーされた場合、[`GetVariation()`](#getvariation) および [`GetVariations()`](#getvariations) メソッドも同様です。
ほとんどのデータ型では、各訪問者は関連付けられたデータのインスタンスを 1 つだけ持つことができます。ただし、[`CustomData`](#customdata) は例外です。訪問者は、インデックスごとに 1 つの関連付けられた `CustomData` インスタンスを持つことができます。
```csharp theme={null}
// Add a single data item (tracked by default)
kameleoonClient.AddData(new Browser(Browser.Browsers.CHROME));
// Add multiple data items (tracked by default)
kameleoonClient.AddData(
visitorCode,
new PageView("https://url.com", "title", new int[] {3}),
new UserAgent("UserAgent")
);
// Add multiple data items stored locally for targeting only (not sent to the Kameleoon Data API)
kameleoonClient.AddData(
visitorCode,
false,
new PageView("https://url.com", "title", new int[] {3}),
new UserAgent("UserAgent")
);
```
##### 引数
| 名前 | 型 | 説明 | デフォルト値 |
| ------------------ | ---------------- | ----------------------------------------------------------------------------------------------------------- | ------ |
| visitorCode (*必須*) | `string` | 訪問者の一意の識別子です。 | |
| track (*オプション*) | `bool` | 追加されたデータがトラッキングの対象であるかどうかを指定します。`false` に設定すると、データはローカルに保存され、ターゲティング評価にのみ使用され、Kameleoon Data API には送信されません。 | `true` |
| data (*必須*) | `params IData[]` | Kameleoon データ型のコレクションです。 | |
##### 例外
| 型 | 説明 |
| -------------------- | ----------------------------------------------- |
| `VisitorCodeInvalid` | 提供された訪問者コードが無効であることを示す例外です。空であるか、255 文字を超えています。 |
#### Flush()
* 📨 *Kameleoon にトラッキングデータを送信します*
`Flush()` メソッドは、訪問者にリンクされた Kameleoon データを収集します。次に、`AddData` メソッドを使用して以前に追加された、まだ [これらのメソッド](/developer-docs/feature-experimentation/technical-reference/faq-global#when-does-the-sdk-send-a-tracking-request-for-analytics) のいずれかを使用して送信されていないすべてのデータとともにトラッキングリクエストを送信します。`Flush()` は、サーバー呼び出しが非同期に行われるため、非ブロッキングです。
`Flush()` を使用すると、指定された `visitorCode` に関連付けられたデータがいつ当社のサーバーに送信されるかを制御できます。例えば、`AddData()` を 12 回呼び出した場合、`AddData()` が呼び出されるたびにデータをサーバーに送信するのは非効率的なので、最後に `Flush()` を 1 回呼び出すだけで済みます。
`visitorCode` を指定すると、`Flush()` メソッドはそれを一意の訪問者識別子として使用します。これは [クロスデバイス実験](/developer-docs/cross-device-experimentation) に役立ちます。`visitorCode` を指定し、`isUniqueIdentifier` パラメータを `true` に設定すると、SDK は指定された識別子に関連付けられた訪問者とフラッシュされたデータをリンクします。
パラメータ `isUniqueIdentifier` は非推奨です。代わりに [`UniqueIdentifier`](#uniqueidentifier) を使用してください。
`isUniqueIdentifier` は、特殊な状況で役立ちます。例えば、訪問者に付与された匿名の `visitorCode` にアクセスできないが、セッションマージを通じてその訪問者にリンクされた内部 ID を使用できる場合などです。
```csharp theme={null}
string visitorCode = kameleoonClient.GetVisitorCode(Request, Response, "example.com");
kameleoonClient.AddData(new Browser(Browser.Browsers.CHROME));
kameleoonClient.AddData(
visitorCode,
new PageView("https://url.com", "title", new int[] {3}),
new Conversion(32, 10f, false)
);
kameleoonClient.Flush(visitorCode); // Interval tracking (most performant tracking method)
kameleoonClient.Flush(true, visitorCode); // Instant tracking
// if you operate with unique ID
kameleoonClient.AddData(visitorCode, new UniqueIdentifier(true));
kameleoonClient.Flush(visitorCode);
```
##### 引数
| 名前 | 型 | 説明 |
| ------------------------ | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| instant | bool | データを即座に送信する (`true`) か、予定されたトラッキング間隔に従って送信する (`false`) かを示すブール値フラグです。このフィールドはオプションです。 |
| visitorCode | string | ユーザーの一意の識別子です。このフィールドは必須です。 |
| isUniqueIdentifier (非推奨) | bool | visitorCode が一意の識別子であるかどうかを指定するオプションのパラメータです。訪問者に `isUniqueIdentifier` を適用するには、`visitorCode` が提供されており `null` でない必要があります。そうでない場合は無視されます。指定しない場合、デフォルト値は `false` です。このフィールドはオプションです。 |
#### GetRemoteData()
このメソッドは以前 `RetrieveDataFromRemoteSource` と呼ばれていましたが、SDK バージョン `4.0.0` で削除されました。
`GetRemoteData()` は、指定した **キー** を使用して、特定の **siteCode** (`KameleoonClientFactory.create()` で設定) のデータをリモートの Kameleoon サーバーから取得できるメソッドです。当社の Data API は、このデータを大量のデータを効率的に処理するように設計された当社のサーバーに保存しています。このメソッドはサーバー呼び出しを伴うため、非同期で動作することに注意してください。
```csharp theme={null}
var testValue = await kameleoonClient.GetRemoteData("test"); // default timeout
testValue = await kameleoonClient.GetRemoteData("test", 1000);
try {
testValue = await kameleoonClient.GetRemoteData("test");
} catch (Exception e) {
// Timeout or Json Parsing Exception
}
```
##### 引数
| 名前 | 型 | 説明 |
| ------- | ------ | -------------------------------------------------------------------------------------- |
| key | string | 取得しようとしているデータが関連付けられているキーです。このフィールドは必須です。 |
| timeout | int? | タイムアウト (ミリ秒)。このパラメータは、結果を待つ最大時間を指定します。このフィールドはオプションで、指定しない場合は 10000 ミリ秒のデフォルト値が使用されます。 |
##### 戻り値
| 型 | 説明 |
| ------- | ------------------------------- |
| JObject | 特定の **キー** のデータ取得に関連付けられたデータです。 |
##### スローされる例外
| 型 | 説明 |
| --------- | ---------------------------------------------------------------- |
| Exception | リクエストがタイムアウトした、または取得したデータを `JObject.Parse` メソッドで解析できないことを示す例外です。 |
#### GetRemoteVisitorData()
`GetRemoteVisitorData()` は、`VisitorCode` を使用して特定のユーザーの Kameleoon 訪問データを取得するメソッドです。バックグラウンドで動作し、他のメソッドがターゲティングを決定するためにこのデータを保存します。
このデータは、いくつかの理由で重要です:
* 異なるデバイスから収集された情報を使用できます。
* 以前の訪問で訪問したページなど、ユーザーの履歴にアクセスできます。
* データレイヤー変数やフロントエンドでのみコンバージョンを追跡するゴールなど、クライアントサイドでのみ利用可能なデータを使用できます。
可能なユースケースをよりよく理解するために、[この記事](/developer-docs/feature-experimentation/targeting-and-segmentation/native-segmentation) をお読みください。
デフォルトでは、`GetRemoteVisitorData()` は最新の保存されているカスタムデータ (`Scope=Visitor`) を自動的に取得し、`AddData()` メソッドを呼び出すことなく訪問者にアタッチします。これは [複数のデバイス間でカスタムデータを同期する](/developer-docs/sdks/web-sdks/nodejs-sdk#synchronizing-custom-data-across-devices) ために特に有用です。
パラメータ `isUniqueIdentifier` は非推奨です。代わりに [`UniqueIdentifier`](#uniqueidentifier) を使用してください。
`isUniqueIdentifier` は、特殊な状況で役立ちます。例えば、訪問者に付与された匿名の `visitorCode` にアクセスできないが、セッションマージを通じてその訪問者にリンクされた内部 ID を使用できる場合などです。
```csharp theme={null}
string visitorCode = "visitorCode";
// Visitor data will be fetched and automatically added for `visitorCode`
Task> visitorData = kameleoonClient.GetRemoteVisitorData(visitorCode);
// If you only want to fetch data and add it yourself manually, set addData == `false`.
Task> visitorData = kameleoonClient.GetRemoteVisitorData(visitorCode, false);
// If you want to fetch custom list of data types
var filter = new RemoteVisitorDataFilter(25, customData: false, conversions: true, experiments: true);
var visitorData = kameleoonClient.getRemoteVisitorData(visitorCode, filter: filter);
try {
IReadOnlyCollection visitorData = await kameleoonClient.GetRemoteVisitorData(visitorCode);
// Your custom code
} catch (Exception e) {
// Catch exception
}
```
##### 引数
| 名前 | 型 | 説明 |
| ------------------------ | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| visitorCode | string | 割り当てられたデータを取得したい訪問者コードです。このフィールドは必須です。 |
| addData | bool | メソッドが取得したデータを訪問者に自動的に追加するかどうかを示すブール値です。このフィールドはオプションです。 |
| timeout | int? | タイムアウト (ミリ秒)。このパラメータは、結果を待つ最大時間を指定します。このフィールドはオプションです。指定しない場合、デフォルト値は 10000 ミリ秒です。 |
| filter | `Kameleoon.Types.RemoteVisitorDataFilter` | 訪問からどのデータを取得するかを指定するフィルタです。デフォルトでは、現在および最新の以前の訪問から `CustomData` のみが取得されます (`new RemoteVisitorDataFilter(previousVisitAmount: 1, currentVisit: true, customData: true)` または `RemoteVisitorDataFilter.Default`)。他のフィルタパラメータは `false` に設定されています。このフィールドはオプションです。 |
| isUniqueIdentifier (非推奨) | bool | visitorCode が一意の識別子であるかどうかを指定するオプションのパラメータです。指定しない場合、デフォルト値は `false` です。このフィールドはオプションです。 |
##### 戻り値
| 型 | 説明 |
| ---------------------------------- | ------------------------- |
| `Task>` | 指定された訪問者に関連付けられたコレクションです。 |
##### スローされる例外
| 型 | 説明 |
| -------------------- | ---------------------------------- |
| HttpRequestException | リクエストが何らかの理由で失敗したことを示す例外です。 |
| Exception | リクエストがタイムアウトした、またはその他の失敗理由を示す例外です。 |
##### GetRemoteVisitorData() でのパラメータの使用
`GetRemoteVisitorData()` メソッドは、訪問者のデータを取得する際にさまざまなパラメータを定義できる柔軟性を提供します。ゴール、実験、またはバリエーションに基づいてターゲティングする場合でも、同じアプローチがすべてのデータ型に適用されます。
例えば、ゴール「Order transaction」を完了した訪問者のデータを取得したい場合、`GetRemoteVisitorData()` メソッド内でパラメータを指定してターゲティングを絞り込むことができます。例えば、最後の 5 回の訪問でゴールでコンバージョンしたユーザーのみをターゲットにしたい場合は、`PreviousVisitAmount` パラメータを 5 に設定し、`Conversions` を true に設定します。
この例で示された柔軟性はゴールデータに限定されません。`GetRemoteVisitorData()` メソッド内でパラメータを使用して、さまざまな訪問者の行動に関するデータを取得できます。
利用可能な `Kameleoon.Types.RemoteVisitorDataFilter` オプションのリストは以下のとおりです:
| 名前 | 型 | 説明 | デフォルト |
| ----------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| previousVisitAmount (*オプション*) | `int` | データを取得する以前の訪問回数です。`1` から `25` の間の数字 | `1` |
| currentVisit (*オプション*) | `bool` | true の場合、現在の訪問データが取得されます | `true` |
| customData (*オプション*) | `bool` | true の場合、カスタムデータが取得されます。 | `true` |
| pageViews (*オプション*) | `bool` | true の場合、ページデータが取得されます。 | `false` |
| geolocation (*オプション*) | `bool` | true の場合、位置情報データが取得されます。 | `false` |
| device (*オプション*) | `bool` | true の場合、デバイスデータが取得されます。 | `false` |
| browser (*オプション*) | `bool` | true の場合、ブラウザデータが取得されます。 | `false` |
| operatingSystem (*オプション*) | `bool` | true の場合、オペレーティングシステムデータが取得されます。 | `false` |
| conversions (*オプション*) | `bool` | true の場合、コンバージョンデータが取得されます。 | `false` |
| experiments (*オプション*) | `bool` | true の場合、実験データが取得されます。 | `false` |
| kcs (*オプション*) | `bool` | true の場合、Kameleoon Conversion Score (KCS) が取得されます。[AI Predictive Targeting アドオン](/user-manual/ai-predictive-targeting/target-users-based-on-likelihood-to-convert) が必要です。 | `false` |
| visitorCode (*オプション*) | `bool` | true の場合、最新の訪問の `visitorCode` が取得され、現在の訪問者に適用されます。[クロスデバイス実験](/developer-docs/cross-device-experimentation) に必要です。 | `true` |
| cbs (*オプション*) | `bool` | true の場合、Contextual Bandit スコアデータが取得されます。 | `false` |
#### GetVisitorWarehouseAudience()
このメソッドは、指定された `visitorCode` と `warehouseKey` を使用して、データウェアハウスで訪問者に関連付けられたすべてのオーディエンスデータを取得します。`warehouseKey` は通常、内部ユーザー ID です。`customDataIndex` パラメータは、訪問者をターゲットにするために Kameleoon が使用する Kameleoon カスタムデータに対応します。追加の詳細については、[ウェアハウスターゲティングのドキュメント](/user-manual/integrations/data-warehouses/bigquery/use-bigquery-as-a-source-audience-targeting) を参照してください。このメソッドは `CustomData` オブジェクトを返し、データが訪問者に追加され、ターゲティングの目的で利用可能であることを確認します。
```csharp theme={null}
Task warehouseAudienceDataTask = kameleoonClient.
GetVisitorWarehouseAudience(visitorCode, customDataIndex); // default timeout
Task warehouseAudienceDataTask = kameleoonClient.
GetVisitorWarehouseAudience(visitorCode, customDataIndex, timeout: 1000);
// If you need to specify warehouse key
Task warehouseAudienceDataTask = kameleoonClient.
GetVisitorWarehouseAudience(visitorCode, customDataIndex, warehouseKeyValue); // default timeout
Task warehouseAudienceDataTask = kameleoonClient.
GetVisitorWarehouseAudience(visitorCode, customDataIndex, warehouseKeyValue, 1000);
try
{
CustomData warehouseAudienceData = await warehouseAudienceDataTask;
// Your custom code
}
catch (Exception e)
{
// Catch exception
}
```
##### 引数
| 名前 | 型 | 説明 |
| --------------- | ------ | ---------------------------------------------------------------------------------- |
| visitorCode | string | 一意の訪問者識別文字列で、255 文字を超えることはできません。 |
| customDataIndex | int | BigQuery オーディエンスをターゲットにするために使用したいカスタムデータのインデックスを表す整数です。 |
| warehouseKey | string | ウェアハウスデータを識別するための一意のキー (通常、内部ユーザー ID) です。このフィールドはオプションです。 |
| timeout | int? | タイムアウト (ミリ秒)。このパラメータは、結果を待つ最大時間を指定します。このフィールドはオプションです。指定しない場合、デフォルト値は 10000 ミリ秒です。 |
##### 戻り値
| 型 | 説明 |
| ------------------ | ------------------------------------------- |
| `Task` | データが訪問者に追加されたことを確認する `CustomData` インスタンスです。 |
##### スローされる例外
| 型 | 説明 |
| ------------------------------------- | ------------------------------------------------- |
| KameleoonException.VisitorCodeInvalid | 提供された訪問者コードが無効であることを示す例外です (空であるか、255 文字を超えています)。 |
| HttpRequestException | リクエストが何らかの理由で失敗したことを示す例外です。 |
| Exception | リクエストがタイムアウトした、またはその他の失敗理由を示す例外です。 |
#### SetLegalConsent()
このメソッドを使用して、訪問者が個人データの使用に法的同意を与えたかどうかを指定する必要があります。`legalConsent` パラメータを `false` に設定すると、トラッキングリクエストに含めることができるデータ型が制限されます。このメソッドは、訪問者データを責任を持って管理しながら、法律および規制要件を遵守するのに役立ちます。個人データの詳細については、[同意管理ポリシー](/user-manual/project-management/consent-management-policy) を参照してください。
```csharp theme={null}
string visitorCode = kameleoonClient.GetVisitorCode(httpRequest, httpResponse);
kameleoonClient.SetLegalConsent(visitorCode, true, httpResponse);
```
##### 引数
| 名前 | 型 | 説明 |
| ------------ | --------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
| visitorCode | string | ユーザーの一意の識別子です。このフィールドは必須です。 |
| legalConsent | bool | 法的同意状態を表すブール値です。`true` は訪問者が法的同意を与えたことを示し、`false` は訪問者が法的同意を提供したことがない、または撤回したことを示します。このフィールドは必須です。 |
| response | Microsoft.AspNetCore.Http.HttpResponse / System.Web.HttpRequest | 法的同意状態に基づいて Cookie の値が調整される HTTP レスポンスです。このフィールドはオプションです。 |
##### スローされる例外
| 型 | 説明 |
| ------------------------------------- | ----------------------------------------------- |
| KameleoonException.VisitorCodeInvalid | 提供された訪問者コードが無効であることを示す例外です。空であるか、255 文字を超えています。 |
##### 同意撤回の動作
`consent=false` で `setLegalConsent()` を呼び出すと、SDK は `kameleoonVisitorCode` Cookie を削除しません。代わりに、Cookie の有効期限の延長を停止し、Cookie が自然に期限切れになるまで保持されるようにします。
コンプライアンス要件でオプトアウト時に Cookie ファイルを即座に削除する必要がある場合は、フレームワークのネイティブの Cookie 管理メソッドを使用して手動で削除する必要があります。SDK はファイルを自動的に削除しません。
### ゴールとサードパーティ分析
#### TrackConversion()
* 📨 *Kameleoon にトラッキングデータを送信します*
このメソッドを使用して、特定の [ゴール](/user-manual//assets/goals/create-a-goal) とユーザーのコンバージョンを追跡します。このメソッドには `visitorCode` と `goalId` が必要です。また、このメソッドはオプションの `revenue`、`negative`、`metadata` 引数も受け取ります。`visitorCode` は通常、実験をトリガーしたときに使用したものと同じです。
`TrackConversion()` メソッドは値を返しません。このメソッドは、サーバー呼び出しが非同期に行われるため、非ブロッキングです。
パラメータ `isUniqueIdentifier` は非推奨です。代わりに [`UniqueIdentifier`](#uniqueidentifier) を使用してください。
`isUniqueIdentifier` は、訪問者に元々割り当てられた匿名の `visitorCode` にアクセスできないが、セッションマージ機能を使用して匿名の訪問者に接続された内部 ID にアクセスできる場合など、他のエッジケースシナリオでも役立ちます。
```csharp theme={null}
using Kameleoon;
string visitorCode = kameleoonClient.GetVisitorCode(Request, Response, "example.com");
int goalId = 83023;
kameleoonClient.TrackConversion(visitorCode, goalId);
// Add metadata
var cd = new CustomData(1, "metadata");
kameleoonClient.TrackConversion(visitorCode, goalId, metadata: cd)
```
##### 引数
| 名前 | 型 | 説明 | デフォルト |
| -------------------------- | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------- |
| visitorCode (*必須*) | `string` | 訪問者の一意の識別子です。 | |
| goalId (*必須*) | `int` | ゴールの ID です。 | |
| revenue (*オプション*) | `float?` | コンバージョンの収益です。 | `0` |
| negative (*オプション*) | `bool` | 収益がプラスかマイナスかを定義します。 | `false` |
| metadata (*オプション*) | `params CustomData[]` | Kameleoon アプリでゴールのメタデータとして定義されたカスタムデータに特定の値を設定できます。例: `[CustomData{id: 5, value: "Payment Type"}, CustomData{id: 6, value: "Delivery Method"}]`。この例では、`5` と `9` がカスタムデータのインデックスです (5 = "Payment Type"、9 = "Delivery Method")。 | `new CustomData[0]` |
| isUniqueIdentifier *(非推奨)* | `bool` | visitorCode が一意の識別子であるかどうかを指定するオプションのパラメータです。 | `false` |
メタデータの値は、[生データのエクスポート](/user-manual/experiment-analytics/analyze-results/results-page/results-page-actions#Export) と [結果ページ](/user-manual/experiment-analytics/analyze-results/data-and-metrics/goal-metadata) からアクセスできます。
`metadata` パラメータが提供されている場合、Kameleoon は [`AddData()`](#adddata) メソッドを使用して以前に収集された値ではなく、これらの指定された値を現在のコンバージョンに使用します。パラメータが省略された場合、Kameleoon はコンバージョン以前にトラッキングされた最後の値を、同じ訪問内で対応する [`CustomData`](#customdata) に使用します。
Kameleoon は、`TrackConversion()` メソッドのパラメータとして明示的に渡されたメタデータ値のみを考慮します。
以下の例では、Kameleoon は、パラメータとして明示的に提供されたカスタムデータ値 (ここでは、インデックス 5 に値 'Amex Credit Card') のみをコンバージョンに関連付けます。
```csharp theme={null}
kameleoonClient.AddData(visitorCode, new CustomData(5, "Credit Card"), new CustomData(9, "Express Delivery"));
kameleoonClient.TrackConversion(visitorCode, 10, metadata: new CustomData(5, "Amex Credit Card"));
```
##### 例外
| 型 | 説明 |
| -------------------- | ----------------------------------------------- |
| `VisitorCodeInvalid` | 提供された訪問者コードが無効であることを示す例外です。空であるか、255 文字を超えています。 |
#### GetEngineTrackingCode()
Kameleoon は、Mixpanel、Google Analytics 4、Segment などのいくつかの分析ソリューションと統合されています。サーバーサイドの実験を正しく追跡するには、訪問者が実験をトリガーした後に `GetEngineTrackingCode()` メソッドを呼び出します。SDK は、訪問者が過去 5 秒間にトリガーした実験の JavaScript キューコマンドを返します。このコードをページに挿入すると、Engine.js がコマンドを処理し、アクティブな分析統合を介して露出イベントを送信します。
このメソッドの実装の詳細については、[ハイブリッド実験](/developer-docs/feature-experimentation/get-started/hybrid-experimentation) を参照してください。
```csharp theme={null}
string engineTrackingCode = kameleoonClient.GetEngineTrackingCode(visitorCode);
```
* この機能を使用するには、C# 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 `