Android SDK - 유저 ID 및 해시된 User Details 설정

팔로우
Avatar
Jared Ornstead
Updated

유저 ID 및 해시된 User Details 설정

내부 유저 ID를 Singular에 전송하여 크로스 디바이스 트래킹과 유저 레벨 데이터 보고를 활성화하세요.

참고: Singular의 크로스 디바이스 솔루션 을 사용하는 경우, 모든 플랫폼에서 유저 ID를 수집해야 합니다.

유저 ID 요구사항

개인정보 및 모범 사례

개인정보 보호 준수와 정확한 크로스 디바이스 측정을 보장하려면 유저 ID 트래킹을 구현할 때 다음 지침을 따르세요.

  • PII 금지: 유저 ID는 이메일 주소, 유저명, 전화번호 등 개인 식별 정보(PII)를 노출해서는 안 됩니다. 자사 데이터에 고유한 해시 값을 사용하세요. 이메일 주소나 전화번호를 전송하려면 대신 전용 해시된 User Details API를 사용하세요.
  • 플랫폼 간 일관성: 유저 ID 값은 정확한 크로스 디바이스 측정을 위해 모든 플랫폼(Web/Mobile/PC/Console/Offline)에서 수집하는 동일한 내부 식별자여야 합니다.
  • 자사 데이터: Singular는 유저 ID를 유저 레벨 익스포트, ETL, 내부 BI 포스트백(구성된 경우)에 포함합니다. 유저 ID는 자사 데이터이며 제3자와 공유되지 않습니다.
  • 지속성: 유저 ID는 unsetCustomUserId() 를 사용해 명시적으로 해제하거나 앱이 삭제될 때까지 유지됩니다. 앱을 종료하거나 재시작해도 유저 ID는 초기화되지 않습니다.

구현 개요

유저 ID를 설정해야 하는 시점

유저 식별자를 설정하려면 setCustomUserId() 를, 로그아웃 시 해제하려면 unsetCustomUserId() 를 사용하세요.

모범 사례: 여러 유저가 하나의 디바이스를 공유하는 경우, 로그인 시 setCustomUserId() 를 호출하고 로그아웃 시 unsetCustomUserId() 를 호출하는 로그아웃 플로우를 구현하세요.

앱이 열릴 때 이미 유저 ID를 알고 있다면, Singular SDK를 초기화하기 전에 setCustomUserId() 를 호출하세요. 이를 통해 첫 세션부터 Singular가 유저 ID를 받을 수 있습니다. 다만, 유저 ID는 일반적으로 유저가 등록하거나 로그인할 때까지 사용할 수 없으므로 등록 또는 인증 플로우가 완료된 후 setCustomUserId() 를 호출하세요.

SDK 메서드

사용자 지정 유저 ID 설정

크로스 디바이스 트래킹과 유저 레벨 보고를 위해 내부 유저 ID를 Singular에 전송하세요.

Kotlin Java 
// Set the user ID after login or registration
Singular.setCustomUserId("custom_user_id")

메서드 시그니처: 

public static void setCustomUserId(String customUserId);

사용자 지정 유저 ID 해제

여러 유저가 사용하는 디바이스에서 정확한 세션 트래킹을 보장하려면 유저가 로그아웃할 때 유저 ID를 초기화하세요.

Kotlin Java 
// Unset the user ID on logout
Singular.unsetCustomUserId()

메서드 시그니처: 

public static void unsetCustomUserId();

해시된 User Details(이메일 및 전화번호)

위의 유저 ID는 여러분이 직접 관리하는 불투명한 식별자입니다. 유저의 이메일 주소나 전화번호도 Singular로 전송하려면 별도의 SingularUserDetails API를 사용하세요. SDK가 디바이스에서 값을 정규화하고 SHA-256으로 해싱하므로 원본 이메일 주소와 전화번호는 전송되지 않습니다.

사용 가능 버전: Android SDK 버전 12.16.0 이상. 이 API는 Kids SDK 버전에서는 사용할 수 없습니다.

해싱 모드 선택

PII를 전달하는 방법은 두 가지입니다. 유저별로 하나를 선택하고 일관되게 사용하세요.

  • SDK 해싱(권장): 평문 이메일 또는 전화번호를 전달합니다. SDK가 값을 정규화하고 해싱하며, Singular가 매칭에 사용할 수 있는 모든 변형을 생성합니다.
  • 사전 해싱: 직접 정규화하고 SHA-256으로 해싱한 값을 전달합니다. SDK는 전달된 값을 그대로 저장하며 추가 처리를 하지 않습니다. 앱이 해당 시점에 평문 PII를 보유할 수 없는 경우에 사용하세요.

중요: 평문 값과 이에 대응하는 사전 해싱 값을 모두 설정하면 사전 해싱 값이 우선합니다.

SingularUserDetails Setter

Setter 세부 정보
setEmail

모드: SDK 해싱

평문 이메일 주소입니다. SDK는 해싱 전에 공백을 제거하고 소문자로 변환합니다. gmail.com 및 googlemail.com 주소의 경우, 로컬 파트에서 +tag 접미사와 모든 점을 제거한 두 번째 변형도 생성합니다.

예시: user@example.com

setPhoneNumber

모드: SDK 해싱

평문 전화번호입니다. SDK는 두 가지 변형을 생성합니다. 선행 +를 유지하고 나머지 비숫자 문자를 제거한 E.164 형식과, +까지 제거한 숫자 전용 형식입니다. E.164 변형을 사용할 수 있도록 국가 코드를 포함하세요.

예시: +15551234567

setEmailSTD

모드: 사전 해싱

공백 제거 및 소문자 변환 후 이메일 주소의 SHA-256 해시입니다.

setEmailNoDots

모드: 사전 해싱

공백 제거, 소문자 변환, 로컬 파트의 +tag 접미사 및 모든 점 제거 후 이메일 주소의 SHA-256 해시입니다. Gmail 형식 주소에 적용됩니다.

setPhoneE164

모드: 사전 해싱

선행 +를 유지한 E.164 형식 전화번호의 SHA-256 해시입니다.

setPhoneDigits

모드: 사전 해싱

선행 +를 포함한 모든 비숫자 문자를 제거한 전화번호의 SHA-256 해시입니다.

모든 setter에는 설정한 값을 반환하는 대응 getter(getEmail, getPhoneNumber, getEmailSTD, getEmailNoDots, getPhoneE164, getPhoneDigits)가 있습니다.

초기화 시 User Details 설정

Singular.init를 호출하기 전에 SingularConfig에 withUserDetails를 체이닝하면 SDK가 전송하는 첫 세션에 User Details가 첨부됩니다.

Kotlin Java 
val userDetails = SingularUserDetails()
userDetails.setEmail("user@example.com")
userDetails.setPhoneNumber("+15551234567")

val config = SingularConfig("SDK KEY", "SDK SECRET")
    .withUserDetails(userDetails)

Singular.init(context, config)

초기화 후 PII 설정

이메일 주소나 전화번호를 로그인 또는 등록 후에만 알 수 있는 경우, 그 시점에 setUserDetails를 호출하세요. 이후 SDK가 전송하는 모든 세션과 이벤트에 값이 첨부됩니다.

Kotlin Java 
// Cleartext values, hashed by the SDK
val userDetails = SingularUserDetails()
userDetails.setEmail("user@example.com")
userDetails.setPhoneNumber("+15551234567")
Singular.setUserDetails(userDetails)

// Or supply your own SHA-256 hashes
val hashed = SingularUserDetails()
hashed.setEmailSTD("b4c9a289323b21a01c3e940f150eb9b8c542587f1abfd8f0e1cc1ffc5e475514")
hashed.setPhoneE164("8a59780bb8cd2ba022bfa5ba2ea3b6e07af17a7d8b30c1f9b3390e36f69019e4")
Singular.setUserDetails(hashed)

메서드 시그니처: 

public static void setUserDetails(SingularUserDetails userDetails);

PII 삭제

저장된 User Details는 앱 실행 간에 디바이스에 유지됩니다. 로그아웃 시 또는 유저가 동의를 철회할 때 clearUserDetails를 호출하여 삭제하세요.

Kotlin Java 
// Remove stored user details on logout
Singular.clearUserDetails()

메서드 시그니처: 

public static void clearUserDetails();

참고: 페이로드는 Android Keystore에 보관된 키로 암호화되어 디바이스에 저장됩니다. 값이 유지되므로 이후 실행에서 withUserDetails를 호출해도 이전에 저장된 값은 삭제되지 않습니다. clearUserDetails만이 이를 제거하는 유일한 방법입니다.

검증 및 개인정보 처리 동작

  • 이메일 검증: 평문 이메일에는 정확히 하나의 @와 그 뒤의 점이 있어야 합니다. 유효하지 않은 값은 거부되고 로그에 기록되며 전송되지 않습니다.
  • 전화번호 검증: 평문 전화번호에는 최소 6자리 숫자가 있어야 합니다. 더 짧은 값은 거부되고 로그에 기록됩니다.
  • 모드 오류 방지: 이미 해싱된 것처럼 보이는 값은 setEmail 및 setPhoneNumber에서 거부됩니다. 마찬가지로 사전 해싱 setter는 64자 SHA-256 16진수 문자열이 아닌 값을 거부합니다.
  • Limit Data Sharing: Limit Data Sharing이 활성화된 동안에는 PII 페이로드가 모든 요청에서 제외됩니다. 참조: 데이터 개인정보 보호.
  • 동의: 법적 근거가 있는 경우에만 이메일 주소와 전화번호를 수집하고 전송하세요. 해싱은 GDPR, CCPA 또는 이에 상응하는 규정에 따른 의무를 면제하지 않습니다.