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

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

사용자 ID 요구 사항

개인정보 보호 및 모범 사례

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

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

구현 개요

사용자 ID를 설정하는 시기

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

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

SDK 메서드

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

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

// TurboModule direct API (React Native 0.76+ New Architecture)
import NativeSingular from 'singular-react-native/js/NativeSingular';

// Set the user ID after login or registration
NativeSingular.setCustomUserId('user_123456');

import { Singular } from 'singular-react-native';

// Set the user ID after login or registration
Singular.setCustomUserId('user_123456');

메소드 서명:

static setCustomUserId(customUserId: string): void

예시: 로그인 후 사용자 ID 설정

사용자가 인증을 성공적으로 완료한 후 즉시 setCustomUserId() 으로 전화하여 이후의 모든 이벤트가 사용자 ID와 연결되도록 합니다.

// TurboModule direct API (React Native 0.76+ New Architecture)
import NativeSingular from 'singular-react-native/js/NativeSingular';

async function handleUserLogin(email, password) {
  try {
    // Your authentication logic
    const response = await authenticateUser(email, password);

    if (response.success) {
      // Set the user ID in Singular after successful login
      NativeSingular.setCustomUserId(response.userId);

      console.log('User ID set:', response.userId);

      // Navigate to home screen
      navigateToHome();
    }
  } catch (error) {
    console.error('Login failed:', error);
  }
}

import { Singular } from 'singular-react-native';

async function handleUserLogin(email, password) {
  try {
    // Your authentication logic
    const response = await authenticateUser(email, password);

    if (response.success) {
      // Set the user ID in Singular after successful login
      Singular.setCustomUserId(response.userId);

      console.log('User ID set:', response.userId);

      // Navigate to home screen
      navigateToHome();
    }
  } catch (error) {
    console.error('Login failed:', error);
  }
}

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

사용자가 로그아웃할 때 사용자 ID를 지우면 다중 사용자 디바이스에서 정확한 세션 추적을 보장할 수 있습니다.

// TurboModule direct API (React Native 0.76+ New Architecture)
import NativeSingular from 'singular-react-native/js/NativeSingular';

// Unset the user ID on logout
NativeSingular.unsetCustomUserId();

import { Singular } from 'singular-react-native';

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

메서드 서명:

static unsetCustomUserId(): void

예시: 로그아웃 시 사용자 ID 설정 해제

로그아웃 흐름 중에 unsetCustomUserId() 을 호출하여 사용자 ID를 지우고 후속 이벤트의 잘못된 어트리뷰션을 방지합니다.

// TurboModule direct API (React Native 0.76+ New Architecture)
import NativeSingular from 'singular-react-native/js/NativeSingular';

async function handleUserLogout() {
  try {
    // Clear app data and user session
    await clearUserSession();

    // Unset the user ID in Singular
    NativeSingular.unsetCustomUserId();

    console.log('User ID cleared');

    // Navigate to login screen
    navigateToLogin();
  } catch (error) {
    console.error('Logout failed:', error);
  }
}

import { Singular } from 'singular-react-native';

async function handleUserLogout() {
  try {
    // Clear app data and user session
    await clearUserSession();

    // Unset the user ID in Singular
    Singular.unsetCustomUserId();

    console.log('User ID cleared');

    // Navigate to login screen
    navigateToLogin();
  } catch (error) {
    console.error('Logout failed:', error);
  }
}

초기화 중 사용자 ID 설정

앱이 실행될 때 사용자 ID를 사용할 수 있는 경우(예: 사용자가 이미 로그인한 경우) SDK 초기화 중에 withCustomUserId() 을 사용하여 사용자 ID를 구성합니다. 이렇게 하면 첫 번째 세션에 사용자 ID가 포함됩니다.

// TurboModule direct API (React Native 0.76+ New Architecture)
import React, { useEffect } from 'react';
import NativeSingular from 'singular-react-native/js/NativeSingular';
import type { SingularConfig } from 'singular-react-native/js/NativeSingular';
import AsyncStorage from '@react-native-async-storage/async-storage';

export default function App() {
  useEffect(() => {
    initializeSingular();
  }, []);

  async function initializeSingular() {
    // Check if user is already logged in
    const userId = await AsyncStorage.getItem('user_id');

    // Create configuration object
    const config: SingularConfig = {
      apikey: 'YOUR_SDK_KEY',
      secret: 'YOUR_SDK_SECRET',
      ...(userId ? { customUserId: userId } : {}),
    };

    // Initialize SDK
    NativeSingular.init(config);
  }

  return (
    // Your app components
    null
  );
}

import React, { useEffect } from 'react';
import { Singular, SingularConfig } from 'singular-react-native';
import AsyncStorage from '@react-native-async-storage/async-storage';

export default function App() {
  useEffect(() => {
    initializeSingular();
  }, []);

  async function initializeSingular() {
    // Check if user is already logged in
    const userId = await AsyncStorage.getItem('user_id');

    // Create configuration
    const config = new SingularConfig(
      'YOUR_SDK_KEY',
      'YOUR_SDK_SECRET'
    );

    // If user ID exists, set it during initialization
    if (userId) {
      config.withCustomUserId(userId);
    }

    // Initialize SDK
    Singular.init(config);
  }

  return (
    // Your app components
  );
}

구성 방법 서명:

withCustomUserId(customUserId: string): SingularConfig

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

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

해싱 모드 선택

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

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

SingularUserDetails Setter

모든 setter는 동일한 객체를 반환하므로 호출을 체이닝할 수 있습니다. New Architecture에서는 동일한 6개 키(email, phoneNumber, emailSTD, emailNoDots, phoneE164, phoneDigits)를 사용하는 일반 객체를 전달할 수도 있습니다.

초기화 시 User Details 설정

init()를 호출하기 전에 SingularConfig.userDetails를 설정하거나 withUserDetails() 빌더를 사용하면, SDK가 전송하는 첫 세션에 User Details가 첨부됩니다.

// TurboModule direct API (React Native 0.76+ New Architecture)
import NativeSingular from 'singular-react-native/js/NativeSingular';
import type { SingularConfig } from 'singular-react-native/js/NativeSingular';
const config: SingularConfig = {
  apikey: 'YOUR_SDK_KEY',
  secret: 'YOUR_SDK_SECRET',
  userDetails: {
    email: 'user@example.com',
    phoneNumber: '+15551234567'
  }
};
NativeSingular.init(config);

import { Singular, SingularConfig, SingularUserDetails } from 'singular-react-native';
const userDetails = new SingularUserDetails()
  .setEmail('user@example.com')
  .setPhoneNumber('+15551234567');
const config = new SingularConfig('YOUR_SDK_KEY', 'YOUR_SDK_SECRET')
  .withUserDetails(userDetails);
Singular.init(config);

구성 메서드 시그니처:

withUserDetails(userDetails: SingularUserDetails): SingularConfig

초기화 후 User Details 설정

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

// TurboModule direct API (React Native 0.76+ New Architecture)
import NativeSingular from 'singular-react-native/js/NativeSingular';
// Cleartext values, hashed on the device by the SDK
NativeSingular.setUserDetails({
  email: 'user@example.com',
  phoneNumber: '+15551234567'
});
// Or supply your own SHA-256 hashes
NativeSingular.setUserDetails({
  emailSTD: 'b4c9a289323b21a01c3e940f150eb9b8c542587f1abfd8f0e1cc1ffc5e475514',
  phoneE164: '8a59780bb8cd2ba022bfa5ba2ea3b6e07af17a7d8b30c1f9b3390e36f69019e4'
});

import { Singular, SingularUserDetails } from 'singular-react-native';
// Cleartext values, hashed on the device by the SDK
const userDetails = new SingularUserDetails()
  .setEmail('user@example.com')
  .setPhoneNumber('+15551234567');
Singular.setUserDetails(userDetails);
// Or supply your own SHA-256 hashes
const hashed = new SingularUserDetails()
  .setEmailSTD('b4c9a289323b21a01c3e940f150eb9b8c542587f1abfd8f0e1cc1ffc5e475514')
  .setPhoneE164('8a59780bb8cd2ba022bfa5ba2ea3b6e07af17a7d8b30c1f9b3390e36f69019e4');
Singular.setUserDetails(hashed);

메서드 시그니처:

static setUserDetails(userDetails: SingularUserDetails): void

User Details 삭제

저장된 User Details는 디바이스에 유지됩니다. iOS에서는 Keychain, Android에서는 암호화된 저장소에 보관되며 앱 실행 간에 보존됩니다. 로그아웃 시 또는 유저가 동의를 철회할 때 clearUserDetails()를 호출하여 삭제하세요.

// TurboModule direct API (React Native 0.76+ New Architecture)
import NativeSingular from 'singular-react-native/js/NativeSingular';
// Remove stored user details on logout
NativeSingular.clearUserDetails();

import { Singular } from 'singular-react-native';
// Remove stored user details on logout
Singular.clearUserDetails();

메서드 시그니처:

static clearUserDetails(): void

검증 및 개인정보 처리 동작

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