動的設定とデータアップロード先の動的更新¶
本記事の例では FTSDKAgent と FTSDKConfig を使用します。既存プロジェクトで使用されている FTMobileAgent と FTMobileConfig は、対応する互換インターフェースを通じて引き続き利用できます。
リモート設定¶
リモート設定を通じてプラットフォームから配信される環境変数を取得し、SDK の収集設定を調整します。SDK の初期化時に統一コールバックを登録することも、業務で必要なときに能動的に取得し、設定を適用する前にカスタム処理を行うこともできます。
前提条件¶
メインスレッドで SDK を起動する前に、FTSDKConfig.remoteConfiguration = YES を設定し、有効なアップロード先を構成します。その後 RUM を初期化し、FTRumConfig の App ID で、設定を取得するアプリを指定します。完全な接続手順については、SDK 初期化と RUM 設定を参照してください。
リモートサンプリング設定は、接続済みのモジュールに適用されます。ログと分散型トレーシングの収集では、それぞれの初期化を完了する必要があります。
更新方法¶
| 更新方法 | 最小更新間隔 | コールバック |
|---|---|---|
| RUM の初期化時、アプリがフォアグラウンドに戻ったときに自動更新を試行 | remoteConfigMiniUpdateInterval、デフォルトは 12 時間 |
初期化時に登録されたグローバルコールバック |
引数なしの updateRemoteConfig |
初期化時に設定した間隔を使用 | グローバルコールバック |
updateRemoteConfigWithMiniUpdateInterval:completion:(Swift:updateRemoteConfig(withMiniUpdateInterval:completion:)) |
今回渡した間隔を使用します。単位は秒で、値は非負整数です。0 は間隔チェックをスキップします |
今回の completion を指定可能 |
最小更新間隔はリクエスト頻度を制限するためのものです。SDK が 12 時間ごとに定期的に更新することはなく、アプリを再起動しても保存済みのリクエスト時刻はリセットされません。能動的な更新は非同期リクエストです。0 を渡す場合も初期化条件を満たす必要があり、既存のリクエストが実行中の場合は今回の呼び出しをスキップし、今回渡したコールバックに失敗結果を返します。
コールバックとカスタム設定¶
SDK 1.5.19 以降では、
FTRemoteConfigFetchCompletionBlockの戻り値を通じて最終設定をカスタマイズして変更できます。
コールバックは設定を適用する前に実行されます。各パラメータの意味は次のとおりです。
| パラメータ | 意味 |
|---|---|
success |
今回の取得操作の結果。YES は model、content が非 nil であることを保証しません。NO はリクエストが実行されなかったか、取得に失敗したことを示します。 |
error |
失敗の詳細。成功時は nil。 |
model |
変更可能な設定モデル。使用前に非 nil を確認してください。 |
content |
今回のコールバックに関連する設定辞書。カスタムフィールドを読み取れます。リモートコンテンツが変更されていない場合は、キャッシュ済みの設定に由来する可能性があります。 |
成功し model が非 nil の場合は、変更後のモデルを返します。SDK がこれを適用してキャッシュします。nil を返した場合は、SDK がコールバックに渡す前のモデルを使用します。失敗時は nil を返します。コールバックはメインスレッドで実行されることを保証しません。UI を更新する場合はメインスレッドに切り替える必要があります。
今回渡した非 nil の completion は FTSDKConfig.remoteConfigFetchCompletionBlock より優先され、両方が同時に実行されることはありません。引数なしの updateRemoteConfig はグローバルコールバックを使用します。明示的に nil を渡した場合、実際にリクエストを開始した後はグローバルコールバックを使用しますが、リクエスト前のチェックで通過しなかった結果はグローバルコールバックに通知されない可能性があります。
実際のリクエストが成功し、リモートコンテンツが変更されていない場合でも、コールバックは実行され、既存のモデルが渡されます。success = YES はサーバー側の設定が変更されたことを意味しません。
コード例
SDK 1.6.8 以降では、以下の小数パーセントサンプリングフィールドをサポートします。値の範囲は
[0,100]です。旧サンプリング属性は互換性のため保持されています。フィールドと優先順位については環境変数を参照してください。
例では config、rumConfig の作成を省略し、コールバックを初期化時と業務上の更新時の両方からアクセスできる場所に保存します。2 つのシナリオは別々のタイミングで実行します。起動時にコールバックを登録し、その後、業務のトリガーポイントで能動的に更新します。
custom_userid はリモートから配信されるカスタムフィールドです。例では、このフィールドが一致した場合に 3 つのサンプリングレートを 100% に設定します。現在ログインしているユーザーに合わせて調整する場合は、業務側のユーザー ID と組み合わせる必要があり、ユーザー切り替え後の設定復元も処理する必要があります。
// 核心:再利用可能なリモート設定コールバックを定義します。
FTRemoteConfigFetchCompletionBlock handler =
^FTRemoteConfigModel * _Nullable(
BOOL success,
NSError * _Nullable error,
FTRemoteConfigModel * _Nullable model,
NSDictionary<NSString *, id> * _Nullable content) {
if (!success || !model) {
return nil;
}
id userId = content[@"custom_userid"];
if ([userId isKindOfClass:NSString.class] &&
[userId isEqualToString:@"user_1"]) {
model.sessionSamplingRate = @100; // RUM:100%
model.logSamplingRate = @100; // Log:100%
model.traceSamplingRate = @100; // Trace:100%
}
return model; // SDK は変更後の設定を使用します。
};
// シナリオ 1:SDK / RUM の初期化時に設定します(config、rumConfig の作成は省略)。
config.remoteConfiguration = YES;
config.remoteConfigFetchCompletionBlock = handler;
[FTSDKAgent startWithConfigOptions:config];
[[FTSDKAgent sharedInstance] startRumWithConfigOptions:rumConfig];
// シナリオ 2:後続の業務で必要に応じて能動的に更新し、同じコールバックを再利用します。
// 0 は最小更新間隔を無視することを示します。
[FTSDKAgent updateRemoteConfigWithMiniUpdateInterval:0
completion:handler];
// 核心:再利用可能なリモート設定コールバックを定義します。
let handler: FTRemoteConfigFetchCompletionBlock = { success, error, model, content in
guard success, let model = model else {
return nil
}
let userId = content?["custom_userid"] as? String
if userId == "user_1" {
model.sessionSamplingRate = 100 // RUM:100%
model.logSamplingRate = 100 // Log:100%
model.traceSamplingRate = 100 // Trace:100%
}
return model // SDK は変更後の設定を使用します。
}
// シナリオ 1:SDK / RUM の初期化時に設定します(config、rumConfig の作成は省略)。
config.remoteConfiguration = true
config.remoteConfigFetchCompletionBlock = handler
FTSDKAgent.start(withConfigOptions: config)
FTSDKAgent.sharedInstance().startRum(withConfigOptions: rumConfig)
// シナリオ 2:後続の業務で必要に応じて能動的に更新し、同じコールバックを再利用します。
// 0 は最小更新間隔を無視することを示します。
FTSDKAgent.updateRemoteConfig(withMiniUpdateInterval: 0, completion: handler)
データアップロード先の動的更新¶
FTSDKAgent を使用して、SDK の実行中にデータアップロード先を動的に切り替えます。設定に成功すると、以降のデータは新しいアドレスに継続してアップロードされます。
SDK 1.5.21 以降では
setDatakitURLとsetDatawayURL:clientToken:をサポートします。setDatakitURLとsetDatawayURL:clientToken:はどちらか一方を使用します。setDatawayURL:clientToken:を使用する場合は、新しいclientTokenも同時に渡す必要があります。
ユースケース¶
FTSDKConfig は初期化時に datakitUrl または datawayUrl を渡さないことをサポートしています。このシナリオでは、SDK はまずデータ収集を実行しますが、アップロードは行いません。
その後、[FTSDKAgent setDatakitURL:] または [FTSDKAgent setDatawayURL:clientToken:] を呼び出してアップロード先を動的に設定すると、SDK はローカルキャッシュの消費を開始し、データアップロードを実行します。
注意点として、アップロード先が設定されていない期間でも、収集されたデータはローカルキャッシュの上限の制限を受けます。キャッシュ上限は主に以下の設定の組み合わせによって決まります。
FTLoggerConfig.logCacheLimitCountFTRumConfig.rumCacheLimitCountFTSDKConfig.enableLimitWithDbSizeに対応するデータベースキャッシュ上限
キャッシュが上限に達した場合、上限を超えたデータは破棄される可能性があります。そのため、このモードではできるだけ早くアップロード先を設定するか、業務シナリオに合わせてキャッシュ制限を適切に設定することを推奨します。
| メソッド名 | 型 | 必須 | 意味 |
|---|---|---|---|
| setDatakitURL | NSString | はい | Datakit のアップロード先を動的に設定します。設定に成功すると、SDK は新しい Datakit アドレスへのデータアップロードを継続します。 |
| setDatawayURL:clientToken: | NSString, NSString | はい | Dataway のアップロード先と clientToken を動的に設定します。設定に成功すると、SDK は新しい Dataway アドレスへのデータアップロードを継続します。 |