ユーザーIDとハッシュ化 User Details の設定

社内ユーザーIDをSingularに送信して、クロスデバイス追跡とユーザーレベルデータレポートを有効にします。

ユーザーIDの要件

プライバシーとベストプラクティス

プライバシーコンプライアンスと適切なクロスデバイス測定を保証するため、ユーザーIDトラッキングを実施する際は以下のガイドラインに従ってください。

• PIIを使用しない：ユーザIDは、メールアドレス、ユーザ名、電話番号などの個人を特定できる情報（PII）を公開するべきではありません。ファーストパーティデータに固有のハッシュ化された値を使用してください。 メールアドレスや電話番号を送信する場合は、代わりに専用の ハッシュ化 User Details API を使用してください。
• プラットフォーム間の一貫性：ユーザーIDの値は、正確なクロスデバイス測定のために、すべてのプラットフォーム（ウェブ／モバイル／PC／コンソール／オフライン）で同じ内部識別子でなければなりません。
• ファーストパーティデータ：Singularはユーザーレベルのエクスポート、ETL、内部BIポストバック（設定されている場合）にユーザーIDを含みます。 ユーザーIDはファーストパーティデータであり、第三者と共有されることはありません。
• 永続性：ユーザー ID は、unsetCustomUserId() を使用して明示的に設定が解除されるか、アプリがアンインストールされるまで保持されます。アプリを終了または再起動しても、ユーザIDはクリアされません。

実装の概要

ユーザIDを設定するタイミング

ユーザーIDを設定するにはSingular.setCustomUserId() 、ログアウト時にクリアするにはSingular.unsetCustomUserId() 。

アプリを開いたときにすでにユーザーIDがわかっている場合は、Singular SDKを初期化する前にwithCustomUserId() 。 これによりSingularは最初のセッションからユーザーIDを受け取ります。ただし、ユーザーIDは通常、ユーザーが登録またはログインするまで使用できません。その場合は、登録または認証フローが完了した後にsetCustomUserId() 。

SDKメソッド

カスタムユーザーIDの設定

クロスデバイスのトラッキングとユーザーレベルのレポートのために、内部ユーザー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が利用可能な場合（ユーザーがすでにログインしているなど）、withCustomUserId() を使用してSDKの初期化中にユーザー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 を渡す方法は2つあります。ユーザーごとに1つを選び、一貫して使用してください。

• SDKハッシュ化(推奨): 平文のメールアドレスまたは電話番号を渡します。SDKが値を正規化してハッシュ化し、Singularがマッチングに使用できるすべてのバリアントを生成します。
• 事前ハッシュ化: ご自身で正規化してSHA-256でハッシュ化した値を渡します。SDKは渡された値をそのまま保存し、それ以上の処理は行いません。呼び出し時点でアプリが平文の User Details を保持できない場合に使用してください。

SingularUserDetails のセッター

すべてのセッターは同じオブジェクトを返すため、呼び出しをチェーンできます。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" という文字列も含まれます。値の形式は検証しません。
• メールアドレスの検証: 平文のメールアドレスには @ が正確に1つ含まれ、その後にドットが必要です。無効な値は拒否されログに記録され、送信されません。
• 電話番号の検証: 平文の電話番号には少なくとも6桁の数字が必要です。それより短い値は拒否されログに記録されます。
• モード誤用の防止: すでにハッシュ化されているように見える値は setEmail と setPhoneNumber で拒否されます。同様に、事前ハッシュ化用のセッターは64文字のSHA-256の16進文字列以外を拒否します。
• Limit Data Sharing: Limit Data Sharing が有効な間は、User Details ペイロードがすべてのリクエストから除外されます。 参照: データプライバシー.
• 同意: 法的根拠がある場合にのみ、メールアドレスと電話番号を収集して送信してください。ハッシュ化はGDPR、CCPA、または同等の規制に基づく義務を免除するものではありません。