고급 가이드
1. 유저 ID 설정
SDK 인스턴스는 기본적으로 난수를 각 유저의 기본 게스트 ID로 사용하며, 이 ID는 유저가 로그인하지 않은 상태에서 신원을 식별하는 ID로 사용됩니다. 게스트 ID는 유저가 캐시를 삭제하거나 디바이스를 변경하면 바뀐다는 점에 유의하십시오.
1.1 게스트 ID 설정
일반적으로 게스트 ID를 직접 정의할 필요는 없습니다. 유저 식별 규칙을 충분히 이해한 후 게스트 ID를 설정하십시오.
ta.setDistinctId("Thinker");
게스트 ID를 가져오려면 getDistinctId를 호출합니다:
//게스트 ID 반환
var distinctId = ta.getDistinctId();
1.2 계정 ID 설정
유저가 로그인할 때 login을 호출하여 유저의 계정 ID를 설정할 수 있습니다. AE 플랫폼은 계정 ID를 신원 식별 ID로 사용하며, 설정한 계정 ID는 logout을 호출하기 전까지 계속 유지됩니다. login을 여러 번 호출하면 이전 계정 ID를 덮어씁니다.
// 유저의 로그인 고유 식별자. 이 데이터는 전송 데이터의 #account_id에 해당하며, 이때 #account_id의 값은 TA
ta.login("TA");
이 메서드는 로그인 이벤트를 전송하지 않습니다
1.3 계정 ID 지우기
유저가 로그아웃한 후 logout을 호출하여 계정 ID를 지울 수 있습니다. 다음에 login을 호출하기 전까지는 게스트 ID가 신원 식별 ID로 사용됩니다.
ta.logout();
로그아웃 작업 시 logout을 호출하는 것이 좋습니다. 예를 들어 유저가 계정에서 로그아웃하는 행동을 했을 때만 호출하고, 앱을 닫을 때는 호출할 필요가 없습니다.
이 메서드는 로그아웃 이벤트를 전송하지 않습니다
2. 이벤트 전송
SDK 초기화가 완료되면 데이터 트래킹을 진행하여 유저의 행동 정보를 수집할 수 있습니다. 일반적으로 일반 이벤트로 비즈니스 시나리오의 요구 사항을 충족할 수 있으며, 실제 비즈니스 시나리오에 따라 최초 이벤트, 업데이트 가능 이벤트 등을 사용할 수도 있습니다.
2.1 일반 이벤트
track을 호출하여 이벤트를 전송할 수 있습니다. 앞서 정리한 문서에 따라 이벤트 속성과 이벤트 전송 조건을 설정하는 것을 권장합니다. 여기서는 유저가 어떤 상품을 구매하는 경우를 예로 듭니다:
ta.track(
"product_buy", //이벤트 이름
{ product_name: "상품"} //이벤트 속성
);
2.2 최초 이벤트
최초 이벤트는 특정 디바이스 또는 기타 차원의 ID에 대해 한 번만 기록되는 이벤트입니다. 예를 들어 어떤 시나리오에서 특정 디바이스의 활성화 이벤트를 기록하려는 경우 최초 이벤트로 데이터를 전송할 수 있습니다
ta.trackFirst({
eventName: "device_activation",
properties: { key:"value" }
});
디바이스 이외의 다른 차원으로 최초 여부를 판단하려면 최초 이벤트에 first_check_id를 직접 지정할 수 있습니다.
// 유저 ID를 최초 이벤트의 FIRST_CHECK_ID로 설정하여 유저의 최초 활성화 이벤트 수집
ta.trackFirst({
eventName: "account_activation",
firstCheckId: "TA",
properties: { key: "value"}
});
주의: 최초 여부 검증은 서버 측에서 이루어지므로 최초 이벤트는 기본적으로 1시간 지연되어 저장됩니다.
2.3 업데이트 가능 이벤트
업데이트 가능 이벤트를 사용하면 특정 시나리오에서 이벤트 데이터를 수정해야 하는 요구를 충족할 수 있습니다. 업데이트 가능 이벤트는 해당 이벤트를 식별하는 ID를 지정해야 하며, 업데이트 가능 이벤트 객체를 생성할 때 전달합니다. AE 백엔드는 이벤트 이름과 이벤트 ID를 기준으로 업데이트할 데이터를 결정합니다.
// 예시: 업데이트 가능한 이벤트 전송, 이벤트 이름은 UPDATABLE_EVENT라고 가정
// 전송 후 이벤트 속성 status는 3, price는 100
ta.trackUpdate({
eventName: "UPDATABLE_EVENT",
properties: { status: 3, price: 100 },
eventId: "test_event_id"
});
// 전송 후 이벤트 속성 status는 5로 업데이트되고, price는 변경되지 않음
ta.trackUpdate({
eventName: "UPDATABLE_EVENT",
properties: { status: 5 },
eventId: "test_event_id"
});
2.4 덮어쓰기 가능 이벤트
덮어쓰기 가능 이벤트는 업데이트 가능 이벤트와 비슷하지만, 최신 데이터로 과거 데이터를 완전히 덮어쓴다는 점이 다릅니다. 효과 면에서는 이전 데이터를 삭제하고 최신 데이터를 저장하는 것과 같습니다. AE 백엔드는 이벤트 이름과 이벤트 ID를 기준으로 업데이트할 데이터를 결정합니다.
// 예시: 덮어쓰기 가능한 이벤트 전송, 이벤트 이름은 OVERWRITE_EVENT라고 가정
// 전송 후 이벤트 속성 status는 3, price는 100
ta.trackOverwrite({
eventName: "OVERWRITE_EVENT",
properties: { status: 3, price: 100 },
eventId: "test_event_id"
});
// 전송 후 이벤트 속성 status는 5로 업데이트되고, price 속성은 삭제됨
ta.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 객체이며, 형식 요구 사항은 이벤트 속성과 같습니다.
// 공통 이벤트 속성 설정. 모든 데이터 이벤트에 이 속성들이 포함됨
ta.setSuperProperties({ channel: "채널명", user_name: "사용자 이름" });
속성 설정 외에도 정적 공통 이벤트 속성을 다루는 다른 API를 제공하여 일상적인 비즈니스 요구를 충족합니다.
// 정적 공통 이벤트 속성 가져오기
var superProperties = ta.getSuperProperties();
// 정적 공통 이벤트 속성 하나 지우기(예: 이전에 설정한 'channel' 속성을 지우면 이후 데이터에는 해당 속성이 포함되지 않음)
ta.unsetSuperProperty("channel");
// 모든 정적 공통 이벤트 속성 지우기
ta.clearSuperProperties();
2.5.2 페이지 공통 속성 설정
페이지 이름이나 주소처럼 일부 페이지의 정적 속성은 해당 페이지에서 트리거되는 모든 이벤트에 추가하고 싶을 수 있습니다. 이처럼 페이지의 모든 이벤트에 적용해야 하는 정적 속성은 setPageProperty로 설정할 수 있습니다. setPageProperty로 설정한 공통 속성은 현재 페이지에서만 유효하다는 점에 유의하십시오
// 페이지 ID를 페이지 공통 속성으로 설정. 이 페이지에서 트리거되는 모든 이벤트에 다음 속성이 포함됨
ta.setPageProperty({ page_id: "page10001" });
현재 페이지의 페이지 공통 속성을 가져오려면 getPageProperty를 호출합니다
// 현재 페이지의 페이지 공통 속성 가져오기
var pageProperty = ta.getPageProperty();
2.5.3 페이지 동적 공통 속성 설정
setDynamicSuperProperties로 동적 공통 속성의 콜백 함수를 설정하면 SDK는 이벤트를 전송할 때 콜백 함수를 트리거하고 반환된 JSON 객체를 이벤트 속성에 추가합니다. setDynamicSuperProperties의 파라미터는 함수이며, 이 함수는 JSON 객체를 반환해야 합니다.
// 동적 공통 속성 설정. 이벤트 전송 시 콜백 함수를 트리거하고 반환된 JSON 객체를 이벤트 속성에 추가함
ta.setDynamicSuperProperties(function() {
var d = new Date();
d.setHours(10);
return { date: d };
});
2.6 이벤트 지속 시간 기록
특정 이벤트의 지속 시간을 기록하려면 timeEvent를 호출하여 시간 측정을 시작할 수 있습니다. 시간을 측정할 이벤트 이름을 설정해 두면 해당 이벤트를 전송할 때 이벤트 속성에 기록된 시간을 나타내는 #duration 속성이 자동으로 추가되며, 단위는 초입니다. 같은 이벤트 이름에 대해서는 시간 측정 작업을 하나만 진행할 수 있습니다.
//다음 예시는 유저가 특정 상품 페이지에 머문 시간을 집계함
ta.timeEvent("stay_shop");
/**do someting
.......
**/
//유저가 상품 페이지를 떠나면 타이머가 종료되며, "stay_shop" 이벤트에 이벤트 소요 시간을 나타내는 속성 #duration이 포함됨
ta.track("stay_shop",{product_name:"상품명"});
2.7 일괄 전송
데이터 일괄 전송은 SDK 버전 1.6.1 이상에서 지원합니다
var config = {
appId: '2f2d8810817c4cbfb7c38aeb8466615a',
serverUrl: 'https://receiver-ta-preview.thinkingdata.cn',
send_method: 'ajax',
//일괄 전송 활성화, 기본값은 false
batch:true
//또는
batch: {
size: 6,//데이터가 size건에 도달하면 자동으로 전송 트리거, 기본값은 6
interval: 6000,//몇 밀리초 간격으로 즉시 전송할지, 기본값은 6S
maxLimit:500//로컬에 캐시할 수 있는 최대 데이터 건수, 기본값은 500건
},
};
- batch: 데이터 일괄 전송 활성화 여부. 필수가 아니며 기본값은 false
- size: 데이터가 size건에 도달하면 자동으로 전송을 트리거합니다. 기본값은 6, 최솟값은 1, 최댓값은 30
- interval: 전송 시간 간격. 기본값은 6000
- maxLimit: 로컬에 캐시할 수 있는 최대 데이터 건수. 기본값은 500건
참고:
- 일괄 전송 기능과 콜백 함수 기능은 함께 사용할 수 없습니다. 예를 들어 track에 callback을 추가해도 일괄 전송을 사용하면 callback이 실행되지 않습니다.
- 일괄 전송은 기본적으로 ajax 방식으로 데이터를 전송합니다.
- localStorage에 캐시된 데이터 건수가 maxLimit(기본값 500건)를 초과하면 선입선출 전략에 따라 가장 오래된 데이터를 폐기합니다.
- app_js_bridge와 batch_send 중 하나만 선택할 수 있으며, 연동을 활성화하면 일괄 전송을 사용할 수 없습니다.
- localstorage를 사용하여 저장합니다.
- debug 또는 debugOnly는 데이터를 바로 전송하며, 로컬에 캐시한 후 일괄 전송하지 않습니다.
- 활성화하면 지정한 건수 또는 지정한 시간 간격을 충족해야 데이터가 전송됩니다. 페이지 이동이 잦은 경우 전송하기 전에 페이지가 닫혀 일부 데이터가 유실될 수 있으므로 신중하게 활성화하십시오.
3. 유저 속성
AE 플랫폼에서 지원하는 유저 속성 설정 API는 다음과 같습니다: userSet, userSetOnce, userAdd, userUnset, userDelete, userAppend, userUniqAppend.
3.1 userSet
일반적인 유저 속성은 userSet을 호출하여 설정할 수 있습니다. 이 인터페이스로 업로드한 속성은 원래 속성 값을 덮어쓰며, 이전에 해당 유저 속성이 없었다면 새로 생성하고 타입은 전달된 속성의 타입과 같습니다. 여기서는 사용자 이름 설정을 예로 듭니다:
// username은 TA
ta.userSet({ username: "TA" });
//username은 AE
ta.userSet({ username: "AE" });
3.2 userSetOnce
전송하려는 유저 속성을 한 번만 설정하면 되는 경우 userSetOnce를 호출하여 설정할 수 있습니다. 해당 속성에 이미 값이 있으면 이 정보는 무시됩니다. 여기서는 최초 결제 시간 설정을 예로 듭니다.
//first_payment_time은 2018-01-01 01:23:45.678
ta.userSetOnce({first_payment_time: "2018-01-01 01:23:45.678" });
//first_payment_time은 여전히 2018-01-01 01:23:45.678
ta.userSetOnce({first_payment_time: "2018-12-31 01:23:45.678" });
3.3 userAdd
숫자형 속성을 업로드할 때 userAdd를 호출하여 해당 속성을 누적할 수 있습니다. 해당 속성이 아직 설정되지 않았으면 0을 할당한 후 계산합니다. 음수를 전달하면 빼기 연산과 같습니다.
//이때 total_revenue는 30
ta.userAdd({ total_revenue: 30 });
//이때 total_revenue는 678
ta.userAdd({ total_revenue: 648 });
3.4 userUnset
유저의 유저 속성 값을 비우려면 userUnset을 호출하여 지정한 속성을 비울 수 있습니다. 해당 속성이 아직 클러스터에 생성되지 않았다면 userUnset은 해당 속성을 생성하지 않습니다
// 이 유저의 속성 이름이 userPropertykey인 유저 속성 값을 비움. 즉 NULL로 설정
ta.userUnset("userPropertykey");
3.5 userDelete
특정 유저를 삭제하려면 userDelete를 호출하여 해당 유저를 삭제할 수 있습니다. 삭제한 후에는 해당 유저의 유저 속성을 더 이상 조회할 수 없지만, 해당 유저가 발생시킨 이벤트는 여전히 조회할 수 있습니다.
ta.userDelete();
3.6 userAppend
userAppend를 호출하여 배열 타입의 유저 데이터에 요소를 추가할 수 있습니다.
ta.userAppend({ user_list: ["apple", "ball"] });
3.7 userUniqAppend
v1.6.0부터 userUniqAppend를 호출하여 Array (List) 타입의 유저 데이터에 고유한 요소를 추가할 수 있습니다. userUniqAppend 인터페이스를 호출하면 추가하는 유저 속성의 중복이 제거되며, userAppend 인터페이스는 중복을 제거하지 않으므로 유저 속성에 중복 값이 있을 수 있습니다.
//이때 user_list의 속성 값은 ["apple","ball"]
ta.userAppend({ user_list: ["apple", "ball"] });
//이때 user_list의 속성 값은 ["apple","apple","ball","cube"]
ta.userAppend({ user_list: ["apple", "cube"] });
//이때 user_list의 속성 값은 ["apple","ball","cube"]
ta.userUniqAppend({ user_list: ["apple", "cube"] });
4. 데이터 전송 암호화 지원
v1.6.0부터 데이터 전송 방식이 ajax인 경우 데이터 전송 암호화를 지원합니다. SDK 초기화 config에서 암호화 관련 정보를 설정할 수 있습니다.
var config = {
appId: "xxx",
serverUrl: "xxx",
secretKey: {
//암호화 공개 키. AE 관리 백엔드에서 가져올 수 있음
publicKey: '공개 키',
//공개 키 버전 번호
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. 다중 도메인 연동
다중 도메인 연동은 SDK 버전 1.6.1 이상에서 지원합니다. 서로 다른 두 도메인의 웹사이트에서 발생한 유저 행동을 통합할 수 있어, 관련 웹사이트 유저의 전환 과정을 더 효과적으로 관찰할 수 있습니다.
ta.quick('siteLinker', {
linker: [
{ part_url: 'thinkingdata.cn', after_hash: true }，
{ part_url: 'example.com', after_hash: true }
]
})
part_url : 설정한 part_url 문자열은 연동할 웹사이트 URL의 하위 문자열이어야 합니다.
| 연동할 도메인 | 설정 | a 태그 href 주소 | a 태그 연동 결과 |
|---|---|---|---|
| thinkingdata.cn | { part_url: 'thinkingdata.cn', after_hash: false } | https://thinkingdata.cn/ | https://thinkingdata.cn/?_tasdk='d'+distinctID |
after_hash: 필수 속성이며, 속성 값은 불리언 타입, 즉 true 또는 false여야 합니다. _tasdk 파라미터를 URL의 hash 부분(즉 # 뒤 부분)에 둘지, URL의 search 부분(즉 # 앞의 ? 부분)에 둘지를 설정합니다
6. 기타 기능
6.1 디바이스 ID 가져오기
getDeviceId를 호출하여 디바이스 ID를 가져올 수 있습니다.
var deviceId = ta.getDeviceId();
6.2 기본 시간대 설정
기본적으로 SDK는 인터페이스를 호출한 시점의 로컬 시간을 이벤트 발생 시간으로 전송합니다. 초기화 시 기본 시간대를 설정할 수도 있으며, 이렇게 하면 모든 이벤트의 이벤트 시간이 설정한 시간대에 맞춰 정렬됩니다:
var config = {
appId: "xxx",
serverUrl: "xxx",
zoneOffset:8
};
참고: 지정한 시간대로 이벤트 시간을 정렬하면 디바이스의 로컬 시간대 정보가 사라집니다. 디바이스의 로컬 시간대 정보를 유지해야 한다면 현재로서는 이벤트에 관련 속성을 직접 추가해야 합니다.
6.3 SDK의 설정 정보 가져오기 비활성화
SDK가 초기화 시 설정 정보를 가져오지 않도록 하려면 다음과 같이 제어할 수 있습니다:
var config = {
appId: "xxx",
serverUrl: "xxx",
disableRConfig:true
};
ta.init(config);
disableRConfig가 true이면 설정 정보 가져오기를 금지하고, false이면 설정 정보 가져오기를 활성화합니다