UniApp 0.3.0 移行ガイド¶

本ドキュメントは、0.2.x から 0.3.0 以降のバージョンにアップグレードするプロジェクトを対象としています。

プロジェクトの統合方式を確認し、該当するセクションのみをお読みください。

• uni-app アプリケーション：HBuilderX で直接 App をビルドする場合、uni-app アプリケーションの移行 をお読みください。
• ホストアプリ内の uni ミニアプリ：uni-app で開発・wgt リソースパッケージ化し、ホストアプリ内で動作させる場合、ホストアプリ内の uni ミニアプリの移行 をお読みください。

以下の diff コードブロックでは、- は削除する内容、+ は追加する内容を示します。

uni-app アプリケーションの移行¶

0.3.0 では、従来の App ネイティブ言語プラグイン nativeplugins/GCUniPlugin を置き換えるために、GC-UniPlugin UTS プラグインが新たに追加されました。アップグレード時には、プラグインの置き換えと SDK API のインポート方法の変更という 2 つの修正が必要です。

1. App ネイティブ言語プラグインの置き換え¶

古いローカルネイティブ言語プラグインを削除し、代わりに GC-UniPlugin UTS プラグインをインストールします。

- nativeplugins/GCUniPlugin
+ uni_modules/GC-UniPlugin

移行後のディレクトリ構造：

uni_modules/
├── GC-JSPlugin
└── GC-UniPlugin

併せて以下の操作を実施してください。

1. manifest.json から nativeplugins/GCUniPlugin に対応するローカルネイティブ言語プラグインの設定を削除します。
2. 同一バージョンのリリースパッケージから GC-JSPlugin と GC-UniPlugin をコピーしてください。異なるバージョンを混在させないでください。
3. HBuilderX は 4.25.0 以降のバージョンを使用してください。

0.2.0 から 0.2.3 へのアップグレードの場合、元のプロジェクトに GC-JSPlugin が含まれていない可能性があります。その場合は、移行時に両方のモジュールを同時にインストールしてください。

nativeplugins/GCUniPlugin と uni_modules/GC-UniPlugin を同時に保持しないでください。SDK の重複、データ収集の重複、またはネイティブシンボルの競合が発生する可能性があります。

2. SDK API のインポート方法の変更¶

uni.requireNativePlugin() を使用して SDK オブジェクトを取得するコードを削除し、代わりに GC-UniPlugin からインポートするように変更します。

- const mobileAgent = uni.requireNativePlugin('GCUniPlugin-MobileAgent');
- const rum = uni.requireNativePlugin('GCUniPlugin-RUM');
- const logger = uni.requireNativePlugin('GCUniPlugin-Logger');
- const tracer = uni.requireNativePlugin('GCUniPlugin-Tracer');
+ // main.js / main.ts：一度だけ読み込み、GC-JSPlugin コレクターの呼び出しより前に配置します
+ import '@/uni_modules/GC-UniPlugin/setup.js';
+ import {
+     mobileAgent,
+     rum,
+     logger,
+     tracer
+ } from '@/uni_modules/GC-UniPlugin';

3. 既存の初期化コードはそのまま維持¶

API のインポート方法を移行した後、既存の初期化呼び出しは引き続き使用できます。

mobileAgent.sdkConfig(mobileConfig);
rum.setConfig(rumConfig);
logger.setConfig(loggerConfig);
tracer.setConfig(traceConfig);

以下の状況に応じて、関連パラメータを確認するだけで済みます。

サンプルレートパラメータ¶

設定で samplerate を使用している場合は、sampleRate に変更することを推奨します。

rum.setConfig({
-    samplerate: 1
+    sampleRate: 1
});

logger.setConfig({
-    samplerate: 1
+    sampleRate: 1
});

tracer.setConfig({
-    samplerate: 1
+    sampleRate: 1
});

samplerate は現在も互換性がありますが、非推奨です。両方が設定されている場合は sampleRate が優先されます。

HarmonyOS アプリケーションの新規対応¶

HarmonyOS アプリケーションをリリースする場合のみ、対応する RUM App ID を追加します。

rum.setConfig({
    androidAppId: 'YOUR_ANDROID_APP_ID',
    iOSAppId: 'YOUR_IOS_APP_ID',
+    harmonyAppId: 'YOUR_HARMONY_APP_ID',
    // ...
});

各プラットフォームでは、それぞれ観測雲で作成した RUM App ID を使用してください。

HarmonyOS で Action を自動収集する場合は、アプリケーション起動時に以下の呼び出しも必要です。

gcActionTracking.startTracking();

4. 必要に応じて JS コレクターを調整¶

0.2.6 以下のバージョンからアップグレードし、Vue 3 を使用する場合¶

Vue 3 では、createSSRApp() が返すアプリケーションインスタンスを gcViewTracking.startTracking() に渡す必要があります。

-gcViewTracking.startTracking();

export function createApp() {
    const app = createSSRApp(App);
+    gcViewTracking.startTracking(app);
    return { app };
}

詳細は View 自動収集 を参照してください。

gcRequest から gcResourceTracking への移行¶

gcResourceTracking は 0.2.7 から提供されており、標準の uni.request をインターセプトするために使用します。プロジェクトで非推奨の gcRequest を引き続き使用している場合は、gcResourceTracking への移行を推奨します。両方の収集方式を同時に有効にしないでください。詳細は Resource 自動収集 を参照してください。

ホストアプリ内の uni ミニアプリの移行¶

本セクションの「uni ミニアプリ」は、uni-app で開発・wgt リソースパッケージ化し、ホストアプリ内で動作させるプロジェクトを指します。

0.3.0 では、App ネイティブ言語プラグインの使用方法と公開場所が変更されました。

  # uni ミニアプリプロジェクト
- nativeplugins/GCUniPlugin
  uni_modules/GC-JSPlugin

  # ホストアプリ
- nativeplugins/GCUniPlugin からホスト側ネイティブ依存関係を取得
+ dist/unimp-host-extension から GC-UniPlugin ネイティブ依存ライブラリを取得

uni ミニアプリプロジェクトは、App ネイティブ言語プラグインが不要になり、uni-app アプリケーションで使用する GC-UniPlugin UTS プラグインもインストールしません。ホストアプリは引き続き Native SDK を統合し、dist/unimp-host-extension にある対応プラットフォームの GC-UniPlugin ネイティブ依存ライブラリを追加する必要があります。

1. uni ミニアプリプロジェクトの調整¶

1. nativeplugins/GCUniPlugin と manifest.json 内の対応する App ネイティブ言語プラグイン設定を削除します。
2. GC-JSPlugin ディレクトリ全体を 0.3.0 以降のバージョンに置き換えます。
3. GC-UniPlugin はインストールせず、GC-UniPlugin/setup.js も読み込みません。

調整後のディレクトリ構造：

uni_modules/
└── GC-JSPlugin

ここでは SDK 依存関係のみを調整するため、uni ミニアプリプロジェクトのアップグレードや改造は必要ありません。既存のコードで uni.requireNativePlugin() を直接呼び出して SDK オブジェクトを取得している場合は、次の手順の修正も必要です。

2. SDK API のインポート方法の変更¶

App ネイティブ言語プラグインを削除した後、uni.requireNativePlugin() を直接呼び出すと、ネイティブプラグインが見つからないというエラーが発生し、無効なオブジェクトが返される可能性があり、その後のメソッド呼び出しができなくなります。代わりに GC-JSPlugin から SDK API をインポートするように変更します。

- const mobileAgent = uni.requireNativePlugin('GCUniPlugin-MobileAgent');
- const rum = uni.requireNativePlugin('GCUniPlugin-RUM');
- const logger = uni.requireNativePlugin('GCUniPlugin-Logger');
- const tracer = uni.requireNativePlugin('GCUniPlugin-Tracer');
+ import {
+     mobileAgent,
+     rum,
+     logger,
+     tracer
+ } from '@/uni_modules/GC-JSPlugin';

GC-JSPlugin は、ホストが対応するネイティブ Module を登録しているかどうかを確認します。Module が利用できない場合、後続の API 呼び出しは安全にダウングレードされ、ビジネスコードの中断を回避します。GC-UniPlugin ネイティブ依存ライブラリが統合されていないベースでデバッグする場合、コンソールに「現在実行中のベースにはネイティブプラグインが含まれていません。manifest でプラグインを設定してください」という一般的なメッセージが表示されることがあります。このシナリオでは、App ネイティブ言語プラグインを再設定する必要はありません。ネイティブ機能は、依存関係の統合が完了したホストアプリで検証する必要があります。

3. ホストアプリの依存関係の更新¶

ホストアプリは引き続き Native SDK を統合します。nativeplugins/GCUniPlugin から取得していたホスト側ネイティブ依存関係を、dist/unimp-host-extension にある対応プラットフォームの GC-UniPlugin ネイティブ依存ライブラリに置き換えます。

• Android：gc-uniplugin-<version>.aar
• iOS：GC-UniPlugin-App.xcframework
• HarmonyOS：GCUniPlugin.har

GC-UniPlugin ネイティブ依存ライブラリは、uni ミニアプリの実行環境に SDK Module を登録するために使用され、旧バージョンの App ネイティブ言語プラグインが提供していたホスト側ネイティブ機能に対応します。

各プラットフォームの依存関係と登録方法については、ホストアプリの統合 を参照してください。

アップグレード後の検証¶

アップグレードが完了し、カスタムベースまたはインストールパッケージを再作成した後、以下の項目を確認してください。

• アプリケーション内で Native SDK が 1 回だけ初期化されていること。
• 有効化された RUM、Log、Trace のデータが正常にレポートされること。
• uni-app アプリケーションで古いネイティブ言語プラグインが削除され、setup.js が JS コレクターより前に読み込まれていること。
• uni ミニアプリのホストアプリが、wgt を開く前に Native SDK の初期化と Module の登録を完了していること。
• uni.request のビジネスコールバックが正常に動作し、Trace が有効な場合に Trace Header が正常に追加されること。

Native API を呼び出せない場合は、トラブルシューティング を参照してください。