콘텐츠로 이동

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

업데이트 내역

2026.8.25:

  • @cloudcare/rum-uniapp 2.2.22: allowedTracingUrls 추가, 전체 요청 URL로 매칭; allowedTracingOrigins는 하위 호환성을 위해 폐기된 구성으로 변경; Douyin 네비게이션 및 페이지 스택이 일시적으로 비어 있을 때의 페이지 귀속 문제 수정.

2026.8.20:

  • @cloudcare/rum-uniapp 2.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 또는 정규식일 수 있음.

전제 조건

애플리케이션 연동

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 페이지 네비게이션 및 라이프사이클에서 관찰된 최대 로딩 소요 시간
page_ready_time View 시작부터 onReady까지의 소요 시간
first_render_time WeChat firstRender.duration; Douyin은 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가 없다고 해서 소요 시간이 0이거나 화이트 스크린이라는 증거는 아닙니다.

플랫폼 성능 기준은 WeChat 미니프로그램 PerformanceEntry, WeChat 미니프로그램 setData 성능, Douyin 미니프로그램 createObserver 및 Douyin 미니프로그램 PerformanceEntry를 참고하세요.

참고:

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

문서 평가

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