HarmonyOS アプリの導入¶

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

読み進め方¶

初回導入：まずクイックスタートを参照
完全な導入：この記事を引き続き参照
旧パッケージ名からの移行：旧設定の移行を参照
HAR パッケージのダウンロード：HAR の取得方法を参照
初期化パラメータ：SDK の初期化、RUM 設定、Log 設定、Trace 設定を参照
高度な機能：「高度なシナリオ」グループ配下の専用ページを参照
データモデル：アプリデータ収集を参照
トラブルシューティング：トラブルシューティングを参照

前提条件¶

注意

すでに RUM Headless サービスを有効にしている場合は、前提条件が自動的に設定されているため、アプリをそのまま導入できます。

DataKit をインストールします
RUM コレクターを設定します
DataKit をパブリックネットワークからアクセス可能にし、IP 地理位置情報データベースをインストールします

アプリの導入¶

RUM > アプリを新規作成 > HarmonyOS を選択します
アプリ名とアプリ ID を入力します
アプリの導入方法を選択します：
パブリックネットワーク DataWay：DataKit コレクターのインストールなしで RUM データを直接受信します
ローカル環境へのデプロイ：前提条件を満たしたうえで RUM データを受信します

インストール¶

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": "^0.1.1"
  }
}

次に、アプリの 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、コールドスタートデータは自動収集されません。

SDK の導入¶

プロジェクトの導入方法に応じて、以下のいずれかのインストール方法を選択できます。

方法 1：ohpm によるインストール¶

サードパーティのリポジトリの設定が完了している場合は、ohpm を使用して直接インストールできます：

ohpm install @guancecloud/ft_sdk

ohpm install @guancecloud/ft_sdk_ext # オプション
ohpm install @guancecloud/ft_native  # オプション

方法 2：ローカル HAR によるインストール¶

HarmonyOS 公式ドキュメント（HAR パッケージのインポートガイド）に従い、先に HAR の取得方法を参照してインストールパッケージを準備してください。HAR ファイルをプロジェクトの libs ディレクトリに配置し、oh-package.json5 に必要に応じて scoped 依存関係を追加します。

{
  "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"    // オプション
  }
}

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/ ディレクトリにインストールされます。scoped 依存関係を使用する場合、ディレクトリは通常、oh_modules/@guancecloud/ft_sdk、oh_modules/@guancecloud/ft_sdk_ext、oh_modules/@guancecloud/ft_native のように構成されます。

バイトコード 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 に同梱される consumer 難読化ルールによって公開 API が保持されます。SDK パッケージ内の consumer-rules.txt を削除または置き換えないでください。アプリ自身で難読化を有効にしている場合も、SDK の公開機能を正常に呼び出せます。

HAR の取得方法¶

新しい HAR の取得方法¶

まず対象の ohpm ページを開きます
次に、目的のバージョンの dist.tarball を探します
dist.tarball からダウンロードし、対応する HAR パッケージを取り出します

対応するアドレス：

@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 です
実際に使用する 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 を旧パッケージ名と深いパスからのインポート方式から、現在の scoped パッケージ名と公開 Index エントリに移行する方法を説明します。対象となるプロジェクトは、次の 3 種類です。

ローカル HAR 方式で導入しており、ft_sdk.har、ft_sdk_ext.har、ft_native.har を使用したことがある
ohpm でインストールしているが、スコープなしの旧パッケージ名の設定や深いパスからのインポートをまだ使用している
@guancecloud/ scoped パッケージ名に移行済みだが、コードが依然として @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 インストールでも、依存名は scoped パッケージ名に統一し、コードのインポートは公開 Index エントリに統一してください
@guancecloud/.../src/main/... は旧バージョンの scoped 深いパス表記です。移行の参考にはなりますが、最新の推奨導入方法ではありません
ローカル 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"
  }
}

従来の scoped 深いパス表記：

//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 でインストールする場合も、依存名を scoped パッケージ名に変更する必要があります。例：

ohpm install @guancecloud/ft_sdk
ohpm install @guancecloud/ft_sdk_ext
ohpm install @guancecloud/ft_native

比較の説明：

新しい表記では、依存名を従来の ft_sdk、ft_sdk_ext、ft_native から scoped パッケージ名に変更しています
ohpm でインストールする場合も、新しい scoped パッケージ名を使用してインストールコマンドを実行してください
overrides はプロジェクトルートの oh-package.json5 に設定します
プロジェクトがローカル HAR 方式で ft_sdk_ext.har を導入している場合、overrides["@guancecloud/ft_sdk"] は、その内部のリモート依存関係をローカルの ft_sdk.har に書き換えるために使用します
ft_sdk.har または ft_native.har のみを使用する場合は、実際の必要に応じて対応する dependencies を残してください

コードのインポート変更¶