> ## 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.
# Go SDK
> Kameleoon Go SDK を統合して、Go ウェブアプリケーションおよびサービスで実験を実行し、機能フラグを有効化します。
Go SDK を使用すると、実験を実行したり機能フラグを有効化したりできます。当社の SDK をウェブアプリケーションに統合するのは簡単で、フットプリント(メモリおよびネットワーク使用量)も小さく抑えられています。
**はじめに**: 入門ガイドについては、[開発者ガイド](#開発者ガイド)を参照してください。
**変更履歴**: Go SDK の最新バージョン: 3.20.0 [変更履歴](https://github.com/Kameleoon/client-go/blob/master/CHANGELOG.md)。
**SDK メソッド**: Go SDK の完全なリファレンスドキュメントについては、[リファレンス](#リファレンス)セクションを参照してください。
## 開発者ガイド
このセクションに従って SDK をインストール・設定し、高度な機能について学習してください。
### はじめに
#### Go クライアントのインストール
Kameleoon Go SDK をインストールするには、`go get` コマンドを使用して、GitHub リポジトリから直接パッケージをインストールします。以下のコマンドを実行するだけです:
```shell theme={null}
go get github.com/Kameleoon/client-go/v3
```
#### 追加設定
Go SDK の追加設定を提供するには、設定ファイルを使用して SDK の動作をカスタマイズできます。サンプル設定ファイルは [こちら](/assets/developer-docs/sdks/web-sdks/client-configs/client-go.yaml) からダウンロードできます。
このファイルはデフォルトパス `/etc/kameleoon/client-go.yaml` にインストールすることをお勧めします。このパスは自動的に読み込まれます。このパスをカスタマイズする必要がある場合は、`NewClient()` メソッドに追加引数を指定できます。設定ファイルへの代替パスを示す文字列を指定するか、設定を含む JavaScript オブジェクト(マップ)を追加します。
現行バージョンの Go 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)ドキュメントを参照してください。 | |
| `SessionDuration` / `session_duration` (*オプション*) | Kameleoon が訪問者およびその関連データをメモリ(RAM)に保存する、事前定義された時間間隔を指定します。セッション期間を長くすると、訪問者データを保存するために割り当てる必要のある RAM の量が増加します。 | `30` 分 |
| `RefreshInterval` / `refresh_interval` (*オプション*) | SDK がアクティブな実験および機能フラグの設定を取得するリフレッシュ間隔(分単位)を指定します。この値によって、機能フラグの有効化・無効化や実験の開始などの変更を本番サーバーに伝播するのにかかる最大時間が決まります。さらに、サーバー送信イベント(SSE)を使用して新しい設定を自動的に SDK にプッシュし、遅延なくリアルタイムに新しい設定を適用する [ストリーミングモード](/developer-docs/feature-experimentation/technical-reference/technical-considerations/#streaming-premium-option) も提供しています。 | `60` 分 |
| `DefaultTimeout` / `default_timeout` (*オプション*) | SDK からのネットワークリクエストに対するタイムアウト(ミリ秒単位)を指定します。安定した接続がない場合は、30 秒以上に設定してください。一部のメソッドには、特定のメソッドのデフォルトタイムアウトを上書きするために使用できる追加パラメータがあります。メソッドのタイムアウトを明示的に指定しない場合、SDK はこのデフォルト値を使用します。 | `10000` ミリ秒 |
| `TrackingInterval` / `tracking_interval` (*オプション*) | トラッキングリクエストの間隔をミリ秒単位で指定します。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` *(ハイブリッドモードで必須)* | ウェブサイトの現在のトップレベルドメインです。形式: `example.com` を使用します。`https://`、`www`、その他のサブドメインは含めないでください。Kameleoon はこの情報を使用して、対応するクッキーをトップレベルドメインに設定します。 | `""` |
| `ProxyUrl` / `proxy_url` (*オプション*) | SDK からのすべての送信サーバーコールに対するプロキシホストを設定します。 | `""` |
| `NetworkDomain` / `network_domain` (*オプション*) | SDK が送信リクエストに使用するカスタムドメインで、プロキシ用途でよく使われます。有効なドメイン(例: example.com または sub.example.com)である必要があります。形式が無効な場合は Kameleoon のデフォルト値が使用されます。 | `""` |
| `VerboseMode` / `verbose_mode` *(非推奨)* | ネットワークリクエストやデバッグ情報を含む追加のロギングを有効にするブール値(`true` または `false`)です。このフィールドは非推奨であり、SDK バージョン `4.0.0` で削除されます。代わりに [`logging.SetLogLevel`](#ログレベル) を使用してください。 | `false` |
`client_id` および `client_secret` の詳細と取得方法については、[こちらの記事](/user-manual/account-and-team-management/users-and-teams/api-credentials)を参照してください。当社の Go SDK は Automation API を利用しており、OAuth 2.0 クライアント認証情報フローに従っていることに注意してください。
#### Kameleoon クライアントの初期化
アプリケーションに SDK をインストールしたら、Kameleoon を初期化する必要があります。実験のトリガーなど、SDK とのすべてのやり取りは、`NewClient()` メソッドを使用して作成されたオブジェクト(Kameleoon クライアント)を介して行われます。
[設定オブジェクト](#追加設定)を提供することで、SDK の動作(例: 環境や認証情報)をカスタマイズできます。
```go theme={null}
import (
kameleoon "github.com/Kameleoon/client-go/v3"
)
// 最初のオプション
config := &kameleoon.KameleoonClientConfig{
Network: kameleoon.NetworkConfig{ // オプション
ProxyURL: "http://proxy-pass:1234/", // オプション
DoTimeout: 10 * time.Second, // オプション
ReadTimeout: 5 * time.Second, // オプション
WriteTimeout: 5 * time.Second, // オプション
MaxConnsPerHost: 10000, // オプション
},
ClientID: "your-client-id", // このフィールドは必須です。ここに client_id を入力してください。
ClientSecret: "your-client-secret", // このフィールドは必須です。ここに client_secret を入力してください。
TopLevelDomain: "example.com", // このフィールドは強く推奨されます。指定しないとサブドメイン使用時に問題が生じる可能性があります。
RefreshInterval: time.Hour, // オプション(デフォルトは 60 分)
TrackingInterval: time.Second, // オプション(デフォルトは 1000 ms)
Environment: "staging", // オプション
SessionDuration: 30 * time.Minute, // オプション(デフォルトは 30 分)
NetworkDomain: "example.com", // オプション
}
client, err := KameleoonClientFactory.Create("your-project-sitecode", config)
// 2 番目のオプション
config, err := LoadConfig("/etc/kameleoon/client-go.yaml")
client, err := KameleoonClientFactory.Create("your-project-sitecode", config)
// 注意: 上記の例では、設定は毎回読み込まれます。一度だけ読み込むには、`CreateFromFile` を使用してください。
// 3 番目のオプション
client, err := KameleoonClientFactory.CreateFromFile("your-project-sitecode", "/etc/kameleoon/client-go.yaml")
```
#### 機能フラグの有効化
##### ユーザーへの一意の ID の割り当て
ユーザーに一意の ID を割り当てるには、[`GetVisitorCode()`](#getvisitorcode) メソッドを使用できます。**訪問者コード**が(リクエストヘッダーのクッキーから)存在しない場合、このメソッドはランダムな一意の ID を生成するか、生成済みの `defaultVisitorCode` を使用します。ID はその後、レスポンスヘッダーのクッキーに設定されます。
[ハイブリッドモード](/developer-docs/feature-experimentation/get-started/hybrid-experimentation)で Kameleoon を使用している場合、`GetVisitorCode()` メソッドを呼び出すと、一意の ID(**訪問者コード**)がアプリケーションファイル `engine.js`(以前は `kameleoon.js` という名称)と SDK の間で共有されることが保証されます。
##### フラグ設定の取得
コードに機能フラグを実装するには、まず Kameleoon アカウントで機能フラグを作成する必要があります。
特定のユーザーに対する機能フラグのステータスまたはバリエーションを決定するには、[`GetVariation()`](#getvariation) または [`IsFeatureActive()`](#isfeatureactive) メソッドを使用して、`featureKey` に基づいて設定を取得します。
`GetVariation()` メソッドは、ON/OFF 状態のシンプルな機能フラグと、複数のバリエーションを持つより複雑なフラグの両方を処理します。このメソッドは、機能ルールをチェックし、バリエーションを割り当て、`featureKey` および `visitorCode` に基づいてそれを返すことで、ユーザーに適切なバリエーションを取得します。
`IsFeatureActive()` メソッドは、複数のバリエーションやターゲティングオプションを持つ複雑な機能フラグとは対照的に、ON または OFF 状態のみのシンプルな機能フラグの設定を取得したい場合に使用できます。
機能フラグに関連付けられた変数(例: 各バリエーションに関連付けられた特定の動作)がある場合、`GetVariation()` を使用すると [`Variation`](#variation) オブジェクトにもアクセスでき、割り当てられたバリエーションとその関連実験の詳細を提供します。このメソッドはユーザーがターゲットされているかをチェックし、訪問者に割り当てられたバリエーションを見つけて、それをストレージに保存します。`GetVariationOptParams.Track=true` の場合、SDK は次のトラッキングリクエストで指定された実験に露出イベントを送信します。これは SDK の [`tracking_interval`](#追加設定) に基づいて自動的にトリガーされます。デフォルトでは、この間隔は 1000 ミリ秒(1 秒)に設定されています。
`GetVariation()` メソッドでは、トラッキングを行うかどうかを制御できます。`GetVariationOptParams.Track=false` の場合、SDK によって露出イベントは送信されません。これは、たとえば SDK を介してデータをトラッキングするのではなく、Kameleoon エンジンが管理するクライアント側のトラッキングに依存することを希望する場合に便利です。さらに、`GetVariationOptParams.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*()`](#flushall--flushvisitor--flushvisitorinstantly) メソッドを呼び出すことを忘れないでください。
結果の精度を確保するために、[`UserAgent`](#useragent) データ型を使用してボットを除外することをお勧めします。
##### フラグ露出とゴール転換の追跡
ユーザーが望ましいアクション(購入など)を完了すると、それはコンバージョンとして記録されます。コンバージョンを追跡するには、[`TrackConversion()`](#trackconversion) メソッドを使用して、必須の `visitorCode` および `goalId` パラメータを提供します。
コンバージョン追跡リクエストは、次回スケジュールされているトラッキングリクエストとともに送信されます。これは SDK が一定間隔([`tracking_interval`](#追加設定) で定義)で送信します。すぐにリクエストを送信したい場合は、[`FlushVisitorInstantly()`](#flushall--flushvisitor--flushvisitorinstantly) メソッドを使用します。
##### 分析ソリューションへのイベントの送信
コンバージョンを追跡し、露出イベントを顧客分析ソリューションに送信するには、まず [ハイブリッドモード](/developer-docs/feature-experimentation/get-started/hybrid-experimentation/)で Kameleoon を実装する必要があります。その後、[`GetEngineTrackingCode()`](#getenginetrackingcode) メソッドを使用します。
`GetEngineTrackingCode()` メソッドは、分析ソリューションに露出イベントを送信するために必要な一意のトラッキングコードを取得します。このメソッドを使用すると、イベントを記録して希望の分析プラットフォームに送信できます。
### クロスデバイス実験
複数のデバイスからアプリにアクセスする訪問者をサポートするため、Kameleoon はクロスデバイス実験を通じて、訪問者の各デバイス間で以前に収集された訪問者データを同期し、訪問履歴を調整できます。Kameleoon がデバイス間でデータをどのように扱うかに関するケーススタディと詳細情報は、[クロスデバイス実験に関する記事](/developer-docs/cross-device-experimentation)で確認できます。
#### デバイス間でのカスタムデータの同期
訪問者データをデバイス間で整合させるためにカスタムマッピング同期が使用されますが、常に必要なわけではありません。以下は、カスタムマッピング同期が必要ない 2 つのシナリオです:
**デバイス間で同じユーザー ID**
すべてのデバイスで一貫して同じユーザー ID が使用されている場合、カスタムマッピング同期なしで同期が自動的に処理されます。複数のデバイス間で収集されたデータを同期したい場合、`GetRemoteVisitorData()` メソッドを呼び出すだけで十分です。
**一貫した ID を持つマルチサーバーインスタンス**
複数のサーバー(例: 分散サーバーインスタンス)を含む複雑な設定で、サーバー間で同じユーザー ID が利用できる場合、追加のカスタムマッピング同期なしで、サーバー間の同期(`GetRemoteVisitorData()` を使用)で十分です。
追加データが必要なお客様は、[`GetRemoteVisitorData()`](#getremotevisitordata) メソッドの説明を参照して、さらなるガイダンスを得ることができます。以下のコードでは、正確なデータ取得のために 2 つのデバイス間で同じ一意の識別子(この場合、`userId` とも呼ばれる `visitorCode`)が一貫して使用されていると仮定しています。
収集したデータをリアルタイムで同期したい場合は、カスタムデータのスコープに **Visitor** を選択する必要があります。
```go title="デバイス A" theme={null}
// この例では、インデックス `90` のカスタムデータが Kameleoon で「Visitor」スコープに設定されています。
const VisitorScopeCustomDataIndex = 90
kameleoonClient.AddData(visitorCode, types.NewCustomData(VisitorScopeCustomDataIndex, "your data"))
err := kameleoonClient.FlushVisitor(visitorCode)
```
```go title="デバイス B" theme={null}
// データを操作する前に、`GetRemoteVisitorData` メソッドを呼び出します。
_, err := kameleoonClient.GetRemoteVisitorData(visitorCode, true)
// メソッドを呼び出した後、デバイス 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` を指定して [`GetRemoteVisitorData()`](#getremotevisitordata) を呼び出すと、指定したユーザーの既知のすべてのデータが取得されます。
同じ識別子を持つセッションは、実験で常に同じバリエーションが表示されます。実験の結果ページの Visitor ビューでは、これらのセッションは単一の訪問者として表示されます。
SDK 設定により、関連付けられたセッションは常に同じバリエーションの実験を見ることが保証されます。ただし、クロスデバイスのバリエーション割り当てに関していくつかの制限があります。これらの制限は[こちら](/developer-docs/cross-device-experimentation#critical-points-and-practical-insights)で概説されています。
[クロスデバイス履歴調整の有効化](#クロスデバイス実験)ガイドに従って、Kameleoon プラットフォーム上でカスタムデータを設定します。
その後、SDK を通常通り使用できます。セッションマージのコンテキストで役立つ可能性のあるメソッドは次のとおりです:
* `UniqueIdentifier(true)` を追加した `GetRemoteVisitorData()` - リンクされたすべての訪問者のデータを取得します。
* `UniqueIdentifier(true)` データを追加した [`TrackConversion()`](#trackconversion) または [`Flush*()`](#flushall--flushvisitor--flushvisitorinstantly) - 別の訪問者に関連付けられた特定の訪問者の一部のデータを追跡します。
識別子として使用するカスタムデータは **Visitor スコープ**に設定する必要があるため、各デバイスで [`GetRemoteVisitorData()`](#getremotevisitordata) メソッドを使用して識別子を取得するには、[クロスデバイスカスタムデータ同期](/developer-docs/cross-device-experimentation)を使用する必要があります。
セッションマージにカスタムデータを使用する方法の例を以下に示します。
```go theme={null}
// この例では、`91` は Kameleoon で一意の識別子として設定されたカスタムデータのインデックスを表します。
const MappingIndex = 91
const FeatureKey = "ff123"
// 1. 訪問者の認証前
// 認証されていない訪問者のバリエーションを取得します。
// `anonymousVisitorCode` がその訪問者にランダムに生成された ID であると仮定します。
anonymousVariation, err := kameleoonClient.GetVariation(anonymousVisitorCode, FeatureKey)
// 2. 訪問者の認証後
// `userId` が認証された訪問者の訪問者コードであると仮定します。
kameleoonClient.AddData(anonymousVisitorCode, types.NewCustomData(MappingIndex, userId))
err := kameleoonClient.FlushVisitorInstantly(anonymousVisitorCode)
// `userId` が一意の識別子であることを示します。
kameleoonClient.AddData(userId, types.NewUniqueIdentifier(true))
// 3. 訪問者が認証された後
// `userId` のバリエーションを取得します。匿名訪問者コードのバリエーションと一致します。
userVariation, err := kameleoonClient.GetVariation(userId, FeatureKey)
isSameVariation := userVariation.Key == anonymousVariation.Key // true
// `userId` と `anonymousVisitorCode` がリンクされ、単一の訪問者として追跡されます。
err := kameleoonClient.TrackConversionRevenue(userId, 123, 10.0)
// さらに、リンクされた訪問者は取得済みのリモート訪問者データをすべて共有します。
_, err := kameleoonClient.GetRemoteVisitorData(userId, true)
```
この例では、アプリケーションにログインページがあります。ログイン時にはユーザー ID が不明であるため、[`GetVisitorCode()`](#getvisitorcode) メソッドで生成された匿名の訪問者識別子が使用されます。ユーザーがログインした後、匿名の訪問者がユーザー ID に関連付けられ、訪問者の一意の識別子として使用されます。
### カスタムバケッティングキーの使用
デフォルトでは、Kameleoon はユーザーを機能フラグのバリエーションに割り当てるために、一意の匿名訪問者 ID(`visitorCode`)を使用します。この ID は通常、ユーザーのデバイス上で生成・保存されます(クライアント側およびサーバー側 SDK ではブラウザクッキー、モバイル SDK では永続ストレージ)。ただし、特定のシナリオでは、同じ組織のすべてのユーザーが同じ機能フラグのバリアントを見ることを保証する必要がある場合があります。
**カスタムバケッティングキー**オプションを使用すると、独自のカスタム識別子をバケッティングに提供することで、このデフォルトの動作を上書きできます。この上書きにより、Kameleoon の割り当てロジックは、デフォルトの `visitorCode` ではなく、指定したキーを使用します。
#### ユースケース
カスタムバケッティングキーを使用することは、特に次の状況において、機能フラグ割り当ての一貫性と精度を維持するために不可欠です:
* **アカウントレベルまたは組織レベルの実験:** B2B 製品や、同じ組織のすべてのユーザーを同じバリエーションに割り当てたいシナリオでは、`accountId` のような識別子を使用できます。カスタムバケッティングキーは、チームや会社全体に影響を与える機能の A/B テストにとって極めて重要です。
カスタムバケッティングキーを実装することで、実験における整合性と精度を高め、より信頼性の高い結果とより良いユーザーエクスペリエンスにつながります。
#### 技術的な詳細
機能フラグにカスタムバケッティングキーを設定する際、アプリケーションのデータから特定の識別子を Kameleoon に提供します:
```go theme={null}
client.AddData(visitorCode, types.NewCustomData(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 は、ログレベルによるロギングの制限の設定をサポートしています。
```go theme={null}
import (
"development.kameleoon.net/sdk/go-sdk/v3/logging"
)
// `NONE` ログレベルではロギングが許可されません。
logging.SetLogLevel(logging.NONE)
// `ERROR` ログレベルでは、SDK の主要な動作に影響を与える可能性のある問題のみのロギングが許可されます。
logging.SetLogLevel(logging.ERROR)
// `WARNING` ログレベルでは、追加の注意が必要な問題のロギングが許可されます。
// `ERROR` ログレベルを拡張します。
// `WARNING` ログレベルがデフォルトのログレベルです。
logging.SetLogLevel(logging.WARNING)
// `INFO` ログレベルでは、SDK の内部プロセスに関する一般的な情報のロギングが許可されます。
// `WARNING` ログレベルを拡張します。
logging.SetLogLevel(logging.INFO)
// `DEBUG` レベルは SDK の内部プロセスに関する追加の詳細をログ出力し、`INFO` レベルを拡張し、
// よりきめ細かい診断出力を提供します。
// この情報はエンドユーザーが解釈することを意図したものではありませんが、内部のトラブルシューティングを
// 支援するためにサポートチームに送信できます。
logging.SetLogLevel(logging.DEBUG)
```
#### ログのカスタム処理
SDK はデフォルトでログをコンソール出力に書き込みます。この動作は上書き可能です。
ログレベルによるロギングの制限は、ログ処理ロジックとは別に実行されます。
```go theme={null}
import (
"development.kameleoon.net/sdk/go-sdk/v3/logging"
"github.com/sirupsen/logrus"
)
type CustomLogger struct {
}
func NewCustomLogger() logging.LoggerWithLevel {
return &CustomLogger{}
}
func (dl CustomLogger) Log(level logging.LogLevel, message string) {
switch level {
case logging.NONE:
case logging.ERROR:
logrus.Error(message)
case logging.WARNING:
logrus.Warn(message)
case logging.INFO:
logrus.Info(message)
case logging.DEBUG:
logrus.Debug(message)
}
}
// ログレベルのフィルタリングはログ処理ロジックとは別に適用されます。
// カスタムロガーは、指定されたログレベル以上のログのみを受け付けます。
// ログレベルが正しく設定されていることを確認してください。
logging.SetLogLevel(logging.DEBUG) // オプション。デフォルトは `logging.WARNING`。
logging.SetLogger(NewCustomLogger())
```
## リファレンス
これは Go SDK の完全なリファレンスドキュメントです。
### 初期化
#### Create()
SDK を初期化するために、他のメソッドより先にこのメソッドを呼び出します。このメソッドは `KameleoonClientFactory` にあります。これにより、SDK とアプリ間のすべての対話を管理する `KameleoonClient` のインスタンスが作成されます。
```go theme={null}
const siteCode = "sitecode"
config := &kameleoon.KameleoonClientConfig{
// ...
}
client, err := KameleoonClientFactory.Create(siteCode, config)
```
##### 引数
| 名前 | 型 | 説明 |
| --------------- | ----------------------- | ----------------------------------------------------------------------------------- |
| siteCode (*必須*) | string | SDK で使用している Kameleoon プロジェクトの[一意のキー](/user-manual/faq#how-do-i-find-my-sitecode)です。 |
| cfg (*必須*) | \*KameleoonClientConfig | SDK 設定ファイルへのパス、または設定オブジェクトのいずれかを表します。設定オブジェクトを提供する場合、正しい設定キーを含む必要があります。 |
##### 戻り値
| 型 | 説明 |
| --------------- | ------------------------------------------------------------------------------------------------ |
| KameleoonClient | 実験と機能フラグを管理するために使用される **KameleoonClient** のインスタンス。 |
| error | `Create` 呼び出しで発生したエラー。エラーは `errs.SiteCodeIsEmpty` または `errs.ConfigCredentialsInvalid` の可能性があります。 |
#### CreateFromFile()
SDK を初期化するために、他のメソッドより先にこのメソッドを呼び出します。このメソッドは `KameleoonClientFactory` にあります。これにより、SDK とアプリ間のすべての対話を管理する `KameleoonClient` のインスタンスが作成されます。
```go theme={null}
const siteCode = "sitecode"
client, err := KameleoonClientFactory.CreateFromFile(siteCode, "/etc/kameleoon/client-go.yaml")
```
###### 引数
| 名前 | 型 | 説明 |
| --------------- | ------ | ---------------------------------------------------------------------------------------------------------------- |
| siteCode (*必須*) | string | Kameleoon **siteCode**。 |
| cfgPath (*必須*) | string | 設定ファイルへのパス。指定された **siteCode** を持つ `KameleoonClient` インスタンスが `KameleoonClientFactory` に保存されていない場合のみ、ファイルがロードされます。 |
###### 戻り値
| 型 | 説明 |
| --------------- | --------------------------------------------------------------------------------------------- |
| KameleoonClient | 実験と機能フラグを管理するために使用される **KameleoonClient** のインスタンス。 |
| error | `Create` 内で発生したエラー。エラーは `errs.SiteCodeIsEmpty` または `errs.ConfigCredentialsInvalid` の可能性があります。 |
#### Forget()
`Forget` メソッドは、指定された **siteCode** を持つ `KameleoonClient` インスタンスを `KameleoonClientFactory` から削除し、`KameleoonClient` インスタンスが使用するリソースを解放します。`Forget` メソッドを呼び出した後は、`KameleoonClient` インスタンスを使用しないでください。
```go theme={null}
const siteCode = "sitecode"
KameleoonClientFactory.Forget(siteCode)
```
###### 引数
| 名前 | 型 | 説明 |
| -------- | ------ | ------------------------------------------------------------------------------------ |
| siteCode | string | `KameleoonClientFactory` から削除する `KameleoonClient` インスタンスの **siteCode**。このフィールドは必須です。 |
#### WaitInit()
Kameleoon クライアントの初期化は即時には完了しません。アクティブなすべての実験と機能フラグの現在の設定を取得するために、CDN(コンテンツデリバリーネットワーク)へのサーバーリクエストが必要となるためです。
`kameleoon.KameleoonClient` の `WaitInit` メソッドを使用すると、`KameleoonClient` インスタンスが使用可能になるまで待機できます。
```go theme={null}
err := client.WaitInit()
if err != nil {
// クライアントが正しく初期化されませんでした
fmt.Println(err)
} else {
// SDK が初期化されました。ここで機能フラグ/実験設定を取得できます。
}
```
##### 戻り値
| 型 | 説明 |
| ----- | ----------------- |
| error | 初期化プロセス中に発生したエラー。 |
### 機能フラグとバリエーション
#### IsFeatureActive() / IsFeatureActiveWithTracking()
* 📨 *Kameleoon にトラッキングデータを送信します(`track` パラメータに依存)*
複数のバリエーションやターゲティングオプションを持つより複雑な機能フラグとは対照的に、ON / OFF 状態のみのシンプルな機能フラグの設定を取得したい場合は、このメソッドを使用してください。機能フラグにバリエーションや変数がある場合は、[`GetVariation`](#getvariation) メソッドを使用する必要があります。
**visitorCode** と **featureKey** を必須引数として取り、特定のユーザーに対して機能フラグがアクティブかどうかを確認します。
ユーザーが以前に機能フラグに関連付けられていない場合、SDK はランダムなブール値(ユーザーがこの機能を持つべき場合は **true**、そうでない場合は **false**)を返します。ただし、ユーザーがすでにこの機能フラグに登録されている場合、SDK は以前の機能フラグ値を検出します。
コード例に示されているように、発生する可能性のある例外をキャッチするために、コードに適切なエラー処理を設定することが重要です。
`visitorCode` を指定すると、`IsFeatureActive` メソッドはそれを一意の訪問者識別子として使用します。これは[クロスデバイス実験](/developer-docs/cross-device-experimentation)に役立ちます。`visitorCode` を指定して `isUniqueIdentifier` パラメータを `true` に設定すると、SDK はフラッシュされたデータを指定された識別子に関連付けられた訪問者にリンクします。
`isUniqueIdentifier` パラメータは非推奨です。代わりに [`UniqueIdentifier`](#uniqueidentifier) を使用してください。
`isUniqueIdentifier` は固有の状況で役立つ場合があります。たとえば、訪問者に付与された匿名の `visitorCode` にアクセスできないものの、セッションマージを通じてその訪問者にリンクされた内部 ID を使用できる場合です。
Kameleoon は、`IsFeatureActive()`、`GetVariation()`、`GetVariations()` などの特定のメソッドを呼び出した際に、セッションと訪問者数をカウントするためにトラッキングを使用します。
訪問者をバリエーションに露出させてカウントする必要がある場合は、`GetVariationOptParams.Track` パラメータのデフォルト値 `true` を使用してください。訪問者を露出させる前にこれらのメソッドを呼び出す場合のみ、`GetVariationOptParams.Track` パラメータを `false` に設定してください。
たとえば、訪問者を露出させる前にすべてのバリエーションを取得するために `GetVariations()` を呼び出す場合、`GetVariationsOptParams.Track` パラメータを `false` に設定してください。この設定により、Kameleoon が早すぎるタイミングでセッションをカウントするのを防ぎます。その後、訪問者を明示的に露出させたときにトラッキングをトリガーできます。
Kameleoon はデフォルトで毎秒トラッキングデータを送信します。この間隔は、トラッキング間隔の設定オプションを使用して最大 5 秒まで設定できます。Kameleoon は、イベント間の間隔が 30 分未満である限り、トラッキングイベントを単一のセッションにグループ化します。トラッキングイベント間で 30 分以上経過した場合、Kameleoon はイベントを別個のセッションとしてカウントします。訪問は、セッションで最後に記録されたイベントから 30 分後にレポートに表示されます。
```go theme={null}
const featureKey = "new_checkout"
// 機能フラグがアクティブ(ON / OFF)かをチェック
hasNewCheckout, err := client.IsFeatureActive(visitorCode, featureKey)
// トラッキングを無効化
hasNewCheckout, err := client.IsFeatureActiveWithTracking(visitorCode, featureKey, false)
if err != nil {
switch err.(type) {
case *errs.VisitorCodeInvalid:
// 提供された訪問者コードが無効です。この訪問者には古いチェックアウトをトリガーします。
hasNewCheckout = false
case *errs.FeatureConfigNotFound:
// SDK が取得した設定ファイルにまだ機能キーが存在しません。この訪問者には古いチェックアウトをトリガーします。
hasNewCheckout = false
default:
// 予期しないエラーを処理
panic(err)
}
}
if hasNewCheckout {
// 新しいチェックアウトのコードをここに実装
}
```
`IsFeatureActive()` メソッドは、マスターフラグの状態ではなく、配信されたバリアントを評価します。ルールを除外する場合、メソッドは **その他の全員にはこれを配信** のデフォルト状態を使用します。このデフォルト状態に **Off** を選択した場合、マスター機能フラグが **On** であっても、このメソッドは常に `false` を返します。
##### 引数
| 名前 | 型 | 説明 |
| ------------------------ | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| visitorCode | string | ユーザーの一意の識別子。このフィールドは必須です。 |
| featureKey | string | ユーザーに公開したい機能のキー。このフィールドは必須です。 |
| isUniqueIdentifier (非推奨) | bool | visitorCode が一意の識別子であるかを指定するパラメータ。指定されない場合のデフォルト値は `false`。このフィールドはオプションです。 |
| track | bool | 機能評価の追跡を有効または無効にする `IsFeatureActiveWithTracking` メソッドのパラメータ。`IsFeatureActive(visitorCode, featureKey)` は `IsFeatureActiveWithTracking(visitorCode, featureKey, true)` と同等です。 |
##### 戻り値
| 型 | 説明 |
| ---- | ----------------------------------------- |
| bool | 指定された **visitorCode** に対して登録されている機能フラグの値。 |
##### スローされる例外
| 型 | 説明 |
| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| errs.FeatureConfigNotFound | このエラーは、要求された機能キーが SDK の内部設定で見つからなかったことを示します。これは通常、SDK によって機能フラグがまだ取得されていない場合に発生します。SDK が [ポーリング](/ja/developer-docs/feature-experimentation/technical-reference/technical-considerations#ポーリング（デフォルト）)モードの場合に発生する可能性があります。 |
| errs.VisitorCodeInvalid | このエラーは、提供された訪問者コードが無効である場合に返されます。つまり、空であるか、長さが 255 文字を超えています。 |
#### GetVariation()
* 📨 *Kameleoon にトラッキングデータを送信します(`GetVariationOptParams.Track` パラメータに依存)*
特定の機能フラグについて、指定された訪問者に割り当てられた [`Variation`](#variation) を取得します。
このメソッドは `visitorCode` と `featureKey` を必須引数として取ります。`GetVariationOptParams.Track` 引数はオプションで、デフォルトは `true` です。
訪問者に割り当てられた `Variation` を返します。訪問者がどの機能フラグルールにも関連付けられていない場合、メソッドは指定された機能フラグのデフォルト `Variation` を返します。
潜在的な例外を管理するために、コードに適切なエラー処理が実装されていることを確認してください。
デフォルトバリエーションとは、機能フラグの事前定義された配信ルールに一致しない訪問者に割り当てられるバリエーションのことです。言い換えれば、特定のルールでターゲットされていないすべてのユーザーに適用されるフォールバックバリエーションです。管理インターフェースの「その他の全員には...を配信」セクションのバリエーションとして表現されます。
```go theme={null}
const featureKey = "new_checkout"
variation, err := client.GetVariation(visitorCode, featureKey)
// トラッキングを無効化
variation, err := client.GetVariation(visitorCode, featureKey, NewGetVariationOptParams().Track(false))
if err != nil {
// エラー処理
}
// 割り当てられたバリエーションの変数値を取得
title := variation.Variables["title"].Value
switch (variation.Key) {
case "on":
// メインバリエーションキーが visitorCode に対して選択されています
case "alternative_variation":
// 代替バリエーションキー
default:
// デフォルトバリエーションキー
}
```
##### 引数
| 名前 | 型 | 説明 | デフォルト |
| ------------------------------------- | -------- | ----------------------------- | ------ |
| visitorCode (*必須*) | `string` | 訪問者の一意の識別子。 | |
| featureKey (*必須*) | `string` | 訪問者に公開したい機能のキー。 | |
| GetVariationOptParams.Track (*オプション*) | `bool` | 機能評価の追跡を有効または無効にするオプションパラメータ。 | `true` |
##### 戻り値
| 型 | 説明 |
| ----------- | -------------------------------------------------------------------- |
| `Variation` | 成功時は特定の機能フラグについて指定された訪問者に割り当てられた [`Variation`](#variation)、それ以外はエラー。 |
##### スローされる例外
| 型 | 説明 |
| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| `errs.VisitorCodeInvalid` | 提供された訪問者コードが無効であることを示す例外。空であるか、255 文字を超えています。 |
| `errs.FeatureNotFound` | 要求された機能キーが SDK の内部設定に見つからないことを示す例外。これは通常、機能フラグが Kameleoon アプリでアクティブ化されていない(ただし、機能を実装するコードはアプリケーションにすでにデプロイされている)ことを意味します。 |
| `errs.FeatureEnvironmentDisabled` | 訪問者の現在の環境(例: production、staging、development)で機能フラグが無効になっていることを示す例外。 |
#### GetVariations()
* 📨 *Kameleoon にトラッキングデータを送信します(`GetVariationsOptParams.Track` パラメータに依存)*
すべての機能フラグについて、指定された訪問者に割り当てられた [`Variation`](#variation) オブジェクトのマップを取得します。
このメソッドは、利用可能なすべての機能フラグを反復し、指定された訪問者に関連付けられた各フラグの割り当てられた `Variation` を返します。`visitorCode` を必須引数として取り、`GetVariationsOptParams.OnlyActive` と `GetVariationsOptParams.Track` はオプションです。
* `GetVariationsOptParams.OnlyActive` が `true` に設定されている場合、`GetVariations()` メソッドは、ユーザーが `off` バリエーションでバケッティングされていない場合に限り、機能フラグのバリエーションを返します。
* `GetVariationsOptParams.Track` パラメータは、メソッドがバリエーション割り当てを追跡するかどうかを制御します。デフォルトでは `true` に設定されています。`false` に設定されている場合、トラッキングは無効になります。
返されるマップは、機能フラグキーをキーとし、対応する `Variation` を値として持ちます。機能フラグにバリエーションが割り当てられていない場合、メソッドはそのフラグのデフォルト `Variation` を返します。
潜在的な例外を管理するために、適切なエラー処理を実装する必要があります。
デフォルトバリエーションとは、機能フラグの事前定義された配信ルールに一致しない訪問者に割り当てられるバリエーションのことです。言い換えれば、特定のルールでターゲットされていないすべてのユーザーに適用されるフォールバックバリエーションです。管理インターフェースの「その他の全員には...を配信」セクションのバリエーションとして表現されます。
```go theme={null}
variations, err := client.GetVariations(visitorCode)
// すべてのアクティブなバリエーション
variations, err := client.GetVariations(visitorCode, NewGetVariationsOptParams().OnlyActive(true))
// トラッキングを無効化
variations, err := client.GetVariations(visitorCode, NewGetVariationsOptParams().Track(false))
if err != nil {
// エラー処理
}
```
##### 引数
| 名前 | 型 | 説明 | デフォルト |
| ------------------------------------------- | -------- | ------------------------------------------------------------------ | ------- |
| visitorCode (*必須*) | `string` | 訪問者の一意の識別子。 | |
| GetVariationsOptParams.OnlyActive (*オプション*) | `bool` | アクティブ(`true`)またはすべて(`false`)の機能フラグに対するバリエーションを返すかどうかを示すオプションパラメータ。 | `false` |
| GetVariationsOptParams.Track (*オプション*) | `bool` | 機能評価の追跡を有効または無効にするオプションパラメータ。 | `true` |
##### 戻り値
| 型 | 説明 |
| ---------------------- | --------------------------------------------------------------------------------- |
| `map[string]Variation` | 成功時に、対応する機能のキーを使用して機能フラグの割り当てられた [`Variation`](#variation) オブジェクトを含むマップ、それ以外はエラー。 |
##### スローされる例外
| 型 | 説明 |
| ------------------------- | --------------------------------------------- |
| `errs.VisitorCodeInvalid` | 提供された訪問者コードが無効であることを示す例外。空であるか、255 文字を超えています。 |
##### 引数
| 名前 | 型 | 説明 |
| ----------- | ------ | ---------------------------------------------------------------------------------- |
| visitorCode | string | ユーザーの一意の識別子。このフィールドは必須です。 |
| OnlyActive | bool | アクティブ(`true`)またはすべて(`false`)の機能フラグに対するバリエーションを返すかどうかを示すオプションパラメータ(デフォルトは `false`)。 |
| Track | bool | 機能評価の追跡を有効または無効にするオプションパラメータ(デフォルトは `true`)。 |
##### 戻り値
| 型 | 説明 |
| ---------------------- | -------------------------------------------------------------- |
| `map[string]Variation` | 対応する機能のキーを使用して機能フラグの割り当てられた [`Variations`](#variation) を含むマップ。 |
##### スローされる例外
| 型 | 説明 |
| ------------------ | --------------------------------------------- |
| VisitorCodeInvalid | 提供された訪問者コードが無効であることを示す例外。空であるか、255 文字を超えています。 |
#### SetForcedVariation()
このメソッドを使用すると、標準の評価プロセスをバイパスして、特定の [`Variation`](#variation) をユーザーにプログラムで割り当てることができます。これは、通常の評価ロジックが不要、またはスキップする必要がある制御された実験で特に有用です。また、デバッグやカスタムテストなどのシナリオでも役立ちます。
**強制**バリエーションが設定されると、Kameleoon のリアルタイム評価ロジックを上書きします。セグメンテーション、ターゲティング条件、アルゴリズム計算などのプロセスはスキップされます。実験中にセグメンテーションとターゲティング条件を保持するには、代わりに `SetForcedVariationOptParams.ForceTargeting=false` を設定します。
**シミュレートされた**バリエーションは、実行順序で常に優先されます。**シミュレートされた**バリエーション計算がトリガーされると、それが最初に完全に処理および完了されます。
強制バリエーションは、評価されたバリエーションと同様に扱われます。標準の評価されたバリエーションと同様に、分析でトラッキングされ、ユーザーコンテキストに保存されるため、レポーティングの一貫性が保たれます。
特定の条件下(例: 無効なパラメータ、ユーザーコンテキスト、または内部の問題)で、メソッドが例外をスローする場合があります。アプリケーションの安定性と耐久性を確保するために、適切な例外処理が不可欠です。
**強制**バリエーションと **[シミュレートされた](#getvisitorcode)** バリエーションを区別することが重要です:
* **強制バリエーション**: 個別の実験に固有のものです。
* **シミュレートされたバリエーション**: 全体的な**機能フラグ**の結果に影響を与えます。
```go theme={null}
const experimentId = 9516
// 訪問者に対して実験 9516 でバリエーション "on" を強制します。
err := client.SetForcedVariation(visitorCode, experimentId, "on")
// 実験中にセグメンテーションとターゲティング条件を保持しながらバリエーション "on" を強制します。
err := client.SetForcedVariation(
visitorCode, experimentId, "on", NewSetForcedVariationOptParams().ForceTargeting(false),
)
// 訪問者に対して実験 9516 の強制バリエーションをリセットします。
err := client.SetForcedVariation(visitorCode, experimentId, "")
if err != nil {
// エラー処理
}
```
##### 引数
| 名前 | 型 | 説明 | デフォルト |
| ---------------------------------------------------- | -------- | ------------------------------------------------------------------------------ | ------ |
| visitorCode (*必須*) | `string` | 訪問者の一意の識別子。 | |
| experimentId (*必須*) | `int` | 評価プロセス中にターゲットされ選択される **実験 ID**。 | |
| variationKey (*必須*) | `string` | 実験の戻り値として強制される `Variation` に対応する **バリエーションキー**。値が `""` の場合、強制バリエーションはリセットされます。 | |
| SetForcedVariationOptParams.ForceTargeting (*オプション*) | `bool` | 実験のターゲティングを強制してスキップする(`true`)か、標準の評価プロセスとして適用する(`false`)かを示します。 | `true` |
##### スローされる例外
| 型 | 説明 |
| -------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| `errs.VisitorCodeInvalid` | 提供された訪問者コードが無効であることを示す例外。空であるか、255 文字を超えています。 |
| `errs.FeatureExperimentNotFound` | 要求された実験 ID が SDK の内部設定で見つからなかったことを示す例外。これは通常想定内で、ルールに対応する実験がまだ Kameleoon 側でアクティブ化されていないことを意味します。 |
| `errs.FeatureVariationNotFound` | 要求されたバリエーションキー(ID)が SDK の内部設定で見つからなかったことを示す例外。これは通常想定内で、バリエーションに対応する実験がまだ Kameleoon 側でアクティブ化されていないことを意味します。 |
#### EvaluateAudiences()
* 📨 *Kameleoon にトラッキングデータを送信します*
このメソッドは、利用可能なすべての Audiences Explorer セグメントに対して訪問者を評価し、一致する訪問者をトラッキングします。
`EvaluateAudiences()` は、**関連するすべての訪問者データが設定または更新された後**、機能のバリエーションを取得する、または機能フラグを確認する **直前** に呼び出す必要があります。このアプローチにより、訪問者が利用可能な最新のデータに対して評価されることを保証し、すべての基準に基づいた正確なオーディエンス割り当てが可能になります。
このメソッドを呼び出した後、Audiences Explorer でセグメントパフォーマンスの詳細な分析を実行できます。
```go theme={null}
if err := client.EvaluateAudiences(visitorCode); err != nil {
// エラー処理
}
```
##### 引数
| 名前 | 型 | 説明 |
| ------------------ | -------- | ----------- |
| visitorCode (*必須*) | `string` | 訪問者の一意の識別子。 |
##### スローされる例外
| 型 | 説明 |
| ------------------------- | --------------------------------------------- |
| `errs.VisitorCodeInvalid` | 提供された訪問者コードが無効であることを示す例外。空であるか、255 文字を超えています。 |
#### GetDataFile()
すべての機能フラグを評価するには、[`GetVariations()`](#getvariations) を使用します。このメソッドは、`DataFile` を呼び出してフラグを反復処理し [`GetVariation()`](#getvariation) を実行するよりも効率的です。
現在の SDK 設定を [`DataFile`](#datafile) オブジェクトとして返します。
```go theme={null}
dataFile := client.GetDataFile()
```
##### 戻り値
| 型 | 説明 |
| ---------- | --------------------------------- |
| `DataFile` | SDK 設定を含む [`DataFile`](#datafile) |
### 訪問者データ
#### GetVisitorCode()
このメソッドは以前 `ObtainVisitorCode` と呼ばれており、SDK バージョン `3.0.0` で削除されました。
特に Kameleoon を [ハイブリッドモード](/developer-docs/feature-experimentation/get-started/hybrid-experimentation/)で使用する場合のユーザー識別の一貫性を確保するために、現在の訪問者の Kameleoon `visitorCode` を取得するために [`GetVisitorCode()`](#getvisitorcode) メソッドを呼び出す必要があります。以下にその仕組みを説明します:
1. Kameleoon は、現在の HTTP リクエストに関連付けられた **kameleoonVisitorCode** クッキーがあるかどうかを確認します。見つかった場合、Kameleoon はこのコードを訪問者識別子として使用します。
2. クッキーが見つからない場合、メソッドは新しい識別子をランダムに生成するか、**defaultVisitorCode** 引数が渡された場合はそれを使用します。識別子を訪問者コードとして使用することで、追加の検索なしで Kameleoon 訪問者と自社のユーザーを一致させることができます。
3. 次に、サーバー側の **kameleoonVisitorCode** クッキーが HTTP ヘッダー経由で識別子値で設定され、メソッドが識別子値を返します。
詳細については、[こちらの記事](/developer-docs/feature-experimentation/get-started/hybrid-experimentation)を参照してください。
Kameleoon が生成した visitorCode を使用する代わりに、独自の `User ID` を提供する場合、User ID が一意であることを保証するのはあなたの責任です。SDK は一意性をチェックしません。提供する User ID は 255 文字を超えてはならないことに注意することが重要です。超過した文字数は例外を発生させます。
`GetVisitorCode()` メソッドを使用すると、訪問者に **シミュレートされた** バリエーションを設定できます。クッキー(**リクエスト** または **ドキュメント** からのもの)に `kameleoonSimulationFFData` キーが含まれている場合、標準の評価プロセスはバイパスされます。代わりに、メソッドは提供されたデータに基づいて [`Variation`](#variation) を直接返します。
シミュレーションは 2 つの方法で適用できます:
* **自動的に(推奨):** Kameleoon Web Experimentation または SDK を [ハイブリッドモード](/developer-docs/feature-experimentation/get-started/hybrid-experimentation#linking-feature-experiments-with-front-end-tracking-code) で使用している場合、[シミュレーションパネル](/user-manual/experimentation/feature-experimentation/using-the-rollout-planner/validation-and-rollback/using-simulation-mode) を使用してバリアントの表示をシミュレートすると、クッキーが自動的に作成されます。
* **手動で:** `kameleoonSimulationFFData` クッキーを手動で設定します。
**シミュレートされた**バリエーションと **[強制](#setforcedvariation)** バリエーションを区別することが重要です:
* **シミュレートされたバリエーション**: 全体的な**機能フラグ**の結果に影響を与えます。
* **強制バリエーション**: 個別の実験に固有のものです。
⚙️ **手動設定**
`kameleoonSimulationFFData` クッキーが以下の形式に従うことを確認してください:
* `kameleoonSimulationFFData={"featureKey":{"expId":10,"varId":20}}`: 指定された `featureKey` に対して、実験 `expId` の `varId` を持つバリエーションをシミュレートします。
* `kameleoonSimulationFFData={"featureKey":{"expId":0}}`: 指定された `featureKey` に対して、デフォルトバリエーション(**本番環境でその他の全員には...を配信** セクションで定義されたもの)をシミュレートします。
⚠️ 適切に機能させるために、クッキー値は [`encodeURIComponent`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/encodeURIComponent) などのメソッドを使用して URI コンポーネントとしてエンコードする必要があります。
```go theme={null}
visitorCode, err := client.GetVisitorCode(req, resp)
visitorCode, err := client.GetVisitorCode(req, resp, "defaultVisitorCode")
```
##### 引数
| 名前 | 型 | 説明 |
| ------------------ | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| request | \*fasthttp.Request | 現在の fasthttp.Request オブジェクトを最初のパラメータとして渡す必要があります。このフィールドは必須です。 |
| response | \*fasthttp.Response | 現在の fasthttp.Response オブジェクトを 2 番目のパラメータとして渡す必要があります。このフィールドは必須です。 |
| defaultVisitorCode | string | このパラメータは、リクエストに既存の **kameleoonVisitorCode** クッキーが見つからない場合に **visitorCode** として使用されます。このフィールドはオプションで、デフォルトではランダムな **visitorCode** が生成されます。 |
##### 戻り値
| 型 | 説明 |
| --------------- | --------------------------------------------------------------------- |
| (string, error) | この特定のユーザーに関連付けられる **visitorCode** とエラーのペア。SDK のほとんどのメソッドで使用する必要があります。 |
##### スローされる例外
| エラーメッセージ | 説明 |
| ----------------------- | ------------------------------------------------------------- |
| errs.VisitorCodeInvalid | このエラーは、提供された訪問者コードが無効である場合に返されます。つまり、空であるか、長さが 255 文字を超えています。 |
#### AddData()
`AddData()` メソッドは、他のメソッドが現在の訪問者をターゲットするかどうかを判断するために使用できる [ターゲティングデータ](#データ型) をストレージに追加します。
`AddData()` メソッドは値を返さず、それ自体では Kameleoon バックエンドサーバーと通信しません。代わりに、宣言されたすべてのデータは [`Flush*()`](#flushall--flushvisitor--flushvisitorinstantly) メソッドを使用して将来送信するために保存されます。このアプローチにより、データは通常 `Flush*()` によってトリガーされる単一のサーバーコールにグループ化されるため、行われるサーバーコール数が減少します。
[`TrackConversion()`](#trackconversion) メソッドも、`Flush*()` と同様に以前に関連付けられたデータを送信します。実験ルールがトリガーされた場合、[`GetVariation()`](#getvariation) および [`GetVariations()`](#getvariations) メソッドにも同じことが当てはまります。
各訪問者は、ほとんどのデータ型に対して 1 つの関連データインスタンスしか持つことができません。ただし、[`CustomData`](#customdata) は例外です。訪問者はインデックスごとに 1 つの関連 `CustomData` インスタンスを持つことができます。
```go theme={null}
import (
"github.com/Kameleoon/client-go/v3/types"
)
// 単一のデータ項目を追加(デフォルトでトラッキング)
client.AddData(visitorCode, types.NewBrowser(types.BrowserTypeChrome))
// 複数のデータ項目を追加(デフォルトでトラッキング)
client.AddData(visitorCode,
types.NewPageViewWithTitle("https://url.com", "title", 3),
types.UserAgent("UserAgent"),
)
// 複数のデータ項目をターゲティングのみのためにローカルに保存(Kameleoon Data API には送信されません)
client.AddDataWithOptParams(
visitorCode,
NewAddDataOptParams().Track(false),
types.NewPageViewWithTitle("https://url.com", "title", 3),
types.UserAgent("UserAgent")
)
```
##### 引数
| 名前 | 型 | 説明 | デフォルト値 |
| ------------------ | --------------- | --------------------------------------------------------------------------------------------------------------- | ------ |
| visitorCode (*必須*) | `string` | 訪問者の一意の識別子。 | |
| track (*オプション*) | `bool` | 追加されたデータがトラッキングの対象となるかどうかを指定します。`false` に設定された場合、データはローカルに保存され、ターゲティング評価にのみ使用されます。Kameleoon Data API には送信されません。 | `true` |
| allData (*必須*) | `...types.Data` | Kameleoon データ型のコレクション。 | |
##### 例外
| 型 | 説明 |
| ------------------------- | --------------------------------------------- |
| `errs.VisitorCodeInvalid` | 提供された訪問者コードが無効であることを示す例外。空であるか、255 文字を超えています。 |
#### FlushAll() / FlushVisitor() / FlushVisitorInstantly()
* 📨 *Kameleoon にトラッキングデータを送信します*
`FlushAll()/FlushVisitor()/FlushVisitorInstantly()` メソッドは、訪問者にリンクされた 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()` を呼び出すだけで済みます。
`FlushVisitor()/FlushVisitorInstantly()` メソッドは `visitorCode` を一意の訪問者識別子として使用します。これは[クロスデバイス実験](/developer-docs/cross-device-experimentation)に役立ちます。`visitorCode` を指定して `isUniqueIdentifier` パラメータを `true` に設定すると、SDK はフラッシュされたデータを指定された識別子に関連付けられた訪問者にリンクします。
`isUniqueIdentifier` パラメータは非推奨です。代わりに [`UniqueIdentifier`](#uniqueidentifier) を使用してください。
`isUniqueIdentifier` は固有の状況で役立つ場合があります。たとえば、訪問者に付与された匿名の `visitorCode` にアクセスできないものの、セッションマージを通じてその訪問者にリンクされた内部 ID を使用できる場合です。
```go theme={null}
import (
"github.com/Kameleoon/client-go/v3/types"
)
visitorCode, err := client.GetVisitorCode(req, resp)
client.AddData(visitorCode, types.NewBrowser(types.BrowserTypeChrome))
client.AddData(visitorCode, types.NewConversionWithRevenue(32, 10, false))
client.FlushVisitor(visitorCode) // 間隔トラッキング(最もパフォーマンスの高いトラッキング方法)
client.FlushAll() // すべての訪問者の未送信データに対する間隔トラッキング
client.FlushVisitorInstantly(visitorCode) // 即時トラッキング
client.FlushAll(true) // すべての訪問者の未送信データに対する即時トラッキング
// 一意の ID で操作する場合
client.AddData(types.NewUniqueIdentifier(true))
client.FlushVisitor(visitorCode)
```
##### 引数
| 名前 | 型 | 説明 |
| ------------------------ | ------ | ------------------------------------------------------------------------------------------------ |
| visitorCode | string | ユーザーの一意の識別子。このフィールドは `FlushVisitor()/FlushVisitorInstantly()` に必須です。 |
| isUniqueIdentifier (非推奨) | bool | `FlushVisitor` メソッドの、visitorCode が一意の識別子であるかを指定するパラメータ。指定されない場合のデフォルト値は `false`。このフィールドはオプションです。 |
##### スローされる例外
| 型 | 説明 |
| ----------------------- | ------------------------------------------------------------ |
| errs.VisitorCodeInvalid | この例外は、提供された訪問者コードが無効である場合に発生します。つまり、空であるか、長さが 255 文字を超えています。 |
#### GetRemoteData()
`GetRemoteData()` メソッドは、引数として渡された **key** に従って、指定された **siteCode**(`KameleoonClient` コンストラクタで指定されたもの)について Kameleoon のリモートサーバーに保存されている外部データを取得します。このキーは通常、Kameleoon 訪問者コードまたは User ID です。
このメソッドを使用して、ユーザー設定、履歴データ、または他のアプリケーションのロジックに関連するデータを取得できます。当社の Data API を使用してこのデータを高度にスケーラブルなサーバーに保存することで、大量のデータを効率的に管理し、すべての訪問者またはユーザーのデータを取得できます。
メソッドの戻り値は、`json.Unmarshal()` 関数を使用してデコードできる JSON オブジェクトです。このデータを使用して、機能フラグや実験の高度なターゲティングセグメントを構築したり、取得したデータに格納されている値に基づいて実験およびパーソナライゼーションレポートをフィルタリングしたりできます。
```go theme={null}
type Test1 struct {
Value string `json:"some field to insert or update"`
}
remoteData, err := s.client.GetRemoteData("USER_ID") // デフォルトタイムアウトを使用
var test1 Test1
err = json.Unmarshal(remoteData, &test1)
remoteData, err := s.client.GetRemoteData("USER_ID", 1000)
```
サーバーコールが必要なため、このメカニズムは非同期です。
Mixpanel、Segment、GA4 との組み込み統合を提供しており、外部コホートを取得して機能実験で利用できます。これらの統合で利用されるキーは、当社の訪問者コードまたは User ID のいずれかです。Mixpanel コホートを取得して利用するには、以下のサンプルコードを参照してください:
```go theme={null}
// Mixpanel コホートを取得して使用
type Cohort struct {
Id string `json:"mixpanel_cohort_id"`
Name string `json:"mixpanel_cohort_name"`
ProjectId string `json:"mixpanel_cohort_project_id"`
}
type MixPanelCohorts struct {
Cohorts []Cohort `json:"mixpanel_cohorts"`
}
remoteData, err := s.client.GetRemoteData("USER_ID")
var mixPanel MixPanelCohorts
if err = json.Unmarshal(remoteData, &mixPanel); err == nil {
cohorts := make([]string, len(mixPanel.Cohorts))
for _, cohort := range mixPanel.Cohorts {
cohorts = append(cohorts, cohort.Id)
}
client.AddData(visitorCode, types.NewCustomData(customDataIndex, cohorts...))
}
```
##### 引数
| 名前 | 型 | 説明 |
| ------- | ------ | ---------------------------------------------------------------------------------------------------------------------------- |
| key | string | 取得しようとしているデータが関連付けられているキー。このフィールドは必須です。このキーは通常、Kameleoon 訪問者コードまたは独自の User ID です。 |
| timeout | int | timeout パラメータは、メソッドが結果を待ってブロックできる最大時間(ミリ秒単位)を指定します。このフィールドはオプションです。指定されない場合、メソッドは [SDK の初期化時](#初期化)に提供されたデフォルトタイムアウト値を使用します。 |
##### 戻り値
| 型 | 説明 |
| ------- | ---------------------------------------------------------------------------------- |
| \[]byte | これは、特定の **key** に対するデータ取得に関連する情報を返します。結果は `json.Unmarshal()` 関数を使用してデコードする必要があります。 |
##### スローされる例外
| 型 | 説明 |
| ----- | ----------------------- |
| error | リクエストがタイムアウトしたことを示すエラー。 |
#### GetRemoteVisitorData()
`GetRemoteVisitorData()` は、Kameleoon Data API から `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 を使用できる場合です。
```go theme={null}
visitorCode := "visitorCode"
var visitorData []types.Data
var err error
// 訪問者データが取得され、`visitorCode` に自動的に追加されます
visitorData, err = client.GetRemoteVisitorData(visitorCode, true) // デフォルトタイムアウトが使用されます
visitorData, err = client.GetRemoteVisitorData(visitorCode, true, time.Second) // 1000 ミリ秒のタイムアウト
// データを取得して手動で追加したい場合のみ、`addData` を `false` に設定します。
visitorData, err = client.GetRemoteVisitorData(visitorCode, false) // デフォルトタイムアウトが使用されます
visitorData, err = client.GetRemoteVisitorData(visitorCode, false, time.Second) // 1000 ミリ秒のタイムアウト
// 一意の ID で操作する場合
client.AddData(types.NewUniqueIdentifier(true))
visitorData, err = client.GetRemoteVisitorData(visitorCode, true)
// カスタムリストのデータ型を取得したい場合
var visitorData = client.GetRemoteVisitorDataWithFilter(
visitorCode,
true,
types.RemoteVisitorDataFilter{PreviousVisitAmount: 10, CustomData: true, Conversion: true, Experiments: true},
// デフォルトタイムアウトが使用されます
)
// または
var visitorData = client.GetRemoteVisitorDataWithFilter(
visitorCode,
true,
types.RemoteVisitorDataFilter{PreviousVisitAmount: 10, CustomData: true, Conversion: true, Experiments: true},
time.Second, // 1000 ミリ秒のタイムアウト
)
```
##### GetRemoteVisitorData の引数
| 名前 | 型 | 説明 |
| ----------- | ------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| visitorCode | string | 割り当てられたデータを取得したい訪問者コード。このフィールドは必須です。 |
| addData | bool | メソッドが訪問者用に取得したデータを自動的に追加するかどうかを示すブール値。このフィールドは必須です。 |
| timeout | time.Duration | timeout パラメータは、メソッドが結果を待ってブロックできる最大時間(ミリ秒単位)を指定します。このフィールドはオプションです。指定されない場合、メソッドは [SDK の初期化時](#初期化)に提供されたデフォルトタイムアウト値を使用します。 |
##### GetRemoteVisitorDataWithFilter の引数
| 名前 | 型 | 説明 |
| ----------- | ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| visitorCode | string | 割り当てられたデータを取得したい訪問者コード。このフィールドは必須です。 |
| addData | bool | メソッドが訪問者用に取得したデータを自動的に追加するかどうかを示すブール値。このフィールドは必須です。 |
| filter | types.RemoteVisitorDataFilter | 訪問から取得するデータを指定するフィルター。このフィールドは必須です。 |
| timeout | time.Duration | timeout パラメータは、メソッドが結果を待ってブロックできる最大時間(ミリ秒単位)を指定します。このフィールドはオプションです。指定されない場合、メソッドは [SDK の初期化時](#初期化)に提供されたデフォルトタイムアウト値を使用します。 |
##### GetRemoteVisitorDataWithOptParams の引数
`GetRemoteVisitorDataWithOptParams` メソッドは非推奨です。代わりに [`GetRemoteVisitorDataWithFilter`](/developer-docs/sdks/web-sdks/go-sdk#arguments-of-getremotevisitordatawithfilter) と [`UniqueIdentifier`](#uniqueidentifier) を使用してください。
| 名前 | 型 | 説明 |
| ----------- | ------------------------------------ | --------------------------------------------------- |
| visitorCode | string | 割り当てられたデータを取得したい訪問者コード。このフィールドは必須です。 |
| addData | bool | メソッドが訪問者用に取得したデータを自動的に追加するかどうかを示すブール値。このフィールドは必須です。 |
| filter | types.RemoteVisitorDataFilter | 訪問から取得するデータを指定するフィルター。このフィールドは必須です。 |
| params | kameleoon.RemoteVisitorDataOptParams | オプションパラメータ。 |
`kameleoon.RemoteVisitorDataOptParams` のフィールドリストは次のとおりです:
| 名前 | 型 | 説明 |
| ---------------------------------- | --------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| IsUniqueIdentifier (*オプション*) (非推奨) | `bool` | visitorCode が一意の識別子であるかを指定するパラメータ。指定されない場合のデフォルト値は `false`。 |
| Timeout (*オプション*) | `time.Duration` | timeout パラメータは、メソッドが結果を待ってブロックできる最大時間(ミリ秒単位)を指定します。このフィールドはオプションです。指定されない場合、メソッドは [SDK の初期化時](#初期化)に提供されたデフォルトタイムアウト値を使用します。 |
`kameleoon.RemoteVisitorDataOptParams` のデフォルト値は `types.RemoteVisitorDataFilter{PreviousVisitAmount: 1, CurrentVisit: true, CustomData: true}` で、`types.DefaultRemoteVisitorDataFilter()` 関数で取得できます。
##### 戻り値
| 型 | 説明 |
| ------------- | ------------------------- |
| \[]types.Data | 指定された訪問者に割り当てられたデータのスライス。 |
| error | 発生したエラー。 |
##### GetRemoteVisitorData() でのパラメータの使用
`GetRemoteVisitorData()` メソッドは、訪問者のデータを取得する際にさまざまなパラメータを定義できる柔軟性を提供します。ゴール、実験、バリエーションに基づいてターゲットする場合でも、すべてのデータ型に対して同じアプローチが適用されます。
たとえば、「Order transaction」というゴールを完了した訪問者のデータを取得したいとします。`GetRemoteVisitorData()` メソッド内でパラメータを指定して、ターゲティングを絞り込むことができます。たとえば、過去 5 回の訪問でゴールでコンバージョンしたユーザーのみをターゲットする場合、`PreviousVisitAmount` パラメータを 5 に、`Conversions` を true に設定できます。
この例で示されている柔軟性は、ゴールデータに限定されません。`GetRemoteVisitorData()` メソッド内のパラメータを使用して、さまざまな訪問者の行動に関するデータを取得できます。
利用可能な `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 コンバージョンスコア(KCS)が取得されます。[AI 予測ターゲティングアドオン](/user-manual/ai-predictive-targeting/target-users-based-on-likelihood-to-convert) が必要です。 | `false` |
| VisitorCode (*オプション*) | `bool` | true の場合、Kameleoon は最新の訪問から `visitorCode` を取得し、現在の訪問に使用します。これは、訪問者(その `visitorCode` で識別される)が[クロスデバイス実験](/developer-docs/cross-device-experimentation)で訪問間で常に同じバリエーションを受け取ることを保証したい場合に必要です。 | `true` |
| Personalization (*オプション*) | `bool` | true の場合、パーソナライゼーションデータが取得されます。これはパーソナライゼーション条件に必要です。 | `false` |
| cbs (*オプション*) | `bool` | true の場合、コンテキストバンディットスコアデータが取得されます。 | `false` |
#### GetVisitorWarehouseAudience()
指定された `VisitorCode` と `WarehouseKey` を使用して、データウェアハウス内で訪問者に関連付けられたすべてのオーディエンスデータを取得します。`WarehouseKey` は通常、内部のユーザー ID です。`CustomDataIndex` パラメータは、Kameleoon が訪問者をターゲットするために使用する Kameleoon カスタムデータに対応します。追加の詳細については、[ウェアハウスターゲティングのドキュメント](/user-manual/integrations/data-warehouses/bigquery/use-bigquery-as-a-source-audience-targeting)を参照してください。このメソッドは `CustomData` オブジェクトを返し、データが訪問者に追加され、ターゲティング目的で利用可能であることを確認します。
```go theme={null}
customData, err = client.GetVisitorWarehouseAudience(VisitorWarehouseAudienceParams{
VisitorCode: "visitorCode",
CustomDataIndex: 10,
WarehouseKey: "warehouseKey", // オプション
Timeout: 5 * time.Second, // オプション
})
customData, err = c.GetVisitorWarehouseAudienceWithOptParams(
"visitorCode", 10, VisitorWarehouseAudienceOptParams{WarehouseKey: "warehouseKey", Timeout: 5 * time.Second})
```
##### GetVisitorWarehouseAudience の引数
| 名前 | 型 | 説明 |
| --------------- | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| VisitorCode | string | 一意の訪問者識別文字列。長さは 255 文字を超えてはいけません。 |
| CustomDataIndex | int | BigQuery オーディエンスのターゲット設定に使用するカスタムデータのインデックスを表す整数。 |
| WarehouseKey | string | ウェアハウスデータを識別するための一意のキー(通常、内部のユーザー ID)。このフィールドはオプションです。 |
| Timeout | time.Duration | timeout パラメータは、メソッドが結果を待ってブロックできる最大時間(ミリ秒単位)を指定します。このフィールドはオプションです。指定されない場合、メソッドは [SDK の初期化時](#初期化)に提供されたデフォルトタイムアウト値を使用します。このフィールドはオプションです。 |
##### GetVisitorWarehouseAudienceWithOptParams の引数
| 名前 | 型 | 説明 |
| --------------- | --------------------------------------------- | ------------------------------------------------- |
| visitorCode | string | 一意の訪問者識別文字列。長さは 255 文字を超えてはいけません。 |
| customDataIndex | int | BigQuery オーディエンスのターゲット設定に使用するカスタムデータのインデックスを表す整数。 |
| params | `kameleoon.VisitorWarehouseAudienceOptParams` | オプションパラメータ。 |
`kameleoon.VisitorWarehouseAudienceOptParams` のフィールドリストは次のとおりです:
| 名前 | 型 | 説明 |
| ------------ | --------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| WarehouseKey | `string` | ウェアハウスデータを識別するための一意のキー(通常、内部のユーザー ID)。このフィールドはオプションです。 |
| Timeout | `time.Duration` | timeout パラメータは、メソッドが結果を待ってブロックできる最大時間(ミリ秒単位)を指定します。このフィールドはオプションです。指定されない場合、メソッドは \[SDK の初期化時]に提供されたデフォルトタイムアウト値を使用します。このフィールドはオプションです。 |
`GetVisitorWarehouseAudience` メソッドの場合、一部のパラメータをオプション(`WarehouseKey` と `Timeout`)にするために、パラメータは `VisitorWarehouseAudienceParams` 構造体の `params` として関数に渡されます。
`GetVisitorWarehouseAudienceWithOptParams` メソッドの場合、オプションパラメータのみが `VisitorWarehouseAudienceOptParams` 構造体の `params` として関数に渡されます。
##### 戻り値
| 型 | 説明 |
| ------------------ | ----------------------------------------- |
| \*types.CustomData | データが訪問者に追加されたことを確認する `CustomData` インスタンス。 |
| error | 発生したエラー。 |
#### SetLegalConsent()
このメソッドを使用して、訪問者が個人データの使用に法的同意を与えたかどうかを指定する必要があります。`legalConsent` パラメータを `false` に設定すると、トラッキングリクエストに含めることができるデータタイプが制限されます。このメソッドは、訪問者データを責任を持って管理しながら、法的および規制上の要件に従うのに役立ちます。個人データに関する詳細は、[同意管理ポリシー](/user-manual/project-management/consent-management-policy)で確認できます。
```go theme={null}
visitorCode, err := kameleoonClient.GetVisitorCode(req, resp)
err := kameleoonClient.SetLegalConsent(visitorCode, true, resp)
```
##### 引数
| 名前 | 型 | 説明 |
| ----------- | ------------------- | ------------------------------------------------------------------------------------------------- |
| visitorCode | string | ユーザーの一意の識別子。このフィールドは必須です。 |
| consent | bool | 法的同意ステータスを表すブール値。`true` は訪問者が法的同意を与えたことを示し、`false` は訪問者が法的同意を提供したことがないか、撤回したことを示します。このフィールドは必須です。 |
| response | \*fasthttp.Response | 法的同意ステータスに基づいてクッキー内の値が調整される HTTP レスポンス。このフィールドはオプションです。 |
##### スローされる例外
| 型 | 説明 |
| ----------------------- | ------------------------------------------------------------- |
| errs.VisitorCodeInvalid | このエラーは、提供された訪問者コードが無効である場合に返されます。つまり、空であるか、長さが 255 文字を超えています。 |
##### 同意撤回の動作
`SetLegalConsent()` を `consent=false` で呼び出した場合、SDK は `kameleoonVisitorCode` クッキーを削除しません。代わりに、クッキーの有効期限の延長を停止し、クッキーが自然に期限切れになるまで持続できるようにします。
コンプライアンス要件としてオプトアウト時にクッキーファイルを即座に削除する必要がある場合は、フレームワークのネイティブクッキー管理メソッドを使用して手動で削除する必要があります。SDK はファイルを自動的に削除しません。
### ゴールとサードパーティ分析
#### TrackConversion()
* 📨 *Kameleoon にトラッキングデータを送信します*
このメソッドを使用して、特定の [ゴール](/user-manual//assets/goals/create-a-goal) およびユーザーのコンバージョンを追跡します。このメソッドには `visitorCode` と `goalId` が必要です。さらに、このメソッドはオプションの `TrackConversionOptParams.Revenue`、`TrackConversionOptParams.Negative`、`TrackConversionOptParams.Metadata` 引数も受け取ります。`visitorCode` は通常、実験をトリガーしたときに使用したものと同じです。
`TrackConversion()` メソッドは値を返しません。サーバーコールは非同期で行われるため、このメソッドは非ブロッキングです。
`isUniqueIdentifier` パラメータは非推奨です。代わりに [`UniqueIdentifier`](#uniqueidentifier) を使用してください。
`isUniqueIdentifier` は、他のエッジケースのシナリオでも役立つ場合があります。たとえば、訪問者に元々割り当てられた匿名の `visitorCode` にアクセスできないものの、セッションマージ機能を使用して匿名訪問者に接続されている内部 ID にアクセスできる場合です。
```go theme={null}
import (
"github.com/Kameleoon/client-go/v3/types"
)
const goalID = 83023
client.TrackConversion(visitorCode, goalID)
client.TrackConversionRevenue(visitorCode, goalID, 10.0)
// メタデータを追加
client.TrackConversionWithOptParams(visitorCode, goalID, TrackConversionOptParams{
Metadata: []*types.CustomData{
types.NewCustomData(3, "metadata1", "md2"),
types.NewCustomData(5, "md3")
},
})
```
##### 引数
| 名前 | 型 | 説明 | デフォルト |
| ------------------------------------------- | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| visitorCode (*必須*) | `string` | 訪問者の一意の識別子。 | |
| goalId (*必須*) | `int` | ゴールの ID。 | |
| TrackConversionOptParams.Revenue (*オプション*) | `float64` | コンバージョンの収益。 | `0` |
| TrackConversionOptParams.Negative (*オプション*) | `bool` | 収益が正か負かを定義します。 | `false` |
| TrackConversionOptParams.Metadata (*オプション*) | `[]*CustomData` | Kameleoon アプリでゴールのメタデータとして定義されたカスタムデータの特定の値を設定できます。例: `[CustomData{id: 5, value: "Payment Type"}, CustomData{id: 6, value: "Delivery Method"}]`。この例では、`5` と `9` はカスタムデータのインデックスです(5 = "Payment Type"、9 = "Delivery Method")。 | `nil` |
| isUniqueIdentifier *(非推奨)* | `bool` | visitorCode が一意の識別子であるかを指定するオプションパラメータ。 | `false` |
TrackConversionOptParams.Metadata の値は、[生データのエクスポート](/user-manual/experiment-analytics/analyze-results/results-page/results-page-actions#Export) と [結果ページ](/user-manual/experiment-analytics/analyze-results/data-and-metrics/goal-metadata) からアクセスできます。
`TrackConversionOptParams.Metadata` パラメータが提供された場合、Kameleoon は、以前に [`AddData()`](#adddata) メソッドを使用して収集されたものではなく、現在のコンバージョンに対してこれらの指定された値を使用します。パラメータが省略された場合、Kameleoon は同じ訪問内のコンバージョンの前に、これらの [`CustomData`](#customdata) について最後にトラッキングされた値を使用します。
Kameleoon は、`TrackConversion()` メソッドにパラメータとして明示的に渡されたメタデータ値のみを考慮します。
以下の例では、Kameleoon はパラメータとして明示的に提供されたカスタムデータ値(ここでは、値が「Amex Credit Card」のインデックス 5)のみをコンバージョンに関連付けます。
```go theme={null}
kameleoonClient.AddData(visitorCode, types.NewCustomData(5, "Credit Card"), types.NewCustomData(9, "Express Delivery"));
kameleoonClient.TrackConversionWithOptParams(visitorCode, 10, TrackConversionOptParams{
Metadata: []*types.CustomData{
types.NewCustomData(9, "Amex Credit Card"),
},
})
```
##### 例外
| 型 | 説明 |
| ------------------------- | --------------------------------------------- |
| `errs.VisitorCodeInvalid` | 提供された訪問者コードが無効であることを示す例外。空であるか、255 文字を超えています。 |
#### GetEngineTrackingCode()
Kameleoon は、Mixpanel、Google Analytics 4、Segment などのいくつかの分析ソリューションと統合されています。サーバー側の実験を正しく追跡するには、訪問者が実験をトリガーした後に `GetEngineTrackingCode()` メソッドを呼び出します。SDK は、前回の 5 秒間に訪問者がトリガーした実験の JavaScript キューコマンドを返します。このコードをページに挿入すると、Engine.js はコマンドを処理し、アクティブな分析統合を介して露出イベントを送信します。
このメソッドの実装の詳細については、[ハイブリッド実験](/developer-docs/feature-experimentation/get-started/hybrid-experimentation)を参照してください。
```go theme={null}
engineTrackingCode := kameleoonClient.GetEngineTrackingCode(visitorCode)
```
* この機能を使用するには、Go SDK と Kameleoon [Engine.js](/developer-docs/web-experimentation/implementation-and-deployment/standard-implementation) の両方を実装します。このフローでは Engine.js はトラッキングにのみ使用されるため、閉じる `` タグの前に非同期タグをインストールできます。
* Kameleoon でのみ実験を追跡し、サードパーティの分析ツールに露出イベントを送信する必要がない場合は、[JavaScript / TypeScript SDK](/developer-docs/sdks/web-sdks/js-sdk) を使用してください。このオプションは [サーバーレスエッジコンピュートプラットフォーム](/developer-docs/feature-experimentation/implementation-and-deployment/serverless-edge-compute-starter-kits) に適しています。JavaScript / TypeScript SDK は、[`getVisitorCode`](/developer-docs/sdks/web-sdks/js-sdk#getvisitorcode) を呼び出した際に、対応する実験割り当てを `window.kameleoonQueue` に追加していれば、自動的にバリエーションを追跡します。
* 返されたトラッキングコードは HTML の `