> ## Documentation Index
> Fetch the complete documentation index at: https://revolai.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Підміна номерів

> Динамічна заміна телефонних номерів для атрибуції дзвінків — відстежуйте які кампанії, реклама та джерела трафіку генерують дзвінки

## Огляд

Phone Swap — це функція **атрибуції дзвінків**, яка динамічно замінює телефонні номери на вашому сайті залежно від джерела трафіку відвідувача. Коли відвідувач приходить з конкретної кампанії — Google Ads, Facebook, партнерського реферала або будь-якого UTM-посилання — трекер автоматично замінює ваш основний номер на виділений трекінговий номер. Коли відвідувач дзвонить на цей номер, ви точно знаєте яка кампанія привела дзвінок.

<Frame>
  <img className="block dark:hidden" src="https://mintcdn.com/revolai/fjI-3Zk750dSQkZZ/images/tracker-phone-swap-light.png?fit=max&auto=format&n=fjI-3Zk750dSQkZZ&q=85&s=359656152b148417f413a1d426c423ef" alt="Вкладка Phone Swap" width="2865" height="1554" data-path="images/tracker-phone-swap-light.png" />

  <img className="hidden dark:block" src="https://mintcdn.com/revolai/fjI-3Zk750dSQkZZ/images/tracker-phone-swap-dark.png?fit=max&auto=format&n=fjI-3Zk750dSQkZZ&q=85&s=31a9369607118a114b7a0cb0b371cabf" alt="Вкладка Phone Swap" width="2865" height="1553" data-path="images/tracker-phone-swap-dark.png" />
</Frame>

***

## Як це працює

<Steps>
  <Step title="Налаштуйте підміну в кампанії">
    Відкрийте кампанію та встановіть **Original Phone** (номер на вашому сайті) і **Replacement Phone** (трекінговий номер для цієї кампанії). Детальніше у розділі [Кампанії — Phone Swap](/uk/widget/campaigns#phone-swap).
  </Step>

  <Step title="Відвідувач заходить на сайт">
    Відвідувач натискає посилання кампанії (з UTM-параметрами) і скрипт трекера завантажується. Трекер отримує активні правила підміни з сервера.
  </Step>

  <Step title="Збіг UTM-параметрів">
    Трекер перевіряє UTM-параметри відвідувача проти кожного правила. Всі ненульові поля збігу (utm\_source, utm\_medium, utm\_campaign, rvl\_ref) повинні збігатися точно. Перше правило, що збіглося, перемагає.
  </Step>

  <Step title="Номер замінюється">
    Трекер знаходить всі екземпляри оригінального номера на сторінці — у `tel:` посиланнях, у тексті з атрибутом `data-revol-phone` — і замінює їх трекінговим номером. Заміна зберігає форматування оригінального номера.
  </Step>

  <Step title="Подія записується">
    Записується подія `phone_swap` з оригінальним та замінним номерами. Ця подія відображається у Activity Log та таблиці Campaign Performance.
  </Step>

  <Step title="Відвідувач дзвонить">
    Відвідувач дзвонить на трекінговий номер. Ви бачите дзвінок, атрибутований до конкретної кампанії — без здогадок.
  </Step>
</Steps>

***

## Вкладка Phone Swap

Вкладка Phone Swap показує всі активні правила підміни з ваших кампаній в одній таблиці:

| Колонка        | Опис                                                     |
| -------------- | -------------------------------------------------------- |
| **Campaign**   | Назва кампанії з UTM-умовами (source, medium тощо) нижче |
| **Phone Swap** | Оригінальний номер → Замінний номер                      |
| **Status**     | Активний або неактивний                                  |

Ця вкладка лише для **перегляду** — щоб додати або змінити правила підміни, відкрийте кампанію у вкладці [Кампанії](/uk/widget/campaigns) та налаштуйте секцію Phone Swap.

***

## Додавання номерів на сайт

Трекер замінює телефонні номери двома способами:

### 1. Tel-посилання (автоматично)

Будь-яке посилання `<a href="tel:...">` на сторінці виявляється автоматично. Якщо href збігається з оригінальним номером з правила, він замінюється — і атрибут `href`, і видимий текст.

```html theme={null}
<!-- До підміни -->
<a href="tel:+380441234567">+380 (44) 123-45-67</a>

<!-- Після підміни (відвідувач з кампанії Google Ads) -->
<a href="tel:+380449876543">+380 (44) 987-65-43</a>
```

Додаткові атрибути не потрібні — трекер знаходить `tel:` посилання автоматично.

### 2. Data-атрибут (явний)

Для номерів, які не в `tel:` посиланнях (простий текст, span, div), додайте атрибут `data-revol-phone`:

```html theme={null}
<!-- Номер у span -->
<span data-revol-phone>+380441234567</span>

<!-- Номер у div -->
<div class="contact-phone" data-revol-phone>+380 44 123 45 67</div>
```

Елементи з `data-revol-phone` приховуються (`visibility: hidden`) до завершення підміни, запобігаючи миготінню оригінального номера.

<Tip>
  Використовуйте `data-revol-phone` для всіх номерів, які хочете замінювати — навіть якщо вони всередині `tel:` посилань. Це дає трекеру явний контроль і запобігає будь-якому миготінню.
</Tip>

***

## Збереження формату

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

| Оригінал              | Заміна (сира)   | Результат             |
| --------------------- | --------------- | --------------------- |
| `+380 (44) 123-45-67` | `+380949876543` | `+380 (94) 987-65-43` |
| `044 123 45 67`       | `0949876543`    | `094 987 65 43`       |
| `+380441234567`       | `+380949876543` | `+380949876543`       |

Якщо кількість цифр відрізняється, замінний вставляється як є, без форматування.

***

## Підтримка SPA

Модуль підміни використовує **MutationObserver** для спостереження за динамічно доданими елементами. Якщо ваш сайт побудований на React, Vue, Angular або будь-якому фреймворку, що рендерить контент після завантаження сторінки — трекер виявляє нові елементи з номерами при їх появі в DOM і замінює їх автоматично.

Observer спостерігає за всім body документа на предмет:

* Нових посилань `<a href="tel:...">`
* Нових елементів з атрибутом `data-revol-phone`

Observer відключається при вивантаженні сторінки для запобігання витоків пам'яті.

***

## Правила збігу

Правила підміни формуються з кампаній. Кожна кампанія з встановленими **Original Phone** та **Replacement Phone** створює правило.

### Як працює збіг

Трекер перевіряє UTM-параметри відвідувача проти полів збігу правила. **Всі ненульові поля повинні збігатися точно** (логіка AND):

```
Правило: { utm_source: "google", utm_medium: "cpc" }

✓ Відвідувач з utm_source=google, utm_medium=cpc        → ЗБІГ
✗ Відвідувач з utm_source=google, utm_medium=organic     → НЕМАЄ ЗБІГУ
✗ Відвідувач з utm_source=facebook, utm_medium=cpc       → НЕМАЄ ЗБІГУ
```

Якщо у кампанії встановлено `utm_source`, але `utm_medium` порожній — достатньо збігу лише source. Порожні поля ігноруються при збігу.

### Пріоритет

Якщо кілька кампаній відповідають UTM-параметрам відвідувача, використовується **перше правило, що збіглося**. Правила повертаються у порядку створення.

***

## Події підміни

Кожна підміна генерує подію `phone_swap`, що записується один раз за сесію відвідувача. Подія містить:

```json theme={null}
{
  "from": "+380441234567",
  "to": "+380949876543"
}
```

Події підміни відображаються у:

* **Activity Log** — як тип події `phone_swap` з даними from/to
* Таблиці **Campaign Performance** — у колонці **Phone Swaps**
* **Деталях сесії** — у хронології подій сесії відвідувача

***

## Сценарії використання

<AccordionGroup>
  <Accordion title="Відстеження дзвінків Google Ads">
    Створіть кампанію з `utm_source=google`, `utm_medium=cpc`. Встановіть оригінальний номер як ваш основний бізнес-номер, а замінний — як виділений трекінговий номер. Кожен дзвінок від відвідувачів Google Ads атрибутується до цієї кампанії.

    **Результат:** Ви бачите скільки саме дзвінків генерують ваші витрати на Google Ads — у тому ж дашборді, що й чат-розмови, відправлення форм та перегляди сторінок.
  </Accordion>

  <Accordion title="Багатоканальна атрибуція">
    Створіть окремі кампанії для кожного джерела трафіку — Google, Facebook, Instagram, email-розсилка — кожна зі своїм трекінговим номером. Один і той же оригінальний номер на сайті замінюється по-різному залежно від того, звідки прийшов відвідувач.

    | Кампанія     | Джерело            | Трекінговий номер  |
    | ------------ | ------------------ | ------------------ |
    | Google Brand | google / cpc       | +380 44 111 1111   |
    | Facebook Ads | facebook / paid    | +380 44 222 2222   |
    | Розсилка     | newsletter / email | +380 44 333 3333   |
    | Органіка     | — (без підміни)    | Оригінальний номер |
  </Accordion>

  <Accordion title="Офлайн-маркетинг (друк, білборди)">
    Створіть кампанію для друкованої реклами з унікальним параметром `rvl_ref`. Додайте виділений номер. Коли хтось дзвонить з номера на флаєрі — ви знаєте, що це з друку, а не з диджиталу. Поєднайте з [QR-кодом](/uk/widget/campaigns#qr-код) для цифрового трекінгу тих самих матеріалів.
  </Accordion>

  <Accordion title="Партнерський та реферальний трекінг">
    Дайте кожному партнеру власну кампанію з `rvl_ref=partner_name` та виділений трекінговий номер. Відстежуйте точну кількість дзвінків від кожного партнера — разом із сесіями, переглядами сторінок та AI-розмовами.
  </Accordion>

  <Accordion title="A/B тестування лендінгів">
    Створіть дві кампанії з однаковим джерелом, але різними значеннями `utm_content` (напр., `landing-v1` vs `landing-v2`), кожна з різним трекінговим номером. Порівнюйте обсяги дзвінків між варіантами.
  </Accordion>
</AccordionGroup>

***

## Інтеграція з SIP

Phone Swap стає значно потужнішим у поєднанні з **інтеграцією SIP (VoIP) номерів**. Коли ви використовуєте SIP-трекінгові номери як замінні, весь життєвий цикл дзвінка фіксується в Revol:

<Steps>
  <Step title="Відвідувач бачить SIP-трекінговий номер">
    Трекер замінює оригінальний номер на SIP-номер для відвідувачів з конкретної кампанії.
  </Step>

  <Step title="Відвідувач дзвонить на SIP-номер">
    Дзвінок маршрутизується через вашого VoIP-провайдера (Binotel, Twilio тощо) і з'єднується з вашою командою.
  </Step>

  <Step title="Дзвінок записується та аналізується">
    З активною VoIP-інтеграцією дзвінок записується, транскрибується і прив'язується до сесії відвідувача. Ви бачите повний шлях: яку рекламу натиснув, які сторінки переглянув, і що сказав під час дзвінка.
  </Step>

  <Step title="AI аналізує розмову">
    Якщо ваш AI-агент налаштований для каналу інтеграції, він може проаналізувати транскрипт дзвінка — визначити намір відвідувача, витягнути дані ліда, оцінити якість дзвінка і навіть запропонувати наступні кроки.
  </Step>
</Steps>

### Що ви отримуєте

З Phone Swap + SIP-інтеграцією разом ви маєте **повний пайплайн атрибуції дзвінків**:

| Дані                                                  | Джерело                                       |
| ----------------------------------------------------- | --------------------------------------------- |
| **Яка кампанія** привела відвідувача                  | UTM-параметри → Збіг кампанії                 |
| **Які сторінки** відвідувач переглянув перед дзвінком | Потік сторінок сесії                          |
| **Скільки часу** провів на сайті                      | Тривалість сесії                              |
| **Що сказав** під час дзвінка                         | Запис + транскрипт VoIP                       |
| **Якість ліда** та намір                              | AI-аналіз дзвінка                             |
| **На який трекінговий номер** подзвонив               | Дані події phone\_swap                        |
| **Вартість дзвінка** (якщо відомі витрати на рекламу) | Атрибуція кампанії + дані рекламної платформи |

<Tip>
  Це створює замкнутий цикл зворотного зв'язку: ви бачите, що клік з Google Ads привів до 3 переглядів сторінок, 45-секундного перегляду, телефонного дзвінка де відвідувач питав про ціни, і AI оцінив його як ліда з високим наміром — все в одній хронології сесії.
</Tip>

***

## Найкращі практики

<AccordionGroup>
  <Accordion title="Використовуйте виділені номери для кожної кампанії">
    Не використовуйте один трекінговий номер для кількох кампаній — це зводить нанівець атрибуцію. Кожна кампанія повинна мати унікальний замінний номер.
  </Accordion>

  <Accordion title="Додайте data-revol-phone до всіх елементів з номерами">
    Навіть якщо ви використовуєте `tel:` посилання (які виявляються автоматично), додавання `data-revol-phone` запобігає миготінню оригінального номера до завершення підміни.
  </Accordion>

  <Accordion title="Зберігайте однаковий оригінальний номер">
    Використовуйте один і той же оригінальний номер у всіх кампаніях. Трекер шукає саме цей номер на сторінці — якщо на сайті різні номери в різних секціях, створіть окремі правила підміни для кожного.
  </Accordion>

  <Accordion title="Тестуйте з UTM-параметрами">
    Після налаштування правила підміни відвідайте свій сайт з відповідними UTM-параметрами (напр., `?utm_source=google&utm_medium=cpc`) та перевірте, що номер змінюється. Перевірте Activity Log на наявність події `phone_swap`.
  </Accordion>
</AccordionGroup>

***

## Технічні деталі

| Деталь                    | Значення                                                                     |
| ------------------------- | ---------------------------------------------------------------------------- |
| **Модуль**                | `tracker/modules/phone-swap.js` — завантажується ліниво, лише коли є правила |
| **Збіг**                  | Точний збіг всіх ненульових UTM-полів (логіка AND)                           |
| **Виявлення**             | Посилання `<a href="tel:...">` + елементи `[data-revol-phone]`               |
| **Підтримка SPA**         | MutationObserver на `document.body` (childList + subtree)                    |
| **Запобігання миготінню** | CSS `visibility: hidden` на `[data-revol-phone]` до підміни                  |
| **Трекінг подій**         | Одна подія `phone_swap` за сесію (лише перша підміна)                        |
| **Оновлення конфігу**     | Кожні 5 хвилин через фонове опитування                                       |
| **Нормалізація номерів**  | Видаляє пробіли, дефіси, дужки, крапки перед порівнянням                     |