# Events Documentation

Consent Pro emits integration events through `window.dataLayer` for analytics and tag-manager workflows.

## Table of Contents

- [Overview](#overview)
- [GTM dataLayer Events](#gtm-datalayer-events)
- [How to Use in GTM](#how-to-use-in-gtm)
- [How to Listen in JavaScript](#how-to-listen-in-javascript)

## Overview

In the current public API:

- `window.FinsweetConsentPro.on(eventName, handler)` and `.off(eventName, handler)` are exposed through the runtime emitter. `once` and `subscribe` are not public emitter methods.
- Runtime events also dispatch DOM events prefixed with `consentpro:`; these are distinct from the GTM dataLayer notifications.
- Consent lifecycle signals are emitted as `dataLayer` events.

## GTM dataLayer Events

Consent Pro pushes the following events to `window.dataLayer`:

### `consent-updated`

Fired whenever consent choices are applied, including rejection and restored choices. The dataLayer entry is `{ event: 'consent-updated' }`; it does not carry the runtime emitter payload. This event alone never proves consent is granted.

### `essential-activated`

Fired once, when `essential` is active.

### `analytics-activated`

Fired once, when `analytics` is active.

### `marketing-activated`

Fired once, when `marketing` is active.

### `personalization-activated`

Fired once, when `personalization` is active.

### `uncategorized-activated`

Fired once, when all categories are active.

## How to Use in GTM

For consent-dependent initialization, prefer `analytics-activated`, `marketing-activated` or `personalization-activated` as a Custom Event trigger plus matching additional consent checks. Basic GA4 initialization uses `analytics-activated` plus `analytics_storage`. Advanced Google initialization uses Initialization — All Pages and built-in consent behavior instead; select the intended mode first. Category events also apply to remembered consent. Reserve `consent-updated` for deliberately configured update handling, and review existing valid triggers before replacing them. `consent-updated` also fires after rejection. Category activation events fire once per page and do not represent purchase or lead events. They do not stop already-loaded code after withdrawal; verify subsequent behavior separately.

Keep business-event triggers for conversion tags and apply appropriate consent checks for the selected mode and purpose. Supported Google tags in Advanced mode use built-in consent behavior. Do not replace them with Consent Updated or All Pages. See [Consent-aware GTM troubleshooting](/knowledge/gtm-troubleshooting).

## How to Listen in JavaScript

Register after runtime initialization, using the supported callback queue:

```javascript
window.FinsweetConsentPro = window.FinsweetConsentPro || [];
window.FinsweetConsentPro.push((api) => {
  const handler = (detail) => {
    console.log('Updated choices', detail.choices);
  };
  api.on('consent-updated', handler);
});
```

Call `api.off('consent-updated', handler)` to remove the same handler when no longer needed.

The emitter's `consent-updated` payload includes choices, timestamp, consent ID, action, source, and previous choices. It fires when changed choices are persisted; unchanged choices need not produce another emitter event. It is distinct from the dataLayer event generated when Google consent state is applied. See the [API Reference](/runtime/api) for event types and DOM listeners.

## Related

- [API Reference](./api.md)