コンテンツにスキップ

HarmonyOS アプリケーションの統合

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

読み進め方

前提条件

注意

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

アプリケーションの統合

  1. ユーザーアクセスモニタリング > アプリケーションを作成 > HarmonyOS に移動します。
  2. アプリケーション名とアプリケーション ID を入力します。
  3. アプリケーションの統合方式を選択します：
  4. パブリックネットワーク DataWay：DataKit コレクターをインストールせずに RUM データを直接受信します。
  5. ローカル環境へのデプロイ：前提条件を満たした上で RUM データを受信します。

インストール

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

方法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 に必要に応じてスコープ付き依存関係を追加します。

{
  "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/ ディレクトリにインストールされます。スコープ付き依存関係を使用する場合、ディレクトリは通常 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 Level が 12 以上であること。ft_sdk_ext の HttpInterceptorChain 機能は引き続き API Level 22 以上が必要です。
  • プロジェクトルートの build-profile.json5 で、実際のビルドプロダクトに対して OHMUrl の正規化を有効にすること。同名の設定が既に存在する場合は、strictMode の内容をマージするだけで問題ありません：
{
  "app": {
    "products": [
      {
        "name": "default",
        "buildOption": {
          "strictMode": {
            "useNormalizedOHMUrl": true
          }
        }
      }
    ]
  }
}
  • oh-package.json5 内の依存関係名は SDK パッケージ名と一致している必要があります。コードは、各パッケージの公開 Index エントリからのみ API をインポートし、src/main/... などの内部パスは使用しないでください。
  • リリースパッケージは ArkGuard による難読化が有効になっており、HAR に付属するコンシューマー難読化ルールにより公開 API が保護されています。SDK パッケージ内の consumer-rules.txt は削除または置き換えないでください。アプリケーション自体で難読化を有効にしている場合でも、SDK の公開機能は正常に呼び出せます。

HAR の入手方法

新しい HAR の入手方法

  • まず、対応する ohpm ページに移動します。
  • 次に、対象バージョンの dist.tarball を見つけます。
  • dist.tarball から対応する HAR パッケージをダウンロードして解凍します。

対応するアドレス：

注意事項：

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

旧バージョンの HAR ダウンロード方法

パッケージの説明

実際の能力に応じて、関連するパッケージを導入してください：

  • ft_sdk.har はコアパッケージであり、必須です。サードパーティリポジトリからインストールする場合のパッケージ名は @guancecloud/ft_sdk です。
  • ft_sdk_ext.har は拡張パッケージであり、@kit.NetworkKit ベースの HttpInterceptorChain を使用した自動収集機能が必要な場合にのみインストールします。HttpInterceptor 関連機能は 0.1.14-alpha03 以降でサポートされ、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 自動収集関連のインポートエントリです。
  • 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 のグローバル変数を上書きします。

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

フィードバック

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