動的設定と動的更新アドレス¶
リモート設定¶
リモート設定を通じてプラットフォームから配信される環境変数を取得し、SDK の収集設定を調整します。SDK の初期化時に共通コールバックを登録するか、業務上の必要に応じて能動的に取得し、設定を適用する前にカスタム処理を行うことができます。
前提条件¶
FTSdk.install(sdkConfig) の前に、FTSDKConfig.setRemoteConfiguration(true) でリモート設定を有効化し、有効な送信先アドレスを設定します。その後 RUM を初期化し、FTRUMConfig.setRumAppId(...) を使用して設定を取得するアプリを指定します。完全な導入手順は SDK の初期化 と RUM 設定 を参照してください。
リモートサンプリング設定は接続済みのモジュールに適用されます。ログとトレースの収集には、それぞれの初期化が別途必要です。
更新方法¶
| 更新方法 | 最小更新間隔 | コールバック |
|---|---|---|
| RUM の初期化時、アプリがフォアグラウンドに戻ったときに自動更新を試行 | setRemoteConfigMiniUpdateInterval、デフォルト 12 時間 |
初期化時に登録したグローバルコールバック |
FTSdk.updateRemoteConfig() |
初期化時に設定した間隔を使用 | グローバルコールバック |
FTSdk.updateRemoteConfig(interval, result) |
今回渡した interval を使用。秒単位の非負整数で、0 は間隔チェックをスキップ |
空でない result を優先し、それ以外の場合はグローバルコールバックを使用 |
最小更新間隔はリクエスト頻度を制限するためのものであり、SDK が 12 時間ごとに定期更新するわけではありません。アプリを再起動しても、保存済みのリクエスト時刻はリセットされません。手動更新は非同期リクエストです。0 を渡しても初期化条件を満たす必要があり、既存のリクエストが実行中の場合は今回の呼び出しはスキップされます。
コールバックとカスタム設定¶
ft-sdk >= 1.6.16では、FetchResult.onConfigSuccessFetchedを通じてリモート設定をカスタム調整できます。
FETCH_RESULT の 2 つのメソッドの役割は次のとおりです:
| メソッド | 呼び出しタイミングと用途 |
|---|---|
onConfigSuccessFetched(configBean, jsonConfig) |
有効かつ変更されたリモート設定を取得した後、設定を適用する前に呼び出されます。jsonConfig はレスポンスの content に対応する JSON です。カスタムフィールドを解析し、変更後の configBean を返せます。null を返した場合は、渡されたオブジェクトをそのまま使用します。 |
onResult(success) |
今回の更新結果を返します。true は設定が適用されたか、リモート内容に変更がなかったことを示します。false は更新失敗、RUM App ID の欠落、最小間隔未到達などを示します。 |
今回渡した空でないコールバックはグローバルコールバックを置き換え、両方が同時に実行されることはありません。SDK が未初期化、リモート設定が未有効化、または既存のリクエストが実行中の場合、手動呼び出しではコールバックを受信できないことがあります。コールバックはメインスレッドで実行されることを保証しません。UI を更新する場合はメインスレッドに切り替える必要があります。
最終的な設定は適用され、ローカルキャッシュに書き込まれます。リモート内容に変更がない場合は onResult(true) のみが実行され、手動更新で 0 を渡しても onConfigSuccessFetched は再実行されません。ローカルユーザーや業務条件の変化によって設定の再計算が自動的にトリガーされることはありません。
コード例
以下のサンプリング setter は
ft-sdk >= 1.7.6が必要です。値の範囲は[0,100]で小数をサポートします。旧サンプリングメソッドは[0,1]単位のままです。フィールドと互換性の説明は環境変数を参照してください。
例では sdkConfig、rumConfig の作成を省略し、コールバックを初期化時と業務更新時の両方からアクセスできる位置に保持します。2 つのシナリオは別々のタイミングで実行します。起動時にコールバックを登録し、その後、業務上のトリガーポイントで手動更新します。
custom_userid はリモートから配信されるカスタムフィールドです。例では、このフィールドが一致した場合に 3 つのサンプリング率を 100% に設定します。現在ログインしているユーザーに合わせて調整する場合は、業務側のユーザー ID と組み合わせる必要があり、ユーザー切り替え後の設定復元も処理する必要があります。
// ポイント:カスタムリモート設定コールバック。初期化と手動更新で共用します。
final FTRemoteConfigManager.FetchResult FETCH_RESULT =
new FTRemoteConfigManager.FetchResult() {
@Override
public RemoteConfigBean onConfigSuccessFetched(
RemoteConfigBean configBean, String jsonConfig) {
// リモート設定を適用する前に、カスタムフィールドを解析して設定を上書きできます。
try {
JSONObject json = new JSONObject(jsonConfig);
String userId = json.optString("custom_userid", "");
if ("custom_user_test6".equals(userId)) {
// サンプリング率の範囲:0~100。100f は 100% を表します。
configBean.setSessionSamplingRate(100f);
configBean.setLogSamplingRate(100f);
configBean.setTraceSamplingRate(100f);
}
} catch (JSONException e) {
// カスタム解析に失敗した場合は、元の設定を保持します。
}
return configBean;
}
@Override
public void onResult(boolean success) {
// true:更新成功、または設定に変更なし。
// false:更新失敗、または最小更新間隔未到達など。
}
};
// シナリオ 1:SDK / RUM の初期化時にリモート設定を有効化し、コールバックを登録します。
sdkConfig.setRemoteConfiguration(true)
.setRemoteConfigurationCallBack(FETCH_RESULT);
FTSdk.install(sdkConfig);
FTSdk.initRUMWithConfig(rumConfig); // 既存の RUM 設定を使用します。RUM App ID を含みます。
// シナリオ 2:後続の業務で必要に応じて手動更新します。0 は最小更新間隔を無視することを示します。
// 設定に変更がない場合、コールバックは onResult(true) のみで、カスタム解析は再実行されません。
FTSdk.updateRemoteConfig(0, FETCH_RESULT);
// ポイント:カスタムリモート設定コールバック。初期化と手動更新で共用します。
val FETCH_RESULT = object : FTRemoteConfigManager.FetchResult() {
override fun onConfigSuccessFetched(
configBean: RemoteConfigBean,
jsonConfig: String
): RemoteConfigBean {
// リモート設定を適用する前に、カスタムフィールドを解析して設定を上書きできます。
try {
val json = JSONObject(jsonConfig)
val userId = json.optString("custom_userid", "")
if (userId == "custom_user_test6") {
// サンプリング率の範囲:0~100。100f は 100% を表します。
configBean.setSessionSamplingRate(100f)
configBean.setLogSamplingRate(100f)
configBean.setTraceSamplingRate(100f)
}
} catch (e: JSONException) {
// カスタム解析に失敗した場合は、元の設定を保持します。
}
return configBean
}
override fun onResult(success: Boolean) {
// true:更新成功、または設定に変更なし。
// false:更新失敗、または最小更新間隔未到達など。
}
}
// シナリオ 1:SDK / RUM の初期化時にリモート設定を有効化し、コールバックを登録します。
sdkConfig.setRemoteConfiguration(true)
.setRemoteConfigurationCallBack(FETCH_RESULT)
FTSdk.install(sdkConfig)
FTSdk.initRUMWithConfig(rumConfig) // 既存の RUM 設定を使用します。RUM App ID を含みます。
// シナリオ 2:後続の業務で必要に応じて手動更新します。0 は最小更新間隔を無視することを示します。
// 設定に変更がない場合、コールバックは onResult(true) のみで、カスタム解析は再実行されません。
FTSdk.updateRemoteConfig(0, FETCH_RESULT)
AndroidID の取得の動的な有効化と無効化¶
FTSdk を使用して、SDK で Android ID を取得するかどうかを設定します。
送信先アドレスの動的更新¶
FTSdk を使用して、SDK の実行中にデータの送信先アドレスを動的に切り替えます。設定が成功すると、以降のデータは新しいアドレスに継続してアップロードされます。
ft-sdk >= 1.6.17 でサポートされます。
setDatakitUrlとsetDatawayUrlはどちらか一方を使用します。setDatawayUrlを使用する場合は、新しいclientTokenも同時に渡す必要があります。
ユースケース¶
FTSDKConfig.builder() は初期化時に datakitUrl または datawayUrl を渡さないことをサポートします。このシナリオでは、SDK はまずデータ収集を実行しますが、アップロードは行いません。
その後 FTSdk.setDatakitUrl(...) または FTSdk.setDatawayUrl(..., ...) を呼び出して送信先アドレスを動的に設定すると、SDK はローカルキャッシュの消費を開始し、データ送信を実行します。
注意点として、アップロード先アドレスが未設定の期間も、収集されたデータはローカルキャッシュの上限の影響を受けます。キャッシュ上限は主に以下の設定によって決まります:
FTLoggerConfig.setLogCacheLimitCountFTRUMConfig.setRumCacheLimitCountFTSDKConfig.enableLimitWithCacheSizeに対応する総キャッシュサイズの上限
キャッシュが上限に達すると、超過分のデータは破棄される可能性があります。そのため、このモードではできるだけ早くアップロード先アドレスを追加するか、業務シナリオに合わせてキャッシュ制限を適切に設定することを推奨します。
| メソッド名 | 型 | 必須 | 説明 |
|---|---|---|---|
| setDatakitUrl | String | 必須 | Datakit の送信先アドレスを動的に設定します。設定が成功すると、SDK は新しい Datakit アドレスへのデータアップロードを継続します。 |
| setDatawayUrl | String, String | 必須 | Dataway の送信先アドレスと clientToken を動的に設定します。設定が成功すると、SDK は新しい Dataway アドレスへのデータアップロードを継続します。 |