Свой 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-режим: 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:
GravitySDK.instance.isFetchContentOnTrack = true
GravitySDK.instance.staleContentTimeout = 15
Настройки общие для процесса: их можно задать до initialize, они сохраняются при повторной инициализации, а изменение staleContentTimeout действует и на уже выполняющиеся запросы. Запросы используют текущие Options и ContentSettings из setOptions(...) без изменений. Сигнатуры.
Аналитика собственного UI
Загрузка не означает показ. Сохраните исходные campaign/content и при работе с товарами slot. Передавайте их в engagement после фактического взаимодействия:
Порог и дедупликацию реализует приложение. Встроенный iOS detector для inline/товаров использует 50% площади без задержки; в полном примере собственного рендерера выбрано 50% в течение секунды.
Публичного ContentClickEngagement нет. sendContentEngagement/sendProductEngagement вызывают tracking URL, но не gravityEventCallback. Для бизнес-действий отправляйте TriggerEvent отдельно. Справочник engagement.