Идентификация пользователя в Android
Android SDK поддерживает два режима идентификации: автоматический и управляемый приложением.
Стандарт CUID на основе телефона (phone_hash)
Рекомендуемый идентификатор пользователя для LoginEvent и SignUpEvent - SHA-256 хеш нормализованного мобильного телефона.
Правила формирования:
- перед хешированием номер очищается от всех символов, кроме цифр;
- для РФ и КЗ номер приводится к формату
7XXXXXXXXXX; - для других стран используется международный формат без
+и разделителей; - хеш считается по строке в UTF-8;
- результат передается в lowercase hex;
- в
cuidTypeпередается строка"phone_hash".
Один и тот же идентификатор рекомендуется использовать во всех каналах: web, server-side API, offline import и mobile SDK.
Автоматическая идентификация
Это поведение SDK по умолчанию. Если сервер вернул uid и ses, SDK сохраняет и переиспользует их. uid сохраняется в постоянном хранилище, ses — только в памяти процесса. При Options(isReturnUserInfo = true) SDK запрашивает объект user; без него идентификаторы обновятся только если сервер всё равно вернул user.
Это означает:
- неавторизованный пользователь идентифицируется SDK автоматически;
uidиsesне нужно передавать вручную, если вы используете SDK-managed режим;- после логина рекомендуется отправить
LoginEvent, чтобы связать анонимный и авторизованный профили.
Ручная идентификация через setUser
Если приложение уже управляет идентификатором пользователя и сессии, можно задать их явно.
Пример:
GravitySDK.instance.setUser(
userId = "user-from-my-system-42",
sessionId = "session-from-my-system-xyz",
)
userId записывается в user.custom, sessionId — в user.ses. Это внешний ID приложения, а не подмена user.uid.
С версии 1.1.0 значения из setUser() используются в /visit, /event и /choose: при загрузке по selector, группе и ID кампании, в inline-компонентах и при автоматическом показе in-app. Ранее ручная идентификация применялась только к просмотрам и событиям.
Автоматический запрос сохраняет пользователя на время цепочки от просмотра/события до загрузки контента. Смена userId или sessionId отменяет ожидающий автопоказ для прежнего пользователя. Новый контент запрашивайте после установки актуальной идентификации; уже открытый UI этим вызовом не закрывается.
Серверный UID
С 1.3.0 приложение может прочитать, сбросить и восстановить серверный UID, который SDK получает в user.uid:
// Сохраните UID вместе с аккаунтом приложения.
val uid = GravitySDK.instance.getUserId()
// Выход из аккаунта.
try {
GravitySDK.instance.resetUser()
} catch (e: Exception) {
// Хранилище не удалило UID: сессия и setUser уже сброшены, решите, повторять ли удаление.
}
// Повторный вход в тот же аккаунт.
GravitySDK.instance.restoreUserId(savedUid)
Правила:
restoreUserIdобрезает пробелы по краям; пустая или состоящая из пробелов строка вызываетIllegalArgumentException. Следующий запрос отправляется с этим UID; неизвестный серверу UID сервер может заменить.resetUserиrestoreUserIdсбрасывают сессию и пользователя изsetUser. Ожидающий автопоказ отменяется, inline-кэш очищается; уже открытый UI не закрывается. Ожидающая доставка visible impression сохраняется.- Ошибка хранилища передаётся вызывающему коду. Если
resetUserне удалил UID с диска, UID в памяти уже сброшен. ЕслиrestoreUserIdне сохранил новый UID, остаётся прежний сохранённый UID, и следующий запрос использует его. - Listener один на весь процесс: он сохраняется после
dispose()и повторной инициализации и вызывается асинхронно на главном потоке. Чтение сохранённого UID listener не вызывает; ответы сервера иrestoreUserIdвызывают.resetUserвызывает listener, только если UID ранее существовал или уже был опубликован.
UID хранится в SharedPreferences приложения; хранилище настраивается в initialize(context). С 1.3.0 SDK не зависит от multiplatform-settings-no-arg.
Методы идентификации доступны и до initialize(...). В этом случае getUserId() ждёт инициализации, а resetUser() и restoreUserId() сразу применяют изменение в памяти и завершаются после инициализации и записи в хранилище. Listener можно установить заранее.
Выход и смена аккаунта
С 1.3.0 при выходе вызывайте resetUser(): SDK удалит серверный UID и пользователя из setUser. Если в приложение снова входит прежний аккаунт, восстановите его UID через restoreUserId(...), новому аккаунту задайте setUser(...) и отправьте LoginEvent. Повторный initialize(...) сбрасывает пользователя из setUser, но не удаляет серверный UID. Сигнатуры.
Вход в систему (LoginEvent)
val loginEvent = LoginEvent(
cuid = sha256Hex(normalizePhone(rawPhoneNumber)),
cuidType = "phone_hash",
)
Поле hashedEmail опционально. Если email не является обязательным в вашем процессе регистрации или логина, его можно не передавать.
Для LoginEvent рекомендуется использовать единый идентификатор phone_hash. Если проект использует другой cuid, он должен быть согласован и одинаково использоваться во всех каналах интеграции.
Отправляйте login/signup после успешной авторизации, с тем же CUID, что в других каналах. Как отправлять события.