본문으로 건너뛰기

미니 프로그램&미니 게임

최근 업데이트 2026. 10. 05.
팁

연동하기 전에 먼저 연동 전 준비를 읽어 주십시오.

게임 엔진으로 미니 게임을 개발하는 경우 자주 사용하는 게임 엔진의 통합 계획을 참고하십시오: Egret Engine, LayaAir, CocosCreator.

최신 버전: v3.8.1 다운로드(미니 프로그램) 다운로드(미니 게임)

업데이트 시간: 2026-09-29

리소스 다운로드: 소스 코드

주의

이 문서는 v3.0.0 이상 버전에 적용됩니다. 과거 버전은 미니 프로그램&미니 게임 연동 가이드(V2), 미니 프로그램 SDK 다운로드(v2.2.4), 미니 게임 SDK 다운로드(v2.2.4)를 참고하십시오

미니 프로그램&미니 게임 SDK는 일반적인 미니 프로그램 플랫폼, 퀵 앱, 미니 게임 플랫폼에서 데이터 전송 기능을 구현할 수 있도록 표준 API 인터페이스를 제공합니다. 현재 지원하는 플랫폼과 해당 파일은 다음과 같습니다:

미니 프로그램:

  • 위챗 미니 프로그램: tdanalytics.wx.min.js
  • Baidu 미니 프로그램: tdanalytics.swan.min.js
  • Douyin 미니 프로그램: tdanalytics.tt.min.js
  • Alipay 미니 프로그램: tdanalytics.my.min.js
  • DingTalk 미니 프로그램: tdanalytics.dd.min.js
  • Kuaishou 미니 프로그램: tdanalytics.ks.min.js
  • 퀵 앱: tdanalytics.quick.min.js
  • QQ 미니 프로그램: tdanalytics.qq.min.js
  • JD 미니 프로그램: tdanalytics.jd.min.js
  • 360 미니 프로그램: tdanalytics.qh.min.js

미니 게임:

  • 위챗 미니 게임: tdanalytics.mg.wx.min.js
  • QQ 미니 게임: tdanalytics.mg.qq.min.js
  • Douyin 미니 게임: tdanalytics.mg.tt.min.js
  • Baidu 미니 게임: tdanalytics.mg.swan.min.js
  • Bilibili 미니 게임: tdanalytics.mg.bl.min.js
  • Huawei 퀵 게임: tdanalytics.mg.huawei.min.js
  • OPPO 퀵 게임: tdanalytics.mg.oppo.min.js
  • vivo 퀵 게임: tdanalytics.mg.vivo.min.js
  • Meizu 퀵 게임: tdanalytics.mg.mz.min.js
  • Honor 퀵 게임: tdanalytics.mg.honor.min.js
  • Xiaomi 퀵 게임: tdanalytics.mg.xiaomi.min.js
  • Taobao 미니 게임: tdanalytics.mg.tb.min.js
  • Kuaishou 미니 게임: tdanalytics.mg.ks.min.js
  • Alipay 미니 게임: tdanalytics.mg.my.min.js
  • Meituan 미니 게임: tdanalytics.mg.mt.min.js
  • JD 미니 게임: tdanalytics.mg.jd.min.js
  • H5 미니 게임
  • UC 미니 게임
  • Facebook 미니 게임

1. SDK 통합​

미니 프로그램 SDK를 다운로드한 후 app.js에서 해당 SDK 파일을 불러옵니다(위챗 미니 프로그램 예시):

var TDAnalytics = require("./tdanalytics.wx.min.js");

SDK를 불러온 후 SDK 인스턴스를 생성하여 데이터 전송을 시작할 수 있습니다:

// AE SDK 설정 객체
var config = {
  appId: "YOU-APP-ID", // 프로젝트의 APP ID
  serverUrl: "https://youserverurl.com", // 데이터 수집 주소
  autoTrack: {
    appLaunch: true, // ta_mp_launch 자동 수집
    appShow: true, // ta_mp_show 자동 수집
    appHide: true, // ta_mp_hide 자동 수집
    pageShow: true, // ta_mp_view 자동 수집
    pageShare: true // ta_mp_share 자동 수집
  }
};

// 초기화
TDAnalytics.init(config);

AE 설정 객체의 파라미터 설명은 다음과 같습니다:

  • appId: 프로젝트의 APP ID로, 필수입니다. AE 백엔드의 프로젝트 관리 페이지에서 확인할 수 있습니다

  • serverUrl: 데이터 전송 URL로, 필수입니다

    • 클라우드 서비스를 사용하는 경우 다음을 입력합니다: https://global-receiver-ta.thinkingdata.cn
    • 프라이빗 배포 버전을 사용하는 경우 운영 담당자에게 전송 주소를 확인하십시오

  • enableBatch: 데이터를 먼저 로컬에 캐시한 후 일괄 전송합니다. 기본값은 false입니다

  • autoTrack: 선택 사항으로, 자동 수집 기능 활성화 여부를 나타냅니다. 각 요소는 다음 자동 수집 이벤트를 나타내며, 기본값은 모두 비활성화입니다:

    • appLaunch: 미니 프로그램 초기화 자동 수집. 1회 사용 중 한 번만 트리거됩니다
    • appShow: 미니 프로그램 시작 또는 백그라운드에서 포그라운드 진입 자동 수집
    • appHide: 미니 프로그램의 포그라운드에서 백그라운드 진입을 자동 수집하고, 이번 방문(시작부터 백그라운드 전환까지)의 시간을 기록
    • pageShow: 미니 프로그램 페이지 표시 또는 포그라운드 전환을 자동 수집하고, 페이지 경로와 이전 경로를 기록
    • pageShare: 미니 프로그램의 전달 공유를 자동 수집하고, 전달 시의 페이지를 기록

자동 수집 이벤트에 대한 자세한 내용은 자동 수집 이벤트 섹션을 참고하십시오

주의

데이터를 전송하기 전에 WeChat Official Accounts Platform 또는 기타 플랫폼의 개발 설정에서 데이터 전송 URL을 서버 도메인의 request 목록에 추가하십시오.

2. 자주 사용하는 기능​

자주 사용하는 기능을 사용하기 전에 먼저 유저 식별 규칙을 이해하는 것을 권장합니다. SDK는 기본적으로 난수를 생성하여 게스트 ID로 사용하고, 게스트 ID를 로컬에 영구 저장합니다. 유저가 로그인하기 전에는 게스트 ID가 신원 식별 ID로 사용됩니다. 참고: 게스트 ID는 유저가 캐시를 삭제하거나 디바이스를 변경하면 바뀝니다.

2.1 계정 ID 설정​

유저가 로그인할 때 login을 호출하여 유저의 계정 ID를 설정할 수 있습니다. AE 플랫폼은 계정 ID를 신원 식별 ID로 사용하며, 설정한 계정 ID는 logout을 호출하기 전까지 계속 유지됩니다. login을 여러 번 호출하면 이전 계정 ID를 덮어씁니다

// 유저의 로그인 고유 식별자로, 전송 데이터의 #account_id에 해당합니다. 이때 #account_id의 값은 TA입니다
TDAnalytics.login("TA");

이 메서드는 로그인 이벤트를 전송하지 않습니다

2.2 공통 이벤트 속성 설정​

공통 이벤트 속성은 모든 이벤트에 포함되는 속성입니다. setSuperProperties를 호출하여 공통 이벤트 속성을 설정할 수 있으며, 이벤트를 보내기 전에 먼저 공통 이벤트 속성을 설정하는 것을 권장합니다. 유저의 회원 등급, 유입 채널 등 일부 중요한 속성은 모든 이벤트에 설정해야 하므로, 이러한 속성은 공통 이벤트 속성으로 설정할 수 있습니다.

var superProperties = {
    channel : "ta",
    age : 1,
    isSuccess : true,
    birthday :  new Date(),
    object : { key : "value" },
    object_arr : [ { key : "value" } ],
    arr : [ "value" ]
};
TDAnalytics.setSuperProperties(superProperties);

공통 이벤트 속성은 캐시에 저장되므로 시작할 때마다 호출할 필요가 없습니다. setSuperProperties를 호출하여 이전에 설정한 공통 이벤트 속성을 다시 업로드하면 이전 속성을 덮어씁니다.

  • Key는 해당 속성의 이름으로 문자열 타입입니다. 영문자로 시작해야 하며 숫자, 영문자, 밑줄 "_"을 포함할 수 있고, 최대 길이는 50자입니다. 대소문자를 구분하지 않으며 AE에서 모두 소문자로 변환합니다
  • Value는 해당 속성의 값으로 문자열, 숫자, 불리언, 시간, 객체, 객체 그룹, 배열을 지원합니다

이벤트 속성과 유저 속성의 요구 사항은 공통 이벤트 속성과 같습니다

2.3 이벤트 전송​

track을 호출하여 이벤트를 전송할 수 있습니다. 앞서 정리한 트래킹 문서에 따라 이벤트 속성과 정보 전송 조건을 설정하는 것을 권장합니다. 여기서는 유저가 어떤 상품을 구매하는 경우를 예로 듭니다.

TDAnalytics.track({
    eventName: "product_buy", // 이벤트 이름
    properties: {
        product_name: "상품명"
    } //이벤트 속성
});

이벤트 이름은 문자열 타입이며, 영문자로 시작해야 하고 숫자, 영문자, 밑줄 "_"을 포함할 수 있으며, 최대 길이는 50자입니다.

2.4 유저 속성 설정​

일반적인 유저 속성은 userSet을 호출하여 설정할 수 있습니다. 이 인터페이스로 전송한 속성은 원래 속성 값을 덮어쓰며, 이전에 해당 유저 속성이 없었다면 새로 생성하고 타입은 전달된 속성의 타입과 같습니다. 여기서는 사용자 이름 설정을 예로 듭니다:

//이때 username은 TA
TDAnalytics.userSet({
    properties: {
        username: "TA"
    }
});
//이때 username은 AE
TDAnalytics.userSet({
    properties: {
        username: "AE"
    }
});

3. 모범 사례​

다음 예시 코드에는 위의 모든 작업이 포함되어 있으며, 다음 단계에 따라 사용하는 것을 권장합니다

SDK를 불러온 후 SDK 인스턴스를 생성하여 데이터 전송을 시작할 수 있습니다:

var TDAnalytics = require("./tdanalytics.wx.min.js");
var config = {
  appId: "YOU-APP-ID", // 프로젝트의 APP ID
  serverUrl: "https://youserverurl.com", // 데이터 전송 주소
  autoTrack: {
    appLaunch: true, // ta_mp_launch 자동 수집
    appShow: true, // ta_mp_show 자동 수집
    appHide: true, // ta_mp_hide 자동 수집
    pageShow: true, // ta_mp_view 자동 수집
    pageShare: true // ta_mp_share 자동 수집
  }
};
// 초기화
TDAnalytics.init(config);
// 유저의 로그인 고유 식별자로, 전송 데이터의 #account_id에 해당합니다. 이때 #account_id의 값은 TA입니다
TDAnalytics.login("TA");
//공통 이벤트 속성 설정
var superProperties = {
    channel : "ta", //문자열
    age : 1,//숫자
    isSuccess : true,//불리언
    birthday :  new Date(),//시간
    object : { key : "value" },//객체
    object_arr : [ { key : "value" } ],//객체 그룹
    arr : [ "value" ]//배열
};
TDAnalytics.setSuperProperties(superProperties);
//이벤트 전송
TDAnalytics.track({
    eventName: "product_buy", // 이벤트 이름
    properties: {
        product_name: "상품명"
    } //이벤트 속성
});
//유저 속성 설정
TDAnalytics.userSet({
    properties: { 
        username: "AE" 
    }
});
이 문서가 도움이 되었나요?
이 페이지의 내용