Skip to main content

Decipher Toolbox Integration

This guide will walk you through integrating the DQCToolBox with Decipher Platform Surveys.

📌 Steps to Integrate DQC Toolbox with Decipher​

Step 1: Api Key​

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

Step 2: Edit the Survey XML​

  1. Navigate to your Decipher Portal:
    👉 Open Decipher Portal
  2. Select your survey.
  3. Go to the navigation bar and click:
    Build → More Tools → Edit XML

Step 2.1: Add Code to execute the Quality Tools on the survey​

Insert the following code after the <survey> tag:

  • Make sure to replace DQC_API_KEY with your actual API key.
  • This code includes the toolbox initialization, exec blocks, and data holder all in one place.
  • This is the concise integration with only the minimum recommended fields. Additional fields are available if needed in full examples.
<style name="global.page.head" wrap="ready"><![CDATA[
(async () => {
  try {
    const { DQCToolBox } = await import('https://api.dqco-op.com/tools/toolbox/DQC_API_KEY');
    await DQCToolBox.getIdentity();
  } catch (error) {
    console.error('Error in client code:', error);
  }
})();
]]></style>
<suspend/>

<exec when="init">
defaultAnswer = 'Submission too quick, data not processed'
defaultSurveyMetricsAnswer = 'No Data'
def save_dqc_data():
    defaultDeviceFailuresAnswer = 'None' if getattr(p, 'client_dqc_participant_id', '') else defaultAnswer
    dqc_data.rid.val = getattr(p, 'client_dqc_request_id', '') or defaultAnswer
    dqc_data.pid.val = getattr(p, 'client_dqc_participant_id', '') or defaultAnswer
    dqc_data.per.val = getattr(p, 'client_dqc_persona', '') or 'NONE'
    dqc_data.dts.val = getattr(p, 'client_dqc_data_trust_score', '') or '0'
    dqc_data.dcs.val = getattr(p, 'client_dqc_device_score', '') or '0'
    dqc_data.cty.val = getattr(p, 'client_dqc_country_code', '') or defaultAnswer
    dqc_data.sub.val = getattr(p, 'client_dqc_subdivision_name', '') or defaultAnswer
    dqc_data.dup.val = getattr(p, 'client_dqc_is_duplicate', False)
    dqc_data.sid.val = getattr(p, 'client_dqc_survey_id', '') or defaultAnswer
    dqc_data.dfc.val = getattr(p, 'client_dqc_device_failures', '') or defaultDeviceFailuresAnswer
</exec>

<exec when="submit">
  save_dqc_data()
</exec>

<text
  cond="0"
  label="dqc_data"
  optional="0"
  size="10"
  translateable="0"
  where="execute,survey,report">
  <title>DQC Data Holder</title>
  <row label="rid">dqc-request-id</row>
  <row label="pid">dqc-participant-id</row>
  <row label="dts">dqc-data-trust-score</row>
  <row label="per">dqc-persona</row>
  <row label="dcs">dqc-device-score</row>
  <row label="dup">dqc-is-duplicate</row>
  <row label="cty">dqc-country</row>
  <row label="sub">dqc-subdivision</row>
  <row label="sid">dqc-survey-id</row>
  <row label="dfc">dqc-device-failures</row>
</text>

<suspend/>

Step 2.2: Optional Configuration Parameters​

Step 2.2.1: Custom surveyId (optional - recommended)​

You can add a custom surveyId to the script. This is useful if you want to track responses from different surveys. If you leave it empty, the system will use the current URL (hostname+pathname) as the surveyId. This is the default behavior.

await DQCToolBox.getIdentity('Your_Custom_Survey_Id');

The Your_Custom_Survey_Id parameter should be added within the <style name="global.page.head" wrap="ready"> section of your XML, specifically in the JavaScript code that calls DQCToolBox.getIdentity().

tip

💡 Pro Tip: Use different survey IDs for testing vs live surveys (e.g., 'Brand Study 2026 Testing' during testing, then change to 'Brand Study 2026' before going live). This helps separate test data from actual survey responses.

These survey IDs appear in the DQCO-OP dashboard and make it simple to filter and analyze survey-level results. For each survey ID you can view key metrics such as the average, lowest, and highest device score, the duplication rate, and common device failures (for example: Bot Detection, Timezone Mismatch, Incognito Mode, Proxy/VPN usage, etc.).

Quality Tools Dashboard - Survey ID View

Figure: Quality Tools — Survey ID view in the DQCO-OP dashboard.

Step 2.2.2: Decipher UUID (optional)​

The surveyId and uuid parameters can be used independently or together. Both are optional.

Decipher provides a custom UUID to enable session-based duplicate detection. This allows participants to resume surveys while maintaining their original isDuplicate status across different browser sessions.

How it works:

  • When a participant is not flagged as a duplicate (isDuplicate=false), their UUID is stored in the system.
  • On subsequent requests with the same UUID, the system recognizes them as returning to their original session and maintains isDuplicate=false.
  • If a different UUID is provided, the participant is treated as a new session and may be flagged as a duplicate based on standard duplicate detection logic.

This is particularly useful for scenarios where participants need to resume a survey while preserving their original duplicate status.

Usage:

await DQCToolBox.getIdentity({
  surveyId: 'Your_Custom_Survey_Id', // Use your custom survey ID here
  uuid: `${uuid}` // Don't modify this line -  this is how decipher provides the UUID
});

Or with only a UUID:

await DQCToolBox.getIdentity({
  uuid: `${uuid}` // Don't modify this line -  this is how decipher provides the UUID
});

The uuid parameter (optionally together with surveyId) should be added inside the <style name="global.page.head" wrap="ready"> section of your XML, specifically by replacing the DQCToolBox.getIdentity() call in the JavaScript code with your updated version that includes the uuid parameter.

note

For most Decipher/Forsta users, setting a custom UUID is not required—the default behavior is suitable for typical use cases. Only configure the UUID if you have a specific need for session-based duplicate detection. Incorrect use of this option may result in inaccurate duplicate detection. Please contact DQC support if you have questions about this feature.

Full XML Survey Example​

Here is a complete example of the final XML, following all the steps above.

Note: the DQC_API_KEY shown is not valid—you will need to generate your own.

View Complete XML Example
<?xml version="1.0" encoding="UTF-8"?>
<survey
  alt="Quality Tools Integration - Testing"
  autosave="0"
  builder:wizardCompleted="1"
  builderCompatible="1"
  compat="154"
  delphi="1"
  extraVariables="source,record,decLang,list,userAgent"
  fir="on"
  html:showNumber="0"
  mobile="compat"
  mobileDevices="smartphone,tablet,desktop"
  name="Survey"
  secure="1"
  setup="term,decLang,time"
  ss:disableBackButton="1"
  ss:enableNavigation="1"
  ss:hideProgressBar="0"
  state="testing">

<style name="global.page.head" wrap="ready"><![CDATA[
(async () => {
  try {
    const { DQCToolBox } = await import('https://api.dqco-op.com/tools/toolbox/DQC_API_KEY');
    await DQCToolBox.getIdentity();
  } catch (error) {
    console.error('Error in client code:', error);
  }
})();
]]></style>
<suspend/>

<exec when="init">
defaultAnswer = 'Submission too quick, data not processed'
defaultSurveyMetricsAnswer = 'No Data'
def save_dqc_data():
    defaultDeviceFailuresAnswer = 'None' if getattr(p, 'client_dqc_participant_id', '') else defaultAnswer
    dqc_data.rid.val = getattr(p, 'client_dqc_request_id', '') or defaultAnswer
    dqc_data.pid.val = getattr(p, 'client_dqc_participant_id', '') or defaultAnswer
    dqc_data.per.val = getattr(p, 'client_dqc_persona', '') or 'NONE'
    dqc_data.dts.val = getattr(p, 'client_dqc_data_trust_score', '') or '0'
    dqc_data.dcs.val = getattr(p, 'client_dqc_device_score', '') or '0'
    dqc_data.cty.val = getattr(p, 'client_dqc_country_code', '') or defaultAnswer
    dqc_data.sub.val = getattr(p, 'client_dqc_subdivision_name', '') or defaultAnswer
    dqc_data.dup.val = getattr(p, 'client_dqc_is_duplicate', False)
    dqc_data.sid.val = getattr(p, 'client_dqc_survey_id', '') or defaultAnswer
    dqc_data.dfc.val = getattr(p, 'client_dqc_device_failures', '') or defaultDeviceFailuresAnswer
</exec>

<exec when="submit">
  save_dqc_data()
</exec>

<text
  cond="0"
  label="dqc_data"
  optional="0"
  size="10"
  translateable="0"
  where="execute,survey,report">
  <title>DQC Data Holder</title>
  <row label="rid">dqc-request-id</row>
  <row label="pid">dqc-participant-id</row>
  <row label="dts">dqc-data-trust-score</row>
  <row label="per">dqc-persona</row>
  <row label="dcs">dqc-device-score</row>
  <row label="dup">dqc-is-duplicate</row>
  <row label="cty">dqc-country</row>
  <row label="sub">dqc-subdivision</row>
  <row label="sid">dqc-survey-id</row>
  <row label="dfc">dqc-device-failures</row>
</text>

<suspend/>

<radio
  label="Q1">
  <title>Q1: Are you human?</title>
  <comment>Select one</comment>
  <row label="r1">Yes</row>
  <row label="r2">No</row>
</radio>

<suspend/>

<radio
  label="Q2">
  <title>Q2: Are you a duplicate?</title>
  <comment>Select one</comment>
  <row label="r1">Yes</row>
  <row label="r2">No</row>
</radio>

<suspend/>

<radio
  label="Q3">
  <title>Q3: You made it to the end of the example survey</title>
  <comment>Select one</comment>
  <row label="r1">Yay</row>
  <row label="r2">Bummer</row>
</radio>

<suspend/>


</survey>

Viewing Quality Tools Data in Your Survey Responses​

On your survey, go to the navigation bar and click:

  • RESPONSES → VIEW/EDIT RESPONSES

The data collected by the DQCToolBox will be stored in the dqc_data columns.

You can access this data in your survey responses by clicking on the Choose Columns and add the dqc_data Survey Variable (columns) to view your responses.

Decipher Responses

✅ Summary​

  • Include the initial DQC script after the <survey> tag.
  • Change the DQC_API_KEY in the script to your own.
  • Confirm success by checking that the data is stored in the dqc_data columns.