External Study Credit Granting with Google Forms

While these instructions refer to “credit granting”, they work for both credit and paid studies. For paid studies, participation will be marked (instead of credit granted) just like with any other paid study.

Step 1: Add an Internal Survey ID to your Google Forms Survey

Go to the bottom of your Google Forms Survey and click the icon to add a new question:

The new question you added should be a Short Answer question type. If it isn’t, then change the question type now:

  • Part 2 Study Settings

Then copy and paste the following into the question text:
Internal Survey ID - Do Not Change (sona-survey-code)

Leave the answer blank. Your new question text should look like this:

Step 2: Obtain a Pre-filled Link from Google Forms

On the top right of the menu options (next to the Send button) are three vertical dots. Click to open this dropdown menu, then select “Get pre-filled link”:

This will open a fillable version of your survey. Scroll down to the question you just added (which should be the last question). In the answer field to the Internal Survey ID “question” field, enter an ID number of your choosing:

Be sure to pick a number you will be able to recognize easily later!

Once you have chosen an ID code value and entered it, click the “Get link” button:

This will open up a button option. To get your pre-filled URL, click Copy Link:

You will use this URL to create your Study URL and configure your Sona study for integration in the next steps, so it may be worthwhile to paste it into a temporary document (that way, you can access it easily later and you need not rely on your clipboard).

Step 3: Change your Study URL in Sona

On your study page, click the Study Information menu button, then select Change Study Information. Scroll down to the Study URL section. You will only want to paste part of the URL you just copied, so if you haven’t already, it will be useful to temporarily paste the complete URL in a text editor (e.g., Notepad or TextEdit)

The URL you copied should look similar to the one below, with the code you picked following the “=” sign:

Paste the copied URL into the Study URL field, then replace the Internal Survey ID with %SURVEY_CODE%:

Once you have appended %SURVEY_CODE% to your study URL, scroll down to the bottom of your Change Study Information page and click Save Changes.

Step 4: Copy your Study’s the Completion URL

Your Study Information page should now contain fields customized for Google forms Integration. In this step, the important one is your study’s Completion Link:

You will need this completion link for the next step. Copy the link, and paste it into a document or text editor (e.g., Notepad or TextEdit) for later use. It should look similar the the URL below:
https://yourschool.sona-systems.com/webstudy_credit.aspx?experiment_id=123&credit_token=4e48f9b638a&survey_code=${surveyCode}

Please make sure your completion code ends with {surveyCode}

Step 5: Open Script Editor in Google Forms

In Google Forms, click on the three vertical dots icon to open the dropdown menu from before. This time, however, select the “Script editor” option:

This will open a Google Apps Script window (note the name “Code.gs”; the extension .gs stands for “Google Script” and seeing it means you are in the write area to paste you your code):

Delete the lines of code function myFunction() so that the editor is blank:

Step 6: Copy & Paste Code into Script Editor

Now that you have a blank script editor open, you can paste in the necessary code. The easiest way to do this is to move your cursor over the code block below. In the top-right corner, you will see a Copy to Clipboard button appear. Click the button to copy the code to your clipboard:

Copy to Clipboard

Once copied, paste the code into the script editor:

As a quick check, please make sure the number of lines of code you pasted matches the number (29) shown in the image immediately above. For the integration process to work properly, you must copy and paste the complete code from the code block above.

After you have checked to make sure you correctly pasted all the code, you will need to edit the completion URL in the script to match the completion URL you copied in Step 4. Find the line beginning with var completionLink (it should be line 16 in app script). In that line is a placeholder, %COMPLETION_LINK%, that you will need to replace with your completion code. The final result of this part of the code should look like this:
var completionLink = `https://yourschool.sona-systems.com/webstudy_credit.aspx?experiment_id=123&credit_token=4e48f9b638a&survey_code=${surveyCode}`;

Once you have replaced the placeholder %COMPLETION_LINK% with the completion code you’ve copied, save the script by clicking on the Save Project icon, located roughly over the word “function” in the first line of your new code:

Step 7: Add a Trigger

Finally, you must indicate when your script should run by adding a trigger. You will be configuring your script to run whenever participants submit their responses, and there is a built-in trigger to do precisely this.

To add it, place your mouse over the alarm clock icon on the left-hand panel to expand the options (this will make sure you are selecting the correct menu option), then click on the icon:

This will bring you to the Triggers page for your project. On the lower right-hand side, click on the Add Trigger button:

This will open the Add Trigger options. Please make sure to select both of the following :

  • The function is onFormSubmit
  • the “event type” is “On Form Submit”

The correct option settings are shown below:

Once you have the correct function and event type, click “Save” to save your trigger:

You should now see the trigger you added on your trigger project page:

That’s it! Your Google Forms survey is now integrated with Sona’s automatic credit granting process.