SDK の初期化¶
このドキュメントでは、React Native SDK の初期化とランタイム機能に関する内容を説明します。
SDK のインポート¶
コード内では、次のように使用できます:
import {
FTMobileReactNative,
FTReactNativeLog,
FTReactNativeTrace,
FTReactNativeRUM,
FTMobileConfig,
FTLogConfig,
FTTraceConfig,
FTRUMConfig,
ErrorMonitorType,
DeviceMetricsMonitorType,
DetectFrequency,
TraceType,
FTLogStatus,
EnvType,
} from '@cloudcare/react-native-mobile';
基本設定¶
// ローカル環境デプロイ、Datakit デプロイ
let config: FTMobileConfig = {
datakitUrl: datakitUrl,
};
// パブリック DataWay を使用
let config: FTMobileConfig = {
datawayUrl: datawayUrl,
clientToken: clientToken,
};
await FTMobileReactNative.sdkConfig(config);
| フィールド | 型 | 必須 | 説明 |
|---|---|---|---|
| datakitUrl | string | 必須 | ローカル環境デプロイ(Datakit)のレポート URL アドレス。例:http://10.0.0.1:9529、ポートはデフォルトで 9529。SDK をインストールしたデバイスからこのアドレスにアクセスできる必要があります。注意:datakitUrl と datawayUrl はどちらか一方のみ設定してください |
| datawayUrl | string | 必須 | パブリック DataWay のレポート URL アドレス。RUM アプリから取得します。例:https://open.dataway.url、SDK をインストールしたデバイスからこのアドレスにアクセスできる必要があります。注意:datakitUrl と datawayUrl はどちらか一方のみ設定してください |
| clientToken | string | 必須 | 認証トークン。datawayUrl と同時に使用する必要があります |
| debug | boolean | 任意 | ログの出力を許可するかどうか。デフォルトは false |
| env | string | 任意 | 環境設定。デフォルトは prod。任意の文字列です。単一の単語での使用を推奨します(例:test など) |
| envType | enum EnvType | 任意 | 環境設定。デフォルトは EnvType.prod。注:env と envType はどちらか一方を設定すれば十分です |
| service | string | 任意 | 所属する業務またはサービスの名前を設定します。Log と RUM の service フィールドのデータに影響します。デフォルト:df_rum_ios、df_rum_android |
| autoSync | boolean | 任意 | データ収集後にサーバーへ自動同期するかどうか。デフォルトは true。false の場合は、FTMobileReactNative.flushSyncData() を使用してデータ同期を管理します |
| syncPageSize | number | 任意 | 同期リクエストの項目数を設定します。範囲 [5,)。注意:リクエスト項目数が大きいほど、データ同期により多くの計算リソースを消費します |
| syncSleepTime | number | 任意 | 同期の間隔時間を設定します。範囲 [0,5000]。デフォルトでは設定されません |
| enableDataIntegerCompatible | boolean | 任意 | Web データと共存する場合は有効化を推奨します。この設定は、Web データ型の保存互換性の問題を処理するためのものです。0.3.12 以降のバージョンではデフォルトで有効です |
| globalContext | object | 任意 | カスタムタグを追加します。追加ルールはこちらを参照してください |
| compressIntakeRequests | boolean | 任意 | アップロード同期データを deflate 圧縮します。デフォルトでは無効です |
| enableLimitWithDbSize | boolean | 任意 | DB を使用したデータサイズ制限を有効にします。デフォルトは 100MB、単位は Byte。データベースが大きいほどディスク負荷が高くなります。デフォルトでは無効です。注意:有効にすると、Log 設定の logCacheLimitCount と RUM 設定の rumCacheLimitCount は無効になります。SDK 0.3.10 以降でこのパラメータをサポートしています |
| dbCacheLimit | number | 任意 | DB キャッシュの制限サイズ。範囲 [30MB,)、デフォルトは 100MB、単位は byte。SDK 0.3.10 以降でこのパラメータをサポートしています |
| dbDiscardStrategy | string | 任意 | データベース内のデータ破棄ルールを設定します。破棄ポリシー:FTDBCacheDiscard.discard は新しいデータを破棄(デフォルト)、FTDBCacheDiscard.discardOldest は古いデータを破棄。SDK 0.3.10 以降でこのパラメータをサポートしています |
| dataModifier | object | 任意 | 単一フィールドを変更します。SDK 0.3.14 以降でサポート。使用例はデータ収集マスキングを参照してください |
| lineDataModifier | object | 任意 | 単一のデータ行を変更します。SDK 0.3.14 以降でサポート。使用例はデータ収集マスキングを参照してください |
| enableDataFilter | boolean | 任意 | SDK 側のブラックリストフィルタリングを有効にするかどうか。デフォルトは true。Log と RUM データのフィルタリングをサポートします。SDK 0.4.2 以降でサポート。使用例はブラックリストフィルタリングを参照してください |
| dataFilters | Record |
任意 | アプリ内のブラックリストルールを設定します。logging と rum の 2 種類のデータをサポートします。SDK 0.4.2 以降でサポート。ルール構文はルール構文を参照してください |
| remoteConfiguration | boolean | 任意 | データ収集のリモート設定機能を有効にするかどうか。デフォルトでは無効です。有効にすると、SDK の初期化時またはアプリのホットスタート時にデータ更新がトリガーされます。SDK 0.3.16 以降でサポート。設定可能なパラメータ |
| remoteConfigMiniUpdateInterval | number | 任意 | リモート動的設定の最小更新間隔を設定します。単位は秒、デフォルトは 12 時間。SDK 0.3.16 以降でサポート |
| remoteConfigOverrideRules | Array |
任意 | リモート設定の上書きルールを設定します。アプリのリモート設定前にカスタム調整できます。SDK 0.3.16 以降でサポート。使用例はこちらを参照してください |
ブラックリストフィルタリング¶
React Native SDK 0.4.2 以降では、データをローカルキャッシュに書き込む前に RUM と Log データをフィルタリングできます。この機能はデフォルトで有効になっており、enableDataFilter: false を設定することで SDK 側のフィルタリングを無効にできます。
ブラックリストルールは、Guance ワークスペースのブラックリストで一元的に設定でき、SDK が DataKit または DataWay から自動的に取得します。また、FTMobileConfig.dataFilters を使用してアプリ内で設定することもできます。2 つの方法は同じブラックリストフィルタリング機能に対応しており、同時に使用できます。いずれかのルールが一致した場合、そのデータは破棄されます。
ブラックリストフィルタリングは lineDataModifier の後、ローカルキャッシュへの書き込み前に実行されます。lineDataModifier とブラックリストフィルタリングの両方を設定している場合、フィルタリングルールは変更後のデータに基づいて判定されます。
enableDataFilterは SDK 側のルール取得とフィルタリングのみを制御します。falseに設定すると、SDK はdataFiltersを適用せず、ワークスペースのルールも取得しません。DataKit 経由でレポートする場合、ワークスペースのブラックリストは DataKit 側で引き続き実行される可能性があります。Data Filter は SDK のデータ書き込み経路に作用します。ルールが多すぎる場合や正規表現が複雑すぎる場合は、データ書き込みのパフォーマンスに影響を与える可能性があります。必要なルールのみを設定することを推奨します。
let config: FTMobileConfig = {
datawayUrl: datawayUrl,
clientToken: clientToken,
enableDataFilter: true,
dataFilters: {
logging: [
"{ `source` in [ 'df_rum_ios_log' , 'df_rum_android_log' ] and `message` match [ 'timeout' ] }",
],
rum: [
"{ `resource_status` match [ '5..' ] }",
],
},
};
await FTMobileReactNative.sdkConfig(config);
SDK は初期化時に、ワークスペースのブラックリストルールを直ちに取得します。以降の取得間隔は、サーバーが返す pull_interval に従います。サーバーが有効な値を返さない場合、SDK はフォールバック間隔として 10 秒を使用します。pull_interval は秒数または単位付きの文字列(例:10、30s、2m、1h)をサポートします。
ルール構文¶
Data Filter のルール構文は、ブラックリストフィルタリングルールとほぼ同一です。完全な構文については、ブラックリストフィルタリングルール を参照してください。
dataFilters の key はデータ分類を表します。現在 SDK がサポートしている分類は次のとおりです:
| 分類 | 説明 |
|---|---|
logging |
Log データ |
rum |
RUM データ |
各ルールは { 条件 } で表します。いずれかのルールに一致すると、その分類のデータはフィルタリングされます。ルール内では、データの tag、field フィールドと、source、measurement のデータ型識別フィールドを使用できます。
フィールド値の形式と演算子の意味については、ブラックリストフィルタリングルールのフィールド値の形式の説明と演算子の説明を参照してください。
SDK のルール文字列内のフィールド値は、配列形式の使用を推奨します。否定演算子は not in、not match をサポートし、サーバーから配信されるルールで使用される notin、notmatch、not_in とも互換性があります。
ユーザー情報のバインドとアンバインド¶
使用方法¶
/**
* ユーザーをバインドします。
* @param userId ユーザー ID。
* @param userName ユーザー名。
* @param userEmail ユーザーのメールアドレス。
* @param extra ユーザーの追加情報。
*/
bindRUMUserData(userId: string, userName?: string, userEmail?: string, extra?: object): Promise<void>;
/**
* ユーザーのバインドを解除します。
*/
unbindRUMUserData(): Promise<void>;
使用例¶
import { FTMobileReactNative } from '@cloudcare/react-native-mobile';
FTMobileReactNative.bindRUMUserData('react-native-user', 'user_name');
FTMobileReactNative.unbindRUMUserData();
ランタイム機能¶
SDK のシャットダウン¶
FTMobileReactNative を使用して SDK をシャットダウンします。
SDK キャッシュデータのクリア¶
FTMobileReactNative を使用して、未送信のキャッシュデータをクリアします。
データの手動同期¶
FTMobileConfig.autoSync を true に設定している場合、追加の操作は不要で、SDK が自動的に同期します。
FTMobileConfig.autoSync を false に設定している場合、データ同期を手動でトリガーする必要があります。
/**
* データを手動同期します。`FTMobileConfig.autoSync = false` に設定している場合は、手動でトリガーする必要があります。
*/
flushSyncData(): Promise<void>;
初期化順序の説明¶
SDK の他のメソッドを呼び出す前に SDK が完全に準備されていることを確認するため、トップレベルの index.js ファイルで App を登録する前に SDK の初期化を完了してください。
基本設定を完了した後、RUM、Log、Trace の設定を行います。
import App from './App';
async function sdkInit() {
await FTMobileReactNative.sdkConfig(config);
await FTReactNativeRUM.setConfig(rumConfig);
// ...
}
sdkInit();
AppRegistry.registerComponent('main', () => App);
動的設定¶
動的設定に関する機能は、動的設定 に分割されています。