# API Reference

Complete reference for the Consent Pro JavaScript API.

## Table of Contents

- [Global API Access](#global-api-access)
- [Main API Object](#main-api-object)
- [Consent API](#consent-api)
- [Elements API](#elements-api)
- [Events API](#events-api)
- [Lifecycle API](#lifecycle-api)
- [Legacy API Reference](/legacy/api/)

## Global API Access

### Recommended: Callback Queue

Use the callback queue to guarantee that Consent Pro is initialized before using the API. This is generally only needed if you load the script asynchronously. By default (async off), Consent Pro installs as two script tags — a config script followed by the runtime script. Place both directly in the `<head>`, in that order, without `async` or `defer`; this allows you to use the API immediately after the second (runtime) script tag.

```html
<script>
  window.FinsweetConsentPro = window.FinsweetConsentPro || [];
  window.FinsweetConsentPro.push([
    'consent',
    (FinsweetConsentPro) => {
      console.log('Consent Pro loaded:', FinsweetConsentPro.version);

      const choices = FinsweetConsentPro.consents.get();
      console.log('Current choices:', choices);

      FinsweetConsentPro.elements.preferences.show();
    },
  ]);
</script>
```

### Direct Access

After initialization, the runtime API is available at `window.FinsweetConsentPro`.

```javascript
console.log(window.FinsweetConsentPro);
```

## Main API Object

```ts
type FinsweetConsentPro = {
  version: string;
  config: ConsentV2SanitizedRuntimeConfiguration;
  instanceConfig: ConsentV2SanitizedRuntimeConfiguration['instances'][string];

  consents: {
    essential: boolean;
    marketing: boolean;
    analytics: boolean;
    personalization: boolean;

    get: () => ConsentChoices;
    set: (consents: ConsentChoices) => void;
    acceptAll: () => void;
    rejectAll: () => void;
    denyAll: () => void;
    renew: () => void;
  };

  elements: {
    banner: { show: () => void; hide: () => void };
    preferences: { show: () => void; hide: () => void };
    fixedPreferences: { show: () => void; hide: () => void };
  };

  push: (...args: ConsentProCallback[]) => void;
  destroy: () => void;
};
```

## Consent API

### `consents.essential`

Returns the current essential consent state.

**Type:** `boolean`

### `consents.marketing`

Returns the current marketing consent state.

**Type:** `boolean`

### `consents.analytics`

Returns the current analytics consent state.

**Type:** `boolean`

### `consents.personalization`

Returns the current personalization consent state.

**Type:** `boolean`

### `consents.get()`

Returns all current consent choices.

**Returns:** `ConsentChoices`

```javascript
const choices = window.FinsweetConsentPro.consents.get();
console.log(choices.analytics, choices.marketing);
```

### `consents.set(consents)`

Sets all consent choices at once.

**Parameters:**

- `consents` (`ConsentChoices`)

**Returns:** `void`

```javascript
window.FinsweetConsentPro.consents.set({
  essential: true,
  analytics: true,
  marketing: false,
  personalization: false,
});
```

### `consents.acceptAll()`

Accepts all consent categories.

**Returns:** `void`

```javascript
window.FinsweetConsentPro.consents.acceptAll();
```

### `consents.rejectAll()`

Rejects all optional consent categories.

**Returns:** `void`

```javascript
window.FinsweetConsentPro.consents.rejectAll();
```

### `consents.denyAll()`

Alias for `consents.rejectAll()`.

**Returns:** `void`

```javascript
window.FinsweetConsentPro.consents.denyAll();
```

### `consents.renew()`

Resets consent to defaults and shows the banner again.

**Returns:** `void`

```javascript
window.FinsweetConsentPro.consents.renew();
```

## Elements API

### `elements.banner.show()` / `elements.banner.hide()`

Shows or hides the consent banner.

```javascript
window.FinsweetConsentPro.elements.banner.show();
window.FinsweetConsentPro.elements.banner.hide();
```

### `elements.preferences.show()` / `elements.preferences.hide()`

Shows or hides the preferences UI.

```javascript
window.FinsweetConsentPro.elements.preferences.show();
window.FinsweetConsentPro.elements.preferences.hide();
```

### `elements.fixedPreferences.show()` / `elements.fixedPreferences.hide()`

Shows or hides the fixed preferences control.

```javascript
window.FinsweetConsentPro.elements.fixedPreferences.show();
window.FinsweetConsentPro.elements.fixedPreferences.hide();
```

## Events API

Consent Pro emits runtime events that you can consume in two ways:

1. Through the runtime emitter API: `window.FinsweetConsentPro.on(eventName, callback)`
2. Through DOM events prefixed with `consentpro:`

The runtime dispatches DOM events with:

```ts
document.documentElement.dispatchEvent(new CustomEvent(`consentpro:${event}`, { detail }));
```

### Using `window.FinsweetConsentPro.on()`

```javascript
window.FinsweetConsentPro.on('ready', () => {
  console.log('Consent Pro is ready');
});

window.FinsweetConsentPro.on('consent-updated', (detail) => {
  console.log('Consent updated', detail.choices);
});
```

### Using DOM events (`consentpro:*`)

```javascript
document.documentElement.addEventListener('consentpro:banner-shown', () => {
  console.log('Banner became visible');
});

document.documentElement.addEventListener('consentpro:consent-updated', (event) => {
  console.log('Consent updated', event.detail);
});
```

### Available events

- `ready`
- `accept-all`
- `reject-all`
- `consent-updated`
- `banner-shown`
- `banner-hidden`
- `preferences-shown`
- `preferences-hidden`
- `fixed-preferences-shown`
- `fixed-preferences-hidden`
- `script-blocked`
- `script-unblocked`
- `iframe-blocked`
- `iframe-unblocked`
- `map-blocked`
- `map-unblocked`

### Event payloads

- `ready`, `accept-all`, `reject-all`, `banner-shown`, `banner-hidden`, `preferences-shown`, `preferences-hidden`, `fixed-preferences-shown`, `fixed-preferences-hidden`: no payload (`void`)
- `consent-updated`:

```ts
{
  id: string;
  choices: ConsentChoices;
  previousChoices?: ConsentChoices;
  action?: ConsentAction;
  source?: ConsentSource;
  timestamp: number;
}
```

- `script-blocked` / `script-unblocked`:

```ts
{
  src: string;
  element: HTMLScriptElement;
  categories: CookieCategory[];
}
```

- `iframe-blocked` / `iframe-unblocked`:

```ts
{
  src: string;
  element: HTMLIFrameElement;
  categories: CookieCategory[];
}
```

- `map-blocked` / `map-unblocked`:

```ts
{
  element: HTMLElement;
  categories: CookieCategory[];
}
```

## Lifecycle API

### `push(...args)`

Queues one or more callbacks to run after Consent Pro is initialized.

```javascript
window.FinsweetConsentPro = window.FinsweetConsentPro || [];
window.FinsweetConsentPro.push((consent) => {
  console.log('Ready with version', consent.version);
});
```

### `destroy()`

Destroys Consent Pro and runs cleanup handlers.

```javascript
window.FinsweetConsentPro.destroy();
```

## Next Steps

- [Events Documentation](./events.md)