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

Зовнішній ID — це унікальний ідентифікатор контакту, що генерується у вашій базі контактів. Щоб уникнути дублювання контактів, збирати всі доступні дані у єдиний профіль контакту і отримувати якомога повнішу інформацію про його взаємодію з вашою компанією, ми рекомендуємо використовувати його як основний ідентифікатор у полі API-запиту externalCustomerId (у мобільному SDK — 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 з полем 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 → "не вказано" та натисніть "Готово".

Система знайде всі контакти без зовнішніх ідентифікаторів та помістить їх у цю групу. Оскільки сегмент динамічний, все нові контакти без зовнішніх ID також автоматично поміщатимуться до нього.