Skip to main content

Nextjs Toolbox Integration

This guide will walk you through integrating the DQCToolBox with Nextjs websites.

Prerequisites​

Before starting, ensure you have:

  • A Nextjs project set up (typescript or javascript).

📌 Steps to Integrate DQC Toolbox with Next.js​

Step 1: API Key​

Make sure you have your API key from the DQCO-OP platform. If you don't have one, follow these steps to get your API key.

Step 2: Create the DQC Toolbox Service​

Create a new file DQCToolbox.js or DQCToolbox.ts inside the services folder:

DQCToolbox.ts
"use client";

const DQC_API_KEY = "YOUR_DQC_API_KEY_HERE";  // Replace manually with your API key from step 1
const DQC_ENDPOINT = "https://api.dqco-op.com/tools/toolbox";

export type IdentityDataDQCType = {
  participantId: string;
  deviceScore: number;
  country: string;
  subdivision: string;
  isDuplicate: boolean;
  surveyId: string;
  averageDeviceScore: number;
  lowestDeviceScore: number;
  totalSurveys: number;
  deviceFailures: string[];
};

/**
 * Retrieves identity data using the DQCToolBox.
 *
 * @param {string} surveyId - If no surveyId is provided, the URL (hostname+pathname) will be used.
 * @returns {Promise<IdentityDataDQCType|null>} The Data Quality identity data {participantId, deviceScore, country, subdivision, isDuplicate, surveyId, averageDeviceScore, lowestDeviceScore, totalSurveys, deviceFailures}.
 * @throws {Error} If surveyId is not a string or if an error occurs while loading DQCToolBox.
 */
export async function getIdentity(surveyId:string = "") : Promise<IdentityDataDQCType|null> {
  if (typeof window === "undefined") {
    throw new Error("getIdentity() must run on the client side");
  }

  if (typeof surveyId !== "string") {
    throw new Error("Survey ID must be a string");
  }

  if (!DQC_ENDPOINT || !DQC_API_KEY) {
    throw new Error("DQC_ENDPOINT and DQC_API_KEY must be defined");
  }

  try {
    const { DQCToolBox } = await import( /* webpackIgnore: true */ `${DQC_ENDPOINT}/${DQC_API_KEY}`);

    if (!DQCToolBox || typeof DQCToolBox.getIdentity !== "function") {
      throw new Error("DQCToolBox module not loaded correctly");
    }

    const identityData = await DQCToolBox.getIdentity(surveyId);
    return identityData;
  } catch (err) {
    console.error("Toolbox Integration Service error:", err);
    return null;
  }
}

Step 3: Create the Quality Tools Component​

Create a new component in your Nextjs project to handle the interaction with the DQC Toolbox.

Create a new file ToolboxSample.jsx or ToolboxSample.tsx inside the components folder:

ToolboxSample.tsx
'use client';
import { useState } from 'react';
import { getIdentity, IdentityDataDQCType } from '../services/DQCToolbox';

const ToolboxSample = () => {
  const [data, setData] = useState<IdentityDataDQCType|null>(null);
  const [loading, setLoading] = useState(false);

  const handleRunQualityTools = async () => {
    setLoading(true);
    setData(null);

    try {
      console.log("Calling DQC Toolbox...");
      const result = await getIdentity();
      setData(result);
      // NOTE: You can save the result to your database or use it for further analysis.
      console.log("Result:", result);
    } catch (err) {
        console.error("Error calling DQC Toolbox:", err);
    }

    setLoading(false);
  };

  return (
    <div>
      <h3>🔍 Quality Tools Response Payload</h3>

      <button onClick={handleRunQualityTools} disabled={loading}>
        {loading ? "⏳ Running..." : "🚀 Run Quality Tools on my browser"}
      </button>


      {data && JSON.stringify(data, null, 2)}
    </div>
  );
}

export default ToolboxSample;


Step 4: Integrate the service/components in Your App​

  • Now, modify your App.js file or any page where you want to use the toolbox.
  • It's up to you to decide where to place the component in your app or just use the service to save the data to your database inside an existing component.
import ToolboxSample from '@/components/ToolboxSample';

export default function Home() {
  return (
    <main>
      <ToolboxSample />
    </main>
  );
}

Step 5: Run Your Application​

Now, start your Nextjs app:

npm run dev

Open your browser and visit http://localhost:3000 to test the integration.

Step 6: Verify the Integration​

Click "Run Quality Tools on my browser" button.

note

The result should appear below as a formatted JSON payload.
If there's an error, check your console and confirm the API key and endpoint

It should work as the following example:

Step 7: Save the results​

You can now save the results to your database for further analysis or use them for real time decision taking.