# UTM campaign tracking

The JavaScript SDK automatically captures UTM parameters from page URLs and attaches them to events as campaign metadata under [`context.campaign`](https://www.krenalis.com/docs/collect-events/spec/schema.md#campaign). No additional SDK configuration is required.

## Campaign parameter mapping

Standard UTM parameters are mapped to [`context.campaign`](https://www.krenalis.com/docs/collect-events/spec/schema.md#campaign) properties as follows.

| URL query parameter | Property                   |
|---------------------|----------------------------|
| `utm_campaign`      | `context.campaign.name`    |
| `utm_source`        | `context.campaign.source`  |
| `utm_medium`        | `context.campaign.medium`  |
| `utm_term`          | `context.campaign.term`    |
| `utm_content`       | `context.campaign.content` |

Note that `utm_campaign` is mapped to `context.campaign.name`, not `context.campaign.campaign`.

Any additional query string parameter prefixed with `utm_` is collected automatically and stored using the parameter name without the `utm_` prefix.

For example:

| URL query parameter | Property                    |
|---------------------|-----------------------------|
| `utm_platform`      | `context.campaign.platform` |
| `utm_creative`      | `context.campaign.creative` |
| `utm_channel`       | `context.campaign.channel`  |
| `utm_ad_group`      | `context.campaign.ad_group` |

## Campaign data in event payloads

When an event is generated, the SDK inspects the current page URL and extracts all query string parameters prefixed with `utm_`.

Example URL:

```text
https://example.com/?utm_source=google&utm_medium=cpc&utm_campaign=summer_sale
```

Calling:

```javascript
analytics.track("Purchase Completed");
```

Produces an event similar to:

```json
{
  "event": "Purchase Completed",
  "context": {
    "campaign": {
      "source": "google",
      "medium": "cpc",
      "name": "summer_sale"
    }
  }
}
```

If the current page URL does not contain UTM parameters, no campaign properties are added automatically.

## Providing campaign values manually

Campaign properties can also be provided explicitly in the event payload.

```javascript
analytics.track("Purchase Completed", {
  context: {
    campaign: {
      source: "crm",
      medium: "email",
      name: "retention_flow"
    }
  }
});
```

This allows campaign data to be attached even when UTM parameters are not present in the current page URL.

## Precedence rules

Automatically collected and manually provided campaign values are merged.

When the same property exists in both places, the manually provided value takes precedence.

Example URL:

```text
https://example.com/?utm_source=google&utm_medium=cpc
```

Event:

```javascript
analytics.track("Purchase Completed", {
  context: {
    campaign: {
      source: "crm"
    }
  }
});
```

Result:

```json
{
  "context": {
    "campaign": {
      "source": "crm",
      "medium": "cpc"
    }
  }
}
```

## Examples

### Standard UTM parameters

URL:

```text
https://example.com/?utm_source=google&utm_medium=cpc&utm_campaign=spring_sale
```

Result:

```json
{
  "context": {
    "campaign": {
      "source": "google",
      "medium": "cpc",
      "name": "spring_sale"
    }
  }
}
```

### Custom UTM parameters

URL:

```text
https://example.com/?utm_platform=facebook&utm_creative=video_a
```

Result:

```json
{
  "context": {
    "campaign": {
      "platform": "facebook",
      "creative": "video_a"
    }
  }
}
```

### Standard and custom parameters together

URL:

```text
https://example.com/?utm_source=google&utm_medium=cpc&utm_campaign=spring_sale&utm_platform=facebook&utm_creative=video_a
```

Result:

```json
{
  "context": {
    "campaign": {
      "source": "google",
      "medium": "cpc",
      "name": "spring_sale",
      "platform": "facebook",
      "creative": "video_a"
    }
  }
}
```

### Manual override

URL:

```text
https://example.com/?utm_source=google&utm_medium=cpc&utm_campaign=spring_sale
```

Event:

```javascript
analytics.track("Purchase Completed", {
  context: {
    campaign: {
      source: "crm",
      name: "retention_flow"
    }
  }
});
```

Result:

```json
{
  "context": {
    "campaign": {
      "source": "crm",
      "medium": "cpc",
      "name": "retention_flow"
    }
  }
}
```

## Technical details

### URL decoding

UTM values are URL-decoded before being stored.

Example:

```text
?utm_campaign=summer%20sale
```

Becomes:

```json
{
  "name": "summer sale"
}
```

### Duplicate parameters

If the same UTM parameter appears multiple times in the URL, the last occurrence is used.

Example:

```text
?utm_source=google&utm_source=linkedin
```

Becomes:

```json
{
  "source": "linkedin"
}
```

## Using campaign data in transformations

In transformations, access UTM campaign information through the `context.campaign` object:

* `context.campaign.name` (`string`): Campaign name.
* `context.campaign.source` (`string`): Campaign source.
* `context.campaign.medium` (`string`): Campaign medium, such as email or social.
* `context.campaign.term` (`string`): Campaign keyword or term.
* `context.campaign.content` (`string`): Campaign content or variation.

## Data warehouse

In your data warehouse, the [events view](https://www.krenalis.com/docs/views-and-tables.md#event-view-schema) exposes campaign data through the following columns:

* `context_campaign_name`
* `context_campaign_source`
* `context_campaign_medium`
* `context_campaign_term`
* `context_campaign_content`

## FAQ

### Which events receive campaign data automatically?

Campaign data is attached automatically to [`page`](https://www.krenalis.com/docs/collect-events/spec/page.md), [`screen`](https://www.krenalis.com/docs/collect-events/spec/screen.md), [`track`](https://www.krenalis.com/docs/collect-events/spec/track.md), [`identify`](https://www.krenalis.com/docs/collect-events/spec/identify.md), and [`group`](https://www.krenalis.com/docs/collect-events/spec/group.md) events when UTM parameters are present in the current page URL.

### Are only standard UTM parameters supported?

No. Any query string parameter prefixed with `utm_` is collected automatically.

### Are custom UTM parameters supported?

Yes. Any query string parameter prefixed with `utm_` is collected automatically and added to [`context.campaign`](https://www.krenalis.com/docs/collect-events/spec/schema.md#campaign) using the parameter name without the `utm_` prefix. These custom UTM parameters remain available in the event payload but are not exposed as dedicated columns in the events view.

### How are automatic and manually provided campaign values combined?

Campaign properties are merged. When the same property exists in both places, the manually provided value takes precedence.

### What happens when no UTM parameters are present?

No campaign properties are added automatically unless campaign values are provided explicitly in the event payload.

### Are UTM parameters persisted across page navigations or sessions?

No. Campaign values are extracted from the current page URL only. If a page URL does not contain UTM parameters, no campaign data is collected automatically.