Integrations
      Back to home
      1. Help Center
      2. App Guide
      3. Integrations

      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.

       

      The following is a preview of the documentation for the Embedded Discovery SDK. This feature will be generally available in January 2025.

      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.

      See an Example:

      An example of the Discovery SDK in action is hosted on our DNA Labs website. Imagine this same technology embedded in your platform.
      Access the Example: DNA Labs Discovery SDK Example

      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:

        • 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. The Self-Registration ID and Account ID are included.
          • Note your accountId and selfRegistrationId
          • Format of URL:
            https://discovery.dnabehavior.com/investor/Demo/{accountId}/{selfRegistrationId}

      Note on Key Vaults: Store these keys securely using services like AWS, Azure, or environment files. Never expose or commit them to public repositories like GitHub.

      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 with actual data:

      <iframe src="https://{domain}?subscriptionKey={encryptedKey}  
      &accountId={account_id}  
      &selfRegistrationId={self_registration_id}  
      &firstname={firstname}  
      &lastname={lastname}  
      &email={email}"  
      height="1080px"  
      width="1920px">  
      </iframe>       

      Tip: Customize the height and width attributes in the <iframe> to control display dimensions and ensure mobile responsiveness.
      The SDK iframe is mobile-responsive. Adjust the iframe’s height and width attributes to ensure proper display across devices.

       
      Required Parameters:
      • subscriptionKey: The encrypted DNA API key for your account, accessible in the Developer Portal.
      • accountId: Identifies your organization in the SDK.
      • selfRegistrationId: Used for self-registration processes.
      • firstname & lastname: Required to personalize the questionnaire experience.
      • email: Identifies the individual user and ensures a consistent experience.

      Note: If you wish to anonymize the client’s email you may do so, however, each email address in the DNA Platform must be unique.

      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.

      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.

      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.

      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);       
      The public key is used to encrypt the subscription key. You have two options for handling this key: you can either replace it with the encryption key that we provide or reference it directly from an environment file for better security and manageability. Referencing from an environment file is recommended, as it keeps sensitive information separate from your code, reducing the risk of exposure.
       

      Note: Store the subscription key in an environment file. Never hard-code it into your codebase.

      Enhanced User Experience Features

      1. Automatic Progress Tracking:
        If a user exits the questionnaire before completion, the SDK automatically saves their progress. When they return and login, they are redirected to the last question they answered, ensuring a smooth and uninterrupted experience.

      2. Direct Results Dashboard Access:
        Once a user completes the questionnaire, any subsequent login will bypass the questionnaire and redirect them directly to their results dashboard. This allows users to efficiently review their insights without needing to retake the questionnaire.

      Upcoming Feature: Webhook Notifications

      How Will You Know When a New Profile Has Been Completed?

      Our development team is currently building a webhook that will automatically notify your system when:

      • A participant completes a questionnaire.
      • A digital scan is completed.

      This webhook will trigger a notification, allowing you to store the completion data in your database for tracking and reporting purposes.