Didomi Vega SDK

A Vega SDK for integrating Didomi's Consent Management Platform (CMP) with Amazon's Vega platform. This SDK enables applications to manage user consent for data collection and processing in compliance with privacy regulations.

Features

• Display consent notices and preference dialogs
• Collect and manage user consent choices
• Synchronize consent data with Didomi servers
• Support for various privacy regulations (GDPR, CCPA, etc.)
• Comprehensive event handling for user interactions

Installation

npm install @didomi/vega-sdk

Peer Dependencies

This SDK has the following peer dependencies:

• React (>=18.0.0 <=18.2.0)
• React DOM (>=18.0.0 <=18.2.0)
• React Native (^0.72.0)
• @amazon-devices/react-native-vega (^2.0.0)
• @amazon-devices/webview

For WebView: Update your app's manifest.toml file to include required services

Usage

Basic Integration

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

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

  return (
    <DidomiSDK
      noticeId="YOUR_NOTICE_ID"
      didomiPublicApiKey="YOUR_PUBLIC_API_KEY"
      ref={didomiRef}
      onReady={() => console.log('Didomi SDK is ready')}
      onConsentChanged={(consent) => console.log('Consent changed:', consent)}
    >
      {/* Your application content */}
      <YourApp />
    </DidomiSDK>
  );
};

Programmatically Interacting with the SDK

After integrating the SDK, you can programmatically access its functionality through the ref:

// All SDK methods are accessible through the ref
const didomiSDK = didomiRef.current;

// Display UI elements
didomiSDK?.notice.show(); // Show consent notice
didomiSDK?.preferences.show('purposes'); // Show preferences UI

// Query SDK state
const isConsentRequired = await didomiSDK?.isConsentRequired();

// Manage user consent
const userStatus = await didomiSDK?.getCurrentUserStatus();
await didomiSDK?.setUserAgreeToAll();
await didomiSDK?.setCurrentUserStatus({
  purposes: {
    /* purpose status */
  },
  vendors: {
    /* vendor status */
  },
});

API Reference

Component Props

The DidomiSDK accepts the following required props:

Methods

The SDK exposes methods through a ref:

Promise-returning methods reject with an Error when the bridge or Web SDK call fails, when no response arrives within 30 seconds, or when the WebView reloads, fails, is reconfigured, or unmounts. Handle these rejections with try/catch.

Dependent-resource load events and errors do not cancel unrelated SDK calls. For Vega load events without frame metadata, cancellation requires a URL matching the configured page or the document identified by didomi.ready. Events with unknown URLs rely on the request timeout. WebView errors are still forwarded to onError.

syncUser() waits for the Web SDK synchronization to finish and preserves its statusApplied and syncError values. Its syncAcknowledged() callback belongs to that specific result and returns the underlying Web SDK callback's boolean result. Each attempt is forwarded independently, including retries after errors; the Web SDK handles duplicate events and normally returns false after the first acknowledgement. This boolean does not confirm HTTP delivery: the Web SDK sends the event asynchronously.

Results with statusApplied: false retain no WebView callback and their acknowledgement returns false. Each WebView retains at most 100 completed results that applied a status, evicting the oldest retained sync calls when that limit is reached. Acknowledging an evicted result, or one from a previous WebView page after a reload or reconfiguration, rejects with an Error.

Consent Management

User Status

User Configuration

Consent Checking

Events

The SDK provides callbacks for various events:

Ready Events

Consent Events

UI Events

User Interaction Events

Error Events

The DidomiError payload is a discriminated union on the source field:

type DidomiError =
  | { source: 'api'; id?: string; reason?: string }
  | {
      source: 'webview';
      code?: number;
      description?: string;
      nativeEvent?: unknown;
    };

• source: 'api' — forwarded from the Didomi Web SDK api.error event (HTTP failures while sending consents, events, metrics, etc.). id identifies the failed request, reason is one of request.failure or response.error.
• source: 'webview' — emitted by the underlying WebView for load/runtime errors.

Implementation Example

Below is a simplified example showing how to implement the SDK and access its functionality:

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

function App() {
  // Create ref to access SDK methods
  const didomiRef = useRef<DidomiSDKAPI>(null);

  // Example of event handling
  const handleReady = () => {
    // SDK is ready, you can now call methods
    console.log('SDK is ready');
  };

  // Example of handling consent changes
  const handleConsentChanged = (consent) => {
    console.log('Consent changed', consent);
    // Update application state or perform actions based on consent
  };

  return (
    <DidomiSDK
      noticeId="YOUR_NOTICE_ID"
      didomiPublicApiKey="YOUR_PUBLIC_API_KEY"
      ref={didomiRef}
      onReady={handleReady}
      onConsentChanged={handleConsentChanged}
    >
      <View>{/* Your application UI */}</View>
    </DidomiSDK>
  );
}

export default App;

License

Copyright © Didomi. All rights reserved.