Формат общения

Предыдущее: архитектура взаимодействия.

В процессе работы потребителя с тегом обмен данными в обе стороны происходит по протоколу https в формате json. Давайте разберемся с запросами в каждом направлении и посмотрим примеры.

Запрос к бекенду

Формат запроса к бекенду регламентируется данной схемой, где обязательными полями являются:

• $schema (string) - версия JSON-схемы;
• client (object) - информация о клиенте (тип, версия);
• activetag (string) - активный тег;
• userID (int) - идентификатор пользователя.

Пример запроса к бекенду:

{
    "$schema": "http://theactivetag.com/schemas/backend-request-1.0.schema.json",
    "client": {
        "name": "Browser",
        "version": "1.0.0"
    },
    "language": "ru",
    "activetag": "activetag-hello",
    "userID": 1
}
			

Получив подобное сообщение, бекенду следует изучить его содержимое (в первую очередь поле activetag) и дать ответ - предложить потребителю информацию о товаре, услуге или ином объекте.

Подробнее о назначении каждого поля запроса смотрите в справке по json-запросам.

Ответ бекенда

Отвечать следует в соответствие с этой схемой, где обязательными полями являются:

• $schema (string) - версия JSON-схемы;
• result (array) - содержимое ответа.

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

• markdown - форматированный текст;
• text - неформатированный текст;
• imgURL - ссылка на изображение;
• videoURL - ссылка на видео Youtube или Vimeo;
• и другие.

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

Запрос на действия

А действия предлагаются потребителю в ответе бекенда через необязательный объект menu. Это список элементов меню (кнопок) и прикрепленные к этим кнопкам поля для заполнения пользователем.

Названия элементов меню - произвольные. Набор связанных с ними полей для заполнения - тоже.

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

Пример ответа бекенда:

{
    "$schema": "http://theactivetag.com/schemas/backend-response-1.0.schema.json",
    "result": [
        {
            "imgURL": "http://example.com/activetag.png"
        },
        {
            "text": "Привет, я Активный тег!"
            "markdown": "Привет, я *Активный тег*!"
        }
    ],
    "menu": {
        "items": [
            {
                "name": "Познакомиться",
                "url": "http://example.com/backend/hello",
                "req": [
                    {
                        "type": "name",
                        "name": "first_name",
                        "title": "Ваше имя",
                        "desc": "Как вас зовут?"
                    }
                ]
            }
        ]
    }
}
			

Подробнее о назначении каждого поля ответа и о типах полей - смотрите в справке по json-ответам.

Тег без артикула

На бекенд может поступить запрос с тегом, состоящим из одного основания, без артикула (adidas или prodam). Технически это обыкновенный тег, который ничем не отличается от тега с артикулом (adidas-ball или prodam-avto). В ответ на такие запросы принято сообщать информацию о компании, бренде или владельце основания.

Идемпотентность

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

Ошибки

В случае возникновения ошибок на бекенде, следует возвращать их в ответе. Для этого в схеме предусмотрено поле error, куда помещается код ошибки и текстовое ее описание. А отображаемое сообщение для потребителя размещаем в поле result.

Пример ответа "тег не найден"

{
    "$schema": "http://theactivetag.com/schemas/backend-response-1.0.schema.json",
    "error": {
        "code": 404,
        "desc": "Article not found"
    },
    "result": [
        {
            "text": "Артикул не найден."
        }
    ]
}
			

Далее: json-запрос...