Android - Advanced

1. 계정 ID 설정

SDK 인스턴스는 랜덤 UUID로 유저의 게스트 ID로 할당됩니다. 게스트 ID는 유저가 로그인하기 전의 유저 식별 ID로 사용됩니다. 하지만, 사전에 주의해야 할 것은, 계정 ID는 유저가 재설치할 경우 변경됩니다.

1.1 게스트 ID 설정

::: 팁

일반적으로, 게스트 ID를 수동 설정할 필요는 없으며, 유저 식별 규칙을 확인한 후에 게스트 ID 설정을 진행해주세요.

만약 게스트 ID를 변경하고 싶은 경우는, SDK를 초기 설정한 후 바로 호출하도록 설정해주세요.

:::

독자적으로 게스트 ID의 관리 체계가 있는 경우는, identify를 호출하여 게스트 ID를 설정해주세요.

// 구별 ID를 Thinker로 설정
instance.identify("Thinker");

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

// 구별 ID 반환
String distinctId = instance.getDistinctId();

1.2 계정 ID 설정

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

// 유저의 로그인 고유 식별자, 데이터 트래킹에서 #account_id에 해당합니다. #Account_id는 현재 TE입니다
instance.login("TE");

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

1.3 계정 ID 삭제

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

instance.logout();

유저가 계정을 삭제할 때 Logout을 호출하도록 설정해주세요.

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

2. 이벤트 전송

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

2.1 기본 이벤트

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

예: 아이템 구매

try {
    JSONObject properties = new JSONObject();
    properties.put("product_name", "아이템명");
    instance.track("product_buy",properties);
} catch (JSONException e) {
    e.printStackTrace();   
}

2.2 첫 이벤트

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

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

JSONObject properties = new JSONObject();
try {
    properties.put("key", "value");
} catch (JSONException e) {
    e.printStackTrace();
}
instance.track(new TDFirstEvent("device_activation", properties));

디바이스 외에 첫 이벤트를 판단하고 싶다면, 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.
TDFirstEvent firstEvent = new TDFirstEvent("account_activation", properties);
firstEvent.setFirstCheckId("TE");
instance.track(firstEvent);

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

2.3 갱신 가능 이벤트

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

 //이벤트 보고 후 속성 상태가 3이며, 가격은 100입니다. 
JSONObject properties = new JSONObject();
try {
    properties.put("status", 3);
    properties.put("price", 100);
} catch (JSONException e) {
    e.printStackTrace();
}
mInstance.track(new TDUpdatableEvent("UPDATABLE_EVENT", properties, "test_event_id"));

//이벤트 보고 후 속성 상태가 5이며, 가격은 변하지 않습니다.
JSONObject properties_new = new JSONObject();
try {
    properties_new.put("status", 5);
} catch (JSONException e) {
    e.printStackTrace();
}
mInstance.track(new TDUpdatableEvent("UPDATABLE_EVENT", properties_new, "test_event_id"));

2.4 덮어쓰기 이벤트

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

// 예시: 덮어쓰기 이벤트를 보고할 때 이벤트 이름이 OVERWRITE_EVENT라고 가정
// 이벤트 속성 상태가 보고 후 3이며, 가격은 100입니다
JSONObject properties = new JSONObject();
try {
    properties.put("status", 3);
    properties.put("price", 100);
} catch (JSONException e) {
    e.printStackTrace();
}
mInstance.track(new TDOverWritableEvent("OVERWRITE_EVENT", properties, "test_event_id"));

//이벤트 속성 상태가 보고 후 5이며, 가격은 삭제됩니다
JSONObject properties_new = new JSONObject();
try {
    properties_new.put("status", 5);
} catch (JSONException e) {
    e.printStackTrace();
}
mInstance.track(new TDOverWritableEvent("OVERWRITE_EVENT", properties_new, "test_event_id"));

2.5 공통 이벤트 속성

공통 이벤트 속성은 모든 이벤트 전송 시 함께 포함되는 속성입니다. 속성의 업데이트 빈도에 따라, 공통 이벤트 속성은 정적 공통 이벤트 속성과 동적 공통 이벤트 속성으로 나뉩니다.

실제 업무 요구에 따라, 공통 이벤트 속성을 설정해주세요; 일반적으로는 이벤트 전송 전에 공통 이벤트 속성을 설정하는 것이 권장됩니다.

같은 이벤트에서, 공통 이벤트 속성, 이벤트 커스텀 속성, 프리셋 속성의 Key가 같은 경우, 다음의 우선 순위로 값이 설정됩니다. 커스텀 속성 > 동적 공통 이벤트 속성 > 정적 공통 이벤트 속성 > 프리셋 속성

2.5.1 정적 공통 이벤트 속성

정적 공통 이벤트 속성은 낮은 빈도로 변경되며 모든 이벤트에 속하는 속성입니다: 예를 들어 VIP 레벨. setSuperProperties를 사용하여 정적 공통 이벤트 속성을 설정하면, SDK는 이벤트 수집 시 설정된 공통 이벤트 속성을 해당 이벤트의 속성으로 사용됩니다.

//슈퍼 속성 설정
try {
    JSONObject superProperties = new JSONObject();
    superProperties.put("vip_level",2);
    instance.setSuperProperties(superProperties);
} catch (JSONException e) {
    e.printStackTrace();
}

정적 공통 이벤트 속성은 캐시에 저장되므로, 앱을 시작할 때마다 호출할 필요가 없습니다. 만약 그 속성이 이미 존재한다면, 새로 설정하는 속성은 원래의 속성 값을 덮어씁니다; 만약 이전에 그 속성이 존재하지 않았다면, 새로운 속성으로 생성됩니다. 속성 설정 외에 API를 사용하여 정적 공통 이벤트 속성을 관리할 수 있습니다.

//특정 슈퍼 속성 삭제
instance.unsetSuperProperty("Channel");
//모든 슈퍼 속성 삭제
instance.clearSuperProperties();
//모든 슈퍼 속성 얻기
instance.getSuperProperties();

2.5.2 동적 공통 이벤트 속성

동적 공통 이벤트 속성은 높은 빈도로 변경되며 모든 이벤트에 속하는 속성입니다. (예: 코인의 수량) setDynamicSuperPropertiesTracker를 사용하여 동적 공통 이벤트 속성을 설정한 후, SDK는 이벤트 수집 시 자동으로 getDynamicSuperProperties의 속성을 가져와 이벤트에 전송됩니다.

int coin = 0;
instance.setDynamicSuperPropertiesTracker(
    new ThinkingAnalyticsSDK.DynamicSuperPropertiesTracker() {
        @Override
        public JSONObject getDynamicSuperProperties() {
            Coin++; //골드 코인 수량의 빈번한 업데이트
            try {
                dynamicSuperProperties.put("coin",coni);
            } catch (JSONException e) {
                e.printStackTrace();
            }
            return dynamicSuperProperties;
        }
    });

2.6 이벤트 시간 기록

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

주의: 하나의 이벤트에 대해서는 하나의 시간 경과 계산 작업만 설정할 수 있습니다.

// 다음 예시는 유저가 특정 제품 페이지에서 보낸 시간을 기록했습니다.
try {
    // 유저가 제품 페이지에 들어가 타이밍을 시작합니다.
    instance.timeEvent("stay_shop");
    /**do something
    .......
    **/
    // 유저가 제품 페이지를 떠날 때 타이밍이 종료됩니다. 
    // "stay_shop" 이벤트는 #duration, 이벤트 지속 시간을 나타내는 속성을 가집니다.
    instance.track("stay_shop");
} catch (JSONException e) {
    e.printStackTrace();
}

3. 유저 속성

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

3.1 userSet

일반적으로 유저 속성 설정은 userSet을 사용하여 설정할 수 있습니다. 이 호출을 사용하면 원래 속성 값이 변경됩니다. 원래 속성 값이 없는 경우 새로 만들어집니다. 데이터 타입은 저장된 데이터 타입과 일치합니다. 다음은 예시입니다:

try {
    // 유저 이름이 지금은 TA입니다.
    JSONObject properties = new JSONObject();
    properties.put("username","TA");
    instance.userSet(properties);
    // 유저 이름이 지금은 TE입니다.
    JSONObject newProperties = new JSONObject();
    newProperties.put("username","TE");
    instance.userSet(newProperties);
} catch (JSONException e) {
    e.printStackTrace();
}

3.2 userSetOnce

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

try {
    // 첫 결제 시간은 2018-01-01 01:23:45.678입니다.
    JSONObject properties = new JSONObject();
    properties.put("first_payment_time","2018-01-01 01:23:45.678");
    instance.userSetOnce(properties);
    
    // 첫 결제 시간은 여전히 2018-01-01 01:23:45.678입니다.
    JSONObject newProperties = new JSONObject();
    newProperties.put("first_payment_time","2018-12-31 01:23:45.678");
    instance.userSetOnce(newProperties); 
       
} catch (JSONException e) {
    e.printStackTrace();
}

3.3 userAdd

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

try {
    // 이 경우, 총 수익은 30입니다.
    JSONObject properties = new JSONObject();additive operation
    properties.put("total_revenue",30);
    instance.userAdd(properties);
    
    // 이 경우, 총 수익은 678입니다.
    JSONObject newProperties = new JSONObject();
    newProperties.put("total_revenue",648);
    instance.userAdd(newProperties);
} catch (JSONException e) {
    e.printStackTrace();
}

3.4 UserUnset

유저 속성을 리셋하고 싶은 경우, userUnset을 사용하여 설정할 수 있습니다. 해당 속성이 클러스터에서 생성되지 않은 경우, userUnset은 해당 속성을 생성하지 않습니다.

// 단일 유저의 속성을 리셋합니다.
instance.userUnset("key1");
// 여러 유저의 속성을 리셋합니다.
instance.userUnset("key1", "key2", "key3");

3.5 UserDelete

유저를 삭제하고 싶은 경우, UserDelete를 사용하여 설정할 수 있습니다. 삭제한 후 해당 유저의 유저 속성은 쿼리할 수 없지만, 해당 유저가 생성한 이벤트 데이터는 쿼리할 수 있습니다.

instance.userDelete();

3.6 userAppend

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

try {
    // list는 유저 속성 user_list의 값이며, JSONArray 타입입니다.
    JSONArray list = new JSONArray("[\"apple\", \"ball\"]");
    JSONObject properties = new JSONObject();
    properties.put("user_list", list);
    // userAppend를 호출하여 유저 속성 user_list에 요소를 추가합니다. 이 경우, 존재하지 않는 요소는 새로 생성됩니다.
    mInstance.userAppend(properties);
} catch (JSONException e) {
    e.printStackTrace();
}

3.7 userUniqAppend

userUniqAppend는 중복을 제외하고 유저 속성을 추가하지만, userAppend는 중복을 제외하지 않습니다.

try {
    // list는 유저 속성 user_list의 값이며, JSONArray 타입입니다.
    // 이 경우, user_list의 속성 값은 ["apple", "ball"]입니다.
    JSONArray list = new JSONArray("[\"apple\", \"ball\"]");
    JSONObject properties = new JSONObject();
    properties.put("user_list", list);
    mInstance.userAppend(properties);
    
    
    // 이 경우, user_list의 속성 값은 ["apple", "apple", "ball", "cube"]입니다.
    JSONArray list1 = new JSONArray("[\"apple\", \"cube\"]");
    JSONObject properties1 = new JSONObject();
    properties1.put("user_list", list1);
    mInstance.userAppend(properties1);
    
    // 이 경우, user_list의 속성 값은 ["apple", "ball", "cube"]입니다.
    mInstance.userUniqAppend(properties1);
    
} catch (JSONException e) {
    e.printStackTrace();
}

4. 암호화 기능

v2.8.0 이후 버전부터, SDK 데이터 전송에 AES+RSA 암호화를 지원하게 되었습니다. 데이터의 암호화 처리는 클라이언트와 서버 양쪽에서 처리됩니다. 자세한 사항은 당사 담당 직원에게 문의해 주세요.

TDConfig config = TDConfig.getInstance(mContext,TA_APP_ID,TA_SERVER_URL);
// 암호화 활성화 및 공개 키 정보 설정
config.enableEncrypt(1,"publicKey")

5. H5 페이지와의 연동

H5 페이지 데이터의 JavaScript SDK와 연동하고 싶은 경우, 초기화 WebView 설정 시 아래의 호출을 활성화해 주세요. 자세한 사항은 H5와 APP SDK의 연동을 참조해주세요.

// H5와 연결
instance.setJsBridge(webView);

6. 기타 기능

6.1 디바이스 ID 획득

getDeviceId를 호출하여 디바이스 ID를 획득할 수 있습니다.

 String deviceID = TDAnalytics.getDeviceId();// 디바이스 ID의 값은 Android ID입니다.

6.2 기본 시간대 설정

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

// TDConfig 인스턴스 획득
TDConfig config = TDConfig.getInstance(this, TA_APP_ID, TA_SERVER_URL);
// 기본 시간대로 UTC 설정
config.setDefaultTimeZone(TimeZone.getTimeZone("UTC"));
// SDK 초기화
TDAnalytics.init(config);

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

6.3 시간 교정

SDK는 기본적으로 해당 디바이스 시간을 이벤트 발생 시간으로 사용하지만, 유저가 수동으로 디바이스의 시간을 수정하는 경우 수정된 시간이 그대로 전송되어 분석에 지장을 줄 수 있습니다. 시간 교정을 사용하여 이벤트 발생 시간의 정확성을 유지할 수 있습니다. TE 시스템은 timestamp와 NTP의 두 가지 시간 교정 방법을 지원합니다.

• 서버 측에서 동기화된 현재의 timestamp를 사용하여 SDK의 시간을 교정할 수 있습니다. 이후, 모든 시간 미지정 호출(이벤트 데이터와 유저 속성 설정)은 교정된 시간을 발생 시간으로 사용합니다.

// 1585633785954는 현재 유닉스 타임 스탬프로, 단위는 도쿄 밀리초; 해당 한국 시간은 2020-03-31 13:49:45입니다
TDAnalytics.calibrateTime(1585633785954);

• NTP 서버 주소 설정으로 SDK는 NTP 서비스의 현지 시간을 획득하여 사용합니다. 기본적으로 시간 초과(3초)하여 획득할 수 없는 경우는 로컬 시간으로 전송됩니다.

// Apple Inc의 NTP 서비스를 이용한 시간 교정 사용
TDAnalytics.calibrateTimeWithNtp("time.apple.com");

1. NTP 서비스로 시간 교정을 수행할 때 불안정성이 있으므로, timestamp를 권장합니다.
2. NTP 서비스를 사용할 경우, 네트워크 환경이 좋고, 유저 디바이스가 서버 시간을 빠르게 획득할 수 있도록 유지해야 합니다.

6.4 즉시 데이터 전송

일반적으로는 일정 시간 간격으로, 또는 일정한 데이터 양을 쌓은 후 데이터 전송이 이루어지지만, 특정 이벤트 데이터를 즉시 데이터 전송하고 싶은 경우 flush를 사용하여 설정할 수 있습니다.

TDAnalytics.flush();

6.5 국가/지역 코드 획득

국가/지역 코드를 획득하고 싶은 경우, getLocalRegion을 사용하여 획득할 수 있습니다.

TDAnalytics.getLocalRegion()