# Transformation

A Transformation is an engine that sits in front of every channel/destination. It sees every event you send to EdgeTag and can reshape it, drop it, or fan out additional events before the event reaches any individual channel.

Use a Transformation when you want to modify events already flowing through the channels EdgeTag ships with — for example, dropping `PageView` events from paid-media channels, enriching every Purchase with a server-side `source` field, hashing PII uniformly across channels, or emitting a `Purchase_Facebook` event when the user's last paid-media click was Facebook.

{% hint style="info" %}
A [Destination](/playground/destination.md) sends events to a new integration you're building from scratch. A Transformation reshapes events that are already going to existing channels. If you need to make outbound HTTP requests or store data, use a Destination.
{% endhint %}

{% embed url="<https://www.loom.com/share/edab0372d54442759faabb12f494809b>" %}

### The six execution levels

A Transformation consists of six files, one per execution level. Three run on the edge and three run in the browser, each at a different granularity:

| Level    | Edge file     | Browser file        | Runs                                                          |
| -------- | ------------- | ------------------- | ------------------------------------------------------------- |
| Root     | `tagRoot`     | `clientTagRoot`     | Once per event, before channel routing                        |
| Channel  | `tagChannel`  | `clientTagChannel`  | Once per provider channel (for example Facebook)              |
| Instance | `tagInstance` | `clientTagInstance` | Once per provider instance (for example `facebook\|\|pixel1`) |

The rule of thumb: use **root** for rules that apply to all channels, channel for rules tied to a specific provider, and instance for rules tied to a specific pixel or account within a provider.

To set channel or instance settings, exit the Playground from full screen and select options that you would like.

<figure><img src="/files/ajMCKH4fBPVHYfizkbpn" alt=""><figcaption></figcaption></figure>

### What a Transformation can do

Every file returns an object that tells EdgeTag how to handle the event. Any combination of these four is valid:

* **Modify the payload** — return `{ payload: <modified> }` to change the event before it reaches channels.
* **Skip the event** — return `{ skipEvent: true }` to drop the event for this level (everywhere, for this channel, or for this instance).
* **Emit additional events** — return `{ additionalEvents: [<event>, ...] }` to fan out extra events alongside the original.
* **Update user data** — return `{ user: <modified> }` to change the PII attached to this event.

Transformations are **pure event transforms** — they don't make HTTP requests, don't write to storage, and don't touch the identity graph. If you need any of that, use a Destination.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.edgetag.io/playground/transformation.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.