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

Внешний ID – это уникальный идентификатор контакта, который генерируется в вашей контактной базе. Чтобы избежать дублирования контактов, собирать все доступные данные в единый профиль контакта и получать полную информацию о его взаимодействии с вашей компанией, мы рекомендуем использовать его как основной идентификатор в поле API-запроса externalCustomerId (в мобильном SDK — 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 с полем External ID, мы рекомендуем проводить каждое его обновление с уникальностью по этому полю — например, при логине (Add/update a contact), создании заказа (Add orders или Generate event) и т. п. Таким образом вы сможете постоянно поддерживать актуальность всех контактных данных, поскольку внешний ID уникален и неизменен, а другие идентификаторы, даже постоянные, могут изменяться.

Внешний 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.

Поиск контактов без внешнего ID в учетной записи eSputnik

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

1. Перейдите в "Контакты" → "Группы" и создайте условную группу.
2. Добавьте условие: "Поля контакта" → External ID → "не указано" и нажмите "Готово".

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