> ## 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.
# iOS SDK
> Kameleoon iOS SDK を統合して、ネイティブ Swift iOS アプリケーションで実験を実行し、機能フラグを有効化します。
Kameleoon iOS (Swift) SDK を使用すると、ネイティブモバイル iOS アプリケーション上で実験を実行し、機能フラグを有効化できます。SDK の Swift アプリへの統合は容易で、フットプリント(メモリおよびネットワーク使用量)も小さく抑えられています。
**はじめに**: 開始方法については、[開発者ガイド](#開発者ガイド)を参照してください。
**変更履歴**: Swift SDK の最新バージョン: 4.27.2 [変更履歴](https://github.com/Kameleoon/client-swift/blob/master/CHANGELOG.md)。
**SDK メソッド**: iOS SDK メソッドの完全なリファレンスドキュメントについては、[リファレンス](#リファレンス)セクションを参照してください。
## 開発者ガイド
Kameleoon iOS SDK をアプリケーションに初めてインストールし設定するには、次の手順に従ってください。
### はじめに
#### スターターキット
開始を支援するため、Kameleoon は SDK をテストするためのスターターキットとデモアプリケーションを提供しています。スターターキットには、SDK メソッドをアプリ内でどのように使用できるかを示すサンプル付きの完全に構成されたアプリが含まれています。スターターキット、デモアプリケーション、および詳細な手順は [iOS 用スターターキット](https://github.com/Kameleoon/ios-examples)で入手できます。
#### 前提条件
* iOS プラットフォームで Swift バージョン 5.0 以上を使用してください。それ以前の iOS アプリケーション(以前の Swift バージョンおよび Objective-C アプリを含む)はサポート予定はありません。x86\_64(iOS Simulator 用)および ARM(App Store への本番デプロイ用)の両方に対応する Universal Framework バージョンが利用可能です。
#### インストール
iOS SDK は CocoaPods または Swift Package Manager を使用してインストールできます:
CocoaPods を使用して、Podfile に以下のコードを貼り付け、`YOUR_TARGET_NAME` をアプリの値に置き換えます:
```swift theme={null}
# Podfile
use_frameworks!
target 'YOUR_TARGET_NAME' do
pod 'kameleoonClient'
end
```
次に、`Podfile` のあるディレクトリでコマンドプロンプトを開き、インストールコマンドを実行します:
```custom_code theme={null}
pod install
```
Swift Package Manager を使用して、Xcode プロジェクトにパッケージ依存関係を追加します。**File > Swift Packages > Add Package Dependency** を選択し、リポジトリ URL `https://github.com/Kameleoon/client-swift` を入力します。
または、`Package.swift` ファイルを直接変更することもできます:
```swift theme={null}
dependencies: [
.package(url: "https://github.com/Kameleoon/client-swift.git", from("3.0.3"))
]
```
***
#### 追加の設定
SDK の動作をカスタマイズするには、Xcode プロジェクトのルートディレクトリに `kameleoon-client-swift.plist` 設定ファイルを作成します。[サンプル設定ファイル](/assets/developer-docs/sdks/mobile-sdks/client-configs/kameleoon-client-swift.plist)をダウンロードすることもできます。
設定できるキーは以下の通りです:
| キー | 説明 | デフォルト値 |
| --------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------- |
| `refreshIntervalMinute` / `refresh_interval_minute` (*任意*) | SDK がアクティブな実験および機能フラグの構成を取得するための更新間隔を分単位で指定します。この値は、機能フラグの有効化または無効化、あるいは実験の開始などの変更が反映されるまでの最大時間を決定します。指定しない場合、デフォルトの間隔は 60 分です。さらに、サーバー送信イベント(SSE)を使用して新しい構成を SDK に自動的にプッシュし、リアルタイムで適用する[ストリーミングモード](/developer-docs/feature-experimentation/technical-reference/technical-considerations/#streaming-premium-option)も利用可能です。 | `60` 分 |
| `dataExpirationIntervalMinute` / `data_expiration_interval_minute` (*任意*) | SDK が訪問者および関連データを保存する事前定義された期間(分単位)を指定します。各データインスタンスは個別に評価されるため、SDK がデータを自動的に削除するまでの保存期間を設定できます。間隔が指定されていない場合、SDK はデバイスから自動的にデータを削除しません。 | `Date.distantFuture` |
| `defaultTimeoutMillisecond` / `default_timeout_millisecond` (*任意*) | SDK からのネットワークリクエストがタイムアウトするまでの時間間隔をミリ秒単位で指定します。安定した接続がない場合は、値を `30000` ミリ秒(30 秒)以上に設定してください。一部のメソッドには、メソッド固有のタイムアウト用の追加パラメータがありますが、明示的に指定しない場合はデフォルト値が使用されます。 | `10000` ms |
| `trackingIntervalMillisecond` / `tracking_interval_millisecond` (*任意*) | トラッキングリクエストの間隔をミリ秒単位で指定します。任意の機能フラグに対して評価された、またはデータがフラッシュされたすべての訪問者がこのトラッキングリクエストに含まれ、間隔ごとに 1 回実行されます。最小値は `1000` ms、最大値は `5000` ms です。 | `1000` ms |
| `environment` / `environment` (*任意*) | マルチ環境の実験および機能フラグを使用している顧客向けに、このオプションは使用する機能フラグ構成を指定します。デフォルトでは、各機能フラグには `production`、`staging`、`development` のオプションがあります。指定しない場合、デフォルト値は `production` です。[詳細情報](/user-manual/experimentation/feature-experimentation/configure-your-feature-flags/manage-environments)。 | `nil` |
| `isUniqueIdentifier` / `is_unique_identifier` (*任意*) | 指定された `visitorCode` が一意の識別子であることを示します。 | `false` |
| `networkDomain` / `network_domain` (*任意*) | 送信リクエスト用に SDK で使用されるカスタムドメインで、しばしばプロキシ用途で使用されます。有効なドメイン(例: example.com または sub.example.com)である必要があります。無効な形式の場合、Kameleoon の値がデフォルトとして使用されます。 | `nil` |
| `defaultDataFile` / `default_datafile` (*任意*) | `default_datafile` 機能は、キャッシュされたデータファイルが存在しない場合にフォールバック構成を提供することで、Kameleoon SDK が常に **READY** であることを保証します。開発者は `https://sdk-config.kameleoon.eu/v3/` から有効な構成を取得し、初期化時に `default_datafile` として渡すことで事前ロードできます。`dateModified` タイムスタンプ(ミリ秒単位)が提供され、キャッシュバージョンよりも新しい場合、SDK はキャッシュバージョンの代わりにデフォルトデータファイルを使用します。**`dateModified` が省略された場合、デフォルトデータファイルはキャッシュバージョンが存在しない場合にのみ適用されます**。これにより、SDK は常にデフォルト、キャッシュ、または更新済みのいずれかの有効な構成を保持します。 | `nil` |
| `activityTrackingIntervalMillisecond` / `activity_tracking_interval_millisecond` (*任意*) | SDK が訪問者のセッションを延長するためにアクティビティイベントを送信する頻度を設定します。この値の変更には副作用が生じる可能性があります。調整する前に [このセクション](#using-activitytrackingintervalmillisecond) を参照してください。最小値およびデフォルト値は `60 000` ms で、これより低い 0 以外の値は無視され、デフォルト値が適用されます。`0` に設定すると、定期的なアクティビティトラッキングは無効になり、この場合はアプリケーション起動時にアクティビティイベントが 1 回だけ送信されます。 | `60 000` ms |
`visitorCode` を指定し、`isUniqueIdentifier` パラメータを `true` に設定した場合、SDK メソッドは `visitorCode` 値を一意の訪問者識別子として使用します。これは[クロスデバイス実験](/developer-docs/cross-device-experimentation)に役立ちます。SDK は、フラッシュされたデータを指定された識別子に関連付けられた訪問者にリンクします。
`isUniqueIdentifier` は、他のエッジケースシナリオでも有用です。例えば、訪問者に元々割り当てられていた匿名の `visitorCode` にアクセスできないが、セッションマージを通じて匿名訪問者と結びつけられた内部 ID にはアクセスできる場合などです。
##### `activityTrackingIntervalMillisecond` の使用
activityTrackingIntervalMillisecond パラメータは、SDK が Data API 上の訪問者のセッションを延長するためにアクティビティイベントを送信する頻度を制御することで、ネットワーク使用量とバッテリー消費を削減するのに役立ちます。デフォルト値および許容される最小値は `60 000` ms (60 秒) で、これより低い 0 以外の値は無視され、デフォルト値が適用されます。アプリがバックグラウンドにある間はタイマーが一時停止するため、間隔はアプリがフォアグラウンドにあるときにのみ実質的に進行します。
#### Kameleoon クライアントの初期化
アプリケーションで SDK を設定した後、Kameleoon クライアントを作成する必要があります。クライアントは、アプリケーションと Kameleoon プラットフォームの間のブリッジとして機能するシングルトンオブジェクトです。実験を実行するために必要なすべてのメソッドとプロパティが含まれています。
```swift theme={null}
import kameleoonClient
let visitorCode = "visitorCode"
let siteCode = "a8st4f59bj"
do {
// pass client configuration as an argument
let config = try KameleoonClientConfig(
clientId: "clientId", // optional
clientSecret: "clientSecret", // optional
refreshIntervalMinute: 15, // optional, 60 minutes by default
dataExpirationIntervalMinute: 60*24*365, // optional, `Data.distantFuture` by default
defaultTimeoutMillisecond: 10_000, // optional, 10_000 milliseconds by default
trackingIntervalMillisecond: 500, // optional, 1000 milliseconds by default
environment: "production", // optional
isUniqueIdentifier: false, // optional, false by default. Set to true if the visitorCode corresponds to your customer's unique userId.
networkDomain: "example.com", // optional, nil by default
defaultDataFile: "{...}", // optional, nil by default
activityTrackingIntervalMillisecond: 20_000 // optional, 15_000 milliseconds by default
)
let kameleoonClient = try KameleoonClientFactory.create(
siteCode: siteCode,
visitorCode: visitorCode, // optional
config: config // optional
)
} catch KameleoonError.visitorCodeInvalid {
// Provided visitor code is invalid
} catch KameleoonError.siteCodeIsEmpty {
// Indicates that provided site code is empty
} catch {
// Unexpected error occurred
}
do {
// read client configuration from a file 'kameleoon-client-swift.plist'
// visitor code isn't provided, so SDK generates a random visitor code which it will use in the future
let kameleoonClient = try KameleoonClientFactory.create(siteCode: siteCode)
} catch KameleoonError.visitorCodeInvalid {
// Provided visitor code is invalid
} catch {
// Unexpected error occurred
}
```
`KameleoonClientFactory.create()` メソッドはクライアントを初期化しますが、クライアントはすぐには使用準備が整いません。クライアントは、Kameleoon リモートサーバーから現在のアクティブな実験および機能フラグの構成(トラフィック分配を含む)を取得する必要があります。この取得には、クライアントがネットワークアクセスを持つ必要があり、これは常に利用可能とは限りません。Kameleoon クライアントが完全に準備できるまで、Kameleoon iOS SDK の他のメソッドを実行しようとしてはいけません。クライアントが最初の機能フラグ構成を取得した後、定期的に構成を更新します。何らかの理由で更新に失敗した場合、Kameleoon クライアントは以前の構成を使用して機能し続けます。
`.ready` パブリックゲッターを使用して、Kameleoon クライアントの初期化が完了したかどうかを確認できます。
あるいは、**ヘルパーコールバック**を使用して、実験のトリガーとバリエーション実装のロジックをカプセル化することもできます。最良のアプローチ(`.ready` または**コールバック**)は、好みとユースケースによって異なります。SDK がまもなく使用可能になることが予想される場合は、`.ready` を使用することを推奨します。例えば、アプリ内をナビゲートしてから数秒または数分後にのみアクセス可能なダイアログで実験を実行する場合、`.ready` が適しています。実験に到達したときに SDK がまだ初期化中である可能性が高い場合は、コールバックを推奨します。例えば、アプリの起動時に表示される実験では、SDK が準備完了するか指定されたタイムアウトが経過するまでアプリケーションを待機させるコールバックを使用する必要があります。
クライアントが準備できる前にメソッドを呼び出さないようにするのは、アプリ開発者であるあなたの責任です。良い慣習として、Kameleoon クライアントがまだ準備できていない場合、アプリユーザーは実験から除外されるべきであると常に想定することです。この除外は、上記のコードサンプルに示すように、デフォルトの参照バリエーションロジックの実装に対応するため、簡単に実行できます。
これで、機能管理および機能フラグを実装する準備が整いました。追加メソッドの詳細については、[リファレンス](#リファレンス)セクションを参照してください。
#### 初期化と使用に関するベストプラクティス
* [`KameleoonClient`](#create) は、初期化に時間がかかる可能性があるため、アプリケーション開始後できるだけ早くシングルトンとして初期化することを推奨します。初期化は非同期で行われるため、アプリケーションの起動プロセスをブロックしたり遅延させたりすることはありません。
* `KameleoonClient` を使用する前に、[`runWhenReady`](#runwhenready) メソッドを呼び出して初期化されていることを確認してください。そうしないと、準備完了前にクライアントを使用しようとするとエラーが発生します。
* ⚠️ ほとんどの主要なメソッドはエラーをスローする可能性があるため、適切な例外処理が必要です。使用する各メソッドの潜在的なエラーを理解するために、必ずドキュメントを確認してください。
```swift theme={null}
// Initialize `KameleoonClient` on application startup and use it as a singleton later
do {
let kameleoonClient = try KameleoonClientFactory.create(siteCode: "");
} catch {}
// Example: Apply a discount percentage based on an feature flag variable's value
func applyDiscountIfApplicable() {
client.runWhenReady(timeoutMilliseconds: 1000) { ready in
guard ready else { return }
if let variation = try? client.getVariation(featureKey: "discount"),
let discount = variation.variables["discount_value"]?.value as? Double {
applyDiscount(value: discount)
}
}
}
```
```swift theme={null}
// Initialize `KameleoonClient` on application startup and use it as a singleton later
do {
let kameleoonClient = try KameleoonClientFactory.create(siteCode: "");
} catch {}
// Example: Apply a discount percentage based on an feature flag variable's value
func applyDiscountIfApplicable() async throws {
try await client.runWhenReady(timeoutMilliseconds: 1000)
if let variation = try client.getVariation(featureKey: "discount"),
let discount = variation.variables["discount_value"]?.value as? Double {
applyDiscount(value: discount)
}
}
```
#### 機能フラグの有効化
##### フラグ構成の取得
コードに機能フラグを実装するには、まず Kameleoon アカウントで機能フラグを作成する必要があります。
特定のユーザーに対する機能フラグのステータスまたはバリエーションを判別するには、[`getVariation()`](#getvariation) または [`isFeatureActive()`](#isfeatureactive) メソッドを使用して、`featureKey` に基づいて構成を取得する必要があります。
`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) メソッドを使用して、これらのデータポイントをユーザーのプロファイルに追加します。
他のデバイスで収集されたデータポイントを取得するには、[`getRemoteVisitorData()`](#getremotevisitordata) メソッドを使用します。このメソッドは、サーバーからデータを非同期に取得します。`getRemoteVisitorData()` を呼び出すことは、バリエーションを取得したり機能フラグがアクティブかどうかを確認したりする*前に*行うことが重要です。このデータは、ユーザーを特定のバリエーションに割り当てるために必要な場合があるためです。
利用可能なターゲティング条件の詳細については、[このトピックに関する詳細な記事](/developer-docs/feature-experimentation/targeting-and-segmentation/native-segmentation)を参照してください。
さらに、訪問者プロファイルに追加したデータポイントは、実験を分析する際に利用可能になり、デバイスなどの要因で結果をフィルタリングおよび分解できます。完全なリストは[こちら](/ja/user-manual/experiment-analytics/analyze-results/results-page/results-page-settings#オーディエンスの分割)を参照してください。
自動的に収集されるもの以外の追加のデータポイントをトラッキングする必要がある場合は、Kameleoon の[カスタムデータ機能](#customdata)を使用できます。カスタムデータを使用すると、実験に関連する特定の情報をキャプチャして分析できます。収集したデータを分析のために Kameleoon サーバーに送信するには、[`flush()`](#flush) メソッドの呼び出しを忘れないでください。
##### ゴールコンバージョンのトラッキング
ユーザーが目的のアクション(購入など)を完了した場合、それはコンバージョンとして記録されます。コンバージョンをトラッキングするには、[`trackConversion()`](#trackconversion) メソッドを使用し、必須の `goalId` パラメータを指定します。
コンバージョントラッキングリクエストは、SDK が定期的に送信する次にスケジュールされたトラッキングリクエスト([`tracking_interval_millisecond`](#追加の設定) で定義) と一緒に送信されます。リクエストを即座に送信したい場合は、`instant=true` パラメータを指定して [`flush()`](#flush) メソッドを使用してください。
### クロスデバイス実験
複数のデバイスからアプリにアクセスする訪問者をサポートするため、Kameleoon は以前に収集した訪問者データを各デバイス間で同期し、クロスデバイス実験を通じてデバイス間の訪問履歴を統合できます。Kameleoon がデバイス間でデータをどのように扱うかに関するケーススタディと詳細情報は、[クロスデバイス実験に関する記事](/developer-docs/cross-device-experimentation)で利用できます。
#### デバイス間でのカスタムデータの同期
カスタムマッピング同期はデバイス間で訪問者データを整合させるために使用されますが、必ずしも必要ではありません。以下は、カスタムマッピング同期が不要な 2 つのシナリオです:
**デバイス間で同じユーザー ID**
すべてのデバイスで同じユーザー ID が一貫して使用されている場合、カスタムマッピング同期なしで同期が自動的に処理されます。複数のデバイス間で収集されたデータを同期したい場合は、`getRemoteVisitorData()` メソッドを呼び出すだけで十分です。
**一貫した ID を持つマルチサーバーインスタンス**
複数のサーバー(例えば、分散サーバーインスタンス)が関与する複雑なセットアップで、サーバー間で同じユーザー ID が利用できる場合、追加のカスタムマッピング同期なしで、サーバー間の同期(`getRemoteVisitorData()` を使用)で十分です。
追加のデータが必要な顧客は、[`getRemoteVisitorData()`](#getremotevisitordata) メソッドの説明を参照してください。以下のコードでは、正確なデータ取得のために、2 つのデバイス間で同じ一意の識別子(この場合は `visitorCode`、`userId` とも呼ばれる)が一貫して使用されていると仮定しています。
収集されたデータをリアルタイムで同期したい場合は、カスタムデータのスコープに\*\*訪問者(Visitor)\*\*を選択する必要があります。
```swift title="Device A" theme={null}
// In this example, Custom data with index `90` was set to "Visitor" scope in Kameleoon.
let visitorScopeCustomDataIndex = 90
kameleoonClient.addData(CustomData(id: visitorScopeCustomDataIndex, values: "your data"))
kameleoonClient.flush()
```
```swift title="Device B" theme={null}
// Before working with the data, call `getRemoteVisitorData`.
kameleoonClient.getRemoteVisitorData { result in
// After calling, the SDK on Device B will have access to CustomData of Visitor scope defined on Device A.
// So, "your data" will be available to target and track the visitor.
}
```
```swift title="Device A" theme={null}
// In this example, Custom data with index `90` was set to "Visitor" scope in Kameleoon.
let visitorScopeCustomDataIndex = 90
kameleoonClient.addData(CustomData(id: visitorScopeCustomDataIndex, values: "your data"))
kameleoonClient.flush()
```
```swift title="Device B" theme={null}
// Before working with the data, call `getRemoteVisitorData`.
try await kameleoonClient.getRemoteVisitorData()
// After calling, the SDK on Device B will have access to CustomData of Visitor scope defined on Device A.
// So, "your data" will be available to target and track the visitor.
```
#### セッションマージのためのカスタムデータの使用
[クロスデバイス実験](/developer-docs/cross-device-experimentation)は、訪問者の各デバイスにわたる履歴を結合(履歴調整)することを可能にします。履歴調整により、異なる訪問者セッションを 1 つにマージできます。訪問履歴を調整するには、[`CustomData`](#customdata) を使用して訪問者の一意の識別子を提供します。詳細については、[専用ドキュメント](/developer-docs/cross-device-experimentation/#activating-cross-device-history-reconciliation)を参照してください。
クロスデバイス調整が有効になった後、`userId` パラメータを指定して [`getRemoteVisitorData()`](#getremotevisitordata) を呼び出すと、指定されたユーザーの既知のすべてのデータを取得できます。
同じ識別子を持つセッションは、実験で常に同じバリエーションが表示されます。実験結果ページの訪問者ビューでは、これらのセッションは単一の訪問者として表示されます。
SDK の構成により、関連するセッションは常に実験の同じバリエーションを参照するようになります。ただし、クロスデバイスバリエーション割り当てに関するいくつかの制限があります。これらの制限は[こちら](/developer-docs/cross-device-experimentation#critical-points-and-practical-insights)に記載されています。
Kameleoon プラットフォーム上でカスタムデータを設定するには、[クロスデバイス履歴調整の有効化](#クロスデバイス実験)ガイドに従ってください。
その後、通常通り SDK を使用できます。セッションマージのコンテキストで役立つ可能性のあるメソッドは以下の通りです:
* `getRemoteVisitorData()` に `isUniqueIdentifier=true` を [`KameleoonClientConfig`](#追加の設定) に渡す - すべてのリンクされた訪問者のデータを取得します。
* [`trackConversion()`](#trackconversion) または [`flush()`](#flush) に `isUniqueIdentifier=true` を `KameleoonClientConfig` に渡す - 別の訪問者に関連付けられた特定の訪問者の一部のデータをトラッキングします。
識別子として使用するカスタムデータは\*\*訪問者スコープ(Visitor scope)\*\*に設定する必要があるため、各デバイスで [`getRemoteVisitorData()`](#getremotevisitordata) メソッドを使用して識別子を取得するには、[クロスデバイスカスタムデータ同期](/developer-docs/cross-device-experimentation)を使用する必要があります。
セッションマージのためのカスタムデータの使用例は以下の通りです。
```swift theme={null}
// In this example, `91` represents the Custom Data's index,
// configured as a unique identifier in Kameleoon.
let mappingIndex = 91;
let featureKey = "ff123";
// 0. Initializing anonymous KameleoonClient
// Assume `anonymousVisitorCode` is the randomly generated ID for the visitor.
let anonymousKameleoonClient = KameleoonClientFactory.create(
siteCode: siteCode,
visitorCode: anonymousVisitorCode
)
anonymousKameleoonClient.runWhenReady { result in
// ...
}
// 1. Before the visitor is authenticated
// Retrieve the variation for an unauthenticated visitor.
let anonymousVariation = anonymousKameleoonClient.getVariation(featureKey)
// 2. After the visitor is authenticated
// Assume `userId` is the visitor code of the authenticated visitor.
anonymousKameleoonClient.addData(CustomData(id: mappingIndex, values: userId))
anonymousKameleoonClient.flush(instant: true)
KameleoonClient userKameleoonClient = KameleoonClientFactory.create(
siteCode: siteCode,
visitorCode: userId,
config: KameleoonClientConfig(
isUniqueIdentifier: true // Indicate that `userId` is a unique identifier
)
)
userKameleoonClient.runWhenReady { result in
// ...
}
// 3. After the visitor has been authenticated
// Retrieve the variation for the `userId`, which will match the anonymous visitor code's variation.
let userVariation = userKameleoonClient.getVariation(featureKey: featureKey)
let isSameVariation = userVariation.key == anonymousVariation.key // true
// The `userId` and `anonymousVisitorCode` are now linked and tracked as a single visitor.
userKameleoonClient.trackConversion(goalId: 123, revenue: 10.0);
// Additionally, the linked visitors will share all fetched remote visitor data.
userKameleoonClient.getRemoteVisitorData { result in
// ...
}
```
```swift theme={null}
// In this example, `91` represents the Custom Data's index,
// configured as a unique identifier in Kameleoon.
let mappingIndex = 91;
let featureKey = "ff123";
// 0. Initializing anonymous KameleoonClient
// Assume `anonymousVisitorCode` is the randomly generated ID for the visitor.
let anonymousKameleoonClient = KameleoonClientFactory.create(
siteCode: siteCode,
visitorCode: anonymousVisitorCode
)
try await anonymousKameleoonClient.runWhenReady()
// 1. Before the visitor is authenticated
// Retrieve the variation for an unauthenticated visitor.
let anonymousVariation = anonymousKameleoonClient.getVariation(featureKey)
// 2. After the visitor is authenticated
// Assume `userId` is the visitor code of the authenticated visitor.
anonymousKameleoonClient.addData(CustomData(id: mappingIndex, values: userId))
anonymousKameleoonClient.flush(instant: true)
KameleoonClient userKameleoonClient = KameleoonClientFactory.create(
siteCode: siteCode,
visitorCode: userId,
config: KameleoonClientConfig(
isUniqueIdentifier: true // Indicate that `userId` is a unique identifier
)
)
try await userKameleoonClient.runWhenReady()
// 3. After the visitor has been authenticated
// Retrieve the variation for the `userId`, which will match the anonymous visitor code's variation.
let userVariation = userKameleoonClient.getVariation(featureKey: featureKey)
let isSameVariation = userVariation.key == anonymousVariation.key // true
// The `userId` and `anonymousVisitorCode` are now linked and tracked as a single visitor.
userKameleoonClient.trackConversion(goalId: 123, revenue: 10.0);
// Additionally, the linked visitors will share all fetched remote visitor data.
try await userKameleoonClient.getRemoteVisitorData()
```
この例では、アプリケーションにログインページがあります。ログイン時点ではユーザー ID が不明であるため、SDK によって自動的に生成された匿名訪問者が使用されます。訪問者コードは [`getVisitorCode()`](#getvisitorcode) メソッドで取得できます。ユーザーがログインした後、匿名訪問者はユーザー ID に関連付けられ、その訪問者の一意の識別子として使用されます。
### カスタムバケットキーの使用
デフォルトでは、Kameleoon は一意の匿名訪問者 ID(`visitorCode`)を使用して、ユーザーを機能フラグのバリエーションに割り当てます。この ID は通常、ユーザーのデバイス上で生成および保存されます(クライアントサイドおよびサーバーサイド SDK ではブラウザの cookie に、モバイル SDK では永続ストレージに)。ただし、特定のシナリオでは、同じ組織のすべてのユーザーが同じ機能フラグのバリアントを参照することを保証する必要がある場合があります。
**カスタムバケットキー**オプションを使用すると、独自のカスタム識別子をバケッティングに提供することで、このデフォルトの動作を上書きできます。この上書きにより、Kameleoon の割り当てロジックはデフォルトの `visitorCode` の代わりに指定されたキーを使用するようになります。
#### ユースケース
カスタムバケットキーの使用は、特に以下の状況で、機能フラグ割り当ての一貫性と正確性を維持するために不可欠です:
* **アカウントレベルまたは組織レベルの実験:** B2B 製品または同じ組織のすべてのユーザーを同じバリエーションに割り当てたいシナリオでは、`accountId` などの識別子を使用できます。カスタムバケットキーは、チームまたは企業全体に影響する機能の A/B テストには不可欠です。
カスタムバケットキーを実装することで、実験の一貫性と正確性が向上し、より信頼性の高い結果とより良いユーザー体験が得られます。
#### 技術的な詳細
機能フラグにカスタムバケットキーを設定すると、アプリケーションのデータからの特定の識別子を Kameleoon に提供することになります:
```swift theme={null}
try? kameleoonClient.addData(CustomData(id: index, values: "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 は、ログレベルによるロギングの制限の構成をサポートしています。
```swift theme={null}
// The `none` log level does not allow logging.
KameleoonLogger.logLevel = .none
// The `ERROR` log level only allows logging issues that may affect the SDK's main behaviour.
KameleoonLogger.logLevel = .error
// The `WARNING` log level allows logging issues which may require additional attention.
// It extends the `ERROR` log level.
// The `WARNING` log level is a default log level.
KameleoonLogger.logLevel = .warning
// The `INFO` log level allows logging general information on the SDK's internal processes.
// It extends the `WARNING` log level.
KameleoonLogger.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 support
// to assist with internal troubleshooting.
KameleoonLogger.logLevel = .debug
```
#### ログのカスタム処理
SDK はデフォルトでログをコンソール出力に書き込みます。この動作はオーバーライドできます。
ログレベルによるロギング制限は、ログ処理ロジックとは別に実行されます。
```swift theme={null}
public struct CustomLogger: Logging {
let customLogger = Logger(subsystem: "com.yourcompany.app", category: "app")
public func log(level: LogLevel, message: String) {
switch level {
case .error:
customLogger.error("\(message)")
case .warning:
customLogger.warning("\(message)")
case .info:
customLogger.info("\(message)")
case .debug:
customLogger.debug("\(message)")
default:
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.
KameleoonLogger.logLevel = .debug // Optional, defaults to `LogLevel.WARNING`.
KameleoonLogger.logger = CustomLogger()
```
### 訪問者コードを WebView に渡す
場合によっては、[Engine.js](/developer-docs/web-experimentation/implementation-and-deployment/standard-implementation) や Web 用 [JavaScript](/developer-docs/sdks/web-sdks/js-sdk) または [React](/developer-docs/sdks/web-sdks/react-js-sdk) SDK を使用する WebView にネイティブアプリケーションから**訪問者コード**を渡す必要がある場合があります。次の例は、これを実現するための推奨方法を示しています:
```swift theme={null}
struct WebView: UIViewRepresentable {
let url: URL
let kameleoonClient: KameleoonClient
private let kameleoonCookieName = "kameleoonVisitorCode"
func makeUIView(context: Context) -> WKWebView {
let config = WKWebViewConfiguration()
let webView = WKWebView(frame: .zero, configuration: config)
let cookieStore = webView.configuration.websiteDataStore.httpCookieStore
let cookie = makeVisitorCookie()
cookieStore.setCookie(cookie) {
webView.load(URLRequest(url: url))
}
return webView
}
func updateUIView(_ webView: WKWebView, context: Context) {}
private func makeVisitorCookie() -> HTTPCookie {
let properties: [HTTPCookiePropertyKey: Any] = [
.domain: ".example.com",
.path: "/",
.name: kameleoonCookieName,
.value: kameleoonClient.visitorCode,
.secure: true,
.expires: Date(timeIntervalSinceNow: 60 * 60 * 24 * 365)
]
return HTTPCookie(properties: properties)!
}
}
```
```swift theme={null}
struct WebView: View {
let url: URL
let kameleoonClient: KameleoonClient
private let websiteDataStore: WKWebsiteDataStore
private let kameleoonCookieName = "kameleoonVisitorCode"
@State private var page: WebPage
init(url: URL, kameleoonClient: KameleoonClient) {
self.url = url
self.kameleoonClient = kameleoonClient
let websiteDataStore = WKWebsiteDataStore.default()
var configuration = WebPage.Configuration()
configuration.websiteDataStore = websiteDataStore
self.websiteDataStore = websiteDataStore
_page = State(initialValue: WebPage(configuration: configuration))
}
var body: some View {
WebView(page)
.webViewBackForwardNavigationGestures(.enabled)
.task(id: url) {
let cookieStore = websiteDataStore.httpCookieStore
let properties: [HTTPCookiePropertyKey: Any] = [
.domain: ".example.com",
.path: "/",
.name: kameleoonCookieName,
.value: kameleoonClient.visitorCode,
.secure: true
]
if let cookie = HTTPCookie(properties: properties) {
await cookieStore.setCookie(cookie)
}
page.load(URLRequest(url: url))
}
}
}
```
### Apple プライバシーコンプライアンス
2024 年 5 月 1 日以降、Apple は Kameleoon iOS SDK のようなサードパーティ SDK を含むアプリにプライバシーマニフェストファイルを含めることを要求しています。SDK の最新バージョンはコード署名され、コンプライアンスに準拠しており、SDK と一緒に有効なマニフェストファイルが含まれています。Kameleoon iOS SDK バージョン 4.2 以降を使用している場合、アクションは必要ありません。
## リファレンス
これは Kameleoon iOS (Swift) SDK の完全なリファレンスドキュメントです。
### 初期化
アプリケーションに [SDK をインストール](#インストール)した後、Kameleoon を初期化する必要があります。実験のトリガーなど、アプリケーションと SDK の間のすべてのやり取りは、この Kameleoon クライアントオブジェクトを使用して行います。
#### create()
SDK を初期化するには、他のメソッドの前にこのメソッドを呼び出します。このメソッドは `KameleoonClientFactory` にあります。`create()` は、SDK とアプリ間のすべてのやり取りを管理する `KameleoonClient` のインスタンスを作成します。
[構成オブジェクト](#追加の設定)を提供することで SDK の動作(例えば、環境、認証情報)をカスタマイズできます。それ以外の場合、SDK は構成ファイルを探し、それを代わりに使用します。
```swift theme={null}
let visitorCode = "visitorCode"
let siteCode = "a8st4f59bj"
do {
// pass client configuration as an argument
let config = try KameleoonClientConfig(
clientId: "clientId", // optional
clientSecret: "clientSecret", // optional
refreshIntervalMinute: 15, // optional, 60 minutes by default
dataExpirationIntervalMinute: 60*24*365, // optional, `Data.distantFuture` by default
defaultTimeoutMillisecond: 10_000, // optional, 10_000 milliseconds by default
trackingIntervalMillisecond: 500, // optional, 1000 milliseconds by default
environment: "production", // optional
isUniqueIdentifier: false, // optional, false by default. Set to true if the visitorCode corresponds to your customer's unique userId.
networkDomain: "example.com", // optional, nil by default
defaultDataFile: "{...}", // optional, nil by default
activityTrackingIntervalMillisecond: 20_000 // optional, 15_000 milliseconds by default
)
let kameleoonClient = try KameleoonClientFactory.create(
siteCode: siteCode,
visitorCode: visitorCode, // optional
config: config // optional
)
} catch KameleoonError.visitorCodeInvalid {
// Provided visitor code is invalid
} catch KameleoonError.siteCodeIsEmpty {
// Indicates that provided site code is empty
} catch {
// Unexpected error occurred
}
do {
// read client configuration from a file 'kameleoon-client-swift.plist'
// visitor code isn't provided, so SDK generates a random visitor code which will be used in the future
let kameleoonClient = KameleoonClientFactory.create(siteCode: siteCode)
} catch KameleoonError.visitorCodeInvalid {
// Provided visitor code is invalid
} catch KameleoonError.siteCodeIsEmpty {
// Indicates that provided site code is empty
} catch {
// Unexpected error occurred
}
```
##### 引数
| 名前 | 型 | 説明 | デフォルト |
| ------------------ | ------------------------ | ----------------------------------------------------------------------------------------------------------------------------- | ----- |
| siteCode (*必須*) | `String` | SDK で使用される Kameleoon プロジェクトを識別する[一意のキー](/user-manual/faq#how-do-i-find-my-sitecode)。 | |
| visitorCode (*任意*) | `String?` | 任意の訪問者識別子。利用可能であれば、内部の **ユーザー ID** を使用してください。それ以外の場合、SDK が自動的に生成します。 | `nil` |
| config (*任意*) | `KameleoonClientConfig?` | 任意の SDK 構成。提供される場合は、外部の[構成ファイル](#追加の設定)からの読み込みではなく、これが使用されます。提供されない場合、SDK はファイルの読み込みを試みますが、ファイルが見つからない場合はデフォルトの動作にフォールバックします。 | `nil` |
##### 戻り値
| 型 | 説明 |
| ----------------- | --------------------------------------------------------- |
| `KameleoonClient` | アプリが実験および機能フラグを管理するために使用できる `KameleoonClient` クラスのインスタンス。 |
##### スローされる例外
| 型 | 説明 |
| ----------------------------------- | --------------------------------------------- |
| `KameleoonError.visitorCodeInvalid` | 提供された訪問者コードが有効でないことを示す例外。空であるか、255 文字を超えています。 |
| `KameleoonError.siteCodeIsEmpty` | 指定されたサイトコードが空文字列であり、無効な値であることを示す例外。 |
#### ready
モバイル SDK では、Kameleoon クライアントの初期化は即座には完了しません。SDK は、すべてのアクティブな実験の現在の構成を取得するためにサーバー呼び出しを実行する必要があります。実験をトリガーする前に、このメソッドを呼び出して SDK の準備が整っているか確認してください。あるいは、コールバック付きの [`runWhenReady()`](#runwhenready) メソッドを使用することもできます。
```swift theme={null}
let ready = kameleoonClient.ready
```
##### 戻り値
| 名前 | 型 | 説明 |
| ----- | ---- | --------------------------------------------------------- |
| ready | Bool | SDK の状態を表すブール値(完全に初期化されている場合は true、使用準備ができていない場合は false)。 |
#### runWhenReady()
* 🔄 *非同期リクエストを実行します(構成が古いか欠落している場合)*
モバイル SDK では、`KameleoonClient` はすべての機能フラグの現在の構成を取得するためにサーバー呼び出しを実行する必要があるため、即座に初期化できません。クライアントが使用可能になるまで待機するには、[`runWhenReady()`](#runwhenready) メソッドを使用します。さらに、クライアントが準備完了するまで待機する最大タイムアウト期間を設定して制御できます。
`ready=true` の場合、`KameleoonClient` は完全に初期化されており、機能フラグが評価されてそれぞれのバリエーションが割り当てられます。結果が `false` であるか、タイムアウトが発生した場合、初期化は完了しません。
タイムアウトが発生すると、ユーザーは機能フラグから除外されるため、コールバックまたは非同期コードは参照バリエーションの適用を処理する必要があります。
初回構成にはサーバー呼び出しが必要な場合があるため、このメカニズムは非同期です。したがって、次のいずれかを実施する必要があります:
* `KameleoonClient` が完全に初期化され使用可能になったときに通知を受けるため、`completion` コールバックをメソッドの引数として提供します。
* 非同期操作を使用します。
```swift theme={null}
func applyRecommendedProductsVariation() {
let defaultValue = 5 // Default control number for recommended products
kameleoonClient.runWhenReady(timeoutMilliseconds: 1000) { ready in
guard ready else {
applyVariation(recommendedProductsNumber: defaultValue)
return
}
let variation = try? kameleoonClient.getVariation(featureKey: "featureKey")
let recommendedProductsNumber = variation.variables["recommendedProductsNumber"]?.value as? Int ?? defaultValue
applyVariation(recommendedProductsNumber: recommendedProductsNumber)
}
}
```
##### 引数
| 名前 | 型 | 説明 | デフォルト |
| -------------------------- | ---------------- | ----------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
| timeoutMilliseconds (*任意*) | `Int` | 初期化プロセスのタイムアウト | [`defaultTimeoutMillisecond`](#create) または [`default_timeout_millisecond`](#追加の設定) |
| callback (*必須*) | `(Bool) -> Void` | コールバックオブジェクト。タイムアウトに到達する前に `KameleoonClient` が準備完了になったかどうかを表す `Bool` 引数を受け取るラムダ式です。 | |
よくある間違いは、`try?` を付けて、または**ネストされた** `do-catch` ブロック内で `CancellationError` を再スローせずに `async` 関数を呼び出すことです。これによりタスクのキャンセルが妨げられ、予期しない動作を引き起こす可能性があります。
タスクのキャンセルを正しく行うために、明示的に `CancellationError` を再スローしない限り、`async` 関数の周りに `try?` や `do-catch` を使用しないでください。
```swift theme={null}
func applyRecommendedProductsVariation() async throws {
let defaultValue = 5 // Default control number for recommended products
try await kameleoonClient.runWhenReady(timeoutMilliseconds: 1000)
let variation = try kameleoonClient.getVariation(featureKey: "featureKey")
let recommendedProductsNumber = variation.variables["recommendedProductsNumber"]?.value as? Int ?? defaultValue
applyVariation(recommendedProductsNumber: recommendedProductsNumber)
}
```
##### 引数
| 名前 | 型 | 説明 | デフォルト |
| -------------------------- | ----- | -------------- | ---------------------------------------------------------------------------------- |
| timeoutMilliseconds (*任意*) | `Int` | 初期化プロセスのタイムアウト | [`defaultTimeoutMillisecond`](#create) または [`default_timeout_millisecond`](#追加の設定) |
##### スローされるエラー
| 型 | 説明 |
| ---------------------------- | --------------------------- |
| `KameleoonError.sdkNotReady` | SDK がまだ完全に初期化されていないことを示す例外。 |
### 機能フラグとバリエーション
#### isFeatureActive()
* *📨 トラッキングデータを Kameleoon に送信します(`track` パラメータに応じて)*
このメソッドは以前 `activateFeature` という名前で、SDK バージョン `4.0.0` で削除されました。
機能トグルを有効化するには、このメソッドを呼び出します。`isFeatureActive()` は、指定された機能が訪問者に対してアクティブになるかどうかを確認するために、必須の引数として `featureKey` を受け取ります。
訪問者がこの機能フラグに関連付けられたことがない場合、このメソッドはランダムなブール値を返します(ユーザーにこの機能を表示すべき場合は `true`、それ以外の場合は `false`)。訪問者がすでにこの機能フラグに登録されている場合、メソッドは以前の `featureFlag` 値を返します。
潜在的なエラーをキャッチするために、サンプルコードに示されているようにエラー処理を実装してください。
Kameleoon は、`isFeatureActive()`、`getVariation()`、`getVariations()` などの特定のメソッドを呼び出すときに、セッションと訪問者を数えるためにトラッキングを使用します。
訪問者をバリエーションに公開し、それらをカウントする必要がある場合は、`track` パラメータのデフォルト値 `true` を使用してください。`track` パラメータを `false` に設定するのは、訪問者を公開する前にこれらのメソッドを呼び出す場合のみにしてください。
例えば、訪問者を公開する前にすべてのバリエーションを取得するために `getVariations()` を呼び出す場合、`track` パラメータを `false` に設定してください。この設定により、Kameleoon がセッションを早期にカウントするのを防げます。その後、訪問者を明示的に公開するときにトラッキングをトリガーできます。
Kameleoon はデフォルトで毎秒トラッキングデータを送信します。この間隔は、トラッキング間隔の構成オプションを使用して最大 5 秒まで構成できます。Kameleoon は、イベント間の間隔が 30 分未満である限り、トラッキングイベントを単一のセッションにグループ化します。トラッキングイベント間で 30 分以上経過した場合、Kameleoon はそれらのイベントを別々のセッションとしてカウントします。訪問は、セッションの最後に記録されたイベントから 30 分後にレポートに表示されます。
```swift theme={null}
let featureKey = "new_checkout"
var hasNewCheckout = false
do {
hasNewCheckout = try kameleoonClient.isFeatureActive(featureKey: featureKey)
// disabling tracking
hasNewCheckout = kameleoonClient.isFeatureActive(featureKey: featureKey, track: false);
} catch {
switch error {
case KameleoonError.sdkNotReady:
// Exception indicating that the SDK has not completed its initialization yet.
hasNewCheckout = false
case KameleoonError.Feature.notFound:
// The feature key is not in the configuration file that has been fetched by the SDK.
hasNewCheckout = false
default:
// Any other error.
hasNewCheckout = false
}
}
if hasNewCheckout
{
// Implement new checkout code here
}
```
`isFeatureActive()` メソッドは、マスターフラグの状態ではなく、配信されたバリアントを評価します。ルールを除外する場合、このメソッドは **その他のすべての訪問者に対しては** デフォルト状態を使用します。このデフォルト状態に **Off** を選択した場合、マスター機能フラグが **On** であってもメソッドは常に `false` を返します。
##### 引数
| 名前 | 型 | 説明 |
| ---------- | -------- | --------------------------------------------------- |
| featureKey | `String` | ユーザーに公開したい機能のキー。このフィールドは必須です。 |
| track | `Bool` | 機能評価のトラッキングを有効または無効にするためのオプションパラメータ(デフォルトは `true`)。 |
##### 戻り値
| 型 | 説明 |
| ------ | -------------- |
| `Bool` | 訪問者に登録された機能の値。 |
##### スローされるエラー
| 型 | 説明 |
| --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `KameleoonError.sdkNotReady` | SDK が完全に初期化されていないことを示す例外。 |
| `KameleoonError.Feature.notFound` | 要求された機能 ID が SDK の内部構成内で見つからなかったことを示す例外。この例外は通常、機能フラグが Kameleoon 側でまだ有効化されていないことを意味します(ただし、機能を実装するコードはすでに Web アプリケーションにデプロイされています)。 |
#### getVariation()
* 📨 *トラッキングデータを Kameleoon に送信します(`track` パラメータに応じて)*
特定の機能フラグに対して、指定された訪問者に割り当てられた [`Variation`](#variation) を取得します。
このメソッドは、必須引数として `visitorCode` と `featureKey` を受け取ります。`track` 引数は任意であり、デフォルトは `true` です。
訪問者に割り当てられた `Variation` を返します。訪問者がいずれの機能フラグルールにも関連付けられていない場合、このメソッドは指定された機能フラグのデフォルト `Variation` を返します。
潜在的な例外を管理するために、コードに適切なエラー処理が実装されていることを確認してください。
デフォルトバリエーションは、訪問者が機能フラグの事前定義された配信ルールのいずれにも一致しない場合に割り当てられるバリエーションを指します。言い換えれば、特定のルールでターゲットされていないすべてのユーザーに適用されるフォールバックバリエーションです。管理インターフェースの「その他のすべての訪問者に対しては...」セクションのバリエーションとして表されます。
```swift theme={null}
let featureKey = "featureKey"
var variation: Types.Variation?
do {
variation = try kameleoonClient.getVariation(featureKey: featureKey)
// disabling tracking
variation = kameleoonClient.getVariation(featureKey: featureKey, track: false);
} catch {
switch error {
case KameleoonError.sdkNotReady:
// Exception indicating that the SDK has not completed its initialization yet.
case KameleoonError.Feature.notFound:
// The feature key is not in the configuration file that has been fetched by the SDK.
case KameleoonError.Feature.environmentDisabled:
// The feature flag is disabled for the environment.
default:
// Any other error.
}
}
let title = variation?.variables["title"].value
switch variation?.key {
case "on":
// Main variation key is selected for visitorCode
case "alternative_variation":
// Alternative variation key
default:
// Default variation key
}
```
##### 引数
| 名前 | 型 | 説明 | デフォルト |
| ------------------ | -------- | ------------------------------------ | ------ |
| visitorCode (*必須*) | `String` | 訪問者の一意な識別子。 | |
| featureKey (*必須*) | `String` | 訪問者に公開したい機能のキー。 | |
| track (*任意*) | `Bool` | 機能評価のトラッキングを有効または無効にするためのオプションパラメータ。 | `true` |
##### 戻り値
| 型 | 説明 |
| ----------- | ------------------------------------------------------- |
| `Variation` | 特定の機能フラグに対して指定された訪問者に割り当てられた [`Variation`](#variation)。 |
##### スローされるエラー
| 型 | 説明 |
| -------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| `KameleoonError.visitorCodeInvalid` | 提供された訪問者コードが有効でないことを示す例外。空であるか、255 文字を超えています。 |
| `KameleoonError.Feature.notFound` | 要求された機能キーが SDK の内部構成内で見つからなかったことを示す例外。これは通常、機能フラグが Kameleoon アプリで有効化されていないことを意味します(ただし、機能を実装するコードはすでにアプリケーションにデプロイされています)。 |
| `KameleoonError.Feature.environmentDisabled` | 機能フラグが訪問者の現在の環境(例えば、production、staging、または development)に対して無効になっていることを示す例外。 |
#### getVariations()
* 📨 *トラッキングデータを Kameleoon に送信します(`track` パラメータに応じて)*
すべての機能フラグにわたって、指定された訪問者に割り当てられた [`Variation`](#variation) オブジェクトのマップを取得します。
このメソッドは、利用可能なすべての機能フラグを反復処理し、指定された訪問者に関連付けられた各フラグに割り当てられた `Variation` を返します。`onlyActive` と `track` を任意の引数として受け取ります。
* `onlyActive` が `true` に設定されている場合、`getVariations()` メソッドは、ユーザーが `off` バリエーションでバケットされていない機能フラグのバリエーションを返します。
* `track` パラメータは、メソッドがバリエーションの割り当てをトラッキングするかどうかを制御します。デフォルトでは `true` に設定されています。`false` に設定すると、トラッキングが無効になります。
返されるマップは、機能フラグのキーをキーとして、対応する `Variation` を値として持ちます。機能フラグにバリエーションが割り当てられていない場合、メソッドはそのフラグのデフォルト `Variation` を返します。
潜在的な例外を管理するために、適切なエラー処理を実装する必要があります。
デフォルトバリエーションは、訪問者が機能フラグの事前定義された配信ルールのいずれにも一致しない場合に割り当てられるバリエーションを指します。言い換えれば、特定のルールでターゲットされていないすべてのユーザーに適用されるフォールバックバリエーションです。管理インターフェースの「その他のすべての訪問者に対しては...」セクションのバリエーションとして表されます。
```swift theme={null}
do {
let variations = kameleoonClient.getVariations();
// only active variations
let variations = kameleoonClient.getVariations(onlyActive: true);
// disable tracking
let variations = kameleoonClient.getVariations(track: false);
} catch KameleoonError.sdkNotReady {
// Exception indicating that the SDK has not completed its initialization yet.
}
```
##### 引数
| 名前 | 型 | 説明 | デフォルト |
| ----------------- | ------ | ------------------------------------------------------------ | ------- |
| onlyActive (*任意*) | `Bool` | アクティブ(`true`)またはすべて(`false`)の機能フラグのバリエーションを返すかどうかを示す任意パラメータ。 | `false` |
| track (*任意*) | `Bool` | 機能評価のトラッキングを有効または無効にするための任意パラメータ。 | `true` |
##### 戻り値
| 型 | 説明 |
| ------------------------- | -------------------------------------------------------------------- |
| `Dict` | 対応する機能のキーを使用して、機能フラグに割り当てられた [`Variation`](#variation) オブジェクトを含むマップ。 |
##### スローされるエラー
| 型 | 説明 |
| ---------------------------- | --------------------------- |
| `KameleoonError.sdkNotReady` | SDK がまだ完全に初期化されていないことを示します。 |
#### setForcedVariation()
このメソッドにより、標準の評価プロセスをバイパスして、特定の [`Variation`](#variation) をプログラム上でユーザーに割り当てることができます。これは、通常の評価ロジックが不要またはスキップする必要がある、制御された実験で特に有用です。また、デバッグやカスタムテストなどのシナリオでも役立ちます。
**強制**バリエーションが設定されている場合、Kameleoon のリアルタイム評価ロジックを上書きします。セグメンテーション、ターゲティング条件、アルゴリズム計算などのプロセスはスキップされます。実験中にセグメンテーションとターゲティング条件を保持するには、代わりに `forceTargeting=false` を設定してください。
強制バリエーションは、評価されたバリエーションと同じ扱いを受けます。標準的な評価バリエーションと同様に、アナリティクスでトラッキングされ、ユーザーコンテキストに保存され、レポートの一貫性が確保されます。
このメソッドは、特定の条件下で例外をスローする場合があります(例えば、無効なパラメータ、ユーザーコンテキスト、または内部の問題)。アプリケーションの安定性と耐障害性を確保するため、適切な例外処理は不可欠です。
```swift theme={null}
let experimentId = 9516
do {
// Forcing the variation "on" for the experiment 9516 for the visitor
try kameleoonClient.setForcedVariation(experimentId: experimentId, variationKey: "on")
// Forcing the variation "on" while preserving segmentation and targeting conditions during the experiment
try kameleoonClient.setForcedVariation(experimentId: experimentId, variationKey: "on", forceTargeting: false)
// Resetting the forced variation for the experiment 9516 for the visitor
try kameleoonClient.setForcedVariation(experimentId: experimentId, variationKey: nil);
} catch {
// Handling the KameleoonError, KameleoonError.Feature and common Error
}
```
##### 引数
| 名前 | 型 | 説明 | デフォルト |
| --------------------- | -------- | ----------------------------------------------------------------------------------- | ------ |
| experimentId (*必須*) | `Int` | 評価プロセス中にターゲットされ選択される **実験 ID**。 | |
| variationKey (*必須*) | `String` | 実験で返された値として強制されるべき `Variation` に対応する **バリエーションキー**。値が `nil` の場合、強制バリエーションはリセットされます。 | |
| forceTargeting (*任意*) | `Bool` | 実験のターゲティングを強制およびスキップするか(`true`)、または標準評価プロセスのように適用するか(`false`)を示します。 | `true` |
##### スローされるエラー
| 型 | 説明 |
| ------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| `KameleoonError.sdkNotReady` | SDK がまだ完全に初期化されていないことを示します。 |
| `KameleoonError.Feature.experimentNotFound` | 要求された実験 ID が SDK の内部構成内で見つからなかったことを示す例外。これは通常正常で、ルールの対応する実験が Kameleoon 側でまだ有効化されていないことを意味します。 |
| `KameleoonError.Feature.variationNotFound` | 要求されたバリエーションキー(id)が SDK の内部構成内で見つからなかったことを示す例外。これは通常正常で、バリエーションの対応する実験が Kameleoon 側でまだ有効化されていないことを意味します。 |
ほとんどの場合、例で示されているように、基本的なエラー `KameleoonError/KameleoonError.Feature` のみを処理すれば十分です。ただし、異なる種類のエラーに対する応答が必要な場合は、特定の要件に基づいて個別に処理してください。さらに、信頼性を高めるため、`Error` を含めることで一般的な言語エラーを処理できます。
#### evaluateAudiences()
* 📨 *トラッキングデータを Kameleoon に送信します*
このメソッドは、利用可能なすべての Audiences Explorer セグメントに対して訪問者を評価し、一致したものをトラッキングします。
`evaluateAudiences()` は、**関連するすべての訪問者データが設定または更新された後**、かつ機能バリエーションを取得したり機能フラグを確認したりする**直前**に呼び出す必要があります。このアプローチにより、訪問者が利用可能な最新のデータに対して評価されるようになり、すべての基準に基づいた正確なオーディエンス割り当てが可能になります。
このメソッドを呼び出した後、Audiences Explorer でセグメントのパフォーマンスを詳細に分析できます。
```swift theme={null}
do {
try kameleoonClient.evaluateAudiences();
} catch {
// Handling the errors
}
```
##### スローされるエラー
| 型 | 説明 |
| ---------------------------- | --------------------------- |
| `KameleoonError.sdkNotReady` | SDK がまだ完全に初期化されていないことを示します。 |
ほとんどの場合、例で示されているように、基本的なエラー `KameleoonError/KameleoonError.Feature` のみを処理すれば十分です。ただし、異なる種類のエラーに対する応答が必要な場合は、特定の要件に基づいて個別に処理してください。さらに、信頼性を高めるため、`Error` を含めることで一般的な言語エラーを処理できます。
#### getFeatureList()
すべての機能フラグを反復処理し、各々で [`getVariation()`](#getvariation) を呼び出したい場合は、代わりに [`getVariations()`](#getvariations) メソッドを使用してください。
現在 SDK で利用可能な機能フラグキーのリストを返します。
```swift theme={null}
let allFeatureList = kameleoonClient.getFeatureList()
```
##### 戻り値
| 型 | 説明 |
| ---------- | ----------- |
| `[String]` | 機能フラグキーのリスト |
#### getDataFile()
すべての機能フラグを評価するには、[`getVariations()`](#getvariations) を使用してください。このメソッドは、`DataFile` を呼び出して [`getVariation()`](#getvariation) でフラグを反復処理するよりも効率的です。
現在の SDK 構成を [`DataFile`](#datafile) オブジェクトとして返します。
```swift theme={null}
do {
let dataFile = try kameleoonClient.getDataFile()
} catch KameleoonError.sdkNotReady {
// Exception indicates that the SDK has not completed its initialization yet.
} catch {
// Handling the KameleoonError, KameleoonError.Feature and common Error
}
```
##### 戻り値
| 型 | 説明 |
| ---------- | ---------------------------------- |
| `DataFile` | SDK 構成を含む [`DataFile`](#datafile)。 |
##### スローされるエラー
| 型 | 説明 |
| ---------------------------- | --------------------------- |
| `KameleoonError.sdkNotReady` | SDK がまだ完全に初期化されていないことを示します。 |
### ゴール
#### trackConversion()
* 📨 *トラッキングデータを Kameleoon に送信します*
このメソッドを使用してコンバージョンをトラッキングします。このメソッドは、特定の[ゴール](/user-manual//assets/goals/create-a-goal)でコンバージョンをトラッキングするために `goalId` を必要とします。さらに、このメソッドは `revenue`、`metadata`、`negative` 引数も受け取ります。
`trackConversion()` メソッドは値を返しません。サーバー呼び出しは非同期に行われるため、このメソッドはノンブロッキングです。
```swift theme={null}
let goalId = 83023
kameleoonClient.trackConversion(goalId: goalId, revenue: 10.0)
kameleoonClient.trackConversion(goalId: goalId, revenue: 10.0, metadata: CustomData(id: 1, values: "metadata"))
```
##### 引数
| 名前 | 型 | 説明 | デフォルト |
| --------------- | ------------------------------ | --------------------------------------------------------------------------------------------------- | ------- |
| goalId (*必須*) | `Int` | ゴールの ID。 | |
| revenue (*任意*) | `Double` | コンバージョンの収益。 | `0` |
| negative (*任意*) | `Bool` | 収益が正か負かを定義します。 | `false` |
| metadata (*任意*) | `CustomData... / [CustomData]` | コンバージョンのメタデータ。[事前に Kameleoon アプリで定義されている必要があります](/ja/user-manual/assets/goals/create-a-goal#メタデータ)。 | `[]` |
metadata の値は、[生データエクスポート](/user-manual/experiment-analytics/analyze-results/results-page/results-page-actions#Export)および[結果ページ](/user-manual/experiment-analytics/analyze-results/data-and-metrics/goal-metadata)からアクセスできます。
`metadata` パラメータが提供されている場合、Kameleoon は [`addData()`](#adddata) メソッドを使用して以前に収集された値の代わりに、これらの指定された値を現在のコンバージョンに使用します。パラメータが省略されている場合、Kameleoon はコンバージョンの前および同じ訪問内で、その [`CustomData`](#customdata) に対して最後にトラッキングされた値を使用します。
Kameleoon は、`trackConversion()` メソッドのパラメータとして明示的に渡されたメタデータ値のみを考慮します。
以下の例では、Kameleoon はパラメータとして明示的に提供されたカスタムデータ値(ここでは: インデックス 5、値 'Amex Credit Card')とのみコンバージョンを関連付けます。
```swift theme={null}
kameleoonClient.addData([CustomData(id: 5, values: "Credit Card"), CustomData(id: 9, "Express Delivery")]);
kameleoonClient.trackConversionWithOptParams(goalId: 1000, metadata: CustomData(5, "Amex Credit Card"));
```
### イベント
#### updateConfigurationHandler()
`updateConfigurationHandler()` メソッドにより、構成が更新されたデータを持つときのイベントを処理できます。入力パラメータとして **handler** を 1 つ受け取ります。リアルタイム構成イベントを使用して構成が更新されるときに呼び出されるハンドラーです。
このハンドラーは、SDK が[ストリーミングモード](/developer-docs/feature-experimentation/technical-reference/technical-considerations#ストリーミング（プレミアムオプション）)(サーバー送信イベント)で実行されている場合にのみ発火します。デフォルトのポーリングモード(`refreshIntervalMinute`)で実行される構成更新では呼び出されません。
```swift theme={null}
kameleoonClient.updateConfigurationHandler {
// configuration was updated
}
```
##### 引数
| 名前 | 型 | 説明 |
| ------- | ------------------------ | ---------------------------------------- |
| handler | `Optional<(() -> Void)>` | リアルタイム構成イベントを使用して構成が更新されるときに呼び出されるハンドラー。 |
### 訪問者データ
#### visitorCode
SDK で使用されている一意の訪問者コードを返します。
```swift theme={null}
let visitorCode = kameleoonClient.visitorCode
```
##### 戻り値
| 型 | 説明 |
| -------- | ---------------------------- |
| `String` | SDK で使用されている一意の訪問者コードを表す文字列。 |
#### addData()
`addData()` メソッドは、他のメソッドが現在の訪問者をターゲットにするかどうかを決定するために使用できる[ターゲティングデータ](#データ型)をストレージに追加します。
`addData()` メソッドは値を返さず、それ自体で Kameleoon バックエンドサーバーと対話しません。代わりに、宣言されたすべてのデータは、[`flush()`](#flush) メソッドを使用した将来の送信のために保存されます。このアプローチにより、データは通常 `flush()` でトリガーされる単一のサーバー呼び出しにグループ化されるため、サーバー呼び出しの数が削減されます。
[`trackConversion()`](#trackconversion) メソッドも、`flush()` と同じように、以前に関連付けられたデータを送信します。実験ルールがトリガーされた場合、[`getVariation()`](#getvariation) および [`getVariations()`](#getvariations) メソッドも同様です。
ほとんどのデータ型では、各訪問者は関連付けられたデータのインスタンスを 1 つしか持つことができません。ただし、[`CustomData`](#customdata) は例外です。訪問者はインデックスごとに関連付けられた `CustomData` のインスタンスを 1 つ持つことができます。
```swift theme={null}
// Add a single data item (tracked by default)
kameleoonClient.addData(CustomData(index: 1, values: "value"))
// Add multiple data items (tracked by default)
kameleoonClient.addData(
CustomData(index: 20, values: "value"),
Geolocation(country: "France")
)
// Add multiple data items stored locally for targeting only (not sent to the Kameleoon Data API)
kameleoonClient.addData(
track: false,
CustomData(index: 20, values: "value"),
Geolocation(country: "France")
)
```
##### 引数
| 名前 | 型 | 説明 | デフォルト値 |
| ------------ | ------------------------------------ | --------------------------------------------------------------------------------------------------------- | ------ |
| track (*任意*) | `Bool` | 追加されたデータがトラッキング対象であるかを指定します。`false` に設定すると、データはローカルに保存され、ターゲティング評価にのみ使用されます。Kameleoon Data API には送信されません。 | `true` |
| data (*必須*) | `KameleoonData... / [KameleoonData]` | Kameleoon データ型のコレクション。 | |
#### 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 回呼び出します。
```swift theme={null}
kameleoonClient.addData(CustomData(id: 20, values: "true", "20"))
kameleoonClient.addData(Conversion(goalId: 32, revenue: 10.0, negative: false))
kameleoonClient.flush() // Interval tracking (most performant way for tracking)
kameleoonClient.flush(instant: true) // Instant tracking
```
##### 引数
| 名前 | 型 | 説明 |
| ------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| instant | `Bool` | データを即座に送信するか(`true`)、SDK パラメータ `trackingIntervalMillisecond` で [`KameleoonClientConfig`](/developer-docs/sdks/mobile-sdks/ios-sdk#initialize-the-kameleoon-client) または [`tracking_interval_millisecond`](#追加の設定) で設定されたデフォルトのトラッキング間隔に従って送信するか(`false`)を示すブールフラグ。このフィールドは任意です。 |
##### スローされるエラー
| 型 | 説明 |
| ---------------------------- | ------------------------- |
| `KameleoonError.sdkNotReady` | SDK が初期化を完了していないことを示すエラー。 |
#### getRemoteData()
* 🔄 *非同期リクエストを実行します*
このメソッドは以前 `retrieveDataFromRemoteSource` という名前で、SDK バージョン `4.0.0` リリースで削除されました。
このメソッドを使用して、アクティブな `siteCode` と `key` 引数(または `key` が省略されている場合はアクティブな `visitorCode`)に基づいてリモート Kameleoon サーバーからデータを取得します。`visitorCode` と `siteCode` は `KameleoonClientFactory.create()` で指定されます。データは Kameleoon Data API を使用して、高度にスケーラブルなリモートサーバーに迅速かつ便利に保存できます。アプリケーションはこのメソッドを使用してデータを取得できます。
サーバー呼び出しが必要なため、このメカニズムは非同期です。したがって、次のいずれかを実施する必要があります:
* データが正常に取得されたときに通知を受けるため、`completion` コールバックをメソッドの引数として提供します。
* 非同期操作を使用します。
```swift theme={null}
struct Test1: Decodable {
let value: String
private enum CodingKeys: String, CodingKey {
case value = "json_value"
}
}
kameleoonClient.getRemoteData(key: "test") { (result: Result) in
switch result {
case .success(let test1):
// test1 is a decoded value for Test1 type
case .failure:
// error includes informaion about request's failure
}
}
kameleoonClient.getRemoteData(key: "test") { (data: Result) in
switch result {
case .success(let data):
if let json = try JSONSerialization.jsonObject(with: data) as? [String: Any] {
print(json)
}
case .failure:
// error includes informaion about request's failure
}
}
```
##### 引数
| 名前 | 型 | 説明 | デフォルト |
| ----------------- | --------------------------------------- | ------------------- | ----- |
| key (*任意*) | `String` | 取得したいデータに関連付けられたキー。 | `""` |
| completion (*必須*) | `(Result) -> Void` | 受信したデータを処理するコールバック。 | |
よくある間違いは、`try?` を付けて、または**ネストされた** `do-catch` ブロック内で `CancellationError` を再スローせずに `async` 関数を呼び出すことです。これによりタスクのキャンセルが妨げられ、予期しない動作を引き起こす可能性があります。
タスクのキャンセルを正しく行うために、明示的に `CancellationError` を再スローしない限り、`async` 関数の周りに `try?` や `do-catch` を使用しないでください。
```swift theme={null}
struct Test1: Decodable {
let value: String
private enum CodingKeys: String, CodingKey {
case value = "json_value"
}
}
Task {
do {
let test1: Test1 = try await kameleoonClient.getRemoteData(key: "test")
// test1 is a decoded value for Test1 type
} catch {
// handle error
}
}
Task {
do {
let data: Data = try await kameleoonClient.getRawRemoteData(key: "test")
if let json = try JSONSerialization.jsonObject(with: data) as? [String: Any] {
print(json)
}
} catch {
// handle error
}
}
```
##### 引数
| 名前 | 型 | 説明 | デフォルト |
| ---------- | -------- | ------------------- | ----- |
| key (*任意*) | `String` | 取得したいデータに関連付けられたキー。 | `""` |
##### 戻り値
| 型 | 説明 |
| ----------- | -------------------------------------------------------------------------------------------- |
| `Decodable` | 解析された取得値を含む [`Decodable`](https://developer.apple.com/documentation/swift/decodable) オブジェクト。 |
##### スローされるエラー
| 型 | 説明 |
| ------- | ------------------------ |
| `Error` | エラーによりリクエストが失敗したことを示します。 |
#### getRemoteVisitorData()
* 🔄 *非同期リクエストを実行します*
`getRemoteVisitorData()` は、Kameleoon Data API から訪問者の 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)のに有用です。
失敗した結果のみを確認することが推奨されます。ただし、必要に応じて、データが訪問者に追加され、ターゲティング目的(またはデバッグ用、ただしデバッグには[ロギング](#ロギング)の使用が推奨されます)に利用可能であることを確認できます。さらに、`addData=false` パラメータが渡されている場合、データを手動で管理できます。
サーバー呼び出しが必要なため、このメカニズムは非同期です。したがって、次のいずれかを実施する必要があります:
* データが正常に取得され訪問者に追加されたときに通知を受けるため、`completion` コールバックをメソッドの引数として提供します。
* 非同期操作を使用します。
```swift theme={null}
// Fetch visitor data and automatically add it
kameleoonClient.getRemoteVisitorData { result in
switch result {
case .success(let visitorData):
// visitorData includes all retrieved data that was added for the visitor
case .failure:
// Handle the error, which contains information about the request failure
}
}
// Fetch visitor data without automatically adding it
kameleoonClient.getRemoteVisitorData(addData: false) { result in
switch result {
case .success(let visitorData):
// visitorData includes all retrieved data that was added for the visitor
case .failure:
// Handle the error, which contains information about the request failure
}
}
// Fetch a custom list of data types
let filter = Types.RemoteVisitorDataFilter(
previousVisitAmount: 25, currentVisit: true, conversions: true, experiments: true, geolocation: true
)
kameleoonClient.getRemoteVisitorData(filter: filter) { result in
switch result {
case .success(let visitorData):
// visitorData includes all retrieved data that was added for the visitor
case .failure:
// Handle the error, which contains information about the request failure
}
}
```
##### 引数
| 名前 | 型 | 説明 | デフォルト |
| ----------------- | ------------------------------------------ | --------------------------------------------------------------------- | --------------------------------- |
| filter (*任意*) | `RemoteVisitorDataFilter` | 訪問履歴から取得すべきデータを選択するフィルター。デフォルトでは、現在および最新の前回の訪問から `CustomData` を取得します。 | `RemoteVisitorDataFilter.default` |
| addData (*任意*) | `Boolean` | メソッドが訪問者に対して取得したデータを自動的に追加すべきかどうかを示すブール値。 | `true` |
| completion (*必須*) | `(Result<[KameleoonData], Error>) -> Void` | 受信した訪問者データを処理するコールバック。 | |
よくある間違いは、`try?` を付けて、または**ネストされた** `do-catch` ブロック内で `CancellationError` を再スローせずに `async` 関数を呼び出すことです。これによりタスクのキャンセルが妨げられ、予期しない動作を引き起こす可能性があります。
タスクのキャンセルを正しく行うために、明示的に `CancellationError` を再スローしない限り、`async` 関数の周りに `try?` や `do-catch` を使用しないでください。
```swift theme={null}
// Fetch visitor data and automatically add it
Task {
do {
let visitorData = try await kameleoonClient.getRemoteVisitorData()
// visitorData includes all retrieved data that was added for the visitor
} catch {
// Handle the error, which contains information about the request failure
}
}
// Fetch visitor data without automatically adding it
Task {
do {
let visitorData = try await kameleoonClient.getRemoteVisitorData(addData: false)
// visitorData includes all retrieved data but was not added for the visitor
} catch {
// Handle the error, which contains information about the request failure
}
}
// Fetch a custom list of data types
Task {
do {
let filter = Types.RemoteVisitorDataFilter(
previousVisitAmount: 25, currentVisit: true, conversions: true, experiments: true, geolocation: true
)
let visitorData = try await kameleoonClient.getRemoteVisitorData(filter: filter)
// visitorData includes all retrieved data based on the specified filter
} catch {
// Handle the error, which contains information about the request failure
}
}
```
##### 引数
| 名前 | 型 | 説明 | デフォルト |
| -------------- | ------------------------- | --------------------------------------------------------------------- | --------------------------------- |
| filter (*任意*) | `RemoteVisitorDataFilter` | 訪問履歴から取得すべきデータを選択するフィルター。デフォルトでは、現在および最新の前回の訪問から `CustomData` を取得します。 | `RemoteVisitorDataFilter.default` |
| addData (*任意*) | `Boolean` | メソッドが訪問者に対して取得したデータを自動的に追加すべきかどうかを示すブール値。 | `true` |
##### 戻り値
| 型 | 説明 |
| ----------------- | ------------------ |
| `[KameleoonData]` | 訪問者用に取得したデータを含む配列。 |
##### スローされるエラー
| 型 | 説明 |
| ------- | ------------------------ |
| `Error` | エラーによりリクエストが失敗したことを示します。 |
##### RemoteVisitorDataFilter でのパラメータの使用
`getRemoteVisitorData()` メソッドは、訪問者データを取得する際にさまざまなパラメータを定義できる柔軟性を提供します。ゴール、実験、またはバリエーションに基づいたターゲティングであっても、同じアプローチがすべてのデータ型に適用されます。
例えば、「注文取引」のゴールを完了した訪問者のデータを取得したいとします。`getRemoteVisitorData()` メソッド内でパラメータを指定して、ターゲティングを絞り込むことができます。例えば、最後の 5 回の訪問でゴールでコンバージョンしたユーザーのみをターゲットにする場合、`previousVisitAmount` パラメータを `5` に、`conversions` を `true` に設定できます。
この例で示される柔軟性は、ゴールデータに限定されません。`getRemoteVisitorData()` メソッド内のパラメータを使用して、さまざまな訪問者の動作に関するデータを取得できます。
利用可能な `Types.RemoteVisitorDataFilter` オプションのリストは以下の通りです:
| 名前 | 型 | 説明 | デフォルト |
| -------------------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| previousVisitAmount (*任意*) | `Int` | データを取得する以前の訪問数。`1` から `25` までの数値。 | `1` |
| currentVisit (*任意*) | `Bool` | true の場合、現在の訪問データが取得されます。 | `true` |
| customData (*任意*) | `Bool` | true の場合、カスタムデータが取得されます。 | `true` |
| conversions (*任意*) | `Bool` | true の場合、コンバージョンデータが取得されます。 | `false` |
| experiments (*任意*) | `Bool` | true の場合、実験データが取得されます。 | `false` |
| geolocation (*任意*) | `Bool` | true の場合、ジオロケーションデータが取得されます。 | `false` |
| kcs (*任意*) | `Bool` | true の場合、Kameleoon Conversion Score (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)で、`visitorCode` で識別される訪問者が訪問にわたって常に同じバリエーションを受け取るようにするために必要です。 | `true` |
| personalization (*任意*) | `Bool` | true の場合、パーソナライゼーションデータが取得されます。`personalization` はパーソナライゼーション条件に必要です。 | `false` |
| cbs (*任意*) | `Bool` | true の場合、Contextual Bandit スコアデータが取得されます。 | `false` |
#### getVisitorWarehouseAudience()
* 🔄 *非同期リクエストを実行します*
データウェアハウス内の訪問者に関連付けられたすべてのオーディエンスデータを取得します。任意の `warehouseKey` パラメータは通常、内部のユーザー ID です。`customDataIndex` パラメータは、訪問者のターゲティングに Kameleoon が使用する Kameleoon カスタムデータに対応します。詳細については、[ウェアハウスターゲティングドキュメント](/user-manual/integrations/data-warehouses/bigquery/use-bigquery-as-a-source-audience-targeting)を参照してください。
サーバー呼び出しが必要なため、このメカニズムは非同期です。したがって、次のいずれかを実施する必要があります:
* データが正常に取得され訪問者に追加されたときに通知を受けるため、`completion` コールバックをメソッドの引数として提供します。
* 非同期処理にコルーチンを使用します。
失敗した結果のみを確認することが推奨されます。ただし、必要に応じて、データが訪問者に追加され、ターゲティング目的(またはデバッグ用、ただしデバッグには[ロギング](#ロギング)の使用が推奨されます)に利用可能であることを確認できます。
```swift theme={null}
// Fetch visitor warehouse audience data
kameleoonClient.getVisitorWarehouseAudience(customDataIndex: 10) { result in
switch result {
case .success(let customData):
// Data was added. You can access it from `customData`
case .failure:
// Handle the error, which contains information about the request failure
}
}
// Fetch visitor warehouse audience data with a specific warehouse key
kameleoonClient.getVisitorWarehouseAudience(
warehouseKey: "warehouseKey", customDataIndex: 10
) { result in
switch result {
case .success(let customData):
// Data was added. You can access it from `customData`
case .failure:
// Handle the error, which contains information about the request failure
}
}
```
##### 引数
| 名前 | 型 | 説明 | デフォルト |
| ---------------------- | ------------------------------------- | ---------------------------------------------------- | ----- |
| warehouseKey (*任意*) | `String` | ウェアハウスデータを識別する一意のキー(通常は内部のユーザー ID)。 | `""` |
| customDataIndex (*必須*) | `Int` | BigQuery オーディエンスをターゲットにするために使用するカスタムデータのインデックスを表す整数。 | |
| completion | `(Result) -> Void` | 受信したデータを処理するコールバック。 | |
よくある間違いは、`try?` を付けて、または**ネストされた** `do-catch` ブロック内で `CancellationError` を再スローせずに `async` 関数を呼び出すことです。これによりタスクのキャンセルが妨げられ、予期しない動作を引き起こす可能性があります。
タスクのキャンセルを正しく行うために、明示的に `CancellationError` を再スローしない限り、`async` 関数の周りに `try?` や `do-catch` を使用しないでください。
```swift theme={null}
// Fetch visitor warehouse audience data
Task {
do {
let customData = try await kameleoonClient.getVisitorWarehouseAudience(customDataIndex: 10)
// Data was added. You can access it from `customData`
} catch {
// Handle the error, which contains information about the request failure
}
}
// Fetch visitor warehouse audience data with a specific warehouse key
Task {
do {
let customData = try await kameleoonClient.getVisitorWarehouseAudience(
warehouseKey: "warehouseKey", customDataIndex: 10
)
// Data was added. You can access it from `customData`
} catch {
// Handle the error, which contains information about the request failure
}
}
```
##### 引数
| 名前 | 型 | 説明 | デフォルト |
| ---------------------- | -------- | ---------------------------------------------------- | ----- |
| warehouseKey (*任意*) | `String` | ウェアハウスデータを識別する一意のキー(通常は内部のユーザー ID)。 | `""` |
| customDataIndex (*必須*) | `Int` | BigQuery オーディエンスをターゲットにするために使用するカスタムデータのインデックスを表す整数。 | |
##### 戻り値
| 型 | 説明 |
| ------------ | ----------------------------------------------------------------------------- |
| `CustomData` | 訪問者に追加された [`CustomData`](#customdata) エントリ。一般的にはこの値は無視できますが、テスト目的で役立つ場合があります。 |
##### スローされるエラー
| 型 | 説明 |
| ------- | ------------------------ |
| `Error` | エラーによりリクエストが失敗したことを示します。 |
#### setLegalConsent()
訪問者が個人データの使用に法的同意を与えたかどうかを指定するには、このメソッドを使用する必要があります。`legalConsent` パラメータを `false` に設定すると、トラッキングリクエストに含めることができるデータの種類が制限されます。このメソッドは、訪問者データを責任を持って管理しながら、法的および規制上の要件を遵守するのに役立ちます。個人データに関する詳細は、[同意管理ポリシー](/user-manual/project-management/consent-management-policy)を参照してください。
##### 引数
| 名前 | 型 | 説明 |
| ------------ | ------- | --------------------------------------------------------------------------------------------------- |
| legalConsent | boolean | 法的同意ステータスを表すブール値。`true` は訪問者が法的同意を与えたことを示し、`false` は訪問者が同意を与えていない、または法的同意を撤回したことを示します。このフィールドは必須です。 |
```swift theme={null}
kameleoonClient.setLegalConsent(true)
```
### データ型
このセクションでは、Kameleoon でサポートされているデータ型を一覧にします。複数の標準データ型が提供されているほか、カスタムデータ型を定義するための `CustomData` 型も提供されています。
#### Conversion
ここに保存される `Conversion` データセットは、それに関連付けられた任意のゴールで実験およびパーソナライゼーションレポートをフィルタするために使用できます。
* 各訪問者は複数の `Conversion` オブジェクトを持つことができます。
* `goalId` は Kameleoon アプリで見つけることができます。
| 名前 | 型 | 説明 | デフォルト |
| --------------- | ------------------------------ | -------------- | ------- |
| goalId (*必須*) | `Int` | ゴールの ID。 | |
| revenue (*任意*) | `Double` | コンバージョンの収益。 | `0` |
| negative (*任意*) | `Bool` | 収益が正か負かを定義します。 | `false` |
| metadata (*任意*) | `CustomData... / [CustomData]` | コンバージョンのメタデータ。 | `[]` |
```swift theme={null}
kameleoonClient.addData(Conversion(goalId: 32, revenue: 10.0, negative: false))
kameleoonClient.addData(Conversion(goalId: 32, metadata: CustomData(id: 1, values: "metadata")))
```
#### CustomData
`CustomData` を使用すると、任意の種類のデータを各訪問者に簡単に関連付けることができます。`CustomData` は、[セグメント](/user-manual/assets/segments/create-a-segment/)のターゲティング条件として、または実験レポートのフィルタ/分解として使用できます。
カスタムデータの詳細については、[この記事](/developer-docs/custom-data)を参照してください。
| 名前 | 型 | 説明 | |
| ----------------- | -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | ------ |
| index/name (*必須*) | `Int`/`String` | カスタムデータのインデックスまたは名前。**`index` または `name` のいずれかを提供して** データを識別する必要があります。 | |
| overwrite (*任意*) | `Bool` | 値がどのように保存され、レポートにどのように表示されるかを明示的に制御するフラグ。[詳細はこちら](/developer-docs/custom-data#default-logic-when-overwrite-parameter-is-false-or-omitted) | `true` |
| values (*必須*) | `String...` または `[String]` | 保存されるカスタムデータの値。 | |
* 各訪問者は、一意の `index` ごとに `CustomData` を 1 つだけ持つことができます。同じ `index` で別の `CustomData` を追加すると、既存の `CustomData` が置き換えられます。
* カスタムデータの `index` は、[カスタムデータダッシュボード](/user-manual/assets/custom-data/manage-custom-data)の「INDEX」列にあります。
* プライバシー上の理由から、SDK が選択したインデックスを持つデータを Kameleoon サーバーに送信するのを防ぐには、カスタムデータの作成時に **このデータをターゲティング目的のためにローカルでのみ使用する** オプションを有効にします。
* SDK インスタンスの構成が最新でない場合、または名前が登録されていない場合に名前で作成された `CustomData` インスタンスを追加すると、データは無視されます。
```swift theme={null}
kameleoonClient.addData(CustomData(index: 1, values: "value"))
// With several values
kameleoonClient.addData(CustomData(index: 1, values: "value 1", "value 2"))
// To set the 'overwrite' flag to false
kameleoonClient.addData(CustomData(index: 1, overwrite: false, values: ["first value", "second value"]))
// To use a name instead of the index
kameleoonClient.addData(CustomData(name: "my-custom-data", values: "value"))
```
#### Device
iOS SDK `4.14.0` 以降、`Device` は [`UIDevice.current.userInterfaceIdiom`](https://developer.apple.com/documentation/uikit/uiuserinterfaceidiom) の値に基づいて自動的に検出されます。ただし、必要に応じて手動で上書きすることもできます。
ユーザーのデバイスに関する情報を保存します。
| 名前 | 型 | 説明 |
| ------ | ------ | -------------------------------------------------- |
| device | Device | デバイスのリスト: `phone`、`tablet`、`desktop`。このフィールドは必須です。 |
```swift theme={null}
try? kameleoonClient.addData(Device.desktop);
```
#### Geolocation
`Geolocation` には訪問者のジオロケーション詳細が含まれます。
| 名前 | 型 | 説明 |
| ----------------- | ---------------------- | ---------------------------- |
| country (*必須*) | `String` | 訪問者の国。 |
| region (*任意*) | `String?` | 訪問者の地域。 |
| city (*任意*) | `String?` | 訪問者の都市。 |
| postalCode (*任意*) | `String?` | 訪問者の郵便番号。 |
| latitude (*任意*) | `Double?` | 訪問者の位置を表す緯度座標。座標値は十進法度を表します。 |
| longitude (*任意*) | `Double?` | 訪問者の位置を表す経度座標。座標値は十進法度を表します。 |
* 各訪問者は `Geolocation` を 1 つだけ持つことができます。2 つ目の `Geolocation` を追加すると、最初のものが上書きされます。
```swift theme={null}
kameleoonClient.addData(Geolocation(country: "France", region: "Île-de-France", city: "Paris"));
```
### 戻り値の型
#### DataFile
`DataFile` には SDK 構成の詳細が含まれます。
クライアントが必要とする場合、追加情報で拡張できます。詳細が必要な場合は、カスタマーサクセスマネージャーにお問い合わせください。
| 名前 | 型 | 説明 |
| ------------ | ----------------------- | ------------------------------------------------------- |
| featureFlags | `[String: FeatureFlag]` | 機能フラグキーをキーとする [`FeatureFlag`](#featureflag) オブジェクトのマップ。 |
| dateModified | `Int` | `DataFile` が最後に変更された時刻を示すタイムスタンプ(ミリ秒単位)。 |
```swift theme={null}
// Retrieves the dictionary of feature flags from the DataFile.
// The dictionary is keyed by feature flag identifiers, with each value being a FeatureFlag object.
let featureFlags = dataFile.featureFlags
// Retrieves the last modification timestamp of the DataFile.
// The value is an Int representing milliseconds since the Unix epoch.
let dateModified = dataFile.dateModified
```
#### FeatureFlag
`FeatureFlag` は、機能フラグ自体を定義する一連のプロパティ — 例えば、その [`Variations`](#variation)、[`Rules`](#rule)、環境ステータス、およびその他の関連詳細 — を表します。
クライアントが必要とする場合、追加情報で拡張できます。詳細が必要な場合は、カスタマーサクセスマネージャーにお問い合わせください。
| 名前 | 型 | 説明 |
| ------------------- | --------------------- | --------------------------------------- |
| environmentEnabled | `Bool` | 現在の環境で機能フラグが有効かどうかを示します。 |
| defaultVariationKey | `String` | 機能フラグに関連付けられたデフォルトバリエーションのキー。 |
| variations | `[String: Variation]` | バリエーションキーをキーとする `Variation` オブジェクトのマップ。 |
| rules | `[Rule]` | `Rule` オブジェクトのリスト。 |
```swift theme={null}
// Check whether the feature flag is enabled in the current environment
let isEnvironmentEnabled = featureFlag.environmentEnabled
// Retrieve the key of the default variation
let defaultVariationKey = featureFlag.defaultVariationKey
// Retrieve the default variation object
let defaultVariation = featureFlag.defaultVariation
// Retrieve all variations of the feature flag as a map (key = variation key, value = Variation object)
let variations = featureFlag.variations
// Retrieve all targeting rules associated with the feature flag
let rules = featureFlag.rules
```
#### Rule
`Rule` は、ルール自体を定義する一連のプロパティ — 例えば、その [`Variations`](#variation) — を表します。
クライアントが必要とする場合、追加情報で拡張できます。詳細が必要な場合は、カスタマーサクセスマネージャーにお問い合わせください。
| 名前 | 型 | 説明 |
| ---------- | --------------------- | --------------------------------------- |
| variations | `[String: Variation]` | バリエーションキーをキーとする `Variation` オブジェクトのマップ。 |
```swift theme={null}
// Retrieve all variations of the rule as a map (key = variation key, value = Variation object)
let variations = rule.variations
```
#### Variation
`Variation` には、訪問者に割り当てられたバリエーション(または、特定の割り当てが存在しない場合のデフォルトバリエーション)に関する情報が含まれます。
| 名前 | 型 | 説明 |
| ------------ | -------------------- | ----------------------------------------------------------------------------------- |
| name | `String` | バリエーションの名前。 |
| key | `String` | バリエーションを識別する一意のキー。 |
| id | `Int` | 割り当てられたバリエーションの ID(デフォルトバリエーションの場合は `-1`)。 |
| experimentId | `Int` | バリエーションに関連付けられた実験の ID(デフォルトの場合は `-1`)。 |
| variables | `[String: Variable]` | 変数名をキーとする、割り当てられたバリエーションの変数を含むマップ。変数が関連付けられていない場合、`variables` は空のコレクションである可能性があります。 |
* `Variation` オブジェクトは、割り当てられたバリエーションとその関連実験の詳細を提供します。一方、[`Variable`](#variable) オブジェクトには、バリエーション内の各変数の特定の詳細が含まれます。
* `id` または `experimentId` が `-1` である可能性のあるケース(デフォルトバリエーションを示す)を、コードが処理することを確認してください。
* バリエーションに変数が関連付けられていない場合、`variables` マップは空である可能性があります。
```swift theme={null}
// Retrieving the variation name
let variationName = variation.name
// Retrieving the variation key
let variationKey = variation.key
// Retrieving the variation id
let variationId = variation.id
// Retrieving the experiment id
let experimentId = variation.experimentId
// Retrieving the variables map
let variables = variation.variables
```
#### Variable
`Variable` には、割り当てられたバリエーションに関連付けられた変数に関する情報が含まれます。
| 名前 | 型 | 説明 |
| ----- | -------- | --------------------------------------------------------------------------------------------------------------- |
| key | `String` | 変数を識別する一意のキー。 |
| type | `String` | 変数の型。可能な値: **BOOLEAN**、**NUMBER**、**STRING**、**JSON**。 |
| value | `Any?` | 変数の値。次の型を取ることができます: **Bool**、**Int**、**Double**、**String**、**\[String: Any]**(json オブジェクト)、**\[Any]**(json 配列)。 |
```swift theme={null}
// Retrieving the variables map
let variables = variation.variables
// Variable type can be retrieved for further processing
let type = variables["isDiscount"]?.type ?? ""
// Get the bool value of "isDiscount" (default to false if missing or not a Bool)
let isDiscount = variables["isDiscount"]?.value as? Bool ?? false
// Get the numeric value of "number" as an Int (default to 0 if missing or not numeric)
let number = (variables["number"]?.value as? NSNumber)?.intValue ?? 0
// Get the String value of "title" (default to an empty string if missing or not a String)
let title = variables["title"]?.value as? String ?? ""
```
### 非推奨メソッド
これらのメソッドは非推奨であり、SDK バージョン `5.0.0` で削除される予定です。
#### getFeatureVariationKey()
* 📨 *トラッキングデータを Kameleoon に送信します*
代わりに [`getVariation()`](#getvariation) を使用してください。
このメソッドを使用して、特定のユーザーの[機能バリエーション](/user-manual/experimentation/feature-experimentation/configure-your-feature-flags/define-feature-variations)キーを取得します。このメソッドは、指定されたユーザーのバリエーションキーを取得するために、必須引数として `featureKey` を受け取ります。
訪問者がこの機能フラグに関連付けられたことがない場合、SDK はランダムに割り当てられたバリエーションキー(機能フラグルールに従って)を返します。訪問者がすでにこの機能フラグに登録されている場合、このメソッドは以前のバリエーションキーを返します。訪問者がどのルールにも一致しない場合、Kameleoon アプリで定義したデフォルトバリエーションが返されます。
潜在的なエラーをキャッチするため、サンプルコードに示されているように適切なエラー処理を設定してください。
```swift theme={null}
let featureKey = "new_checkout"
var variationKey = ""
do {
variationKey = try kameleoonClient.getFeatureVariationKey(featureKey: featureKey)
switch variationKey {
case "variation 1":
// The visitor has been bucketed with variation 1 key
case "variation 2":
// The visitor has been bucketed with variation 1 key
default:
//The visitor has been bucketed with the default variation or is part of the unallocated traffic sample
}
} catch {
switch error {
case KameleoonError.sdkNotReady:
// Exception indicating that the SDK has not completed its initialization yet.
case KameleoonError.Feature.notFound:
// The feature key is not in the configuration file that has been fetched by the SDK. Trigger the old checkout for this visitor.
case KameleoonError.Feature.environmentDisabled:
// The feature flag is disabled for the environment.
default:
// Any other error.
}
}
```
#### getActiveFeatureList()
代わりに [`getVariations()`](#getvariations) を使用してください。
訪問者に対して現在利用可能でアクティブな機能フラグキーのリストを取得します。
```swift theme={null}
let activeFeatureFlags = kameleoonClient.getActiveFeatureList()
```
##### 戻り値
| 型 | 説明 |
| --------- | ------------------------- |
| \[String] | 訪問者に対してアクティブな機能フラグキーのリスト。 |
#### getActiveFeatures()
代わりに [`getVariations()`](#getvariations) を使用してください。
`getActiveFeatures` メソッドは、指定された訪問者コードで利用可能なアクティブな機能フラグに関する情報を取得します。
```swift theme={null}
let activeFeatures = kameleoonClient.getActiveFeatures()
```
##### 戻り値
| 型 | 説明 |
| --------------------------- | ---------------------------------------------------------- |
| `[String: Types.Variation]` | 対応するアクティブな機能のキーを使用して、各アクティブな機能に対して訪問者に割り当てられたバリエーションを含む辞書。 |
#### getFeatureVariable()
* 📨 *トラッキングデータを Kameleoon に送信します*
- 代わりに [`getVariation()`](#getvariation) を使用してください。
- このメソッドは以前 `obtainFeatureVariable()` という名前で、SDK バージョン `4.0.0` で削除されました。
このメソッドを呼び出して、ユーザーに関連付けられたバリエーションキーの[機能変数](/user-manual/experimentation/feature-experimentation/configure-your-feature-flags/define-feature-variables)を取得します。
このメソッドは、特定のユーザーのバリエーションキーの変数を取得するために、必須引数として `featureKey` と `variableKey` を受け取ります。
訪問者がこの機能フラグに関連付けられたことがない場合、SDK は機能フラグルールに従ってランダムに割り当てるバリエーションキーの変数値を返します。ユーザーがすでにこの機能フラグに登録されている場合、SDK は以前に関連付けられたバリエーションの変数値を返します。ユーザーがどのルールにも一致しない場合、デフォルトの変数が返されます。
```swift theme={null}
String featureKey = "myFeature"
String variableKey = "myVariable"
try {
let variable = kameleoonClient.getFeatureVariable(featureKey: featureKey, variableKey: variableKey)
// your custom code, depending on variableValue
} catch {
switch error {
case KameleoonError.sdkNotReady:
// Exception indicating that the SDK has not completed its initialization.
case KameleoonError.Feature.notFound:
// The Feature Key is not in the configuration file that has been fetched by the SDK. Trigger the old checkout for this visitor.
case KameleoonError.Feature.environmentDisabled:
// The feature flag is disabled for the environment.
case KameleoonError.Feature.variableNotFound:
// Exception indicating that the requested variable has not been found. Check that the variable's key matches the one in your code.
default:
// Any other error.
}
}
```
##### 引数
| 名前 | 型 | 説明 |
| ----------- | ------ | -------------------------- |
| featureKey | String | 取得したい機能の識別キー。このフィールドは必須です。 |
| variableKey | String | 値を取得したい変数の名前。このフィールドは必須です。 |
##### 戻り値
| 型 | 説明 |
| --- | ------------------------------------------------------------------------------------------------ |
| Any | この機能フラグに関連付けられたデータ。値は `Int`、`String`、`Bool`、または `Dictionary` を取ることができます(Web インターフェースで定義された型に依存)。 |
##### スローされるエラー
| 型 | 説明 |
| ---------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| KameleoonError.sdkNotReady | SDK が完全に初期化されていないことを示す例外。 |
| KameleoonError.Feature.notFound | 要求された機能 ID が SDK の内部構成内で見つからなかったことを示す例外。この例外は通常、機能フラグが Kameleoon 側でまだ有効化されていないことを意味します(ただし、機能を実装するコードはすでに Web アプリケーションにデプロイされています)。 |
| KameleoonException.Feature.environmentDisabled | 機能フラグが訪問者の現在の環境(例えば、production、staging、または development)に対して無効になっていることを示す例外。 |
| KameleoonError.Feature.variableNotFound | 要求された変数が見つからなかったことを示す例外。Kameleoon アプリの変数のキーがコード内のキーと一致するか確認してください。 |
#### getFeatureVariationVariables()
* 代わりに [`getVariation()`](#getvariation) を使用してください。
* このメソッドは以前 `getFeatureAllVariables` という名前で、SDK バージョン `4.0.0` で削除されました。
機能のすべての変数を取得するには、このメソッドを呼び出します。Kameleoon アプリで機能変数を変更できます。
このメソッドは、引数として `featureKey` を受け取ります。Web インターフェースで定義された `[String: Any]` 型のデータを返します。要求された機能が SDK の内部構成内で見つからなかった場合、例外(`KameleoonError.Feature.notFound`)をスローします。
```swift theme={null}
let featureKey = "myFeature"
let variationKey = "on"
do {
allVariables = try kameleoonClient.getFeatureVariationVariables(featureKey: featureKey, variationKey: variationKey);
} catch KameleoonError.Feature.notFound {
// The feature is not activated in Kameleoon.
} catch KameleoonError.Feature.environmentDisabled {
// The feature flag is disabled for the environment.
} catch {
// This is a generic Exception handler that will handle all errors.
}
```
##### 引数
| 名前 | 型 | 説明 |
| ------------ | ------ | ----------------------------- |
| featureKey | String | 取得したい機能の識別キー。このフィールドは必須です。 |
| variationKey | String | 取得したいバリエーションのキー。このフィールドは必須です。 |
##### 戻り値
| 型 | 説明 |
| -------------- | ------------------------------------------------------------------------------------------------ |
| \[String: Any] | この機能フラグに関連付けられたデータ。値は `Int`、`String`、`Bool`、または `Dictionary` を取ることができます(Web インターフェースで定義された型に依存)。 |
##### スローされるエラー
| 型 | 説明 |
| ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| KameleoonError.sdkNotReady | SDK が完全に初期化されていないことを示す例外。 |
| KameleoonError.Feature.notFound | 要求された機能 ID が SDK の内部構成内で見つからなかったことを示す例外。この例外は通常、機能フラグが Kameleoon アプリでまだ有効化されていないことを意味します(ただし、機能を実装するコードはすでに Web アプリケーションにデプロイされています)。 |
| KameleoonException.Feature.environmentDisabled | 機能フラグが訪問者の現在の環境(例えば、production、staging、または development)に対して無効になっていることを示す例外。 |
| KameleoonError.Feature.variationNotFound | 要求されたバリエーションキーが SDK の内部構成内で見つからなかったことを示す例外。この例外は機能フラグが SDK によってまだ取得されていないことを意味します。これは SDK が[ポーリング](/ja/developer-docs/feature-experimentation/technical-reference/technical-considerations#ポーリング（デフォルト）)モードである場合に発生する可能性があります。 |
```swift theme={null}
let featureKey = "myFeature"
let variationKey = "on"
do {
allVariables = try kameleoonClient.getFeatureVariationVariables(featureKey: featureKey, variationKey: variationKey);
} catch KameleoonError.Feature.notFound {
// The feature is not activated in Kameleoon.
} catch KameleoonError.Feature.environmentDisabled {
// The feature flag is disabled for the environment.
} catch {
// This is a generic Exception handler that will handle all errors.
}
```