Получение пейволов и продуктов для пейволов с Remote Config в iOS SDK

Прежде чем показывать пейволы с Remote Config и кастомные пейволы, нужно получить информацию о них. Обратите внимание: этот раздел посвящён пейволам с Remote Config и кастомным пейволам. Если вы работаете с пейволами, созданными в Paywall Builder, обратитесь к соответствующим гайдам: гайды по получению пейволов Paywall Builder в вашем приложении iOS, Android, React Native, Flutter, и Unity .

Хотите увидеть реальный пример интеграции Adapty SDK в мобильное приложение? Посмотрите наши примеры приложений — они демонстрируют полную настройку: отображение пейволов, совершение покупок и другие базовые функции.

Перед тем как начать получать пейволы и продукты в мобильном приложении (нажмите, чтобы развернуть)

Создайте продукты в дашборде Adapty.
Создайте пейвол и добавьте в него продукты в дашборде Adapty.
Создайте плейсменты и добавьте пейвол в плейсмент в дашборде Adapty.
Установите Adapty SDK в своём мобильном приложении.

Получение информации о пейволе

В Adapty продукт объединяет товары из App Store и Google Play. Эти кроссплатформенные продукты добавляются в пейволы, чтобы показывать их в нужных плейсментах мобильного приложения.

Чтобы отобразить продукты, нужно получить Paywall из одного из ваших плейсментов с помощью метода getPaywall.

Не хардкодьте идентификаторы продуктов. Единственный ID, который стоит хардкодить, — это идентификатор плейсмента. Пейволы настраиваются удалённо, поэтому количество продуктов и доступные офферы могут меняться в любой момент. Приложение должно обрабатывать эти изменения динамически: если сегодня пейвол возвращает два продукта, а завтра три — отображайте все без изменений в коде.

do {
    let paywall = try await Adapty.getPaywall(placementId: "YOUR_PLACEMENT_ID")
    // the requested paywall
} catch {
    // handle the error
}

Adapty.getPaywall(placementId: "YOUR_PLACEMENT_ID", locale: "en") { result in
    switch result {
        case let .success(paywall):
            // the requested paywall
        case let .failure(error):
            // handle the error
    }
}

Параметр	Наличие	Описание
placementId	обязательный	Идентификатор плейсмента. Это значение вы указали при создании плейсмента в дашборде Adapty.
locale	опциональный по умолчанию: `en`	Идентификатор локализации пейвола. Ожидается языковой код, состоящий из одного или нескольких подтегов, разделённых символом минус (-). Первый подтег — язык, второй — регион. Пример: `en` — английский, `pt-br` — бразильский португальский. Подробнее о кодах локалей — в разделе Локализации и коды локалей.
fetchPolicy	по умолчанию: `.reloadRevalidatingCacheData`	По умолчанию SDK пытается загрузить данные с сервера и возвращает кешированные данные в случае ошибки. Мы рекомендуем этот вариант, так как он гарантирует получение самых актуальных данных. Однако если у ваших пользователей нестабильное интернет-соединение, рассмотрите вариант `.returnCacheDataElseLoad` — он вернёт кешированные данные при их наличии. В этом случае пользователи могут получить не самые свежие данные, зато загрузка будет быстрее вне зависимости от качества соединения. Кеш регулярно обновляется, поэтому его безопасно использовать в течение сессии для сокращения сетевых запросов. Кеш сохраняется при перезапуске приложения и очищается только при переустановке или ручной очистке. Adapty SDK хранит пейволы в двух слоях: регулярно обновляемый кеш (описан выше) и резервные пейволы. Для ускорения загрузки используется CDN, а при его недоступности — отдельный резервный сервер. Эта система обеспечивает получение актуальных пейволов и надёжность даже при слабом интернете.
loadTimeout	по умолчанию: 5 сек	Ограничивает таймаут этого метода. При его истечении будут возвращены кешированные данные или локальный фолбэк. Обратите внимание: в редких случаях метод может завершиться немного позже указанного в `loadTimeout`, так как операция может включать несколько запросов под капотом.

Не хардкодьте идентификаторы продуктов! Поскольку пейволы настраиваются удалённо, доступные продукты, их количество и специальные офферы (например, бесплатные пробные периоды) могут меняться со временем. Убедитесь, что ваш код обрабатывает эти сценарии.
Например, если изначально вы получаете 2 продукта, приложение должно показывать 2 продукта. Если позже вы получите 3 продукта, приложение должно показать все 3 без изменений в коде. Хардкодить нужно только идентификатор плейсмента.

Параметры ответа:

Параметр	Описание
Paywall	Объект `AdaptyPaywall` со списком идентификаторов продуктов, идентификатором пейвола, Remote Config и рядом других свойств.

Получение продуктов

После получения пейвола можно запросить массив продуктов, соответствующих ему:

do {
    let products = try await Adapty.getPaywallProducts(paywall: paywall)
    // the requested products array
} catch {
    // handle the error
}

Adapty.getPaywallProducts(paywall: paywall) { result in    
    switch result {
    case let .success(products):
        // the requested products array
    case let .failure(error):
        // handle the error
    }
}

Параметры ответа:

Параметр	Описание
Products	Список объектов `AdaptyPaywallProduct` с идентификатором продукта, названием, ценой, валютой, длительностью подписки и рядом других свойств.

При реализации собственного дизайна пейвола вам, скорее всего, понадобятся свойства объекта AdaptyPaywallProduct. Ниже перечислены наиболее часто используемые из них; полный список доступен в документации по ссылке.

Свойство	Описание
Title	Для отображения названия продукта используйте `product.localizedTitle`. Локализация основана на стране магазина, выбранной пользователем, а не на локали устройства.
Price	Для отображения цены в локализованном формате используйте `product.localizedPrice`. Локализация основана на настройках локали устройства. Цену в числовом виде можно получить через `product.price` — значение будет в местной валюте. Символ валюты доступен через `product.currencySymbol`.
Subscription Period	Для отображения периода (например, неделя, месяц, год) используйте `product.localizedSubscriptionPeriod`. Локализация основана на локали устройства. Для программного доступа к периоду используйте `product.subscriptionPeriod`. Через него можно получить enum `unit` с длительностью (день, неделя, месяц, год или unknown), а `numberOfUnits` — количество единиц периода. Например, для квартальной подписки в `unit` будет `.month`, а в `numberOfUnits` — `3`.
Introductory Offer	Для отображения бейджа или другого индикатора introductory offer используйте свойство `product.subscriptionOffer`. Оно содержит следующие полезные поля: • `offerType`: enum со значениями `introductory`, `promotional` и `winBack`. Бесплатные пробные периоды и начальные скидки будут типа `introductory`. • `price`: сумма скидки в числовом виде. Для бесплатных пробных периодов здесь будет `0`. • `localizedPrice`: отформатированная цена скидки для локали пользователя. • `localizedNumberOfPeriods`: строка в локали устройства с описанием длительности оффера. Например, для трёхдневного пробного периода здесь будет `3 days`. • `subscriptionPeriod`: отдельные параметры периода оффера — работает так же, как описано в предыдущем разделе. • `localizedSubscriptionPeriod`: отформатированный период подписки для локали пользователя.

Проверка доступности introductory offer на iOS

По умолчанию метод getPaywallProducts проверяет доступность introductory offer, promotional offer и win-back offer. Если нужно показать продукты до того, как SDK определит доступность офферов, используйте метод getPaywallProductsWithoutDeterminingOffer.

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

do {
    let products = try await Adapty.getPaywallProductsWithoutDeterminingOffer(paywall: paywall)
    // the requested products array without subscriptionOffer
} catch {
    // handle the error
}

Adapty.getPaywallProductsWithoutDeterminingOffer(paywall: paywall) { result in    
    switch result {
    case let .success(products):
        // the requested products array without subscriptionOffer
    case let .failure(error):
        // handle the error
    }
}

Ускорение загрузки пейвола с помощью пейвола для аудитории по умолчанию

Как правило, пейволы загружаются практически мгновенно, и беспокоиться об ускорении этого процесса не нужно. Однако если у вас много аудиторий и пейволов, а у пользователей слабое интернет-соединение, загрузка может занять больше времени, чем хотелось бы. В таких ситуациях лучше показать пейвол по умолчанию, чем не показывать ничего.

Для этого можно использовать метод getPaywallForDefaultAudience, который получает пейвол указанного плейсмента для аудитории All Users. Тем не менее рекомендуемый подход — использовать метод getPaywall, как описано в разделе Получение информации о пейволе выше.

Почему мы рекомендуем использовать getPaywall

Метод getPaywallForDefaultAudience имеет ряд существенных недостатков:

Возможные проблемы с обратной совместимостью: если нужно показывать разные пейволы для разных версий приложения (текущей и будущих), могут возникнуть сложности. Придётся либо создавать пейволы с поддержкой текущей (устаревшей) версии, либо мириться с тем, что пользователи этой версии могут столкнуться с проблемами отрисовки пейволов.
Потеря таргетинга: все пользователи будут видеть один и тот же пейвол, предназначенный для аудитории All Users, — вы теряете персонализированный таргетинг (в том числе по странам, маркетинговой атрибуции или собственным атрибутам).

Если вы готовы принять эти ограничения ради более быстрой загрузки пейволов, используйте метод getPaywallForDefaultAudience следующим образом. В противном случае придерживайтесь метода getPaywall, описанного выше.

do {
    let paywall = try await Adapty.getPaywallForDefaultAudience("YOUR_PLACEMENT_ID")
   // the requested paywall
} catch {
    // handle the error
}

Adapty.getPaywallForDefaultAudience(placementId: "YOUR_PLACEMENT_ID", locale: "en") { result in
    switch result {
        case let .success(paywall):
            // the requested paywall
        case let .failure(error):
            // handle the error
    }
}

Метод getPaywallForDefaultAudience доступен начиная с версии iOS SDK 2.11.2.

Параметр Наличие Описание

placementId обязательный Идентификатор плейсмента. Это значение вы указали при создании плейсмента в дашборде Adapty.

locale

опциональный

по умолчанию: en

Идентификатор локализации пейвола. Ожидается языковой код, состоящий из одного или нескольких подтегов, разделённых символом минус (-). Первый подтег — язык, второй — регион.

Пример: en — английский, pt-br — бразильский португальский.

Подробнее о кодах локалей — в разделе Локализации и коды локалей.

fetchPolicy

по умолчанию: .reloadRevalidatingCacheData

По умолчанию SDK пытается загрузить данные с сервера и возвращает кешированные данные в случае ошибки. Мы рекомендуем этот вариант, так как он гарантирует получение самых актуальных данных.

Однако если у ваших пользователей нестабильное интернет-соединение, рассмотрите вариант .returnCacheDataElseLoad — он вернёт кешированные данные при их наличии. В этом случае пользователи могут получить не самые свежие данные, зато загрузка будет быстрее вне зависимости от качества соединения. Кеш регулярно обновляется, поэтому его безопасно использовать в течение сессии для сокращения сетевых запросов.

Кеш сохраняется при перезапуске приложения и очищается только при переустановке или ручной очистке.