JavaScript-Advanced

1. 유저 ID 설정

SDK 인스턴스는 랜덤한 값으로 유저의 게스트 ID를 부여합니다. 게스트 ID는 유저가 로그인하기 전의 유저 식별 ID로 사용됩니다. 하지만 주의해야 할 점은, 계정 ID는 유저가 재설치할 때 변경됩니다.

1.1 게스트 ID 설정

::: 팁 일반적으로, 게스트 ID를 수동으로 설정할 필요는 없으며, 유저 식별 규칙을 확인한 후 게스트ID 설정을 진행해야 합니다. 게스트ID를 변경하고 싶은 경우는, SDK 초기 설정 후 바로 호출하도록 설정해야 합니다. :::

te.identify("Thinker");

현재 게스트 ID를 얻고 싶다면, getDistinctId를 호출하여 얻을 수 있습니다.

//Return distinct ID
var distinctId = te.getDistinctId();

1.2 계정 ID 설정

유저 로그인 시, Login을 호출하여 계정ID를 설정할 수 있습니다. TE는 계정ID를 유저 신분의 식별ID로 사용합니다. 한 번 설정된 계정ID는 Logout을 호출하기 전까지 저장됩니다. Login을 여러 번 호출하면, 그 이전의 계정ID는 덮어씌워집니다.

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

이 방법은 로그인 이벤트로 전송되지 않습니다.

1.3 계정 ID 초기화

유저가 로그아웃 이벤트를 실행하기 전에, Logout을 호출하여 계정ID를 클리어할 수 있습니다. 다시 Login을 호출하기 전까지 게스트ID는 유저 신분의 식별ID로 사용됩니다.

te.logout();

유저가 계정을 삭제할 때 Logout을 호출하도록 설정해야 합니다.

로그아웃 이벤트로 전송되지 않습니다.

2. 이벤트 전송

SDK가 초기화 설정을 완료한 후, 데이터 트래킹 정책에 따라 트래킹 코드를 구현하고 유저의 행동 데이터를 수집할 수 있습니다. 일반적으로, 기본 이벤트 전송은 충분히 수집 가능하며, 실제 업무 상황에 따라 처음이나 업데이트 가능 등의 특수 이벤트를 수집할 수도 있습니다.

2.1 기본 이벤트

track을 호출하여 데이터 수집 계획에 따라 이벤트의 속성을 설정한 위에, 데이터 전송할 수 있습니다.

예: 아이템 구매

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

2.2 첫 이벤트

첫 이벤트는 어떤 디바이스 혹은 다른 분석 대상의 ID마다, 처음 한 번만 기록되는 이벤트입니다.

예를 들어: 어떤 디바이스의 활성화 이벤트는 그 디바이스를 최초로 사용할 때 유용합니다.

te.trackFirstEvent({
  eventName: "device_activation",
  properties: { key:"valeu" }
});

디바이스 외에 첫 이벤트를 판단하고 싶다면, first_check_id를 사용하여 첫 이벤트를 정의해주세요.

//set the user ID as the first_check_id of the first event to track the first initialization event of the user.
te.trackFirstEvent({
  eventName: "account_activation",
  firstCheckId: "TE",
  properties: { key: "value"}
});

주의: 서버 측에서 첫 번째 이벤트인지 확인하기 위해, 첫 이벤트는 기본적으로 1시간 지연하여 저장됩니다.

2.3 갱신 가능 이벤트

일반적으로 이벤트는 데이터가 저장되면 갱신할 수 없게 되지만, 데이터 갱신을 하고 싶을 경우에는 갱신 가능 이벤트를 사용해 주세요. 갱신 가능 이벤트는 식별 이벤트의 ID가 필요하며, 생성 시에는 속성에 입력해 주세요. TE시스템은 이벤트 이름과 이벤트 ID를 식별 대상으로 하여 갱신 데이터를 확정합니다.

//이벤트 속성 status가 보고 후 3이며, 가격은 100입니다
te.trackUpdate({
  eventName: "UPDATABLE_EVENT",
  properties: { status: 3, price: 100 },
  eventId: "test_event_id"
});

//이벤트 속성 status가 보고 후 5이며, 가격은 동일하게 유지됩니다
te.trackUpdate({
  eventName: "UPDATABLE_EVENT",
  properties: { status: 5 },
  eventId: "test_event_id"
});

2.4 덮어쓰기 이벤트

덮어쓰기 이벤트는 갱신 가능 이벤트와 비슷하며, 덮어쓰기 이벤트는 과거 데이터를 최신 데이터로 덮어쓰기 때문에 이전 데이터를 삭제하고 새로운 데이터를 저장하는 것처럼 보입니다. TE 시스템은 이벤트 이름과 이벤트 ID를 식별 대상으로 하여 갱신 데이터를 확정합니다.

//보고 후 이벤트 속성 상태는 3이며, 가격은 100입니다
te.trackOverwrite({
  eventName: "OVERWRITE_EVENT",
  properties: { status: 3, price: 100 },
  eventId: "test_event_id"
});


//보고 후 이벤트 속성 상태는 5이며, 가격은 동일합니다
te.trackOverwrite({
  eventName: "OVERWRITE_EVENT",
  properties: { status: 5 },
  eventId: "test_event_id"
});

2.5 공통 이벤트 속성

데이터 수집 과정에서, 많은 이벤트가 공통적인 필드를 가집니다. 이 경우, 매번 track 전송 시 동일한 설정을 하는 것은 비효율적이므로, 공통 이벤트 속성 설정을 권장합니다.

공통 이벤트 속성을 설정하기 전에, 세 가지 유형의 공통 이벤트 속성이 있으니, 필요에 따라 선택하세요:

• 정적 공통 속성: 모든 페이지에서 유효하며, 우선 순위가 가장 낮습니다. 캐시가 유효한 경우, localStorage 또는 cookie에 저장됩니다. 고정값만 설정할 수 있습니다.
• 페이지 공통 속성: 현재 보고 있는 페이지에서만 유효하며, 우선 순위가 가장 높습니다. SDK를 재설정하는 경우, 페이지 공통 속성은 초기화됩니다. 고정값만 설정할 수 있습니다.
• 동적 공통 속성: 현재 보고 있는 페이지에서만 유효하며, 페이지 공통 속성 다음으로 우선 순위가 있습니다. SDK를 재설정한 후에는 다시 설정해야 합니다. 동적 값 설정이 가능합니다.

2.5.1 정적 공통 속성

중요 속성에 대해서는: 유저의 채널, 닉네임, ID 등 모든 이벤트에 포함시키고 싶은 경우, setSuperProperties를 사용하여 정적 공통 이벤트 속성을 설정하세요. 정적 공통 이벤트 속성은 전역에서 유효하며, 캐시는 localStorage또는 cookie에 저장됩니다(기본적으로 캐시가 활성화됨).

정적 공통 속성의 파라미터는 JSON이며, 이벤트 속성과 일치해야 합니다.

// set super properties
ta.setSuperProperties({ channel: "channel", user_name: "nsername" });

속성 설정 외에도, 다른 API를 사용하여 정적 공통 이벤트 속성을 설정할 수 있습니다.

//obtain all certain super properties
var superProperties = ta.getSuperProperties();
// clear a certain super property
te.unsetSuperProperty("channel");
// clear all certain super properties
te.clearSuperProperties();

2.5.2 페이지 공통 속성 설정

페이지 내의 정적 속성에 대해서는: 페이지의 이름이나 URL 같이 해당 페이지에서 트리거된 모든 이벤트에 이러한 속성을 포함시키고 싶은 경우, 페이지 공통 속성을 설정하세요. setPageProperty를 사용하여 설정한 공통 속성은 해당 페이지에서만 유효합니다.

//Set the page ID as a public property of the page, and all events triggered in this page will have the following properties
te.setPageProperty({ page_id: "page10001" });

해당 페이지의 페이지 공통 속성을 얻고 싶다면 getPageProperty로 가능합니다.

//Get the page public properties of the current page
var pageProperty = te.getPageProperty();

2.5.3 페이지 동적 공통 속성 설정

setDynamicSuperProperties를 통해 동적 공통 속성의 콜백 함수를 설정합니다. SDK는 이벤트 데이터 전송 시 콜백 함수를 트리거하고, 반환된 JSON을 이벤트 속성에 기록합니다. setDynamicSuperProperties의 파라미터는 하나의 함수이며, 이 함수는 JSON을 반환 값으로 설정해야 합니다.

te.setDynamicSuperProperties(function() {
  var d = new Date();
  d.setHours(10);
  return { date: d };
});

2.6 이벤트 시간 기록

이벤트의 경과 시간을 기록하고 싶을 경우, timeEvent를 호출하여 계산할 수 있습니다. 계산하고 싶은 이벤트 이름을 설정하고, 해당 이벤트가 전송될 때, 자동으로 이벤트 속성에 #duration 속성이 추가되며, 경과 시간이 기록됩니다. 단위는 초입니다.

//The following instance has recorded the time the user spent on a certain product page
ta.timeEvent("stay_shop");
/**do someting
    .......
**/
//the timing would end when the user leaves the product page. "stay_shop" event would carry#duration, a property representing event duration. 
ta.track("stay_shop",{product_name:"product_name"});

2.7 배치 전송

SDK 버전 1.6.1 이상에서는 데이터의 배치 전송을 지원하게 되었습니다.

var config = {
    appId: '2f2d8810817c4cbfb7c38aeb8466615a',
    serverUrl: 'https://receiver-ta-preview.thinkingdata.cn',
    send_method: 'ajax',
    batch:true
    batch: {
        size: 5,
        interval: 5000,
        storageLimit:200
    },
};

• batch: 배치 전송을 활성화할지 여부, 선택적으로 기본값은 false입니다.
• size: 배치 전송 데이터의 최대값, 기본값은 5이며, 최소값은 1, 최대값은 30입니다.
• interval: 전송 시간 간격, 기본값은 6000입니다.
• storageLimit: 로컬에서 최대 캐시 데이터 수, 기본값은 200개입니다.

주의:

1. 배치 전송과 콜백 기능을 동시에 사용할 수 없습니다. 예를 들어, track이 콜백으로 추가된 경우, 배치 전송을 사용한 후 콜백은 실행되지 않습니다.
2. 배치 전송은 기본적으로 ajax 방식으로 데이터를 전송합니다.
3. localStorage에 200개 이상의 데이터가 저장되어 있는 경우, 배치 전송은 실패하지 않습니다. 200개의 데이터만 localStorage에 저장되고, 새로 생성된 데이터는 구성 메소드를 사용하여 전송됩니다. 대책으로는 매번 20개의 데이터를 삭제하고, 이 20개의 데이터에 동시에 데이터를 전송합니다.
4. app_js_bridge와 batch_send 중 하나만 선택할 수 있습니다.
5. localstorage를 스토리지로 사용합니다.
6. debug 또는 debugOnly는 직접 데이터 전송입니다.

3. 유저 속성

TE에서 유저 속성을 설정하는 API는 userSet, userSetOnce, userAdd, userUnset, userDelete, userAppend, userUniqAppend입니다.

3.1 userSet

일반적으로 유저 속성 설정은 userSet을 사용하여 설정할 수 있습니다. 이 호출을 사용하여 기존 속성 값이 변경됩니다. 기존 속성 값이 없는 경우 새로 생성됩니다. 데이터 타입은 저장된 데이터 타입과 일치합니다.

예를 들어:

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

3.2 userSetOnce

만약 유저 속성이 한 번 설정된 후 변경되지 않는다면, userSetOnce를 사용하여 설정할 수 있습니다. 이 호출은 값이 있을 때 변경을 수행하지 않습니다. 예: 첫 결제 시간 설정

//first_payment_time is 2018-01-01 01:23:45.678
te.userSetOnce({first_payment_time: "2018-01-01 01:23:45.678" });
//first_payment_time is still 2018-01-01 01:23:45.678
te.userSetOnce({first_payment_time: "2018-12-31 01:23:45.678" });

3.3 userAdd

만약 숫자 타입의 속성에 대해 누적 계산을 하고자 한다면, userAdd를 사용하여 설정할 수 있습니다. 이 호출은 값이 없을 때 자동으로 0을 부여한 후 계산됩니다. "-"값으로 계산하는 것도 가능합니다. 예: 누적 결제 금액

//in this case, the total_revenue is 30
te.userAdd({ total_revenue: 30 });
//in this case, the total_revenue is 678
te.userAdd({ total_revenue: 648 });

3.4 userUnset

유저 속성을 리셋하고 싶다면, UserUnset을 사용하여 설정할 수 있습니다. 이 속성이 클러스터 내에서 생성되지 않았다면, UserUnset은 그 속성을 생성하지 않습니다

// reset properties of a single user
te.userUnset("userPropertykey");

3.5 userDel

유저를 삭제하고 싶을 때 userDel을 사용할 수 있습니다. 유저를 삭제하면 해당 유저의 유저 속성은 조회할 수 없게 되지만, 해당 유저가 생성한 이벤트 데이터는 조회할 수 있습니다.

ta.userDelete();

3.6 userAppend

UserAppend를 사용하여 List 타입의 유저 속성에 추가할 수 있습니다.

ta.userAppend({ user_list: ["apple", "ball"] });

3.7 userUniqAppend

v1.6.0 이상에서는 userUniqAppend를 사용하여 Array (List) 타입의 유저 데이터에 고유 요소를 추가할 수 있습니다. userUniqAppend 인터페이스는 추가된 유저 속성에서 중복을 제거하며, userAppend는 중복을 제거하지 않기 때문에 유저 속성이 중복될 가능성이 있습니다.

//이 경우, 유저 목록의 속성 값은 ["apple"，"ball"]입니다
te.userAppend({ user_list: ["apple", "ball"] });
//in this case, the property value of user_list is ["apple","apple","ball","cube"]
te.userAppend({ user_list: ["apple", "cube"] });
//in this case, the 속성 값 of 유저 목록 is ["apple"，"ball","cube"]
te.userUniqAppend({ user_list: ["apple", "cube"] });

4. 암호화 기능

1. v1.6.0 이상에서는 데이터 전송 방식이 ajax이며, 전송 데이터의 암호화를 지원하게 되었습니다. SDK 초기 설정의 config에 암호화할 정보를 입력합니다.

데이터 암호화를 지원하기 위해서는 crypto-js와 jsencrypt를 추가해야 합니다.

var config = {
    appId: "xxx",
    serverUrl: "xxx",
     secretKey: {
       //The encrypted public key can be obtained in the TA management background
       publicKey: '공개키',
       //public key version number
       version: 1
     },
};

데이터 암호화에 대응하기 위해서는, crypto-js와 jsencrypt를 추가할 필요가 있습니다.

<script src="https://cdn.bootcdn.net/ajax/libs/crypto-js/4.1.1/crypto-js.js"></script>
<script src="https://cdn.bootcss.com/jsencrypt/3.2.1/jsencrypt.js"></script>

5. 다중 도메인 연계

1.6.1 버전 이상에서는 다중 도메인 협업이 가능해집니다. 두 개 이상의 다른 도메인 URL의 유저 행동을 통합함으로써 유저의 전환 흐름을 분석할 수 있습니다.

ta.quick('siteLinker', {
    linker: [
        { part_url: 'thinkingdata.cn', after_hash: true }，
        { part_url: 'example.com', after_hash: true }
    ]
})

part_url: 설정된 part_url 문자열은 URL을 열기 위한 URL의 부분 문자열이어야 합니다.

열고자 하는 도메인 구성:	configuration	a 태그 href 주소	결과를 통해 얻을 수 있는 라벨
thinkingdata.cn	{ part_url: 'thinkingdata.cn', after_hash: false }	https://thinkingdata.cn/	https://thinkingdata.cn/?_tasdk='d'+distinctID

after_hash: 필수 속성이며, 속성 값은 Boolean 타입, 즉 true 또는 false여야 합니다. URL의 해시 부분(즉, # 이후 부분) 또는 URL의 검색 부분(즉, # 이전 ? 부분)에 _tasdk 매개변수를 구성합니다.

url	after_hash	result
https://thinkingdata.cn	false	https://thinkingdata.cn?_tasdk=distinctID
	true	https://thinkingdata.cn#?_tasdk=distinctID
https://thinkingdata.cn#index	false	https://thinkingdata.cn?_tasdk=distinctID#index
	true	https://thinkingdata.cn#index?_tasdk=distinctID
https://thinkingdata.cn?a=1#index	false	https://thinkingdata.cn?a=1&_tasdk=distinctID#index
	true	https://thinkingdata.cn?a=1#index?_tasdk=distinctID
https://thinkingdata.cn?a=1#index?b=2	false	https://thinkingdata.cn?a=1&_tasdk=distinctID#index?b=2
	true	https://thinkingdata.cn?a=1#index?b=2&_tasdk=distinctID

6. 기타 기능

6.1 디바이스 ID 가져오기

getDeviceId를 사용하여 디바이스 ID를 얻을 수 있습니다.

var deviceId = ta.getDeviceId();

6.2 기본 시간대 구성

기본적으로 SDK는 본 디바이스의 표시 시간을 이벤트 발생 시간으로 전송합니다. 기본 시간대를 지정할 수도 있습니다.

var config = {
    appId: "xxx",
    serverUrl: "xxx",
    zoneOffset:8
};

시간대를 지정하면, 본 디바이스의 시간대 데이터가 폐기됩니다. 만약 본 디바이스의 시간대를 유지하고 싶다면, 별도의 이벤트에 커스텀 속성을 추가해주세요.