사용자 ID 및 해시된 User Details 설정
교차 디바이스 추적 및 사용자 수준 데이터 보고를 활성화하려면 내부 사용자 ID를 Singular에 전송하세요.
참고: Singular의 크로스 디바이스 솔루션을 사용하는 경우, 모든 플랫폼에서 사용자 ID를 수집해야 합니다.
사용자 ID 요구 사항
개인정보 보호 및 모범 사례
사용자 ID 추적을 구현할 때 다음 가이드라인을 준수하여 개인정보 보호 규정을 준수하고 적절한 교차 디바이스 측정을 보장하세요.
- PII 금지: 사용자 ID는 이메일 주소, 사용자 이름 또는 전화번호와 같은 개인 식별 정보(PII)를 노출해서는 안 됩니다. 퍼스트 파티 데이터에 고유한 해시값을 사용하세요.
- 플랫폼 간 일관성: 정확한 기기 간 측정을 위해 사용자 ID 값은 모든 플랫폼(웹/모바일/PC/콘솔/오프라인)에서 캡처하는 동일한 내부 식별자이어야 합니다.
- 퍼스트 파티 데이터: Singular: 사용자 수준 내보내기, ETL 및 내부 BI 포스트백(구성된 경우)에 사용자 ID가 포함됩니다. 사용자 ID는 퍼스트 파티 데이터이며 타사와 공유되지 않습니다.
-
지속성: 사용자 ID는
unsetCustomUserId()을 사용하여 명시적으로 설정 해제하거나 앱이 제거될 때까지 지속됩니다. 앱을 닫거나 다시 시작해도 사용자 ID는 지워지지 않습니다.
구현 개요
사용자 ID를 설정하는 시기
Singular.setCustomUserId() 을 사용하여 사용자 식별자를 설정하고 Singular.unsetCustomUserId() 을 사용하여 로그아웃 중에 사용자 식별자를 지웁니다.
모범 사례: 여러 사용자가 하나의 디바이스를 공유하는 경우 로그인 시 setCustomUserId(), 로그아웃 시 unsetCustomUserId() 을 호출하는 로그아웃 플로우를 구현하세요.
앱이 열릴 때 사용자 ID를 이미 알고 있는 경우 Singular SDK를 초기화하기 전에 customUserId 속성을 사용하여 구성하세요. 이렇게 하면 Singular가 첫 번째 세션에서 사용자 ID를 수신합니다. 그러나 일반적으로 사용자가 등록하거나 로그인할 때까지 사용자 ID를 사용할 수 없으며, 이 경우 등록 또는 인증 흐름이 완료된 후 setCustomUserId() 을 호출하세요.
SDK 메서드
사용자 지정 사용자 아이디 설정
교차 디바이스 추적 및 사용자 수준 보고를 위해 내부 사용자 ID를 Singular로 전송합니다.
import 'package:singular_flutter_sdk/singular.dart';
// Set the user ID after login or registration
Singular.setCustomUserId('user_123456');메소드 서명:
static void setCustomUserId(String customUserId)예시: 로그인 후 사용자 ID 설정
사용자가 인증을 성공적으로 완료한 후 즉시 setCustomUserId() 으로 전화하여 이후의 모든 이벤트가 사용자 ID와 연결되도록 합니다.
import 'package:singular_flutter_sdk/singular.dart';
Future<void> handleUserLogin(String email, String password) async {
try {
// Your authentication logic
final response = await authenticateUser(email, password);
if (response.success) {
// Set the user ID in Singular after successful login
Singular.setCustomUserId(response.userId);
print('User ID set: ${response.userId}');
// Navigate to home screen
navigateToHome();
}
} catch (error) {
print('Login failed: $error');
}
}사용자 지정 사용자 ID 설정 해제
사용자가 로그아웃할 때 사용자 ID를 지우면 다중 사용자 디바이스에서 정확한 세션 추적을 보장할 수 있습니다.
import 'package:singular_flutter_sdk/singular.dart';
// Unset the user ID on logout
Singular.unsetCustomUserId();메서드 서명:
static void unsetCustomUserId()예시: 로그아웃 시 사용자 ID 설정 해제
로그아웃 흐름 중에 unsetCustomUserId() 을 호출하여 사용자 ID를 지우고 후속 이벤트의 잘못된 어트리뷰션을 방지합니다.
import 'package:singular_flutter_sdk/singular.dart';
Future<void> handleUserLogout() async {
try {
// Clear app data and user session
await clearUserSession();
// Unset the user ID in Singular
Singular.unsetCustomUserId();
print('User ID cleared');
// Navigate to login screen
navigateToLogin();
} catch (error) {
print('Logout failed: $error');
}
}초기화 중 사용자 ID 설정
앱이 실행될 때 사용자 ID를 사용할 수 있는 경우(예: 사용자가 이미 로그인한 경우), SDK 초기화 중에 customUserId 속성을 사용하여 사용자 ID를 구성합니다. 이렇게 하면 첫 번째 세션에 사용자 ID가 포함됩니다.
import 'package:flutter/material.dart';
import 'package:singular_flutter_sdk/singular.dart';
import 'package:singular_flutter_sdk/singular_config.dart';
import 'package:shared_preferences/shared_preferences.dart';
void main() {
runApp(MyApp());
}
class MyApp extends StatefulWidget {
@override
_MyAppState createState() => _MyAppState();
}
class _MyAppState extends State<MyApp> {
@override
void initState() {
super.initState();
initializeSingular();
}
Future<void> initializeSingular() async {
// Check if user is already logged in
final prefs = await SharedPreferences.getInstance();
final userId = prefs.getString('user_id');
// Create configuration
SingularConfig config = SingularConfig(
'YOUR_SDK_KEY',
'YOUR_SDK_SECRET'
);
// If user ID exists, set it during initialization
if (userId != null) {
config.customUserId = userId;
}
// Initialize SDK
Singular.start(config);
}
@override
Widget build(BuildContext context) {
return MaterialApp(
title: 'Flutter Demo',
home: MyHomePage(),
);
}
}구성 속성:
String? customUserId
권장 사항: 영구 로그인 세션이 있는 앱의 경우 초기화 중에 customUserId구성 속성을 사용하세요. 사용자가 매번 로그인해야 하는 앱의 경우 인증 후 setCustomUserId() 을 호출하세요.
해시된 User Details(이메일 및 전화번호)
위의 유저 ID는 고객사가 정의한 고유 식별자입니다. 사용자의 이메일 주소나 전화번호도 Singular에 전송하려면 별도의 SingularUserDetails API를 사용하세요. SDK가 기기에서 값을 정규화하고 SHA-256으로 해시하므로 원본 이메일 주소와 전화번호는 전송되지 않습니다.
사용 가능 버전: Flutter SDK 1.9.1 이상이며, 네이티브 iOS 12.14.2 및 Android 12.16.1이 포함됩니다.
해싱 모드 선택
User Details를 제공하는 방법은 두 가지입니다. 사용자별로 하나를 선택하고 일관되게 사용하세요.
- SDK 해싱(권장): 평문 이메일 또는 전화번호를 설정합니다. SDK가 값을 정규화하고 해시하여 Singular가 매칭할 수 있는 모든 변형을 생성합니다.
- 사전 해싱: 직접 정규화하고 SHA-256으로 해시한 값을 설정합니다. SDK는 값을 그대로 저장하며 추가 처리를 하지 않습니다. 호출 시점에 앱이 평문 User Details를 보유할 수 없는 경우에 사용하세요.
중요: 평문 값과 그에 대응하는 사전 해시 값을 모두 설정하면 사전 해시 값이 우선합니다.
SingularUserDetails 속성
SingularUserDetails는 nullable String 속성 6개를 제공합니다. 보유한 값만 할당하고 나머지는 설정하지 않은 상태로 두세요.
| 속성 | 세부 정보 |
|---|---|
email |
모드: SDK 해싱 평문 이메일 주소입니다. SDK는 해싱 전에 공백을 제거하고 소문자로 변환합니다. 예시: |
phoneNumber |
모드: SDK 해싱 평문 전화번호입니다. SDK는 두 가지 변형을 생성합니다. 선행 예시: |
emailSTD |
모드: 사전 해싱 공백 제거 및 소문자 변환 후의 이메일 주소에 대한 SHA-256 해시입니다. |
emailNoDots |
모드: 사전 해싱 공백 제거, 소문자 변환, |
phoneE164 |
모드: 사전 해싱 선행 |
phoneDigits |
모드: 사전 해싱 선행 |
초기화 시 User Details 설정
Singular.start를 호출하기 전에 SingularConfig에 User Details를 설정하면 SDK가 전송하는 첫 세션에 함께 첨부됩니다. userDetails 속성을 직접 할당하거나 withUserDetails를 호출할 수 있으며 두 방법은 동일합니다.
import 'package:singular_flutter_sdk/singular.dart';
import 'package:singular_flutter_sdk/singular_config.dart';
import 'package:singular_flutter_sdk/singular_user_details.dart';
SingularUserDetails userDetails = SingularUserDetails();
userDetails.email = 'user@example.com';
userDetails.phoneNumber = '+15551234567';
SingularConfig config = SingularConfig('SDK KEY', 'SDK SECRET');
config.withUserDetails(userDetails);
Singular.start(config);메서드 서명:
void withUserDetails(SingularUserDetails userDetails)참고: withUserDetails는 void를 반환하므로 SingularConfig 생성자에 체이닝할 수 없습니다. 별도의 줄에서 호출하거나 config.userDetails를 직접 할당하세요.
초기화 후 User Details 설정
이메일 주소나 전화번호를 로그인 또는 회원가입 이후에만 알 수 있는 경우에는 그 시점에 Singular.setUserDetails를 호출하세요. 이후 SDK가 전송하는 모든 세션과 이벤트에 값이 첨부됩니다.
import 'package:singular_flutter_sdk/singular.dart';
import 'package:singular_flutter_sdk/singular_user_details.dart';
// 평문 값, SDK가 해싱
SingularUserDetails userDetails = SingularUserDetails();
userDetails.email = 'user@example.com';
userDetails.phoneNumber = '+15551234567';
Singular.setUserDetails(userDetails);
// 또는 직접 생성한 SHA-256 해시 사용
SingularUserDetails hashed = SingularUserDetails();
hashed.emailSTD = 'b4c9a289323b21a01c3e940f150eb9b8c542587f1abfd8f0e1cc1ffc5e475514';
hashed.phoneE164 = '8a59780bb8cd2ba022bfa5ba2ea3b6e07af17a7d8b30c1f9b3390e36f69019e4';
Singular.setUserDetails(hashed);메서드 서명:
static void setUserDetails(SingularUserDetails userDetails)User Details 삭제
저장된 User Details는 앱 실행 간에 기기에 유지되며 앱을 삭제하면 제거됩니다. 로그아웃 시 또는 사용자가 동의를 철회할 때 Singular.clearUserDetails를 호출하여 제거하세요.
import 'package:singular_flutter_sdk/singular.dart';
// 로그아웃 시 저장된 User Details 제거
Singular.clearUserDetails();메서드 서명:
static void clearUserDetails()저장된 User Details를 삭제하는 세 가지 방법. clearUserDetails만이 유일한 방법은 아닙니다. 속성이 하나도 설정되지 않은 SingularUserDetails 객체로 setUserDetails를 호출해도 삭제되며, 모든 값이 유효하지 않아 거부되는 객체로 호출하는 경우에도 마찬가지입니다. 이 마지막 경우에는 저장된 페이로드가 그대로 유지되지 않고 삭제됩니다. 저장된 User Details를 그대로 두려면 setUserDetails를 아예 호출하지 마세요.
참고: 이후 실행에서 userDetails를 설정해도 이전에 저장된 값이 지워지지는 않으므로, 삭제하기 전까지는 이전에 저장된 페이로드가 계속 전송됩니다.
유효성 검사 및 개인정보 보호 동작
-
이메일 유효성 검사: 평문 이메일에는
@가 정확히 하나 있어야 하고 그 뒤에 점이 있어야 합니다. 유효하지 않은 값은 거부되고 로그에 기록되며 전송되지 않습니다. - 전화번호 유효성 검사: 평문 전화번호에는 숫자가 6자리 이상 있어야 합니다. 더 짧은 값은 거부되고 로그에 기록됩니다.
-
잘못된 모드 방지: 이미 해시된 것처럼 보이는 값은
email및phoneNumber에서 거부됩니다. 마찬가지로 사전 해시 속성은 64자 SHA-256 16진수 문자열이 아닌 값을 거부합니다. - 저장: 해시된 페이로드는 각 플랫폼의 앱 전용 저장소에 보관되며 앱을 삭제하면 제거됩니다. 평문 값은 저장되지 않습니다.
- Limit Data Sharing: Limit Data Sharing이 활성화된 동안에는 User Details 페이로드가 모든 요청에서 제외됩니다. 데이터 프라이버시를 참조하세요.
- 동의: 법적 근거가 있는 경우에만 이메일 주소와 전화번호를 수집하고 전송하세요. 해싱을 하더라도 GDPR, CCPA 또는 이에 준하는 규정에 따른 의무가 사라지지는 않습니다.