> ## Documentation Index > Fetch the complete documentation index at: https://docs.ycloud.com/llms.txt > Use this file to discover all available pages before exploring further. # Отслеживание пользовательских событий > Определяйте бизнес-события и отправляйте данные об активности клиентов в YCloud. ## Что это такое Пользовательские события (Custom Events) представляют активность из вашего приложения, веб-сайта, магазина или бэкенд-системы. Определите схему события один раз, а затем отправляйте факты его возникновения, которые можно использовать в клиентских сценариях YCloud. ## Перед началом работы * Выберите постоянное имя события, которое не будет меняться при изменении отображаемого текста. * Определите контакт, связанный с каждым событием. * Определите свойства события и их типы данных. * Решите, какая системная временная метка обозначает время совершения действия. ## Как это работает 1. Создайте определение события. 2. Добавляйте или обновляйте определения свойств по мере развития схемы. 3. Отправляйте факты возникновения событий, используя точное имя определения. 4. Связывайте каждое событие с ID контакта, номером телефона или именем пользователя Meta. 5. Отслеживайте отклоненные события и несоответствия схеме. Определения событий являются контрактами. Изменение метки или описания безопаснее, чем изменение смысла существующего имени или свойства. ## Запрос ### Создание определения события `POST /event/definitions` ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} curl --request POST https://api.ycloud.com/v2/event/definitions \ --header "X-API-Key: $YCLOUD_API_KEY" \ --header "Content-Type: application/json" \ --data '{ "name": "order_completed", "label": "Order completed", "description": "A customer completed an order.", "objectType": "CONTACT", "properties": [ { "name": "order_value", "label": "Order value", "type": "NUMBER" } ] }' ``` ### Выбор идентификатора контакта Для события, заданного с `objectType: CONTACT`, укажите один из следующих идентификаторов: | Поле | Как YCloud идентифицирует контакт | | - | - | | `objectId` | Использует числовой ID существующего контакта в вашем аккаунте. Если контакт не существует, запрос завершается ошибкой. | | `contactPhoneNumber` | Выполняет поиск номера телефона в формате E.164 в вашем аккаунте и создает контакт, если совпадений не найдено. | | `contactUsername` | Находит соответствие по сохраненному имени пользователя Meta существующего контакта в вашем аккаунте. Если совпадений нет, запрос завершается ошибкой без создания контакта. | Для каждого события используется только один идентификатор. Если указано несколько идентификаторов, числовой `objectId` имеет приоритет, затем следует непустой `contactPhoneNumber`, а затем `contactUsername`. Если числовой ID контакта не найден, YCloud отклоняет запрос без проверки номера телефона или имени пользователя. Используйте имя пользователя Meta, сохраненное в контакте, без начального символа `@`. `contactUsername` — это поле верхнего уровня запроса, отдельное от `properties`. Добавлять его в определения свойств события не требуется. ### Отправка события по номеру телефона `POST /event/events` ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} curl --request POST https://api.ycloud.com/v2/event/events \ --header "X-API-Key: $YCLOUD_API_KEY" \ --header "Content-Type: application/json" \ --data '{ "eventName": "order_completed", "occurTime": "2026-07-16T12:00:00.000Z", "contactPhoneNumber": "+16315551111", "properties": { "order_value": 99.9 } }' ``` ### Отправка события по имени пользователя Если вам известно имя пользователя контакта в Meta, вы можете отправить то же самое событие без номера телефона или ID контакта. В этом примере `customer_demo` уже должен быть сохранен у контакта в вашем аккаунте. ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} curl --request POST https://api.ycloud.com/v2/event/events \ --header "X-API-Key: $YCLOUD_API_KEY" \ --header "Content-Type: application/json" \ --data '{ "eventName": "order_completed", "occurTime": "2026-07-16T12:00:00.000Z", "contactUsername": "customer_demo", "properties": { "order_value": 99.9 } }' ``` ## Ответ При создании определения возвращается сохраненное определение. ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} { "name": "order_completed", "label": "Order completed", "objectType": "CONTACT", "properties": [ { "name": "order_value", "label": "Order value", "type": "NUMBER" } ] } ``` Успешно принятое событие возвращает HTTP `200` с пустым объектом JSON. ```http theme={"theme":{"light":"github-light","dark":"github-dark"}} HTTP/1.1 200 OK Content-Type: application/json {} ``` ## Развитие схемы * По возможности добавляйте новые необязательные свойства. * Не используйте повторно имя существующего свойства для другого значения. * Проверяйте типы данных перед отправкой событий. * Сохраняйте неизменными имена событий и свойства во всех средах. * Создавайте новую версию имени события, если критическое семантическое изменение неизбежно. ## Ограничения и устранение неполадок * Определение события должно существовать до отправки факта его возникновения. * Имена и значения свойств должны соответствовать определению. * Используйте RFC 3339 для `occurTime`. * Убедитесь, что идентификатор контакта сопоставляется с нужным клиентом в вашем аккаунте. * Для `contactUsername` проверьте, что контакт уже существует, и что имя пользователя совпадает с сохраненным значением без начального `@`. * Опускайте идентификаторы, которые YCloud не должен использовать. Переданный номер телефона имеет приоритет перед именем пользователя. * Ответ `200` подтверждает принятие, но не гарантирует завершение работы последующих процессов автоматизации. Просмотреть схемы определений и свойств. Просмотреть контракт запроса на отправку события. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.