Идентификация пользователя в iOS

SDK поддерживает два режима идентификации: SDK-managed и ручной.

Стандарт CUID на основе телефона (phone_hash)

Для LoginEvent и SignUpEvent рекомендуется использовать единый идентификатор пользователя — SHA-256 хеш нормализованного телефона.

Правила:

  • номер очищается от всех символов, кроме цифр;
  • для РФ и КЗ номер приводится к формату 7XXXXXXXXXX;
  • хеш считается по UTF-8 строке;
  • результат передается в lowercase hex;
  • в LoginEvent.cuidType используется строка "phone_hash".

SDK-managed режим

Если setUser(...) не вызывать:

  • uid, если он возвращён сервером, сохраняется в UserDefaults;
  • ses, если он возвращён сервером, обновляется из ответов backend и хранится только в памяти процесса;
  • последующие запросы используют эти значения автоматически.

С 1.3.0 uid можно прочитать, восстановить или сбросить: см. ID пользователя.

После логина рекомендуется отправить LoginEvent, чтобы связать анонимный и авторизованный профили.

При Options(isReturnUserInfo: true) SDK запрашивает объект user; без него идентификаторы обновятся только если сервер всё равно вернул user.

Ручная идентификация через setUser

Если приложение управляет внешним ID пользователя и сессией, задайте их явно:

GravitySDK.instance.setUser(
    userId: "external-user-id",
    sessionId: "session-id"
)

userId передаётся как user.custom, а не заменяет uid; sessionId задаёт user.ses.

С версии 1.1.0 значения из setUser() используются в /visit, /event и /choose: при загрузке по selector, группе и ID кампании, в inline-компонентах и при автоматическом показе in-app. Ранее ручная идентификация применялась только к просмотрам и событиям.

Автоматический запрос сохраняет пользователя на время цепочки от просмотра/события до загрузки контента. Смена userId или sessionId отменяет ожидающий автопоказ для прежнего пользователя. Новый контент запрашивайте после установки актуальной идентификации; уже открытый UI этим вызовом не закрывается.

ID пользователя: getUserId, resetUser и restoreUserId

С 1.3.0 приложение может читать и менять серверный uid анонимного профиля, который SDK хранит на устройстве. Это не userId из setUser: getUserId() возвращает именно uid.

public func getUserId() async -> String?
public func setUserIdListener(_ listener: ((String?) -> Void)?)
public func resetUser() async throws
public func restoreUserId(_ uid: String) async throws

Типичный сценарий — сохранить историю пользователя после переустановки приложения. Приложение хранит uid на своём сервере вместе с аккаунтом и после входа восстанавливает его:

// После входа: сохраните uid вместе с аккаунтом (saveGravityUserId — метод приложения).
if let uid = await GravitySDK.instance.getUserId() {
    try await saveGravityUserId(uid)
}

// После переустановки и входа: восстановите сохранённый uid.
do {
    try await GravitySDK.instance.restoreUserId(savedUid)
} catch GravityUserIdError.invalidUserId {
    // Пустая строка: идентификация не изменилась.
} catch {
    // storageWriteFailed: сессия сброшена, uid не записан, используется прежний.
}
Метод Поведение
getUserId() Возвращает uid или nil. Если анонимная сессия уже запрашивается, дожидается ответа, но новый запрос не создаёт. При отмене задачи возвращает nil
setUserIdListener(_:) Вызывается на главном потоке при новом uid от сервера, после restoreUserId и после resetUser (с nil). Повтор того же значения не приходит, текущее значение при подписке не передаётся. nil снимает подписку
resetUser() Очищает сессию, пользователя из setUser и сохранённый uid; следующий запрос откроет новую анонимную сессию
restoreUserId(_:) Обрезает пробелы по краям, сохраняет uid, сбрасывает сессию и пользователя из setUser; следующий запрос использует этот uid

Ошибки GravityUserIdError:

  • invalidUserId — restoreUserId получил пустую строку или только пробелы; идентификация не меняется;
  • storageWriteFailed — restoreUserId не смог записать uid. Сессия и пользователь из setUser уже сброшены, используется прежний uid;
  • storageRemovalFailed — resetUser не смог удалить uid из хранилища. В памяти идентификация всё равно сброшена, getUserId() возвращает nil.

Методы можно вызывать до initialize; подписка listener сохраняется при инициализации SDK. После смены пользователя через setUser, resetUser или restoreUserId SDK отменяет ожидающий автопоказ, а getContentBy* и headless-методы не возвращают контент, загруженный для прежнего пользователя. Inline-компоненты повторяют незавершённую загрузку уже для нового пользователя. Сохранённые ранее WRIMP доставляются; модальный показ, ещё не подтверждённый для прежнего пользователя, не учитывается.

Выход и смена аккаунта

С 1.3.0 при выходе из аккаунта вызовите resetUser(): он сбрасывает и пользователя из setUser, и анонимный uid. Возврата из ручного режима через setUser(nil) нет. Не заменяйте выход повторной инициализацией SDK: идентификаторы при этом сохраняются. При входе в другой аккаунт задайте setUser(...) и отправьте LoginEvent.

do {
    try await GravitySDK.instance.resetUser()
} catch {
    // storageRemovalFailed: в памяти пользователь уже сброшен.
}

LoginEvent

let login = LoginEvent(
    cuid: sha256PhoneHash,
    cuidType: "phone_hash"
)

Отправляйте login/signup после успешной авторизации, с тем же CUID, что в других каналах. Как отправлять события.