External Study Credit Granting

With External Study Credit Granting, a participant can receive credit as soon as they finish the online external study. This is accomplished by having the external study notify the system that the participant has completed the study and thus deserves credit.

If you are using a popular commercial product like Qualtrics, SurveyMonkey, Inquisit and many others, then skip this section and go to one of the following sections that provide specific instructions for each product. In addition, it may be easier to use the online integration instructions available for each product at https://www.sona-systems.com/help instead of this documentation. The reason is that those products may have been updated since this documentation was produced, and the online integration instructions are updated more frequently.

What follows in this section is a general description of the integration process if you are not using one of the commercial survey products listed in separate instructions below. If you are using one of those products, then skip to the relevant section (or the online integration instructions) instead.

Accessing the completion URL for the study sends the notification to the system. A properly configured study will have up to two Completion URLs:

  1. Client-Side Completion URL: If this URL is loaded, the participant will receive credit. Typically, the participant clicking on this link in their browser, or the participant being redirected to this link after completing the study, would load this URL. This is the most commonly used method for a commercial survey product where there is not already a built-in integration.
  2. Server-Side Completion URL: This URL would typically be loaded by the external study (not clicked on by the end-user participant) and is a server-to-server communication between the external study and the system. The results are returned in XML format and may be parsed by the external study. This method is used when you have full control over the external study, like if it is programmed from a Perl script. It also provides more control and security than the client-side method.

You should use only one completion URL to achieve credit granting. For most commercial online survey products, and if you are not familiar with programming, the client-side completion URL is likely the most appropriate option. To avoid confusion, the system will only display the client-side completion URL if a commercial survey product is being used and is known to support only the client-side completion URL.

To see the completion URLs for your study, first you need to ensure the study is set up correctly as an online external study. Then, enter the URL for the external site into the Study URL field in Change Study Information and save your changes. Next, click on Change Study Information again and modify the Study URL to include %SURVEY_CODE% in the URL in the appropriate place. If you entered the URL for a commercial product like SurveyMonkey, Qualtrics, SurveyGizmo, Unipark, or Inquisit, then the system will display help text just below the URL with a suggestion for how to include this. Once you save your changes the completion URLs should now appear on the resulting study information page. In short, the completion URLs will appear as long as there is %SURVEY_CODE% anywhere in the Study URL.

The client-side completion URL will look like this:
https://yourschool.sona-systems.com/webstudy_credit.aspx?experiment_id=123&credit_token=9185d436e5f94b1581b0918162f6d7e8&survey_code=XXXX

The server-side completion URL will look like this (if displayed):
https://yourschool.sona-systems.com/services/SonaAPI.svc/WebstudyCredit?experiment_id=123&credit_token=9185d436e5f94b1581b0918162f6d7e8&survey_code=XXXX

In the example above, the XXXX at the end is to show where the survey code number should be placed (in place of XXXX) by the external study website.

The next step is you’ll need to configure the online external study to receive the survey code number from the system at the start of the study, and also to load one of the completion URLs at the end of the study. You will need to replace XXXX with the survey code number and pass that to the system in the completion URL. Because this involves configuring the external study, which is not part of the system, how this is accomplished depends on the external study software. Usually it involves setting up the survey code number as some type of variable that is passed via the URL, and then configuring a redirect URL at the end of the study to be loaded, with this variable in the URL.

As this is a complicated feature, the best method to test it is to actually log in to the system as a fake participant. The entire credit granting process is not possible to test as a researcher, as researchers cannot sign up for studies. To ensure other (real) participants do not sign up for the study while you are testing it, add an Invitation Code to the study (you can remove it later).

The configuration directions for some popular survey products, based on information from those vendors, may be found here: Credit Granting with Other Supported Products.

Related Docs