Внешний ID для создания и обновления контактов

Внешний ID – это уникальный идентификатор контакта, который генерируется в вашей контактной базе. Чтобы избежать дублирования контактов, собирать все доступные данные в единый профиль контакта и получать полную информацию о его взаимодействии с вашей компанией, мы рекомендуем использовать его как основной идентификатор в поле API-запроса externalCustomerId (также может называться user-id).

Типы идентификаторов

Контактные идентификаторы можно разделить на условно постоянные и изменяемые:

• условно постоянные — email, номер телефона и т.д.
• изменяющиеся — web cookies, мобильные и веб-токены.

Обычно сначала в систему попадают изменяющиеся идентификаторы, но внешний ID привязывается только к условно постоянным идентификаторам.

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

Пример 1. Создание и обновление контакта из мобильного приложения

1. Пользователь устанавливает приложение мобильное устройство с ОС Android.
2. Приложение передает в eSputnik мобильный токен контакта (метод API Add/update a contact).
3. В eSputnik создается контакт с этим токеном в качестве идентификатора.
4. Пользователь регистрируется в приложении.
5. В вашу систему попадают условно постоянные идентификаторы, такие как email, номер телефона или имя.
6. Ваша система присваивает этому пользователю уникальный ID и передает его в eSputnik вместе с другими идентификаторами, в том числе с мобильным токеном (метод API Add/update a contact).
7. eSputnik находит контакт с этим мобильным токеном и обновляет его карту, записывая в нее новые идентификаторы.

Пример 2. Создание и обновление контакта для веб-сайта

1. Незалогенный пользователь посещает ваш сайт.
2. В eSputnik передаются и записываются соответствующие cookies. Контакт не создается (используется скрипт веб-трекинга).
3. Пользователь регистрируется на сайте или подписывается на рассылку.
4. В вашу систему попадают постоянные идентификаторы, такие как email, номер телефона или имя.
5. Ваша система присваивает этому пользователю уникальный ID и передает его в eSputnik вместе с другими идентификаторами (Add/update a contact или Subscribe contact).
6. eSputnik сохраняет контакт со всеми передаваемыми идентификаторами и добавляет его предыдущую историю взаимодействия с вашим сайтом (файлы cookies).

После того, как контакт был создан в eSputnik с полем externalCustomerId, мы рекомендуем проводить каждое его обновление с уникальностью по externalCustomerId — например, при логине (Add/update a contact), создании заказа (Add orders или Generate event) и т. п. Таким образом вы сможете постоянно поддерживать актуальность всех контактных данных, поскольку externalCustomerId уникален и неизменен, а другие идентификаторы, даже постоянные, могут изменяться.

Внешний ID клиента для маппинга событий с контактами

Система автоматически привязывает события к контактам. Чтобы событие сохранилось с привязкой к контакту, необходимо знать, какой параметр события содержит идентификатор, по которому можно найти контакт. А также какое поле контакта используется в качестве идентификатора. Если идентификатор контакта не задан в событии, по умолчанию система ищет параметр события ContactId.

Если вы передаете идентификатор в поле “Внешний ID клиента”, дополнительно настраивать маппинг не нужно. Но если этот идентификатор передается в поле с другим названием, его нужно соотнести с системным полем "Внешний ID клиента".

Чтобы сделать это:

1. Перейдите к настройкам вашего аккаунта -> События -> активируйте свитчер "Задайте правило соответствия для привязки события".

2. Укажите имя параметра в событии и выберите поле "Внешний ID клиента".

3. Кликните "Сохранить".

Внешний ID клиента в методах API для одиночных контактов

Ознакомьтесь с обновленной логикой работы методов API, работающих с одним контактом:

Создать контакт (Add/update a contact)

Принимая запрос, система ищет соответствующий контакт по внешнему ID:

• если контакт с этим внешним ID найден, он обновляется данными из запроса;
• если контакт не найден, он создается в системе.
• если контакт с этим внешним ID был удален, он будет восстановлен;
• если внешний ID в запросе отсутствует, логика создания остается неизменной.

Обновить контакт (Update contact)

В URL запроса задается contactId, а в теле передается внешний ID:

• если этот внешний ID уже принадлежит контакту с другим contactId, произойдет ошибка;
• если внешний ID не принадлежит другому контакту, контакт обновится и ему будет предоставлен этот ID;
• если внешний ID не задан, логика остается без изменений.

Получить контакт (Get contact)

Внешний ID добавляется к данным контакта, которые возвращаются запросом.

Подписать контакт (Subscribe contact)

В логике поиска контакта внешний ID имеет самый высокий приоритет; если контакт по этому идентификатору не найден, система ищет его по email-адресу, если email не найден — по номеру телефона.

Внешний ID клиента в методах API для работы с массовыми контактами

Обновлена логика работы массовых методов API.

Поиск (Search contacts)

Вы можете задать уникальность поиска контакта по полю "externalCustomerId". В этом случае задать другие параметры поиска нельзя.

Импорт (Add/update contacts)

При импорте контактов можно использовать любое поле, чтобы определить их уникальность. Например, импортировать контакты с уникальностью по email-адресу, при этом добавлять или обновлять их внешние ID.

Использование в ресурсе Send prepared message

Поддержана возможность использования внешнего ID в ресурсе Send prepared message. Это позволяет отправлять одиночные сообщения через сценарий с учетом этого поля.

Кроме locator или contactId, входные параметры также можно валидировать по полю externalCustomerId.

Приоритет проверки полей: contactId > externalCustomerId > locator.

Экспорт внешнего ID клиента в BigQuery и PostgreSQL

Экспортируйте внешние ID в BigQuery и PostgreSQL — они появятся в колонке в таблице contacts. По умолчанию эта опция доступна для всех новых экспортов. Если вы хотите создать ее для уже существующих экспортов, напишите в службу поддержки на support@esputnik.com.