# Configuring Custom Purposes for Preference Management (/docs/preference-management/configuring-custom-purposes-for-preference-management)

## Step 1) Set up website consent via airgap.js [#step-1-set-up-website-consent-via-airgapjs]

This guide and associated functionalities are dependent on airgap.js being installed and configured on your website(s).

If you have not integrated with airgap.js yet, you can do so by following [Transcend Consent Management documentation](../consent-management/quickstart.mdx#adding-the-html-script).

## Step 2) Persist consent preferences to a backend [#step-2-persist-consent-preferences-to-a-backend]

Check out the [Full Stack Consent Management](../consent-management/full-stack-consent.mdx) to see backend integration options. The recommended solution is to use [Transcend Preference Management](./storing-consent-preferences.mdx) to store consent preferences.

Your backend server would generate the token that identifies the user:

```javascript
// When a user has authenticated
const consentToken = createConsentToken(
  userId,
  base64EncryptionKey,
  base64SigningKey,
);
```

Then the that token would be passed to airgap on the client side:

```javascript
// Authenticate the user to airgap, and sync their consent with Transcend Preference Management
airgap.sync({ auth: consentToken });
```

If you decide to use your own backend, you can listen to consent changes events using the following:

```javascript
// Listen for consent change events
airgap.addEventListener(
  'consent-change',
  ({ detail: { consent, oldConsent, changes } }) => {
    // Read consent data and act accordingly
  },
);
```

and you can set consent preferences using:

```javascript
airgap.setConsent(auth, { SaleOfInfo: true, CustomPurpose: false });
```

## Step 3) Create a Custom Purpose [#step-3-create-a-custom-purpose]

Depending on your case, you may need to create a new custom purpose, such as `PushNotifications` `AlwaysBlock` or `SNAPCollection`, etc.

You can do so by heading towards the [Consent Management -> Regional Experiences -> Purposes](https://app.transcend.io/consent-manager/regional-experiences/purposes).

![Purpose tab in Regional Experiences](/images/screenshot/2023-09-28-custom-purpose.png)

When creating a custom purpose, configure the following parameters:

- `Name`: full name for your new purpose.
- `Slug`: internal name for the purpose. Should only contain letters and cannot be changed after creation. This is what will be used in `airgap.getConsent()` and `airgap.setConsent()`
- `Description`: explicit definition for your purpose, which will be used in the Consent UI if applicable.
- `Respected Privacy Signals`: if known privacy signals (GPC, DNT) should cause this purpose to be opted out for the corresponding user.
- `Show in consent manager`: if you would like users to be asked to opt in or out of this purpose. Some custom purposes might be for internal use only and don't need to be exposed to end users. This cannot be set to `True` if Configurable is `False` as a non-configurable purpose should not show in consent UI.
- `Configurable`: similarly to the parameter below, if your purpose is for internal use only (or for any other reason), you may decide for its value to be set once and never modified. Note that a purpose that does not show in UI can still be modified [with code](../consent-management/testing-and-troubleshooting/faq.mdx#how-do-i-set-user-consent-from-my-website-ui), if Configurable is `True`.

## Step 4) Update Regional Experiences [#step-4-update-regional-experiences]

Once your custom purpose is created, update corresponding [Regional Experiences](https://app.transcend.io/consent-manager/regional-experiences) in your Consent dashboard to put in restrictions on where these preferences can be customized. For example, you may want to add a `SensitiveInformation` purpose that is only available in Virginia.

![Regional Experiences with Custom Purpose](/images/screenshot/2023-09-29-custom-purpose-region.png)

If you want the purpose to be available globally, you'll want to add the purpose to every experience. If you want the purpose to be opted out by default, you'll want to make sure you add the purpose to both the `APPLICABLE CONSENT PURPOSES` and `DEFAULT DISALLOWED CONSENT PURPOSES` columns.

## Step 5) Enable Consent Collection [#step-5-enable-consent-collection]

If your custom purpose was set as `Configurable` in the previous steps, user consent can be collected a few different ways.

- Use the `CompleteOptions` [view state](https://github.com/transcend-io/consent-manager-ui). This view state shows all consent purposes available in the current experience where `Show in consent manager=true`

![Custom Purpose in Consent Banner](/images/screenshot/2023-09-29-custom-purpose-banner.png)

Remember that messages and button labels are customizable from the [Consent Management -> Consent Display Settings -> Messages](https://app.transcend.io/consent-manager/display-settings/messages) tab.

![Custom Purpose Messaging](/images/screenshot/2023-09-29-custom-purpose-message.png)

- Use the `CompleteOptionsToggles` [view state](https://github.com/transcend-io/consent-manager-ui#completeoptionstoggles). This view state shows all consent purposes available in the current experience where `Show in consent manager=true`
- Custom form or alternate UI on your website. If you want to control the flow of collecting user consent for your new purpose, you can integrate with [airgap.js](../consent-management/testing-and-troubleshooting/faq.mdx#how-do-i-set-user-consent-from-my-website-ui) using the `airgap.getConsent()` and `airgap.setConsent()` APIs.

![Custom Form](/images/2023-10-17-consent-purpose-form.png)

## Step 6) Trigger a DSR Workflow on Consent Change (Optional) [#step-6-trigger-a-dsr-workflow-on-consent-change-optional]

If you need to persist the consent preference to other systems (e.g. unsubscribe a user in a Database or SaaS tool like Salesforce, Marketo, Segment), you may want to trigger a [DSR](../dsr-automation/overview.mdx) on consent change event.

This can be done in a two ways:

1. Make an explicit server-side API call to the DSR API:

   <APIOperation path="/v1/data-subject-request" method="post" />

2. If you are using [Transcend Preference Management](./storing-consent-preferences.mdx), you can work with your dedicated solutions engineer to describe which workflows should be triggered when consent purposes change. As long as you call `airgap.sync({ auth: consentToken });`, then any DSR workflow can be triggered on consent change.

![Consent DSR](/images/2023-10-17-conent-dsr.png)