# About Facebook Ads Referral Tags

Facebook Ads referral tags allow tracking where exactly users come from to your site or bot. This allows analyzing advertising campaign effectiveness and optimizing marketing strategy.

---

## Context and Problem

In many cases, you need to track traffic sources:
- Determining most effective advertising campaigns
- Assessing ROI of advertising spend
- Optimizing marketing strategy
- Personalizing messages based on source

Referral tags solve this task by allowing adding unique parameters to advertising campaign URLs and saving them for further analysis.

---

## Key Concepts

### Referral Tag Structure

Referral tags are added to URLs as query parameters:
- `ref_source=ADS` — indicates this is advertising
- `ref=campaign_name` — campaign name
- `ref_ad_id=123456789` — ID of specific advertising campaign

### Saving Tags

Tags from URL are automatically saved in system variables:
- `ref_source` — source (ADS)
- `ref` — campaign name
- `ref_ad_id` — advertising campaign ID

These variables are available in scenarios for use in logic and personalization.

---

## Approach Options

### Saving in Variables vs Custom Data

**Saving in variables:**
- ✅ Pros: Simple access, automatic saving
- ❌ Cons: Limited persistence

**Saving in Custom Data:**
- ✅ Pros: Permanent storage, analytics possibility
- ❌ Cons: Requires additional processing

**Why we use both approaches:**
Variables are convenient for quick access in scenarios, and Custom Data — for long-term storage and analytics.

---

## Adopted Solutions

### Using Action Jail for Saving

For saving tags in Custom Data, Action Jail is used, which:
- Receives tags from URL parameters
- Creates or updates Custom Data
- Adds additional data (name, phone, messenger)

### Automatic Saving in Variables

Tags are automatically saved in system variables when user enters the bot, allowing using them immediately in scenarios.

---

## Implications for Users and Implementation

### For Integrators

When using referral tags, it's important to:

1. **Add tags to URL** — in Facebook advertising campaigns
2. **Configure Action Jail** — for saving tags in Custom Data (optional)
3. **Use tags in scenarios** — for personalization and analytics
4. **Create analytics** — for tracking campaign effectiveness

### Common Errors

**Error:** Tags are not saved  
**Problem:** Action Jail is not added for processing URL parameters  
**Solution:** Add Action Jail that processes URL parameters when user enters

**Error:** Tags are lost between sessions  
**Problem:** Tags are saved only in variables, not in Custom Data  
**Solution:** Use Action Jail to save in Custom Data

**Error:** Cannot track campaign effectiveness  
**Problem:** Tags are not saved for analytics  
**Solution:** Create a table in Custom Data for storing statistics

---

## Usage Examples

### URL with Referral Tags

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

### Usage in Scenarios

Tags are available as variables:
- `{{ref_source}}` — source (ADS)
- `{{ref}}` — campaign name
- `{{ref_ad_id}}` — advertising campaign ID

### Saving in 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;
    
    // Create or update 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';
};
```

---

## Related Documents

- **Explanation:** [Launching Scenario from Facebook Ads](/en/scenariodialog/explanation/facebook-ads-scenario-launch.md) — configuring scenario launch from advertising
- **How-to:** [Create action in Action Jail](/en/actionjail/how-to/admin-manage-actions.md) — how to create custom actions