コンテンツにスキップ

HarmonyOS アプリケーションの接続


HarmonyOS アプリケーションのメトリクスデータを収集し、アプリケーションのパフォーマンスを可視化して分析します。

閲覧パス

前提条件

注意

RUM Headless サービスを有効化済みの場合、前提条件は自動的に設定されているため、アプリケーションを直接接続できます。

ローカル環境にデプロイする場合は、以下のデータ受信側の設定を完了する必要があります。パブリック DataWay を使用する場合、DataKit を自身でデプロイする必要はありません。

アプリケーションの接続

  1. RUM > アプリケーションを作成 > HarmonyOS に移動します
  2. アプリケーション名とアプリケーション ID を入力します
  3. 「接続方式を選択」で Agent 自動接続または手動接続を選択し、「接続設定」を完了します。

接続方式を選択

アプリケーションの設定ページで「Agent 自動接続」または「手動接続」を選択し、「接続設定」を完了します。既存のアプリケーションは、設定ページから直接接続を続行できます。

接続方式 ユースケース 操作入口
Agent 自動接続 プログラミングアシスタントにプロジェクトを分析させ、SDK 接続を完了したい場合 コンソールで生成されたプロンプトをコピーし、アプリケーションのコードリポジトリでプログラミングアシスタントに渡して実行します
手動接続 SDK を自身でインストールし、パラメーターを設定したい場合 データ送信方式を確認し、本文とクイックスタートに従って設定を完了します

Agent 自動接続

  1. 現在のアプリケーションの設定ページで「Agent 自動接続」を選択します。
  2. 「接続設定」内の完全なプロンプトをコピーし、現在のアプリケーションの接続情報が使用されていることを確認します。
  3. アプリケーションのコードリポジトリでプログラミングアシスタントを開き、プロンプトを貼り付け、Agent が接続ガイドに従ってプロジェクトを分析し、SDK 設定を完了するようにします。
  4. アプリケーションをビルドして実行し、ページアクセスなどの操作をトリガーし、現在のアプリケーションのエクスプローラーでデータが受信されていることを確認します。

ページに個人用 API キーまたは一時認証コードが未準備である旨が表示された場合は、案内に従って補完してからプロンプトを再コピーしてください。

手動接続

アプリケーションの設定ページで「手動接続」を選択し、データ送信方式を確認します:

  • パブリック DataWay:RUM データを直接受信し、DataKit コレクターをインストールする必要はありません
  • ローカル環境にデプロイ:前提条件を満たしたうえで RUM データを受信します

以下のインストールとクイックスタートに従って、SDK のインストール、初期化、検証を完了します。既存の SDK 設定がある場合は、事前に確認して再利用し、重複初期化を避けてください。

インストール

Hvigor Plugin 設定の導入

console.*、hilog.* の自動収集およびコールドスタートの自動収集は @cloudcare/hvigor-ohos-plugin に依存します。このプラグインはビルド時のツールキットであり、アプリケーションモジュールの oh-package.json5 の実行時依存関係には含まれません。

注意:コールドスタートの計測は、最初の UI フレームのレンダリングを終了条件とします。@cloudcare/hvigor-ohos-plugin 0.1.1 は ft_sdk 0.1.17 以上を要求します。HarmonyOS API 22 以上では実際のファーストフレームを収集します。API 22 未満では、完全な launch_cold Action とコールドスタートの合計時間を生成できません。

プロジェクトレベルの hvigor/hvigor-config.json5 にプラグイン依存関係を追加します:

{
  "dependencies": {
    "@cloudcare/hvigor-ohos-plugin": "latest"
  }
}

次に、アプリケーションの 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 を解決しないようにすることを推奨します:

//root/oh-package.json5
{
  "overrides": {
    "@guancecloud/ft_sdk": "file:./libs/ft_sdk.har"
  }
}

次に、以下を実行します:

ohpm install

インストール完了後、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:

注意:

  • 新しい方法でダウンロードする場合は、プロジェクトの接続バージョンと一致する dist.tarball を選択してください
  • ft_sdk_ext と ft_sdk は同じバージョンに保つことを推奨します
  • ダウンロードした HAR ファイルは、引き続きプロジェクトの libs/ ディレクトリに配置し、ローカル HAR 方式で接続できます

旧 HAR のダウンロード方法

パッケージの説明

実際の機能に応じて、必要なパッケージを導入してください:

  • 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/ ディレクトリへ移動してください

インポート方法

以下の方法でインポートできます:

import { FTSDK, FTSDKConfig, FTRUMConfig, FTLoggerConfig } from '@guancecloud/ft_sdk/Index';

HttpInterceptorChain に基づく HTTP 自動収集機能を使用する場合は、@guancecloud/ft_sdk_ext からインポートしてください:

import {
  applyFTHttpTrack,
  createFTHttpInterceptorChain
} from '@guancecloud/ft_sdk_ext/Index';

説明:

  • @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 ネットワーク情報を取得します。ネットワーク状態の監視と種別識別に使用します

詳細設定の入口

高度なシナリオ

旧設定からの移行

この記事では、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_sdk
  • ft_sdk_ext -> @guancecloud/ft_sdk_ext
  • ft_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';

移行手順

  1. HAR ファイルをプロジェクトの libs/ ディレクトリに配置します
  2. プロジェクト内の依存関係名を旧パッケージ名から新しいスコープ付きパッケージ名に変更します
  3. プロジェクトがローカル HAR 方式で ft_sdk_ext.har を使用する場合は、プロジェクトルートの oh-package.json5 に overrides を追加します
  4. プロジェクトが ohpm 経由でインストールする場合は、新しいスコープ付きパッケージ名に切り替えてインストールコマンドを再実行します。プロジェクトがローカル HAR でインストールする場合は、ohpm install を実行します
  5. コード内の旧インポートパス、または以前の @guancecloud/.../src/main/... スコープ付きディープパスを、公開 Index エントリに置き換えます

よくある質問

グローバル変数を追加するときに競合フィールドを回避する方法

カスタムフィールドと SDK データの競合を避けるため、タグ名には df_tag_name のようなビジネスプレフィックスを付けることを推奨します。SDK グローバル変数と RUM、Log に同名のフィールドが存在する場合、RUM、Log のフィールドが SDK グローバル変数を上書きします。

カスタムタグの使用方法については、引き続き カスタムタグとグローバルコンテキスト を参照してください。

フィードバック

このページは役に立ちましたか?