Есть артефакт, который превращает фразу «отправляйте нам конверсии» в перечень полей: контракт схемы событий. У каждого поля в нём каноническое имя, состояние обязательности, деловой смысл, владелец и уровень доказательства. Обсуждать такую бумагу выгодно до старта работ: после запуска те же вопросы приходится задавать уже по данным, которые ушли в приёмник.
Два более дешёвых вопроса стоят раньше. Измерим ли путь вообще и кто отвечает за его участок. Оба разобраны в соседних материалах этой группы, а здесь третий: какие данные отправляются из вашей системы и в каком формате.
Отдельно о границах. Справочник полей конкретной платформы - это не контракт схемы событий; сводный перечень требований шести сетей уже собран в статье Матрица параметров конверсий для платформ. Согласуйте интерфейс между системой-источником и исполнителем интеграции так, чтобы обе стороны могли сослаться на конкретную строку документа.
Что контракт схемы событий решает до начала разработки
Самый дорогой спор в проекте кастомной передачи конверсий звучит просто: обязательна ли эта колонка.
Соглашение заканчивает его тем, что отказывается от булева флага и записывает состояние. Вторая
ловушка прячется в смысле: две системы держат поле order_id и подставляют в него заказ, счёт и
продление подписки в одну неделю.
Разделите соглашение на четыре задачи: нормализация полей, сопоставление с приёмниками, обработка дублей и проверка доставки. Для каждого поля запишите исходное и каноническое имя, а также условия конкретного приёмника.
Для обработки дублей согласуйте идентификатор и его владельца отдельно по каждому назначению. Дедупликация по event_id разобрана на примере Facebook Pixel и CAPI, а повторная доставка описана в статье о ретраях. Запрос, ответ и запись у приёмника подтверждают разные этапы; см. уровни доказательства конверсии в Telegram.
Оба шаблона ниже предназначены для соглашения между заказчиком и исполнителем. Они не описывают API продукта.
Состояний обязательности четыре, и одна колонка их не вмещает
| Состояние | Как это записано у приёмника | Что должно стоять в ячейке | Что письменно отвечает владелец данных |
|---|---|---|---|
| Всегда обязательное | Meta помечает event_name, event_time, user_data и action_source как Required на странице параметров серверного события | Поле присутствует в каждом событии, исключений нет | Какая из ваших систем способна не выдать это поле |
| Обязательное для одного сценария | event_source_url помечен Optional и тут же оговорён как обязательный для веб-событий; Google требует user_identifiers для расширенных конверсий лидов и cart_data для корзинных данных | Назван сценарий, который включает требование | Какие сценарии этот путь обслуживает |
| Необязательное, но связывающее после заполнения | По Google: order_id допустимо не заполнять; после первого заполнения значение становится обязательным для любых корректировок | Переключатель в одну сторону: кто вправе начать слать и кто не вправе перестать | Отправляется ли это значение уже где-нибудь |
| Рекомендованное с последствиями | Google рекомендует consent в ClickConversion: без него конверсии могут не атрибутироваться | Последствие записано в самой строке | Кто принимает этот риск и как это видно |
Третья строка таблицы обычно и удивляет, поэтому её лучше цитировать, а не пересказывать:
Это поле необязательно, но настоятельно рекомендуется: оно упрощает обращение к импортированным конверсиям при корректировках. Если вы указали его при импорте, используйте его при любых корректировках.
Два примера Meta показывают, почему одного флага «обязательно/нет» может быть недостаточно. В параметрах данных пользователя Meta требует хотя бы одно из перечисленных полей user_data в правильном формате. Это условие для набора идентификаторов, используемых как идентификатор сопоставления, а не общее правило всех приёмников. Отдельно руководство Meta по использованию API задаёт общий предел для event_time: семь дней. Более старое значение вызывает ошибку всего запроса, и события не обрабатываются. В том же руководстве отдельно указано, что офлайн-транзакции и покупки в физических магазинах с action_source: physical_store следует загружать в течение 62 дней после конверсии. Эту оговорку нужно учитывать для соответствующего источника события. В другом описанном случае некорректного события запрос возвращает ошибку, но валидные события с event_id принимаются. Для каждого приёмника запишите применимые правила времени и обработки пакета; сам ответ не подтверждает атрибуцию.
Девять колонок, которые обязана содержать каждая строка поля
Формат строк не обсуждается только один раз: девять колонок идут в одинаковом порядке, иначе два ревизора сравнивают разные вещи.
- Каноническое имя плюс имя в источнике. Без такой пары переименование поля в CRM оборачивается тихой поломкой отображения, с ней правка превращается в запись в журнале изменений. Сопоставление имён стандартных событий разобрано в статье Стандартные события CAPI: одна конверсия, шесть названий.
- Тип и формат, включая правило часового пояса. Google требует в
conversion_date_timeявное смещение в маскеyyyy-mm-dd HH:mm:ss+|-HH:mm, а Meta ждёт unix-время в секундах и настаивает на GMT. - Состояние обязательности вместе с условием из таблицы выше.
- Деловой смысл словами вашей системы: какой объект, какое изменение состояния и в какой момент событие считается случившимся.
- Источник истины. Одно поле, одна система, которая его ставит; остальные только читают.
- Поведение при отсутствии значения, потому что пустая строка, ноль и пропущенный ключ - это три разных запроса, и приёмники обрабатывают их неодинаково.
- Преобразование и место его применения: хеширование и нормализация разобраны в статье Хэширование Meta CAPI: нормализация данных для сопоставления.
- Уровень доказательства, который поле обеспечивает, плюс артефакт, где этот уровень видно.
- Владелец и версия, чтобы переименование, новое значение перечисления или отброшенная колонка становились подписанной правкой с датой.
# Авторский шаблон строки соглашения; это не формат API Most.
field: order_id
source_names: ["crm.deal.external_key", "billing.invoice.number"]
type_format: "строка ровно в том виде, в каком её хранит источник, включая ведущие нули и регистр"
requiredness: "необязательно до первой отправки, затем обязательно для корректировок"
meaning: "номер оплаченного счёта, а не объекта сделки"
source_of_truth: "биллинг; CRM копирует значение и не создаёт его"
when_absent: "ключ пропускается; пустая строка не отправляется"
transformation: "преобразования нет; значение не хешируется"
proof_level: "принято: тело ответа того же запроса; учтено: отчёт приёмника по конверсии за именованное действие и окно"
owner_version: "v3, согласовано 2026-09-10, владелец: финансовый отдел"Ячейка формата намеренно не содержит ограничения по длине. Страница Google про order_id
документирует статус из цитаты выше и ещё одно ограничение, в таблице типовых ошибок:
DUPLICATE_ORDER_ID возникает, когда несколько конверсий пришли с одним Order ID, такие события
остаются необработанными, и повторить запрос предлагается с уникальными значениями. Это правило про
повтор, а не про длину. Если приёмник накладывает ограничение по длине или составу символов,
ячейка называет это ограничение и страницу приёмника, где оно напечатано. Когда опубликованной
страницы с таким правилом нет, в соглашении стоит форма, которую хранит источник: выдуманный
диапазон в копируемом шаблоне - дефект документа, а не данных.
Вопросы, на которые владелец данных отвечает письменно
Ревизия схемы - это список вопросов, и каждый обязан вернуться текстом.
- Какой объект и какое изменение состояния считаются событием на языке вашей CRM?
- Существует ли значение в момент срабатывания триггера или появляется после правки менеджера?
- Означает повтор идентификатора транзакции повторную отправку, возврат или продление?
- Что означает ваш штамп времени: клик, отправку формы или закрытие сделки? Последствия поясов измеримы и описаны в статье Event time, таймзоны и окна приёма.
- Если одно поле заполняют две системы, чьё значение выигрывает и кто заметит смену правила?
- В какие приёмники это событие реально уходит, раз обязательность зависит от назначения?
- Кто подписывает новую колонку и что происходит с историческими событиями при смене смысла?
Набор материалов, который заказчик передаёт на аудит, собирается в отдельный документ, и данный список его не заменяет: эти ответы ложатся в основу соглашения. Шапка документа нужна затем, чтобы контракт схемы событий был подписан и переживал правки, а не жил в переписке.
контракт схемы событий
область = <одно имя события и его объект-источник>
назначения = <перечисленные рекламные платформы этого пути>
версия = 3 дата применения 2026-09-10
строки полей = <по строке на поле, девять ячеек в каждой>
правило правок = <кто подписывает переименование, новый enum, удалённую колонку>
вне объёма = <атрибуция, ставки, отчётные результаты>Дефекты соглашения: симптом, доказательство, следующий тест
| Симптом в соглашении | Какой артефакт затребовать | Следующий тест |
|---|---|---|
| Одно имя, два смысла | По пять свежих записей из каждой системы, где заполнена колонка | Проверить, не ставит ли одно значение два разных объекта |
| Поле объявлено обязательным и приходит пустым | Журнал исходящих за сутки и ответы приёмника по этим вызовам | Повторить одно записанное событие с пустым полем через тестовый канал приёмника и записать ответ: пустое значение принято - в соглашении пропущена ячейка условия, отклонено - источник нарушает задокументированное правило |
| Сумма отправляется без валюты | Тело исходящего запроса с суммой без кода валюты и ответ приёмника с ошибкой валидации валюты | Отправить одно событие с пустой ячейкой валюты |
| Времена расходятся на фиксированный сдвиг | Конвенция пояса в источнике и ячейка формата в соглашении | Сравнить событие с явным смещением UTC |
| Два ключа дедупликации из двух отделов | Значения обоих ключей до вызова плюс принятый пакет | Сравнить число событий по каждому ключу и по суткам отдельно |
| Переименованное поле CRM тихо сломало отображение | Строка соответствия и запись журнала изменений | Внести переименование в тестовую связку и записать, остановит ли её шаг согласования до отправки событий; переименование без остановки и есть пропущенная ячейка владельца и версии |
| Пакет принят, платформа ничего не показывает | Ответ приёмника и отчёт диагностики за то же окно | Отделить запись о приёмке от учтённой конверсии |
Строки разбираются по порядку, и останавливаться надо на первом артефакте, которого ни у кого нет. Пропуск в контракте схемы событий - бумажный дефект, а инженерным он становится позже.
Что согласованная схема не решает
Идеальный контракт схемы событий не заставляет платформу ничего атрибутировать. Документ определяет, что вы отправляете, что отвечает приёмник и какая запись подтверждает каждый уровень; сопоставление с кликом, правила подсчёта и отнесение остаются решениями платформы, и про ставки верно то же самое. Google описывает верхнюю границу импорта прямым текстом: конверсии, загруженные позже 90 дней после связанного последнего клика, не импортируются. Для расширенных конверсий лидов окно ещё короче - 63 дня (Рекомендации по импорту офлайн-конверсий). Соглашение, которое обещает результат внутри аукциона, подписывать не стоит.
Объём реализации, сроки и уровень обслуживания согласуйте отдельно от перечня полей. Контракт схемы событий сам по себе этих условий не устанавливает.
Нужно уточнить поле?
Пришлите обезличенный перечень полей и вопрос о требованиях. Первая консультация бесплатная.
Не отправляйте токены и пароли.
Источники
Sources
Услуги Way2