Flutter アプリの接続¶
各 Flutter アプリのメトリクスデータを収集し、アプリ側のパフォーマンスを可視化して分析します。
参照の流れ¶
- 初めて接続する場合:まず接続方法の選択を参照してください。手動接続の場合はクイックスタートを参照してください
- 一通り接続する場合:本文を引き続きお読みください
- 初期化パラメータ:SDK 初期化、RUM 設定、Log 設定、Trace 設定を参照してください
- カスタマイズ機能:カスタムタグの使用、データ収集のカスタムルール、データ収集のマスキングを参照してください
- 高度なユースケース:WebView データモニタリング、ネイティブと Flutter のハイブリッド開発、Flutter Session Replay、Publish Package 関連設定を参照してください
- Flutter Web プロジェクト:現在の Flutter SDK は Web bridge を提供していません。Web アプリの接続に従って Browser RUM SDK を使用してください
- 問題の切り分け:トラブルシューティングを参照してください
- データモデル:アプリデータ収集を参照してください
前提条件¶
注意:RUM Headless サービスを開通している場合、前提条件は自動的に設定済みです。そのままアプリを接続してください。
ローカル環境にデプロイする場合は、以下のデータ受信側の設定を完了する必要があります。パブリック DataWay を使用する場合は、DataKit を自身でデプロイする必要はありません。
- DataKit をインストールする
- RUM コレクターを設定する
- DataKit をパブリックアクセス可能にし、IP 地理位置情報ライブラリをインストールする
アプリの接続¶
注意
現在の Flutter バージョンは Android と iOS プラットフォームのみをサポートしています。
- RUM > アプリを作成 > Android/iOS に移動します
- Flutter Android と Flutter iOS 用に 2 つのアプリをそれぞれ作成し、Android プラットフォームと iOS プラットフォームからの RUM データを個別に受信できるようにします
- 各プラットフォームのアプリに、対応するアプリ名とアプリ ID を入力します
- 「接続方法の選択」で Agent 自動接続または手動接続を選択し、「接続設定」を完了します。
Flutter Web プロジェクト¶
ft_mobile_agent_flutter は現在 Android / iOS のネイティブブリッジ機能のみを提供しており、Flutter Web bridge は提供していません。
アプリが Flutter Web で動作している場合は、Web タイプの RUM アプリを作成し、Web アプリの接続に従って Browser RUM SDK を使用してください。この方法は Browser RUM SDK による接続であり、本文で後述する Android / iOS ネイティブブリッジ API は使用せず、Dart コードで ft_mobile_agent_flutter を呼び出して Web RUM を初期化する必要もありません。
Flutter Web プロジェクトの接続箇所は通常、プロジェクトルート配下の web/index.html です。Flutter の起動スクリプトより前に Browser RUM SDK または業務側の初期化スクリプトを読み込むことができます。build/web ディレクトリは変更しないでください。このディレクトリは Flutter のビルド成果物であり、flutter build web を実行すると再生成されます。
接続方法の選択¶
アプリ設定ページで「Agent 自動接続」または「手動接続」を選択し、「接続設定」を完了します。既存のアプリは設定ページに直接移動して接続を続行できます。
| 接続方法 | ユースケース | 操作入口 |
|---|---|---|
| Agent 自動接続 | プログラミングアシスタントにプロジェクトを分析させ、SDK の接続を完了させたい場合 | コンソールが生成したプロンプトをコピーし、アプリのコードリポジトリでプログラミングアシスタントに渡して実行します |
| 手動接続 | SDK を自身でインストールしてパラメータを設定したい場合 | データ送信方法を確認し、本文とクイックスタートに従って設定を完了します |
Agent 自動接続¶
- 現在のアプリの設定ページで「Agent 自動接続」を選択します。
- 「接続設定」内のプロンプト全体をコピーします。現在のアプリの接続情報が使用されていることを確認してください。
- アプリのコードリポジトリでプログラミングアシスタントを開き、プロンプトを貼り付けます。Agent が接続ガイドに従ってプロジェクトを分析し、SDK の設定を完了します。
- アプリをビルドして実行し、ページアクセスなどの操作を発生させ、現在のアプリのエクスプローラーでデータが受信されていることを確認します。
クロスプラットフォームフレームワークを使用する場合は、Agent にフレームワークと対象プラットフォームを伝え、各プラットフォームに対応するアプリ情報をそれぞれ提供してください。
ページに個人用 API Key または一時認証コードが未準備である旨が表示された場合は、案内に従って準備を完了してからプロンプトをコピーし直してください。
手動接続¶
アプリ設定ページで「手動接続」を選択し、データ送信方法を確認します。
- パブリック DataWay:DataKit コレクターをインストールせずに RUM データを直接受信します
- ローカル環境へのデプロイ:前提条件を満たしたうえで RUM データを受信します
後述のインストールとクイックスタートに従って、SDK のインストール、初期化、検証を完了してください。既に SDK の設定がある場合は、重複初期化を避けるため、まず内容を確認して再利用してください。
インストール¶
Pub.Dev: ft_mobile_agent_flutter
ソースコード:https://github.com/GuanceCloud/datakit-flutter
Demo アドレス:https://github.com/GuanceCloud/datakit-flutter/example
プロジェクトのパスで次を実行します:
これにより、パッケージの pubspec.yaml に依存関係が追加されます:
dependencies:
ft_mobile_agent_flutter: [latest_version]
# Flutter 2.0 互換バージョンでは以下の参照方法を使用します
ft_mobile_agent_flutter:
git:
url: https://github.com/GuanceCloud/datakit-flutter.git
ref: [github_legacy_lastest_tag]
Dart コードでインポートします:
ft_mobile_agent_flutter0.5.7以降、Session Replay は独立したパッケージft_session_replay_flutterで提供されます。セッションリプレイを有効にする場合は、Flutter Session Replay を引き続きお読みください。
Android 統合の追加設定¶
- App 起動イベント、および Android Native 関連イベント(ページ遷移、クリックイベント、Native ネットワークリクエスト、WebView データ)を収集するために、Gradle Plugin ft-plugin を設定します
- 起動回数と起動時間を計測する場合、Flutter のバージョンに応じて
Applicationをカスタマイズし、onCreate()をオーバーライドしてsuper.onCreate()を呼び出したうえで、AndroidManifest.xmlで宣言する必要があります。 - カスタム
Applicationはft-pluginのインストルメンテーション対象に含める必要があります。プラグインがデフォルトで除外するcom.ft.sdkパッケージおよびそのサブパッケージには配置せず、除外ルールでこのクラスをスキップしないでください。フォアグラウンド/バックグラウンド状態の記録も正しい接続に依存します。
Flutter 3.28.x 以前のバージョンでは旧方式を使用します:
import io.flutter.app.FlutterApplication
/**
* 【起動回数】と【起動時間】を計測する場合は、ここでカスタム Application を追加する必要があります
*/
class CustomApplication : FlutterApplication() {
override fun onCreate() {
super.onCreate()
}
}
Flutter 3.29.0 以降のバージョンでは新しい方式を使用します:
import android.app.Application
/**
* 【起動回数】と【起動時間】を計測する場合は、ここでカスタム Application を追加する必要があります
*/
class CustomApplication : Application() {
override fun onCreate() {
super.onCreate()
}
}
Flutter 3.29.0 以降のバージョンに関する注意
Flutter 3.29.0 では v1 Android embedding が削除され、io.flutter.app.FlutterApplication も含まれなくなりました。そのため、このバージョンからは上記の新しい方式に切り替えてください。Android App の起動イベントを収集するため、ft-plugin はカスタム Application の onCreate() に起動監視コードを挿入する必要があります。android.app.Application(または androidx.multidex.MultiDexApplication)を直接継承してください。継承しない場合、launch_cold などの App 起動イベントが収集できなくなる可能性があります。
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
package="com.example.flutter.agent_example">
<application android:name=".CustomApplication">
//...
</application>
</manifest>
iOS 統合¶
SDK 0.5.8 以降は Swift Package Manager をサポートし、iOS 15.0 以上が必要です。
SDK は CocoaPods と Swift Package Manager の両方の接続方法を提供しています。iOS ネイティブの依存関係は GuanceSDK1.6.9 にアップグレードされ、Flutter プラグインによって宣言・解決されます。プロジェクトが旧 FTMobileSDK に直接依存している場合は、2 つの SDK が同時にリンクされないよう、これらの依存関係を確認して移行する必要があります。
CocoaPods¶
アプリの ios/Podfile のプラットフォームバージョン、および Xcode のアプリと関連 Extension の Deployment Target を 15.0 以上に設定します:
アプリのディレクトリで flutter pub get を実行し、続いて ios ディレクトリで pod install を実行して、プラグインおよびネイティブ SDK の依存関係を更新します。
Swift Package Manager¶
Flutter 3.44 以降のバージョンを使用し、アプリの pubspec.yaml で Swift Package Manager を有効にします:
flutter pub get を実行した後、flutter run または flutter build ios によって Flutter の Swift Package Manager 統合を完了します。Xcode のアプリおよび関連 Extension の Deployment Target が 15.0 以上であることを確認してください。プラグインのネイティブ SDK をアプリの Target に手動で重複追加する必要はありません。
詳細設定の入口¶
高度なユースケース¶
- カスタムタグの使用
- データ収集のカスタムルール
- データ収集のマスキング
- 動的設定と動的更新アドレス
- WebView データモニタリング
- ネイティブと Flutter のハイブリッド開発
- Flutter Session Replay
- Publish Package 関連設定
競合フィールドの説明¶
- 特殊な key:
track_id。追跡機能で使用されます - ユーザーが
globalContextで追加したカスタムタグが SDK 固有のタグと同じ場合、SDK のタグがユーザー設定値を上書きします -
タグ名にはプロジェクトの略称プレフィックスを付けることを推奨します(例:
custom_tag_name) -
プロジェクトで使用される
key値は Android の定数定義を参照してください:Constants.java