How to Implement Timers

Overview

SurveyToGo supports the use of timers that can be used to measure time, trigger actions after a specified period, or automate survey behavior.

Timers can function as stopwatches and can be configured to perform custom actions when they expire.

This article covers:

1. Creating a timer.

2. Measuring elapsed time.

3. Executing actions when a timer expires.

Step 1: Create a Timer

Timers are created using the SetTimer() function.

Syntax

Timers.SetTimer("MyTimer", 30000, false);

Parameters

Parameter 1: Timer name

A unique string that identifies the timer.

"MyTimer"

Parameter 2: Duration

The timer duration in milliseconds.

30000

In this example, the timer will expire after 30 seconds.

Parameter 3: Auto-restart

A Boolean value that determines whether the timer restarts automatically after expiring.

true

The timer automatically restarts each time it expires.

false

The timer expires only once.

Recommended Location

Timers are typically started from a question's Start Script.

Pausing a Timer

To stop a running timer, use:

Timers.PauseTimer("MyTimer");

The parameter is the name of the timer to pause.

Step 2: Measure Elapsed Time

Timers can be used to measure the time between the moment a timer starts and when it is paused.

For example, you can:

• Measure how long a respondent spends on a specific section.

• Track the duration of an activity.

• Record interview timing information.

The timer can be started at one point in the survey and paused later, allowing the elapsed time to be captured and stored.

Step 3: Perform Actions When a Timer Expires

SurveyToGo provides a callback function that is triggered whenever a timer expires.

Add the following function to the survey's Advanced Scripts:

function OnTimer(key)
{
}

This function is called automatically whenever any timer reaches its configured duration.

Handling a Specific Timer

The key parameter contains the name of the timer that expired.

For example:

function OnTimer(key)
{
    if (key == "MyTimer")
    {
        Prompt("MyTimer was elapsed!");
    }
}

When the timer named MyTimer expires, a message is displayed.

Handling Multiple Timers

You can perform different actions for different timers:

function OnTimer(key)
{
    if (key == "MyTimer")
    {
        Prompt("MyTimer was elapsed!");
    }

    if (key == "test1")
    {
        Prompt("test1 was elapsed!");
    }

    if (key == "test2")
    {
        Prompt("test2 was elapsed!");
    }
}

Each timer can have its own custom logic.

Automatically Move to the Next Question

To advance to the next question when a timer expires, use:

ExecutionMgr.GotoNext();

For example:

function OnTimer(key)
{
    if (key == "MyTimer")
    {
        ExecutionMgr.GotoNext();
    }
}

When MyTimer expires, the interview automatically proceeds to the next question.

Summary

Timers can be used to:

• Measure elapsed time.

• Limit response time.

• Automatically advance interviews.

• Trigger reminders or notifications.

• Execute any custom scripted action when a timer expires.

By combining SetTimer(), PauseTimer(), and the OnTimer() callback, you can create a wide variety of time-based survey behaviors.