fresco 🠖 advanced topics

Integration with other survey tools 

As with Interviewer, Fresco is not intended to replace existing general purpose survey tools - particularly for ego specific data collection. We suggest that extensive ego-level data collection is done using a general purpose survey tool, and that Fresco is used to collect network data.

To facilitate this, Fresco supports integration with other survey tools via shared tokens, called "participant identifiers", which can be passed from your conventional survey tool into Fresco.

This integration will allow your participants to complete a "conventional" survey and then seamlessly transition to the network portion of the interview in Fresco simply by clicking a link. The data collected in Fresco can then be associated to the survey data using the shared participant identifier when conducting your analysis.

This article will explain the process of integrating using Qualtrics as an example, but the process is similar for other survey tools. Please let us know if you would like to see additional documentation for other survey tools.

What is a Participant identifier?

In Fresco, every participant in your study must have a unique identifier. When creating participants manually, you must provide this identifier yourself (or use the dedicated button to randomly generate one). When anonymous recruitment is enabled, this identifier will be generated as a participant is created using the anonymous participation URL, or (as we will see later in this tutorial) can be provided as part of the URL.

How Integration Works

As mentioned previously, the ultimate aim of integration is to be able to have your participant take a "conventional" survey, and then have them click a link that takes them to the network portion of the interview. By itself this would be simple to implement, but the key is to be able to link the data collected in the survey tool back to the data collected in Fresco.

Put simply, this is achieved by embedding the participant identifier in the URL that is used to link to the Fresco interview. When present in a URL, Fresco will use this identifier to either create a new participant (if anonymous recruitment is enabled) with the given identifier, or will link to an existing participant, before launching the interview.

There are two ways that the identifier can be included in the onboarding URL:

Query Parameters

The participant identifier can be included within what are known as "query parameters". This is a standardized web technology that encodes groups of data and labels in the format label=value, separated by ampersands (&) and added to the end of a URL following a question mark character (?). For example, a search engine may use query parameters to store a search query like this: http://google.com?query=networkcanvas.

In Fresco, the query parameter must be named participantIdentifier (this is case-sensitive!), and should be appended to the onboarding URL for your protocol. An example onboarding URL with the participant identifier included as a query parameter might look like:

https://yourstudy.com/onboard/{protocolID}/?participantIdentifier=12345

Using query parameters is the simplest method, but the participant identifier will be visible in the URL and could be tampered with.

POST Parameters

The participant identifier can also be included in the body of a POST request. This is a more secure method, as the data is not visible in the URL, but it is more complex to implement.

Fresco will look at the body of a POST request and try to parse it as JSON. If it finds a key called participantIdentifier, it will use the value of that key as the participant identifier.

This guide will focus on the query parameter method, as it is simpler to implement and should be sufficient for most use cases.

Example integration with Qualtrics

As an example, we will now discuss how to implement this process in Qualtrics, assuming that you do not have a pre-existing list of participants. The process is similar for other survey tools, but the exact steps may vary.

Set up your Fresco instance to allow anonymous recruitment.

Anonymous recruitment will allow participants to join your study without you needing to add them to Fresco in advance. This simplifies the process for the sake of this example, since it means you do not have to synchronize participant lists between Fresco and your survey tool. It is possible to integrate with external tools without anonymous recruitment enabled, but there are no real advantages to doing so.

To turn on the anonymous recruitment feature, log in to your Fresco instance, and go to the "settings" tab in the top navigation bar. Toggle the switch in the anonymous recruitment section to the "on" position.

Navigate to the "protocols" page, and click the button under the "Anonymous Participation URL" column next to the protocol you want to use. This will copy the anonymous participation URL to your clipboard. Paste this into a text editor for referencing later. It should look something like: https://your-fresco-instance.com/onboard/clwak4fc70000pybyrk9rvb98.

Set up your Qualtrics survey to generate or collect an identifier

Create your survey in Qualtrics to your specifications.

You will need to generate a unique identifier for each participant that you want to pass to Fresco. This could be:

For details on how to generate a unique identifier in Qualtrics, consult the Qualtrics support documentation.

For the purposes of this example, we will use the Qualtrics session identifier.

Use piped text to pass the identifier to Fresco

To pass the identifier, we will use the "piped text" feature in Qualtrics. This allows you to insert dynamic data into your survey questions and responses, or as in this case, into the URL that you will use to link to Fresco.

In your survey screen find the "End of Survey" block:

End of Survey
End of Survey

Edit the "End of Survey" block to add a link to your Fresco survey with the "anonymous participation URL" you pasted into your text editor earlier.

Update the link to include the piped text code for your identifier. In this example, we will use the Qualtrics session identifier as the identifier. The piped text code for the session identifier is ${l://SurveySessionID}. We add this code to the URL as a query parameter named participantIdentifier, which results in the following:

You have completed the first part of the study. Click the link below to proceed
to the next section:

<a
  href="https://your-fresco-instance.com/onboard/clwak4fc70000pybyrk9rvb98/?participantIdentifier=${l://SurveySessionID}"
>
  Continue to the next section
</a>

The link must be in the format shown to ensure that the participant identifier is passed correctly. Test the link by clicking on it to ensure that it leads to your Fresco survey, and creates a new participant with the correct identifier.

Assuming that the test was successful, you can now distribute your survey to participants. When they complete the survey, they will be directed to the Fresco interview with the participant identifier in Fresco corresponding to the survey session identifier in Qualtrics.

Additional Considerations