Android アプリの導入¶
Android アプリの指標データを収集し、アプリのパフォーマンスを可視化して分析します。
読む順序¶
- 初回導入:先に導入方法を選択を確認します。手動導入の場合はクイックスタートを参照できます。
- 完全な導入:本記事を引き続き読みます。
- パラメータの詳細:SDK の初期化、RUM 設定、Log 設定、Trace 設定を参照してください。
- 高度な機能:「高度なシナリオ」グループ内の専用ページを参照してください。
- 問題のトラブルシューティング:トラブルシューティングを参照してください。
前提条件¶
注意
RUM Headless サービスを有効化済みの場合、前提条件は自動設定されているため、そのままアプリを導入できます。
ローカル環境にデプロイする場合は、以下のデータ受信側の設定を完了する必要があります。パブリック DataWay を使用する場合、DataKit を自身でデプロイする必要はありません。
- DataKitをインストールする;
- RUM コレクターを設定する;
- DataKit をパブリックにアクセス可能にし、IP 地理情報ライブラリをインストールする。
アプリの導入¶
- RUM > アプリを作成 > Android に進みます;
- アプリ名を入力します;
- アプリ ID を入力します;
- 「導入方法を選択」で Agent 自動導入または手動導入を選択し、「導入設定」を完了します。
導入方法を選択¶
アプリ設定ページで「Agent 自動導入」または「手動導入」を選択し、「導入設定」を完了します。既存のアプリは、設定ページに直接進んで導入を続行できます。
| 導入方法 | ユースケース | 操作の入り口 |
|---|---|---|
| Agent 自動導入 | コーディングアシスタントにプロジェクトを分析させ、SDK の導入を完了したい場合 | コンソールで生成されたプロンプトをコピーし、アプリのコードリポジトリでコーディングアシスタントに実行を依頼します |
| 手動導入 | SDK を自身でインストールしてパラメータを設定したい場合 | データ送信方法を確認し、本記事とクイックスタートに従って設定を完了します |
Agent 自動導入¶
- 現在のアプリの設定ページで「Agent 自動導入」を選択します。
- 「導入設定」内の完全なプロンプトをコピーし、現在のアプリの導入情報が使用されていることを確認します。
- アプリのコードリポジトリでコーディングアシスタントを開き、プロンプトを貼り付けます。Agent が導入ガイドに従ってプロジェクトを分析し、SDK 設定を完了します。
- アプリをビルドして実行し、ページアクセスなどの操作をトリガーした後、現在のアプリのエクスプローラーでデータが受信されたことを確認します。
ページに個人 API Key または一時認証コードが準備できていない旨が表示された場合は、指示に従って補完してからプロンプトを再コピーしてください。
手動導入¶
アプリ設定ページで「手動導入」を選択し、データ送信方法を確認します:
- パブリック DataWay:RUM データを直接受信します。DataKit コレクターをインストールする必要はありません。
- ローカル環境デプロイ:前提条件を満たしたうえで RUM データを受信します。
以下のインストールとクイックスタートに従って、SDK のインストール、初期化、検証を完了してください。既存の SDK 設定がある場合は、まず確認して再利用し、重複初期化を避けてください。
インストール¶
ソースコード URL:https://github.com/GuanceCloud/datakit-android
Demo:https://github.com/GuanceDemo/guance-app-demo
Gradle 設定¶
Plugin を導入¶
- プロジェクトのルートディレクトリにある
build.gradleファイルにSDKのリモートリポジトリ URL を追加します
//build.gradle
buildscript {
//...
repositories {
//...
//Plugin のリモートリポジトリ URL を追加
maven {
url 'https://mvnrepo.guance.com/repository/maven-releases'
}
}
dependencies {
//...
//Plugin のプラグインを追加。AGP 7.4.2 以上、Gradle 7.2.0 以上が必要
classpath 'com.cloudcare.ft.mobile.sdk.tracker.plugin:ft-plugin:[latest_version]'
// AGP 7.4.2 未満の場合は ft-plugin-legacy を使用してください
//classpath 'com.cloudcare.ft.mobile.sdk.tracker.plugin:ft-plugin-legacy:[latest_version]'
}
}
//setting.gradle
pluginManagement {
repositories {
google()
mavenCentral()
gradlePluginPortal()
//Plugin のリモートリポジトリ URL を追加
maven {
url('https://mvnrepo.guance.com/repository/maven-releases')
}
}
}
//build.gradle
plugins{
//Plugin のプラグインを追加。AGP 7.4.2 以上、Gradle 7.2.0 以上が必要
id 'com.cloudcare.ft.mobile.sdk.tracker.plugin' version '[latest_version]' apply false
// AGP 7.4.2 未満の場合は ft-plugin-legacy を使用してください
//id 'com.cloudcare.ft.mobile.sdk.tracker.plugin.legacy' version '[latest_version]' apply false
}
- プロジェクトのメインモジュール
app/build.gradleファイルにPluginの使用を追加します
//app/build.gradle でプラグインを適用します。設定が不足すると、以下の自動収集機能に影響します。
//
// 1.RUM:アプリ起動、OkHttp リクエスト、必要に応じて有効化する HTTP/HTTPS URLConnection リクエスト、WebView の Activity/Fragment 遷移、クリックイベント
// 2.Log:Console Logcat
apply plugin: 'ft-plugin' //ft-plugin-legacy を使用する場合も、この設定を使用します
//オプション:必要に応じてプラグインのパラメータを設定
FTExt {
//showLog = true
//asmVersion='asm7'
//ignorePackages=['com.ft','com/ft']
//knownWebViewClasses = ['com.your.CustomWebView']
}
プラグインのパラメータはすべてオプションです。ほとんどの場合、apply plugin: 'ft-plugin' のみで十分です。プラグインの動作をデバッグする場合、計装範囲を制御する場合、または WebView の認識を手動で補足する場合にのみ、FTExt 設定を追加します。
| パラメータ名 | 型 | デフォルト値 | 説明 | ユースケース |
|---|---|---|---|---|
| showLog | Boolean | false |
ft-plugin のビルドログを出力するかどうか。 |
プラグインの実行過程をデバッグし、計装が有効かどうかを調査するときに有効にします。 |
| asmVersion | String | asm9 |
プラグインが使用する ASM バージョンを指定します。asm7 ~ asm9 を選択できます。 |
プロジェクト内の他のバイトコード処理プラグインとの互換性要件がある場合に調整します。 |
| ignorePackages | String[] | 空 | ASM 計装を行わないパッケージパスを設定します。パス区切りには . または / を使用できます。 |
特定のビジネスパッケージ、サードパーティパッケージ、または他のプラグインと競合するコードをスキップする場合に使用します。 |
| instrumentHttpURLConnection | Boolean | true |
URL.openConnection() / openConnection(Proxy) の戻り値に計装するかどうか。ft-plugin >= 1.3.9-alpha01 でサポートされ、ft-sdk >= 1.7.6-alpha03 が必要です。 |
URLConnection の計装を無効にする場合は false に設定します。実際の収集には 2 つの RUM スイッチも有効にする必要があります。詳細は URLConnection の自動収集を参照してください。 |
| knownWebViewClasses | String[] | 空 | WebView として認識するカスタムクラスを手動で宣言します。 | カスタム WebView の継承階層が複雑で、自動認識が有効にならない場合に使用します。 |
knownWebViewClassesは自動認識に失敗した場合にのみ設定が必要です。関連する調査方法はカスタム WebView の自動収集が有効にならない場合を参照してください。
SDK を導入¶
- プロジェクトのルートディレクトリにある
build.gradleファイルにSDKのリモートリポジトリ URL を追加します
- プロジェクトのメインモジュール
app/build.gradleファイルにSDKの依存関係を追加します
//app/build.gradle
dependencies {
//SDK の依存関係を追加
implementation 'com.cloudcare.ft.mobile.sdk.tracker.agent:ft-sdk:[latest_version]'
//native 層のクラッシュ情報をキャプチャするための依存関係。ft-sdk と組み合わせて使用する必要があり、単独では使用できません
implementation 'com.cloudcare.ft.mobile.sdk.tracker.agent:ft-native:[latest_version]'
// json シリアライズ
implementation 'com.google.code.gson:gson:2.8.+'
//オプション。OkHttp のネットワークリクエスト自動収集と自動分散型トレーシングを使用する場合に追加します。3.12.+ 以上のバージョンと互換性があります
implementation 'com.squareup.okhttp3:okhttp:4.+'
}
最新バージョンは、上記の
ft-sdk、ft-plugin、ft-nativeのバージョン名を参照してください。
Application 設定¶
SDK を初期化する最適な場所は Application の onCreate メソッド内です。アプリにまだ Application が作成されていない場合は作成し、AndroidManifest.xml で宣言する必要があります。サンプルはこちらを参照してください。
R8 / Proguard 難読化設定¶
ft-sdk 1.6.15 より前のバージョンを使用しており、android.buildTypes で minifyEnabled = true を設定する必要がある場合は、次の設定を有効にする必要があります:
-dontwarn com.ft.sdk.**
### ft-sdk ライブラリ
-keep class com.ft.sdk.**{*;}
### ft-native ライブラリ
-keep class ftnative.*{*;}
### Action を取得する際に action_name 内のクラス名が難読化されるのを防ぐ###
-keepnames class * extends android.view.View
-keepnames class * extends android.view.MenuItem
初期化について¶
最小構成の初期化例はクイックスタートを参照してください。
FTSDKConfig の完全なパラメータ説明はSDK の初期化を参照してください。
詳細設定への入口¶
高度なシナリオ¶
- カスタムタグ
- カスタム収集ルール
- データ収集のマスキング
- WebView モニタリング
- 訪問者識別子 Visitor ID
- 動的設定と動的更新アドレス
- シンボルファイルのアップロード
- プライバシーと権限の説明
- Content Provider 設定
- 手動互換導入
Plugin AOP の無視¶
Plugin AOP でメソッドをオーバーライドする際に @IgnoreAOP を追加すると、ASM の挿入を無視できます。一括で無視する必要がある場合は、ft-plugin の FTExt にある ignorePackages を使用して無視してください。
よくある質問¶
グローバル変数を追加して競合フィールドを回避する¶
カスタムフィールドと SDK データの競合を避けるため、タグ名に プロジェクトの略称 のプレフィックスを付けることを推奨します。たとえば custom_tag_name のようにします。プロジェクトで使用されている key の値はソースコードで確認できます。SDK のグローバル変数に RUM、Log と同じ変数が存在する場合、RUM、Log が SDK のグローバル変数を上書きします。
SDK の互換性¶
アプリマーケットのプライバシー審査への対応¶
詳細はプライバシーと権限の説明を参照してください。
サードパーティフレームワーク¶
flutter、react-native、uni-app、unity では、上記のネイティブ Android と同様の遅延初期化方式を採用し、アプリマーケットのプライバシー審査に対応できます。
Jetpack Compose のサポート¶
現在、compose コンポーネントで生成されたページの自動収集はサポートしていませんが、手動の Action および View のカスタムインターフェースを通じて、クリックイベントとページ遷移イベントを追跡できます。詳細はこちらを参照してください。