Справочник 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)
Поле Options По умолчанию
isReturnCounter false
isReturnUserInfo false
isReturnAnalyticsMetadata false
isImplicitPageview false
isImplicitImpression true
isBuildEngagementUrl true, без публичного параметра для изменения

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] = [:]
    )

Ответ и модели

Тип/поле Содержание
ContentResponse Опциональный user и список data с кампаниями
Campaign.payload Список вариантов CampaignVariation
CampaignVariation Идентификаторы решения и список contents
CampaignContent contentId, deliveryMethod, step, variables, products, items, custom, events
content.variables Типизированные frameUI, elements и действия жизненного цикла; может отсутствовать
GravityDataResponse<ContentResponse> data — модель; json: JSONValue — исходный JSON того же ответа; с 1.3.0 delayTime: Int — задержка в мс, ненулевая только в headless-режиме
ContentLoadEvent.delayTime С 1.3.0: та же задержка для контента из trackViewNoShow/triggerEventNoShow; в остальных случаях 0
content.rawVariables [String: JSONValue] со всеми ключами variables, включая неизвестные модели и null
content.variables?.raw / content.variables?["key"] Полный объект переменных / чтение отдельного ключа
content.custom?.json Строка пользовательского JSON, разбирается приложением
Slot item, strId, опциональный slotId, fallback и tracking-события
Style.gridSettings С 1.3.0: GridSettings с columns, horizontalSpacing, verticalSpacing (Double?) для товарной сетки

В 1.2.0 добавлены rawVariables и два метода WithDetails, в 1.3.0 — headless-режим с trackViewNoShow и triggerEventNoShow.

События TriggerEvent

С 1.2.0 у всех событий есть необязательные customProps: [String: String]? и eventTime: Date?. Значения свойств — только строки. SDK отправляет время в UTC (RFC 3339); если время не указано, фиксирует момент вызова triggerEvent(...), до асинхронной отправки. Пример.

Событие Основные параметры
AddToCartEvent value, productId, quantity, currency?, cart?
PurchaseEvent uniqueTransactionId, value, cart, currency?
RemoveFromCartEvent value, productId, quantity, currency?, cart?
SyncCartEvent value, currency?, cart?
AddToWishlistEvent value, productId
SignUpEvent hashedEmail?, cuid?, cuidType?
LoginEvent hashedEmail?, cuid?, cuidType?
CustomEvent type, name, customProps?, cuid?, cuidType?, cart?, eventTime?

Engagement-типы

Содержимое Публичные типы
Контент ContentImpressionEngagement, ContentVisibleImpressionEngagement, ContentCloseEngagement
Товары ProductClickEngagement, ProductVisibleImpressionEngagement

Передавайте исходные content, campaign и slot из ответа SDK. Публичного ContentClickEngagement нет; ручная отправка engagement не вызывает tracking callback. Условия учёта показов.

UI-компоненты

Компонент Параметры
GravityInlineSwiftUIView selector, pageContext, с 1.3.0 rules; перегрузка с @ViewBuilder loader
GravityInlineView init(selector:rules:), затем initialize(pageContext:); перегрузка с loader; свойство rules
GravityInlineListView init(groupSelector:rules:), затем initialize(pageContext:); перегрузка с loader; свойство rules
UISettings fontName: String?
// 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
}

Примеры карточек.