# Exposure Events

## The assignment moment

Exposure events happen every time the `treatment` function is called to check which variant of an experiment to show a visitor. This is how it might look in case of an A/B/C experiment.

```javascript
context.ready().then(function () {
  const expAssignment = context.treatment("experiment_name");
  if (expAssignment === 1) {
    // insert code to show for Variant 1
  } else if (expAssignment === 2) {
    // insert code to show for Variant 2
  } else {
    // insert the Control/Base code
  }
});
```

This `treatment` function call will return the variant assignment. `0` for base, `1` for variant 1 or `2` for variant 2.

> **info**
>
> For a given user identifier, the **treatment** call will always return the same value, making the assignment sticky. This is a very important feature as this means the same visitor will always be shown the same variant.

Before sending exposure events, make sure to correctly initialise and enrich the ABsmartly's context with the [visitor's identity](https://docs.absmartly.com/docs/web-console-docs/events/visitors-identity.md).

## The events page

As soon as your code is deployed and visitors enter this part of your product, exposure events will start being appearing in the ABsmartly's [events' page](https://docs.absmartly.com/docs/web-console-docs/events/the-events-page.md).

![Exposure events on the events page](/assets/images/events-page-exposures-b01d6c80e389cccb883c9042f9d90294.png)

Monitoring events on the events' page is a great way to ensure your tracking is set up properly.

> **tip**
>
> You can even start monitoring the events page before the experiment is started.

## Understanding exposure events data

From the events' page, you can inspect any exposure event raw json data by clicking the event on the event's page.

```json
{
  "event_type": "exposure",
  "unit_uid": "of2dhFlqHRXpW8iQG9mepw",
  "unit_uid_hex": "a1fd9d84596a1d15e95bc8901bd99ea7",
  "unit_type": "absId",
  "unit_type_id": 42,
  "agent": "absmartly-javascript-sdk",
  "application": "absmartly.com",
  "application_id": 39,
  "environment": "Prod",
  "environment_id": 3,
  "environment_type": "production",
  "event_at": 1762888120666,
  "unit_attributes": {
    "application": "absmartly.com",
    "user_agent": {
      "device_type": "Mobile",
      "crawler": "no",
      "value": "Mozilla/5.0 (iPhone; CPU iPhone OS 17_2_1 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.2 Mobile/15E148 Safari/604.1",
      "platform": "iOS",
      "browser": "Safari",
      "browser_type": "Browser"
    },
    "__crawler": false
  },
  "experiment_id": 3214,
  "experiment_name": "absmartly_site_aa",
  "experiment_iteration": 0,
  "variant": 0,
  "flags": 1,
  "properties": null
}
```

Below is an overview of some of the data you will find in the exposure event's raw data.

| Field                | Description                                                                                         |
| -------------------- | --------------------------------------------------------------------------------------------------- |
| **event\_type**      | This indicates the sort of event. In this case, `exposure`.                                         |
| **unit\_type**       | The sort of unit used to identify the visitor.                                                      |
| **unit\_uid**        | The visitor's unique identifier for this unit type. One event is sent for each register identifier. |
| **application**      | Indicates the application where this event comes from.                                              |
| **event\_at**        | The event's timestamp.                                                                              |
| **unit\_attributes** | The list of visitor's attributes registered for this event.                                         |
| **experiment\_id**   | The experiment's id.                                                                                |
| **experiment\_name** | The experiment's name.                                                                              |
| **variant**          | The variant's assignment'. 0 for base. 1 for variant 1. etc.                                        |
| **flags**            | A bitmask describing how this exposure was assigned. See [The flags field](#the-flags-field) below. |

## The flags field

The `flags` field matters most when you export events and crunch the numbers yourself. Inside the UI it's already applied, so you rarely have to think about it. A raw [events-page export](https://docs.absmartly.com/docs/web-console-docs/events/downloading-events.md#from-the-events-page) gives you every exposure we ingested, and `flags` is how you tell a real participant apart from a bot, an ineligible visitor or an overridden assignment. An [experiment export](https://docs.absmartly.com/docs/web-console-docs/events/downloading-events.md#from-the-experiments-overview) skips this step, since it's already filtered down to effective exposures, but any query you run against a raw export or your own warehouse needs it.

`flags` is a **bitmask**. Each bit answers one yes/no question about the exposure, all packed into a single integer, so one event can have several bits set at once. That means you test it with a bitwise `AND` rather than comparing the whole number.

### The bits

| Bit value | Name              | Meaning                                                                                                                    |
| --------- | ----------------- | -------------------------------------------------------------------------------------------------------------------------- |
| `1`       | eligible          | The unit was eligible to participate. When this is **0**, traffic allocation was below 100% and this unit fell outside it. |
| `2`       | assigned          | The assignment logic ran for this exposure. When this is **0**, no variant was actually assigned.                          |
| `4`       | overridden        | The assignment was overridden by the SDK.                                                                                  |
| `8`       | full on           | The experiment was full on (100% on a single variant) when the event was ingested.                                         |
| `16`      | custom            | The exposure used a custom assignment.                                                                                     |
| `32`      | audience mismatch | The unit did not match the experiment's intended audience.                                                                 |
| `64`      | crawler           | The unit was detected as a bot or crawler.                                                                                 |
| `128`     | ignored           | The unit was flagged to be ignored via its unit attributes. Present in exported data but not shown in the UI.              |
| `256`     | rule override     | The variant was determined by a rule override rather than the normal assignment.                                           |

### Reading a value

Take `flags = 3`. In binary that's `0000 0011`, so bits `1` and `2` are set:

```javascript
const eligible = (flags & 1) !== 0; // true
const assigned = (flags & 2) !== 0; // true
const crawler  = (flags & 64) !== 0; // false
```

That's a clean exposure: the visitor was eligible and got assigned a variant. Compare it with `flags = 66` (`0100 0010`), where bit `2` (assigned) and bit `64` (crawler) are set but bit `1` (eligible) isn't. That row is a bot, so it shouldn't count as a participant.

### Matching the UI's participant count

A row counts as an effective participant when it's eligible and assigned and none of the disqualifying bits are set. You can check all of that in one masked test, `(flags & 207) = 3`: the mask keeps bits `1 + 2 + 4 + 8 + 64 + 128`, and `= 3` means eligible (`1`) and assigned (`2`) are the only ones left standing.

```sql
-- matches the UI's participant count for one experiment
SELECT count(DISTINCT unit_uid)
FROM exposures
WHERE (flags & 207) = 3
  AND experiment_id = <your experiment id>
  AND unit_type = '<your unit type>'
```

Scope the count to a single experiment and unit type, as shown above. A `unit_uid` is only unique within its `unit_type`, and an export can span many experiments, so counting across the whole file would merge separate visitors.

The `207` mask throws out overridden (`4`), full on (`8`), crawler (`64`) and ignored (`128`) rows. Rule overrides get excluded too, just by a different route: the SDK never marks them as assigned (bit `2`), so they fail the `= 3` test on their own. Custom (`16`) and audience mismatch (`32`) aren't in the mask, so on their own they won't drop a row from the count.

## Events info & warning

Exposure events can be labelled with extra information or warning

| Label                                                                                                                                                                  | Type    | Trigger                                 |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | --------------------------------------- |
| **An experiment with this name was not running at the time of ingestion**                                                                                              | warning | `experiment_id` empty (not flag-driven) |
| **The unit of this exposure event was not eligible to participate in the experiment at the time of ingestion because traffic allocation for the experiment was < 100** | warning | eligible bit (`1`) not set              |
| **The assignment logic did not run for this exposure event**                                                                                                           | warning | assigned bit (`2`) not set              |
| **The assignment of this exposure was overridden by the SDK**                                                                                                          | warning | overridden bit (`4`) set                |
| **The experiment was full on at the time of ingestion**                                                                                                                | info    | full on bit (`8`) set                   |
| **This exposure has a custom assignment**                                                                                                                              | info    | custom bit (`16`) set                   |
| **The unit of this exposure event did not match the intended audience**                                                                                                | info    | audience mismatch bit (`32`) set        |
| **The unit of this exposure event was detected to be a bot/crawler**                                                                                                   | info    | crawler bit (`64`) set                  |
| **The variant of this exposure was determined by a rule override**                                                                                                     | info    | rule override bit (`256`) set           |

The full on label is worth acting on: it's good practice to clean up full on experiments once you're done with them.
