Показ пейволов Paywall Builder в режиме Observer в Android SDK

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

Этот раздел относится только к режиму Observer. Если вы не работаете в режиме Observer, обратитесь к разделу Android — отображение пейволов Paywall Builder.

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

Настройте начальную интеграцию Adapty с Google Play и с App Store.
Установите и настройте Adapty SDK. Убедитесь, что параметр observerMode установлен в true. Обратитесь к нашим инструкциям для конкретных фреймворков для Android.
Создайте продукты в дашборде Adapty.
Настройте пейволы, назначьте им продукты и кастомизируйте их с помощью Paywall Builder в дашборде Adapty.
Создайте плейсменты и назначьте им пейволы в дашборде Adapty.
Получите пейволы Paywall Builder и их конфигурацию в коде вашего мобильного приложения.

Реализуйте AdaptyUiObserverModeHandler.

Событие onPurchaseInitiated уведомит вас о том, что пользователь инициировал покупку. В ответ на этот колбэк вы можете запустить свой кастомный флоу покупки:

val observerModeHandler =
 AdaptyUiObserverModeHandler { product, paywall, paywallView, onStartPurchase, onFinishPurchase ->
    onStartPurchase()
    yourBillingClient.makePurchase(
        product,
        onSuccess = { purchase ->
            onFinishPurchase()
            //handle success
        },
        onError = {
            onFinishPurchase()
            //handle error
        },
        onCancel = {
            onFinishPurchase()
            //handle cancel
        }
    )
}

AdaptyUiObserverModeHandler observerModeHandler = (product, paywall, paywallView, onStartPurchase, onFinishPurchase) -> {
    onStartPurchase.invoke();
    yourBillingClient.makePurchase(
        product,
        purchase -> {
            onFinishPurchase.invoke();
            //handle success
        },
        error -> {
            onFinishPurchase.invoke();
            //handle error
        },
        () -> { //cancellation
            onFinishPurchase.invoke();
            //handle cancel
        }
    );
};

Чтобы обрабатывать восстановление покупок в Observer mode, переопределите getRestoreHandler(). По умолчанию он возвращает null, что использует встроенный в Adapty поток Adapty.restorePurchases(). Чтобы предоставить собственную реализацию восстановления:

val observerModeHandler = object : AdaptyUiObserverModeHandler {
    // onPurchaseInitiated implementation (see above)

    override fun getRestoreHandler() =
        AdaptyUiObserverModeHandler.RestoreHandler { onStartRestore, onFinishRestore ->
            onStartRestore()
            yourBillingClient.restorePurchases(
                onSuccess = { restoredPurchases ->
                    onFinishRestore()
                    //handle successful restore
                },
                onError = {
                    onFinishRestore()
                    //handle error
                }
            )
        }
}

AdaptyUiObserverModeHandler observerModeHandler = new AdaptyUiObserverModeHandler() {
    // onPurchaseInitiated implementation (see above)

    @Override
    public RestoreHandler getRestoreHandler() {
        return (onStartRestore, onFinishRestore) -> {
            onStartRestore.invoke();
            yourBillingClient.restorePurchases(
                restoredPurchases -> {
                    onFinishRestore.invoke();
                    //handle successful restore
                },
                error -> {
                    onFinishRestore.invoke();
                    //handle error
                }
            );
        };
    }
};

Не забудьте вызывать следующие колбэки, чтобы уведомлять AdaptyUI о процессе покупки или восстановления. Это необходимо для корректной работы пейвола, например для отображения загрузчика:

Callback	Описание
onStartPurchase()	Callback следует вызывать, чтобы уведомить AdaptyUI о начале покупки.
onFinishPurchase()	Callback следует вызывать, чтобы уведомить AdaptyUI о завершении покупки.
onStartRestore()	Необязательный. Callback можно вызывать, чтобы уведомить AdaptyUI о начале восстановления покупок.
onFinishRestore()	Необязательный. Callback можно вызывать, чтобы уведомить AdaptyUI о завершении восстановления покупок.

Чтобы отобразить визуальный пейвол на экране устройства, его нужно сначала настроить.

Для этого вызовите метод AdaptyUI.getPaywallView() или создайте AdaptyPaywallView напрямую:

   val paywallView = AdaptyUI.getPaywallView(
       activity,
       viewConfiguration,
       products,
       eventListener,
       personalizedOfferResolver,
       tagResolver,
       timerResolver,
       observerModeHandler, 
   )

   val paywallView =
        AdaptyPaywallView(activity) // or retrieve it from xml
   ...
   with(paywallView) {
       showPaywall(
           viewConfiguration,
           products,
					 eventListener,
           personalizedOfferResolver,
           tagResolver,
           timerResolver,
					 observerModeHandler,
       )
   }

AdaptyPaywallView paywallView = AdaptyUI.getPaywallView(
        activity,
        viewConfiguration,
        products,
        eventListener,
        personalizedOfferResolver,
        tagResolver,
        timerResolver,
        observerModeHandler
);

AdaptyPaywallView paywallView =
  new AdaptyPaywallView(activity); //add to the view hierarchy if needed, or you receive it from xml
...
paywallView.showPaywall(viewConfiguration, products, eventListener, personalizedOfferResolver, tagResolver, timerResolver, observerModeHandler);

<com.adapty.ui.AdaptyPaywallView xmlns:android="http://schemas.android.com/apk/res/android"
    android:layout_width="match_parent"
    android:layout_height="match_parent" />

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

Для этого используйте следующую composable-функцию:

AdaptyPaywallScreen(
    viewConfiguration,
    products,
    eventListener,
    personalizedOfferResolver,
    tagResolver,
    timerResolver,
)

Параметры запроса:

Параметр	Наличие	Описание
Products	необязательный	Передайте массив `AdaptyPaywallProduct`, чтобы оптимизировать время отображения продуктов на экране. Если передать `null`, AdaptyUI автоматически загрузит необходимые продукты.
ViewConfiguration	обязательный	Передайте объект `AdaptyViewConfiguration`, содержащий визуальные настройки пейвола. Используйте метод `Adapty.getViewConfiguration(paywall)` для его загрузки. Подробнее см. в разделе Получение визуальной конфигурации пейвола.
EventListener	необязательный	Передайте `AdaptyUiEventListener` для отслеживания событий пейвола. Для удобства рекомендуется расширять `AdaptyUiDefaultEventListener`. Подробнее см. в разделе Обработка событий пейвола.
PersonalizedOfferResolver	необязательный	Чтобы указать персонализированную цену (подробнее), реализуйте `AdaptyUiPersonalizedOfferResolver` и передайте собственную логику, которая возвращает `true` для `AdaptyPaywallProduct`, если цена продукта персонализирована, и `false` в противном случае.
TagResolver	необязательный	Используйте `AdaptyUiTagResolver` для обработки пользовательских тегов в тексте пейвола. Этот резолвер принимает тег в качестве параметра и преобразует его в соответствующую строку. Подробнее см. в разделе Пользовательские теги в Paywall Builder.
ObserverModeHandler	обязательный для режима Observer	`AdaptyUiObserverModeHandler`, реализованный на предыдущем шаге.
variationId	обязательный	Строковый идентификатор варианта. Его можно получить через свойство `variationId` объекта `AdaptyPaywall`.
transaction	обязательный	Для iOS, StoreKit 1: объект `SKPaymentTransaction`. Для iOS, StoreKit 2: объект Transaction. Для Android: строковый идентификатор (`purchase.getOrderId()`) покупки, где покупка — экземпляр класса Purchase из библиотеки биллинга.

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

Настройте начальную интеграцию Adapty с Google Play и с App Store.
Установите и настройте Adapty SDK. Убедитесь, что параметр observerMode установлен в true. Обратитесь к инструкциям для вашего фреймворка: Android, React Native, Flutter и Unity.
Создайте продукты в дашборде Adapty.
Настройте пейволы, назначьте им продукты и кастомизируйте их с помощью Paywall Builder в дашборде Adapty.
Создайте плейсменты и назначьте им пейволы в дашборде Adapty.
Получите пейволы Paywall Builder и их конфигурацию в коде вашего мобильного приложения.

Реализуйте AdaptyUiObserverModeHandler. Колбэк AdaptyUiObserverModeHandler (onPurchaseInitiated) срабатывает, когда пользователь инициирует покупку. Вы можете запустить собственный процесс покупки в ответ на этот колбэк:

val observerModeHandler =
AdaptyUiObserverModeHandler { product, paywall, paywallView, onStartPurchase, onFinishPurchase ->
    onStartPurchase()
    yourBillingClient.makePurchase(
        product,
        onSuccess = { purchase ->
            onFinishPurchase()
            //handle success
        },
        onError = {
            onFinishPurchase()
            //handle error
        },
        onCancel = {
            onFinishPurchase()
            //handle cancel
        }
    )
}

AdaptyUiObserverModeHandler observerModeHandler = (product, paywall, paywallView, onStartPurchase, onFinishPurchase) -> {
    onStartPurchase.invoke();
    yourBillingClient.makePurchase(
        product,
        purchase -> {
            onFinishPurchase.invoke();
            //handle success
        },
        error -> {
            onFinishPurchase.invoke();
            //handle error
        },
        () -> { //cancellation
            onFinishPurchase.invoke();
            //handle cancel
        }
    );
};

Также не забудьте вызывать эти коллбэки в AdaptyUI. Это необходимо для правильной работы пейвола, например для отображения загрузчика:

Callback в Kotlin	Callback в Java	Описание
onStartPurchase()	onStartPurchase.invoke()	Callback нужно вызвать, чтобы уведомить AdaptyUI о том, что покупка начата.
onFinishPurchase()	onFinishPurchase.invoke()	Callback нужно вызвать, чтобы уведомить AdaptyUI о том, что покупка завершена успешно, завершена с ошибкой или отменена.

Чтобы отобразить визуальный пейвол, его необходимо сначала инициализировать. Для этого вызовите метод AdaptyUI.getPaywallView() или создайте AdaptyPaywallView напрямую:

val paywallView = AdaptyUI.getPaywallView(
    activity,
    viewConfiguration,
    products,
    AdaptyPaywallInsets.of(topInset, bottomInset),
    eventListener,
    personalizedOfferResolver,
    tagResolver,
    observerModeHandler,
)

//======= OR =======
val paywallView =
     AdaptyPaywallView(activity) // or retrieve it from xml
...
with(paywallView) {
    setEventListener(eventListener)
    setObserverModeHandler(observerModeHandler)
    showPaywall(
        viewConfiguration,
        products,
        AdaptyPaywallInsets.of(topInset, bottomInset),
        personalizedOfferResolver,
        tagResolver,
    )
}

AdaptyPaywallView paywallView = AdaptyUI.getPaywallView(
        activity,
        viewConfiguration,
        products,
        AdaptyPaywallInsets.of(topInset, bottomInset),
        eventListener,
        personalizedOfferResolver,
        tagResolver,
        observerModeHandler
);

//======= OR =======

AdaptyPaywallView paywallView =
  new AdaptyPaywallView(activity); //add to the view hierarchy if needed, or you receive it from xml
...
paywallView.setEventListener(eventListener);
paywallView.setObserverModeHandler(observerModeHandler);
paywallView.showPaywall(viewConfiguration, products, AdaptyPaywallInsets.of(topInset, bottomInset), personalizedOfferResolver);

<com.adapty.ui.AdaptyPaywallView xmlns:android="http://schemas.android.com/apk/res/android"
    android:layout_width="match_parent"
    android:layout_height="match_parent" />

После успешного создания представления вы можете добавить его в иерархию представлений и отобразить.

Параметры запроса:

Параметр	Наличие	Описание
Products	опционально	Передайте массив `AdaptyPaywallProduct`, чтобы оптимизировать время отображения продуктов на экране. Если передать `null`, AdaptyUI автоматически загрузит необходимые продукты.
ViewConfiguration	обязательно	Передайте объект `AdaptyViewConfiguration`, содержащий визуальные настройки пейвола. Используйте метод `Adapty.getViewConfiguration(paywall)` для его загрузки. Подробнее см. в разделе Получение визуальной конфигурации пейвола.
Insets	обязательно	Определите объект `AdaptyPaywallInsets`, содержащий информацию об области, перекрытой системными панелями, — это создаёт вертикальные отступы для контента. Если строка состояния и панель навигации не перекрывают `AdaptyPaywallView`, передайте `AdaptyPaywallInsets.NONE`. В полноэкранном режиме, когда системные панели перекрывают часть интерфейса, получите отступы так, как показано под таблицей.
EventListener	опционально	Передайте `AdaptyUiEventListener` для отслеживания событий пейвола. Для удобства рекомендуется расширить `AdaptyUiDefaultEventListener`. Подробнее см. в разделе Обработка событий пейвола.
PersonalizedOfferResolver	опционально	Чтобы указать персонализированную цену (подробнее), реализуйте `AdaptyUiPersonalizedOfferResolver` и передайте собственную логику, которая возвращает `true` для `AdaptyPaywallProduct` с персонализированной ценой и `false` в остальных случаях.
TagResolver	опционально	Используйте `AdaptyUiTagResolver` для обработки пользовательских тегов в тексте пейвола. Этот резолвер принимает тег и возвращает соответствующую строку. Подробнее см. в разделе Пользовательские теги в Paywall Builder.
ObserverModeHandler	обязательно для режима Observer	`AdaptyUiObserverModeHandler`, реализованный на предыдущем шаге.
variationId	обязательно	Строковый идентификатор варианта. Его можно получить через свойство `variationId` объекта `AdaptyPaywall`.
transaction	обязательно	Для iOS, StoreKit 1: объект `SKPaymentTransaction`. Для iOS, StoreKit 2: объект Transaction. Для Android: строковый идентификатор (`purchase.getOrderId()`) покупки, где покупка — это экземпляр класса Purchase из библиотеки биллинга.
Для полноэкранного режима, где системные панели перекрывают часть вашего UI, получите инсеты следующим образом:

import androidx.core.graphics.Insets
import androidx.core.view.ViewCompat
import androidx.core.view.WindowInsetsCompat

//create extension function
fun View.onReceiveSystemBarsInsets(action: (insets: Insets) -> Unit) {
    ViewCompat.setOnApplyWindowInsetsListener(this) { _, insets ->
        val systemBarInsets = insets.getInsets(WindowInsetsCompat.Type.systemBars())
        ViewCompat.setOnApplyWindowInsetsListener(this, null)
        action(systemBarInsets)
        insets
    }
}
//and then use it with the view
paywallView.onReceiveSystemBarsInsets { insets ->
    val paywallInsets = AdaptyPaywallInsets.of(insets.top, insets.bottom)
    paywallView.setEventListener(eventListener)
    paywallView.setObserverModeHandler(observerModeHandler)
    paywallView.showPaywall(viewConfig, products, paywallInsets, personalizedOfferResolver, tagResolver)
}

import androidx.core.graphics.Insets;
import androidx.core.view.ViewCompat;
import androidx.core.view.WindowInsetsCompat;

...

ViewCompat.setOnApplyWindowInsetsListener(paywallView, (view, insets) -> {
    Insets systemBarInsets = insets.getInsets(WindowInsetsCompat.Type.systemBars());
    ViewCompat.setOnApplyWindowInsetsListener(paywallView, null);
  
    AdaptyPaywallInsets paywallInsets =
                 AdaptyPaywallInsets.of(systemBarInsets.top, systemBarInsets.bottom);
    paywallView.setEventListener(eventListener);
    paywallView.setObserverModeHandler(observerModeHandler);
    paywallView.showPaywall(viewConfiguration, products, paywallInsets, personalizedOfferResolver, tagResolver);
            
    return insets;
});

Возвращает:

Объект	Описание
`AdaptyPaywallView`	объект, представляющий запрошенный экран пейвола.

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