Uniapp 開発フレームワークに基づくミニアプリの導入¶
更新履歴
2026.8.25：
@cloudcare/rum-uniapp2.2.22：allowedTracingUrlsを追加。完全なリクエスト URL でマッチング。allowedTracingOriginsは非推奨の互換設定に変更。抖音の navigation とページスタックが一時的に空になる際のページ帰属の問題を修正。
2026.8.20：
@cloudcare/rum-uniapp2.2.21：ページ初回レンダリング、FP、FCP、LCP、Ready 状態、ページ終了理由、setDataのセグメント化された所要時間、プラットフォーム能力フィールドを追加。低速レンダリングや白画面候補の統計に使用可能。
2026.8.11：
@cloudcare/rum-uniapp：allowTraceHeaderWithoutSession設定を追加。デフォルト値はfalse。有効にすると、現在の Session が RUM サンプリングにヒットしない場合でも、allowedTracingOriginsにヒットしたリクエストには Trace Header が注入されるが、その Session の RUM データが強制的にサンプリングされたりアップロードされたりすることはない。
2022.9.29：初期化パラメータに isIntakeUrl 設定を追加。リクエストリソース URL に基づいて、対応するリソースデータを収集するかどうかを判断するために使用。デフォルトではすべて収集。
2022.3.29：
traceType設定を追加。分散型トレーシングのツールタイプを設定。設定しない場合のデフォルトはddtrace。現在はddtrace、zipkin、skywalking_v3、jaeger、zipkin_single_header、w3c_traceparentの 6 種のデータタイプをサポート。allowedTracingOriginsを追加。Trace コレクターに必要なヘッダーを注入するためのすべてのリクエストリスト。リクエストの origin でも正規表現でも可。
前提条件¶
- DataKit をインストールしていること。
アプリケーションの導入¶
Guance コントロールパネルにログインし、リアルユーザーモニタリング（RUM） ページに移動します。左上のアプリケーションを作成をクリックし、新しいアプリケーションの作成を開始します。
右側で、インストール設定の導入方式を選択し、右側のパラメータ設定をクリックして関連パラメータを入力した後、プロジェクトにコピーして使用できます。
使用方法¶
Uniapp プロジェクトのエントリファイル main.js の先頭に以下のようにコードを追加します。
NPM¶
導入（Uniapp 公式のnpm 導入方法を参照）
...
import Vue from 'vue'
//#ifndef H5 || APP-PLUS || APP-NVUE || APP-PLUS-NVUE
const { datafluxRum } = require('@cloudcare/rum-uniapp')
// Rum の初期化
datafluxRum.init(Vue, {
datakitOrigin: '<DATAKIT ORIGIN>',// 必須、Datakit のドメインアドレス。WeChat ミニアプリ管理画面でドメインホワイトリストに追加する必要あり
applicationId: '<アプリケーション ID>', // 必須、dataflux プラットフォームで生成されたアプリケーション ID
env: 'testing', // オプション、ミニアプリの環境
version: '1.0.0', // オプション、ミニアプリのバージョン
service: 'miniapp', // 現在のアプリケーションのサービス名
trackInteractions: true, // ユーザー行動データ
sampleRate: 100, // 指標データ収集のパーセンテージ。100 は全収集、0 は収集なし
allowedTracingUrls: ['https://api.example.com/v1/', /https:\/\/.*\.my-api-domain\.com\/v2\//], // 完全なリクエスト URL でマッチング
})
//#endif
....
導入（Uniapp 公式のnpm 導入方法を参照）
...
//#ifndef H5 || APP-PLUS || APP-NVUE || APP-PLUS-NVUE
import { datafluxRum } from '@cloudcare/rum-uniapp'
// Rum の初期化
datafluxRum.initVue3({
datakitOrigin: '<DATAKIT ORIGIN>',// 必須、Datakit のドメインアドレス。WeChat ミニアプリ管理画面でドメインホワイトリストに追加する必要あり
applicationId: '<アプリケーション ID>', // 必須、dataflux プラットフォームで生成されたアプリケーション ID
env: 'testing', // オプション、ミニアプリの環境
version: '1.0.0', // オプション、ミニアプリのバージョン
service: 'miniapp', // 現在のアプリケーションのサービス名
trackInteractions: true, // ユーザー行動データ
sampleRate: 100, // 指標データ収集のパーセンテージ。100 は全収集、0 は収集なし
allowedTracingUrls: ['https://api.example.com/v1/', /https:\/\/.*\.my-api-domain\.com\/v2\//], // 完全なリクエスト URL でマッチング
})
//#endif
....
CDN¶
ファイルをダウンロードしてローカルに導入（ダウンロードアドレス）
...
import Vue from 'vue'
//#ifndef H5 || APP-PLUS || APP-NVUE || APP-PLUS-NVUE
const { datafluxRum } = require('./dataflux-rum-uniapp.js'); // js ファイルのローカルパス
// Rum の初期化
datafluxRum.init(Vue, {
datakitOrigin: '<DATAKIT ORIGIN>',// 必須、Datakit のドメインアドレス。WeChat ミニアプリ管理画面でドメインホワイトリストに追加する必要あり
applicationId: '<アプリケーション ID>', // 必須、dataflux プラットフォームで生成されたアプリケーション ID
env: 'testing', // オプション、ミニアプリの環境
version: '1.0.0', // オプション、ミニアプリのバージョン
service: 'miniapp', // 現在のアプリケーションのサービス名
trackInteractions: true, // ユーザー行動データ
sampleRate: 100, // 指標データ収集のパーセンテージ。100 は全収集、0 は収集なし
allowedTracingUrls: ['https://api.example.com/v1/', /https:\/\/.*\.my-api-domain\.com\/v2\//], // 完全なリクエスト URL でマッチング
})
//#endif
....
ファイルをダウンロードしてローカルに導入（ダウンロードアドレス）
...
//#ifndef H5 || APP-PLUS || APP-NVUE || APP-PLUS-NVUE
import { datafluxRum } from './dataflux-rum-uniapp.js'; // js ファイルのローカルパス
// Rum の初期化
datafluxRum.initVue3({
datakitOrigin: '<DATAKIT ORIGIN>',// 必須、Datakit のドメインアドレス。WeChat ミニアプリ管理画面でドメインホワイトリストに追加する必要あり
applicationId: '<アプリケーション ID>', // 必須、dataflux プラットフォームで生成されたアプリケーション ID
env: 'testing', // オプション、ミニアプリの環境
version: '1.0.0', // オプション、ミニアプリのバージョン
service: 'miniapp', // 現在のアプリケーションのサービス名
trackInteractions: true, // ユーザー行動データ
sampleRate: 100, // 指標データ収集のパーセンテージ。100 は全収集、0 は収集なし
allowedTracingUrls: ['https://api.example.com/v1/', /https:\/\/.*\.my-api-domain\.com\/v2\//], // 完全なリクエスト URL でマッチング
})
//#endif
....
設定¶
初期化パラメータ¶
| パラメータ | 型 | 必須 | デフォルト値 | 説明 |
|---|---|---|---|---|
applicationId |
String | はい | Guance で作成されたアプリケーション ID。 | |
datakitOrigin |
String | はい | DataKit データアップロードの Origin。 ❗️ ミニアプリ管理画面で request ホワイトリストに追加する必要があります。 |
|
env |
String | いいえ | ミニアプリアプリケーションの現在の環境。例：prod：本番環境；gray：カナリア環境；pre：プリリリース環境；common：日常環境；local：ローカル環境。 | |
version |
String | いいえ | ミニアプリアプリケーションのバージョン番号。 | |
service |
String | いいえ | 現在のアプリケーションのサービス名。デフォルトは miniapp。カスタム設定可能。 |
|
sampleRate |
Number | いいえ | 100 |
指標データ収集のパーセンテージ。100 は全収集、0 は収集なし。 |
trackInteractions |
Boolean | いいえ | false |
ユーザー行動収集を有効にするかどうか。 |
traceType |
Enum | いいえ | ddtrace |
分散型トレーシングのツールタイプ。設定しない場合のデフォルトは ddtrace。現在は ddtrace、zipkin、skywalking_v3、jaeger、zipkin_single_header、w3c_traceparent の 6 種のデータタイプをサポート。❗️ 1. opentelemetry は zipkin_single_header、w3c_traceparent、zipkin、jaeger の 4 種をサポート。2. 対応するタイプの traceType を設定するには、対応する API サービスで異なる Access-Control-Allow-Headers を設定する必要があります。詳細は APM と RUM の連携 を参照してください。 |
traceId128Bit |
Boolean | いいえ | false |
128 ビットの traceID を生成するかどうか。traceType に対応。現在は zipkin、jaeger をサポート。 |
allowedTracingUrls |
Array | いいえ | [] |
Trace Header の注入を許可する完全なリクエスト URL のマッチングリスト。文字列は URL プレフィックスでマッチング。正規表現と関数は完全な URL を受け取ります。オブジェクトは { match, traceType } を使用して、単一ルールに伝播タイプを指定します。バージョン要件は 2.2.22 以上。 |
allowedTracingOrigins |
Array | いいえ | 非推奨の互換設定。リクエスト Origin のみでマッチング。新規プロジェクトでは allowedTracingUrls を使用してください。両方が設定されている場合、allowedTracingUrls が優先されます。 |
|
allowTraceHeaderWithoutSession |
Boolean | いいえ | false |
現在の Session がサンプリングにヒットしない場合でも、allowedTracingUrls にヒットしたリクエストに Trace Header を注入するかどうか。有効にしても、その Session の RUM データが強制的にサンプリングまたはアップロードされることはありません。 |
isIntakeUrl |
Function | いいえ | function(url) {return false} |
リクエストリソース URL に基づいて、対応するリソースデータを収集するかどうかをカスタムメソッドで判断します。デフォルトではすべて収集。戻り値：false は収集する、true は収集しない。❗️ 1. このパラメータメソッドの戻り値は Boolean 型である必要があります。そうでない場合は無効なパラメータとみなされます。 2. バージョン要件は 2.1.13 以上。 |
Trace Header URL マッチング¶
allowedTracingUrls は完全なリクエスト URL を使用してマッチングします。String は URL プレフィックスでマッチング、RegExp と Function は完全な URL を受け取ります。単一ルールで異なる伝播タイプが必要な場合は、{ match, traceType } を使用できます。
allowedTracingUrls: [
'https://api.example.com/v1/',
/https:\/\/.*\.my-api-domain\.com\/v2\//,
function (url) {
return url.indexOf('https://internal.example.com/') === 0
},
{ match: 'https://otel.example.com/', traceType: 'w3c_traceparent' },
]
リモート設定で配信する場合、JSON で表現可能な String または { match: String, traceType } のみ使用できます。RegExp と Function は配信できません。allowedTracingOrigins は古い設定との互換性のためだけに使用されます。両方のパラメータが存在する場合、SDK は allowedTracingUrls のみを使用します。
ページパフォーマンスと白画面候補¶
@cloudcare/rum-uniapp 2.2.21 以上では、ページライフサイクル、プラットフォームの Performance entry、setData の所要時間を収集します。すべての所要時間フィールドは Guance にアップロードされる際にナノ秒（ns）に統一されます。
SDK はスクリーンショットを収集せず、スケルトン画面後のビジネスコンテンツが利用可能かどうかを確認することもできません。そのため、指標はパフォーマンス異常や白画面候補の識別にのみ使用でき、単独でページの視覚的な白画面を証明することはできません。
プラットフォーム能力とライフサイクル¶
| フィールド | 型 | 説明 |
|---|---|---|
performance_supported |
Boolean | 現在のプラットフォームの Performance Observer が正常にサブスクライブされたかどうか |
first_render_supported |
Boolean | 現在のプラットフォームに SDK が利用可能な初回レンダリングシグナルが存在するかどうか |
view_start_reason |
String | page_load、page_show、または session_renewal |
view_end_reason |
String | onHide、onUnload、または session_renewal |
ready_reached |
Boolean | 現在のページライフサイクルが onReady に到達したかどうか |
first_render_reached |
Boolean | 現在のページがプラットフォームの初回レンダリングシグナルを受信したかどうか |
ended_before_ready |
Boolean | page_load View の終了時にまだ onReady に到達していないかどうか |
ended_before_render |
Boolean | 初回レンダリングシグナルがサポートされている場合、page_load View が初回レンダリング前に終了したかどうか |
view_is_active |
Boolean | View がまだアクティブ状態かどうか |
ended_before_render は first_render_supported=true の場合にのみ統計的な意味を持ちます。Session の更新は RUM View を分割するだけで、ページの再読み込みを意味しないため、ページの早期終了の結論は生成されません。
レンダリングと setData の指標¶
| フィールド | 説明 |
|---|---|
loading_time |
ページの navigation とライフサイクルで観測された最大読み込み所要時間 |
page_ready_time |
View 開始から onReady までの所要時間 |
first_render_time |
WeChat の firstRender.duration；抖音の場合は first-paint - navigationStart |
page_fp |
現在のページの navigationStart からの FP の所要時間 |
page_fcp |
現在のページの navigationStart からの FCP の所要時間 |
page_lcp |
現在のページの最新の LCP の navigationStart からの所要時間 |
view_setdata_count |
有効な setData 更新のサンプル数 |
view_setdata_duration |
すべての有効な更新の累計所要時間 |
view_setdata_max_duration |
単一更新の最大所要時間 |
view_setdata_pending_duration |
キューに入ってから更新開始までの累計待機所要時間 |
view_setdata_update_duration |
更新開始から終了までの累計実行所要時間 |
view_setdata_merged_count |
プラットフォームによってマージ処理された更新回数 |
SDK は、route、pageId、最新の navigationStart に基づいてプラットフォーム entry をページインスタンスに割り当てます。これにより、高速ページ切り替え、同一ルートの再構築、遅延コールバックによるページ間の汚染を防ぎます。非表示ページ、アンロードされたページ、または古いコンポーネントの遅延 setData コールバックは現在の View に計上されません。
推奨統計口径¶
白画面候補の統計では、まず view_start_reason=page_load、performance_supported=true、first_render_supported=true をフィルタリングし、次に以下の指標を観察します。
| 問題 | 推奨条件 | 説明 |
|---|---|---|
| 初回レンダリングが遅い | first_render_time がビジネス閾値を超える |
P75、P95、および閾値超過の割合を統計 |
| 終了前に初回レンダリングなし | ended_before_render=true |
信頼度の高い白画面候補。ただし、ユーザーが素早く戻る操作をした場合もヒットする可能性あり |
| 長時間 Ready にならない | page_ready_time がビジネス閾値を超える |
ライフサイクルまたは初期化のブロッキングを示す。視覚的な白画面と同等ではない |
| 終了前に Ready にならない | ended_before_ready=true |
view_end_reason と滞在時間を組み合わせて、素早い離脱を除外 |
| FCP/LCP が遅い | page_fcp または page_lcp がビジネス閾値を超える |
コンテンツの出現および主要コンテンツの安定速度を観察するために使用 |
起動段階では、action_type=launch_attempt もアップロードされ、ネイティブの launch entry のカバレッジを計算するために使用されます。プラットフォームの Performance entry がないことは、所要時間がゼロまたは白画面の証拠にはなりません。
プラットフォームのパフォーマンス口径については、WeChat ミニプログラム PerformanceEntry、WeChat ミニプログラム setData パフォーマンス、抖音ミニプログラム createObserver、抖音ミニプログラム PerformanceEntry を参照してください。
注意：
datakitOriginに対応する DataKit のドメインは、ミニアプリ管理画面で request ホワイトリストに追加する必要があります。- 現在、各プラットフォームのミニアプリでは、パフォーマンスデータ API の公開が完全に統一されていないため、一部のパフォーマンスデータ（例：
ミニアプリ起動、ミニアプリパッケージダウンロード、スクリプト注入など）は、WeChat プラットフォーム以外では欠落する可能性があります。 - 現在、各プラットフォームのミニアプリのリクエストリソース API
uni.request、uni.downloadFileの戻りデータ内のprofileフィールドは、WeChat ミニプログラムの iOS システムでのみサポートされていません。そのため、収集されるリソース情報のうち timing 関連のデータが完全に収集されない可能性があります。現時点では解決策はありません：request、downloadFile、API サポート状況。 trackInteractionsユーザー行動収集を有効にすると、WeChat ミニプログラムの制限により、コントロールのコンテンツや構造データを収集できません。そのため、ミニプログラム SDK では宣言的プログラミングを採用しています。テンプレート内でdata-name属性を設定することで、インタラクション要素に名前を付けることができ、後続の統計で操作記録を特定しやすくなります。例：