콘텐츠로 이동

Uniapp 개발 프레임워크 기반 미니프로그램 연동

업데이트 로그

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 수집기에 필요한 header를 주입할 모든 요청 목록입니다. 요청의 origin 또는 정규식일 수 있습니다.

전제 조건

애플리케이션 연동

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 도메인 주소. 위챗 미니프로그램 관리 백엔드에서 도메인 화이트리스트에 추가해야 함
  applicationId: '<애플리케이션 ID>', // 필수, dataflux 플랫폼에서 생성된 애플리케이션 ID
  env: 'testing', // 선택 사항, 미니프로그램 환경
  version: '1.0.0', // 선택 사항, 미니프로그램 버전
  service: 'miniapp', // 현재 애플리케이션의 서비스 이름
  trackInteractions: true, // 사용자 행동 데이터
  sampleRate: 100, // 메트릭 데이터 수집 비율, 100은 전체 수집, 0은 수집 안 함
  allowedTracingOrigins: ['https://api.example.com',/https:\/\/.*\.my-api-domain\.com/],  // 선택 사항, trace 수집기에 필요한 header를 주입할 모든 요청 목록. 요청의 origin 또는 정규식일 수 있음
})
//#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 도메인 주소. 위챗 미니프로그램 관리 백엔드에서 도메인 화이트리스트에 추가해야 함
  applicationId: '<애플리케이션 ID>', // 필수, dataflux 플랫폼에서 생성된 애플리케이션 ID
  env: 'testing', // 선택 사항, 미니프로그램 환경
  version: '1.0.0', // 선택 사항, 미니프로그램 버전
  service: 'miniapp', // 현재 애플리케이션의 서비스 이름
  trackInteractions: true, // 사용자 행동 데이터
  sampleRate: 100, // 메트릭 데이터 수집 비율, 100은 전체 수집, 0은 수집 안 함
  allowedTracingOrigins: ['https://api.example.com',/https:\/\/.*\.my-api-domain\.com/],  // 선택 사항, trace 수집기에 필요한 header를 주입할 모든 요청 목록. 요청의 origin 또는 정규식일 수 있음
})
//#endif
....

CDN

파일을 다운로드하여 로컬에서 임포트(다운로드 주소)

...
import Vue from 'vue'
//#ifndef H5 || APP-PLUS || APP-NVUE || APP-PLUS-NVUE
const { datafluxRum } = require('./dataflux-rum-miniapp.js'); // js 파일 로컬 경로
// RUM 초기화
datafluxRum.init(Vue, {
  datakitOrigin: '<DATAKIT ORIGIN>',// 필수, Datakit 도메인 주소. 위챗 미니프로그램 관리 백엔드에서 도메인 화이트리스트에 추가해야 함
  applicationId: '<애플리케이션 ID>', // 필수, dataflux 플랫폼에서 생성된 애플리케이션 ID
  env: 'testing', // 선택 사항, 미니프로그램 환경
  version: '1.0.0', // 선택 사항, 미니프로그램 버전
  service: 'miniapp', // 현재 애플리케이션의 서비스 이름
  trackInteractions: true, // 사용자 행동 데이터
  sampleRate: 100, // 메트릭 데이터 수집 비율, 100은 전체 수집, 0은 수집 안 함
  allowedTracingOrigins: ['https://api.example.com',/https:\/\/.*\.my-api-domain\.com/],  // 선택 사항, trace 수집기에 필요한 header를 주입할 모든 요청 목록. 요청의 origin 또는 정규식일 수 있음
})
//#endif
....

파일을 다운로드하여 로컬에서 임포트(다운로드 주소)

...
//#ifndef H5 || APP-PLUS || APP-NVUE || APP-PLUS-NVUE
import { datafluxRum } from './dataflux-rum-miniapp.js'; // js 파일 로컬 경로
// RUM 초기화
datafluxRum.initVue3({
  datakitOrigin: '<DATAKIT ORIGIN>',// 필수, Datakit 도메인 주소. 위챗 미니프로그램 관리 백엔드에서 도메인 화이트리스트에 추가해야 함
  applicationId: '<애플리케이션 ID>', // 필수, dataflux 플랫폼에서 생성된 애플리케이션 ID
  env: 'testing', // 선택 사항, 미니프로그램 환경
  version: '1.0.0', // 선택 사항, 미니프로그램 버전
  service: 'miniapp', // 현재 애플리케이션의 서비스 이름
  trackInteractions: true, // 사용자 행동 데이터
  sampleRate: 100, // 메트릭 데이터 수집 비율, 100은 전체 수집, 0은 수집 안 함
  allowedTracingOrigins: ['https://api.example.com',/https:\/\/.*\.my-api-domain\.com/],  // 선택 사항, trace 수집기에 필요한 header를 주입할 모든 요청 목록. 요청의 origin 또는 정규식일 수 있음
})
//#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 유형을 지원합니다.
allowedTracingOrigins Array 아니요 [] ddtrace 수집기에 필요한 header를 주입할 모든 요청 목록입니다. 요청의 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.13 이상이어야 합니다.

참고：

  1. datakitOrigin에 해당하는 DataKit 도메인은 미니프로그램 관리 백엔드에서 request 화이트리스트에 추가해야 합니다.
  2. 현재 각 플랫폼의 미니프로그램은 성능 데이터 API 노출이 완전히 통일되지 않아 일부 성능 데이터를 완벽하게 수집하지 못할 수 있습니다. 예를 들어 미니프로그램 시작, 미니프로그램 패키지 다운로드, 스크립트 주입 등 일부 데이터는 위챗 플랫폼을 제외하면 누락될 가능성이 있습니다.
  3. 현재 각 플랫폼 미니프로그램의 요청 리소스 API uni.request, uni.downloadFile 반환 데이터의 profile 필드는 현재 위챗 미니프로그램의 iOS 시스템만 반환을 지원하지 않아 수집된 리소스 정보 중 timing 관련 데이터가 완전히 수집되지 않을 수 있습니다. 현재 해결 방법은 없습니다：request, downloadFile, API 지원 상황.
  4. trackInteractions 사용자 행동 수집을 활성화하면 위챗 미니프로그램의 제한으로 인해 컨트롤의 콘텐츠와 구조 데이터를 수집할 수 없습니다. 따라서 미니프로그램 SDK에서는 선언형 프로그래밍을 채택하여 템플릿에서 data-name 속성을 설정함으로써 상호작용 요소에 이름을 추가할 수 있어 이후 통계에서 조작 기록을 쉽게 식별할 수 있습니다. 예시：
 <button bindtap="bindSetData" data-name="setData">setData</button>

문서 평가

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