Свойства покупателя

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

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

Об оплате свойства ничего не говорят: пускать ли в платное, решает проверка права доступа.

Перед началом

• Идентификатор покупателя (guid) в приложении — «Как мы узнаём покупателя».
• Ключ доступа на вашем сервере — «Аутентификация». Без ключа запрос не работает, поэтому приложение спрашивает свойства у вашего сервера, а не у нас.

Запрос и ответ

curl "https://api.subster.ai/s2s/v1/user/properties?guid=<GUID>" \
  -H "Authorization: Bearer sk_live_…"

{
  "user_id": "abc123def456",
  "guid": "abc123def456",
  "email": "[email protected]",
  "properties": [
    { "property": "country", "value": "DE", "block_id": null },
    { "property": "utm_campaign", "value": "spring_sale", "block_id": null },
    { "property": "Какая у вас цель?", "value": "b7c1e0d2-…", "block_id": "3f9a41c8-…" },
    { "property": "Ваш вес", "value": "70 kg", "block_id": "8d20e6f5-…" }
  ]
}

В списке три вида свойств:

• ответы на вопросы квиза — имя свойства равно тексту вопроса, который видел покупатель;
• метки кампании utm_source … utm_content — с первого захода в воронку: повторный заход с другими метками их не перезапишет;
• country — страна по IP-адресу при первом заходе, двухбуквенным кодом.

Идентификатор неизвестный или из другого проекта — даже вашей же организации — даёт отказ 404. Знакомый покупатель без свойств — успех и пустой список. Отказы из-за формы запроса те же, что у запроса права доступа с ключом. Потолок — 120 запросов в минуту на ключ, у чтения и записи свойств счётчики раздельные («Аутентификация»).

Какой экран пропустить

Показывайте экран онбординга, только если в списке нет ответа с идентификатором его вопроса (block_id). Сверяйте именно block_id: текст вопроса меняется, когда владелец правит формулировку или переводит воронку, а block_id остаётся прежним.

Что лежит в value, зависит от вопроса:

Для пропуска экрана хватит block_id. Чтобы подставить сам ответ — например, выбранную цель, — сопоставьте идентификаторы вариантов со своими значениями:

{
  "3f9a41c8-…": { "b7c1e0d2-…": "lose_weight", "e04a9b31-…": "build_muscle" }
}

Если покупатель прошёл квиз ещё раз с тем же идентификатором, новый ответ на вопрос заменяет прежний.

Собрать block_id и идентификаторы вариантов можно только своим проходом воронки: пройдите её, вернитесь в приложение и запросите свойства — в ответе будет каждый вопрос с выбранным вариантом. Один проход даёт один вариант на вопрос, поэтому для вопроса с тремя вариантами нужно три прохода, и в каждом выбирайте другой вариант. Добавил владелец новый вариант — пройдите воронку ещё раз.

Копия воронки, в том числе для A/B-теста, получает новые идентификаторы вопросов и вариантов. Соберите их для копии тем же проходом и храните соответствие отдельно для каждой воронки.

Почему ответа может не быть

• Покупатель попал на экран с ценами мимо квиза.
• Он пропустил необязательный вопрос или не увидел его из-за ветвления.
• Он отказался от отслеживания на странице воронки, а в ЕС — не дал на него согласия. Тогда мы не сохраняем ни ответы, ни метки, ни страну.
• Квиз с блоком согласия на сбор ответов: без этой галочки ответы следующих экранов не сохраняются.

Поэтому онбординг целиком не убирайте: пропускайте только те экраны, ответ на которые пришёл.

Записать своё свойство

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

curl -X POST "https://api.subster.ai/s2s/v1/user/properties?user=<GUID>" \
  -H "Authorization: Bearer sk_live_…" \
  -H "Content-Type: application/json" \
  -d '{ "property": "onboarding_goal", "value": "strength" }'

Ответ — { "success": true }. Один запрос записывает одно свойство: несколько свойств — несколько запросов. Повторная запись того же имени заменяет значение; block_id у своего свойства — null.

Семь имён пишем только мы: utm_source, utm_medium, utm_campaign, utm_term, utm_content, country, email. Запись под таким именем получит отказ 400 с кодом reserved_property. Если покупатель явно отказался от отслеживания, запись отклоняется отказом 409 с кодом consent_denied.

Если воронка уводит человека на ваш сайт

Воронка может закончиться не оплатой у нас, а переходом на ваш адрес — кнопкой-ссылкой, блоком «Редирект на URL» или правилом перехода. Тогда те же сведения приезжают параметрами в этом адресе, без запроса к нам.

Владелец проекта вписывает в адрес метки в фигурных скобках, а мы подставляем значения в момент ухода. Список меток он видит под полем адреса, в подсказке «Метки в исходящем адресе».

https://your-site.io/pay?src={utm_source}&cid={click_id}&goal={answer.<question-id>}

Метки подставляются только в значения параметров. Если значения для метки нет, а параметр состоял только из неё, как cid={click_id}, параметр пропадает из адреса целиком: ваша страница должна переживать его отсутствие.

Пустыми придут:

• ответ вопроса без галочки «Передавать ответ в исходящий адрес» в конструкторе. Галочка есть только у блоков «Один вариант», «Несколько вариантов» и «Многошаговый вопрос»: ответы шкал, оценок и полей ввода в адрес не уходят;
• все ответы в воронках про похудение, здоровье, психику и веру — там галочка не действует;
• все метки, если посетитель отказался от отслеживания или его браузер запрещает передачу данных (Global Privacy Control);
• идентификатор посетителя и ответы, если человек пришёл через направление A/B-теста «Добавить URL»: квиза в этом пути не было.

Почты, телефона, имени и текста, который человек ввёл сам, среди меток нет. Воронку с такой меткой кабинет не сохранит.

Дальше

• Проверить право доступа — оплачен ли доступ у этого покупателя.
• Вебхуки — узнавать об ответах в момент, когда покупатель их даёт: события user.property_updated и user.properties_completed.
• Как мы узнаём покупателя — откуда у приложения идентификатор, по которому спрашивать свойства.