UniApp アプリケーション接続¶
ドキュメント概要¶
本書は UniApp RUM SDK のエントリーページとして、初回接続に必要な情報、インストール方法、参照順序、詳細設定への入り口、高度なユースケースへの入り口、FAQ をまとめています。
パラメータ一覧、API の説明、手動収集の例、実行時の機能については、以下の専用ページを参照してください。
参照順序¶
以下の順序で参照することをお勧めします。
0.2.xからのアップグレードでは、まず UniApp 0.3.0 移行ガイド を参照してください。- 初回接続では、まず接続方法を選択してください。手動接続の場合はクイックスタートを参照できます。
- 実際の接続方法に応じてインストールを完了します。
- SDK の初期化が完了したら、引き続き SDK 初期化 と RUM 設定 を参照してください。
- ログ収集と分散型トレーシングが必要な場合は、引き続き Log 設定 と Trace 設定 を参照してください。
- タグ、マスキング、WebView 収集が必要な場合は、対応する高度なトピックを参照してください。
前提条件¶
uni-app アプリケーションで GC-UniPlugin 0.3.0 以降に接続する場合は、HBuilderX 4.25.0 以降を使用します。
注意:すでに RUM Headless サービスを開通している場合、前提条件は自動的に設定済みであるため、そのままアプリケーションの接続を開始できます。
ローカル環境にデプロイする場合は、以下のデータ受信側の設定を完了する必要があります。パブリック DataWay を使用する場合は、DataKit を自身でデプロイする必要はありません。
- DataKit をインストールします。
- RUM コレクタを設定します。
- DataKit をパブリックからアクセス可能にし、IP ジオロケーションライブラリをインストールします。
アプリケーションの接続¶
- RUM > アプリを作成 に移動します。
- 実際のリリースプラットフォームごとに Android、iOS、HarmonyOS のアプリケーションを作成します。
- 各プラットフォームに対応する
RUM App IDを保存し、RUM の初期化時にそれぞれandroidAppId、iOSAppId、harmonyAppIdを渡します。 - 「接続方法の選択」で Agent 自動接続または手動接続を選択し、「接続設定」を完了します。
接続方法を選択¶
アプリケーションの設定ページで「Agent 自動接続」または「手動接続」を選択し、「接続設定」を完了します。既存のアプリケーションは、設定ページに直接移動して接続を続行できます。
| 接続方法 | ユースケース | 操作の入り口 |
|---|---|---|
| Agent 自動接続 | コーディングアシスタントにプロジェクトを分析させて SDK の接続を完了したい場合 | コンソールが生成したプロンプトをコピーし、アプリケーションのコードリポジトリでコーディングアシスタントに渡して実行します |
| 手動接続 | SDK を自身でインストールしてパラメータを設定したい場合 | データ送信方式を確認し、本書とクイックスタートに従って設定を完了します |
Agent 自動接続¶
- 現在のアプリケーションの設定ページで「Agent 自動接続」を選択します。
- 「接続設定」のプロンプト全体をコピーし、現在のアプリケーションの接続情報が使用されていることを確認します。
- アプリケーションのコードリポジトリでコーディングアシスタントを開き、プロンプトを貼り付けます。Agent は接続ガイドに従ってプロジェクトを分析し、SDK の設定を完了します。
- アプリケーションをビルドして実行し、ページアクセスなどの操作を発生させ、現在のアプリケーションのエクスプローラーでデータが受信されたことを確認します。
クロスプラットフォームフレームワークを使用する場合は、Agent にフレームワークと対象プラットフォームを伝え、各プラットフォームに対応するアプリケーション情報をそれぞれ提供してください。
ページに個人 API Key または一時認証コードが未準備である旨が表示された場合は、案内に従って準備を完了してからプロンプトを再コピーしてください。
手動接続¶
アプリケーションの設定ページで「手動接続」を選択し、データ送信方式を確認します。
- パブリック DataWay:
datawayUrlとclientTokenを準備します。 - ローカル環境へのデプロイ:
datakitUrlを準備します。
後述のインストールとクイックスタートに従って、SDK のインストール、初期化、検証を完了します。すでに SDK 設定がある場合は、まず内容を確認して再利用し、重複した初期化を避けてください。
インストール¶
ローカルでの使用¶
ソースコード:GuanceCloud/datakit-uniapp-native-plugin
ダウンロードした SDK パッケージの構成は以下のとおりです。
|-- datakit-uniapp-native-plugin
|-- Hbuilder_Example // HBuilderX サンプルプロジェクトとそのまま使用できる uni_modules
|-- uni_modules
|-- GC-JSPlugin // JS 自動収集
|-- js_sdk
|-- Action/GCActionTracking.js // HarmonyOS 側の Action 自動収集
|-- Error/GCErrorTracking.js // Error 自動収集
|-- Request/GCResourceTracking.js // uni.request の Resource と Trace の自動収集
|-- View/GCViewTracking.js // 推奨される View グローバル自動収集器
|-- index.js
|-- package.json
|-- GC-UniPlugin // Android、iOS、HarmonyOS の UTS メインプラグイン
|-- utssdk
|-- setup.js // JS 収集器と UTS SDK のブリッジを確立
|-- package.json
|-- GC-UniSessionReplay // オプションの Android、iOS Session Replay プラグイン
|-- native-projects // ネイティブビルド、パッケージング、統合検証用プロジェクト
|-- dist // 対外リリース成果物
|-- native-sdk-hybrid // uni-app アプリケーションのオフラインビルド成果物
|-- unimp-host-extension // ホスト App が使用する GC-UniPlugin ネイティブ依存ライブラリ
SDK ソースコードリポジトリの該当バージョンの Hbuilder_Example/uni_modules から、以下のディレクトリをビジネスプロジェクトの uni_modules にコピーします。
Session Replay が必要な場合は、オプションの GC-UniSessionReplay もインストールします。Session Replay は現在 Android と iOS のみをサポートしています。
インストール済みのすべてのモジュールは同一のリリースバージョンを使用する必要があります。アップグレード時はすべてまとめて置き換え、異なるバージョンの JS、UTS、Session Replay モジュールを混在させないでください。
GC-UniPlugin は 0.3.0 から追加され、旧バージョンの nativeplugins/GCUniPlugin ネイティブプラグインを置き換えるものです。これは UTS モジュールであるため、nativeplugins にコピーする必要はなく、manifest.json で旧ローカルネイティブプラグインを登録する必要もありません。GC-JSPlugin は引き続き共通 JS API と収集器を提供します。
UTS Bridge の読み込み¶
アプリケーションのエントリで最初に setup.js を一度読み込みます。
SDK API は GC-UniPlugin からインポートし、HBuilderX が UTS interface に基づいて提供する型チェックとパラメータヒントを利用します。JS 収集器は GC-JSPlugin からインポートします。
import {
mobileAgent,
rum,
logger,
tracer
} from '@/uni_modules/GC-UniPlugin';
import {
gcErrorTracking,
gcViewTracking,
gcResourceTracking,
gcActionTracking
} from '@/uni_modules/GC-JSPlugin';
マーケットプレイスプラグイン方式¶
現在、マーケットプレイスプラグイン方式は提供されていません。ローカルでの使用で接続を完了してください。
uni ミニプログラム SDK のインストール¶
本節の「uni ミニプログラム」は、uni-app で開発し、HBuilderX で wgt リソースパッケージとして作成され、ホスト App 上で動作するプロジェクトを特に指します。WeChat、Alipay などのプラットフォームのミニプログラムを一般的に指すものではありません。
uni ミニプログラム SDK のインストールは、uni ミニプログラムプロジェクトとホスト App の 2 つの部分で構成されます。
| 接続位置 | インストール内容 | 主な役割 |
|---|---|---|
| uni ミニプログラムプロジェクト | GC-JSPlugin |
共通 JS API を提供し、View、Error、Resource、Action を収集します |
| ホスト App | Native SDK + uni ミニプログラムホスト拡張 | SDK を初期化し、ネイティブデータを収集し、uni ミニプログラムにネイティブ Module を提供します |
開発デバッグと wgt リリースでの使用¶
開発デバッグ時および wgt リソースパッケージ作成時は、uni ミニプログラムプロジェクトには GC-JSPlugin のみをインストールします。
GC-JSPlugin はディレクトリ全体で提供され、SDK リポジトリ内のソースディレクトリは Hbuilder_Example/uni_modules/GC-JSPlugin/ です。このディレクトリを uni ミニプログラムプロジェクトの uni_modules/ 配下にコピーすると、最終的なパスは uni_modules/GC-JSPlugin/ になります。
uni ミニプログラムプロジェクトでは、GC-UniPlugin をインストールまたはインポートせず、GC-UniPlugin/setup.js も読み込まないでください。そうしないと UTS コードがプロジェクトのコンパイル依存に含まれてしまいます。
SDK オブジェクトと JS 収集器は、すべて GC-JSPlugin からインポートします。
import {
mobileAgent,
rum,
logger,
tracer,
gcErrorTracking,
gcViewTracking,
gcResourceTracking,
gcActionTracking
} from '@/uni_modules/GC-JSPlugin';
0.3.0 以降、新規に接続するプロジェクトではホスト App が SDK ならびに RUM、Log、Trace の初期化を完了します。uni ミニプログラムは mobileAgent.sdkConfig()、rum.setConfig()、logger.setConfig()、tracer.setConfig() を重複して呼び出さず、以下の実行時 API のみを呼び出します。
bindRUMUserData()、unbindRUMUserData()appendGlobalContext()、appendRUMGlobalContext()、appendLogGlobalContext()、appendBridgeContext()rum、logger、tracerが提供する手動データ収集と Header 取得の API
既存の 0.2.x uni ミニプログラムプロジェクトをアップグレードする場合、従来の初期化方式を維持し、引き続き uni.requireNativePlugin() で Module を取得できます。ビジネスコードを直ちに書き換える必要はありません。
const mobileAgent = uni.requireNativePlugin('GCUniPlugin-MobileAgent');
const rum = uni.requireNativePlugin('GCUniPlugin-RUM');
const logger = uni.requireNativePlugin('GCUniPlugin-Logger');
const tracer = uni.requireNativePlugin('GCUniPlugin-Tracer');
新規プロジェクトでは、すべて GC-JSPlugin からインポートすることを推奨します。旧バージョンの具体的な移行方法は0.2.x からのアップグレードを参照してください。
ホスト App への統合¶
ホスト App は、対応プラットフォームの Native SDK と 0.3.0 以降の uni ミニプログラムホスト拡張を統合する必要があります。
| ホストプラットフォーム | ホスト拡張の形態 | リリース成果物 | SDK リポジトリ内のリリースパス |
|---|---|---|---|
| Android | Android UniModule | gc-uniplugin-<version>.aar |
dist/unimp-host-extension/android/ |
| iOS | DCUniModule |
GC-UniPlugin-App.xcframework |
dist/unimp-host-extension/ios/ |
| HarmonyOS | ETS ネイティブ拡張 | GCUniPlugin.har |
dist/unimp-host-extension/harmony/ |
リリース成果物の名称は、使用するバージョンのリリースパッケージ内の実際のファイル名に従います。
ホスト拡張は、uni ミニプログラムが共通 JS API または uni.requireNativePlugin() を通じてネイティブ機能を呼び出せるよう、uni ミニプログラムの実行環境に以下のモジュール ID を登録する必要があります。
ホスト App は、プラットフォームごとに以下の依存関係の統合と Module の登録操作を完了する必要があります。
iOS¶
-
依存ライブラリを追加します。
ホスト App は iOS Native SDK インストール手順 に従って Native SDK を統合します。Swift Package Manager の使用を推奨し、
GuanceSDKPackage Product をホスト App の Target に追加します。Native SDK のバージョンは UniApp SDK のリリースバージョンと一致する必要があります。具体的なバージョンは該当バージョンの更新履歴を参照してください。リリースパッケージ内の
GC-UniPlugin-App.xcframeworkをホスト App の Target に追加します。Xcode のTARGETS -> Build Phases -> Link Binary With Librariesで「+」をクリックし、Add Other -> Add Files...を選択して該当ファイルを選択します。この XCFramework は静的ライブラリであるため、TARGETS -> General -> Frameworks, Libraries, and Embedded ContentではDo Not Embedのままにします。 -
アプリケーション起動時に
GCUniPluginModule を登録します。- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions { [WXSDKEngine registerModule:@"GCUniPlugin-MobileAgent" withClass:NSClassFromString(@"FTMobileUniModule")]; [WXSDKEngine registerModule:@"GCUniPlugin-RUM" withClass:NSClassFromString(@"FTRUMModule")]; [WXSDKEngine registerModule:@"GCUniPlugin-Logger" withClass:NSClassFromString(@"FTLogModule")]; [WXSDKEngine registerModule:@"GCUniPlugin-Tracer" withClass:NSClassFromString(@"FTTracerModule")]; return YES; }
Android¶
-
依存ライブラリを追加します。
リリースパッケージ内の
gc-uniplugin-<version>.aarをホストプロジェクトのlibsディレクトリにコピーします。Android Native SDK Gradle 設定 に従って Maven リポジトリを追加し、build.gradleに以下の依存関係を追加します。dependencies { implementation files('libs/gc-uniplugin-<version>.aar') implementation 'com.cloudcare.ft.mobile.sdk.tracker.agent:ft-sdk:<version>' implementation 'com.cloudcare.ft.mobile.sdk.tracker.agent:ft-native:<version>' implementation 'com.alibaba:fastjson:1.2.83' implementation 'com.google.code.gson:gson:2.8.5' }Native SDK のバージョンは UniApp SDK のリリースバージョンと一致する必要があります。具体的なバージョンは該当バージョンの更新履歴を参照してください。
-
Application.onCreate()でGCUniPluginModule を登録します。public class App extends Application { @Override public void onCreate() { super.onCreate(); try { WXSDKEngine.registerModule("GCUniPlugin-MobileAgent", FTSDKUniModule.class); WXSDKEngine.registerModule("GCUniPlugin-RUM", FTRUMModule.class); WXSDKEngine.registerModule("GCUniPlugin-Logger", FTLogModule.class); WXSDKEngine.registerModule("GCUniPlugin-Tracer", FTTracerModule.class); } catch (Exception e) { e.printStackTrace(); } } }
HarmonyOS¶
GCUniPlugin.har をホストプロジェクトの libs に配置し、oh-package.json5 に UniMP ランタイムとローカル拡張の依存関係を追加します。
{
"dependencies": {
"@dcloudio/uni-app-runtime": "5.2.32026080401",
"@guancecloud/gc-uniplugin": "file:./libs/GCUniPlugin.har"
}
}
依存関係を追加した後、プロジェクトディレクトリで ohpm install を実行します。
ホスト拡張は initializeNativeSDK() と registerNativeModules() を提供します。ホストはまず UIAbility.onCreate() で SDK を初期化します。その後、init() で uni ミニプログラム実行環境の初期化が完了した後、最初に uni ミニプログラムを開く前にモジュールを登録します。
import { UIAbility } from '@kit.AbilityKit';
import { window } from '@kit.ArkUI';
import { init } from '@dcloudio/uni-app-runtime';
import {
initializeNativeSDK,
registerNativeModules
} from '@guancecloud/gc-uniplugin';
import { SDK_STARTUP_CONFIG } from '../config/SDKStartupConfig';
export default class EntryAbility extends UIAbility {
onCreate(): void {
initializeNativeSDK(this.context, SDK_STARTUP_CONFIG);
}
onWindowStageCreate(windowStage: window.WindowStage): void {
init(this, windowStage, { debug: true });
registerNativeModules(this.context);
// 此后再打开 uni 小程序。
}
}
SDK_STARTUP_CONFIG はホスト App が提供し、Mobile、RUM、Log、Trace の初期化設定を含みます。uni ミニプログラムは対応する初期化 API を重複して呼び出しません。
初期化とデバッグ¶
ホスト App は、uni ミニプログラムを開く前に Native SDK の初期化と Module の登録を完了し、最終的なアプリケーション内に Native SDK が 1 つだけ、SDK シングルトンが 1 組だけ存在することを保証する必要があります。uni ミニプログラムで SDK を再度初期化する必要はありません。
Android と iOS のホストにおける Native SDK の初期化方法は、それぞれ Android SDK 初期化 と iOS SDK 初期化 を参照してください。HarmonyOS のホストは前述の initializeNativeSDK() を使用して初期化します。
uni ミニプログラムプロジェクトが、ホスト拡張を統合していない通常のデバッグベースで動作する場合、GC-JSPlugin は存在しないネイティブ呼び出しを空操作にダウングレードするため、uni.requireNativePlugin() が null を返してもページの読み込みが妨げられることはありません。このモードは JS ページと収集ロジックのデバッグにのみ使用でき、ネイティブデータの送信は検証できません。完全な結合テストは実際のホスト App で行う必要があります。
0.2.x からのアップグレード¶
0.3.0 では、通常の uni-app と uni ミニプログラムで異なる移行方法を採用します。通常の uni-app は GC-UniPlugin で旧ネイティブプラグインを置き換えます。uni ミニプログラムプロジェクトは引き続き GC-JSPlugin のみを統合し、ホスト App が Native SDK とホスト拡張をアップグレードします。
依存関係の全体構成、API のインポート、初期化の位置、互換方法、移行前後のコード比較については、UniApp 0.3.0 移行ガイド を参照してください。
詳細設定への入り口¶
設定の説明¶
- クイックスタート:初回接続の最短経路。
- SDK 初期化:基本設定、ユーザーバインド、SDK の終了、キャッシュのクリア、能動的な同期。
- RUM 設定:RUM の初期化設定、Action/View/Error/Resource の収集機能。
- Log 設定:Log の初期化設定とログ出力。
- Trace 設定:Trace の初期化設定と分散型トレーシング。
高度なユースケース¶
よくある質問¶
Android のクラウドビルドとオフラインビルドの違い¶
Android のクラウドビルドとオフラインビルドでは、2 つの異なる統合ロジックを使用します。オフラインビルド方式は Android Native SDK の統合方式と同一で、ホストプロジェクトに Android Gradle Plugin を適用できます。クラウドビルドではこのプラグインを適用できないため、一部の機能は UniApp プラグイン内部で実装されます。
そのため、オフラインビルドでは通常、より完全なネイティブ自動収集機能を利用できます。sdkConfig では offlinePackage で 2 つのビルド方式を区別します。
- Android のクラウドビルド:デフォルト値
falseのままにします。 - Android のオフラインビルド:
trueに設定します。 - 既存の
0.2.xuni ミニプログラムプロジェクトで、引き続き JS 側でsdkConfig()を呼び出す場合:trueに設定します。 0.3.0以降の新しい uni ミニプログラム接続ではホスト App が SDK を初期化するため、このパラメータは関与しません。uni ミニプログラムはsdkConfig()を重複して呼び出しません。
オフラインビルドまたは uni ミニプログラムのホスト App で、App の起動、ネイティブページ、クリック、ネットワークリクエスト、WebView のデータを収集する場合は、ホストプロジェクトで Android Gradle Plugin を設定する必要もあります。
その他¶
- Android プライバシー審査
- iOS その他の関連項目
- Android その他の関連項目
- ネイティブシンボルファイルのアップロード:Android、iOS