Skip to main content

React Toolbox Integration

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

Prerequisites​

Before starting, ensure you have:

  • A React project set up (TypeScript or JavaScript).

📌 Steps to Integrate DQC Toolbox with React​

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
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 React project to handle the interaction with the DQC Toolbox.

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

ToolboxSample.tsx
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 to use the service to save the data to your database inside an existing component.
import logo from './logo.svg';
import './App.css';
import ToolboxSample from './components/ToolboxSample';

function App() {
  return (
    <div className='App'>
      <header className='App-header'>
        <ToolboxSample />
        <img src={logo} className='App-logo' alt='logo' />
      </header>
    </div>
  );
}

export default App;

Step 5: Run Your Application​

Now, start your React app:

npm run dev

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

Step 6: Verify the Integration​

Click the "Run Quality Tools on my browser" button.

note

The result should appear below as a formatted JSON payload.
If there is 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-making.