ユーザーIDとハッシュ化 User Details の設定
社内ユーザーIDをSingularに送信して、クロスデバイス追跡とユーザーレベルデータレポートを有効にします。
注： Singularのクロスデバイスソリューションをご利用の場合は、すべてのプラットフォームでユーザーIDを収集する必要があります。
ユーザーIDの要件
プライバシーとベストプラクティス
プライバシーコンプライアンスと適切なクロスデバイス測定を保証するため、ユーザーIDトラッキングを実施する際は以下のガイドラインに従ってください。
- PIIを使用しない：ユーザIDは、電子メールアドレス、ユーザ名、電話番号などの個人を特定できる情報（PII）を公開すべきではありません。ファーストパーティデータに固有のハッシュ化された値を使用してください。
- プラットフォーム間の一貫性：ユーザーIDの値は、正確なクロスデバイス測定のために、すべてのプラットフォーム（ウェブ／モバイル／PC／コンソール／オフライン）で同じ内部識別子でなければなりません。
- ファーストパーティデータ：Singularは、ユーザーレベルのエクスポート、ETL、内部BIポストバック（設定されている場合）にユーザーIDを含めます。ユーザーIDはファーストパーティデータであり、第三者と共有されることはありません。
-
永続性：ユーザー ID は、
unsetCustomUserId()を使用して明示的に設定が解除されるか、アプリがアンインストールされるまで保持されます。アプリを終了または再起動しても、ユーザIDはクリアされません。
実装の概要
ユーザIDを設定するタイミング
ユーザーIDを設定するにはSingular.setCustomUserId() 、ログアウト時にクリアするにはSingular.unsetCustomUserId() 。
ベストプラクティス複数のユーザーが1つのデバイスを共有する場合は、ログイン時にsetCustomUserId() を呼び出し、ログアウト時にunsetCustomUserId() を呼び出すログアウトフローを実装します。
アプリを開いたときのユーザーIDをすでに知っている場合は、Singular SDKを初期化する前にcustomUserId プロパティを使って設定します。これにより、Singularは最初のセッションからユーザーIDを受け取ります。ただし、ユーザIDは通常、ユーザが登録またはログインするまで使用できません。その場合は、登録または認証フローが完了した後にsetCustomUserId() を呼び出します。
SDKメソッド
カスタムユーザーIDの設定
クロスデバイスのトラッキングとユーザーレベルのレポートのために、内部ユーザー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が含まれるようになります。
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 を指定する方法は2つあります。ユーザーごとにどちらかを選び、一貫して使用してください。
- SDKハッシュ化(推奨): 平文のメールアドレスまたは電話番号を設定します。SDKが値を正規化してハッシュ化し、Singularがマッチングに使用できるすべてのバリアントを生成します。
- 事前ハッシュ化: お客様側で正規化とSHA-256ハッシュ化を済ませた値を設定します。SDKは値をそのまま保存し、それ以上の処理は行いません。呼び出し時点でアプリが平文の User Details を保持できない場合に使用してください。
重要: 平文の値と対応する事前ハッシュ値の両方を設定した場合は、事前ハッシュ値が優先されます。
SingularUserDetails のプロパティ
SingularUserDetailsには、nullableなStringプロパティが6つあります。保有している値のみを設定し、それ以外は未設定のままにしてください。
| プロパティ | 詳細 |
|---|---|
email |
モード: SDKハッシュ化 平文のメールアドレスです。SDKはハッシュ化の前に空白を削除し、小文字に変換します。 例: |
phoneNumber |
モード: SDKハッシュ化 平文の電話番号です。SDKは2つのバリアントを生成します。先頭の 例: |
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 を削除する3つの方法。 clearUserDetailsだけが方法ではありません。プロパティが1つも設定されていないSingularUserDetailsオブジェクトでsetUserDetailsを呼び出しても削除され、すべての値が無効として拒否されるオブジェクトで呼び出した場合も同様です。後者では、保存されているペイロードはそのまま残らず削除されます。保存された User Details をそのままにしたい場合は、setUserDetailsを呼び出さないでください。
注: 後の起動でuserDetailsを設定しても、以前に保存された値が消去されることはありません。そのため、削除するまでは以前のペイロードが送信され続けます。
検証とプライバシーの動作
-
メールアドレスの検証: 平文のメールアドレスには
@がちょうど1つ含まれ、その後にドットが必要です。無効な値は拒否されてログに記録され、送信されません。 - 電話番号の検証: 平文の電話番号には数字が6桁以上必要です。それより短い値は拒否されてログに記録されます。
-
モード誤りの防止: すでにハッシュ化されているように見える値は
emailとphoneNumberで拒否されます。同様に、事前ハッシュ化プロパティは64文字のSHA-256の16進文字列以外を拒否します。 - 保存: ハッシュ化されたペイロードは各プラットフォームのアプリ専用ストレージに保存され、アプリをアンインストールすると削除されます。平文の値が保存されることはありません。
- Limit Data Sharing: Limit Data Sharingが有効な間、User Details のペイロードはすべてのリクエストから除外されます。データプライバシーを参照してください。
- 同意: 法的根拠がある場合にのみ、メールアドレスと電話番号を収集・送信してください。ハッシュ化を行っても、GDPR、CCPAまたは同等の規制上の義務がなくなるわけではありません。