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 の設定はどちらか一方のみです。SDK 0.4.3 以降では、初期化後に setDatakitURL() で遅延設定できます。設定するまでデータは送信されません。詳しくは送信先アドレスの動的更新を参照してください。 |
| datawayUrl | string | はい | パブリック DataWay の送信 URL アドレス。RUM アプリから取得します。例:https://open.dataway.url。SDK をインストールしたデバイスからこのアドレスにアクセスできる必要があります。注意:datakitUrl と datawayUrl の設定はどちらか一方のみです。SDK 0.4.3 以降では、初期化後に setDatawayURL() で遅延設定できます。設定するまでデータは送信されません。詳しくは送信先アドレスの動的更新を参照してください。 |
| clientToken | string | はい | 認証トークン。datawayUrl と同時に使用する必要があります。SDK 0.4.3 以降では、初期化後に setDatawayURL(datawayUrl, clientToken) で送信先アドレスとまとめて遅延設定できます。詳しくは送信先アドレスの動的更新を参照してください。 |
| debug | boolean | いいえ | ログ出力を許可するかどうか。デフォルトは false です。 |
| env | string | いいえ | 環境設定。デフォルトは prod です。任意の文字列を使用できますが、test などの 1 単語の使用を推奨します。 |
| 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 以降でサポートされます。ルール構文はルール構文を参照してください。 |
| allowWebViewHost | Array |
いいえ | WebView RUM とログで共有する host ホワイトリストを設定します。null はすべての host を許可し、[] はすべての host を禁止します。未設定の場合は旧 RUM 設定を引き継ぎ、それ以外の場合は旧設定より優先されます。リモート設定が優先されます。詳しくは WebView host 設定を参照してください。SDK 0.4.3 以降でサポートされます。 |
| remoteConfiguration | boolean | いいえ | データ収集のリモート設定機能を有効にするかどうか。デフォルトでは無効です。有効にすると、SDK の初期化時またはアプリのホットスタート時にデータ更新がトリガーされます。SDK 0.3.16 以降でサポートされます。設定可能なパラメータ |
| remoteConfigMiniUpdateInterval | number | いいえ | リモート動的設定の最小更新間隔を秒単位で設定します。デフォルトは 12 時間です。SDK 0.3.16 以降でサポートされます。 |
| remoteConfigOverrideRules | Array |
いいえ | リモート設定の上書きルールを設定します。リモート設定を適用する前にカスタム調整できます。SDK 0.3.16 以降でサポートされます。使用例はこちらを参照してください。 |
SDK 0.4.3 以降では、初期化時に送信先アドレスを指定しないでおくことができます:
await FTMobileReactNative.sdkConfig({});
// RUM、Log など必要な収集モジュールの初期化を続行します。
// 送信先アドレスを取得した後に設定します:
await FTMobileReactNative.setDatawayURL('https://open.dataway.url', 'client_token');
アドレスを設定していない場合でも、有効になっている収集モジュールはデータを収集してキャッシュできますが、アップロードは行われません。DataWay アドレスを設定するときは clientToken も同時に指定する必要があります。DataKit を使用する場合は setDatakitURL() を呼び出します。キャッシュには引き続き容量制限があります。詳しくは送信先アドレスの動的更新を参照してください。
ブラックリストフィルタリング¶
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);
動的設定¶
動的設定に関する機能は動的設定に分割されました。