Передача данных во флоу в Capacitor SDK

Кастомный тег — это пользовательская переменная, значение которой задаётся в приложении. После того как вы выбираете Value comes from outside the app в настройках переменной, приложение может задать её значение через Adapty SDK. Например, текстовый элемент содержит «Coins:» и кастомный тег. Если приложение передаёт для тега «120», пользователь видит «Coins: 120».

Прежде чем начать

Вам необходим Adapty SDK версии 4 или выше. Версии ниже v4 не отображают флоу.

Добавьте пользовательские теги во флоу

Чтобы отображать значения из вашего приложения во флоу, настройте кастомные теги в билдере:

Создайте кастомный тег для каждого значения, которое передаёт ваше приложение.
Вставьте каждый тег в текстовый элемент.
Запишите полное имя каждого тега, включая его группу. Именно под этим именем код вашего приложения передаёт каждое значение. Например, если группа user содержит тег streak, полное имя тега — user.streak.

Передача значений пользовательских тегов

Передайте значения из вашего приложения в параметр customTags метода createFlowView в виде объекта:

Каждый ключ — это полное имя пользовательского тега, например user.streak.
Каждое значение — строка, которую увидят пользователи вместо тега.
Каждое значение должно быть удобочитаемым, например “1 250”, а не “1250.0”. Adapty не форматирует и не переводит его.

SDK считывает значения один раз — при создании представления, поэтому они не меняются, пока флоу открыт.


const customTags = {
  'username': 'DragonSlayer42',
  'coins': '1,250',
};

try {
  const view = await createFlowView(flow, { customTags });
  await view.present();
} catch (error) {
  // handle the error
}

Чтобы протестировать пользовательские теги, откройте флоу в своём приложении после добавления кода, который устанавливает их значения. Холст конструктора и предпросмотр на устройствах отображают только начальные значения: мобильное приложение Adapty не устанавливает значения пользовательских тегов.

Если ваше приложение уже устанавливает значения custom tags для пейволов старого Paywall Builder, изучите чем custom tags во флоу отличаются.

Что пользователи видят при отсутствии значения

Пользователи видят Начальное значение пользовательского тега как резервное в следующих случаях:

Ваше приложение не передаёт никакого значения для тега.
Пользователь не обновил приложение до версии, которая передаёт это значение.
Имя в коде вашего приложения не совпадает с полным именем тега, включая регистр букв.
Другой пользовательский тег в том же текстовом элементе не имеет значения. В этом случае каждый пользовательский тег в этом текстовом элементе показывает своё начальное значение.

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

Пример: показываем ИМТ по ответам с онбординга

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

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

В этом примере онбординг-флоу собирает вес и рост пользователя. Когда пользователь закрывает онбординг-флоу после последнего экрана, приложение вычисляет индекс массы тела (ИМТ). Затем открывается пейвол-флоу, который показывает этот ИМТ.

Настройка флоу

Создайте два флоу: онбординг-флоу, собирающий вес и рост пользователя, и флоу-пейвол, показывающий его ИМТ.
Добавьте два поля Number в онбординг-флоу:
- Одно для веса в килограммах с Element ID weight.
- Одно для роста в сантиметрах с Element ID height.
Для обоих полей установите Format в значение Integer. Поле отправляет значение как текст, точно так, как его ввёл пользователь, а пример кода не воспринимает «70.5» и «70,5» одинаково. Целые числа не содержат разделителя дробной части, поэтому код читает их одинаково в любой локали.
Чтобы убедиться, что приложение получает оба значения, завершите онбординг-флоу экраном без полей ввода. На этом экране добавьте кнопку с действием Close flow. Поля отправляют свои значения при потере фокуса или при переходе пользователя на другой экран. Действие Close flow не отправляет их. Пример кода открывает пейвол только в том случае, если пользователь добрался до последнего экрана.
В флоу-пейволе создайте кастомный тег с именем bmi. В поле Initial value введите тире (—). Пользователь увидит тире, если приложение не передало значение ИМТ.
Добавьте текстовый элемент со словами «Your BMI:» в флоу-пейвол. После этих слов вставьте кастомный тег bmi.
Добавьте онбординг-флоу в плейсмент, например onboarding. Добавьте флоу-пейвол в плейсмент с ID bmi_paywall. Код из раздела Pass the BMI to the paywall получает пейвол по этому ID.

Передайте BMI на пейвол

Собирайте вес и рост из событий flow_user_input онбординг-флоу, как описано в Обработка данных из флоу. Чтобы узнать, что пользователь достиг последнего экрана, отслеживайте событие flow_screen_showed с is_last_screen, равным true, как описано в Отслеживание просмотров экранов флоу. Когда пользователь закроет флоу онбординга после этого экрана, вычислите BMI. Затем создайте представление пейвола и передайте BMI для кастомного тега bmi.

Зарегистрируйте следующие обработчики на onboardingView — представлении, которое вы создаёте для флоу онбординга:


const bodyAnswers: Record<string, string> = {};
let reachedLastScreen = false;

await onboardingView.setEventHandlers({
  onAnalytics(name, params) {
    if (name === 'flow_screen_showed' && params.is_last_screen) {
      reachedLastScreen = true;
    }
    if (name === 'flow_user_input' && typeof params.value === 'string') {
      bodyAnswers[params.element_id as string] = params.value;
    }
    return false;
  },
  onDisappeared() {
    // Number inputs send their values as strings.
    const weight = Number(bodyAnswers.weight);
    const height = Number(bodyAnswers.height);
    const finished = reachedLastScreen;
    delete bodyAnswers.weight;
    delete bodyAnswers.height;
    reachedLastScreen = false;

    if (finished && weight > 0 && height > 0) {
      const heightInMeters = height / 100;
      const bmi = weight / (heightInMeters * heightInMeters);
      showBmiPaywall(bmi.toLocaleString(undefined, { maximumFractionDigits: 1 }));
    }
    return false;
  },
});

async function showBmiPaywall(bmi: string) {
  try {
    const flow = await adapty.getFlow({ placementId: 'bmi_paywall' });
    const view = await createFlowView(flow, { customTags: { 'bmi': bmi } });
    await view.present();
  } catch (error) {
    // handle the error
  }
}

toLocaleString использует десятичный разделитель локали пользователя: «22.7» в английском, «22,7» в немецком.

Сохраните ИМТ в профиле пользователя

Чтобы показывать пользователям разные флоу в зависимости от их ИМТ, сохраните его как пользовательский атрибут профиля. В дашборде Adapty создайте числовой пользовательский атрибут (Number) с ключом bmi. Затем показывайте каждый флоу нужной аудитории, построенной на основе этого атрибута.

Вызовите метод updateProfile в onDisappeared, сразу после строки, которая вычисляет bmi. Передайте само число, а не отформатированную строку — это нужно, чтобы сегмент мог сравнивать BMI с пороговым значением. onDisappeared не может быть async, поэтому обрабатывайте результат через .catch вместо await:

adapty
  .updateProfile({ codableCustomAttributes: { bmi } })
  .catch((error) => {
    // handle the error
  });