動的構成と動的報告先アドレス更新¶
動的構成の有効化¶
動的構成はデフォルトで無効です。有効にすると、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 は環境、サービス名、アップロード関連の構成をサポートします。RUM はサンプリングレート、自動収集のオン/オフ、WebView ホストのホワイトリストをサポートします。Log はサンプリングレート、レベル、オン/オフをサポートします。Trace はサンプリングレート、自動トレース、タイプをサポートします。オンラインで新しい構成を取得した後、アップロードのオン/オフとパラメータ、Log 構成、Trace のサンプリングレート、RUM のサンプリングレートとエラーサンプリングレートのみが即座に有効になります。その他の構成は次回初期化時に有効になります。
動的構成の手動同期¶
FTSDK を使用して動的構成を手動で同期します。自動更新で要件を満たせない場合、手動で呼び出して更新タイミングを調整できます。
/**
* リモート構成を手動で更新します。呼び出し頻度は FTSDKConfig.setRemoteConfigMiniUpdateInterval の影響を受けます。
*/
FTSDK.updateRemoteConfig();
/**
* 指定された最小更新間隔を使用してリモート構成を手動で更新します。
* 0 を指定すると即時にリクエストします。
*
* @param intervalSeconds 最小更新間隔(秒)。負数は 0 として扱われます。
* @param result 取得結果のコールバック。初期化時のコールバックを上書きできます。
*/
FTSDK.updateRemoteConfig(intervalSeconds, result);
コード例¶
import {
FTSDK,
FTRemoteConfigFetchResult,
RemoteConfigBean
} from '@guancecloud/ft_sdk/Index';
const result: FTRemoteConfigFetchResult = {
onResult(success: boolean): void {
// 取得成功、サーバー構成に変更がなかった場合は true。
},
onConfigSuccessFetched(configBean: RemoteConfigBean, jsonConfig: string): RemoteConfigBean | null {
// オプションの拡張:jsonConfig を解析してカスタム環境変数を解釈し、configBean を変更します。
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 モードでは、有効なクライアントトークンも必要です。相対パス、非 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 アドレスにデータをアップロードし続けます |