# Custom events

Custom events are *synthetic events* in Javascript that can be dispatched to our SDK.

Use custom events to communicate with Didomi custom elements to wrap your code and handle all logic, analytics and API requests.

* [didomi:send-authentication](#didomi-send-authentication)
* [didomi:verify-otp-code](#didomi-verify-otp-code)
* [didomi:set-pending-consents](#didomi-set-pending-consents)
* [didomi:save-pending-consents](#didomi-save-pending-consents)
* [didomi:set-consents](#didomi-set-consents)

#### didomi:send-authentication

To request end-user authentication through the Didomi SDK and send an email to your end-user (via either Magic Link or One-Time Password code) dispatch the `didomi:send-authentication` custom event. Set the email address provided by the end-user to `detail.value`.

Note that our Headless widget will use the default authentication provider of your organization. To use a different provider, you can [define a provider](https://developers.didomi.io/api-and-platform/widgets/authentication/manage-authentication-providers#manage-authentication-within-a-widget) at widget level.

{% hint style="warning" %}
`didomi:send-authentication` custom event needs to be dispatched from an element within the `didomi-auth-headless` custom element.
{% endhint %}

```javascript
new CustomEvent("didomi:send-authentication", {
      detail: {
        value: email,
      },
      bubbles: true,
      composed: true,
    });
```

#### didomi:verify-otp-code

*<mark style="color:blue;">This event needs the previous event to work properly as the</mark>* <mark style="color:blue;">`send-authentication`</mark> *<mark style="color:blue;">event will allow email address storage in local storage that is required to verify the code.</mark>*

If your widget is using a One-Time Password provider, you need to verify the code received by the end-user. To verify the code, dispatch the `didomi:verify-otp-code` custom event. Set the code provided by the end-user to `detail.value`.

{% hint style="warning" %}
`didomi:verify-otp-code` custom event needs to be dispatched from an element within the `didomi-auth-headless` custom element.
{% endhint %}

```json
new CustomEvent("didomi:verify-otp-code", {
      detail: {
        value: otpCode,
      },
      bubbles: true,
      composed: true,
    });
```

#### didomi:set-pending-consents

To set end-user pending consents in your web application state, dispatch the `didomi:set-pending-consents` custom event.

When setting a purpose, the `detail` object must contain the `purposeId` and the corresponding `value` (true or false). When setting a preference, the `detail` object must contain the `purposeId`, `preferenceId`, and the selected `value`.

{% hint style="warning" %}
Custom event `didomi:set-pending-consents` should be dispatched from an element placed within the `didomi-pending-consent-receiver` wrapper.
{% endhint %}

```javascript
new CustomEvent("didomi:set-pending-consents", {
      // If used for Purposes
      detail: {
        purposeId,
        value: true/false,
      },
      // If used for Preference values
      detail: {
        purposeId,
        preferenceId,
        value: "asdf,ghjk,bvcx", // list of enabled values as string
      },
      bubbles: true,
      composed: true,
    });
```

#### didomi:save-pending-consents

To save end-user pending consents using the Didomi SDK, dispatch the `didomi:save-pending-consents` custom event.

{% hint style="warning" %}
Custom event `didomi:save-pending-consents`should be dispatched from an element placed within the `didomi-pending-consent-receiver` wrapper.
{% endhint %}

```javascript
new CustomEvent("didomi:save-pending-consents", {
      detail: {
        // You can pass optional metadata object
        metadata: {},
        // You can pass optional userMetadata object
        userMetadata: {},
      },
      bubbles: true,
      composed: true,
    });
```

#### didomi:set-consents

To save end-user consent upon end-user click through our SDK, dispatch the `didomi:set-consents` custom event.

When saving a purpose, the `detail` object should include the `purposeId` and the corresponding `value` (true or false). When saving a preference, the `detail` object should include the `purposeId`, `preferenceId`, and the selected `value`.

Custom event `didomi:set-consents` should be dispatched from an element placed within the `didomi-consent-receiver` wrapper.

```javascript
new CustomEvent("didomi:set-consents", {
      // If used for Purposes
      detail: {
        purposeId,
        value: true/false,
        // You can pass optional metadata object
        metadata: {},
        // You can pass optional userMetadata object
        userMetadata: {},
      },
      // If used for Preference values
      detail: {
        purposeId,
        preferenceId,
        value: "qFkQbPnT,gEhjHDk,sbvLLcx", // list of enabled values as string
        // You can pass optional metadata object
        metadata: {},
        // You can pass optional userMetadata object
        userMetadata: {},
      },
      bubbles: true,
      composed: true,
    });
```

*Note that the* `bubbles` *and* `composed` *options must be set to* `true` *to allow the event to bubble and trigger listeners outside of a shadow root, respectively.*