> For the complete documentation index, see [llms.txt](https://alhena.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://alhena.gitbook.io/docs/developer-reference/website-sdk/site-events.md).

# Site Events

Send your own site events (product views, category views, add to cart and purchases) to Alhena from your tag manager, site code, or server.

Site Events let you send Alhena the shopping activity your site already tracks: product views, category and search views, add to cart, and purchases. Alhena stores each event exactly as you send it and uses it to understand how shoppers browse and buy, including shoppers who never open the chat.

You can send events from any page, even where the Alhena widget isn't loaded. Most stores add one tag in their tag manager (Google Tag Manager or Tealium). No Alhena SDK code is required.

{% hint style="info" %}
Site Events are for analysis. They don't affect revenue attribution. To attribute revenue to Alhena, use [Cart & Checkout Events](/docs/developer-reference/website-sdk/cart-checkout-events.md).
{% endhint %}

## Endpoint

```
POST /analytics/customer_events?company_key=YOUR_COMPANY_KEY
```

Send requests to the host for your region:

* **US region -** <https://app.alhena.ai/>
* **EU region -** <https://eu.alhena.ai/>

Put your Alhena company key in the URL. Send one event per request.

## Payload

The body is a JSON object. Only `event` is required. Every other field is stored as you send it, so you can reuse the event objects your site already builds.

```json
{
  "event": "purchase",
  "user_fingerprint": "550e8400-e29b-41d4-a716-446655440000",
  "order_id": "ORD-7890",
  "value": 199.97,
  "currency": "USD",
  "items": [
    { "product_id": "123", "price": 99.99, "quantity": 2 }
  ]
}
```

| Field              | Type   | Required    | Description                                                                              |
| ------------------ | ------ | ----------- | ---------------------------------------------------------------------------------------- |
| `event`            | string | Yes         | The event name, for example `view_item`, `add_to_cart` or `purchase`                     |
| `user_fingerprint` | string | Recommended | The visitor's Alhena fingerprint. Links the event to the visitor's Alhena conversations. |
| Any other field    | any    | No          | Stored as sent: product IDs, prices, order ID, page URL, and so on                       |

We suggest the same event names Google Analytics 4 uses, such as `view_item`, `add_to_cart` and `purchase`, but any name works. Alhena also records when each event arrived and which browser sent it.

{% hint style="warning" %}
Don't send personal information such as email addresses, names, phone numbers, street addresses or payment details.
{% endhint %}

### Getting the Fingerprint

The Alhena widget keeps the visitor's fingerprint in a first-party cookie named `fingerprint-uuid`. Read it in whichever way suits your setup:

* **Site code:** call `window.gleenWidget.getFingerprint()` when the widget is loaded, or read the `fingerprint-uuid` cookie.
* **Google Tag Manager:** create a **1st-Party Cookie** variable for `fingerprint-uuid`.
* **Tealium iQ:** use the `cp.fingerprint-uuid` value.

The cookie exists once the Alhena widget has loaded in the visitor's browser. Until then, send the event with an empty `user_fingerprint`.

## Response

```json
{
  "status": "success",
  "event_type": "CUSTOMER_EVENT_RECORDED"
}
```

If `company_key` or `event` is missing, the event isn't stored and the response is:

```json
{
  "status": "error",
  "event_type": "MISSING_REQUIRED_FIELDS"
}
```

## Examples

{% tabs %}
{% tab title="JavaScript" %}

```javascript
function sendAlhenaEvent(event) {
  const cookie = document.cookie.match(/(?:^|; )fingerprint-uuid=([^;]*)/);
  event.user_fingerprint = cookie ? cookie[1] : '';
  navigator.sendBeacon(
    'https://app.alhena.ai/analytics/customer_events?company_key=YOUR_COMPANY_KEY',
    JSON.stringify(event)
  );
}

sendAlhenaEvent({ event: 'view_item', product_id: '123', page_url: location.href });
```

{% endtab %}

{% tab title="Google Tag Manager" %}
Create a **Custom HTML** tag with a **Custom Event** trigger for your ecommerce events (for example `view_item|add_to_cart|purchase`, with regex matching on):

```html
<script>
  navigator.sendBeacon(
    'https://app.alhena.ai/analytics/customer_events?company_key=YOUR_COMPANY_KEY',
    JSON.stringify({
      event: {{Event}},
      ecommerce: {{DLV - ecommerce}},
      page_url: {{Page URL}},
      user_fingerprint: {{Cookie - fingerprint-uuid}} || ''
    })
  );
</script>
```

`{{Event}}` and `{{Page URL}}` are built-in variables. Create `{{DLV - ecommerce}}` as a **Data Layer Variable** for `ecommerce`, and `{{Cookie - fingerprint-uuid}}` as a **1st-Party Cookie** variable.
{% endtab %}

{% tab title="Tealium iQ" %}
If a tag already builds an event payload (for example, one that sends the same events to another analytics vendor), add these lines after the payload is built:

```javascript
payload.user_fingerprint = b['cp.fingerprint-uuid'] || '';
navigator.sendBeacon(
  'https://app.alhena.ai/analytics/customer_events?company_key=YOUR_COMPANY_KEY',
  JSON.stringify(payload)
);
```

{% endtab %}

{% tab title="cURL" %}

```bash
curl 'https://app.alhena.ai/analytics/customer_events?company_key=YOUR_COMPANY_KEY' \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "event": "purchase",
    "user_fingerprint": "550e8400-e29b-41d4-a716-446655440000",
    "order_id": "ORD-7890",
    "value": 199.97,
    "currency": "USD"
  }'
```

{% endtab %}
{% endtabs %}

***

## Notes

* **Use `sendBeacon` in the browser**\
  It keeps working when the shopper leaves the page and needs no special headers. Bodies sent as `text/plain` or `application/json` are both accepted.
* **Duplicates**\
  A page reload can send the same purchase twice. Include a stable order ID so repeat events can be removed.
* **Viewing the data**\
  Site Events don't have a dashboard view yet. Your Alhena team can share reports.