본문으로 건너뛰기

JavaScript

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

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

JavaScript SDK는 브라우저 환경에서 실행해야 하며, IE 8 이하 버전과는 아직 호환되지 않습니다.

JavaScript SDK의 크기는 약 58 KB입니다

최신 버전: v2.6.1

업데이트 시간: 2026-07-31

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

주의

이 문서는 v2.0.0 이상 버전에 적용됩니다. 과거 버전은 JS 연동 가이드(V1), SDK 다운로드(V1)를 참고하십시오

1. SDK 통합​

SDK 지원 범위:

클라이언트 프레임워크: Vue2, Vue3, React, Angular

데스크톱 프레임워크: Electron

1.1 자동 통합​

npm install thinkingdata-browser --save

"dependencies": {
    "thinkingdata-browser": "2.6.1",
},

이어서 SDK를 초기화합니다. 구체적인 설정 파라미터는 2단계를 참고하십시오.

import ta from "thinkingdata-browser";
var config = {
    appId: "APP_ID",
    serverUrl: "https://YOUR_SERVER_URL",
    autoTrack: {
     pageShow: true, //페이지 표시 이벤트 활성화, 이벤트 이름 ta_page_show
     pageHide: true, //페이지 숨김 이벤트 활성화, 이벤트 이름 ta_page_hide
     pageView: true, //단일 페이지 조회 이벤트 활성화, 이벤트 이름 ta_pageview
     pageClick:true //페이지 요소 클릭 이벤트 활성화, 이벤트 이름 ta_page_click
    }
};
ta.init(config);

1.2 수동 통합​

1단계: JavaScript SDK를 다운로드합니다

압축 파일에는 두 가지 규격의 스크립트가 들어 있으며, 필요에 따라 원하는 스크립트를 선택할 수 있습니다. 아래에서 설명하는 비동기 로드에는 thinkingdata.min.js 파일을, 동기 로드에는 thinkingdata.umd.min.js를 사용해야 합니다.

2단계: JavaScript SDK 로드

비동기 로드 또는 동기 로드 방식으로 SDK를 사용할 수 있습니다. 두 방식은 실제 사용에서 큰 차이가 없으므로 어느 쪽을 선택해도 됩니다.

SDK를 초기화할 때 몇 가지 설정 파라미터를 전달해야 합니다:

  • appId: 프로젝트의 APP_ID로, 설정해야 합니다. 프로젝트를 신청할 때 발급되며, 여기에 입력하십시오
  • serverUrl: 데이터를 업로드할 URL로, 설정해야 합니다

클라우드 서비스를 사용하는 경우 다음 URL을 입력하십시오: https://global-receiver-ta.thinkingdata.cn

프라이빗 배포 버전을 사용하는 경우 다음 URL을 입력하십시오: https://데이터 수집 주소

비동기 로드의 경우 thinkingdata.min.js를 사용하고, 다음 코드를 html의 <script> 안에 넣은 후 해당 파라미터를 설정합니다:

<!--Thinking Analytics SDK BEGIN-->
<script>
    !function (e) { if (!window.ThinkingDataAnalyticalTool) { var n = e.sdkUrl, t = e.name, r = window, a = document, i = "script", l = null, s = null; r.ThinkingDataAnalyticalTool = t; var o = ["track", "quick", "login", "identify", "logout", "trackLink", "userSet", "userSetOnce", "userAdd", "userDel", "setPageProperty", "setSuperProperties", "setDynamicSuperProperties", "clearSuperProperties", "timeEvent", "unsetSuperProperties", "initInstance", "trackFirstEvent", "trackUpdate", "trackOverwrite"]; r[t] = function (e) { return function () { if (this.name) (r[t]._q = r[t]._q || []).push([e, arguments, this.name]); else if ("initInstance" === e) { var n = arguments[0]; r[t][n] = { name: n }; for (var a = 0; a < o.length; a++)r[t][n][o[a]] = r[t].call(r[t][n], o[a]); (r[t]._q1 = r[t]._q1 || []).push([e, arguments]) } else (r[t]._q = r[t]._q || []).push([e, arguments]) } }; for (var u = 0; u < o.length; u++)r[t][o[u]] = r[t].call(null, o[u]); r[t].param = e, r[t].__SV = 1.1, l = a.createElement(i), s = a.getElementsByTagName(i)[0], l.async = 1, l.src = n, s.parentNode.insertBefore(l, s) } }(
    {
        appId:'APP_ID', //시스템에서 할당한 APPID
        name: 'ta', //전역 호출 변수명. 임의로 설정할 수 있으며, 이후에는 이 이름으로 호출하면 됨
        sdkUrl:'./thinkingdata.min.js', //통계 스크립트 URL
        serverUrl:'https://YOUR_SERVER_URL', //데이터 업로드 URL
        autoTrack: {
           pageShow: true, //페이지 표시 이벤트 활성화, 이벤트 이름 ta_page_show
           pageHide: true, //페이지 숨김 이벤트 활성화, 이벤트 이름 ta_page_hide
           pageView: true, //단일 페이지 조회 이벤트 활성화, 이벤트 이름 ta_pageview
           pageClick:true //페이지 요소 클릭 이벤트 활성화, 이벤트 이름 ta_page_click
        },
        loaded: function(ta) {
           // var currentId = ta.getDistinctId();
           // ta.identify(currentId);
           // ta.quick('autoTrack');
        }
    });
</script>
<!--Thinking Analytics SDK END-->

비동기 로드 전용 파라미터 설명:

  • name은 전역 호출 변수명입니다
  • sdkUrl은 sdk의 URL로, 설정해야 합니다
  • loaded는 초기화 콜백 함수입니다. 코드 스니펫으로 로드하면 비동기 로드가 되므로 반환값이 있는 메서드는 호출에 실패할 수 있고, SDK 로드가 완료되기 전에 트리거된 track은 예외가 발생합니다. 이를 위해 파라미터에 loaded 속성을 제공합니다. loaded의 콜백 함수는 초기화가 완료된 후, 데이터 전송을 시작하기 전에 호출됩니다. 예를 들어 여기에서 유저 ID를 설정하면 SDK 로드 전에 생성된 데이터에도 해당 유저 ID가 설정됩니다.

2. 자주 사용하는 기능​

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

2.1 계정 ID 설정​

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

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

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

2.2 공통 이벤트 속성 설정​

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

var superProperties = {};
superProperties["channel"] = "ta";//문자열
superProperties["age"] = 1;//숫자
superProperties["isSuccess"] = true;//불리언
superProperties["birthday"] = new Date();//시간
superProperties["object"] = {key:"value"};//객체
superProperties["object_arr"] = [{key:"value"}];//객체 그룹
superProperties["arr"] = ["value"];//배열
ta.setSuperProperties(superProperties);//공통 이벤트 속성 설정

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

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

이벤트 속성과 유저 속성의 요구 사항은 공통 이벤트 속성과 동일합니다

2.3 이벤트 전송​

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

ta.track("product_buy",{product_name:"상품명"});

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

Array 타입은 v1.3.0 이후 버전에서 지원하며, AE 플랫폼 2.5 이상 버전과 함께 사용해야 합니다.

Object 타입은 AE 플랫폼 3.5 이상 버전과 함께 사용해야 합니다

2.4 유저 속성 설정​

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

// username은 TA
ta.userSet({ username: "TA" });
//username은 AE
ta.userSet({ username: "TE" });

3. 모범 사례​

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

import ta from "thinkingdata-browser";
var config = {
    appId: "APP_ID",
    serverUrl: "https://YOUR_SERVER_URL/sync_js",
    autoTrack: {
     pageShow: true, //페이지 표시 이벤트 활성화, 이벤트 이름 ta_page_show
     pageHide: true, //페이지 숨김 이벤트 활성화, 이벤트 이름 ta_page_hide
     pageView: true, //단일 페이지 조회 이벤트 활성화, 이벤트 이름 ta_pageview
     pageClick:true //페이지 요소 클릭 이벤트 활성화, 이벤트 이름 ta_page_click
    }
};
//SDK 초기화
ta.init(config);

//유저가 로그인한 경우 유저의 계정 ID를 고유 식별자로 설정할 수 있음
ta.login("TA");

//공통 이벤트 속성 설정
var superProperties = {};
superProperties["channel"] = "ta";//문자열
superProperties["age"] = 1;//숫자
superProperties["isSuccess"] = true;//불리언
superProperties["birthday"] = new Date();//시간
superProperties["object"] = {key:"value"};//객체
superProperties["object_arr"] = [{key:"value"}];//객체 그룹
superProperties["arr"] = ["value"];//배열
ta.setSuperProperties(superProperties);//공통 이벤트 속성 설정

//이벤트 전송
ta.track("product_buy", //이벤트 이름
 //이벤트 속성
 {product_name:"상품명"});
 
//유저 속성 설정
ta.userSet({username: "TA" });
이 문서가 도움이 되었나요?
이 페이지의 내용