# Про реферальні мітки з реклами Facebook

Реферальні мітки з реклами Facebook дозволяють відстежувати, звідки саме приходять користувачі на ваш сайт або бот. Це дозволяє аналізувати ефективність рекламних кампаній та оптимізувати маркетингову стратегію.

## Контекст і проблема

У багатьох випадках потрібно відстежувати джерела трафіку:
- Визначення найефективніших рекламних кампаній
- Оцінка ROI рекламних витрат
- Оптимізація маркетингової стратегії
- Персоналізація повідомлень на основі джерела

Реферальні мітки вирішують цю задачу, дозволяючи додавати унікальні параметри до URL рекламних кампаній та зберігати їх для подальшого аналізу.

## Основні концепції

### Структура реферальних міток

Реферальні мітки додаються до URL як query параметри:
- `ref_source=ADS` — вказує, що це реклама
- `ref=campaign_name` — назва кампанії
- `ref_ad_id=123456789` — ID конкретної рекламної кампанії

### Збереження міток

Мітки з URL автоматично зберігаються в змінних системи:
- `ref_source` — джерело (ADS)
- `ref` — назва кампанії
- `ref_ad_id` — ID рекламної кампанії

Ці змінні доступні в сценаріях для використання в логіці та персоналізації.

## Варіанти підходів

### Збереження в змінних vs Custom Data

**Збереження в змінних:**
- ✅ Плюси: Простота доступу, автоматичне збереження
- ❌ Мінуси: Обмежена персистентність

**Збереження в Custom Data:**
- ✅ Плюси: Постійне зберігання, можливість аналітики
- ❌ Мінуси: Потрібна додаткова обробка

**Чому використовуємо обидва підходи:**
Змінні зручні для швидкого доступу в сценаріях, а Custom Data — для довгострокового зберігання та аналітики.

## Прийняті рішення

### Використання Action Jail для збереження

Для збереження міток в Custom Data використовується Action Jail, який:
- Отримує мітки з URL параметрів
- Створює або оновлює Custom Data
- Додає додаткові дані (ім'я, телефон, месенджер)

### Автоматичне збереження в змінних

Мітки автоматично зберігаються в змінних системи при вході користувача в бот, що дозволяє використовувати їх одразу в сценаріях.

## Наслідки для користувачів і імплементації

### Для інтеграторів

При використанні реферальних міток важливо:

1. **Додати мітки до URL** — в рекламних кампаніях Facebook
2. **Налаштувати Action Jail** — для збереження міток в Custom Data (опційно)
3. **Використати мітки в сценаріях** — для персоналізації та аналітики
4. **Створити аналітику** — для відстеження ефективності кампаній

### Типові помилки

**Помилка:** Мітки не зберігаються  
**Проблема:** Не додано Action Jail для обробки URL параметрів  
**Рішення:** Додати Action Jail, який обробляє URL параметри при вході користувача

**Помилка:** Мітки втрачаються між сесіями  
**Проблема:** Мітки зберігаються тільки в змінних, а не в Custom Data  
**Рішення:** Використати Action Jail для збереження в Custom Data

**Помилка:** Неможливо відстежити ефективність кампаній  
**Проблема:** Мітки не зберігаються для аналітики  
**Рішення:** Створити таблицю в Custom Data для зберігання статистики

## Приклади використання

### URL з реферальними мітками

```
https://www.example.com?ref=campaign_a&ref_source=ADS&ref_ad_id=123456789
```

### Використання в сценаріях

Мітки доступні як змінні:
- `{{ref_source}}` — джерело (ADS)
- `{{ref}}` — назва кампанії
- `{{ref_ad_id}}` — ID рекламної кампанії

### Збереження в Custom Data

```javascript
const action_save_referral_data = function() {
    const j = this.getCurrentStateJSON();
    const user_request = j.user_request || {};
    
    const ref_source = user_request.ref_source || null;
    const ref = user_request.ref || null;
    const ref_ad_id = user_request.ref_ad_id || null;
    
    // Створюємо або оновлюємо custom_data
    if (!j.custom_data) {
        j.custom_data = {};
    }
    
    if (!j.custom_data.referral_stats) {
        j.custom_data.referral_stats = [];
    }
    
    j.custom_data.referral_stats.push({
        ref_source: ref_source,
        ref: ref,
        ref_ad_id: ref_ad_id,
        timestamp: new Date().toISOString(),
        client_name: j.client?.first_name || '',
        client_phone: j.client?.phone || '',
        messenger: this.channel
    });
    
    this.setCurrentStateConstant('custom_data', j.custom_data);
    
    return 'success';
};
```

## Пов'язані документи

- **Explanation:** [Запуск сценарію з реклами на Facebook](/uk/scenariodialog/explanation/facebook-ads-scenario-launch.md) — налаштування запуску сценарію з реклами
- **How-to:** [Створити action в Action Jail](/uk/actionjail/how-to/admin-manage-actions.md) — як створити власні action