Перейти к основному содержимому
Документация для версии v73

Регистрация события достижения цели

Описание​

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

Данные о событии достижения цели можно использовать в следующих механиках платформы:

URL-адрес​

Метод: POST

https://example.com/api/v1.1/goals/register

Параметры запроса​

Основные параметры​

ПараметрТипПримерОбязательныйОписание
tokenstring"abcdefghijklmnqrstuvwxyz"ДаAPI токен
db_idint1ДаИдентификатор базы данных
pixel_idint1ДаИдентификатор пикселя
goalstring"card"НетНазвание цели
goalsJSON array
[
    {
        "goal": "card", 
        "value": 10.0
    }
]
НетНесколько целей со значениями
valuefloat-25.5НетЗначение цели
datestring"2006-01-25T15:04:05+07:00"НетДата события в формате RFC 3339

Параметры матчинга​

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

ПараметрТипПримерОбязательныйОписание
matchingstring"email" – поиск по email из профиля или подписок

"email_profile" – по email из профиля

"email_sub" – по email из подписок

"phone" – по телефону из профиля или подписок

"phone_sub" – по телефону из подписок

"profile_id" – по идентификатору профиля (только при обновлении!)

"push_sub" – по пуш подписке

"custom" – по кастомному полю

"custom_sub" – по подписке на кастомный канал

"email_phone" – по email или телефону из профиля

"email_phone_sub" – по email или телефону из подписок		Нет, если поиск по email из профиля или подписокРежим поиска подписчика.
По умолчанию - email.
emailstring"john@example.com""matching":"email" - по профилю и подпискам

"matching":"email_profile" - только по профилю		Email-адрес
phonestring"+79000000000""matching":"phone"Номер телефона
profile_idstring"abcdefghijklmnqrstuvwxyz""matching":"profile_id"Идентификатор профиля
field_namestring"CRM_ID""matching":"custom"Название кастомного поля профиля для поиска.
field_valueint/string"12345""matching":"custom"Значение кастомного поля для поиска.

Доступен поиск по сочетанию значений поля с типом "теги". Теги передаются в строке черз запятую: "тег_1, тег_2".

Дополнительные параметры​

ПараметрТипПримерОбязательныйОписание
pixel_dataJSON object
{
   "key":"value",
   "array":[1,2,3]
}
НетJSON-объект с дополнительными данными события цели.

Объект не должен содержать вложенные объекты или массивы. Размер объекта не больше 1 KB.
skip_triggersboolfalseНетОтключает настроенные на событие триггеры и сценарии.

По умолчанию — false.
enrich_profilebooltrueНетСобытие обновляет данные профиля.

Используется для обновления данных через следующие поля: browser, os, device, country, region, city, zip, time_zone.
is_testboolfalseНетСобытие отмечается как тестовое для аналитики.

По умолчанию — false.
vendorstring"altcraft"НетПоле профиля _vendor на момент события
external_typestring"event_pixel_test"НетТип внешнего идентификатора
external_event_idstring"qwerty123"НетВнешний идентификатор
altcraft_client_idstring"9f11d32d-2935-43d0-b8df-f4c3568095b2"НетУникальный сквозной идентификатор Altcraft

HTTP-параметры​

ПараметрТипПримерОбязательныйОписание
refererstring"api.example.com"НетЗаголовок запроса Referer
user_agentstring"Mozilla/5.0 (Linux; Android 6.0.1; SM-G935S Build/MMB29K; wv)"НетЗаголовок запроса User-Agent
accept_languagestring"fr-CH, fr;q=0.9, en;q=0.8, de;q=0.7, *;q=0.5"НетЯзык операционной системы устройства клиента (Заголовок запроса Accept-Language)
client_ipstring"10.0.0.0"НетIP клиента из оригинального запроса
client_ip_v4string"198.16.74.224"НетIPv4 адрес клиента
client_ip_v6string"fe80::5215:5556:d75f:806b"НетIPv6 адрес клиента
browserstring"Chrome"НетБраузер клиента

Получить список допустимых значений можно через запрос /v1.1/dictionary ("browsers")
osstring"Ubuntu"НетОперационная система клиента

Получить список допустимых значений можно через запрос /v1.1/dictionary ("oses")
devicestring"Desktop"НетТип клиентского устройства

Получить список допустимых значений можно через запрос /v1.1/dictionary ("devices")
подсказка

Поля browser, os и device автоматически заполняются платформой на основе содержимого поля user_agent.

Если в одном запросе вы передаёте и user_agent, и отдельные значения для browser, os и device, то данные из user_agent имеют приоритет и перезаписывают указанные значения.

Если вы передаёте поля browser, os и device без user_agent, для обновления профиля необходимо указать "enrich_profile": true, иначе платформа не обновит профиль.

Параметры геолокации​

Платформа автоматически определит значения, если передать client_ip.

ПараметрТипПримерОбязательныйОписание
latfloat55.244075Да,
если передаётся lon		Широта клиента
lonfloat55.244075Да,
если передаётся lat		Долгота клиента
countrystring"RU"НетСтрана клиента (ISO-код или полное название)
regionstring"Ryazan"НетРегион клиента
citystring"Ryazan"НетГород клиента
addressstring"Pochtovaya street"НетАдрес клиента
zipstring"390000"НетПочтовый индекс клиента
time_zonestring"Europe/Moscow"НетЧасовой пояс
подсказка

Платформа автоматически определяет значения полей country, region, city, zip и time_zone на основе IP-адреса, переданного в параметрах client_ip, client_ip_v4 или client_ip_v6. Если в запросе указаны как IP-адрес, так и отдельные значения для этих полей, данные, определённые по IP, будут иметь приоритет и перезапишут переданные вручную значения.

Для обновления профиля с использованием значений из полей country, region, city, zip и time_zone необходимо установить параметр "enrich_profile": true.

UTM-параметры​

ПараметрТипПримерОбязательныйОписание
utm_contentstring"utm_content"НетUTM параметры
utm_mediumstring"utm_medium"Нет
utm_sourcestring"utm_source"Нет
utm_campaignstring"utm_campaign"Нет
utm_termstring"utm_term"Нет

Параметры сети​

ПараметрТипПримерОбязательныйОписание
net_ssidstring"10.200.0.0"НетИмя сети клиента
net_mac_addrstring"28:87:ba:c1:0d:5e"НетMAC-адрес клиента
net_gateway_ipv4string"10.200.0.1"НетIPv4 адрес шлюза клиента
net_gateway_ipv6string"::ff"НетIPv6 адрес шлюза клиента

Параметры кампании​

ПараметрТипПримерОбязательныйОписание
send_message_idstring"abcdefghijklmnqrstuvwxyz"НетИдентификатор отправленного сообщения в платформе. Позволяет связать событие пикселя с конкретной кампанией.

Параметры программы лояльности​

ПараметрТипПримерОбязательныйОписание
loyalty_idint5НетИдентификатор программы лояльности
promo_idstring"6285183c3f62fcd4ac5ed36d"НетИдентификатор привязанного промокода

Параметры маркета​

ПараметрТипПримерОбязательныйОписание
endpoint_eidstring"example_endpoint"НетВнешний идентификатор точки контакта.

Если для пикселя выбрана определенная база профилей, то эта база должна совпадать с базой канала продаж.
order_eidstring"12345"НетВнешний идентификатор заказа
product_eidstring"example_product"Да, если передается sku_eidВнешний идентификатор продукта
sku_eidstring"example_sku"НетВнешний идентификатор SKU. При использовании этого параметра в запросе также необходимо передавать product_eid.
region_eidstring"region_eYFe2AE6s"НетВнешний идентификатор региона
count_itemsint1НетКоличество товара в позиции заказа
categoriesarray
[
   "category_1",
   "category_2"
]
НетКатегории продукта или SKU
к сведению

Максимальная длина любого строкового поля — 128 символов.

Примеры запроса​

Пример запроса для регистрации одной цели и её значения​

{
    "token": "91f1dfa81c264a938b475677c60ce967",
    "db_id": 1,
    "goal": "card",
    "pixel_id": 1,
    "referer": "api.example.com",
    "value": -25.5,
    "matching":"profile_id",
    "profile_id": "abcdefghijklmnqrstuvwxyz"
}

Пример запроса для регистрации нескольких целей и их значений​

{
    "token": "abcdefghijklmnqrstuvwxyz",
    "client_ip": "10.20.30.40",
    "db_id": 24,
    "goals": [
        {
            "goal": "view product",
            "value": 10.99
        },
        {
            "goal": "add to cart",
            "value": -12.34
        }
    ],
    "pixel_id": 7,
    "matching": "profile_id",
    "profile_id": "abcdefghijklmnqrstuvwxyz",
    "referer": "api.req.from.my.site"
}

Пример запроса для передачи дополнительной информации о событии​

{
    "token": "abcdefghijklmnqrstuvwxyz",
    "db_id": 24,
    "goals": [
        {
            "goal": "cart",
            "value": 10.99
        },
        {
            "goal": "two",
            "value": -12.34
        }
    ],
    "client_ip": "192.168.0.0",
    "pixel_id": 7,
    "referer": "api.req.from.my.site",
    "accept_language": "fr-CH, fr;q=0.9, en;q=0.8, de;q=0.7, *;q=0.5",
    "user_agent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/51.0.2704.103 Safari/537.36",
    "matching": "profile_id",
    "profile_id": "abcdefghijklmnqrstuvwxyz",
    "pixel_data": {
        "hello": "hi",
        "arr": [
            1,
            2,
            3
        ],
        "int_val": 56893,
        "bool_val": true,
        "date_val": "2023-08-12"
    },
    "skip_triggers": false,
    "enrich_profile": true,
    "is_test": true,
    "vendor": "altcraft",
    "external_type": "event_pixel_test",
    "external_event_id": "qwerty123",
    "altcraft_client_id": "9f11d32d-2935-43d0-b8df-f4c3568095b2",
    "browser": "Chrome",
    "os": "Ubuntu",
    "device": "Desktop",
    "utm_content": "utm_content",
    "utm_medium": "utm_medium",
    "utm_source": "utm_source",
    "utm_campaign": "utm_campaign",
    "utm_term": "utm_term",
    "client_ip_v4": "198.16.74.224",
    "client_ip_v6": "fe80::5215:5556:d75f:806b",
    "net_ssid": "10.200.0.0",
    "net_mac_addr": "28:87:ba:c1:0d:5e",
    "net_gateway_ipv4": "10.200.0.1",
    "net_gateway_ipv6": "::ff",
    "loyalty_id": 5,
    "promo_id": "abcdefghijklmnqrstuvwxyz",
    "endpoint_eid": "online_store",
    "order_eid": "12345",
    "product_eid": "hd_450_bt_earphones",
    "sku_eid": "hd_450bt_earphones_black",
    "region_eid": "region_eYFe2AE6s",
    "count_items": 1,
    "categories": [
        "category_KBZ1qurFP"
    ],
    "lat": 55.244075,
    "lon": 19.379932,
    "country": "RU",
    "region": "Ryazan",
    "city": "Ryazan",
    "address": "Pochtovaya street",
    "zip": "390000",
    "time_zone": "Europe/Moscow",
    "send_message_id": "w4Wq877djSG1_2_a1_6t_2p_U_2_g.2UCSmxz7zFnuCfCMK_5KmKH9"
}

Пример ответа​

{
    "error": 0,
    "error_text": "Successful operation"
}

Возвращаемые параметры​

ПараметрТипОписание
errorintКод ошибки
error_textstringТекст ошибки
Последнее обновление