Отправить событие нам

Вы сообщите нам с вашего сервера о регистрации, установке или покупке в приложении — так, чтобы событие дошло до рекламных сетей один раз.

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

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

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

Тариф Pro или Business. На бесплатном тарифе адрес отвечает отказом на любой запрос.
Ключ доступа. Право принимать события у ключа есть по умолчанию; где его выпустить — «Аутентификация».
ID проекта. Кабинет: Настройки проекта → Подключение приложения → Для разработчика, поле «ID проекта».
Подключённые рекламные сети. Их подключает владелец проекта: Настройки проекта → «Аналитика и пиксели» → «Рекламные источники», по шагам — «Рекламные сети и пиксели» на дорожке владельца. Не подключено ни одной — событие примем, но отправлять его будет некуда.

Что присылать

Событие	Когда присылать
`registration`	человек завёл учётную запись в приложении
`app_installed`	приложение установлено
`purchase`	покупка внутри приложения или на вашем сервере

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

Событие о покупке не открывает покупателю доступ в приложении: это сообщение для рекламных сетей и партнёра.

Запрос

curl -X POST "https://api.subster.ai/public/event" \
  -H "Authorization: Bearer sk_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "event": "purchase",
    "projectId": "<PROJECT_ID>",
    "eventId": "ios-iap-2000000712345678",
    "guid": "abc123def456",
    "amountCents": 1999,
    "currency": "usd",
    "consent": "granted"
  }'

Поле	Обязательное	Что это
`event`	да	тип события из таблицы выше
`projectId`	да	ID проекта; нужен и в запросе с ключом
`eventId`	да	ваш номер события: от 8 до 64 знаков, только латиница, цифры и `. _ ~ -`
`guid`	нет	идентификатор покупателя, если он у вас есть (откуда он берётся)
`email`	нет	почта покупателя

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

Ответ — 204 без тела. Если ключ на этом участке держать негде, подпишите тело секретом: порядок описан в «Аутентификации».

Как не задвоить событие

Повтор с тем же номером события в том же проекте мы отбрасываем, а отвечаем так же, как на первый.

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

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

Об установке нам могут сообщить ещё наша библиотека в приложении и трекер установок. Если мы узнали покупателя — по идентификатору guid или по почте, которую он у нас подтвердил, — все сообщения склеятся в одну установку, и она попадёт в отчёт владельца проекта. Без этого склеивать не с чем: каждое сообщение станет своей конверсией, а в отчёте установки не будет.

Без согласия покупателя конверсия не уйдёт

Рекламной сети мы передаём данные о человеке: почту, телефон, IP-адрес, метки клика. Для этого нужно основание — согласие покупателя на отслеживание. Годится одно из двух:

Наша запись. Её мы находим, только если узнали покупателя — по идентификатору или подтверждённой почте. Годится она, когда человек сам прошёл вашу воронку в браузере и не отказался от отслеживания на баннере, а посетитель из Европы согласился явно.
Ваше заявление — поле consent в теле события: "granted" или "denied".

Нет ни того, ни другого — конверсия в сеть не уйдёт. Мы всё равно ответим успехом, ваш сервер ничего не узнает, а рекламный кабинет недосчитается продажи. У покупателя, который попал в приложение мимо воронки, нашей записи нет: за него решает только ваше поле.

Отказ сильнее согласия. Отказ в вашем заявлении останавливает отправку. Записанный у нас отказ самого человека останавливает её и при вашем согласии.
Заявление — ваша ответственность. Согласие покупателя собираете вы. Мы храним каждое заявление рядом с событием: что заявлено, когда и каким ключом или подписью.
Поле решает только про рекламные сети. Отчёт в трекер партнёра его не читает. По покупателю, пришедшему мимо воронки, отчёт решает по стране IP-адреса, с которого шлёт ваш сервер: вне ЕС уйдёт, в ЕС — нет.

Отправку видно в кабинете: Настройки проекта → «Аналитика и пиксели» → «Рекламные источники», у подключённой сети кнопка «Журнал отправок». Строка «Решили не слать» с причиной про согласие у события без вашего заявления значит, что основания не нашлось.

Поля для рекламных сетей и партнёра

Все необязательные: без них событие примем, но сеть получит меньше.

Чтобы	Пришлите
покупка ушла в сеть с ценностью	`amountCents` и `currency` вместе; валюта — код ISO 4217 из трёх букв, регистр любой: `usd` и `USD` равны
сеть узнала человека	`phone` — с кодом страны, например `+15551234567`: номер без него сеть не узнает; для Meta `fbc` и `fbp` — значения кук `_fbc` и `_fbp` из браузера покупателя; для TikTok `ttp` — кука `_ttp`, `ttclid` — метка клика из адреса, по которому он пришёл; `clientIp` и `clientUserAgent` — адрес и браузер покупателя, а не вашего сервера
партнёр отнёс продажу к клику	`clickId`, `transactionId`; без номера сделки партнёр получит вместо него ваш `eventId`
конверсия легла на свой день	`eventTimeSec`
TikTok получил адрес страницы — у него это поле обязательное	`eventSourceUrl`: только настоящий адрес; нет его — не присылайте поле
проверочная покупка не ушла ни в сеть, ни партнёру	`livemode: false`

Сумма — в минимальных единицах валюты, несмотря на слово «cents» в имени поля: 19,99 USD — это 1999, а 500 иен — 500, у иены и воны деления нет. Валюту присылайте вместе с суммой. Без неё покупка уйдёт в сеть без ценности, а сумма в иенах у партнёра окажется в сто раз меньше. Сумма и номер сделки работают только у purchase.

Время события — unix-время в секундах, не в миллисекундах. Оно нужно, если вы копите события и шлёте пачкой: иначе сеть отнесёт покупку ко дню доставки. Сети не берут события старше семи суток, поэтому время старше «шесть суток и восемнадцать часов назад» мы сдвинем на эту отметку — шесть часов оставлены на дорогу до сети. Время позже чем через час станет «через час». Миллисекунды получат отказ 400.

Незнакомые поля мы отбрасываем без ответа. Опечатка в имени, например amount вместо amountCents, не даст отказа, а сумма потеряется.

Событие без единого признака человека в сети не отправляется. Признаки — идентификатор, почта, телефон, метки клика, адрес и браузер покупателя. В журнале отправок у каждой подключённой сети такое событие оставит строку «посетителя не по чему опознать». Полный список полей с пределами длины — в Справочнике.

Проверочные события

Проще всего отлаживаться тестовым ключом sk_test_…: событие с ним проверочное, если в теле нет поля livemode. Шлёте боевым ключом или подписываете тело секретом — помечайте проверочную покупку признаком из таблицы выше. Значение поля в теле сильнее режима ключа.

Признак останавливает и рекламные сети, и отчёт в трекер партнёра.

Согласие проверочное событие не проверяет: оно отсеивается до этой проверки, и в журнале отправок будет строка «проверочная покупка». Первое боевое событие сверьте с журналом отдельно.

Отказы

Ответ	Когда приходит
`204`	событие принято, либо это повтор уже принятого
`400` с полем `code`	событие не принято, исправьте тело и повторите с тем же номером: `event_time_in_milliseconds` — время в миллисекундах, `invalid_currency` — валюты нет в списке ISO 4217, `invalid_client_ip` — `clientIp` не IP-адрес
`400` без кода	тело не разобралось: нет обязательного поля, `event` не из трёх, `projectId` не в формате UUID, номер события, идентификатор или почта не по формату. Какое поле виновато, ответ не говорит
`404`	ключ неизвестен, подпись не сошлась или устарела, тариф проекта не оплачен — ответ один на всё, и по нему причину не отличить. Проверьте по порядку: ключ или подпись (метка времени подписи в секундах вместо миллисекунд тоже даёт `404`), затем тариф проекта у владельца
`429` с полем `code`	превышен потолок частоты: `PUBLIC_EVENT_PROJECT_RATE_LIMITED` — больше 300 событий в минуту на проект; `PUBLIC_EVENT_FAILED_AUTH_RATE_LIMITED` — больше 60 запросов в минуту с одного адреса без верного ключа или подписи; `PUBLIC_EVENT_IP_RATE_LIMITED` — больше 3000 любых запросов в минуту с одного адреса. Подождите столько секунд, сколько в заголовке `Retry-After`, и повторите с тем же номером
`500`	мы не записали событие — повторите с тем же номером

Коротко

Номер события берите из своей записи: повтор с тем же номером отбрасывается целиком.
Присылайте заявление о согласии: без него покупка человека, пришедшего мимо воронки, в сеть не уйдёт, а ответ всё равно будет успешным.
Сумму — в минимальных единицах и всегда вместе с валютой.
Проверочные события шлите тестовым ключом либо помечайте признаком из таблицы полей.

Дальше

Вебхуки — обратное направление: наши события на ваш сервер.
Аутентификация — ключ доступа и подпись запроса секретом.
Как мы узнаём покупателя — откуда берётся идентификатор, который стоит класть в событие.
Диагностика — что делать, когда адрес отвечает отказом без объяснений.

Дальше

Рецепты

Открыть →