Руководство по базовой интеграции модуля Mendix

В этом руководстве рассматривается добавление модуля Pushwoosh в существующее нативное мобильное приложение Mendix, от его установки из Marketplace до получения уведомления на устройстве.

Предварительные требования

Для интеграции модуля Pushwoosh в ваше приложение вам потребуется следующее:

Требования

• Аккаунт Pushwoosh.
• Проект Pushwoosh, настроенный в вашем аккаунте.
• Для интеграции с iOS:
  • Платформа iOS, настроенная для отправки push-уведомлений. Мы рекомендуем использовать конфигурацию на основе токенов как самый простой способ.
  • Во время настройки установите Gateway на Sandbox, чтобы отправлять пуши в симулятор.
• Для интеграции с Android:
  • Настроенная платформа Android
  • Файл google-services.json и package name из вашего проекта Firebase.
  • Проект Firebase, подключенный к вашему Android-приложению. При необходимости следуйте руководству по настройке Firebase.
• Ваш Pushwoosh Application Code и Pushwoosh Device API Token из панели управления Pushwoosh для вашего приложения.

Device API Token из списка выше не требуется для этого модуля. Виджет принимает Application Code и ничего больше.

Вам также потребуется следующее:

• Mendix Studio Pro 11.12.3 или новее. Пакет модуля собран с этой версией, и Studio Pro не может открыть пакет, созданный более новой версией.
• Профиль навигации для нативного мобильного приложения в вашем приложении.
• Xcode или Android Studio для создания нативной сборки. Приложение Make It Native не может запустить этот модуль, так как оно не содержит стороннего нативного кода.

1. Установите модуль из Marketplace

В Studio Pro нажмите на иконку Marketplace в правом верхнем углу, найдите Pushwoosh и нажмите Download. Studio Pro добавит в ваше приложение модуль с именем Pushwoosh.

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

2. Добавьте виджет событий Pushwoosh на вашу домашнюю страницу

Виджет Pushwoosh events запускает SDK и превращает push-уведомления в события nanoflow. Он ничего не отображает, поэтому разместите его один раз на странице, которая загружается первой в профиле навигации нативного мобильного приложения.

1. Откройте домашнюю страницу вашего профиля навигации нативного мобильного приложения.
2. Перетащите виджет Pushwoosh events на страницу. Он находится в категории Pushwoosh на панели инструментов.
3. Установите свойство Application Code на Application Code вашего приложения из панели управления Pushwoosh. Он выглядит как XXXXX-XXXXX.

Оставьте Register on load включенным, чтобы зарегистрировать устройство сразу после открытия приложения. Отключите его, если вы предпочитаете запрашивать разрешение на уведомления позже, в тот момент в приложении, когда запрос будет более понятен пользователю. См. Регистрация устройства ниже.

3. Настройте нативную сборку

Pushwoosh заменяет встроенные push-уведомления приложения Mendix, а не работает параллельно с ними. В Native Mobile Builder установите возможности следующим образом:

• Push notifications: выкл.
• Firebase Android: вкл., чтобы google-services.json по-прежнему подхватывался.

Две службы уведомлений, зарегистрированные для события com.google.firebase.MESSAGING_EVENT, перекрывают друг друга, и уведомления перестают приходить. На Android FCM Sender ID берется из google-services.json; он не передается в модуль.

На iOS добавьте возможность Push Notifications в сгенерированный проект Xcode в разделе Signing & Capabilities и загрузите ваш ключ APNs в панель управления Pushwoosh, как описано в руководстве по настройке платформы iOS.

Сборка на macOS

В Studio Pro для Mac нет Native Mobile Builder. Вместо этого настройте нативный шаблон с помощью инструмента командной строки @mendix/native-mobile-toolkit, а затем соберите сгенерированные проекты iOS и Android локально с помощью Xcode и Gradle.

4. Регистрация устройства

Устройство получает уведомления только после регистрации в Pushwoosh. Есть два способа регистрации, и вам нужен один из них.

Регистрация при загрузке. Оставьте свойство виджета Register on load включенным. Устройство регистрируется сразу после загрузки виджета, и на iOS в этот момент появляется системный запрос на разрешение.

Регистрация из nanoflow. Отключите Register on load и вызовите действие RegisterForPushNotifications из вашего собственного nanoflow, например, после входа пользователя в систему или принятия экрана согласия. Действие возвращает push-токен в виде строки.

Чтобы прекратить доставку на устройство, вызовите UnregisterForPushNotifications.

5. Обработка уведомления, которое приходит, когда приложение открыто

Когда уведомление приходит, пока приложение находится на переднем плане, виджет записывает уведомление в атрибуты, на которые вы его направите, а затем запускает nanoflow в On push received.

1. Установите Message на строковый атрибут, который получает текст уведомления.
2. Установите Payload на строковый атрибут, который получает полную полезную нагрузку в формате JSON.
3. Установите On push received на nanoflow, который реагирует на это, например, показывает сообщение или обновляет список.

Атрибуты заполняются до запуска nanoflow, поэтому nanoflow может сразу их прочитать.

6. Обработка открытого уведомления и deep link

Когда пользователь нажимает на уведомление, виджет запускает nanoflow в On push opened, с заполненными теми же атрибутами Message и Payload.

Если уведомление содержит deep link, виджет также записывает ссылку в атрибут, установленный в Deep link, и запускает nanoflow в On deep link. Этот nanoflow запускается в дополнение к On push opened, поэтому используйте его для маршрутизации пользователя на страницу, на которую указывает ссылка.

7. Идентификация пользователя и установка тегов

Теги — это то, что превращает массовую рассылку в целевое сообщение. Вызовите SetTags из любого nanoflow с объектом JSON в качестве параметра:

'{"Language":"en","Plan":"pro","Level":7}'

Кавычки в выражениях Mendix

Строка в выражении Mendix пишется в одинарных кавычках, поэтому JSON внутри нее сохраняет свои двойные кавычки без экранирования. Написание "" или \" внутри выражения приведет к созданию строки, которую действие не сможет разобрать.

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

8. Отправка событий

События управляют триггерными кампаниями и сообщениями в приложении. Вызовите PostEvent с именем события и, опционально, объектом JSON с атрибутами:

'{"product":"Coffee grinder","price":129}'

Имя события должно совпадать с событием, настроенным в панели управления Pushwoosh.

9. Отправка тестового уведомления

Зарегистрируйте устройство как тестовое и отправьте на него сообщение из панели управления Pushwoosh. См. Тестирование интеграции для получения инструкций.

Уведомление, которое приходит, когда приложение открыто, отображается системой как оповещение, и также запускается nanoflow On push received. Чтобы подавить системное оповещение и обработать уведомление только в nanoflow, вызовите SetShowForegroundAlert со значением false. Это действие работает только на iOS.

10. Проверка интеграции, когда ничего не приходит

Проработайте эти пункты по порядку, если устройство не получает уведомлений:

1. Убедитесь, что приложение является кастомным приложением для разработчиков или настоящей нативной сборкой. Приложение Make It Native не содержит модуль, поэтому каждое действие Pushwoosh в нем завершается без ошибок, но и без результата.
2. Убедитесь в правильности настроек нативной сборки: Push notifications выключено, Firebase Android включено.
3. Убедитесь, что устройство зарегистрировано. Вызовите GetPushToken и проверьте, что он возвращает токен, а не пустую строку.
4. Убедитесь, что платформа настроена в панели управления Pushwoosh, с загруженным ключом APNs для iOS и ключом сервера Firebase для Android.

Если устройство по-прежнему недоступно, вызовите GetHwid и создайте заявку в службу поддержки с этим идентификатором.

Следующие шаги

• Справочник по действиям модуля - свойства виджета и действия JavaScript, с параметрами и возвращаемыми значениями
• Часто задаваемые вопросы по Mendix - вопросы, которые возникают во время первой интеграции