🌐EN🛠️ Developer Guide
User Guide

Інструкція з інтеграції CMS

Suggest Edits

Інтеграція вашої CMS-платформи з eSputnik дозволяє власникам інтернет-магазинів швидко впровадити професійні маркетингові інструменти без залучення внутрішніх розробників. Ця інтеграція охоплює такі етапи:

  • Синхронізація контактних та замовлень з CMS до eSputnik
  • Відстеження поведінки користувачів за подіями
  • Налаштування Web Push підписок
  • (Опційно) Налаштування товарного фіду для генерації персональних рекомендацій на сайті та в повідомленнях

Після завершення інтеграції користувачі CMS можуть під’єднати свій магазин до eSputnik, активувати додаткові канали комунікації та запускати омніканальні кампанії без необхідності додаткової розробки.

📘

Зверніть увагу

Щоб спростити налаштування, ви можете скористатися реальним прикладом повнофункціональної інтеграції в нашому репозиторії Yespo-Shopify на GitHub. Tакож вам можуть бути корисними наступні інструкції:

1. Синхронізація контактних даних

1.1 Синхронізація нових контактів

Мета: Після активації інтеграції всі нові контакти, створені в CMS, автоматично передаються до eSputnik у режимі реального часу.

Використання ідентифікаторів, таких як externalCustomerId, phone та email, дозволяє уникнути дублювання навіть у випадках, коли контакт уже існує в eSputnik.

Реалізація: Використовуйте API Add/update a contact.

1.2 Імпорт наявних контактів

Мета: Контакти, які існували в CMS до інтеграції, можуть бути імпортовані до eSputnik під час початкового налаштування. Система розпізнає унікальні контакти за externalCustomerId, phone та email, уникаючи дублювання.

Реалізація: Використовуйте API Add/update contacts.

  • Контакти, які не вдалося імпортувати, будуть позначені помилкою з її описом
  • Для моніторингу статусу імпорту використовуйте API Get contact import status

1.3 Оновлення контактів

Мета: Якщо в CMS змінюється email, номер телефону або інші дані контакту, eSputnik оновлює відповідний профіль або створює новий, якщо такий відсутній.

Реалізація: Використовуйте API Add/update a contact.

1.4 Видалення контактів

Мета: Контакти, видалені в CMS, або повністю видаляються в eSputnik (1-й тип видалення), або деактивуються (2-й тип видалення).

Реалізація: Підтримайте обидва типи видалення:

  1. GDPR-видалення: використовуйте API Delete contact by externalCustomerId з параметром erase=true.
    • Це повністю видаляє дані контакту з бази eSputnik і анонімізує пов’язані замовлення
  2. Ручне видалення: використовується той самий метод з erase=false.
    • Контакти позначаються як видалені, але зберігаються в окремій вкладці та залишаються прив'язаними до замовлень. Їх можна відновити в eSputnik

Додаткові джерела контактних даних

Підписка через віджети

Мета: Контакти, що підписалися через віджет eSputnik, додаються напряму в eSputnik, минаючи CMS.

Реалізація: Забезпечте підтримку таких варіантів:

  • Використовуються форми eSputnik та CMS
  • Тільки форма eSputnik
  • Тільки форма CMS

📘

Зверніть увагу

Щоб використовувати віджети eSputnik, зареєструйте домен, а також отримайте та встановіть скрипт вебтрекінгу

Підписка на Web Push

Мета: Коли користувач підписується на Web Push на CMS-сайті, eSputnik створює контакт із push-токеном для надсилання сповіщень.

Реалізація: Налаштуйте Web Push у CMS та переконайтесь, що токен передається коректно.

Контакти із замовлень

Через Generate event API

Мета: При отриманні замовлення eSputnik ідентифікує контакт за externalCustomerId або locator (phone/email). Якщо контакт відсутній, створюється новий.

Реалізація: використовуйте API Generate event v3.

📘

Ознайомтеся з інструкцією з використання Generate event для передачі замовлень

Через Add orders API

Мета: Аналогічно до попереднього прикладу.

Реалізація: використовуйте API Add orders.

Контакти з вебтрекінгової події PurchasedItems

Мета: Коли клієнт робить замовлення в магазині CMS, контакт створюється або оновлюється в eSputnik через подію PurchasedItems. Незалежно від того, чи контакт новий, чи вже існує, він буде пов’язаний із подією вебтрекінгу через подію CustomerData.

Реалізація: Надсилайте події вебтрекінгу з магазину CMS через JavaScript.

Створення акаунта та логін

Мета: eSputnik отримує ідентифікаційні дані при реєстрації або логіні користувача.

Реалізація: Надсилайте подію CustomerData, коли:

  • Користувач створює акаунт
  • Користувач входить у систему

📘

Зверніть увагу

  • Подія CustomerData сама по собі не створює та не оновлює контакт. Використовуйте її в поєднанні з логікою з розділів про створення та оновлення контактів
  • Якщо контакт невідомий, система використовує cookies для трекінгу та деанонімізує його поведінку після авторизації

2. Синхронізація замовлень

2.1 Нові замовлення

Мета: Після активації інтеграції всі нові замовлення з CMS автоматично передаються до eSputnik.

Реалізація:

  • Використовуйте API Add orders та/або Generate event v3
  • Зіставляйте статуси замовлень між CMS та eSputnik і переконайтеся, що актуальні статуси завжди синхронізовані з eSputnik

2.2 Імпорт наявних замовлень

Мета: Дані про замовлення, створені до інтеграції, можна імпортувати під час початкового налаштування.

Реалізація: Використовуйте API Add orders або Generate past events v3.

2.3 Оновлення замовлень

Мета: eSputnik відображає актуальні дані замовлень та їх статуси. Якщо в CMS змінюються дані або статус замовлення, eSputnik оновлює або створює відповідне замовлення.

Реалізація:

  • Використовуйте API Add orders та/або Generate event v3
  • Підтримуйте однакове відображення статусів (синхронізоване з eSputnik)

Додаткові джерела даних про замовлення

Замовлення з вебтрекінгу

Мета: Замовлення створюється в eSputnik, коли користувач завершує покупку в магазині CMS.

Реалізація: використовуйте вебтрекінгову подію PurchasedItems.

3. Відстеження поведінки відвідувачів сайту

Мета

Вебтрекінг дозволяє:

  • Формувати аудиторії за поведінкою
  • Відправляти персоналізовані кампанії
  • Запускати тригерні розсилки: покинутий кошик, перегляд тощо
  • Генерувати рекомендації товарів за допомогою ШІ

Реалізація

  1. Зареєструйте домен.
  2. Отримайте та встановіть скрипт вебтрекінгу eSputnik (якщо вже встановлений для віджетів — пропустіть цей крок).
  3. Налаштуйте товарний фід (через інтерфейс або API).
  4. Надсилайте події з фронтенду, бекенду або комбіновано — забезпечте гнучкість незалежно від параметрів конфігурації інтерфейсу магазину. Наприклад, CustomerData, StatusCart, PurchasedItems — із бекенду; інші — з фронтенду.

📘

Зверніть увагу

При надсиланні StatusCart з бекенду рекомендації для кошика не працюватимуть

Обов'язкові події

У статті “Передача даних про поведінку відвідувачів сайту через REST API” наведено повний список подій вебтрекінгу; нижче перелічені лише необхідні:

  • PageView: автоматично надсилається після встановлення скрипту)
  • ProductPage
  • StatusCart: використовуйте ID варіації як ключ продукту, якщо варіації обробляються на вебсайті
  • PurchasedItems: використовуйте ID варіації як ключ продукту, якщо варіації обробляються на вебсайті; покупка ініціює створення контакту/замовлення. Також, використовуючи варіацію, переконайтеся, що ви передаєте ID варіації через замовлення та/або події API.
  • CustomerData
  • CategoryPage
  • 404
  • MainPage

4. Налаштування підписки Web Push

Мета

  • Власники магазинів можуть швидко налаштувати Web Push з мінімальними зусиллями
  • Підписники додаються в eSputnik з push-токеном
  • Ті, хто відмовився від підписки, не додаються, але їх можна буде знову запросити пізніше
  • Ручні оновлення (наприклад, іконки, типи підписки) підтримуються через налаштування в обліковому записі eSputnik
  • Власники магазинів можуть налаштовувати кастомні push-кампанії через eSputnik
    Дані CMS використовуються для аналітики
  • Конфлікти з іншими push-сервісами обробляються коректно

Реалізація

  1. Додайте домен для нотифікацій Web Push.
  2. Отримайте скрипт eSputnik та вміст service worker.
  3. Згенеруйте файл sw.js зі вмістом service worker і завантажте його разом зі скриптом на сайт.

📘

Зверніть увагу

За замовчуванням, налаштування через API створює підписку в один клік. Тип підписки можна змінити в обліковому записі eSputnik

5. Налаштування товарного фіду

Мета

Товарний фід надає eSputnik доступ до актуального каталогу товарів з CMS для персоналізованих рекомендацій, динамічного контенту та запуску релевантних тригерів.

📘

Зверніть увагу

Наявність фіду обов’язкова для роботи вебтрекінгу

Реалізація

  • Надішліть посилання на фід (із мовними параметрами) до eSputnik з CMS
  • Виявляйте відсутні або некоректні фіди і сповіщайте про це користувача
  • Додайте інтерфейс для редагування посилань або виправлення помилок
  • Дозвольте користувачам керувати налаштуваннями фіду: частота оновлення, мови тощо

Потрібна допомога?

Якщо будь-який із кроків видається незрозумілим або технічно складним, зверніться до нашої служби підтримки за адресою [email protected] і скористайтеся чатом у правому нижньому куті цієї сторінки для безпосередньої підтримки. Ми з радістю допоможемо підібрати найкращий підхід до інтеграції.

Updated about 19 hours ago