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

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

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

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

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

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

Важливо!

Зовнішній ID повинен створюватися у вашій системі у той момент, коли ви вперше отримуєте будь-який умовно сталий ідентифікатор

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

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

  1. Користувач встановлює додаток на мобільний пристрій з ОС Android.
  2. Додаток передає у eSputnik мобільний токен користувача (метод API /v1/contact).
  3. У eSputnik створюється контакт з цим токеном як ідентифікатором.
  4. Користувач реєструється у додатку.
  5. У вашу систему потрапляють сталі ідентифікатори, такі як email, номер телефону чи ім’я.
  6. Ваша система присвоює цьому користувачу унікальний ID і передає його в eSputnik разом з іншими ідентифікаторами, у тому числі з мобільним токеном (метод API /v1/contact).
  7. eSputnik знаходить контакт з цим мобільним токеном і оновлює його картку, записуючи в неї нові ідентифікатори.

Use case 2. Створення і оновлення контакту для веб-сайту

  1. Незалогінений користувач відвідує ваш сайт.
  2. У eSputnik передаються і записуються відповідні cookies. Контакт не створюється (використовується скрипт веб-трекінгу).
  3. Користувач реєструється на сайті або підписується на розсилку .
  4. У вашу систему потрапляють умовно сталі ідентифікатори, такі як email, номер телефону або ім’я.
  5. Ваша система присвоює цьому користувачу унікальний ID і передає його в eSputnik разом з іншими ідентифікаторами (/v1/contact або /v1/contact/subscribe).
  6. eSputnik зберігає контакт з усіма переданими ідентифікаторами і додає його попередню історію взаємодії з вашим сайтом (файли cookies).

Після того, як контакт був створений у eSputnik з полем externalCustomerId, ми рекомендуємо проводити кожне його оновлення з унікальністю за externalCustomerId — наприклад, при логіні (/v1/contact), створенні замовлення (v1/orders або v1/event) тощо. Таким чином ви зможете постійно підтримувати актуальність всіх контактних даних, оскільки externalCustomerId унікальний і незмінний, а інші ідентифікатори, навіть умовно сталі, можуть змінюватися.

Примітка

Якщо ваша система не присвоює контактам ID, ви можете викоритсовувати системний ID eSputnik (Contact_id) і потім зберігати його на своїй стороні як ідентифікатор клієнта. Але використання externalCustomerId є кращим варіантом, адже така ідентифікація на 100% убезпечує від створення дублікатів.

Зовнішній ID клієнта для мапінгу подій з контактами

Система автоматично прив'язує події до контактів. Щоб подія збереглася з прив'язкою до контакта, необхідно знати, який параметр у події містить ідентифікатор, за яким можна знайти контакт. А також яке саме поле контакта використовується в якості ідентифікатора. Якщо ідентифікатор контакта не заданий у події, система за замовчуванням шукає параметр події ContactId.

Якщо ви передаєте у події ідентифікатор у полі “Зовнішній ID клієнта”, додатково налаштовувати мапінг не потрібно. Але якщо цей ідентифікатор передається у полі з відмінною назвою, її потрібно співвіднести з системним полем “Зовнішній ID клієнта”.

Щоб зробити це:

1. Перейдіть до налаштувань вашого акаунту -> Події -> активуйте світчер "Задати правило відповідності".

Налаштування

2. Задайте вашу назву параметра в події і оберіть поле контакта "Зовнішній ID клієнта".

Задайте правило відповідності

3. Клікніть "Зберегти".

Зовнішній ID клієнта в методах API для одиночних контактів

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

Створити контакт (contact POST)

Приймаючи запит, система шукає відповідний контакт за зовнішнім ID:

  • якщо контакт з цим зовнішнім ID знайдено, він оновлюється даними із запиту;
  • якщо контакт з цим зовнішнім ID був вилучений, його буде відновлено;
  • якщо контакт не знайдено, він створюється у системі.
  • якщо зовнішній ID у запиті відсутній, логіка створення залишається незмінною.

Оновити контакт (contact PUT)

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

  • якщо цей зовнішній ID вже належить контакту з іншим contactId, відбудеться помилка;
  • якщо зовнішній ID не належить іншому контакту, контакт оновиться і йому буде наданий цей ID.
  • якщо зовнішній ID не задано, логіка лишається без змін

Отримати контакт (contact GET)

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

Підписати контакт (contact/subscribe POST)

У логіці пошуку контакту зовнішній ID має найвищій пріоритет; якщо контакт за цим ідентифікатором не знайдено, система шукає його за email-адресою, якщо email не знайдено — за номером телефону.

Зовнішній ID клієнта в методах API для роботи з масовими контактами

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

Пошук (contacts GET)

Ви можете задати унікальність пошуку за полем “Зовнішній ID клієнта”, тоді:

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

Імпорт (contacts POST)

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

Експорт зовнішнього ID клієнта у BigQuery та PostgreSQL

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

Залишилися питання?
Спеціалісти обов'язково нададуть відповідь та допоможуть вирішити вашу проблему!
Зворотний дзвінок
Залишіть заявку – і наш спеціаліст зв'яжеться з вами в робочий час.
Відправити заявку
Консультація в чаті
Готові до ваших запитань!
Написати в чат
Електронна пошта
Напишіть в службу підтримки eSputnik.
Надіслати email