Reference

Usage

You can access all methods through a ref to the <DidomiSDK /> component.

import { DidomiSDK, DidomiSDKAPI } from '@didomi/vega-sdk';
import React, { useRef } from 'react';

const App = () => {
  const didomiRef = useRef<DidomiSDKAPI>(null);

  return (
    <DidomiSDK
      noticeId="YOUR_NOTICE_ID"
      didomiPublicApiKey="YOUR_PUBLIC_API_KEY"
      ref={didomiRef}
      onReady={() => console.log('SDK ready')}
    >
      <YourApp />
    </DidomiSDK>
  );
};

addEventListener

Attach a listener to SDK events (consent changes, UI visibility, errors, etc.).

Signature

didomi.addEventListener(event: DidomiEvent, handler: (payload?: unknown) => void): void

Parameters

  • event — Event name (see Events list below).

  • handler — Callback invoked with an optional payload.

Returns

  • void

Example

didomiRef.current?.addEventListener('consent.changed', (status) => {
  console.log('Consent changed', status);
});

removeEventListener

Detach a previously registered event listener.

Signature

didomi.removeEventListener(event: DidomiEvent, handler: (payload?: unknown) => void): void

Parameters

  • event — Event name.

  • handler — The same function reference passed to addEventListener.

Returns

  • void

Example

const onChanged = (s: unknown) => {/* ... */};
didomiRef.current?.addEventListener('consent.changed', onChanged);
// later
didomiRef.current?.removeEventListener('consent.changed', onChanged);

getJavaScriptForWebView

Generate an inline JS snippet to inject into a Vega WebView that mirrors the current consent state.

Signature

didomi.getJavaScriptForWebView(): Promise<string>

Parameters

  • None

Returns

  • Promise<string> — JavaScript to inject.

Example

const js = await didomiRef.current?.getJavaScriptForWebView();
vegaWebView.injectJavaScript(js!);

getQueryStringForWebView

Build a query string carrying the current consent information for WebView navigation.

Signature

didomi.getQueryStringForWebView(): Promise<string>

Parameters

  • None

Returns

  • Promise<string> — Query string (without the leading ?).

Example

const qs = await didomiRef.current?.getQueryStringForWebView();
vegaWebView.loadUrl(`https://example.app/privacy?${qs}`);

showNotice

Display the consent notice. If already visible, it becomes focused.

Signature

didomi.notice.show(): void

Parameters

  • None

Returns

  • void

Example

didomiRef.current?.notice.show();

hideNotice

Hide the consent notice if visible.

Signature

didomi.notice.hide(): void

Parameters

  • None

Returns

  • void

Example

didomiRef.current?.notice.hide();

isNoticeVisible

Check if the consent notice is currently visible.

Signature

didomi.notice.isVisible(): Promise<boolean>

Parameters

  • None

Returns

  • Promise<boolean>

Example

const visible = await didomiRef.current?.notice.isVisible();

showPreferences

Open the preferences dialog.

Signature

didomi.preferences.show(type?: 'information' | 'purposes' | 'vendor'): void

Parameters

  • type (optional) — Initial tab to open ('information', 'purposes', or 'vendor'). Defaults to 'purposes'.

Returns

  • void

Example

didomiRef.current?.preferences.show('vendor');

hidePreferences

Close the preferences dialog if open.

Signature

didomi.preferences.hide(): void

Parameters

  • None

Returns

  • void

Example

didomiRef.current?.preferences.hide();

isPreferencesVisible

Check if the preferences dialog is visible.

Signature

didomi.preferences.isVisible(): Promise<boolean>

Parameters

  • None

Returns

  • Promise<boolean>

Example

const isOpen = await didomiRef.current?.preferences.isVisible();

isReady

Return whether the SDK has finished initialization.

Signature

didomi.isReady(): boolean

Parameters

  • None

Returns

  • boolean

Example

if (didomiRef.current?.isReady()) { /* ... */ }

onReady

Register a callback to run once the SDK is ready.

Signature

didomi.onReady(callback: () => void): void

Parameters

  • callback — Invoked when the SDK is ready (called immediately if already ready).

Returns

  • void

Example

didomiRef.current?.onReady(() => console.log('Vega SDK ready'));

onError

Register a callback for SDK-level errors (configuration, network, rendering).

Signature

didomi.onError(callback: (error: unknown) => void): void

Parameters

  • callback — Receives an error object or message.

Returns

  • void

Example

didomiRef.current?.onError((e) => console.error('Didomi error', e));

isError

Returns whether the SDK is in an error state.

Signature

didomi.isError(): boolean

Parameters

  • None

Returns

  • boolean

Example

if (didomiRef.current?.isError()) { /* show fallback */ }

setLogLevel

Set the SDK log verbosity.

Signature

didomi.setLogLevel(level: 'DEBUG' | 'INFO' | 'WARN' | 'ERROR'): void

Parameters

  • level — Desired log level.

Returns

  • void

Example

didomiRef.current?.setLogLevel('INFO');

getText

Resolve a UI text key using the current language.

Signature

didomi.getText(key: string): Promise<string | undefined>

Parameters

  • key — Text key.

Returns

  • Promise<string | undefined>

Example

const title = await didomiRef.current?.getText('notice.title');

getTranslatedText

Resolve a UI text key for a specific language.

Signature

didomi.getTranslatedText(key: string, lang: string): Promise<string | undefined>

Parameters

  • key — Text key.

  • lang — IETF language tag (e.g., en, fr-FR).

Returns

  • Promise<string | undefined>

Example

const titleFr = await didomiRef.current?.getTranslatedText('notice.title', 'fr');

updateSelectedLanguage

Change the SDK UI language at runtime.

Signature

didomi.updateSelectedLanguage(lang: string): Promise<void>

Parameters

  • lang — IETF language tag.

Returns

  • Promise<void>

Example

await didomiRef.current?.updateSelectedLanguage('es');

getVendor

Retrieve a vendor definition by ID.

Signature

didomi.getVendor(vendorId: string): Promise<Vendor | undefined>

Parameters

  • vendorId — Vendor identifier.

Returns

  • Promise<Vendor | undefined>

Example

const vendor = await didomiRef.current?.getVendor('google');

getPurpose

Retrieve a purpose definition by ID.

Signature

didomi.getPurpose(purposeId: string): Promise<Purpose | undefined>

Parameters

  • purposeId — Purpose identifier.

Returns

  • Promise<Purpose | undefined>

Example

const purpose = await didomiRef.current?.getPurpose('cookies');

getTotalVendorCount / getIabVendorCount / getNonIabVendorCount

Counts for vendors in the current configuration.

Signatures

didomi.getTotalVendorCount(): Promise<number>
didomi.getIabVendorCount(): Promise<number>
didomi.getNonIabVendorCount(): Promise<number>

Parameters

  • None

Returns

  • Promise<number>

Example

const [all, iab, nonIab] = await Promise.all([
  didomiRef.current!.getTotalVendorCount(),
  didomiRef.current!.getIabVendorCount(),
  didomiRef.current!.getNonIabVendorCount(),
]);

getRequiredPurposes / getRequiredVendors

Return lists of purposes/vendors that are required by configuration.

Signatures

didomi.getRequiredPurposes(): Promise<string[]>
didomi.getRequiredVendors(): Promise<string[]>

Parameters

  • None

Returns

  • Promise<string[]>

Example

const requiredPurposes = await didomiRef.current?.getRequiredPurposes();

applicableRegulation

Get the regulation currently applied to the user (e.g., gdpr, cpra, none).

Signature

didomi.applicableRegulation(): Promise<string>

Parameters

  • None

Returns

  • Promise<string>

Example

const reg = await didomiRef.current?.applicableRegulation();

getCurrentUserStatus

Return the current user consent status.

Signature

didomi.getCurrentUserStatus(): Promise<UserStatus>

Parameters

  • None

Returns

  • Promise<UserStatus>

Example

const status = await didomiRef.current?.getCurrentUserStatus();

isUserStatusPartial

Whether the stored status is partial (some choices missing).

Signature

didomi.isUserStatusPartial(): Promise<boolean>

Parameters

  • None

Returns

  • Promise<boolean>

Example

const partial = await didomiRef.current?.isUserStatusPartial();

setCurrentUserStatus

Set the user consent status at purpose/vendor level.

Signature

didomi.setCurrentUserStatus(status: {
  purposes?: Record<string, 'granted' | 'denied'>,
  vendors?: Record<string, 'granted' | 'denied'>
}): Promise<void>

Parameters

  • status — Object with per-purpose and/or per-vendor decisions.

Returns

  • Promise<void>

Example

await didomiRef.current?.setCurrentUserStatus({
  purposes: { storage: 'granted', measurement: 'denied' },
  vendors: { google: 'granted' }
});

setUserAgreeToAll

Grant consent for all purposes and vendors.

Signature

didomi.setUserAgreeToAll(): Promise<void>

Parameters

  • None

Returns

  • Promise<void>

Example

await didomiRef.current?.setUserAgreeToAll();

setUserDisagreeToAll

Deny consent for all purposes and vendors.

Signature

didomi.setUserDisagreeToAll(): Promise<void>

Parameters

  • None

Returns

  • Promise<void>

Example

await didomiRef.current?.setUserDisagreeToAll();

openCurrentUserStatusTransaction

Create a transaction to stage updates to the current user status (purposes & vendors) and apply them atomically on commit.

Updates made via the transaction are queued and only written to the user status when you call commit().

Signature

didomi.openCurrentUserStatusTransaction(): CurrentUserStatusTransaction

Parameters

  • None

Returns

  • CurrentUserStatusTransaction — A chainable object for batching purpose/vendor updates.

Behavior & Notes

  • Purposes/vendors not specified in the transaction remain unchanged.

  • Essential purposes are always enabled and cannot be changed by the transaction.

  • If the applied regulation is none, vendors and purposes remain enabled; commit() will return false.

  • IDs not present in the Notice Config are ignored (no-op).

  • Invalid IDs are ignored; errors may be logged to the console (see Error handling below).

Example

const tx = didomiRef.current!.openCurrentUserStatusTransaction();

// enable / disable purposes
tx.enablePurpose('cookies');
tx.enablePurposes(['cookies', 'analytics']);
tx.disablePurpose('analytics');
tx.disablePurposes(['cookies', 'analytics']);

// enable / disable vendors
tx.enableVendor('vendor-1');
tx.enableVendors(['vendor-1', 'vendor-2']);
tx.disableVendor('vendor-1');
tx.disableVendors(['vendor-1', 'vendor-2']);

// chain calls
tx.enablePurpose('cookies').disablePurpose('analytics');

// apply all staged changes
const updated = await tx.commit(); // true if changes applied, false otherwise

Error handling

  • Invalid purposes or vendors are ignored; the SDK may log messages to the browser console. Example:

    const tx = didomiRef.current!.openCurrentUserStatusTransaction();
tx.enablePurposes(['cookies', 'invalid_ID']);
const ok = await tx.commit();
// Console:
// 'Didomi SDK - disablePurpose ignored due to invalid purpose: invalid_ID'
// ok === true

CurrentUserStatusTransaction (Methods)

Method
Parameters
Returns
Description

enablePurpose

id: string

CurrentUserStatusTransaction

Enable a single purpose by ID.

enablePurposes

ids: string[]

CurrentUserStatusTransaction

Enable multiple purposes by ID.

disablePurpose

id: string

CurrentUserStatusTransaction

Disable a single purpose by ID.

disablePurposes

ids: string[]

CurrentUserStatusTransaction

Disable multiple purposes by ID.

enableVendor

id: string

CurrentUserStatusTransaction

Enable a single vendor by Didomi ID.

enableVendors

ids: string[]

CurrentUserStatusTransaction

Enable multiple vendors by Didomi ID.

disableVendor

id: string

CurrentUserStatusTransaction

Disable a single vendor by Didomi ID.

disableVendors

ids: string[]

CurrentUserStatusTransaction

Disable multiple vendors by Didomi ID.

commit

—

Promise<boolean>

Apply all staged changes. Returns true if the user status was updated, false otherwise.

Types

Add these to the Types section for completeness:

export interface CurrentUserStatusTransaction {
  enablePurpose: (id: string) => CurrentUserStatusTransaction;
  enablePurposes: (ids: string[]) => CurrentUserStatusTransaction;
  disablePurpose: (id: string) => CurrentUserStatusTransaction;
  disablePurposes: (ids: string[]) => CurrentUserStatusTransaction;
  enableVendor: (id: string) => CurrentUserStatusTransaction;
  enableVendors: (ids: string[]) => CurrentUserStatusTransaction;
  disableVendor: (id: string) => CurrentUserStatusTransaction;
  disableVendors: (ids: string[]) => CurrentUserStatusTransaction;
  commit: () => Promise<boolean>;
}

And add the method to your API surface:

export interface DidomiSDKAPI {
  // ...
  openCurrentUserStatusTransaction: () => CurrentUserStatusTransaction;
  // ...
}

reset

Clear locally stored consent data and re-evaluate.

Signature

didomi.reset(): Promise<void>

Parameters

  • None

Returns

  • Promise<void>

Example

await didomiRef.current?.reset();

shouldUserStatusBeCollected

Whether the app should prompt for consent (e.g., user is in-scope, no valid status yet).

Signature

didomi.shouldUserStatusBeCollected(): Promise<boolean>

Parameters

  • None

Returns

  • Promise<boolean>

Example

if (await didomiRef.current?.shouldUserStatusBeCollected()) {
  didomiRef.current?.notice.show();
}

syncUser

Update the local user status from the Didomi servers in a single-page application.

If your site is not an SPA, do not call this method directly — syncing is automatically performed when window.didomiConfig.user is set on page load.

Synchronization will only run if:

  • Sync is enabled in the configuration,

  • An organizationUserId is provided,

  • The user is not a bot, and

  • The sync frequency has not been exceeded.

Signature

didomi.syncUser(): Promise<SyncReadyEvent>

Parameters

  • None

Returns

  • Promise<SyncReadyEvent> — An object describing the result of the sync.

SyncReadyEvent

Property
Type
Description

statusApplied

boolean

true if the local user status was updated from the server, false otherwise.

syncAcknowledged

() => Promise<boolean>

Call this to confirm to Didomi that the synchronized status has been communicated to the user. Returns true if the acknowledgment event was sent successfully, false otherwise.

syncError

string | undefined

Error message if the sync failed.

Examples

Simple sync

await didomiRef.current!.syncUser();

Reassurance notice flow

const syncResult = await didomiRef.current!.syncUser();

if (syncResult.statusApplied) {
  // The user status actually changed from syncing

  // Show your reassurance notice to the user

  // Report that the reassurance notice has been shown
  const acknowledged = await syncResult.syncAcknowledged();
  console.log('Sync acknowledged:', acknowledged);
}

Notes

  • Use syncUser() only when you need to refresh consent state in an SPA.

  • Always check statusApplied — if it’s false, the local state is already up to date.

  • If you show any UI reassurance (e.g., “Your preferences are updated”), remember to call syncAcknowledged().

setUser

Update the user configuration details in a single-page application. In multi-page apps, do not call this method directly. Instead, set the user configuration details via window.didomiConfig.user on page load.

The function updates all the provided properties and sets any omitted properties to undefined.

Signature

didomi.setUser(userConfiguration: UserConfiguration): Promise<void>

Parameters

Name
Type
Description

organizationUserId

string

Organization User ID to associate with the user.

organizationUserIdAuthAlgorithm

string

Algorithm used for computing the digest.

organizationUserIdAuthSid

string

ID of the secret used for computing the digest.

organizationUserIdAuthSalt

string

Salt used for computing the digest.

organizationUserIdAuthDigest

string

Digest of the organization user ID and secret.

organizationUserIdExp

number

Unix timestamp (expiration).

organizationUserIdIv

string

Initialization vector if encryption was used for the digest.

Returns

  • Promise<void>

Example

await didomiRef.current?.setUser({
  organizationUserId: 'organizationUserID',
  organizationUserIdAuthAlgorithm: 'HS256',
  organizationUserIdAuthSid: 'sid_123',
  organizationUserIdAuthSalt: 'random_salt',
  organizationUserIdAuthDigest: 'abcdef123456',
  organizationUserIdExp: 1699999999,
  organizationUserIdIv: 'iv_string'
});

Notes

  • Call setUser only once per session unless you explicitly need to update the user identity.

  • If you pass only a subset of fields, any omitted ones will be reset to undefined.

  • Always ensure the digest values (if used) are generated securely on your backend.

clearUser

Disassociate any user identifier from the current session.

Signature

didomi.clearUser(): Promise<void>

Parameters

  • None

Returns

  • Promise<void>

Example

await didomiRef.current?.clearUser();

Notice Config

These helpers expose details about the loaded notice/config.

Depending on your Vega integration, some fields may be undefined until onReady.

Types

Below are the key TypeScript interfaces surfaced by the SDK.

type DidomiEvent =
  | 'sdk.ready'
  | 'sdk.error'
  | 'notice.shown'
  | 'notice.hidden'
  | 'preferences.shown'
  | 'preferences.hidden'
  | 'preferences.saved'
  | 'consent.changed';

interface Vendor {
  id: string;
  name?: string;
  policyUrl?: string;
  purposeIds?: string[];
  [key: string]: unknown;
}

interface Purpose {
  id: string;
  name?: string;
  description?: string;
  [key: string]: unknown;
}

interface UserStatus {
  purposes: Record<string, 'granted' | 'denied'>;
  vendors: Record<string, 'granted' | 'denied'>;
  regulation?: 'gdpr' | 'cpra' | 'none' | string;
  updatedAt?: string;
}
PreviousSetupNextEvents

Last updated