미니프로그램 애플리케이션 연동¶
SDK를 도입하여 WeChat 미니프로그램 애플리케이션의 성능 메트릭, 오류 로그 및 리소스 요청 데이터를 수집하고 Guance로 전송하여 애플리케이션 성능을 시각화하여 분석합니다.
미니프로그램 애플리케이션 생성¶
- 「실제 사용자 모니터링(RUM) > 애플리케이션 목록」으로 이동하여 「애플리케이션 생성」을 클릭하고 애플리케이션 유형에서 「미니프로그램」을 선택합니다.
- 「애플리케이션 정의」에서 애플리케이션 이름과 애플리케이션 ID를 입력하고 애플리케이션을 생성합니다. 콘솔에서 이 애플리케이션의 Client Token이 생성됩니다.
- 생성에 성공하면 「연동 방식 선택」에서 Agent 자동 연동 또는 수동 연동을 선택한 후 「연동 설정」에 따라 설정을 완료합니다. 기존 미니프로그램 애플리케이션은 해당 설정 페이지로 이동하여 연동을 계속할 수 있습니다.
미니프로그램 애플리케이션은 이 페이지의 미니프로그램 SDK를 사용해야 합니다. Web 애플리케이션과 동일한 비즈니스 코드를 사용하더라도 실제 애플리케이션 유형에 따라 각각 연동해야 합니다.
연동 방식 선택¶
| 연동 방식 | 사용 사례 | 작업 경로 |
|---|---|---|
| Agent 자동 연동 | 코딩 어시스턴트가 미니프로그램 프로젝트를 분석하고 프로젝트 상황에 맞게 SDK 연동을 계획하고 완료하기를 원하는 경우 | 콘솔에서 생성된 Agent 프롬프트를 복사하여 미니프로그램 코드 저장소에서 실행 |
| 수동 연동 | SDK를 직접 도입하고 전송 파라미터를 설정하려는 경우 | 퍼블릭 DataWay 또는 로컬 환경 배포를 선택한 후 이 페이지의 예시에 따라 코드를 수정 |
Agent 자동 연동¶
- 미니프로그램 애플리케이션 설정 페이지에서 「Agent 자동 연동」을 선택합니다.
- 「연동 설정」에 있는 전체 프롬프트를 복사한 후, 미니프로그램 코드 저장소에서 코딩 어시스턴트를 열고 붙여넣습니다. 프롬프트는 현재 미니프로그램 애플리케이션에서 가져온 것이어야 하며, 해당 애플리케이션의 ID를 사용해야 합니다.
- Agent의 연동 안내에 따라 설정을 완료한 후 연동 검증에 따라 미니프로그램 데이터 전송 및 저장을 확인합니다.
페이지에서 개인 API Key 또는 임시 인증 코드가 준비되지 않았다고 표시되면 안내에 따라 개인 API Key를 생성하거나, 관리자에게 권한 활성화를 요청하거나, 정보를 보완한 후 프롬프트를 다시 복사합니다.
수동 연동¶
일반적으로는 「퍼블릭 DataWay 사용」을 우선 선택하며, DataKit을 직접 배포할 필요가 없습니다. 데이터 수신 엔드포인트를 직접 관리해야 하거나 현재 워크스페이스에서 퍼블릭 DataWay 주소를 제공하지 않는 경우에는 「로컬 환경 배포」를 선택할 수 있습니다.
| 데이터 전송 방식 | 사전 조건 | 초기화 파라미터 |
|---|---|---|
| 퍼블릭 DataWay 사용 | 현재 애플리케이션의 연동 설정에서 퍼블릭 DataWay 주소와 Client Token을 가져옵니다 | applicationId, site, clientToken |
| 로컬 환경 배포 | DataKit을 직접 설치하고 RUM 수집기를 활성화하며, 미니프로그램이 해당 전송 주소에 액세스할 수 있어야 합니다 | applicationId, datakitOrigin |
NPM과 CDN은 SDK 도입 방식이며, 퍼블릭 DataWay 또는 로컬 DataKit으로 전송하는 것과는 별개의 선택 사항입니다.
퍼블릭 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 도입 방식을 하나 선택한 후, 선택한 데이터 전송 방식에 따라 초기화합니다. SDK는 app.js에서 App() 호출 전에 초기화해야 하며, 한 번만 초기화해야 합니다.
SDK 도입¶
WeChat 공식 npm 도입 안내에 따라 종속성을 준비한 후 app.js에서 가져옵니다:
SDK 파일 다운로드 링크에서 SDK 파일을 다운로드하여 미니프로그램 프로젝트에 넣습니다(예: lib/dataflux-rum-miniapp.js). 그런 다음 app.js에서 가져옵니다:
콘솔의 「CDN」 방식은 먼저 파일을 프로젝트에 다운로드한 후 로컬 경로로 가져와야 합니다.
SDK 초기화¶
다음 두 가지 설정 중 하나만 선택합니다. 퍼블릭 DataWay는 site와 clientToken을 사용하고, 로컬 환경 배포는 datakitOrigin을 사용합니다. 동일한 초기화 설정에 두 세트의 전송 파라미터를 동시에 입력하지 않습니다.
자리 표시자를 현재 애플리케이션의 실제 설정으로 바꿉니다. 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의 쿼리 문자열 수집 여부입니다. 쿼리 문자열에 토큰 또는 사용자 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 |
현재 Session이 샘플링 대상으로 선택되지 않은 경우에도 allowedTracingUrls에 일치하는 요청에 Trace Header를 주입할지 여부입니다. 활성화해도 해당 Session을 강제로 샘플링하거나 해당 Session의 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만 사용합니다.
샘플링되지 않은 Session의 Trace Header¶
allowTraceHeaderWithoutSession의 기본값은 false입니다. true로 설정하면 현재 Session이 RUM 샘플링 대상으로 선택되지 않았더라도 SDK는 allowedTracingUrls에 일치하는 요청에 Trace Header를 계속 주입합니다. 이 설정은 강제로 샘플링하거나 새 Session을 생성하지 않으며, 샘플링되지 않은 Session의 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 속성을 설정하여 상호작용 요소에 이름을 추가할 수 있습니다. 이를 통해 이후 통계에서 작업 기록을 쉽게 찾을 수 있습니다. 예: