콘텐츠로 이동

미니프로그램 애플리케이션 연동

SDK 파일을 도입하여 미니프로그램 애플리케이션의 성능 지표, 오류 로그 및 리소스 요청 데이터를 수집하고 Guance 플랫폼에 보고하여 시각화된 방식으로 미니프로그램 애플리케이션의 성능을 분석합니다.

사전 조건(DataKit 연동)

연동 시작하기

  1. RUM > 새 애플리케이션 > 미니프로그램으로 이동합니다.
  2. 애플리케이션 이름을 입력합니다.
  3. 애플리케이션 ID를 입력합니다.

  4. 애플리케이션 연동 방식을 선택합니다.

  5. 공용 DataWay: RUM 데이터를 직접 수신하며 DataKit 수집기를 설치할 필요가 없습니다.

  6. 로컬 환경 배포: 사전 조건을 충족한 후 RUM 데이터를 수신합니다.

연동 방식

  1. DataKit이 설치되어 공개 네트워크에서 접근 가능하게 구성되고 IP 지리 정보 데이터베이스가 설치되어 있는지 확인합니다.
  2. 콘솔에서 applicationId, env, version 등의 매개변수를 가져와 애플리케이션 연동을 시작합니다.
  3. SDK를 통합할 때 datakitOrigin을 DataKit의 도메인 또는 IP로 설정합니다.
  1. 콘솔에서 applicationId, clientToken, site 등의 매개변수를 가져와 애플리케이션 연동을 시작합니다.
  2. SDK 통합 시 datakitOrigin을 구성할 필요가 없으며 데이터는 기본적으로 공용 DataWay로 전송됩니다.

사용 방법

미니프로그램의 app.js 파일에 다음과 같이 코드를 도입합니다.

참고: 도입 위치는 App() 초기화 이전이어야 합니다.

NPM 패키지 도입 방식은 WeChat 공식 npm 도입 방식을 참조하세요.

const { datafluxRum } = require('@cloudcare/rum-miniapp')
// RUM 초기화
datafluxRum.init({
  datakitOrigin: '<DATAKIT ORIGIN>',// 필수, Datakit 도메인 주소는 WeChat 미니프로그램 관리 백엔드에서 도메인 화이트리스트에 추가해야 함
  site: "http://172.16.212.186:9529", // 공용 DataWay 해당 사이트의 도메인
  clientToken: "a993f53a8ea04bc6b9350e5e670a3a3b", // 공용 DataWay 보고에 필요한 클라이언트 토큰, Guance 콘솔에서 애플리케이션 생성 시 생성됨
  applicationId: '<애플리케이션 ID>', // 필수, dataflux 플랫폼에서 생성된 애플리케이션 ID
  env: 'testing', // 선택 사항, 미니프로그램 환경
  version: '1.0.0', // 선택 사항, 미니프로그램 버전
  service: 'miniapp', // 현재 애플리케이션의 서비스 이름
  trackInteractions: true,
  traceType: 'ddtrace', // 선택 사항, 기본값 ddtrace, 현재 ddtrace, zipkin, skywalking_v3, jaeger, zipkin_single_header, w3c_traceparent 6가지 유형 지원
  allowedTracingOrigins: ['https://api.example.com',/https:\/\/.*\.my-api-domain\.com/],  // 선택 사항, trace 수집기에 필요한 헤더를 삽입할 모든 요청 목록입니다. 요청의 origin 또는 정규식일 수 있음
  allowTraceHeaderWithoutSession: true, // Session이 샘플링되지 않아도 Trace Header를 계속 삽입하며, 이로 인해 RUM 데이터가 보고되지 않음
})

파일 다운로드 로컬 방식으로 도입

const { datafluxRum } = require('./lib/dataflux-rum-miniapp.js')
// RUM 초기화
datafluxRum.init({
  datakitOrigin: '<DATAKIT ORIGIN>',// 필수, Datakit 도메인 주소는 WeChat 미니프로그램 관리 백엔드에서 도메인 화이트리스트에 추가해야 함
  site: "http://172.16.212.186:9529", // 공용 DataWay 해당 사이트의 도메인
  clientToken: "a993f53a8ea04bc6b9350e5e670a3a3b", // 공용 DataWay 보고에 필요한 클라이언트 토큰, Guance 콘솔에서 애플리케이션 생성 시 생성됨
  applicationId: '<애플리케이션 ID>', // 필수, dataflux 플랫폼에서 생성된 애플리케이션 ID
  env: 'testing', // 선택 사항, 미니프로그램 환경
  version: '1.0.0', // 선택 사항, 미니프로그램 버전
  service: 'miniapp', // 현재 애플리케이션의 서비스 이름
  trackInteractions: true,
  traceType: 'ddtrace', // 선택 사항, 기본값 ddtrace, 현재 ddtrace, zipkin, skywalking_v3, jaeger, zipkin_single_header, w3c_traceparent 6가지 유형 지원
  allowedTracingOrigins: ['https://api.example.com',/https:\/\/.*\.my-api-domain\.com/],  // 선택 사항, trace 수집기에 필요한 헤더를 삽입할 모든 요청 목록입니다. 요청의 origin 또는 정규식일 수 있음
  allowTraceHeaderWithoutSession: true, // Session이 샘플링되지 않아도 Trace Header를 계속 삽입하며, 이로 인해 RUM 데이터가 보고되지 않음
})

구성

초기화 매개변수

매개변수 유형 필수 여부 기본값 설명
applicationId String 예 Guance에서 생성한 애플리케이션 ID입니다.
datakitOrigin String 예 DataKit 데이터 보고 Origin입니다.
❗️ 미니프로그램 관리 백엔드에서 request 화이트리스트에 추가해야 합니다.
site String 예(공용 DataWay 보고 방식 필수) 공용 DataWay 해당 사이트의 도메인입니다. 참고: 프로토콜(// 포함), 도메인(또는 IP 주소)[및 포트 번호] 예: https://www.dataway.com, http://100.20.34.3:8088
clientToken String 예 (공용 DataWay 필수) 공용 DataWay 보고에 필요한 클라이언트 토큰으로, Guance 콘솔에서 애플리케이션 생성 시 생성됩니다.
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 traceID를 128바이트 방식으로 생성할지 여부입니다. traceType에 해당하며 현재 zipkin, jaeger 유형을 지원합니다.
allowedTracingOrigins Array 아니요 [] [신규] ddtrace 수집기에 필요한 헤더를 삽입할 모든 요청 목록입니다. 요청의 origin 또는 정규식일 수 있습니다. origin: 프로토콜(// 포함), 도메인(또는 IP 주소)[및 포트 번호]. _예: ["https://api.example.com", /https:\\/\\/._\\.my-api-domain\\.com/]*
allowTraceHeaderWithoutSession Boolean 아니요 false 현재 Session이 샘플링에 포함되지 않은 경우에도 allowedTracingOrigins에 해당하는 요청에 Trace Header를 계속 삽입할지 여부입니다. 활성화해도 해당 Session의 RUM 데이터가 강제로 샘플링되거나 보고되지 않습니다.
isIntakeUrl Function 아니요 function(url) {return false} 요청 리소스 URL을 기반으로 해당 리소스 데이터를 수집할지 여부를 결정하는 사용자 정의 메서드입니다. 기본적으로 모두 수집합니다. 반환값: false는 수집, true는 수집하지 않음을 의미합니다.
❗️
1. 이 매개변수 메서드의 반환 결과는 반드시 Boolean 유형이어야 합니다. 그렇지 않으면 유효하지 않은 매개변수로 간주됩니다.
2. 버전 요구 사항은 2.1.10 이상입니다.

샘플링되지 않은 Session의 Trace Header

allowTraceHeaderWithoutSession의 기본값은 false입니다. true로 설정하면 현재 Session이 RUM 샘플링에 포함되지 않은 경우에도 SDK는 allowedTracingOrigins에 해당하는 요청에 Trace Header를 계속 삽입합니다. 이 구성은 강제로 샘플링하거나 새 Session을 생성하지 않으며, 샘플링되지 않은 Session의 View, Action, Resource, Error 등의 RUM 데이터를 보고하지 않습니다.

참고 사항

  1. datakitOrigin에 해당하는 DataKit 도메인은 미니프로그램 관리 백엔드에서 request 화이트리스트에 추가해야 합니다.
  2. 현재 WeChat 미니프로그램 요청 리소스 API wx.request, wx.downloadFile 반환 데이터의 profile 필드는 iOS 시스템에서 반환을 지원하지 않으므로 수집된 리소스 정보에서 timing 관련 데이터가 완전히 수집되지 않을 수 있습니다. 현재 해결 방법은 없습니다: request, downloadFile, API 지원 현황.
  3. trackInteractions 사용자 행동 수집을 활성화하면 WeChat 미니프로그램의 제한으로 인해 컨트롤의 내용 및 구조 데이터를 수집할 수 없습니다. 따라서 미니프로그램 SDK에서는 선언형 프로그래밍 방식을 채택하여 wxml 파일에 data-name 속성을 설정하여 상호작용 요소에 이름을 추가하고 추후 통계에서 작업 기록을 쉽게 식별할 수 있도록 합니다. 예:
<button bindtap="bindSetData" data-name="setData">
  setData
</button>

문서 평가

이 페이지가 도움이 되었나요?