SDK の初期化¶
この記事では、Flutter SDK の初期化と実行時機能に関する内容を説明します。
基本設定¶
void main() async {
WidgetsFlutterBinding.ensureInitialized();
// ローカル環境デプロイ、Datakit デプロイ
await FTMobileFlutter.sdkConfig(
datakitUrl: datakitUrl,
);
// パブリック DataWay を使用
await FTMobileFlutter.sdkConfig(
datawayUrl: datawayUrl,
cliToken: cliToken,
);
}
| フィールド | 型 | 必須 | 説明 |
|---|---|---|---|
| datakitUrl | String | いいえ | ローカル環境デプロイ(Datakit)の送信先 URL アドレス。例:http://10.0.0.1:9529。ポートはデフォルトで 9529 です。SDK をインストールしたデバイスからこのアドレスにアクセスできる必要があります。注意:送信先アドレスを設定する際は、datakitUrl と datawayUrl のいずれか一方のみを設定してください。SDK 0.5.8 以降では、一時的に設定せず、後から実行時メソッドで設定できます |
| datawayUrl | String | いいえ | パブリック DataWay の送信先 URL アドレス。リアルユーザーモニタリング(RUM)アプリから取得します。例:https://open.dataway.url。SDK をインストールしたデバイスからこのアドレスにアクセスできる必要があります。注意:送信先アドレスを設定する際は、datakitUrl と datawayUrl のいずれか一方のみを設定してください。SDK 0.5.8 以降では、一時的に設定せず、後から実行時メソッドで設定できます |
| cliToken | String | DataWay 使用時は必須 | 認証トークン。datawayUrl と同時に設定する必要があります。アドレスを後から設定する場合は、setDatawayURL(datawayUrl, cliToken) でまとめて設定します |
| debug | bool | いいえ | ログ出力を許可するかどうか。デフォルトは false |
| env | String | いいえ | 環境設定。デフォルトは prod。任意の文字列を指定できますが、test のような単一単語を推奨します |
| envType | enum EnvType | いいえ | 環境設定。デフォルトは EnvType.prod。注意:env と envType はどちらか一方のみを設定してください |
| autoSync | bool | いいえ | データ収集後にサーバーへ自動同期するかどうか。デフォルトは true。false の場合は FTMobileFlutter.flushSyncData() を使用してデータ同期を自身で管理します |
| syncPageSize | enum | いいえ | 同期リクエストの件数を設定します。SyncPageSize.mini は 5 件、SyncPageSize.medium は 10 件、SyncPageSize.large は 50 件、デフォルトは SyncPageSize.medium |
| customSyncPageSize | number | いいえ | 同期リクエストの件数を設定します。範囲は [5, )。リクエスト件数が多いほど、データ同期がより大きな計算リソースを消費します |
| syncSleepTime | number | いいえ | 同期間隔を設定します。範囲は [0,5000]。デフォルトでは設定されません |
| globalContext | object | いいえ | カスタムタグを追加します。追加ルールは競合フィールドの説明を参照してください |
| serviceName | String | いいえ | サービス名 |
| customHttpOverrides | HttpOverrides | いいえ | カスタム HTTP Overrides。HTTP 自動収集を有効にした際、プロジェクトで HttpOverrides.global をカスタマイズ済みの場合は、このパラメータでカスタム実装を渡すことができ、SDK は収集処理でその実装を再利用します |
| enableLimitWithDbSize | boolean | いいえ | DB を使用してデータサイズを制限する機能を有効にします。デフォルトは 100MB(単位: Byte)で、デフォルトでは無効です。有効にすると logCacheLimitCount および rumCacheLimitCount は無効になります。SDK 0.5.3-pre.2 以降でサポートされます |
| dbCacheLimit | number | いいえ | DB キャッシュの制限サイズ。範囲は [30MB, )、デフォルトは 100MB(単位: byte)。SDK 0.5.3-pre.2 以降でサポートされます |
| dbCacheDiscard | string | いいえ | データベース内のデータ破棄ルールを設定します。FTDBCacheDiscard.discard は新しいデータを破棄し(デフォルト)、FTDBCacheDiscard.discardOldest は古いデータを破棄します。SDK 0.5.3-pre.2 以降でサポートされます |
| enableLimitWithCacheSize | boolean | いいえ | キャッシュサイズを使用してデータサイズを制限する機能を有効にします。Android ではキャッシュ総サイズによる制限を使用し、iOS では DB キャッシュサイズ制限にマッピングされます。有効にすると cacheLimit が優先され、未設定の場合は dbCacheLimit が互換的に使用されます |
| cacheLimit | number | いいえ | キャッシュ制限サイズ(単位: byte)。Android ではキャッシュ総サイズ、iOS では DB キャッシュ制限に対応します |
| cacheDiscard | enum FTCacheDiscard | いいえ | キャッシュデータの破棄ルールを設定します。Android ではキャッシュ破棄ポリシーを使用し、iOS では DB データ破棄ルールにマッピングされます。FTCacheDiscard.discard は新しいデータを破棄し(デフォルト)、FTCacheDiscard.discardOldest は古いデータを破棄します |
| enableFileDataStore | boolean | いいえ | Android:FileStore ファイルキャッシュを有効にするかどうか |
| needTransformOldCache | boolean | いいえ | Android:FileStore を有効にする際に旧 SQLite キャッシュデータを移行するかどうか |
| fileDataStoreShadow | boolean | いいえ | Android:SQLite 読み取りパス使用時に FileStore へ同期書き込みするかどうか |
| compressIntakeRequests | boolean | いいえ | アップロード同期データを deflate 圧縮します。SDK 0.5.3-pre.2 以降でサポートされ、SDK 0.5.7 以降はデフォルトで有効、それ以前はデフォルトで無効です。false に設定すると無効にできます |
| enableDataIntegerCompatible | boolean | いいえ | Web データと共存する必要がある場合に有効化を推奨します。Web データ型の保存互換性の問題を処理するために使用します。0.5.4-pre.1 以降はデフォルトで有効です |
| dataModifier | Map<String,Object> |
いいえ | 単一フィールドを変更します。使用例はデータ収集マスキングを参照してください |
| lineDataModifier | Map<String,Map<String,Object>> |
いいえ | 単一データを変更します。使用例はデータ収集マスキングを参照してください |
| enableDataFilter | bool | いいえ | SDK 側のブラックリストフィルタリングを有効にするかどうか。デフォルトは true。Log と RUM データのフィルタリングをサポートします。SDK 0.5.7 以降でサポートされます。使用例はブラックリストフィルタリングを参照してください |
| dataFilters | Map<String,List<String>> |
いいえ | アプリ内ブラックリストルールを設定します。logging と rum の 2 種類のデータをサポートします。SDK 0.5.7 以降でサポートされます。ルール構文はルール構文を参照してください |
| enableRemoteConfiguration | bool | いいえ | リモート設定を有効にするかどうか。有効にすると、SDK は自動更新時または明示的な呼び出し時に設定の取得を試み、呼び出し頻度は最小更新間隔によって制限されます。詳細は動的設定を参照してください |
| remoteConfigMiniUpdateInterval | int | いいえ | リモート設定の最小更新間隔(秒)。デフォルトは 12 時間です。enableRemoteConfiguration を有効にする必要があります。詳細は動的設定の能動的同期を参照してください |
| allowWebViewHost | List<String> |
いいえ | WebView データ収集で許可する Host リスト。RUM と Log で共用します。未設定の場合はすべての Host を許可し、空のリストはどの Host も許可しないことを示します。優先順位はリモート設定 > ここの基本設定 > 旧 RUM 設定入口です。SDK 0.5.8 以降でサポートされます。詳細はWebView データモニタリングを参照してください |
| remoteConfigOverrideRules | List<Map<String, Object?>> |
いいえ | リモート設定のローカルオーバーライドルール。サーバーから返されるカスタム環境変数に従って最終設定を調整します |
| iOSGroupIdentifiers | List<String> |
いいえ | iOS App Group 識別子リスト。Extension とメイン App 間でキャッシュデータを共有するために使用します |
送信先アドレスの後からの設定と動的な切り替えについては、送信先アドレスの動的更新を参照してください。
有効化と更新方法についてはリモート設定を参照してください。サポートされるフィールドはFlutter リモート設定フィールドを参照してください。
ブラックリストフィルタリング¶
Flutter SDK 0.5.7 以降では、データがローカルキャッシュに書き込まれる前に RUM と Log データをフィルタリングできます。この機能はデフォルトで有効で、enableDataFilter: false により SDK 側のフィルタリングを無効にできます。
ブラックリストルールは Guance ワークスペースのブラックリストで一括設定でき、SDK が DataKit または DataWay から自動的に取得します。また、FTMobileFlutter.sdkConfig(dataFilters: ...) を使用してアプリ内で設定することもできます。どちらの方法も同じブラックリストフィルタリング機能に対応し、同時に使用できます。いずれかのルールに一致したデータは破棄されます。
ブラックリストフィルタリングは lineDataModifier の後、ローカルキャッシュへの書き込み前に実行されます。lineDataModifier とブラックリストフィルタリングを同時に設定した場合、フィルタリングルールは変更後のデータに基づいて判定されます。
enableDataFilterは SDK 側のルール取得とフィルタリングのみを制御します。falseに設定すると、SDK はdataFiltersを適用せず、ワークスペースルールも取得しません。DataKit を使用して送信する場合、ワークスペースのブラックリストが DataKit 側で引き続き実行される可能性があります。Data Filter は SDK のデータ書き込み経路に作用します。ルールが多すぎる場合や正規表現が複雑すぎる場合は、データ書き込みのパフォーマンスに影響する可能性があるため、必要なルールのみを設定することを推奨します。
await FTMobileFlutter.sdkConfig(
datawayUrl: datawayUrl,
cliToken: cliToken,
enableDataFilter: true,
dataFilters: {
'logging': [
"{ source in [ 'df_rum_ios_log', 'df_rum_android_log' ] and message match [ 'timeout' ] }",
],
'rum': [
"{ resource_status match [ '5..' ] }",
],
},
);
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 にも対応します。
ユーザー情報のバインドとアンバインド¶
使用方法¶
/// ユーザーをバインド
///
/// [userid] ユーザー ID
/// [userName] ユーザー名
/// [userEmail] ユーザーメールアドレス
/// [userExt] 拡張データ
static Future<void> bindRUMUserData(String userId,
{String? userName, String? userEmail, Map<String, String>? ext})
/// ユーザーをアンバインド
static Future<void> unbindRUMUserData()
コード例¶
ext の追加ルールについては競合フィールドの説明を参照してください。
実行時機能¶
データの能動的同期¶
autoSync: falseの場合にのみ、自身でデータ同期を行う必要があります。
シャットダウンと再初期化¶
Core SDK 0.5.8、Session Replay SDK 0.1.1 以降では、ベース SDK をシャットダウンする際に、接続済みの Flutter Session Replay のクリーンアップ完了を待機します。
SDK のシャットダウンは統一して FTMobileFlutter.shutDown() で行います。Session Replay がインストールされていない場合も使用できます。返される Future<void> の完了後に、後続の再初期化操作を実行してください。
シャットダウン後に収集を継続する場合は、FTMobileFlutter.sdkConfig(...) および必要な RUM、Log、Trace 設定を再度呼び出してください。Session Replay を使用する場合は、FTSessionReplayManager().setConfig(...) も再度呼び出し、記録対象のビューが SessionReplayCapture でラップされていることを確認してください。Session Replay API は独立パッケージ ft_session_replay_flutter からインポートします。