HarmonyOS アプリケーションの接続¶
HarmonyOS アプリケーションのメトリクスデータを収集し、アプリケーションのパフォーマンスを可視化して分析します。
閲覧パス¶
- 初回接続時:まず接続方式を選択します。手動接続の場合はクイックスタートを参照できます
- 完全な接続:本文を引き続き参照してください
- 旧パッケージ名からの移行:旧設定からの移行を参照してください
- HAR パッケージのダウンロード:HAR の取得方法を参照してください
- 初期化パラメーター:SDK の初期化、RUM 設定、Log 設定、Trace 設定を参照してください
- 高度な機能:「高度なシナリオ」(#advanced-scenarios)グループ内の専用ページを参照してください
- セッションリプレイ:HarmonyOS セッションリプレイ(実験的)を参照してください
- データモデル:アプリケーションデータ収集を参照してください
- トラブルシューティング:トラブルシューティングを参照してください
前提条件¶
注意
RUM Headless サービスを有効化済みの場合、前提条件は自動的に設定されているため、アプリケーションを直接接続できます。
ローカル環境にデプロイする場合は、以下のデータ受信側の設定を完了する必要があります。パブリック DataWay を使用する場合、DataKit を自身でデプロイする必要はありません。
- DataKit をインストールする
- RUM コレクターを設定する
- DataKit をパブリックネットワークからアクセス可能にし、IP ジオロケーションライブラリをインストールする
アプリケーションの接続¶
- RUM > アプリケーションを作成 > HarmonyOS に移動します
- アプリケーション名とアプリケーション ID を入力します
- 「接続方式を選択」で Agent 自動接続または手動接続を選択し、「接続設定」を完了します。
接続方式を選択¶
アプリケーションの設定ページで「Agent 自動接続」または「手動接続」を選択し、「接続設定」を完了します。既存のアプリケーションは、設定ページから直接接続を続行できます。
| 接続方式 | ユースケース | 操作入口 |
|---|---|---|
| Agent 自動接続 | プログラミングアシスタントにプロジェクトを分析させ、SDK 接続を完了したい場合 | コンソールで生成されたプロンプトをコピーし、アプリケーションのコードリポジトリでプログラミングアシスタントに渡して実行します |
| 手動接続 | SDK を自身でインストールし、パラメーターを設定したい場合 | データ送信方式を確認し、本文とクイックスタートに従って設定を完了します |
Agent 自動接続¶
- 現在のアプリケーションの設定ページで「Agent 自動接続」を選択します。
- 「接続設定」内の完全なプロンプトをコピーし、現在のアプリケーションの接続情報が使用されていることを確認します。
- アプリケーションのコードリポジトリでプログラミングアシスタントを開き、プロンプトを貼り付け、Agent が接続ガイドに従ってプロジェクトを分析し、SDK 設定を完了するようにします。
- アプリケーションをビルドして実行し、ページアクセスなどの操作をトリガーし、現在のアプリケーションのエクスプローラーでデータが受信されていることを確認します。
ページに個人用 API キーまたは一時認証コードが未準備である旨が表示された場合は、案内に従って補完してからプロンプトを再コピーしてください。
手動接続¶
アプリケーションの設定ページで「手動接続」を選択し、データ送信方式を確認します:
- パブリック DataWay:RUM データを直接受信し、DataKit コレクターをインストールする必要はありません
- ローカル環境にデプロイ:前提条件を満たしたうえで RUM データを受信します
以下のインストールとクイックスタートに従って、SDK のインストール、初期化、検証を完了します。既存の SDK 設定がある場合は、事前に確認して再利用し、重複初期化を避けてください。
インストール¶
Hvigor Plugin 設定の導入¶
console.*、hilog.* の自動収集およびコールドスタートの自動収集は @cloudcare/hvigor-ohos-plugin に依存します。このプラグインはビルド時のツールキットであり、アプリケーションモジュールの oh-package.json5 の実行時依存関係には含まれません。
注意:コールドスタートの計測は、最初の UI フレームのレンダリングを終了条件とします。
@cloudcare/hvigor-ohos-plugin0.1.1 はft_sdk0.1.17 以上を要求します。HarmonyOS API 22 以上では実際のファーストフレームを収集します。API 22 未満では、完全なlaunch_coldAction とコールドスタートの合計時間を生成できません。
プロジェクトレベルの hvigor/hvigor-config.json5 にプラグイン依存関係を追加します:
次に、アプリケーションの HAP モジュールの hvigorfile.ts でプラグインを登録します:
import { hapTasks } from '@ohos/hvigor-ohos-plugin';
import { ftConsoleLogPlugin } from '@cloudcare/hvigor-ohos-plugin';
export default {
system: hapTasks,
plugins: [ftConsoleLogPlugin()]
};
プラグインはアプリケーションの src/main/ets 内の呼び出しのみを変換し、ディスク上のソースコードや SDK 依存関係を書き換えることはありません。コンパイル時に生成されるコールドスタートコードは ft_sdk を参照するため、アプリケーションは引き続き ft_sdk の実行時依存関係を保持する必要があります。設定完了後にクリーンビルドを一度実行してください。プラグインをインストールしていない場合、console、hilog、コールドスタートのデータは自動収集されません。
ft_sdk 0.1.18 以上での自動収集は、Hvigor プラグインと組み合わせて使用する必要があります。インストルメンテーションが必要な各ソースモジュール(HAP、HAR、HSP)は、それぞれの oh-package.json5 の dependencies で ft_sdk を宣言する必要があります。Replay の自動収集には ft_session_replay の宣言も必要です。プロジェクトルート、他のモジュール、または devDependencies でのみ宣言しても、そのモジュールの自動収集は有効になりません。詳細はセッションリプレイの接続を参照してください。
コールドスタートでは、エントリでできるだけ早く RUM をインストールし、setEnableTraceUserAction(true) を有効にする必要があります。完全なアプリケーション初期化フェーズを取得するには、HAP の module.json5 で AbilityStage を srcEntry として設定することを推奨します。設定しない場合、新しいプラグインでは近似したフェーズ時間のみ提供できます。
注意:コールバック付きの
windowStage.loadContent('pages/Index', (err) => { ... })記法を使用することを推奨します。プラグインはonWindowStageCreate()の先頭でファーストフレームのリスナー登録を試み、ページ読み込み成功時のコールバックでも追加で登録を試みます。コールバックなしの場合、onWindowStageCreate()の先頭でのみ 1 回登録を試みます。
0.1.18 では、各プロセスで最大 1 回 launch_cold をレポートし、同一プロセスの最初の UI フレームがレンダリングされるのを待ってからレポートします。所要時間はプロセス起動からファーストフレームまでを計算し、ファーストフレーム前のバックグラウンド待機時間を含みます。フォアグラウンド/バックグラウンドの切り替えによって、記録済みのフェーズ境界はリセットされません。UI のファーストフレームが一度もないプロセスでは、コールドスタート Action は生成されません。起動 Action は引き続き Session サンプリングと Action フィルタリングの制御を受けます。
SDK の導入¶
プロジェクトの接続方式に応じて、以下のいずれかのインストール方法を選択できます。
方法 1:ohpm 経由でインストール¶
サードパーティリポジトリの設定が完了している場合は、ohpm 経由で直接インストールできます:
ohpm install @guancecloud/ft_sdk
ohpm install @guancecloud/ft_sdk_ext #オプション
ohpm install @guancecloud/ft_native #オプション
ohpm install @guancecloud/ft_session_replay #オプション、セッションリプレイ(実験的)
方法 2:ローカル HAR 経由でインストール¶
HarmonyOS 公式ドキュメント(HAR パッケージのインポートガイド)に従い、まず HAR の取得方法 を参照してインストールパッケージを準備し、HAR ファイルをプロジェクトの libs ディレクトリに配置して、oh-package.json5 に必要に応じてスコープ付き依存関係を追加してください。
{
"dependencies": {
"@guancecloud/ft_sdk": "file:../libs/ft_sdk.har",
"@guancecloud/ft_sdk_ext": "file:../libs/ft_sdk_ext.har", //オプション
"@guancecloud/ft_native": "file:../libs/ft_native.har", //オプション
"@guancecloud/ft_session_replay": "file:../libs/ft_session_replay.har" //オプション、セッションリプレイ(実験的)
}
}
HAR パッケージ依存関係を使用する場合は、プロジェクトルートの oh-package.json5 に overrides も追加し、モジュール内部のリモート依存関係をローカル HAR に書き換えて、ft_sdk_ext が引き続きリモートリポジトリから @guancecloud/ft_sdk を解決しないようにすることを推奨します:
次に、以下を実行します:
インストール完了後、HAR パッケージはプロジェクトの oh_modules/ ディレクトリにインストールされます。スコープ付き依存関係を使用する場合、ディレクトリは通常 oh_modules/@guancecloud/ft_sdk、oh_modules/@guancecloud/ft_sdk_ext、oh_modules/@guancecloud/ft_native、oh_modules/@guancecloud/ft_session_replay のようになります。
バイトコード HAR ビルド設定¶
ft_sdk 0.1.15、ft_sdk_ext 0.1.15、ft_native 0.1.1 のリリースパッケージはバイトコード HAR を使用します。これらのパッケージのいずれかを接続する場合は、以下を確認してください:
- プロジェクトは HarmonyOS API 12 以上を使用する必要があります。
ft_sdk_extのHttpInterceptorChain機能は HarmonyOS API 22 以上を要求します。 - プロジェクトルートの
build-profile.json5で、実際にビルドするプロダクトに対して正規化 OHMUrl を有効にします。同名の設定が既に存在する場合は、strictModeの内容をマージするだけで済みます:
{
"app": {
"products": [
{
"name": "default",
"buildOption": {
"strictMode": {
"useNormalizedOHMUrl": true
}
}
}
]
}
}
oh-package.json5の依存関係名は SDK パッケージ名と一致させる必要があります。コードは各パッケージが公開するIndexエントリからのみ API をインポートし、src/main/...などの内部パスを使用しないでください。- Release パッケージでは ArkGuard 難読化が有効になっており、HAR とともに配布されるコンシューマー難読化ルールによって公開 API が保持されます。SDK パッケージ内の
consumer-rules.txtを削除または置換しないでください。アプリケーション自体で難読化を有効にしている場合でも、SDK の公開機能を通常どおり呼び出せます。
HAR の取得方法¶
新しい HAR の取得方法¶
- まず対応する ohpm ページにアクセスします
- 次に、対象バージョンの
dist.tarballを見つけます dist.tarballから対応する HAR パッケージをダウンロードして展開します
対応 URL:
@guancecloud/ft_sdk:https://repo.harmonyos.com/ohpm/@guancecloud/ft_sdk@guancecloud/ft_sdk_ext:https://repo.harmonyos.com/ohpm/@guancecloud/ft_sdk_ext@guancecloud/ft_native:https://repo.harmonyos.com/ohpm/@guancecloud/ft_native
注意:
- 新しい方法でダウンロードする場合は、プロジェクトの接続バージョンと一致する
dist.tarballを選択してください ft_sdk_extとft_sdkは同じバージョンに保つことを推奨します- ダウンロードした HAR ファイルは、引き続きプロジェクトの
libs/ディレクトリに配置し、ローカル HAR 方式で接続できます
旧 HAR のダウンロード方法¶
- 旧版
ft_sdk.harファイルをダウンロード:ダウンロード URL - 必要に応じて
ft_sdk_ext.harファイルをダウンロード:ダウンロード URL - 必要に応じて
ft_native.harファイルをダウンロード:ダウンロード URL
パッケージの説明¶
実際の機能に応じて、必要なパッケージを導入してください:
ft_sdk.harはコアパッケージであり、必須です。サードパーティリポジトリ経由でインストールする場合、対応するパッケージ名は@guancecloud/ft_sdkですft_sdk_ext.harは拡張パッケージです。@kit.NetworkKitに基づくHttpInterceptorChain自動収集機能が必要な場合にインストールします。この機能は HarmonyOS API 22 以上を要求します。サードパーティリポジトリ経由でインストールする場合、対応するパッケージ名は@guancecloud/ft_sdk_extですft_native.harはオプションのパッケージであり、Native Crash などのネイティブ機能が必要な場合にのみインストールします。サードパーティリポジトリ経由でインストールする場合、対応するパッケージ名は@guancecloud/ft_nativeですft_session_replay.harはオプションのセッションリプレイパッケージであり、コア SDK に依存します。バージョン要件、インストール、初期化については HarmonyOS セッションリプレイ(実験的) を参照してください- 実際に使用する HAR ファイルのみを
libs/ディレクトリに配置してください。ディレクトリが存在しない場合は先に作成し、HAR ファイルが現在プロジェクトルートにある場合は先にlibs/ディレクトリへ移動してください
インポート方法¶
以下の方法でインポートできます:
HttpInterceptorChain に基づく HTTP 自動収集機能を使用する場合は、@guancecloud/ft_sdk_ext からインポートしてください:
説明:
@guancecloud/ft_sdk:デフォルト接続および Axios 互換モードのインポートエントリ@guancecloud/ft_sdk_ext:HttpInterceptorChain自動収集のインポートエントリ(HarmonyOS API 22 以上を要求)applyFTAxiosTrackなどの Axios 互換パスは、引き続き@guancecloud/ft_sdkからエクスポートされます
権限の説明¶
SDK には以下の権限宣言が自動的に含まれているため、手動で追加設定する必要はありません:
| 権限名 | 用途 |
|---|---|
ohos.permission.INTERNET |
ネットワークアクセス権限。データ送信とネットワークリクエストの追跡に使用します |
ohos.permission.GET_WIFI_INFO |
WiFi 情報を取得します。ネットワーク種別の検出と信号強度の収集に使用します |
ohos.permission.GET_NETWORK_INFO |
ネットワーク情報を取得します。ネットワーク状態の監視と種別識別に使用します |
詳細設定の入口¶
高度なシナリオ¶
- カスタムタグとグローバルコンテキスト
- データ収集のカスタムルール
- データ収集のマスキング
- 動的設定と動的更新アドレス
- WebView データモニタリング
- HarmonyOS セッションリプレイ(実験的)
旧設定からの移行¶
この記事では、HarmonyOS SDK を旧バージョンのパッケージ名およびディープパスインポートから、現在のスコープ付きパッケージ名と公開 Index エントリに移行する方法を説明します。対象は以下の 3 種類のプロジェクトです:
- ローカル HAR 方式で接続済みで、
ft_sdk.har、ft_sdk_ext.har、ft_native.harを使用したことがある ohpm経由でインストール済みだが、旧バージョンのスコープなしパッケージ名設定またはディープパスインポートを引き続き使用している@guancecloud/スコープ付きパッケージ名に移行済みだが、コードが引き続き@guancecloud/ft_sdk/src/main/...または@guancecloud/ft_sdk_ext/src/main/...のディープパスからインポートしている
移行内容の概要¶
ft_sdk->@guancecloud/ft_sdkft_sdk_ext->@guancecloud/ft_sdk_extft_native->@guancecloud/ft_native@guancecloud/ft_sdk/src/main/...->@guancecloud/ft_sdk/Index@guancecloud/ft_sdk_ext/src/main/...->@guancecloud/ft_sdk_ext/Index
注意:
- HAR ファイル名自体は、引き続き
ft_sdk.har、ft_sdk_ext.har、ft_native.harを使用できます - 調整が必要なのは
oh-package.json5の依存関係名とコード内のインポートパスです。SDK が公開するIndexエントリに統一することを推奨します - ローカル HAR インストールでも
ohpm経由のインストールでも、依存関係名はスコープ付きパッケージ名に統一して移行し、コードのインポートは公開Indexエントリに統一して移行する必要があります @guancecloud/.../src/main/...は以前のバージョンのスコープ付きディープパス記法であり、移行の参考として引き続き使用できますが、最新の推奨接続方式ではありません- ローカル HAR パッケージを再取得する必要がある場合は、HAR の取得方法 を参照してください
設定ファイルの変更¶
旧記法:
//root/entry/oh-package.json5
{
"dependencies": {
"ft_sdk": "file:../libs/ft_sdk.har",
"ft_sdk_ext": "file:../libs/ft_sdk_ext.har",
"ft_native": "file:../libs/ft_native.har"
}
}
以前のスコープ付きディープパス記法:
//root/entry/oh-package.json5
{
"dependencies": {
"@guancecloud/ft_sdk": "file:../libs/ft_sdk.har",
"@guancecloud/ft_sdk_ext": "file:../libs/ft_sdk_ext.har",
"@guancecloud/ft_native": "file:../libs/ft_native.har"
}
}
//root/oh-package.json5
{
"overrides": {
"@guancecloud/ft_sdk": "file:./libs/ft_sdk.har"
}
}
ohpm 経由でインストールする場合も、依存関係名をスコープ付きパッケージ名に変更する必要があります。例:
ohpm install @guancecloud/ft_sdk
ohpm install @guancecloud/ft_sdk_ext
ohpm install @guancecloud/ft_native
比較説明:
- 新しい記法では、依存関係名を旧来の
ft_sdk、ft_sdk_ext、ft_nativeからスコープ付きパッケージ名に変更しています ohpm経由でインストールする場合も、新しいスコープ付きパッケージ名を使用してインストールコマンドを実行する必要がありますoverridesはプロジェクトルートのoh-package.json5に設定する必要があります- プロジェクトがローカル HAR 方式で
ft_sdk_ext.harを接続する場合、overrides["@guancecloud/ft_sdk"]はその内部のリモート依存関係をローカルのft_sdk.harに書き換えるために使用します ft_sdk.harまたはft_native.harのみを使用する場合は、実際の必要に応じて対応するdependenciesを保持できます
コードインポートの変更¶
旧記法:
import { FTSDK } from 'ft_sdk/src/main/ets/components/FTSDK';
import { FTSDKConfig } from 'ft_sdk/src/main/ets/components/Configs';
import { createFTHttpInterceptorChain } from 'ft_sdk_ext/src/main/ets/components/network/FTHttpAutoTrackExt';
新しい記法:
import { FTSDK } from '@guancecloud/ft_sdk/src/main/ets/components/FTSDK';
import { FTSDKConfig } from '@guancecloud/ft_sdk/src/main/ets/components/Configs';
import { createFTHttpInterceptorChain } from '@guancecloud/ft_sdk_ext/src/main/ets/components/network/FTHttpAutoTrackExt';
新しい記法:
import { FTSDK, FTSDKConfig } from '@guancecloud/ft_sdk/Index';
import { createFTHttpInterceptorChain } from '@guancecloud/ft_sdk_ext/Index';
移行手順¶
- HAR ファイルをプロジェクトの
libs/ディレクトリに配置します - プロジェクト内の依存関係名を旧パッケージ名から新しいスコープ付きパッケージ名に変更します
- プロジェクトがローカル HAR 方式で
ft_sdk_ext.harを使用する場合は、プロジェクトルートのoh-package.json5にoverridesを追加します - プロジェクトが
ohpm経由でインストールする場合は、新しいスコープ付きパッケージ名に切り替えてインストールコマンドを再実行します。プロジェクトがローカル HAR でインストールする場合は、ohpm installを実行します - コード内の旧インポートパス、または以前の
@guancecloud/.../src/main/...スコープ付きディープパスを、公開Indexエントリに置き換えます
よくある質問¶
グローバル変数を追加するときに競合フィールドを回避する方法¶
カスタムフィールドと SDK データの競合を避けるため、タグ名には df_tag_name のようなビジネスプレフィックスを付けることを推奨します。SDK グローバル変数と RUM、Log に同名のフィールドが存在する場合、RUM、Log のフィールドが SDK グローバル変数を上書きします。
カスタムタグの使用方法については、引き続き カスタムタグとグローバルコンテキスト を参照してください。