Skip to main content

FV Decipher Support

All the topics, resources needed for FV Decipher.

FocusVision Knowledge Base

TrueSample Best Practices and Implementation Guide

These steps may be used if your company has obtained direct service with TrueSample, and have received your own login and account ID. Decipher also offers this service. Contact your account manager for more information.

1:  What is True Sample?

True Sample is a verification process to validate the person taking the survey as being who they say they are, in essence they are a real person. Each person that has been validated by TRUE SAMPLE (i.e., "TS") will be given a TRUE SAMPLE ID (TS ID). This is what is passed in the URL and verified against the TS database.

TrueSample is able to de-dupe across different panels. The TrueSample ID assigned to a person is unique and can be easily identified if the person belongs to multiple panels.

1.1:  Verification

Respondent verification can be done in two ways:

  • Pre verification:  Most panel companies will already have a percentage of their panel set up as True Sample verified and they will pass in that TS ID to us.

  • Real time verification:  For those being passed into the survey without a TS ID, they will go through what is called the real time verification process. This happens as they enter the survey, anyone that comes in without a TS ID can be directed to a set of qualification questions (personal address, phone number etc.) that is then verified with TS. If verified, they continue into the survey and will be assigned a TS ID that can be obtained on the TS site (discussed below).

1.2:  Available Countries

Currently for Decipher, TS has the following countries set up in their system:

  • United States
  • United Kingdom
  • Germany
  • Canada
  • France

If you need another country added, your contact at TS can set up a global contract that will include other countries that may be needed.

1.3:  TrueSample Login

In order to proceed with the steps below, you must already have direct service with TrueSample, and have your own account and ID with them. This information may be obtained from your contact at TrueSample.

Decipher also offers this service, and we will handle the project setup for you. Contact your account manager at Decipher for more information.

2:  Project Setup    

These steps must be done by the client before the back-end setup can start.

2.1:  Standard Panel Redirects

Panel companies will provide the redirects as with other panel projects.

2.2:  providerID = Source ID (Provider ID for True Sample)

You will need a providerID for each provider hitting the Decipher system. These can be found by logging into true sample platform (https://www.truesample.com) and searching on the "Identification Codes" tab.  Please contact support@truesample.com if you are not sure about which code to use.

The provider ID is usually an 8 digit number that has been assigned by TS.

These ID’s will need to be programmed into the survey (discussed in the programming section), each provider on the study will need to have their own provider ID as they will be passed in the URL.

2.3:  Validation Settings

What Validation settings does the client want? We will need this information in order for the programmers to set it up properly.

  • Real:  Verification of TrueSample ID passed in.  If the ID is missing or invalid it can validate their address (verified through a third party validation partner)
  • Unique:  Checks for duplicate respondents across the multiple providers (Uses fingerprinting and source/ respondent-ids for this)
  • Engaged:  Do you want to check for straight liners, speeders, etc…? These should almost always be turned on. Validation settings are typically set by the end client, so AM’s should relay this information to the client and see which settings should be turned on.
    • If you have some 2D radio/checkbox questions visible to respondents but which are likely to be filled out in patterns, set tsengaged=”0” on them to disable reporting of their data to TrueSample, otherwise your respondents may be marked as un-enaged.
  • If you set truesample=”off” then TrueSample will be temporarily disabled: any of the checks above will not redirect, but continue the survey as usual. All tsXXX questions will be set to “insufficient”.

Note:  "Unique", "Engaged", and "Real" are almost always turned on. Validation settings are typically set by the end client, so AM’s should relay this information to the client and see which settings should be turned on.

Once you have set the survey live any changes to settings will need to be relayed to True Sample (i.e., inform your contact at TrueSample ) as they will need to manually update it on their side, otherwise it will not be active.

2.4:  Mandatory ID's

The following Id's are mandatory fields that must be set up correctly upon project commencement.

2.4.1:  Researcher ID

The researcher ID is for the firm conducting the survey, such as Factworks, Ameritest, Market-Strategies etc. This will allow them to look things up on the TS website and track results, much like having access to the Decipher Portal. One can check on the TS website to see if the researcher is already included within the TS website database by first clicking on the “Identification Codes” tab on the main website page, and then searching under company. If the company is not listed with TS, you can request to have them added, this can be done by clicking on the “Request New Companies” tab.

https://client.truesample.com/company/index

If you requested to add a new company, you'll see the window shown below. Enter your name and email address. Then enter the company name and division (can be the same as the company name if unknown). Then select the "type", which is typically either "End-Client" or "Researcher".

2.4.2:  End Client ID

The End Client ID is exactly what it says, this is whoever the end client of the research may be, i.e., ACME Co., etc. This would never be listed as Decipher and in many cases is different from whoever the researcher (Research ID) is for the project. Again, you can search for end clients the same way you can researchers (shown above), though the dropdown refers to them as “Sources”, not end clients.

https://client.truesample.com/company/index

2.4.3:  Category ID

The Category ID is located under the same “Identification Codes” tab that you find Researcher ID and End Client ID. Once you click on the “Category IDs” tab, you will see an expansion menu that will allow you to select or narrow down as close as possible the type of category your study falls under. For example if you were running a study on fast food, you would select "Dining" and then check the “fast food restaurants” option. This is important to not only True Sample but everyone as it allows them to classify the respondents based on the surveys they have recently taken in case they need to be excluded for a period of time. If we are putting in incorrect categories it creates problems by having people excluded from taking surveys for the wrong reasons potentially.

http://client.truesample.com/category/index

2.4.4:  Methods ID

The Method ID tab can be found right next to the Category IDs tab, once you click on the Method IDs tab, you will see an expansion menu, click on "All" to see the list of options. Once you have expanded the list, select (as best as possible) the methodology your study will be utilizing, such as; Concept Test, Discrete Choice, Monadic Product Test, Tracker etc.

https://client.truesample.com/method/index

3:  Dashboard Summary

Once you're logged in, click on the "View survey reports" link to access the True Sample Dashboard.

In the "Survey Validation" tab, open the "Reports" and click on the "+" icon next to the desired project to view the report. Select the "Regular Responses" tab when a study is live, or "Test Responses" when reviewing test data, to review the field report data. Click on the "Export response data" link to download the raw data in Excel. The screenshot below points out where each of these items are located in the report.

2013-06-20_0849.png

If you click on the "Learn More" link in the dashboard, you're taken to an FAQ page, like the one shown below. The "Resources" tab contains PDF resource guides that are available for download as well.

2013-06-20_0831.png

In the "SurveyScore® Predictor" tab, you can predict the survey score prior to fielding. Simply fill in the applicable fields and click "Calculate SurveyScore".

4:  Additional Information

Click here for a great PDF on TrueSample.

Here's some information for less common setup possibilities:

4.1:  Multiple Sample Partners

When working with multiple sampling partners or an aggregator (Federated, Fulcrum etc.):  You will need to have the provider ID for each of the Sample partners programmed into the study, but you don’t need to have separate links (list=1, list=2 etc.). As long as the provider ID is passed in the URL, you can utilize just one URL for the project.

4.2:  SurveyScore® Question

This is a simple question that is asked at the end of the study asking the respondents how this study compares to others they have participated in. Based upon their answer a SurveyScore® is created.  By default this should be included but is optional.

  • There is also a SurveyScore® predictor located on the True Sample website (https://client.truesample.com/sspredictor/index). If your client would like to have an idea how their survey will score, this is the utility to use. You only need to have basic information on the questionnaire (number of questions, types of questions etc.) and you can generate an estimate. 

4.3:  Real Time Verification

For those being passed into the survey without a TS (True Sample) ID, they will go through what is called the real time verification process. This happens as they enter the survey, anyone that comes in without a TS ID will be directed to a set of qualification questions (personal address, phone number etc.) that is then verified with TS. If verified, they continue into the survey and will be assigned a TS ID that can be obtained on the TS site (discussed below).  
It is possible to use real time verification without allowing non-preverified TrueSample respondents by passing "real=False" in the TrueSample survey code.  This will allow pre-verified TrueSample respondents with a valid ID (real checking) but does not ask the address verification question if the ID is empty or invalid.

4.4:  Project De-duping with True Sample

A person can only have one True Sample ID, but they can be members of multiple panels. In the case that you are utilizing more than one panel, True Sample will de-dupe the TS ID against all panels involved in the project. So while this may not be exactly like the old Optimus system, there is a level of de-dupe available with True Sample, but only based on their TS ID.

Optional based on client requirements 1-5:

1.  respondent-id  - Necessary if ‘Real Time’ Validation check is on and client wants True Sample validated panelists.
2.  Methods
3.  Categories
4.  Joined
5.  Client-id

5:  Programmer Setup

In the <survey> tag, ensure you have given your project a name or alt value. Set the truesample attribute to 1 or more of the following: real, unique, engaged, qualified, off. This enables the TrueSample system and generates non-virtual questions that will capture the data returned from TrueSample.

To disable TrueSample for respondents entering the survey through a specific sample source list, set the persistent variable p.nots to 1. For example:

<exec cond="list == '2'">
p.nots = 1
</exec>

Learn more by viewing this updated example survey.

Add this code below at the beginning of survey.xml using the XML editor:

<exec when="flow">
realStatus = 0
uniqueStatus = 0
qualifiedStatus = 0
tsid = ''
</exec>

<exec when="init">
# Just for debugging
def ts(q):
  if q.val is None:
     return "(not set)"
  return q.rows[q.val].text
</exec>
<if cond="str(gv.survey.root.truesample) != 'off'">
<label label="before_truesample"/>
<exec>
if list == '1': providerId = ########            # Enter the providerID.
elif list == '2': providerId = ########          # Enter the providerID.
else: providerId = source

truesampleRedirect(
  # required
  country="US",

  # optional
  endclient=########,                     # End client ID

  # optional
  researcher=########,                    # Researcher ID

  # Sample source provider, below GMI
  # Toluna is 88924047
  sample= providerId,

  # This will come from the sample provider, turn on if using "real" validation
  #respondent= tsid or "xyzzy123_" + uuid or sourceID or respondentID,

  #rule = 1117,             # Rules are used in conjunction with the "qualified" check.  This is not normally used.

  # optional
  #categories=[93],         # List categories for the project. Category codes can be obtained from the TrueSample site.

  # optional
  #methods=[202727],        # List methods for the project.  Method codes can be obtained from the TrueSample site.

  # optional (passed by panel provider)
  #joined=joined or "2010-01-01",
  
  # optional
  #real=False, # optional, use this in conjunction with "real" validation in the survey tag to only allow pre-validated TS respondents.  No address verification will be performed if real=False.
)
</exec>

<exec>
# for debugging only
realStatus = ts(tsreal)
uniqueStatus = ts(tsunique)
qualifiedStatus = ts(tsqualified)
</exec>
<html label="tres" cond="gv.survey.root.state.testing or gv.isStaff()">&lt;ul&gt;
 <li/>Real Status: ${realStatus} (tsreal.val = ${tsreal.val})
 <li/>Unique Status: ${uniqueStatus} (tsunique.val = ${tsunique.val})
 <li/>Qualified Status: ${qualifiedStatus} (tsqualified.val = ${tsqualified.val})
 <li/>Used response-id = ${uuid} and respondent-id ${tsid or "xyzzy123_" + uuid}

</html>
</if>

Add the following after the last question in the survey and before the “survey" tag, </survey> using the XML editor.

<if cond="str(gv.survey.root.truesample) != 'off'">
<label label="not_used_label1"/>
<exec>
truesampleFinal()
</exec>
<label label="not_used_label2"/>
<exec>
engagedStatus = ts(tsengaged)
</exec>
</if>

You must provide your account ID and passcode to your account manager, so they can implement the information in the nstyles file.

  Requires Decipher Cloud

If you are a shell user, you may navigate to your client level directory (e.g. selfserve/53b) and update/create an nstyles file. In the nstyles file, you will supply the code below. Please ensure you have updated the accountid and passcode with your own.

*truesample.account: accountid passcode

There is also a term at the beginning and a question at the very last. Will need to check with client if they want those 2 implemented.

<term cond="(tsreal.invalid or tsunique.invalid) and str(gv.survey.root.truesample) != 'off'">TRUESAMPLE NOT REAL OR NOT UNIQUE</term>

<style name="button.continue" with="B_TRUESAMPLE"><![CDATA[
<input type="submit" name="continue" id="btn_continue" class="btn continue survey-button" value="@(finish) &raquo;" />
]]></style>

<radio label="B_TRUESAMPLE" type="rating" truesampleSurveyScore="1" ratingDirection="reverse" averages="cols">
  <title>Lastly, how did this survey-taking experience compare to other online surveys you have taken?</title>
  <comment>(Please select one answer)</comment>
  <col label="c6" value="6"><b>Much better</b></col>
  <col label="c5" value="5"></col>
  <col label="c4" value="4"></col>
  <col label="c3" value="3"></col>
  <col label="c2" value="2"></col>
  <col label="c1" value="1"><b>Much worse</b></col>
</radio>
<suspend/>

Always include the suspend after the rating question [ B_TRUESAMPLE] - otherwise the SurveyScore® will not populate correctly.

Part of troubleshooting requires us to check the reporting tool at truesample.com. Their tool captures most of our variables and respondent status. The validation results are shown as a comment in the survey and can be viewed while in the testing state or logged in. A list of TrueSample error codes can be found here.

A TrueSample configured survey will add an invisible <suspend> tag to the beginning of the survey which redirects to TrueSample. This results in an additional page break in the field report. It will also add non-virtual tsreal, tsqualified, tsengaged and tsunique radio questions which will be assigned the status of the various validations. To maintain the data layout the questions are always added even if real/qualified/engaged/unique validation is turned off. Each of these questions will have 4 rows:

  • valid: address was validated
  • invalid: address entered was invalid
  • insufficient: when truesample is turned "off"
  • error: server or configuration error (e.g. invalid client/sample source IDs, mismatched country)

The questions are displayed in the report with an appropriate title and will appear in downloads.

6:  Example Survey

The following code is a full, working survey that you can use as a starting point for creating a TrueSample enabled survey. Project-specific components like sample sources, variables, etc... will need to be updated to meet the needs of your project, but the structure is convenient and ready to roll.

This survey sets the persistent variable p.nots = 1 to disable TrueSample for specific lists. 

Read the comments.

<survey
  alt="TrueSample Example"
  builderCompatible="1"
  autosave="0"
  compat="128"
  extraVariables="source,respondent,joined,tsid"
  name="test"
  setup="term"
  state="testing"
  truesample="qualified,unique,engaged"
  id="survey">

  <samplesources>
    <samplesource list="1">
      <title>TrueSample Enabled</title>
      <exit cond="terminated">Thank you for taking our survey.</exit>
      <exit cond="qualified">Thank you for taking our survey. Your efforts are greatly appreciated!</exit>
      <exit cond="overquota">Thank you for taking our survey.</exit>
    </samplesource>
    <samplesource list="2">
      <title>TrueSample Enabled</title>
      <exit cond="terminated">Thank you for taking our survey.</exit>
      <exit cond="qualified">Thank you for taking our survey. Your efforts are greatly appreciated!</exit>
      <exit cond="overquota">Thank you for taking our survey.</exit>
    </samplesource>
    <samplesource list="3">
      <title>TrueSample DISABLED</title>
      <exit cond="terminated">Thank you for taking our survey.</exit>
      <exit cond="qualified">Thank you for taking our survey. Your efforts are greatly appreciated!</exit>
      <exit cond="overquota">Thank you for taking our survey.</exit>
    </samplesource>
    <samplesource list="4">
      <title>TrueSample DISABLED</title>
      <exit cond="terminated">Thank you for taking our survey.</exit>
      <exit cond="qualified">Thank you for taking our survey. Your efforts are greatly appreciated!</exit>
      <exit cond="overquota">Thank you for taking our survey.</exit>
    </samplesource>
  </samplesources>
  <suspend/>

  <condition label="tsEnabled"  cond="int(list) in (1, 2) and str(gv.survey.root.truesample) != 'off'">TrueSample is active for these lists</condition>
  <condition label="tsDisabled" cond="int(list) in (3, 4) or  str(gv.survey.root.truesample) == 'off'">TrueSample is NOT active for these lists or is turned off</condition>

  <exec cond="condition.tsDisabled">
"""
Who should NOT have TrueSample enabled?
 - by setting p.nots = 1, we can ignore TrueSample functionality

 IMPORTANT: UPDATE the tsEnabled/tsDisabled conditions above to reference the correct list #s
"""
p.nots = 1
  </exec>

  <label label="before_TrueSample" />
  <exec cond="condition.tsEnabled">
"""
TrueSample configurations for TrueSample enabled sample sources
 - this code establishes the provider ID based on the sample source list value and
 - this is where respondents are redirected from the survey to the TrueSample website
 - please contact your Account Manager or sample source provider for details

 IMPORTANT: UPDATE the code below to reflect your project's settings
"""
if list == '1':
    providerId = 2874446        # e.g. Research Now
elif list == '2':
    providerId = 24788535       # e.g. Authentic Response
else:
    providerId = SOMEVARIABLE   # e.g. source, pid, etc...

truesampleRedirect(
  country="US",
  endclient=54286683,                               # required
  researcher=100332966,                             # optional
  sample=providerId,                                # required, sample source provider (GMI=83843645, Toluna=88924047, RN=2874446, AR=24788535)
  #respondent=(respondent or ("xyz1234_" + uuid)),   # optional, provided by sample source provider if "real" validation is enabled
  #rule = 1117,                                      # optional
  #categories=[21],                                  # optional
  #methods=[332],                                    # optional
  #joined=(joined or "2010-01-01"),                  # optional, may be provided by sample source provider
  #real=False,                                       # optional, use this in conjunction with "real" validation in the survey tag to only allow pre-validated TS respondents.  No address verification will be performed if real=False.
)
  </exec>

  <exec when="flow">
"""
Settings required to prevent errors
when loading the survey in One Page mode
"""
realStatus = 0
uniqueStatus = 0
qualifiedStatus = 0
tsid = ''
  </exec>

  <exec when="init">
""" Debugging purposes only """
def ts(q):
  if q.val is None:
  return "(not set)"
  return q.rows[q.val].text
  </exec>

  <exec cond="condition.tsEnabled">
""" Debugging purposes only """
realStatus = ts(tsreal)
uniqueStatus = ts(tsunique)
qualifiedStatus = ts(tsqualified)
  </exec>

  <block label="TS_Status" cond="condition.tsEnabled">
    <html label="tres" cond="gv.survey.root.state.testing or gv.isStaff()"><![CDATA[
      <ul>
        <li/>Real Status: ${realStatus} (tsreal.val = ${tsreal.val})
        <li/>Unique Status: ${uniqueStatus} (tsunique.val = ${tsunique.val})
        <li/>Qualified Status: ${qualifiedStatus} (tsqualified.val = ${tsqualified.val})
        <li/>Used response-id = ${uuid} and respondent-id ${tsid or "xyz1234_" + uuid}
      </ul>
    ]]></html>
    <suspend/>

    <note>IMPORTANT: CHECK with your Account Manager/client to see if this termination logic should exist</note>
    <term cond="condition.tsEnabled and (tsreal.invalid or tsunique.invalid)">TRUESAMPLE NOT REAL OR NOT UNIQUE</term>
  </block>






  <note>This is the first real question in the survey</note>
  <radio label="q1" grouping="cols" optional="1">
    <title>Matrix (radio by cols)</title>
    <row label="r1">R1</row>
    <row label="r2">R2</row>
    <row label="r3">R3</row>
    <col label="c1">C1</col>
    <col label="c2">C2</col>
    <col label="c3">C3</col>
  </radio>
  <suspend/>


  <style name="button.continue" with="B_TRUESAMPLE"><![CDATA[
        <input type="submit" name="continue" id="btn_continue" class="btn
continue survey-button" value="@(finish) »" />
      ]]></style>

  <block label="TS_Final" cond="condition.tsEnabled">

    <note>IMPORTANT: CHECK with your Account Manager/client to see if this final question should be asked.</note>

    <note>DO NOT REMOVE `ratingDirection="reverse"` from this question below. It is required for the API call made to TrueSample.</note>
    <radio label="B_TRUESAMPLE" type="rating" truesampleSurveyScore="1" ratingDirection="reverse" averages="cols">
      <title>Lastly, how did this survey-taking experience compare to other online surveys you have taken?</title>
      <comment>(Please select one answer)</comment>
      <col label="c6" value="6"><b>Much better</b></col>
      <col label="c5" value="5"></col>
      <col label="c4" value="4"></col>
      <col label="c3" value="3"></col>
      <col label="c2" value="2"></col>
      <col label="c1" value="1"><b>Much worse</b></col>
    </radio>
    <suspend/>
    

    <note>IMPORTANT: KEEP these TrueSample function calls above the "qualified" marker</note>
    <exec>truesampleFinal()</exec>
    <exec>engagedStatus = ts(tsengaged)</exec>
  </block>

  <marker name="qualified"/>
</survey>
  • Was this article helpful?