Справочник iOS SDK 1.3.0
Сигнатуры сверены с публичным исходным кодом. Примеры настройки — в Конфигурации, бизнес-сценарии — в Контексте и событиях.
Инициализация и настройки
public static var isInitialized: Bool { get }
public static var instance: GravitySDK { get }
public static func initialize(
apiKey: String,
section: String,
gravityEventCallback: GravityEventCallback? = nil,
productViewBuilder: ProductViewBuilder? = nil,
productFilter: ProductFilter? = nil,
uiSettings: UISettings? = nil,
logLevel: LogLevel = .error
)
public func setOptions(
options: Options?,
contentSettings: ContentSettings?,
proxyUrl: String?
)
public func setNotificationPermissionStatus(
status: NotificationPermissionStatus
)
public func setLogListener(_ listener: GravityLogListener?)
Типы callback
public typealias ProductFilter = (Slot) -> Bool
public typealias GravityEventCallback = (TrackingEvent) -> Void
public typealias GravityLogListener = @Sendable (LogLevel, String) -> Void
Идентификация
public func setUser(userId: String, sessionId: String)
// С 1.3.0
public func getUserId() async -> String?
public func setUserIdListener(_ listener: ((String?) -> Void)?)
public func resetUser() async throws
public func restoreUserId(_ uid: String) async throws
public enum GravityUserIdError: Error, Equatable {
case invalidUserId
case storageWriteFailed
case storageRemovalFailed
}
setUser задаёт custom/ses для просмотров, событий и запросов контента, включая inline и автопоказ. Правила идентификации.
С 1.3.0 getUserId() возвращает серверный uid анонимного профиля (не userId из setUser), setUserIdListener сообщает о его изменениях на главном потоке. resetUser() очищает uid, сессию и пользователя из setUser; restoreUserId(_:) устанавливает ранее полученный uid. Методы можно вызывать до initialize. Сценарии и ошибки.
Просмотры и события
public func trackView(
pageContext: PageContext,
viewController: UIViewController? = nil
)
public func triggerEvent(
events: [TriggerEvent],
pageContext: PageContext,
viewController: UIViewController? = nil
)
Загрузка контента
public func getContentBySelector(
selector: String,
pageContext: PageContext,
rules: [RtRule]? = nil
) async -> ContentResponse?
public func getContentByGroupSelector(
groupSelector: String,
pageContext: PageContext,
rules: [RtRule]? = nil
) async -> ContentResponse?
public func getContentByCampaignId(
_ campaignId: String,
_ pageContext: PageContext,
rules: [RtRule]? = nil
) async -> ContentResponse?
Ошибка возвращает nil; успешный ответ может содержать пустой data. Эти методы не показывают UI, но отправляют content load tracking. С 1.3.0 метод также возвращает nil, если за время запроса пользователь сменился через setUser, resetUser или restoreUserId: контент прежнего пользователя не передаётся приложению. Параметр rules добавлен в 1.3.0:
Загрузка исходного JSON
public func getContentBySelectorWithDetails(
selector: String,
pageContext: PageContext,
rules: [RtRule]? = nil
) async -> GravityDataResponse<ContentResponse>?
public func getContentByCampaignIdWithDetails(
_ campaignId: String,
_ pageContext: PageContext,
rules: [RtRule]? = nil
) async -> GravityDataResponse<ContentResponse>?
GravityDataResponse.data — модель ContentResponse, json — весь ответ как JSONValue. Тип сохраняет строки, целые числа (Int64), дробные числа, boolean, массивы, объекты и JSON null. Для чтения доступны stringValue, intValue, int64Value, doubleValue, boolValue, arrayValue, objectValue, isNull и индексы по ключу/позиции.
Оба метода доступны с 1.2.0. Они возвращают модель и JSON одного ответа, отправляют content load tracking и не показывают UI. Ошибка запроса или разбора возвращает nil. Версии WithDetails для группы нет. Примеры чтения.
С 1.3.0 у GravityDataResponse есть поле delayTime: Int. Для getContentBy*WithDetails оно всегда 0; задержку выбранной кампании возвращают только методы headless-режима.
Headless-режим
// С 1.3.0
public var isFetchContentOnTrack: Bool { get set } // по умолчанию true
public var staleContentTimeout: TimeInterval { get set } // секунды, по умолчанию 10
public func trackViewNoShow(
pageContext: PageContext
) async throws -> GravityDataResponse<ContentResponse>?
public func triggerEventNoShow(
events: [TriggerEvent],
pageContext: PageContext
) async throws -> GravityDataResponse<ContentResponse>?
Методы отправляют просмотр или события и возвращают контент кампании без UI. Кандидаты перебираются по убыванию priority, пока не найдётся кампания с корневым контентом. delayTime — задержка выбранной кампании в миллисекундах; SDK её не выдерживает. Impression, visible impression и клики приложение отправляет само.
nil возвращается, если отправка не удалась, ни один кандидат не дал контента, isFetchContentOnTrack == false, запрос старше staleContentTimeout или сменился пользователь. Отмена задачи выбрасывает CancellationError. Обе настройки общие для процесса, сохраняются при повторной initialize и действуют только на NoShow; отрицательный staleContentTimeout становится 0. Сценарий и пример.
Правила рекомендаций
// С 1.3.0
public struct RtRule: Codable, Equatable {
public init(id: Int? = nil, type: String, slots: [Int]? = nil, conditions: [RtRuleCondition])
}
public struct RtRuleCondition: Codable, Equatable {
public init(field: String, arguments: [RtRuleArgument])
}
public struct RtRuleArgument: Codable, Equatable {
public init(action: String, value: [String])
}
rules принимают getContentBySelector, getContentByCampaignId, getContentByGroupSelector, оба метода WithDetails и inline-компоненты. SDK передаёт правила в поле rules элемента запроса /choose; nil — без правил. Допустимые type, field и action определяет конфигурация проекта. Пример с фильтрами каталога.
Engagement
public func sendContentEngagement(engagement: ContentEngagement)
public func sendProductEngagement(engagement: ProductEngagement)
Presentation lock
public func lockPresentation()
public func unlockPresentation()
public func setPresentationLockListener(_ listener: ((Bool) -> Void)?)
Подготовка и закрытие in-app
В 1.1.0 добавлена перегрузка initialize с последним параметром inAppPreparation. Основная сигнатура продолжает работать без изменений:
public static func initialize(
apiKey: String,
section: String,
gravityEventCallback: GravityEventCallback? = nil,
productViewBuilder: ProductViewBuilder? = nil,
productFilter: ProductFilter? = nil,
uiSettings: UISettings? = nil,
logLevel: LogLevel = .error,
inAppPreparation: InAppPreparation?
)
public typealias InAppPreparationHandler =
(CampaignContent, Campaign) async throws -> CampaignContent?
// Инициализатор InAppPreparation
public init(timeout: TimeInterval = 5, handler: @escaping InAppPreparationHandler)
// Метод CampaignContent
public func filteringProducts(_ predicate: (Slot) -> Bool) -> CampaignContent?
public func dismissInApp(
contentId: String,
completion: @escaping (Bool) -> Void = { _ in }
)
inAppPreparation выполняется перед автопоказом и при openStep, после productFilter, content load tracking и задержки кампании. Возврат nil, ошибка или таймаут пропускают этот in-app. timeout задаётся в секундах: конечное число больше 0 и не больше 3600. Используйте отменяемые async-запросы. Ручные getContentBy* и inline не запускают подготовку.
filteringProducts сохраняет исходные слоты, порядок, события и метаданные. Если товаров не осталось или товарного блока нет, возвращается nil; SDK не догружает замену удалённым товарам.
dismissInApp закрывает показанный SDK in-app с указанным contentId. Completion получает true на главном потоке после закрытия UI; false — если подходящего показа нет или он уже закрывается. SDK отправляет close один раз, product click отправляет приложение. Inline не закрывается.
Настройка и полный пример отзывов.
Настройки запросов
// Options
public init(
isReturnCounter: Bool = false,
isReturnUserInfo: Bool = false,
isReturnAnalyticsMetadata: Bool = false,
isImplicitPageview: Bool = false,
isImplicitImpression: Bool = true
)
// ContentSettings
public init(
skusOnly: Bool = false,
fields: [String]? = nil
)
// UISettings
public init(fontName: String? = nil)
ContentSettings: skusOnly по умолчанию false, fields — nil. Оба объекта заменяются целиком через setOptions.
PageContext
// PageContext: Codable, Equatable
public init(
type: ContextType,
data: [String],
location: String,
lng: String? = nil,
pageNumber: Int? = nil,
referrer: String? = nil,
utm: [String: String]? = nil,
attributes: [String: String] = [:]
)
Ответ и модели
В 1.2.0 добавлены rawVariables и два метода WithDetails, в 1.3.0 — trackViewNoShow и triggerEventNoShow.
События TriggerEvent
С 1.2.0 у всех событий есть необязательные customProps: [String: String]? и eventTime: Date?. Значения свойств — только строки. SDK отправляет время в UTC (RFC 3339); если время не указано, фиксирует момент вызова triggerEvent(...), до асинхронной отправки. Пример.
Engagement-типы
Передавайте исходные content, campaign и slot из ответа SDK. Публичного ContentClickEngagement нет; ручная отправка engagement не вызывает tracking callback. Условия учёта показов.
UI-компоненты
// GravityInlineSwiftUIView
public init(selector: String, pageContext: PageContext, rules: [RtRule]? = nil)
public init<Loader: View>(
selector: String,
pageContext: PageContext,
rules: [RtRule]? = nil,
@ViewBuilder loader: () -> Loader
)
// GravityInlineView
public convenience init(selector: String, rules: [RtRule]? = nil)
public var rules: [RtRule]? { get set }
public func initialize(pageContext: PageContext)
public func initialize<Loader: View>(
pageContext: PageContext,
@ViewBuilder loader: () -> Loader
)
// GravityInlineListView
public convenience init(groupSelector: String, rules: [RtRule]? = nil)
public var rules: [RtRule]? { get set }
public func initialize(pageContext: PageContext)
public func initialize<Loader: View>(
pageContext: PageContext,
@ViewBuilder loader: () -> Loader
)
public protocol ProductViewBuilder {
@ViewBuilder
func build(
slot: Slot,
content: CampaignContent,
campaign: Campaign
) -> AnyView
}
public protocol LegacyProductViewBuilder: ProductViewBuilder {
func createView(
slot: Slot,
content: CampaignContent,
campaign: Campaign
) -> UIView
}