ミニプログラムアプリの接続¶
SDK を導入して、WeChat ミニプログラムアプリのパフォーマンス指標、エラーログ、リソースリクエストデータを収集し、Guance に送信することで、アプリのパフォーマンスを可視化して分析できます。
ミニプログラムアプリを作成する¶
- 「リアルユーザーモニタリング(RUM) > アプリ一覧」に移動し、「アプリを作成」をクリックして、アプリタイプで「ミニプログラム」を選択します。
- 「アプリの定義」でアプリ名とアプリ ID を入力し、アプリを作成します。コンソールでこのアプリの Client Token が生成されます。
- 作成後、「接続方法の選択」で Agent 自動接続または手動接続を選択し、「接続設定」に従って設定を完了します。既存のミニプログラムアプリは、その設定ページに移動して接続を続行できます。
ミニプログラムアプリでは、このページのミニプログラム SDK を使用してください。Web アプリと同じビジネスコードを使用している場合でも、実際のアプリタイプごとに個別に接続する必要があります。
接続方法の選択¶
| 接続方法 | ユースケース | 操作入口 |
|---|---|---|
| Agent 自動接続 | プログラミングアシスタントにミニプログラムプロジェクトを分析させ、プロジェクトの状況に応じて SDK 接続を計画・完了したい場合 | コンソールで生成された Agent プロンプトをコピーし、ミニプログラムのコードリポジトリで実行します |
| 手動接続 | SDK を自分で導入し、送信パラメータを設定したい場合 | パブリック DataWay またはローカル環境デプロイを選択し、このページの例に従ってコードを変更します |
Agent 自動接続¶
- ミニプログラムアプリの設定ページで「Agent 自動接続」を選択します。
- 「接続設定」の完全なプロンプトをコピーし、ミニプログラムのコードリポジトリでプログラミングアシスタントを開いて貼り付けます。プロンプトは現在のミニプログラムアプリのものであり、そのアプリの ID を使用している必要があります。
- Agent の接続ガイドに従って設定を完了し、接続の検証に従ってミニプログラムのデータ送信と取り込みを確認します。
ページに個人 API キーまたは一時認可コードが準備できていない旨が表示された場合は、案内に従って個人 API キーを生成するか、管理者に連絡して権限を有効化するか、情報を補完してからプロンプトを再コピーしてください。
手動接続¶
通常は「パブリック DataWay を使用」を優先して選択してください。DataKit を自分でデプロイする必要はありません。データ受信側を自分で管理する必要がある場合、または現在のワークスペースでパブリック DataWay アドレスが提供されていない場合は、「ローカル環境デプロイ」を選択できます。
| データ送信方法 | 前提条件 | 初期化パラメータ |
|---|---|---|
| パブリック DataWay を使用 | 現在のアプリの接続設定からパブリック DataWay アドレスと Client Token を取得します | applicationId、site、clientToken |
| ローカル環境デプロイ | DataKit を自分でインストールして RUM コレクターを有効化し、ミニプログラムからその送信先アドレスにアクセスできるようにします | applicationId、datakitOrigin |
NPM と CDN は SDK の導入方法であり、パブリック DataWay またはローカル DataKit への送信とは独立した 2 つの選択項目です。
パブリック DataWay を使用¶
- 「手動接続」で「パブリック DataWay を使用」を選択します。
- 現在のアプリの接続設定から
applicationId、site、clientTokenをコピーします。コンソールが提供する現在のサイトアドレスを使用し、コンソールのログインアドレスや他のサイトのアドレスをsiteとして使用しないでください。 siteに対応するドメインを WeChat ミニプログラム管理画面の request 合法ドメインに追加してから、SDK の統合に従ってコードを設定します。この方法では、DataKit のインストールや RUM コレクターの追加設定は不要です。
ローカル環境デプロイ¶
- DataKit をインストールし、RUM コレクターを有効化します。
- ミニプログラムが存在するネットワークから DataKit のデータ送信先アドレスにアクセスできることを確認し、必要に応じて IP 地理情報データベースをインストールして、ユーザー IP に対応する地理情報を解決します。
- 「手動接続」で「ローカル環境デプロイ」を選択し、
datakitOriginを実際の DataKit 受信アドレスに設定し、対応するドメインをミニプログラム管理画面の request 合法ドメインに追加します。 - SDK の統合のローカル環境デプロイ例に従って初期化し、
siteとclientTokenを同時に設定しないでください。
SDK の統合¶
まず SDK の導入方法を 1 つ選択し、次に選択したデータ送信方法に従って初期化します。SDK は app.js 内で App() を呼び出す前に初期化し、1 回だけ初期化する必要があります。
SDK の導入¶
WeChat 公式の npm 導入説明に従って依存関係を準備し、app.js で導入します:
SDK ファイルをダウンロードし、ミニプログラムプロジェクトに配置します(例:lib/dataflux-rum-miniapp.js)。その後、app.js で導入します:
コンソールの「CDN」方式では、まずファイルをプロジェクトにダウンロードしてから、ローカルパスを使用して導入する必要があります。
SDK の初期化¶
以下の 2 つの設定のうち 1 つだけを選択してください。パブリック DataWay では site と clientToken を使用し、ローカル環境デプロイでは datakitOrigin を使用します。同じ初期化設定に 2 セットの送信パラメータを同時に記入しないでください。
プレースホルダーを現在のアプリの実際の設定に置き換えてください。allowedTracingUrls にはトレースを関連付ける必要があるビジネス API アドレスのみを記入します。分散型トレーシングが不要な場合は削除できます。
接続の検証¶
- 選択した送信先アドレスに対応するドメインが、WeChat ミニプログラムの request 合法ドメインに追加されていることを確認します。
- ミニプログラムを開き、ページアクセス、ボタンクリック、ビジネスリクエストを発生させ、開発者ツールで成功した RUM 送信リクエストが存在し、ドメイン検証や SDK 初期化のエラーがないことを確認します。
- 「RUM > アプリ一覧」に移動し、該当するミニプログラムアプリを開いて、エクスプローラーに View、Resource、Action などのデータがあることを確認します。
- リリース前に実機でネットワーク接続とデータ送信を検証し、開発者ツールのデバッグ設定だけに依存しないようにします。
データがない場合は、まず applicationId が現在のミニプログラムアプリと一致していることを確認し、次に選択した送信方法のパラメータ、request 合法ドメイン、sampleRate を確認してください。
設定¶
初期化パラメータ¶
| パラメータ | 型 | 必須 | デフォルト値 | 説明 |
|---|---|---|---|---|
applicationId |
String | はい | Guance で作成したアプリ ID。 | |
datakitOrigin |
String | ローカル環境デプロイ時 | DataKit のデータ送信先アドレス。ローカル環境デプロイ時のみ設定します。対応するドメインをミニプログラム管理画面の request 合法ドメインに追加する必要があります。 | |
site |
String | パブリック DataWay 時 | 現在のサイトのパブリック DataWay アドレス。アプリの接続設定からコピーします。対応するドメインをミニプログラム管理画面の request 合法ドメインに追加する必要があります。 | |
clientToken |
String | パブリック DataWay 時 | パブリック DataWay 送信で使用する Client Token。コンソールでアプリを作成するときに生成されます。 | |
env |
String | いいえ | ミニプログラムアプリの現在の環境。例:prod:本番環境、gray:グレー環境、pre:プレリリース環境、common:日常環境、local:ローカル環境。 | |
version |
String | いいえ | ミニプログラムアプリのバージョン番号。 | |
service |
String | いいえ | 現在のアプリのサービス名。デフォルトは miniapp で、カスタム設定をサポートします。 |
|
sampleRate |
Number | いいえ | 100 |
メトリクスデータの収集割合:100 はすべて収集、0 は収集しないことを示します。 |
sessionSampleRate |
Number | いいえ | 100 |
sampleRate の互換エイリアスです。両方を設定した場合は sampleRate が優先されます。 |
remoteConfiguration |
Boolean | いいえ | false |
リモート設定を有効にするかどうか。SDK はまずローカル設定で起動し、その後、サポートされる設定項目を非同期で取得して適用します。 |
remoteConfigration |
Boolean | いいえ | false |
remoteConfiguration の旧スペル互換項目です。新規プロジェクトでの使用は推奨しません。 |
remoteConfigurationFetchTimeout |
Number | いいえ | 3000 |
リモート設定リクエストのタイムアウト時間(ミリ秒)。リクエストが失敗またはタイムアウトした場合は、ローカル設定を引き続き使用します。 |
trackInteractions |
Boolean | いいえ | false |
ユーザー行動収集を有効にするかどうか。 |
trackResourceQueryString |
Boolean | いいえ | false |
リクエスト URL のクエリ文字列を収集するかどうか。クエリ文字列には token やユーザー ID が含まれる可能性があるため、安全であることを確認した場合にのみ有効にしてください。 |
trackRequestErrorResponseBody |
Boolean | いいえ | false |
失敗したリクエストのレスポンスボディをエラースタックに書き込むかどうか。レスポンスボディには機密データが含まれる可能性があります。 |
requestErrorResponseLengthLimit |
Number | いいえ | 32768 |
失敗したリクエストのレスポンスボディをエラースタックに書き込む際の最大文字数。trackRequestErrorResponseBody を有効にした場合にのみ有効です。 |
trackLaunchOptions |
Boolean | いいえ | false |
ミニプログラムの起動パラメータ内の query と referrerInfo を収集するかどうか。 |
beforeSend |
Function | いいえ | データが送信キューに入る前のコールバック。イベントを変更できます。false を返すと View 以外のイベントを破棄できます。コールバックの例外はビジネス処理や SDK を中断しません。 |
|
userId / user_id |
String | いいえ | 初期化時にログインユーザー ID を設定します。初期化後に setUser({ id }) を呼び出して設定することもできます。 |
|
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.19 以上です。 |
allowedTracingOrigins |
Array |
いいえ | 非推奨の互換設定。リクエスト Origin の完全一致のみを行います。新規プロジェクトでは allowedTracingUrls を使用してください。両方を設定した場合は allowedTracingUrls が優先されます。 |
|
allowTraceHeaderWithoutSession |
Boolean | いいえ | false |
現在のセッションがサンプリング対象外の場合でも、allowedTracingUrls に一致するリクエストに Trace Header を注入するかどうか。有効にしても、そのセッションの RUM データを強制的にサンプリングまたは送信することはありません。 |
isIntakeUrl |
Function | いいえ | function(url) {return false} |
リクエストリソースの URL に基づいて、対応するリソースデータを収集する必要があるかどうかを判断するカスタムメソッド。デフォルトではすべて収集します。戻り値:false は収集する、true は収集しないことを示します。❗️ 1. このパラメータメソッドの戻り値は Boolean 型である必要があり、そうでない場合は無効なパラメータと見なされます。 2. バージョン要件は 2.1.10 以上です。 |
Trace Header URL のマッチング¶
allowedTracingUrls は完全なリクエスト 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' },
]
allowedTracingOrigins は旧設定との互換性のためにのみ使用されます。文字列と正規表現はどちらもリクエスト Origin に対してマッチします。両方のパラメータを設定した場合、SDK は allowedTracingUrls のみを使用します。
サンプリングされていないセッションの Trace Header¶
allowTraceHeaderWithoutSession のデフォルトは false です。true に設定すると、現在のセッションが RUM のサンプリング対象外であっても、SDK は allowedTracingUrls に一致するリクエストに Trace Header を注入します。この設定では、サンプリングを強制したり新しいセッションを作成したりすることはなく、サンプリングされていないセッションの View、Action、Resource、Error などの RUM データも送信しません。
注意¶
- 実際に使用する送信先アドレス(パブリック DataWay の
site、またはローカル環境デプロイのdatakitOrigin)に対応するドメインを、ミニプログラム管理画面の request 合法ドメインに追加します。 - 現在、WeChat ミニプログラムのリソースリクエスト API
wx.request、wx.downloadFileが返すデータでは、profileフィールドが iOS システムで返されないため、収集されるリソース情報のうち timing 関連データが不完全になります。現在、解決策はありません:request、downloadFile、API サポート状況。 trackInteractionsユーザー行動収集を有効にすると、WeChat ミニプログラムの制限により、コントロールの内容と構造データを収集できません。そのため、ミニプログラム SDK では宣言型プログラミングを採用しており、wxml ファイルで data-name 属性を設定することで、インタラクティブ要素に名前を追加し、後続の集計時に操作記録を特定しやすくできます。例: