getCookieConsentPreferences

The getCookieConsentPreferences bridge method enables Forge apps to read the user's current cookie consent preferences. Use it to decide whether your app may store data in the browser, such as cookies, localStorage, or analytics identifiers.

Overview

Users choose which categories of cookies and similar technologies they accept. Your app runs inside the host page, so it should respect those choices before it stores or reads anything that isn't essential for the app to work.

getCookieConsentPreferences returns the user's choices for each cookie category. When the user changes their choices, the host emits a FORGE_COOKIE_CONSENT_CHANGED event that your app can subscribe to.

Function signature

1
2
3
4
5
6
7
8
function getCookieConsentPreferences(): Promise<CookieConsentPreferences | null>;

type CookieConsentPreferences = {
  functional: boolean;
  analytics: boolean;
  marketing: boolean;
};

Usage

The following example reads the user's preferences and stores a value in localStorage only when the user has allowed functional storage.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
import { getCookieConsentPreferences } from "@forge/bridge";

const STORAGE_KEY = "my-app-last-view";

async function saveLastView(view: string): Promise<void> {
  const preferences = await getCookieConsentPreferences();

  if (!preferences?.functional) {
    return;
  }

  localStorage.setItem(STORAGE_KEY, view);
}

Subscribe to changes

Use the events API to subscribe to FORGE_COOKIE_CONSENT_CHANGED. The event payload has the same shape as the value returned by getCookieConsentPreferences.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
import {
  events,
  getCookieConsentPreferences,
  type CookieConsentPreferences,
} from "@forge/bridge";

const STORAGE_KEY = "my-app-last-view";

function applyPreferences(preferences: CookieConsentPreferences | null): void {
  if (!preferences?.functional) {
    localStorage.removeItem(STORAGE_KEY);
  }
}

function init(): void {
  getCookieConsentPreferences().then(applyPreferences);

  const subscription = events.on(
    "FORGE_COOKIE_CONSENT_CHANGED",
    async (preferences: CookieConsentPreferences | null) => {
      applyPreferences(preferences);
    }
  );

  window.addEventListener("pagehide", () => {
    subscription.then(({ unsubscribe }) => unsubscribe());
  });
}

events.on resolves to a Subscription, so await it or chain from the promise to reach unsubscribe(). Unsubscribe when your app's view is torn down, so the listener doesn't outlive the code that handles the event. This example uses pagehide rather than the deprecated unload event. If your app is a React component, call unsubscribe() from a useEffect cleanup function instead.

Return value

getCookieConsentPreferences returns a Promise that resolves to null or a CookieConsentPreferences object.

The CookieConsentPreferences object has the following fields:

A value of false means the user has denied that category. Storage that is strictly necessary for your app to work doesn't require consent, so it isn't included.

Best practices

• Default to denied. If the method resolves to null, or a category is false, don't store data for that category.
• Don't store non-essential data until consent is known. Wait for the method to resolve with preferences before you write cookies, localStorage values, or analytics identifiers.
• Subscribe to changes. Listen for FORGE_COOKIE_CONSENT_CHANGED so your app reacts when the user updates their preferences during a session, and call unsubscribe() when the view is torn down.
• Clear stored data when consent is withdrawn. When a category changes from allowed to denied, remove the data your app stored for that category.