Идентификация пользователя в 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:

Метод Назначение
suspend fun getUserId(): String? Сохранённый серверный UID; ждёт уже идущую инициализацию сессии
fun setUserIdListener(listener: ((String?) -> Unit)?) Подписка на изменения UID; null снимает подписку
suspend fun resetUser() Сбрасывает сессию, пользователя из setUser и удаляет сохранённый UID
suspend fun restoreUserId(uid: String) Восстанавливает UID, ранее полученный через getUserId()
// Сохраните 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, что в других каналах. Как отправлять события.