Зовнішній ID для створення та оновлення контактів

Зовнішній ID — це унікальний ідентифікатор контакта, що генерується у вашій базі контактів. Щоб уникнути дублювання контактів, збирати всі доступні дані у єдиний профіль контакту і отримувати якомога повнішу інформацію про його взаємодію з вашою компанією, ми рекомендуємо використовувати його як основний ідентифікатор у полі API-запиту externalCustomerId (також може називатися user-id).

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

Контактні ідентифікатори можна розділити на умовно сталі і змінювані:

• умовно сталі — email, номер телефону та інші контактні дані, отримані від клієнта під час реєстрації.
• змінювані — web cookies, мобільні та веб-токени.

Зазвичай спершу у систему потрапляють змінювані ідентифікатори, але зовнішній ID прив’язується лише до умовно сталих ідентифікаторів.

Щоб краще зрозуміти, як контактні дані потрапляють у систему і як оптимізувати ідентифікацію контактів, розглянемо 2 базові приклади використання: для мобільних додатків і веб-сайтів.

Приклад 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.