Unity SDK - 사용자 ID 및 해시된 User Details 설정

팔로우
Avatar
Jared Ornstead
Updated

사용자 ID 및 해시된 User Details 설정

교차 디바이스 추적 및 사용자 수준 데이터 보고를 활성화하려면 내부 사용자 ID를 Singular에 전송하세요.

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

사용자 ID 요구 사항

개인정보 보호 및 모범 사례

사용자 ID 추적을 구현할 때 다음 가이드라인을 준수하여 개인정보 보호 규정을 준수하고 적절한 교차 디바이스 측정을 보장하세요.

  • PII 금지: 사용자 ID는 이메일 주소, 사용자 이름 또는 전화번호와 같은 개인 식별 정보(PII)를 노출해서는 안 됩니다. 퍼스트 파티 데이터에 고유한 해시값을 사용하세요.
  • 플랫폼 간 일관성: 정확한 기기 간 측정을 위해 사용자 ID 값은 모든 플랫폼(웹/모바일/PC/콘솔/오프라인)에서 캡처하는 동일한 내부 식별자이어야 합니다.
  • 퍼스트 파티 데이터: Singular: 사용자 수준 내보내기, ETL 및 내부 BI 포스트백(구성된 경우)에 사용자 ID가 포함됩니다. 사용자 ID는 퍼스트 파티 데이터이며 타사와 공유되지 않습니다.
  • 지속성: 사용자 ID는 UnsetCustomUserId() 을 사용하여 명시적으로 설정 해제하거나 앱이 제거될 때까지 지속됩니다. 앱을 닫거나 다시 시작해도 사용자 ID는 지워지지 않습니다.

구현 개요

사용자 ID를 설정하는 시기

SetCustomUserId() 을 사용하여 사용자 식별자를 설정하고 UnsetCustomUserId() 을 사용하여 로그아웃 중에 사용자 식별자를 지웁니다.

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

앱이 열릴 때 사용자 ID를 이미 알고 있는 경우 Singular SDK를 초기화하기 전에 SetCustomUserId() 을 호출하세요. 이렇게 하면 Singular가 첫 번째 세션에서 사용자 ID를 수신합니다. 그러나 일반적으로 사용자가 등록하거나 로그인할 때까지 사용자 ID를 사용할 수 없으므로 등록 또는 인증 흐름이 완료된 후 SetCustomUserId() 을 호출하세요.

SDK 메서드

사용자 지정 사용자 아이디 설정

교차 디바이스 추적 및 사용자 수준 보고를 위해 내부 사용자 ID를 Singular로 전송합니다.

C# 
// Set the user ID after login or registration
SingularSDK.SetCustomUserId("custom_user_id");

메소드 서명: 

public static void SetCustomUserId(string customUserId)

사용자 지정 사용자 ID 설정 해제

사용자가 로그아웃할 때 사용자 ID를 지워 다중 사용자 디바이스에 대한 정확한 세션 추적을 보장합니다.

C# 
// Unset the user ID on logout
SingularSDK.UnsetCustomUserId();

메소드 서명: 

public static void UnsetCustomUserId()

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

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

사용 가능 버전: Unity SDK 5.10.0 이상. 두 메서드 모두 Unity 에디터에서는 아무 동작도 하지 않으므로, 디바이스나 에뮬레이터에서 확인하세요.

해싱 모드 선택

User Details를 제공하는 방법은 두 가지입니다. 사용자별로 하나를 선택하고 일관되게 사용하세요.

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

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

SingularUserDetails Setter

모든 setter는 동일한 SingularUserDetails 인스턴스를 반환하므로 체이닝할 수 있습니다. null, 빈 문자열 또는 공백을 전달하면 해당 값이 저장되지 않고 제거됩니다.

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 — 그리고 값이 하나라도 설정되었는지 알려주는 IsEmpty도 있습니다.

초기화 전에 User Details 설정

Unity에는 User Details를 위한 별도의 구성 시점 API가 없습니다. SDK 초기화 전에 SetUserDetails를 호출하면 값이 보관되었다가 첫 세션과 함께 전송되므로, 최초 요청부터 값이 첨부됩니다.

C#
// Called before the Singular SDK initializes
SingularUserDetails userDetails = new SingularUserDetails()
    .SetEmail("user@example.com")
    .SetPhoneNumber("+15551234567");

SingularSDK.SetUserDetails(userDetails);

초기화 후 User Details 설정

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

C#
// Cleartext values, hashed by the SDK
SingularUserDetails userDetails = new SingularUserDetails()
    .SetEmail("user@example.com")
    .SetPhoneNumber("+15551234567");

SingularSDK.SetUserDetails(userDetails);

// Or supply your own SHA-256 hashes
SingularUserDetails hashed = new SingularUserDetails()
    .SetEmailSTD("b4c9a289323b21a01c3e940f150eb9b8c542587f1abfd8f0e1cc1ffc5e475514")
    .SetPhoneE164("8a59780bb8cd2ba022bfa5ba2ea3b6e07af17a7d8b30c1f9b3390e36f69019e4");

SingularSDK.SetUserDetails(hashed);

메소드 서명:

public static void SetUserDetails(SingularUserDetails details)

User Details 삭제

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

C#
// Remove stored user details on logout
SingularSDK.ClearUserDetails();

메소드 서명:

public static void ClearUserDetails()

참고: 이후 실행에서 SetUserDetails를 호출해도 이전에 저장된 값은 삭제되지 않습니다. SetUserDetails(null) 또는 값이 하나도 설정되지 않은 SingularUserDetails를 전달하는 경우에도 저장된 값이 삭제되며, 그대로 유지되지 않습니다.

검증 및 개인정보 처리 동작

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