How to Embed the Discovery SDK: A Step-by-Step Guide

This guide provides detailed instructions for embedding the Discovery SDK into your website, including the requirements, setup process, and user flow to ensure a seamless integration.

Overview of the Discovery SDK

The Discovery SDK is an embeddable <iframe> tag, compatible with HTML-based applications, such as those built in Angular, React, Vue.js, Svelte, or Solid.js. It requires minimal configuration; once key information is securely provided, the SDK is ready for use.

What You’ll Need:

1. Iframe Configuration: Provided in this article (see below)

2. A Key Vault for Secure Storage: The SDK needs secure, private Account Details associated with your account to be stored on your end. These Account Details should be stored in a key vault on your end to ensure account security. The details you will need to secure include:

   • accountId: Obtain this from your DNA Web App settings page.

   • Encryption Key: Create a ticket and request your encryption key.

   • Subscription Key (DNA API Key): Available in the DNA Developer Portal. Click here for instructions.
   • Self-Registration Details: Log into your DNA Web App account, select the desired self-registration process for your embedded discovery, and copy the corresponding link.
     
     • Note your selfRegistrationId from your account.
     • Format of URL:
       https://discovery.dnabehavior.com/investor/Demo/{accountId}/{selfRegistrationId}

Encrypting the Subscription Key

To encrypt your subscription key, use the jsencrypt package:
Package Link: jsencrypt

const publicKey = environment.publicKey;
const encryption = new JSEncrypt();
encryption.setPublicKey(publicKey);
const encryptedKey = encryption.encrypt(environment.SubscriptionKey); 

Iframe Configuration:

The Discovery SDK is embedded as an <iframe>  tag within your HTML document. This is similar to embedding any other iframe-based element with additional required parameters for configuration.

Embedding Format:

Use the following structure to embed the SDK in your HTML document, replacing placeholder values (highlighted in bold) with actual data:

<iframe src="https://embeddiscovery.dnabehavior.com/?accountId={accountId}
&selfRegistrationId={self_registration_id}
&questionPattern={questionPattern}
&firstname={firstname}
&lastname={lastname}
&email={email}"
height="1080px"
width="1920px">
</iframe>

Parse the following code when loading the iframe:

this.iframe.nativeElement.onload = () => {
  const encryptedKey = 'YOUR_ENCRYPTED_KEY';
  const messageTarget = 'https://embeddiscovery.dnabehavior.com/'; //Discovery SDK baseUrl
  this.iframe.nativeElement.contentWindow?.postMessage(
    encryptedKey,
    messageTarget
  );
};

• subscriptionKey: The encrypted DNA API key for your account, accessible in the Developer Portal.
• accountId: Your unique account identifier.
• questionPattern: Choose one from the options: 11, 17, or 46.
• selfRegistrationId: Used for self-registration processes.
• firstname & lastname: Required to personalize the questionnaire experience.
• email: Identifies the individual user and ensures a consistent experience.

Using the SDK

Flow and User Experience

1. Initialize SDK: When users access the iframe, the SDK will automatically check that all required parameters are present. Missing parameters will result in an error screen.
2. Instructions Screen: Users will first see an instructions page with guidelines for completing the questionnaire. They must acknowledge these instructions to continue.
3. Questionnaire Completion: Users complete the questionnaire, which takes them through a series of questions.
4. Data Processing: Once completed, the system makes API calls to calculate user scores.
5. Dashboard and Insights: After scoring, users are redirected to a dashboard where they can view their results and insights.

Customizing the Results Screen with Your Own UI

To display a custom UI for the results screen after the questionnaire is completed, simply listen for the event sent by the SDK. When the screenChanged event is detected with the value dashboard, this indicates the completion of the questionnaire. You can then transition to your own UI for the results screen, providing complete control over the design and flow of the post-questionnaire experience.

Embedded Discovery SDK Process Flow Chart

Multi-Language Support:

The SDK includes multi-language options, which allow users to change languages according to their preferences. An Instructions button in the header is accessible at any time for guidance on the questionnaire process.

The supported languages are:

• • Afrikaans
  • Dutch (Netherlands)
  • English (UK)
  • English (US)
  • French (Canadian)
  • French (France)
  • German
  • Hindi
  • Mandarin Chinese
  • Portuguese (Brazil)
  • Portuguese (Portugal)
  • Spanish (Mexico)
  • Spanish (Spain)
  • Urdu (Pakistan)

Multiple Account Access:

Each account in the DNA Web App has its own secure DNA API Key. If your organization leverages multiple accounts, each will require its own set of records in your Key Vault. Additionally, you will need to develop the internal logic to feed this information to the iframe parameters.

Webhook Notifications: Real-Time Data Integration

Need a way to get notified when a client completes their profile through the SDK? With the DNA API's webhook functionality, you can set up real-time notifications that integrate directly with your system. Here’s how you can get started:

Step 1: Register Your Webhook URL

To start receiving notifications, you first need to register your webhook URL to your Account ID. Follow these steps:

1. Log in to the Developer Portal
   • Visit the DNA Behavior Developer Portal and log in with your Web App account.
   • After logging in, navigate to the Public API section.
   • Search for the RegisterWebhookURL API.
2. Registering Your Webhook
   • Account ID and Webhook URL: Enter your Account ID and the Webhook URL where you want to receive notifications.
   • Make sure you set the status as True to activate the webhook.

API Request Example:

{
    "accountId": 1234,
    "webhookURL": "https://yourdomain.com/webhook",
    "status": true
}

Once the registration is successful, you’ll receive a confirmation with a 200 OK status, indicating that your webhook is active and set up.

Successful Registration Response:

{
    "message": "Webhook registered successfully.",
    "statusCode": 200
}

Step 2: Receive Profile Completion Data

Once your webhook is set up, you’ll start receiving notifications in real time when a user completes their profile. The data will be sent as a JSON payload containing key information such as:

1. PersonID
2. CreditID
3. UserName
4. AccountID
5. AssignedNameUser
6. Tags
7. DiscoveryType
8. DiscoveryCompletionDate

Sample Data Payload:

{
    "PersonID": 12345,
    "CreditID": 67890,
    "UserName": "john_doe",
    "AccountID": 1234,
    "AssignedNameUser": "John Doe",
    "Tag": [
        {
            "TagID": 1,
            "TagName": "VIP"
        }
    ],
    "FirstName": "John",
    "LastName": "Doe",
    "FullName": "John Doe",
    "DiscoveryType": 11,
    "DiscoveryCompletionDate": "2025-01-23T10:30:00"
}

Step 3: Retrieve Your Webhook URL (If Needed)

If you ever need to retrieve or verify your registered webhook URL, you can do so using the GetWebhookURLByAccountID API. Simply provide your Account ID in the request.

API Request Example:

GET https://api.dnabehavior.com/prod-public-api/Accounts/GetWebhookURLByAccountId/{AccountId}

Successful Response Example:

{
    "message": "Webhook URL retrieved successfully.",
    "data": {
        "accountId": 1234,
        "webhookURL": "https://yourdomain.com/webhook",
        "status": true
    },
    "statusCode": 200
}

Step 4: Update or Overwrite Your Webhook URL

If you need to update or overwrite the existing webhook URL, simply re-register the new URL using the RegisterWebhookURL API. You can then verify the update with the GetWebhookURLByAccountID API.

By following these steps, you can easily integrate webhook notifications into your system and receive real-time updates when a profile is completed. This ensures that you have the most up-to-date data at all times.

Still Need Help?

Submit a ticket here.