Синтаксис нативных шаблонов In-App

Нативные In-App сообщения отображаются непосредственно SDK. WebView при этом не используется. Вместо страницы index.html ZIP-ресурс содержит файл native-config.json, который описывает сообщение в виде структурированных данных (тип макета, тексты, цвета, изображения, кнопки). SDK считывает этот файл и отрисовывает соответствующее нативное представление, что обеспечивает более плавную анимацию и лучшую производительность по сравнению со встроенной веб-страницей.

В этом руководстве описана схема native-config.json: поля, типы и примеры для каждого типа отображения. О классическом формате на основе HTML читайте в статье Синтаксис шаблонов Rich Media.

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

Для нативных In-App сообщений требуется:

• iOS: SDK 7.2.0 или новее (7.2.1+ для баннера, карусели и листа)
• Android: SDK 6.10.0 или новее (6.10.1+ для баннера, карусели и листа)

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

Поддержка платформ

Тип отображения	iOS	Android
modal	✅ 7.2.0+	✅ 6.10.0+
fullscreen	✅ 7.2.0+	✅ 6.10.0+
stories	✅ 7.2.0+	✅ 6.10.0+
banner	✅ 7.2.1+	✅ 6.10.1+
carousel	✅ 7.2.1+	✅ 6.10.1+
sheet	✅ 7.2.1+	✅ 6.10.1+
video	✅	✅ 6.11.0+
pip	✅	Пока недоступно
scratchcard	✅	Пока недоступно
spinwheel	✅	Пока недоступно

Осторожно

native-config.json с displayType, который не реализован в текущей версии SDK вашего приложения, рассматривается как недействительная конфигурация. SDK пропустит его, а не будет показывать некорректный макет. Нацеливайте кампании на нужную версию приложения, если вы используете тип, который доступен еще не везде.

Структура шаблона

Нативный шаблон In-App — это ZIP-архив, такой же, как и обычный шаблон Rich Media, за исключением того, что в корневом каталоге вместо index.html находится файл native-config.json:

<template>.zip
├── native-config.json   ← required, layout and content
├── pushwoosh.json        ← optional, localization (see below)

Изображения и видео, на которые есть ссылки в native-config.json (image, poster, fallback, url в pip/video), должны быть абсолютными URL-адресами HTTPS. SDK загружает их по сети. Локальные файлы из архива он не считывает.

Сама конфигурация представляет собой единый объект JSON:

{ "displayType": "<type>", "<type>": { /* content block for this type */ } }

displayType выбирает один из десяти форматов, описанных ниже. Объект под соответствующим ключом содержит контент этого формата. Конфигурация с неизвестным displayType, отсутствующим блоком контента или пустым обязательным списком (items для carousel/stories, segments для spinwheel) является недействительной. SDK пропустит ее отображение, чтобы не отрисовывать некорректный макет.

Настройки доставки (даты начала/окончания и ограничение частоты показов) не являются частью native-config.json. Они настраиваются так же, как и для любого другого In-App сообщения, на шаге Настройки отображения кампании.

Кроме того, для ограничения частоты показов нативных In-App сообщений требуется явное согласие на стороне SDK. См. Интеграция SDK.

Цвета

Каждое значение цвета — это шестнадцатеричная строка CSS: #RGB, #RGBA, #RRGGBB или #RRGGBBAA. Начальный символ # обязателен во всех четырех формах.

Общие строительные блоки

Эти небольшие объекты повторно используются в нескольких типах отображения.

Text

Поле	Тип	Обязательно	Описание
text	string	да	Текстовое содержимое
color	string	да	Цвет текста

{ "text": "Spin for a garage perk", "color": "#FFFFFFFF" }

Border

Поле	Тип	Обязательно	Описание
color	string	да	Цвет рамки
radius	number	да	Радиус скругления углов в пунктах

{ "color": "#0E72E5FF", "radius": 12 }

Cover

Необязательное изображение поверх фонового цвета. Используется в fullscreen и scratchcard.

Поле	Тип	Обязательно	Описание
image	string	нет	URL-адрес изображения обложки
background	string	да	Фоновый цвет, отображаемый под изображением (или вместо него)

{ "image": "https://example.com/cover.jpg", "background": "#1A1A1EFF" }

Action

Различаемое объединение по type:

Вариант	Поля	Описание
{ "type": "close" }	Нет	Закрывает In-App сообщение
{ "type": "url", "url": string }	url обязательно	Открывает URL или диплинк

{ "type": "url", "url": "pushwoosh://sale" }

Button

Поле	Тип	Обязательно	Описание
text	Text	да	Надпись на кнопке
background	string	да	Цвет заливки кнопки
border	Border	да	Рамка кнопки
action	Action	да	Действие, выполняемое при нажатии

spinButton (spinwheel) и revealButton (scratchcard) имеют ту же структуру, но без action. Их поведение (вращать колесо, открыть карту) является встроенным.

{
  "text": { "text": "Book a test drive", "color": "#FFFFFFFF" },
  "background": "#0E72E5FF",
  "border": { "color": "#0E72E5FF", "radius": 12 },
  "action": { "type": "url", "url": "pushwoosh://sale" }
}

Reward

Панель с призом, отображаемая в scratchcard и spinwheel. Действительная награда должна иметь title или code.

Поле	Тип	Обязательно	Описание
title	Text	нет	Заголовок награды
message	Text	нет	Описание награды
code	string	нет	Промокод, отображаемый с кнопкой копирования
button	Button	нет	Кнопка подтверждения с собственным действием

{
  "title": { "text": "20% off detailing", "color": "#111111FF" },
  "message": { "text": "Valid for any full-detail booking this month.", "color": "#555555FF" },
  "code": "APEX20",
  "button": {
    "text": { "text": "Book detailing", "color": "#FFFFFFFF" },
    "background": "#B3227CFF",
    "border": { "color": "#B3227CFF", "radius": 12 },
    "action": { "type": "url", "url": "pushwoosh://detailing" }
  }
}

Типы отображения

banner

Компактная панель, закрепленная у верхнего или нижнего края экрана.

Поле	Тип	Обязательно	Описание
showClose	boolean	да	Показывать кнопку закрытия (✕)
position	top | bottom	да	Край экрана
background	string	да	Цвет фона панели
image	string	нет	Миниатюра слева
title	Text	нет	Однострочный заголовок, усекаемый многоточием
message	Text	нет	Основной текст, до 2 строк
action	Action	да	Выполняется при нажатии на саму панель
autoDismiss	number	нет	Автоматически закрыть через указанное количество секунд. Опустите, чтобы оставить до закрытия вручную

{
  "displayType": "banner",
  "banner": {
    "showClose": true,
    "position": "bottom",
    "background": "#4B5057FF",
    "image": "https://example.com/thumb.jpg",
    "title": { "text": "Alpine A110 just dropped", "color": "#FFFFFFFF" },
    "message": { "text": "The featherweight icon — tap to see the build", "color": "#FFFFFFFF" },
    "action": { "type": "url", "url": "pushwoosh://product/x6f" },
    "autoDismiss": 6
  }
}

carousel

Полноэкранный набор карточек с возможностью прокрутки и индикаторами страниц.

Поле	Тип	Обязательно	Описание
showClose	boolean	да	Показывать кнопку закрытия (✕)
items	Item[]	да	Карточки (не менее 1)

Элемент карусели:

Поле	Тип	Обязательно	Описание
title	Text	нет	Заголовок карточки
message	Text	нет	Подзаголовок карточки
image	string	нет	Изображение карточки
action	Action	нет	Выполняется при нажатии на карточку

{
  "displayType": "carousel",
  "carousel": {
    "showClose": true,
    "items": [
      {
        "image": "https://example.com/card-1.jpg",
        "title": { "text": "AMG GT R", "color": "#FFFFFFFF" },
        "message": { "text": "585 hp biturbo V8 — just landed", "color": "#FFFFFFFF" },
        "action": { "type": "url", "url": "pushwoosh://product/n6fx" }
      },
      {
        "image": "https://example.com/card-2.jpg",
        "title": { "text": "Alpine A110", "color": "#FFFFFFFF" },
        "message": { "text": "Featherweight icon — limited allocation", "color": "#FFFFFFFF" },
        "action": { "type": "url", "url": "pushwoosh://product/x6f" }
      }
    ]
  }
}

fullscreen

Изображение обложки от края до края с текстом и кнопками поверх него.

Поле	Тип	Обязательно	Описание
showClose	boolean	да	Показывать кнопку закрытия (✕)
cover	Cover	да	Фоновое изображение и цвет
title	Text	нет	Заголовок
message	Text	нет	Основной текст
buttons	Button[]	да	Кнопки внизу (может быть пустым)

{
  "displayType": "fullscreen",
  "fullscreen": {
    "showClose": true,
    "cover": { "image": "https://example.com/hero.jpg", "background": "#1A1A1EFF" },
    "title": { "text": "Pure Maranello", "color": "#FFFFFFFF" },
    "message": { "text": "The prancing horse, reimagined.", "color": "#EBEBEBFF" },
    "buttons": [
      {
        "text": { "text": "Reserve now", "color": "#FFFFFFFF" },
        "background": "#0E72E5FF",
        "border": { "color": "#0E72E5FF", "radius": 8 },
        "action": { "type": "url", "url": "pushwoosh://sale" }
      },
      {
        "text": { "text": "Not now", "color": "#FFFFFFFF" },
        "background": "#00000000",
        "border": { "color": "#FFFFFF99", "radius": 8 },
        "action": { "type": "close" }
      }
    ]
  }
}

modal

Карточка, расположенная по центру.

Поле	Тип	Обязательно	Описание
showClose	boolean	да	Показывать кнопку закрытия (✕)
dimBackground	boolean	да	Затемнять экран за карточкой
background	string	да	Цвет фона карточки
image	string	нет	Изображение обложки
title	Text	нет	Заголовок
message	Text	нет	Основной текст
buttons	Button[]	да	Кнопки под текстом (может быть пустым)

{
  "displayType": "modal",
  "modal": {
    "showClose": true,
    "dimBackground": true,
    "background": "#FFFFFFFF",
    "image": "https://example.com/cover.jpg",
    "title": { "text": "The GT R has landed", "color": "#4B5057FF" },
    "message": { "text": "585 hp — now in the showroom.", "color": "#4B5057FF" },
    "buttons": [
      {
        "text": { "text": "Book a test drive", "color": "#FFFFFFFF" },
        "background": "#0E72E5FF",
        "border": { "color": "#0E72E5FF", "radius": 12 },
        "action": { "type": "url", "url": "pushwoosh://sale" }
      },
      {
        "text": { "text": "Not now", "color": "#4B5057FF" },
        "background": "#FFFFFFFF",
        "border": { "color": "#4B5057FF", "radius": 12 },
        "action": { "type": "close" }
      }
    ]
  }
}

pip

Плавающее окно с видео в режиме «картинка в картинке», закрепленное в углу экрана.

Поле	Тип	Обязательно	Описание
showClose	boolean	да	Показывать кнопку закрытия (✕)
position	bottom-right | bottom-left | top-right | top-left	да	Угол экрана
loop	boolean	да	Зациклить воспроизведение
muted	boolean	да	Начать с выключенным звуком
url	string	да	URL-адрес видео
poster	string	нет	Постер, отображаемый до начала воспроизведения
fallback	string	нет	Изображение, отображаемое, если видео не удалось воспроизвести
width	number	да	Ширина окна в процентах от ширины экрана, в диапазоне 15–70
aspectRatio	number	да	Соотношение высоты и ширины окна
borderRadius	number	нет	Радиус скругления углов окна в пунктах
action	Action	нет	Выполняется при нажатии на само окно

На pip нет настраиваемых кнопок. Элементы управления окном (развернуть на весь экран, выключить звук, закрыть) предоставляются системой.

{
  "displayType": "pip",
  "pip": {
    "showClose": true,
    "position": "bottom-right",
    "loop": true,
    "muted": true,
    "url": "https://example.com/teaser.mp4",
    "poster": "https://example.com/poster.jpg",
    "width": 40,
    "aspectRatio": 0.5625,
    "action": { "type": "url", "url": "pushwoosh://product/x6f" }
  }
}

scratchcard

Карточка с наградой, скрытой под стираемым слоем.

Поле	Тип	Обязательно	Описание
showClose	boolean	да	Показывать кнопку закрытия (✕)
background	string | string[]	да	Цвет фона карточки или точки градиента
revealThreshold	number	да	Доля слоя, которую необходимо стереть (0–1), прежде чем появится награда
cover	Cover	да	Стираемый слой. Без image на фоновом цвете отображается подсказка «сотрите здесь»
revealButton	Button (no action)	нет	Кнопка «Показать сразу»
title	Text	нет	Заголовок
message	Text	нет	Основной текст
reward	Reward	да	Приз, скрытый под слоем

{
  "displayType": "scratchcard",
  "scratchcard": {
    "showClose": true,
    "background": ["#3A1C71FF", "#B3227CFF", "#E0503AFF"],
    "revealThreshold": 0.55,
    "cover": { "background": "#C9CDD6FF" },
    "revealButton": {
      "text": { "text": "Reveal without scratching", "color": "#3A1C71FF" },
      "background": "#F2DFF5FF",
      "border": { "color": "#F2DFF5FF", "radius": 10 }
    },
    "title": { "text": "Your loyalty reward", "color": "#FFFFFFFF" },
    "message": { "text": "Scratch the foil to reveal this week's garage perk.", "color": "#F2DFF5FF" },
    "reward": {
      "title": { "text": "20% off detailing", "color": "#111111FF" },
      "message": { "text": "Valid for any full-detail booking this month.", "color": "#555555FF" },
      "code": "APEX20",
      "button": {
        "text": { "text": "Book detailing", "color": "#FFFFFFFF" },
        "background": "#B3227CFF",
        "border": { "color": "#B3227CFF", "radius": 12 },
        "action": { "type": "url", "url": "pushwoosh://detailing" }
      }
    }
  }
}

sheet

Карточка, закрепленная у нижнего края, с маркером для перетаскивания.

Поле	Тип	Обязательно	Описание
showClose	boolean	да	Показывать кнопку закрытия (✕)
dimBackground	boolean	да	Затемнять экран за карточкой
background	string	да	Цвет фона карточки
image	string	нет	Изображение обложки
title	Text	нет	Заголовок
message	Text	нет	Основной текст
buttons	Button[]	да	Кнопки под текстом (может быть пустым)

{
  "displayType": "sheet",
  "sheet": {
    "showClose": true,
    "dimBackground": true,
    "background": "#FFFFFFFF",
    "image": "https://example.com/cover.jpg",
    "title": { "text": "Your quote is ready", "color": "#000000FF" },
    "message": { "text": "Guaranteed buyout for your A110: $68,500.", "color": "#000000FF" },
    "buttons": [
      {
        "text": { "text": "Get guaranteed quote", "color": "#FFFFFFFF" },
        "background": "#0E72E5FF",
        "border": { "color": "#0E72E5FF", "radius": 12 },
        "action": { "type": "url", "url": "pushwoosh://sale" }
      }
    ]
  }
}

spinwheel

Колесо фортуны со взвешенными сегментами и центральной кнопкой.

Поле	Тип	Обязательно	Описание
showClose	boolean	да	Показывать кнопку закрытия (✕)
background	string | string[]	да	Цвет фона карточки или точки градиента
winIndex	number	да	Индекс (начиная с 0) выигрышного сегмента
spinButton	Button (no action)	да	Центральная кнопка
title	Text	нет	Заголовок
message	Text	нет	Основной текст
reward	Reward	да	Награда за выигрышный спин (резервный вариант для сегментов без собственной награды)
loseTitle	Text	нет	Заголовок, отображаемый при проигрыше
segments	Segment[]	да	Сегменты колеса (SDK ожидает 2–12)

Сегмент:

Поле	Тип	Обязательно	Описание
message	Text	да	Надпись на сегменте
color	string	нет	Цвет сегмента. Опустите, чтобы использовать резервную палитру, применяемую по всему колесу
weight	number	да	Относительный размер сегмента
reward	Reward	нет	Награда для конкретного сегмента

{
  "displayType": "spinwheel",
  "spinwheel": {
    "showClose": true,
    "background": ["#1B1B46FF", "#5B2B8FFF", "#B0338AFF"],
    "winIndex": 1,
    "spinButton": {
      "text": { "text": "SPIN", "color": "#1B1B46FF" },
      "background": "#F2C94CFF",
      "border": { "color": "#D9A02BFF", "radius": 36 }
    },
    "title": { "text": "Spin for a garage perk", "color": "#FFFFFFFF" },
    "message": { "text": "One spin — every slice wins this week.", "color": "#E3D9F2FF" },
    "reward": {
      "title": { "text": "You won a garage perk!", "color": "#FFFFFFFF" },
      "code": "APEXPERK",
      "button": {
        "text": { "text": "Claim", "color": "#FFFFFFFF" },
        "background": "#5B2B8FFF",
        "border": { "color": "#5B2B8FFF", "radius": 12 },
        "action": { "type": "close" }
      }
    },
    "segments": [
      { "message": { "text": "5% off", "color": "#FFFFFFFF" }, "color": "#5856D6FF", "weight": 1 },
      {
        "message": { "text": "20% off", "color": "#FFFFFFFF" },
        "color": "#30B0C7FF",
        "weight": 1,
        "reward": {
          "title": { "text": "20% off your next service", "color": "#FFFFFFFF" },
          "code": "SPIN20",
          "button": {
            "text": { "text": "Claim service deal", "color": "#FFFFFFFF" },
            "background": "#30B0C7FF",
            "border": { "color": "#30B0C7FF", "radius": 12 },
            "action": { "type": "url", "url": "pushwoosh://service" }
          }
        }
      },
      { "message": { "text": "Free wash", "color": "#FFFFFFFF" }, "color": "#FF2D55FF", "weight": 1 }
    ]
  }
}

stories

Полноэкранные слайды с индикаторами выполнения вверху, похожие на истории в социальных сетях.

Поле	Тип	Обязательно	Описание
showClose	boolean	да	Показывать кнопку закрытия (✕)
loop	boolean	да	Начать с первого слайда после последнего
items	Item[]	да	Слайды (не менее 1)

Элемент историй:

Поле	Тип	Обязательно	Описание
title	Text	нет	Заголовок
message	Text	нет	Подзаголовок
image	string	нет	Фоновое изображение слайда
buttons	Button[]	да	Кнопки призыва к действию внизу (может быть пустым)
duration	number	да	Продолжительность слайда в секундах

{
  "displayType": "stories",
  "stories": {
    "showClose": true,
    "loop": false,
    "items": [
      {
        "image": "https://example.com/slide-1.jpg",
        "title": { "text": "AMG GT R", "color": "#FFFFFFFF" },
        "message": { "text": "The Green Hell special", "color": "#FFFFFFFF" },
        "buttons": [
          {
            "text": { "text": "Configure yours", "color": "#FFFFFFFF" },
            "background": "#0F0F0FFF",
            "border": { "color": "#0F0F0FFF", "radius": 26 },
            "action": { "type": "url", "url": "pushwoosh://product/n6fx" }
          }
        ],
        "duration": 4
      },
      {
        "image": "https://example.com/slide-2.jpg",
        "title": { "text": "Alpine A110", "color": "#FFFFFFFF" },
        "message": { "text": "The featherweight legend, reborn", "color": "#FFFFFFFF" },
        "buttons": [],
        "duration": 4
      }
    ]
  }
}

video

Полноэкранное видео с текстом и кнопками поверх него.

Поле	Тип	Обязательно	Описание
showClose	boolean	да	Показывать кнопку закрытия (✕)
loop	boolean	да	Зациклить воспроизведение
muted	boolean	да	Начать с выключенным звуком
url	string	да	URL-адрес видео (HLS или MP4)
poster	string	нет	Постер, отображаемый до начала воспроизведения
fallback	string	нет	Изображение, отображаемое, если видео не удалось воспроизвести
title	Text	нет	Заголовок
message	Text	нет	Основной текст
buttons	Button[]	да	Кнопки призыва к действию внизу (может быть пустым)

{
  "displayType": "video",
  "video": {
    "showClose": true,
    "loop": true,
    "muted": true,
    "url": "https://example.com/reveal.mp4",
    "poster": "https://example.com/poster.jpg",
    "title": { "text": "The reveal", "color": "#FFFFFFFF" },
    "message": { "text": "Watch it move before anyone else.", "color": "#EBEBEBFF" },
    "buttons": [
      {
        "text": { "text": "Shop the lineup", "color": "#FFFFFFFF" },
        "background": "#0E72E5FF",
        "border": { "color": "#0E72E5FF", "radius": 14 },
        "action": { "type": "url", "url": "pushwoosh://sale" }
      }
    ]
  }
}

Локализация

Нативные In-App сообщения используют тот же механизм локализации, что и HTML Rich Media: строковые значения в native-config.json могут содержать плейсхолдеры {{key|type|default}}, а переводы находятся в файле pushwoosh.json рядом с ним, в том же формате, который описан в разделе Добавление pushwoosh.json. Плейсхолдер может находиться в любом строковом поле на любой глубине (заголовок, надпись на кнопке, URL-адрес изображения, URL-адрес действия).

Примечание

Неразрешенный плейсхолдер локализации заменяется своим значением по умолчанию.

Динамический контент

Текстовые поля — title, message, text кнопки, reward.title/reward.message и message элемента/сегмента — также принимают динамический контент и синтаксис Liquid: те же сокращения {Tag|modifier|default} и теги Liquid {% %}/{{ }}, которые используются в пушах и email-сообщениях. Pushwoosh обрабатывает их для каждого получателя перед отправкой сообщения, так же, как и для пушей и email.

При создании шаблона в редакторе нативных In-App сообщений в Control Panel вставленные токены отображаются в виде чипов в предпросмотре, а кнопка Сохранить блокируется, если Liquid в текстовом поле не может быть обработан.

Интеграция SDK

После добавления в приложение модуля SDK для нативных In-App сообщений они будут отображаться автоматически. Для показа сообщений, вызванных пушем, Customer Journey, postEvent или из папки «Входящие», не требуется дополнительный код.

SDK также предоставляет небольшой API для ручного управления:

• iOS: Pushwoosh.inApp (модуль PushwooshInApp)
• Android: PushwooshInAppUi (модуль pushwoosh-inapp-ui)

Возможность	iOS	Android
Показать конфигурацию напрямую (тестирование/ручное использование)	Pushwoosh.inApp.present(config)	PushwooshInAppUi.present(configJson)
Наблюдать за жизненным циклом и кликами	delegate (PWInAppMessageDelegate)	delegate (InAppMessageDelegate)
Проверить, отображается ли что-то на экране	isPresenting	isPresenting
Закрыть то, что отображается в данный момент	dismiss()	dismiss()
Приостановить / возобновить отображение	isPaused	isPaused
Применить ограничение maxDisplays / cooldown	setFrequencyCapEnabled(_:)	setFrequencyCapEnabled(...)

Осторожно

Ограничение частоты показов, настроенное в настройках отображения кампании, не применяется автоматически для нативных In-App сообщений, в отличие от классических Rich Media. SDK игнорирует maxDisplays/cooldown до тех пор, пока вы явно не вызовете setFrequencyCapEnabled(true). Даты начала/окончания показа сообщения всегда соблюдаются независимо от этой настройки.

Колбэки делегата (все вызываются в основном потоке): shouldDisplay (верните false, чтобы скрыть одно сообщение до его показа, например, на экране оформления заказа), willPresent, didPresent, didClose и clickedAction (вызывается, когда пользователь нажимает на действие url, перед открытием URL).

Для iOS дополнительно сообщаются rewardRevealed и rewardClaimed для геймифицированных шаблонов scratchcard и spinwheel.

// iOS
Pushwoosh.inApp.delegate = self
Pushwoosh.inApp.setFrequencyCapEnabled(true)

// Android
PushwooshInAppUi.delegate = this
PushwooshInAppUi.setFrequencyCapEnabled(true)