SDK 初期化¶
この記事では、Android SDK の初期化に関する内容を説明します。
Application 設定¶
SDK の最適な初期化位置は Application の onCreate メソッド内です。アプリでまだ Application を作成していない場合は、Application を作成し、AndroidManifest.xml で宣言する必要があります。例はこちらをご覧ください。
基本設定¶
public class DemoApplication extends Application {
@Override
public void onCreate() {
// ローカル環境デプロイ、Datakit デプロイ
FTSDKConfig config = FTSDKConfig.builder(datakitUrl);
// パブリック DataWay を使用
FTSDKConfig config = FTSDKConfig.builder(datawayUrl, clientToken);
// ...
// config.setDebug(true); // デバッグモード
FTSdk.install(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 | はい | 認証 token。datawayUrl と同時に設定する必要があります |
| setDebug | Boolean | いいえ | デバッグモードを有効化するかどうか。デフォルトは false です。有効化すると SDK の実行ログを出力できます |
| setEnv | EnvType | いいえ | 収集環境を設定します。デフォルトは EnvType.PROD です |
| setEnv | String | いいえ | 収集環境を設定します。デフォルトは prod です。注意:String または EnvType 型はどちらか一方のみ設定してください |
| setOnlySupportMainProcess | Boolean | いいえ | メインプロセスでのみ実行することをサポートするかどうか。デフォルトは true です。他のプロセスで実行する必要がある場合は、このフィールドを false に設定する必要があります |
| setAllowWebViewHost | Array | いいえ | WebView RUM と Log が Bridge を使用できる host 範囲を一括設定します。null はすべての host を許可することを示し、空の配列は Bridge を自動使用しないことを示します。設定した host はそのサブドメインにも一致します。デフォルトは null です。ft-sdk 1.7.5 以上でサポートされます。詳細はWebView モニタリングをご覧ください |
| setEnableAccessAndroidID | Boolean | いいえ | Android ID の取得を有効化します。デフォルトは true です。false に設定すると、device_uuid フィールドデータは収集されません。アプリマーケットのプライバシー審査関連はこちらをご覧ください |
| addGlobalContext | Dictionary | いいえ | SDK グローバルプロパティを追加します。追加ルールはこちらをご覧ください |
| setServiceName | String | いいえ | サービス名を設定します。Log と RUM の service フィールドデータに影響します。デフォルトは df_rum_android です |
| setAutoSync | Boolean | いいえ | データ収集後にサーバーへ自動同期するかどうか。デフォルトは true です。false の場合は FTSdk.flushSyncData() を使用してデータ同期を自身で管理します |
| setSyncPageSize | Int | いいえ | 同期リクエストの件数を設定します。SyncPageSize.MINI は 5 件、SyncPageSize.MEDIUM は 10 件、SyncPageSize.LARGE は 50 件です。デフォルトは SyncPageSize.MEDIUM です |
| setCustomSyncPageSize | Enum | いいえ | 同期リクエストの件数を設定します。範囲は [5,) です。リクエスト件数が多いほど、データ同期がより多くの計算リソースを消費することに注意してください。デフォルトは 10 です。注意:setSyncPageSize と setCustomSyncPageSize はどちらか一方のみ設定してください |
| setSyncSleepTime | Int | いいえ | 同期間隔を設定します。範囲は [0,5000]、単位は ms、デフォルトは 0 です |
| enableDataIntegerCompatible | Void | いいえ | Web データと共存する必要がある場合に有効化を推奨します。この設定は Web データ型の保存互換性の問題を処理するために使用されます。ft-sdk 1.6.9 バージョンではデフォルトで有効です |
| setNeedTransformOldCache | Boolean | いいえ | ft-sdk 1.6.0 以下バージョンの旧キャッシュデータの同期互換性が必要かどうか。デフォルトは false です |
| enableFileDataStore | Void | いいえ | ファイルキャッシュを有効化し、同期キャッシュと RUM 集約データに使用します。デフォルトでは引き続き SQLite キャッシュを使用します。ft-sdk 1.7.2 以上でサポートされます |
| setUseFileDataStore | Boolean | いいえ | ファイルキャッシュを使用するかどうかを設定します。true を渡すとファイルキャッシュを使用し、false を渡すとデフォルトの SQLite キャッシュを使用します。ft-sdk 1.7.2 以上でサポートされます |
| setFileDataStoreShadow | Boolean | いいえ | ファイルキャッシュのシャドウ書き込みを有効化します。有効化後、読み取りは引き続き SQLite を使用し、同時に書き込みをファイルキャッシュへミラーリングします。移行前の検証に使用します。ft-sdk 1.7.2 以上でサポートされます |
| setCompressIntakeRequests | Boolean | いいえ | アップロードする同期データを deflate 圧縮します。デフォルトで有効です。false に設定すると無効にできます。ft-sdk 1.6.3 以上でこのメソッドをサポートします |
| enableLimitWithCacheSize | Void, Long | いいえ | 総キャッシュサイズ制限を有効化します。デフォルトは 100MB、単位は Byte です。cacheSize を渡す場合の範囲は [30MB,) です。有効化後、FTLoggerConfig.setLogCacheLimitCount および FTRUMConfig.setRumCacheLimitCount は無効になります。ft-sdk 1.7.2 以上でサポートされます |
| setCacheDiscard | CacheDiscard | いいえ | キャッシュがサイズ上限に達した後の破棄ポリシーを設定します。デフォルトは CacheDiscard.DISCARD です。DISCARD は追加データを破棄し、DISCARD_OLDEST は最も古いキャッシュデータを削除します。ft-sdk 1.7.2 以上でサポートされます |
| enableLimitWithDbSize | Void | いいえ | 非推奨です。旧バージョンとの互換性のために保持されています。代わりに enableLimitWithCacheSize の使用を推奨します |
| setEnableOkhttpRequestTag | Boolean | いいえ | 同一リクエストが高同時実行されるシナリオ向けに、OkHttp Request へ一意の ResourceID を自動追加します。ft-sdk 1.6.10 以上、ft-plugin 1.3.5 以上でサポートされます |
| setProxy | java.net.Proxy | いいえ | データのネットワーク同期リクエストに Proxy 設定を行います。okhttp3 のみをサポートします。ft-sdk 1.6.10 以上でサポートされます |
| setProxyAuthenticator | okhttp3.Authenticator | いいえ | データ同期のネットワークリクエストに Proxy 認証設定を行います。okhttp3 のみをサポートします。ft-sdk 1.6.10 以上でサポートされます |
| setDns | okhttp3.Dns | いいえ | データ同期のネットワークリクエストで、カスタム DNS によるドメイン名解決を独自に処理できます。okhttp3 のみをサポートします。ft-sdk 1.6.10 以上でサポートされます |
| setDataModifier | DataModifier | いいえ | 単一フィールドを変更します。ft-sdk 1.6.11 以上でサポートされます。使用例はこちらをご覧ください |
| setLineDataModifier | LineDataModifier | いいえ | 単一データを変更します。ft-sdk 1.6.11 以上でサポートされます。使用例はこちらをご覧ください |
| setEnableDataFilter | Boolean | いいえ | ブラックリストフィルタリングを有効化するかどうか。デフォルトは true です。Logging と RUM データのフィルタリングをサポートします。ft-sdk 1.7.2 以上でサポートされます |
| setDataFilters | HashMap<String, String[]> |
いいえ | アプリ内のブラックリストルールを設定します。logging と rum の 2 種類のデータをサポートします。ルール構文はブラックリストフィルタリングルールをご覧ください。ft-sdk 1.7.2 以上でサポートされます |
| setRemoteConfiguration | Boolean | いいえ | リモート設定を有効化するかどうか。デフォルトは false です。SDK 初期化前に設定する必要があり、有効なレポート先アドレスと RUM App ID を設定する必要があります。RUM の初期化時またはアプリがフォアグラウンドに戻ったときに、最小間隔で更新を試行します。ft-sdk 1.6.12 以上でサポートされ、DataKit >= 1.60 またはパブリック Dataway が必要です。詳細はリモート設定をご覧ください |
| setRemoteConfigMiniUpdateInterval | Int | いいえ | リモート設定の最小更新間隔。単位は秒、デフォルトは 12 時間です。この値はリクエスト頻度を制限するものであり、定時更新の周期ではありません。ft-sdk 1.6.12 以上でサポートされます |
| setRemoteConfigurationCallBack | FTRemoteConfigManager.FetchResult | いいえ | SDK 初期化前にグローバルコールバックを登録し、更新結果を受け取って、設定を適用する前に独自に調整できます。明示的な更新では、今回のコールバックを渡してグローバルコールバックを上書きできます。詳細は初期化と明示的な更新の例をご覧ください。ft-sdk 1.6.16 以上でサポートされます |
ファイルキャッシュ¶
ft-sdk 1.7.2 以上バージョンでは、同期キャッシュと RUM 集約データをファイルキャッシュへ書き込むことをサポートします。旧バージョンからのアップグレードをスムーズにするため、SDK はデフォルトで引き続き SQLite キャッシュを使用します。ファイルキャッシュを有効化する場合は、FTSDKConfig で明示的に有効化できます。
ファイルキャッシュへの書き込み状況を先に検証する場合は、シャドウ書き込みを有効化できます。有効化後、SDK は引き続き SQLite からデータを読み取り、同時に書き込みをファイルキャッシュへミラーリングします。検証が完了したら、enableFileDataStore に切り替えます。
キャッシュサイズ制限¶
ft-sdk 1.7.2 以上バージョンでは、enableLimitWithCacheSize を使用して SDK の総キャッシュサイズ制限を設定することを推奨します。有効化後、個別のログ件数上限 FTLoggerConfig.setLogCacheLimitCount および RUM 件数上限 FTRUMConfig.setRumCacheLimitCount は無効になります。
ブラックリストフィルタリング¶
ft-sdk 1.7.2 以上バージョンでは、データをローカルキャッシュへ書き込む前に Logging、RUM データをフィルタリングできます。この機能はデフォルトで有効で、setEnableDataFilter(false) で無効にできます。
ブラックリストルールは Guance ワークスペースのブラックリストで一括設定でき、SDK が DataKit または Dataway から自動取得します。また、setDataFilters でアプリ内に設定することもできます。2 つの方法は同じブラックリストフィルタリング機能に対応し、同時に使用できます。いずれかのルールに一致すると、そのデータは破棄されます。
setDataFilters は logging、rum の 2 種類のルールをサポートします。各ルールは { 条件 } で表し、データのタグ、フィールド、および source、measurement、class などのデータ型識別フィールドに一致できます。完全な構文はブラックリストフィルタリングルールをご覧ください。
ブラックリストフィルタリングは LineDataModifier の後、ローカルキャッシュへの書き込み前に実行されます。setLineDataModifier とブラックリストフィルタリングを同時に設定した場合、フィルタリングルールは変更後のデータに基づいて判定されます。
HashMap<String, String[]> filters = new HashMap<>();
filters.put("logging", new String[]{
"{ source in ['custom_log'] and message match ['password'] }"
});
filters.put("rum", new String[]{
"{ source in ['resource'] and status in [404, 503] }"
});
FTSDKConfig config = FTSDKConfig.builder(datawayUrl, clientToken)
.setEnableDataFilter(true)
.setDataFilters(filters);
FTSdk.install(config);
val filters = hashMapOf(
"logging" to arrayOf(
"{ source in ['custom_log'] and message match ['password'] }"
),
"rum" to arrayOf(
"{ source in ['resource'] and status in [404, 503] }"
)
)
val config = FTSDKConfig.builder(datawayUrl, clientToken)
.setEnableDataFilter(true)
.setDataFilters(filters)
FTSdk.install(config)
ローカルとリモートのデータフィルタリングを無効化する場合は、明示的に設定します:
ワークスペースのブラックリストルールの取得間隔は、サーバーが返す pull_interval に従います。サーバーが有効な値を返さない場合、SDK はフォールバック間隔として 10 秒を使用します。pull_interval は秒数または単位付きの文字列をサポートします。例:10、30s、2m、1h。
ユーザー情報のバインドとアンバインド¶
FTSdk を使用してユーザーのバインドとアンバインドを行います。
使用方法¶
UserData¶
| メソッド名 | 意味 | 必須 | 注意 |
|---|---|---|---|
| setId | ユーザー ID を設定 | いいえ | |
| setName | ユーザー名を設定 | いいえ | |
| setEmail | メールアドレスを設定 | いいえ | |
| setExts | ユーザー拡張を設定 | いいえ | 追加ルールはアプリ接続をご覧ください |
コード例¶
// ユーザーログイン成功後にこのメソッドを呼び出してユーザー情報をバインドできます
FTSdk.bindRumUserData("001");
UserData userData = new UserData();
userData.setName("test.user");
userData.setId("test.id");
userData.setEmail("test@mail.com");
Map<String, String> extMap = new HashMap<>();
extMap.put("ft_key", "ft_value");
userData.setExts(extMap);
FTSdk.bindRumUserData(userData);
// ユーザーログアウト後にこのメソッドを呼び出してユーザー情報をアンバインドできます
FTSdk.unbindRumUserData();
// ユーザーログイン成功後にこのメソッドを呼び出してユーザー情報をバインドできます
FTSdk.bindRumUserData("001")
// ユーザーの追加データをバインド
val userData = UserData()
userData.name = "test.user"
userData.id = "test.id"
userData.email = "test@mail.com"
val extMap = HashMap<String, String>()
extMap["ft_key"] = "ft_value"
userData.setExts(extMap)
FTSdk.bindRumUserData(userData)
// ユーザーログアウト後にこのメソッドを呼び出してユーザー情報をアンバインドできます
FTSdk.unbindRumUserData()
実行時の機能¶
SDK の停止¶
SDK 設定を動的に変更する場合は、誤ったデータの生成を避けるため、先に SDK を停止する必要があります。
SDK キャッシュデータのクリア¶
FTSdk を使用して未送信のキャッシュデータをクリアします。
データの自動同期設定¶
ft-sdk 1.7.3 以上バージョンでは、SDK 初期化後にキャッシュデータの自動同期を動的に有効化または無効化できます。無効化後も、SDK は収集データをローカルキャッシュに書き込みますが、データ収集後に自動で同期をトリガーしません。FTSdk.flushSyncData() と組み合わせて、データ同期を自身で管理できます。
データの明示的な同期¶
FTSdk を使用してデータを明示的に同期します。
FTSdk.setAutoSync(false)の場合にのみ、自身でデータ同期を行う必要があります。