Logo Utrecht University

DHLab Manuals

Handleidingen

Back

Panel Randomizer Manual

V1.1/26-07-2018

This manual introduces the Panel Randomizer application, which was built by the Digital Humanities Lab for the ERC project ‘ROCKY’ to add custom functionality to LimeSurvey. More specifically, it:

  • adds a check to ensure that respondents can take a survey only once
  • randomizes the survey a respondent takes while ensuring even distribution of respondents
  • adds custom functionality for including YouTube and Vimeo clips in a survey

Integration of Panel Randomizer with LimeSurvey hinges on the ability of LimeSurvey to receive data (i.e. ‘Panel Integration’). It does this in the first (few) question(s) of a survey, which will be ‘pre-filled’ from the url used to open the survey. Note that these first question(s) need not to be visible to respondents, but exist only to enable communication with Panel Randomizer.

A very important aspect of creating surveys with Panel Randomizer, then, is setting up the urls that will be created by Panel Randomizer, and matching these with questions in LimeSurvey. This manual will detail the workflow required.

  • The integration with Panel Randomizer requires that a survey uses so called ‘pre-filled’ questions. In order to save the encrypted student number and to receive a variable that can be used for presenting different groups (branching), two questions need to be filled by the GET parameters in the url that is generated by Panel Randomizer.

    Panel Randomizer generates for example this url to LimeSurvey:

    https://survey2.hum.uu.nl/index.php/395174?lang=en&branch=1&student=79Nz

    In this example the GET variables ‘branch=1’ and ‘student=79Nz’ are send to LimeSurvey. Each survey in LimeSurvey needs to be prepared to use these variables as answers that are prefilled by the GET parameters.

  • Step 1

    Create a Survey in LimeSurvey

  • It is possible to define another survey for respondents using a mobile device. The steps needed for setting up the survey itself are the same. The mobile survey can then be added when setting up the Panel Randomizer.

  • Step 2

    Create a Question Group

    This first group is the group that will contain the ‘prefill’ questions. On the basis of the GET parameter received in the questions in this group, respondents will be redirected to other groups, i.e. the ones that contain actual questions.

  • Step 3

    Create Questions for Prefilling

    First create one or two questions in this first group. These will be prefilled by the URL of Panel Randomizer. Add a question for student number and (optionally) a question for branching. We need these questions to exist for further setup of receiving the GET parameters from Panel Randomizer. Note that these questions can be made ‘hidden’ optionally.

  • Step 4

    Set up ‘Panel Integration’ in LimeSurvey.

    (For LimeSurvey 2.50: Tab Survey properties → General settings & texts → General Options → Panel integration)

    This is the place where the communication between Panel Randomizer and LimeSurvey is realized. Add the url parameters that are used for prefilling the answers. Choose a parameter name for the student number parameter that will be taken from the url and, in the dropdown, assign the parameter to the target question from step 2. If required, also choose a name for the branching parameter and assign the parameter to the target question for the branching from step 2. Note that you will use these exact parameter names later when you configure Panel Randomizer.

    In the background, LimeSurvey will now create a link between the name of the question and the value it receives via the url (by ‘answering’ our prefill question). For example, the example url we saw above contains the following parameter student=79Nz. Our settings in Panel Integration now answers question ‘V001’ with the parameter value ‘79Nz’.

  • Step 5

    Set up Groups (Optional)

    If you want to use different sets of questions, i.e. ‘groups’ in LimeSurvey, you can create branches.

    For this you will again use a GET parameter and a ‘prefill’ question. The answer to this prefilled question determines which group will be shown to the respondent. To get this to work you will need to configure the value for ‘relevance equation’ of each group in the following manner: [questionid]==[rotation number]. For example V002==1.

    In the case of our example, this particular group will only be shown when the question V002 (to be used for branching)  was prefilled with ‘1’ by the forwarding url. (illustration below)

  • Step 6

    Set up Panel Randomizer

    1. Enter the Admin of Panel Randomizer →
      https://panel-randomizer.hum.uu.nl/admin/
    2. Right from ‘Surveys’ choose ‘Add’.

  • Step 7

    Fill Out the Fields

    A Survey Name (Required)
    This name will be used as the last part of the link for the respondents. The complete link will be: https://panel-randomizer.hum.uu.nl/test_panel_randomizer. When a respondent opens this url, the settings for this particular survey will be retrieved. The name does not need to be the same as the desktop and mobile survey names in LimeSurvey. It is best to use an easy-to-understand name that is descriptive for the research, as it will be the last part of the url that is presented to the respondents.
    Survey Desktop Url (Required)
    This is the url you see in your LimeSurvey that you plan for desktop users under ‘Survey URL’. Copy the (green) url from LimeSurvey and paste it in this field. Note that Panel Randomizer will enrich this url with extra GET variables.
    Survey Mobile Url (Optional)
    The LimeSurvey url you plan for the users of mobile devices.
    Expected Completion Time
    In minutes. This will be shown on the welcome screen of Panel Randomizer.
    Group Count
    The number of groups that need to be rotated. The group number is passed as a GET variable in the forwarding URL generated by Panel Randomizer. For every new respondent this integer will be incremented with 1 until the max number is reached, and starts again at 1.
    Integration Parameter Student Enc (Required)
    The parameter name you choose (in step 4) in LimeSurveys ‘Panel Integration’ to save the (encrypted) student number. Please fill out the exact same name. The encrypted student number will be passed as a GET variable in the URL to LimeSurvey with this name. I.e when you choose the name ‘student’ in panel integration as the url parameter that pre-fills the student number question, please fill out the same name here. The redirecting URL to LimeSurvey will then contain this: &student=[encrypted number]
    Integration Parameter Branching (Optional)
    The parameter name you choose in LimeSurveys ‘Panel Integration’ to save the answer needed for showing a particular group. Please fill out the exact same name. I.e when you choose the name ‘branch’ in panel integration as the url parameter that pre-fills the question that decides which group of questions is shown next, fill out ‘branch’ here as well. In the generated url the GET parameter will then contain this: &branch=1, and a ‘1’ will be filled as the question answer in LimeSurvey. For the next respondent the number will be ‘2’ until the number you filled in ‘Group count’ is met.

    Click ‘save’.

  • Step 8

    Check If Everything Is Working

    Go to https://panel-randomizer.hum.uu.nl/test_panel_randomizer

    (Replace test_panel_randomizer; with the survey name you just entered).

    Instead of panel-randomizer.hum.uu.nl the shorter panel.hum.uu.nl can also be used!

    In order to test the connection to your LimeSurvey survey, use the student number: ‘123’. This number is (for the moment) available for testing purposes and will not be saved in the database. Note that using any other student number will allow for only one entry (!).

  • When you open the page and see ‘Onderzoeksnaam ontbreekt of is onjuist’, the survey name was not found. Perhaps you forgot to add the name of the survey you just created in the admin, or misspelled it. Please use a slash / and the survey name after the base url: https://panel-randomizer.hum.uu.nl in the browser address bar. Otherwise, click the button. You should now get the first page of the survey and see the questions filled with the variables from the url.

  • Step 9

    Autoplay and Continue YouTube or Vimeo Clips

    Sometimes, a question contains one or more YouTube or Vimeo clips. To make sure such questions use the customization provided by Panel Randomizer follow the instructions below.

    Adding Code

    When adding a new question, click ‘Source’ in the editor window. This will show the code behind the question, where we will need to insert some code.

    Paste the following lines of code (make sure to insert the correct url  for the video!):

    <div class="single-play-video" data-video-url="URL_TO_YOUR_VIDEO"></div>
    <script src="https://panel-randomizer.hum.uu.nl/static/js/video_helper.js" async></script>

    (see image)

    The first line (which starts with <div class=) inserts a YouTube or Vimeo player. This is where you need to insert the url for the desired video. The second line (which starts with <script src=) retrieves the code from Panel Randomizer that customizes the video. This script will start the clip automatically, hide all buttons from the respondent, and navigate to the next group when the video is done.

    Before the Next Button

    In Safari it isn’t possible to autoplay the video. Once the respondent started the video it will continue to play and at the end it will go the next question. If it still desired to autoplay the video this can be done by placing the video in the question before and setting with data-before-next="true" that this video will be played once the user clicks the ‘next’ button. This is done using the following code:

    <div class="single-play-video" data-video-url="URL_TO_YOUR_VIDEO" data-before-next="true"></div>
    <script src="https://panel-randomizer.hum.uu.nl/static/js/video_helper.js" async></script>

  • This work-around might have difficulties dealing with required questions and additional validation. Check that these still work as expected! For example: the video shouldn’t play if the respondent clicks the next-button but hasn’t yet filled in all questions.

Last modified: 6/05/2019

Back