Динамические формы

IMSHOP Retail Protocol (IRP) является объектом интеллектуальной собственности ООО «АЙ ЭМ СОЛЮШНЗ» (IMSHOP) и защищён как объект авторского права. Свидетельство о депонировании произведения № 023-014461 от 16 января 2023 г. подтверждает исключительные права ООО «АЙ ЭМ СОЛЮШНЗ» на данные технологии.

IMSHOP Retail Protocol создан по заказу ООО «АЙ ЭМ СОЛЮШНЗ». Использование IMSHOP Retail Protocol допустимо только при взаимодействии с ООО "АЙ ЭМ СОЛЮШНЗ" и наличии действующего лицензионного договора. Более подробно можно ознакомиться здесь.

Динамические формы – формы на сабтудеях с возможностью подгрузки дополнительных элементов форм на основе введенных пользователем данных.

Для корректной работы динамических форм необходимо включение интеграции.

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

В консоли при создании элементов сабтудея необходимо завести форму, дать ей идентификатор (для примера, form123) и отметить, что данная форма будет загружаться через IRP ендпоинт.

Механизм работы webhook-интеграции

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

{
  "formName": "form123"
}

При запросе формы из DSS-приложения в запрос дополнительно будет присылаться outletId магазина, привязанного к продавцу (в случае наличия привязанного магазина).

{
    "formName": "form123",
    "outletId": "id123"
}

В ответ сервер должен отправить содержание формы:

{
  "success": true,
  "name": "form123",
  "form": {
    "alertText": "We have received your feedback.",
    "alertTitle": "Thanks for participating",
    "title": "Запишитесь сегодня!",
    "elements": [...],
  }
}

success – boolean, успех отправки формы
name – название запрашиваемой и отправляемой формы
form
- alertText и alertTitle – заголовок и текст сообщения после заполнения формы
- title – заголовок формы
- elements – массив с элементами формы

Элементы формы в elements могут располагаться в произвольном порядке.

Элементы формы

Заголовок (title)

Заголовок или произвольная надпись в форме жирным шрифтом. Не распологается произвольно, всегда находится сверху формы.

Передается в form

"title": "Запишитесь сегодня!"

Барабан (picker)

Поле, при нажатии которого появляется барабан с возможностью выбора одного варианта.

Передается в elements

{
  "name": "service",
  "placeholder": "Выберите услугу",
  "required": true,
  "type": "picker",
  "title": "Выберите услугу",
  "list": ["Терапевт", "Ортопед", "Массажист"],
  "nextElementsNames": ["date"]
}

name – идентификатор элемента
placeholder – плейсхолдер для поля ввода
required – true/false, является для данный элемент обязательным для заполнения
type – тип элемента (picker)
title – заголовок элемента
list – массив из строк с вариантами выбора
nextElementsNames – подгрузка следующих элементов формы

Чекбокс (checkbox)

Чекбокс.

Передается в elements

{
  "name": "checkbox",
  "title": "Перезвоните мне",
  "type": "checkbox"
}

name – идентификатор элемента
type – тип элемента (checkbox)
title – надпись справа от чекбокса

Поле ввода текста (text)

Поле для ввода текста.

Передается в elements

{
  "name": "username",
  "placeholder": "Имя",
  "title": "Введите имя",
  "required": true,
  "type": "text"
}

name – идентификатор элемента
placeholder – плейсхолдер для поля ввода
required – true/false, является для данный элемент обязательным для заполнения
type – тип элемента (text)
title – заголовок элемента

Поле ввода эл.почты (email)

Поле с форматированием электронной почты.

Передается в elements

{
  "name": "email",
  "title": "Эл.почта",
  "placeholder": "Введите адрес",
  "required": true,
  "type": "email"
}

name – идентификатор элемента
placeholder – плейсхолдер для поля ввода
required – true/false, является для данный элемент обязательным для заполнения
type – тип элемента (email)
title – заголовок элемента

Поле ввода телефона (phone)

Поле с форматированием телефонного номера.

Передается в elements

{
  "name": "phone",
  "title": "Телефон",
  "placeholder": "Введите телефон",
  "required": true,
  "type": "phone"
}

name – идентификатор элемента
placeholder – плейсхолдер для поля ввода
required – true/false, является для данный элемент обязательным для заполнения
type – тип элемента (phone)
title – заголовок элемента

Поле ввода даты (date)

Поле, при нажатии которого отображается барабан с возможностью ввода даты.

Передается в elements

{
  "name": "dob",
  "title": "Дата рождения",
  "placeholder": "Выберите дату рождения",
  "required": true,
  "type": "date"
}

name – идентификатор элемента
placeholder – плейсхолдер для поля ввода
required – true/false, является для данный элемент обязательным для заполнения
type – тип элемента (text)
title – заголовок элемента

Кнопка завершения редактирования формы (submit)

Кнопка завершения заполнения формы, при нажатии данные отправляются на сервер и появляется сообщение.

Передается в elements

{
  "name": "submitBtn",
  "placeholder": "Записаться",
  "disabledPlaceholder": "Заполните поля",
  "type": "submit"
}

name – идентификатор элемента
placeholder – надпись на кнопке
disabledPlaceholder – надпись на кнопке в заблокированном состоянии ( когда пользователь не ввел данные в обязательные поля)
type – тип элемента (submit)

Примечание (notice)

Примечание, надпись мелким шрифтом.

Передается в elements

{
  "name": "notice",
  "placeholder": "Заполняя форму, вы соглашаетесь с условиями обработки персональных данных.",
  "type": "notice"
}

name – идентификатор элемента
placeholder – надпись
type – тип элемента (notice)

Ссылка (url)

Текст, по нажатию на который открывается ссылка.

Передается в elements

{
  "name": "url",
  "title": "Test url",
  "redirectTo": "https://google.com",
  "useExternalBrowser": false,
  "alignToLeft": false
  "type": "url"
}

name – идентификатор элемента
title – надпись
redirectTo – ссылка (поддерживаются диплинки)
useExternalBrowser – true/false, открывать ссылку во внешнем браузере (по умолчанию false)
alignToLeft – сместить текст к левому краю (по умолчанию false)
type – тип элемента (notice)

Сообщение после завершения заполнения формы (alert)

Сообщение, которое отображается после нажатия на сабмит.

Передается в form

"alertText": "We have received your feedback. Thanks for participating.",
"alertTitle": "Thanks for participating",

alertTitle – заголовок сообщения
alertText – тело сообщения

Markdown (markdown)

Rich-текст в формате Markdown.

Передается в elements

{
  "name": "md-el",
  "text": "## Example heading\n\n**Lorem ipsum dolor sit amet**, consectetur adipiscing elit. Mauris ante dolor, feugiat finibus nunc et, egestas auctor mi.\n\n*Quisque neque risus, vulputate at massa nec, ornare lobortis magna.*",
  "type": "markdown"
}

name – идентификатор элемента
text – текст в формате Markdown
type – тип элемента (markdown)

Пикер фотографий (images)

Rich-текст в формате Markdown.

Передается в elements

{
  "name": "photos-el",
  "minImages": 1,
  "maxImages": 3,
  "type": "images"
}

name – идентификатор элемента
minImages – минимальное количество фотографий для отправки (по умолчанию 0)
maxImages – максимальное количество фотографий для отправки (по умолчанию ограничение отсутствует)
type – тип элемента (images)

Изображения передаются в base64. При экспорте формы в поле data появится массив images следующего вида:

{
    ...
    "data": {
        ...
        "images": [
            {
                "id": "9e7f9397-10e7-47ab-9d02-75d611e77b39",
                "type": "image/jpg",
                "base64": "/9j/4AAQSkZJRgABAQAA..."
            },
            ...
        ]
    }
}

id – случайный идентификатор фотографии
type – MIME-тип изображения
base64 – закодированное изображение в base64

Авторизация покупателя (customer_auth)

Только для DSS. Авторизация или регистрация покупателя и последующая отправка его данных в форме.

Передается в elements

{
  "name": "customer-auth-el",
  "required": true,
  "type": "customer_auth",
  "nextElementsNames": ["picker"]
}

name – идентификатор элемента
required – true/false, является ли данный элемент обязательным для заполнения
type – тип элемента (customer_auth)
nextElementsNames – подгрузка следующих элементов формы (необязательно)

При экспорте формы в поле data появится объект customer следующего вида:

{
    ...
    "data": {
        ...
        "customer": {
            "name": "Dale Cooper",
            "phone": "79000000000",
            "email": "test@imshop.io",
            "externalId": "79000000000"
        }
    }
}

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

Помимо этого, запросе на экспорт формы будет приходить staffId продавца, с аккаунта которого была отправлена форма:

{
    "formId": "test-form",
    "installId": "123",
    "data": {
      ...
    },
    "staffId": "STAFF123"
    }
}

Запрос клиентом следующих элементов формы

В элементе барабана или авторизации покупателя возможно наличие идентификаторов следующих полей nextElementsNames. Дозапрос от сервера следующих элементов формы происходит после выбора пользователем значения в барабане, либо после авторизации покупателя.

Сервер принимает JSON с введенными пользователем значениями в поле data, где ключ – идентификатор элемента как в поле name в отправленных элементах:

{
  formName: 'form123',
  data: {
    checkbox: true,
    text: 'Some text',
    phone: '+7 (111) 111-1111',
    email: 'test@imshop.io',
    date: '25 января',
    picker: 'Ортопед'
  },
  nextElementsNames: [ 'next_services' ]
}

В ответ сервер отправляет следующие элементы форм, например:

{
  "name": "form123",
  "success": true,
  "elements": [
    {
      "name": "date",
      "placeholder": "Выберите дату",
      "required": true,
      "type": "picker",
      "title": "Выберите дату",
      "list": [
        "26 мая",
        "27 мая",
        "28 мая",
        "29 мая",
        "30 мая",
        "31 мая",
      ],
      "nextElementsNames": ["time"]
    }
  ]
}

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

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

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

PreviousКоллекции NextЭкспорт форм

Last updated 5 months ago

Динамические формы

Оглавление

Заведение сабтудея с поддержкой динамических форм

Механизм работы webhook-интеграции

Элементы формы

Заголовок (title)

Барабан (picker)

Чекбокс (checkbox)

Поле ввода текста (text)

Поле ввода эл.почты (email)

Поле ввода телефона (phone)

Поле ввода даты (date)

Кнопка завершения редактирования формы (submit)

Примечание (notice)

Ссылка (url)

Сообщение после завершения заполнения формы (alert)

Markdown (markdown)

Пикер фотографий (images)

Авторизация покупателя (customer_auth)

Запрос клиентом следующих элементов формы