コンテンツにスキップ

UniApp アプリケーション接続


ドキュメント概要

本書は UniApp RUM SDK のエントリーページとして、初回接続に必要な情報、インストール方法、参照順序、詳細設定への入り口、高度なユースケースへの入り口、FAQ をまとめています。

パラメータ一覧、API の説明、手動収集の例、実行時の機能については、以下の専用ページを参照してください。

参照順序

以下の順序で参照することをお勧めします。

  1. 0.2.x からのアップグレードでは、まず UniApp 0.3.0 移行ガイド を参照してください。
  2. 初回接続では、まず接続方法を選択してください。手動接続の場合はクイックスタートを参照できます。
  3. 実際の接続方法に応じてインストールを完了します。
  4. SDK の初期化が完了したら、引き続き SDK 初期化 と RUM 設定 を参照してください。
  5. ログ収集と分散型トレーシングが必要な場合は、引き続き Log 設定 と Trace 設定 を参照してください。
  6. タグ、マスキング、WebView 収集が必要な場合は、対応する高度なトピックを参照してください。

前提条件

uni-app アプリケーションで GC-UniPlugin 0.3.0 以降に接続する場合は、HBuilderX 4.25.0 以降を使用します。

注意:すでに RUM Headless サービスを開通している場合、前提条件は自動的に設定済みであるため、そのままアプリケーションの接続を開始できます。

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

アプリケーションの接続

  1. RUM > アプリを作成 に移動します。
  2. 実際のリリースプラットフォームごとに Android、iOS、HarmonyOS のアプリケーションを作成します。
  3. 各プラットフォームに対応する RUM App ID を保存し、RUM の初期化時にそれぞれ androidAppId、iOSAppId、harmonyAppId を渡します。
  4. 「接続方法の選択」で Agent 自動接続または手動接続を選択し、「接続設定」を完了します。

接続方法を選択

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

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

Agent 自動接続

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

クロスプラットフォームフレームワークを使用する場合は、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 にコピーします。

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

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 を一度読み込みます。

import '@/uni_modules/GC-UniPlugin/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 のみをインストールします。

uni_modules/
└── 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 を登録する必要があります。

GCUniPlugin-MobileAgent
GCUniPlugin-RUM
GCUniPlugin-Logger
GCUniPlugin-Tracer

ホスト App は、プラットフォームごとに以下の依存関係の統合と Module の登録操作を完了する必要があります。

iOS
  1. 依存ライブラリを追加します。

    ホスト App は iOS Native SDK インストール手順 に従って Native SDK を統合します。Swift Package Manager の使用を推奨し、GuanceSDK Package 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 のままにします。

  2. アプリケーション起動時に GCUniPlugin Module を登録します。

    - (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
  1. 依存ライブラリを追加します。

    リリースパッケージ内の 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 のリリースバージョンと一致する必要があります。具体的なバージョンは該当バージョンの更新履歴を参照してください。

  2. Application.onCreate() で GCUniPlugin Module を登録します。

    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.x uni ミニプログラムプロジェクトで、引き続き JS 側で sdkConfig() を呼び出す場合:true に設定します。
  • 0.3.0 以降の新しい uni ミニプログラム接続ではホスト App が SDK を初期化するため、このパラメータは関与しません。uni ミニプログラムは sdkConfig() を重複して呼び出しません。

オフラインビルドまたは uni ミニプログラムのホスト App で、App の起動、ネイティブページ、クリック、ネットワークリクエスト、WebView のデータを収集する場合は、ホストプロジェクトで Android Gradle Plugin を設定する必要もあります。

その他

フィードバック

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