UniApp アプリケーションに接続¶

ドキュメントの概要¶

このページは UniApp RUM SDK のエントリーページです。初回接続に必要な情報、インストール方法、読み進める順序、詳細な設定の入り口、高度なシナリオの入り口、FAQ をまとめています。

パラメータテーブル、API 説明、手動収集のサンプル、ランタイムの機能については、以下の各トピックページをご参照ください。

読み進める順序¶

以下の順序でお読みになることをお勧めします。

0.2.x からのアップグレードは、まず UniApp 0.3.0 移行ガイドをお読みください。
初回接続は、まずクイックスタートをお読みください。
実際の接続方式に従ってインストールを完了してください。
SDK の初期化が完了したら、SDK 初期化と RUM 設定を引き続きお読みください。
ログ収集と分散型トレーシングが必要な場合は、Log 設定と Trace 設定を引き続きお読みください。
タグ、マスキング、WebView 収集が必要な場合は、さらに各高度なトピックをお読みください。

前提条件¶

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

DataKit をインストールしていること。
RUM コレクターを設定していること。
DataKit がインターネットからアクセス可能で、かつ IP 地理位置情報データベースをインストールしていること。
uni-app アプリケーションが GC-UniPlugin 0.3.0 以降のバージョンで接続する場合、HBuilderX 4.25.0 以降を使用してください。

アプリケーションに接続¶

RUM > アプリケーションを作成 に進みます。
実際の公開プラットフォームに応じて、Android、iOS、HarmonyOS アプリケーションをそれぞれ作成します。
各プラットフォームに対応する RUM App ID を保存し、RUM 初期化時にそれぞれ androidAppId、iOSAppId、harmonyAppId を渡します。
データ送信方式を選択します。
パブリックネットワーク DataWay：datawayUrl と clientToken を準備します。
ローカル環境へのデプロイ：datakitUrl を準備します。

インストール¶

ローカルで使用する¶

ソースコードアドレス：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 が提供する手動データ収集およびヘッダー取得 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 ミニプログラムの実行環境に以下のモジュール ID を登録する必要があります。これにより、uni ミニプログラムが共通 JS API または uni.requireNativePlugin() を通じてネイティブの機能を呼び出せるようになります。

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

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

iOS¶

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

ホスト 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 のままにします。

アプリケーション起動時に 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¶

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

リリースパッケージ内の 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() で 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 と一連の SDK シングルトンのみが存在することを確認する必要があります。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 のクラウドパッケージングとオフラインパッケージングでは、異なる統合ロジックが使用されます。オフラインパッケージングの方法は 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 で、アプリ起動、ネイティブページ、クリック、ネットワークリクエスト、WebView データを収集する必要がある場合は、ホストプロジェクトで Android Gradle Plugin を設定する必要もあります。

その他¶

Android プライバシー監査
iOS その他関連
Android その他関連
ネイティブシンボルファイルのアップロード：Android、iOS