Свой UI и Custom JSON в iOS

Используйте этот путь, когда приложение само рисует кампанию или рекомендации. SDK получает контент и отправляет content load tracking; видимость, клики и навигацию определяет приложение. Сначала выполните инициализацию.

getContentBySelector(selector:pageContext:)

Используйте этот метод для manual rendering и кастомного UI.

let response = await GravitySDK.instance.getContentBySelector(
    selector: "homepage-recommendations",
    pageContext: PageContext(
        type: .homepage,
        data: [],
        location: "app://homepage"
    )
)

if let response {
    // Разберите response.data и постройте собственный UI.
}

Для вызова требуется корректно заполненный PageContext.

Что важно учесть:

  • успешный getContentBySelector(...) автоматически запускает content load tracking для всех contents, пришедших в response;
  • при сетевой ошибке или ошибке декодирования метод возвращает nil и пишет SDK-лог;
  • это означает, что ContentLoadEvent может прийти в gravityEventCallback сразу после загрузки контента, даже если UI еще не был показан пользователю;
  • impression / visible impression / click для manual widget SDK автоматически не отправляет: приложение по-прежнему должно вызвать sendContentEngagement(...) и sendProductEngagement(...) самостоятельно.

Загрузка по группе и ID кампании

Для группы и ID кампании используйте getContentByGroupSelector(...) и getContentByCampaignId(...): сигнатуры.

Методы загрузки по группе и ID кампании возвращают ту же структуру ContentResponse?, автоматически отправляют content load tracking и не показывают UI. Все методы выбора контента используют Options и ContentSettings, установленные через setOptions(...).

С 1.3.0 все методы getContentBy* принимают необязательный rules — например, фильтры каталога, выбранные пользователем: правила рекомендаций. Если за время запроса пользователь сменился через setUser, resetUser или restoreUserId, метод возвращает nil, чтобы приложение не показало контент прежнего пользователя.

Исходный JSON и переменные кампании

С 1.2.0 getContentBySelectorWithDetails(...) и getContentByCampaignIdWithDetails(...) возвращают модель и исходный JSON одного ответа. Например, если в variables кампании задан ключ button_title:

let pageContext = PageContext(type: .homepage, data: [], location: "app://home")
let details = await GravitySDK.instance.getContentBySelectorWithDetails(
    selector: "homepage-banner-json",
    pageContext: pageContext
)

if let details {
    let response = details.data // ContentResponse; кампании находятся в response.data.
    let rawResponse = details.json // JSONValue всего ответа, а не строка.
    if let content = response.data.first?.payload.first?.contents.first {
        let title = content.rawVariables["button_title"]?.stringValue ?? "Подробнее"
        let sameTitle = content.variables?["button_title"]?.stringValue
        // Постройте UI приложения; campaign и content сохраните для engagement.
    }
}

// В Swift аргументы этого метода передаются без меток.
let byId = await GravitySDK.instance.getContentByCampaignIdWithDetails(
    "YOUR_CAMPAIGN_ID", pageContext
)

rawVariables имеет тип [String: JSONValue]; неизвестные модели ключи, вложенные объекты, массивы и JSON null сохраняются. Отсутствующий ключ возвращает nil, явный null — .null. Если variables отсутствует или Variables создан вручную, словарь пуст. Типизированные variables.frameUI и variables.elements доступны как раньше.

rawVariables доступен и после обычного getContentBy*: WithDetails нужен, когда требуется JSON всего ответа. Это отдельный источник данных от строки content.custom?.json, описанной ниже. Загрузка автоматически отправляет content load tracking; фактический показ и клики собственного UI отправляет приложение.

Custom JSON

Пользовательский JSON приходит в content.custom?.json как строка. SDK не декодирует её в модель приложения. Например, для кампании с JSON { "variant": "compact" }:

struct ExperimentConfig: Decodable {
    let variant: String
}

if let campaign = response?.data.first,
   let content = campaign.payload.first?.contents.first,
   let json = content.custom?.json,
   let data = json.data(using: .utf8) {
    do {
        let config = try JSONDecoder().decode(ExperimentConfig.self, from: data)
        // Покажите UI для config.variant. Для неизвестного значения используйте свой fallback.
    } catch {
        // Используйте стандартный UI приложения.
    }
}

Вариант A/B выбирает сервер; приложение использует полученный JSON и сохраняет исходные campaign/content для engagement. Полный сценарий A/B.

getContentBySelector(...) сам не показывает UI, но trackView(...) и triggerEvent(...) могут запустить автопоказ. Чтобы получать кампании по просмотру или событию и показывать их своим UI, используйте headless-режим. Presentation lock ограничивает новые in-app показы SDK, но не отменяет HTTP-запросы и content load tracking.

Headless-режим: trackViewNoShow и triggerEventNoShow

С 1.3.0 trackViewNoShow(pageContext:) и triggerEventNoShow(events:pageContext:) отправляют просмотр или события так же, как trackView и triggerEvent, но не открывают UI SDK. Вместо показа они возвращают GravityDataResponse<ContentResponse>? выбранной кампании: модель, исходный JSON ответа и delayTime. Для одного просмотра или действия вызывайте один метод: обычный или NoShow.

let pageContext = PageContext(type: .product, data: ["sku-123"], location: "app://product/sku-123")

Task {
    do {
        guard let details = try await GravitySDK.instance.trackViewNoShow(pageContext: pageContext),
              let campaign = details.data.data.first,
              let content = campaign.payload.first?.contents.first(where: { $0.step == nil })
        else { return } // Кампании нет, запрос устарел или пользователь сменился.

        if details.delayTime > 0 {
            // Задержка из настроек кампании, в миллисекундах. SDK её не выдерживает.
            try await Task.sleep(nanoseconds: UInt64(details.delayTime) * 1_000_000)
        }
        // Проверьте, что экран и пользователь не сменились, и покажите свой UI.
        showCampaign(campaign, content)
    } catch {
        // CancellationError: задача отменена, показывать нечего.
    }
}

showCampaign — функция приложения. Для события используйте triggerEventNoShow(events: [...], pageContext: pageContext) с тем же разбором ответа.

Как SDK выбирает контент:

  • кампании из ответа на просмотр/событие перебираются по убыванию priority; если у кандидата нет корневого контента (step == nil) или его загрузка не удалась, SDK пробует следующего;
  • content load tracking и ContentLoadEvent отправляются только для возвращённого ответа; ContentLoadEvent.delayTime совпадает с details.delayTime;
  • delayTime — целое число миллисекунд, 0 без задержки; отрицательные значения сервера приводятся к 0. Метод возвращает контент сразу, ждёт приложение;
  • nil означает, что отправка не удалась, подходящего контента нет, isFetchContentOnTrack выключен, запрос устарел или пользователь сменился; отмена задачи выбрасывает CancellationError.

В headless-режиме SDK не отправляет impression, visible impression и клики автоматически. После фактического показа отправьте ContentImpressionEngagement, при достижении порога видимости — ContentVisibleImpressionEngagement, для товаров — product engagement: правила аналитики.

Две настройки управляют только методами NoShow:

Свойство По умолчанию Назначение
isFetchContentOnTrack true При false просмотр или событие отправляются, но контент не загружается, метод возвращает nil
staleContentTimeout 10 секунд Максимальный возраст запроса с момента вызова; более старый результат не возвращается. Отрицательное значение становится 0
GravitySDK.instance.isFetchContentOnTrack = true
GravitySDK.instance.staleContentTimeout = 15

Настройки общие для процесса: их можно задать до initialize, они сохраняются при повторной инициализации, а изменение staleContentTimeout действует и на уже выполняющиеся запросы. Запросы используют текущие Options и ContentSettings из setOptions(...) без изменений. Сигнатуры.

Аналитика собственного UI

Загрузка не означает показ. Сохраните исходные campaign/content и при работе с товарами slot. Передавайте их в engagement после фактического взаимодействия:

Действие Тип engagement
Контент появился в интерфейсе ContentImpressionEngagement
Контент достиг порога видимости ContentVisibleImpressionEngagement
Контент закрыт ContentCloseEngagement
Карточка товара достигла порога видимости ProductVisibleImpressionEngagement
Пользователь нажал на товар ProductClickEngagement

Порог и дедупликацию реализует приложение. Встроенный iOS detector для inline/товаров использует 50% площади без задержки; в полном примере собственного рендерера выбрано 50% в течение секунды.

Публичного ContentClickEngagement нет. sendContentEngagement/sendProductEngagement вызывают tracking URL, но не gravityEventCallback. Для бизнес-действий отправляйте TriggerEvent отдельно. Справочник engagement.