動的設定と送信先アドレスの動的更新¶
動的設定を有効にする¶
動的設定はデフォルトで無効です。有効にすると、SDK はインストール時にローカルキャッシュを読み込みます。RUM 設定がインストール済みで有効な送信先アドレスが存在する場合、SDK は RUM アプリケーション ID を使用してサーバー側の設定を取得します。送信先アドレスが実行時に設定された場合、SDK はアドレスが有効になった後に動的設定の取得を継続します。
import {
FTSDK,
FTSDKConfig,
FTRUMConfig,
FTRemoteConfigFetchResult,
RemoteConfigBean
} from '@guancecloud/ft_sdk/Index';
const remoteConfigResult: FTRemoteConfigFetchResult = {
// サーバーが有効かつ変更された設定を返したときに呼び出されます。
onConfigSuccessFetched(configBean: RemoteConfigBean, jsonConfig: string): RemoteConfigBean | null {
// jsonConfig からカスタム環境変数を解析し、変更後の設定を返すことができます。
return configBean;
},
// 取得成功時、またはサーバー側設定が変更されていない場合は true。リクエスト失敗時、または更新間隔を満たさない場合は false。
onResult(success: boolean): void {
// 必要に応じて取得結果を記録
}
};
const sdkConfig = FTSDKConfig.builder()
.setRemoteConfiguration(true)
.setRemoteConfigMiniUpdateInterval(43200)
.setRemoteConfigurationCallBack(remoteConfigResult);
FTSDK.install(sdkConfig, this.context);
FTSDK.installRUMConfig(new FTRUMConfig().setRumAppId('your-rum-app-id'));
| メソッド | 型 | デフォルト値 | 説明 |
|---|---|---|---|
setRemoteConfiguration |
boolean |
false |
動的設定を有効にするか |
setRemoteConfigMiniUpdateInterval |
number |
43200 |
最小取得間隔(秒)。小数は切り捨て、負数は 0 として扱います。0 を渡すと即時更新に使用できます |
setRemoteConfigurationCallBack |
FTRemoteConfigFetchResult \| null |
null |
取得結果コールバックを設定します。onConfigSuccessFetched は変更後の RemoteConfigBean を返すことができ、onResult は結果を受け取るために使用します |
ローカルキャッシュは各設定のインストール前にマージされます。ベース SDK は環境、サービス名、アップロード関連設定、WebView Host ホワイトリストをサポートします。RUM はサンプリングレートと自動収集スイッチをサポートします。Log はサンプリングレート、レベル、スイッチをサポートします。Trace はサンプリングレート、自動トレース、タイプをサポートします。新しい設定をオンラインで取得した後、アップロードスイッチとパラメータ、Log 設定、Trace サンプリングレート、RUM サンプリングレートとエラーサンプリングレートは直ちに有効になります。WebView Host ホワイトリストは以降の新しいバインドに対して有効になり、その他の設定は次回の初期化時に有効になります。
WebView Host ホワイトリストの優先順位は、リモートの rumAllowWebViewHost > 明示的に設定された FTSDKConfig.setAllowWebViewHost(...) > 非推奨の FTRUMConfig.setAllowWebViewHost(...) です。リモートのフィールドが欠落している場合はローカル設定を復元し、不正な値の場合は前回有効だったリモート設定を保持し、有効なリモート設定がない場合はローカルにフォールバックします。キャッシュはフィールドの欠落、null、[] を区別します。既存のバインドは設定更新に追随しないため、Web コンポーネントと controller を再作成してバインドする必要があります。Host の値については SDK 初期化設定 を参照してください。
動的設定を手動で同期する¶
FTSDK を使用して動的設定を手動で同期します。自動更新で要件を満たせない場合は、明示的に呼び出すことで更新タイミングを調整できます。
ft_sdk0.1.18 以降では、onConfigSuccessFetched(configBean, jsonConfig)を通じて環境変数を独自に解析し、収集設定を調整できます。
/**
* リモート設定を明示的に更新します。呼び出し頻度は FTSDKConfig.setRemoteConfigMiniUpdateInterval の影響を受けます。
*/
FTSDK.updateRemoteConfig();
/**
* リモート設定を明示的に更新し、指定した最小更新間隔を使用します。
* 0 を渡すと即時リクエストします。
*
* @param intervalSeconds 最小更新間隔(秒)。負数は 0 として扱います。
* @param result 取得結果コールバック。初期化時のコールバックを上書きできます。
*/
FTSDK.updateRemoteConfig(intervalSeconds, result);
コード例¶
以下の例では、カスタム環境変数 custom_userid を解析し、custom_user_test6 を VIP ユーザーとして識別して、その RUM、Log、Trace のサンプリングレートを 100(全収集)に設定します。パーセントサンプリング API の値の範囲は [0,100] です。
import {
FTSDK,
FTRemoteConfigFetchResult,
RemoteConfigBean
} from '@guancecloud/ft_sdk/Index';
interface CustomRemoteConfig {
custom_userid?: string;
}
const result: FTRemoteConfigFetchResult = {
onResult(success: boolean): void {
// 取得に成功した場合、またはサーバー側設定が変更されていない場合は true。
},
onConfigSuccessFetched(configBean: RemoteConfigBean, jsonConfig: string): RemoteConfigBean | null {
// 任意の拡張。独自に解析してローカル設定を変更します。
let isVip = false;
try {
const customConfig = JSON.parse(jsonConfig) as CustomRemoteConfig;
isVip = customConfig.custom_userid === 'custom_user_test6';
} catch (error) {
// 解析に失敗した場合は元の設定を保持します。
}
if (isVip) {
configBean.setSessionSamplingRate(100);
configBean.setLogSamplingRate(100);
configBean.setTraceSamplingRate(100);
}
return configBean;
}
};
// 0 を渡すと即時リクエストし、今回のコールバックで初期化時のコールバックを上書きします。
FTSDK.updateRemoteConfig(0, result);
デバイス識別子の動的な有効化と無効化¶
FTSDK を使用して、SDK でシステムのデバイス識別子を取得するかどうかを設定します。デフォルトでは、SDK が永続化したプライバシー UUID を device_uuid として使用します。有効にすると、SDK は ODID の取得を優先し、ODID が利用できない場合は UDID にフォールバックし、それでも利用できない場合はプライバシー UUID を使用します。
// システムのデバイス識別子へのアクセスを有効にする
FTSDK.setEnableAccessDeviceID(true);
// SDK のプライバシー UUID に切り替える
FTSDK.setEnableAccessDeviceID(false);
送信先アドレスの動的更新¶
FTSDK を使用して、SDK の実行中にデータ送信先アドレスを動的に切り替えます。FTSDK.install(...) の完了後に呼び出してください。設定に成功すると、以降のデータは新しいアドレスに継続してアップロードされます。
setDatakitUrlとsetDatawayUrlはどちらか一方を使用します。setDatawayUrlを使用する場合は、新しいclientTokenも同時に渡す必要があります。
ユースケースの説明¶
FTSDKConfig.builder() は、初期化時に datakitUrl または datawayUrl を渡さないことをサポートしています。この場合、SDK はまずデータ収集を実行しますが、データはアップロードしません。
その後、FTSDK.setDatakitUrl(...) または FTSDK.setDatawayUrl(..., ...) を呼び出して完全かつ有効な HTTP(S) 送信先アドレスを設定すると、SDK はローカルキャッシュの消費を開始し、自動アップロードを再開します。DataWay モードでは有効なクライアント Token も必要です。相対パス、HTTP(S) 以外のプロトコル、または形式が不正なアドレスでは自動アップロードは再開されません。直ちにアップロードをリクエストする必要がある場合は、FTSDK.flushSyncData() を呼び出せます。
動的設定が有効な場合、有効な送信先アドレスに切り替えた後、SDK は新しいアドレスからリモート設定を直ちにリフレッシュします。旧アドレスで進行中のリクエスト結果は無視されます。ブラックリストフィルタリングが有効な場合、SDK は旧アドレスのリモートルールをクリアし、新しいアドレスから直ちに再取得します。ローカルルールは引き続き保持されます。
実行時に設定したアドレスはメモリ内にのみ保存されるため、アプリの再起動後に再度設定する必要があります。SDK のインストール前に送信先アドレスを設定する場合は、FTSDKConfig.builder() が返す設定オブジェクトで setDatakitUrl(...) または setDatawayUrl(...) を呼び出してください。詳細は SDK 初期化 を参照してください。
アップロード先アドレスが未設定の間も、収集されたデータはローカルキャッシュの上限に制限されます。キャッシュが上限に達すると、超過したデータは破棄される可能性があるため、できるだけ早く送信先アドレスを設定し、業務シナリオに合わせてキャッシュ制限を適切に設定することを推奨します。
import { FTSDK } from '@guancecloud/ft_sdk/Index';
// DataKit を使用して送信
FTSDK.setDatakitUrl('http://10.0.0.1:9529');
// または DataWay を使用して送信
FTSDK.setDatawayUrl('https://open.dataway.url', 'your-client-token');
| メソッド名 | 型 | 必須 | 説明 |
|---|---|---|---|
setDatakitUrl |
string |
必須 | FTSDK.install(...) の後に DataKit の送信先アドレスを動的に設定します。設定に成功すると、SDK は新しい DataKit アドレスへのデータアップロードを継続します |
setDatawayUrl |
string, string |
必須 | FTSDK.install(...) の後に DataWay の送信先アドレスと clientToken を動的に設定します。設定に成功すると、SDK は新しい DataWay アドレスへのデータアップロードを継続します |