JavaScript

::: 팁

구현하기 전에 데이터 전송 준비를 확인해주세요.

JavaScript SDK 실행 환경인 브라우저는 IE 8 이하 버전을 지원하지 않습니다.

JavaScript SDK의 크기는 약 35 KB입니다.

:::

최신 버전: v2.0.0 다운로드 (opens new window)

업데이트 시간: 2023-11-08

소스 코드: Source Code (opens new window)

1. SDK 구현

1.1 자동 구현

npm install thinkingdata-browser --save

SDK 초기 설정:

import thinkingdata from "thinkingdata-browser";
var config = {
    appId: "APP_ID",
    serverUrl: "https://YOUR_SERVER_URL",
    autoTrack: {
     pageShow: true, //page display event, event name ta_page_show
     pageHide: true, //page hide event, event name ta_page_hide
    }
};
thinkingdata.init(config);

1.2 수동 액세스

1. JavaScript SDK (opens new window)를 다운로드

압축을 풀면 2가지 스크립트가 포함되어 있으며, 실제 필요에 따라 선택해주세요.

아래 설명된 비동기 로드에는 thinkingdata.min.js가 사용됩니다.

동기 로드에는 thinkingdata.umd.min.js가 사용됩니다.

1. JavaScript SDK를 로드

비동기 로드 또는 동기 로드 방법으로 SDK를 사용할 수 있습니다.

실제 사용상 특별한 차이는 없으며, 선택에 따라 결정해주세요.

SDK 초기 설정에서는 다음과 같은 파라미터를 설정할 필요가 있습니다

• APPID: 프로젝트의 APPID, TE 프로젝트 관리 화면에서 획득 가능
• SERVER_URL: 데이터 전송 주소
  • SaaS의 경우 프로젝트 관리 → 데이터 전송 주소에서 확인해주세요
  • 프라이빗 서버 구축의 경우, 데이터 전송 주소를 지정할 수 있습니다.
    

비동기 로드에 대해서는, thinkingdata.min.js를 사용해주세요.

다음 코드를 html의 에 입력하거나, 그 외 초기 설정 코드 중에서, 아래 설정 파라미터를 입력해주세요.

<!--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 assigned by the system
        name: 'ta', //The global call variable name can be set arbitrarily, and subsequent calls can use this name
        sdkUrl:'./thinkingdata.min.js', //script address
        serverUrl:'https://YOUR_SERVER_URL', //URL for data upload
        autoTrack: {
           pageShow: true, //page display event, event name ta_page_show
           pageHide: true, //page hide event, event name ta_page_hide
        }，
        loaded: function(te) {
           // var currentId = te.getDistinctId();
           // te.identify(currentId);
           // te.quick('autoTrack');
        }
    });
</script>
<!--Thinking Analytics SDK END-->

비동기 로드의 특정 파라미터 설명:

• name은 글로벌 호출 파라미터 이름입니다.
• sdkUrl은 SDK의 URL로, 설정이 필요합니다.
• loaded는 초기 설정의 콜백 함수로, 코드 조각을 사용한 로드는 비동기 로드이기 때문에, 반환 값을 가진 메소드가 정상적으로 호출되지 않거나, SDK의 로드가 완료되기 전에 트리거된 트랙에서 예외가 발생할 수 있습니다. 파라미터에 loaded 프로퍼티를 제공합니다. loaded의 콜백 함수는 초기화가 완료된 후, 데이터가 보고되기 전에 호출됩니다. 예를 들어, 여기에 유저 ID가 설정되어 있는 경우, SDK가 로드되기 전에 생성된 데이터는 위의 유저ID에 설정됩니다.

동기 로드의 경우 thinkingdata.umd.min.js를 사용하여, 초기 설정 코드 내에서 아래의 설정 파라미터를 입력해주세요.

<!--Thinking Analytics SDK BEGIN-->
<script src="./thinkingdata.umd.min.js"></script>
<script>
// Create an SDK configuration object
var config = {
    appId: 'APP_ID',
    serverUrl: 'https://YOUR_SERVER_URL',
    autoTrack: {
     pageShow: true, //page display event, event name ta_page_show
     pageHide: true, //page hide event, event name ta_page_hide
    }
};
//Assign the SDK instance to the global variable ta, or other variables you specify
window.te = thinkingdata;
//Initialize the SDK with a configuration object
te.init(config);
</script>
<!--Thinking Analytics SDK END-->

2. 주요 기능

주요 기능을 사용하기 전에, 유저 식별 규칙을 확인해 주세요.

SDK는 게스트 ID를 자동으로 생성하고, 로컬에 저장됩니다; 유저가 로그인하기 전에, 게스트 ID를 신분 식별 ID로 사용됩니다.

주의: 게스트 ID는 유저가 앱을 재설치할 때 리셋됩니다.

2.1 계정ID 설정

유저가 로그인할 때, login을 호출하여 유저의 계정ID를 설정할 수 있습니다. TE 플랫폼은 계정ID를 식별 ID로 로그아웃을 호출할 때까지 유지합니다. login을 여러 번 호출하면 이전의 계정ID는 덮어씌워집니다.

// The login unique identifier of the user, corresponding to the #account_id in data tracking. #Account_id now is TE
ta.login("TE");

이 방법은 로그인 이벤트를 보내지 않습니다.

2.2 공통 이벤트 속성 설정

공통 이벤트 속성은 모든 이벤트에 포함되는 속성입니다. setSuperProperties를 호출하여 설정할 수 있습니다. 이벤트를 보내기 전에, 공통 이벤트 속성을 설정해두세요.

예: 플레이어의 레벨, 전투력, 소유 자원 등의 속성

var superProperties = {};
superProperties["channel"] = "te";//string
superProperties["age"] = 1;//number
superProperties["isSuccess"] = true;//boolean
superProperties["birthday"] = new Date();//time
superProperties["object"] = {key:"value"};//object
superProperties["object_arr"] = [{key:"value"}];//array object
superProperties["arr"] = ["value"];//array
te.setSuperProperties(superProperties);//set super properties

공통 이벤트 속성은 캐시에 저장되며, 페이지를 접속할 때마다 호출할 필요가 없습니다. 호출할 경우 setSuperProperties: 이전에 설정한 공통 이벤트 속성은 덮어씌워집니다.

• Key는 해당 속성의 이름으로, 문자열 타입이며, 영문자와 숫자, "_"를 포함하며, 최대 50자입니다. TE 시스템은 일괄적으로 소문자로 통일됩니다.
• Value는 해당 속성의 값으로, String, Number, Boolean, Time, object, array, list object를 지원합니다.

이벤트 속성, 유저 속성은 공통 이벤트 속성과 일치해야 합니다.

2.3 이벤트 전송

track을 호출하여 이벤트를 전송합니다. 데이터 플랜을 미리 준비한 후, 전송해주세요. 다음은 모델 코드입니다.

예: 아이템 구매

ta.track(
"product_buy", //event name
 //event property
 {product_name:"tv"});

이벤트 이름은 문자열 타입으로, 영문자와 숫자, "_"를 포함하여 최대 50자까지 입력 가능합니다.

Array 타입은 v 1.3.0 이상의 버전에서 지원됩니다.
Object 타입은 TE 플랫폼 3.5 이상의 버전에서 지원됩니다.

2.4 유저 속성 설정

일반적인 유저 속성은 userSet을 사용하여 설정할 수 있으며, userSet은 원래의 값을 덮어씁니다. 해당 속성에 값이 없는 경우에는 속성이 새로 생성됩니다. 다음은 코드 예시입니다.

//the username now is TA
ta.userSet({ username: "TA" });
//the username now is TE
ta.userSet({ username: "TE" });

3. 코드 예시 (Example Code)

아래의 코드 예시에 모든 작업이 포함되어 있으며, 아래 순서대로 사용하는 것을 권장합니다:

import thinkingdata from "thinkingdata-browser";
var config = {
    appId: "APP_ID",
    serverUrl: "https://YOUR_SERVER_URL/sync_js",
    autoTrack: {
     pageShow: true, //page display event, event name ta_page_show
     pageHide: true, //page hide event, event name ta_page_hide
    }
};

//Initialize the SDK
thinkingdata.init(config);

//if the user has logged in, the account ID of the user could be set as the unique identifier 
ta.login("TA");

//set super properties
var superProperties = {};
superProperties["channel"] = "ta";//string
superProperties["age"] = 1;//number
superProperties["isSuccess"] = true;//boolean
superProperties["birthday"] = new Date();//time
superProperties["object"] = {key:"value"};//object
superProperties["object_arr"] = [{key:"value"}];//array object
superProperties["arr"] = ["value"];//array
ta.setSuperProperties(superProperties);

//upload events
ta.track("product_buy", //event name
 //event property
 {product_name:"tv"});
 
//Set user properties
ta.userSet({username: "TA" });