사용자 식별자와 속성

사용자 식별자 관리

사용자 식별자는 사용자를 고유하게 식별하는 목적으로 사용합니다. 사용자 식별자의 의미와 중요성, 선택하는 기준 등에 대해서는 사용자 식별자 관리하기 문서를 참고하시기 바랍니다.

사용자 정보를 변경하는 함수(setUser, setUserId, setDeviceId, updateUserProperties, resetUser 등)는 callback이 있는 함수 사용을 권장합니다.

callback은 변경된 사용자 정보가 SDK에 반영된 이후 호출됩니다.

사용자 식별자

핵클에서 제공하는 기본 식별자

Android SDK는 디바이스의 식별자를 관리하는 기능을 포함하고 있습니다. 따라서 사용자 식별자를 별도로 전달하지 않아도 사용자를 자동으로 식별할 수 있습니다.

SDK에서 관리하는 식별자를 조회하는 방법은 다음과 같습니다.

Kotlin

// 디바이스ID 가져오기
val deviceId = hackleApp.deviceId

// 세션 ID 가져오기
val sessionId = hackleApp.sessionId

// 사용자 정보 모두 가지고 오기
val user = hackleApp.user

Java

// 디바이스ID 가져오기
String deviceId = hackleApp.getDeviceId();

// 세션 ID 가져오기
String sessionId = hackleApp.getSessionId();

// 사용자 정보 모두 가지고 오기
User user = hackleApp.getUser();

디바이스 ID 수정

핵클에서 제공하는 디바이스 ID를 사용하지 않고 직접 디바이스 ID를 주입할 수 있습니다.

Kotlin

// 디바이스 ID 변경
hackleApp.setDeviceId("CUSTOM_DEVICE_ID") {
    // 적용 완료
}

// 빌더 패턴 사용
val user = User.builder()
    .deviceId("CUSTOM_DEVICE_ID") // 디바이스 ID
    .build()

hackleApp.setUser(user) {
    // 적용 완료
}

Java

// 디바이스 ID 변경
hackleApp.setDeviceId("CUSTOM_DEVICE_ID", () -> {
    // 적용 완료
});

사용자 식별자(User ID) 설정

로그인 한 사용자의 식별자를 설정하실 수 있습니다.

Kotlin

// 로그인 한 사용자 ID 추가
hackleApp.setUserId("LOGIN_ID") {
    // 적용 완료
}

// 빌더 패턴 사용
val user = User.builder()
    .userId("LOGIN_ID") // 사용자 ID
    .build()

hackleApp.setUser(user) {
    // 적용 완료
}

Java

// 로그인 한 사용자 ID 추가
hackleApp.setUserId("LOGIN_ID", () -> {
    // 적용 완료
});

추가 식별자

기본 식별자(deviceid, userid) 외의 식별자 타입을 추가할 경우 아래와 같이 설정할 수 있습니다.

추가 식별자는 핵클 통합 식별자로 통합되지 않습니다.

setUser 를 하는 경우 현재 디바이스의 유저 정보를 덮어씁니다.

• 현재 A userId를 사용중인데 setUser 시 A userId 를 전달하지 않으면 userId가 A -> null로 변경됩니다.

• 현재 custom deviceId를 사용중인데 setUser 시 사용중인 deviceId를 전달하지 않으면 custom deviceId -> hackle deviceId로 변경됩니다.

• 추가 식별자를 사용하는 경우에도 setUser 시 전달하지 않으면 추가 식별자가 초기화가 됩니다.

• 프로퍼티의 경우 아래 케이스로 디바이스 내 캐싱된 프로퍼티가 유지 or 초기화 될 수 있습니다.

  • setUser 전 / 후 userId와 deviceId가 동일하다면 캐시된 프로퍼티 유지됩니다.

  • setUser 전 / 후 userId 혹은 deviceId가 변경된다면 캐시된 프로퍼티가 삭제됩니다.

Kotlin

import io.hackle.sdk.common.User

val user = User.builder()
    .userId("143")                   // 사용자 ID (핵클 통합 식별자 사용가능)
    .deviceId("ae2182e0")            // 디바이스 ID (핵클 통합 식별자 사용가능)
    .identifier("myCustomId", "42")  // Custom ID
    .build()

hackleApp.setUser(user) {
    // 적용 완료
}

Java

import io.hackle.sdk.common.User

User user = User.builder()
    .userId("143")                   // 사용자 ID (핵클 통합 식별자 사용가능)
    .deviceId("ae2182e0")            // 디바이스 ID (핵클 통합 식별자 사용가능)
    .identifier("myCustomId", "42")  // Custom ID
    .build();

hackleApp.setUser(user, () -> {
    // 적용 완료
});

사용자 속성(Property)

핵클 SDK는 사용자 속성을 추가할 수 있도록 지원합니다.

• 속성은 속성명(key)과 속성값(value)을 한 쌍으로 보내야 합니다.

• 추가 가능한 속성 개수는 최대 128개입니다.

구분	타입	제약사항
속성 명(key)	string	글자수 제한은 128자입니다. (128 characters) 대소문자를 구분하지 않습니다. 예를 들어 AGE와 age는 동일한 속성명으로 인식합니다.
속성 값(value)	boolean, string, number, array	string 타입인 경우 글자수 제한은 1024자입니다. (1024 characters) string 타입은 대소문자를 구분합니다. 예를 들어 APPLE과 apple은 서로 다른 속성값으로 인식합니다. number 타입인 경우 정수 최대 15자리, 소수점 최대 6자리를 지원합니다.

사용자 속성 추가

PropertyOperations 객체에 set 을 이용하여 속성을 추가한 뒤 updateUserProperties 를 호출하면 사용자 속성을 간단하게 추가할 수 있습니다.

setUserProperty 함수는 Android SDK 4.0.0 부터 deprecated 되었습니다. updateUserProperties 를 사용해 주세요.

Kotlin

import io.hackle.sdk.common.PropertyOperations

// 속성 설정
val operations = PropertyOperations.builder()
    .set("gender", "female")
    .build()

hackleApp.updateUserProperties(operations) {
    // 적용 완료
}

Java

import io.hackle.sdk.common.PropertyOperations;

// 속성 설정
PropertyOperations operations = PropertyOperations.builder()
    .set("gender", "female")
    .build();

hackleApp.updateUserProperties(operations, () -> {
    // 적용 완료
});

사용자 속성 설정

사용자 속성을 추가, 제거 할 수 있습니다.

지원하는 함수	설명
set	사용자 속성을 설정합니다. 속성 키에 이미 설정한 속성값이 있는 경우 덮어씁니다
setOnce	사용자 속성 값을 한번만 설정합니다. 속성키에 대한 속성이 이미 있는 경우 무시됩니다. 예를 들어 사용자에 대한 가입일, 초기 가입 위치 등을 설정할 수 있습니다.
unset	사용자 속성을 제거합니다.
clearAll	사용자의 모든 속성을 제거합니다.

설정하고 싶은 사용자 속성으로 PropertyOperations 객체를 인스턴스화 합니다. 다음 updateUserProperties 를 호출하여 사용자 속성을 업데이트 합니다. 한 번에 여러개의 속성을 설정할 수도 있습니다.

Kotlin

import io.hackle.sdk.common.PropertyOperations

// 속성 설정
val operations = PropertyOperations.builder()
    .set("age", 42)
    .set("grade", "GOLD")
    .setOnce("sign_up_date", "2020-07-03")
    .build()

hackleApp.updateUserProperties(operations) {
    // 적용 완료
}

// 속성 지우기
val clearOperations = PropertyOperations.clearAll()

hackleApp.updateUserProperties(clearOperations) {
    // 적용 완료
}

Java

import io.hackle.sdk.common.PropertyOperations;

// 속성 설정
PropertyOperations operations = PropertyOperations.builder()
    .set("age", 42)
    .set("grade", "GOLD")
    .setOnce("sign_up_date", "2020-07-03")
    .build();

hackleApp.updateUserProperties(operations, () -> {
    // 적용 완료
});

// 속성 지우기
PropertyOperations clearOperations = PropertyOperations.clearAll();

hackleApp.updateUserProperties(clearOperations, () -> {
    // 적용 완료
});

사용자 초기화

기존에 설정한 정보를 초기화해야 합니다. 초기화를 하는 경우 기존에 설정했던 식별자, 속성이 모두 초기화됩니다.

사용자 초기화를 하는 경우 서버에 저장된 사용자 속성까지 모두 초기화가 됩니다. 로그아웃 처리를 원하는 경우 hackleApp.setUserId(null)을 사용해주세요.

userId에 null을 대입하면 클라이언트 상에서 로그아웃 처리가 됩니다.

hackleApp.resetUser {
    // 적용 완료
}