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

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

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

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

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

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

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

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

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

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

Adapty.getFlow(placementId: "YOUR_PLACEMENT_ID") { result in
    switch result {
        case let .success(flow):
            // the requested flow
        case let .failure(error):
            // handle the error
    }
}

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

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

fetchPolicy

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

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

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

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

Adapty SDK хранит флоу и пейволы в двух слоях: регулярно обновляемый кеш, описанный выше, и резервные пейволы. Для ускоренной загрузки флоу и пейволов также используется CDN, а на случай его недоступности — отдельный резервный сервер.

loadTimeout

по умолчанию: 5 сек

Это значение ограничивает таймаут метода. При его истечении возвращаются кешированные данные или локальный резерв.

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

В v4 параметр locale перенесён из getFlow в getFlowConfiguration (используется только при рендеринге через AdaptyUI). Для кастомных пейволов все доступные локали возвращаются вместе в flow.remoteConfigs — выберите ту, которая соответствует языку устройства пользователя или настройкам вашего приложения.

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

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

Параметр	Описание
Flow	Объект `AdaptyFlow`, содержащий плейсмент, идентификаторы (`id`, `variationId`), название, массив `remoteConfigs` (по одной записи на каждую настроенную локаль) и флаг `hasViewConfiguration`. Чтобы получить продукты для флоу, вызовите `getPaywallProducts(flow:)`.

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

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

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

Adapty.getPaywallProducts(flow: flow) { result in
    switch result {
    case let .success(products):
        // запрошенный массив продуктов
    case let .failure(error):
        // обработка ошибки
    }
}

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

Параметр	Описание
Products	Список объектов `AdaptyPaywallProduct` с идентификатором продукта, его названием, ценой, валютой, длительностью подписки и рядом других свойств.
При реализации собственного дизайна пейвола вам, скорее всего, понадобятся свойства объекта `AdaptyPaywallProduct`. Ниже показаны наиболее часто используемые свойства, однако полный список доступных свойств приведён в документации по ссылке.
Свойство	Описание
-------------------------	----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
Title	Чтобы отобразить название продукта, используйте `product.localizedTitle`. Локализация основана на стране стора, выбранной пользователем, а не на локали устройства.
Price	Чтобы отобразить локализованную цену, используйте `product.localizedPrice`. Локализация основана на локали устройства. Цену в числовом виде можно получить через `product.price` — значение будет в местной валюте. Для получения символа валюты используйте `product.currencySymbol`.
Subscription Period	Чтобы отобразить период (например, неделя, месяц, год и т. д.), используйте `product.localizedSubscriptionPeriod`. Локализация основана на локали устройства. Для программного получения периода подписки используйте `product.subscriptionPeriod`. Из этого объекта доступен enum `unit` с единицей периода (day, week, month, year или 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`: отформатированный период подписки скидочного предложения для локали пользователя.

В v4 все продукты, возвращаемые методом getPaywallProducts(flow:), уже содержат информацию о подходящих офферах. Отдельный вызов getPaywallProductsWithoutDeterminingOffer из v3 был удалён.

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

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

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

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

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

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

Adapty.getFlowForDefaultAudience(placementId: "YOUR_PLACEMENT_ID") { result in
    switch result {
        case let .success(flow):
            // запрошенный флоу
        case let .failure(error):
            // обработка ошибки
    }
}

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

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

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

fetchPolicy

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

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

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

Обратите внимание: кеш сохраняется при перезапуске приложения и очищается только при его переустановке или ручной очистке.

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

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

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

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

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

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

Не хардкодьте ID продуктов. Единственный ID, который можно захардкодить — это 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 для ускорения загрузки пейволов и отдельный резервный сервер на случай недоступности CDN. Эта система гарантирует, что вы всегда получаете актуальную версию пейволов, обеспечивая надёжность даже при слабом интернете.
loadTimeout	по умолчанию: 5 сек	Это значение ограничивает таймаут метода. Если таймаут истекает, возвращаются кешированные данные или локальный резервный вариант. Обратите внимание: в редких случаях метод может завершиться с небольшой задержкой относительно значения, указанного в `loadTimeout`, поскольку операция может включать несколько запросов под капотом.
Не задавайте product ID в коде! Поскольку пейволы настраиваются удалённо, доступные продукты, их количество и специальные предложения (например, бесплатные пробные периоды) могут меняться со временем. Убедитесь, что ваш код учитывает эти сценарии.

Например, если изначально вы получаете 2 продукта, приложение должно отображать именно 2 продукта. Но если позже вы получите 3 продукта, приложение должно показать все 3 без каких-либо изменений в коде. Единственное, что нужно задать в коде, — это ID плейсмента.

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

Параметр	Описание
Paywall	Объект `AdaptyPaywall` содержит: список ID продуктов, идентификатор пейвола, 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):
        // запрошенный массив продуктов
    case let .failure(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):
        // запрошенный массив продуктов без subscriptionOffer
    case let .failure(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):
            // запрошенный пейвол
        case let .failure(error):
            // обработка ошибки
    }
}

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

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

locale

необязательный

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

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

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

Подробнее о кодах локалей и рекомендациях по их использованию см. в разделе Локализации и коды локалей.

fetchPolicy

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

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

Обратите внимание: кеш сохраняется при перезапуске приложения и очищается только при его переустановке или принудительной очистке вручную.