Survey Reminders

Survey Reminders allow survey authors to script the display of one-time and recurring notifications that display in the device notification area to remind them to complete a survey. This is useful for diary studies, for example, where a survey author may want a reminder to be set for a time in the future when the app can remind the user to complete the next iteration of the survey. Depending on the type of study, the frequency of when to prompt the user can vary significantly. In some cases, it may require multiple surveys per day, and different times of the day for each respondent. In other cases it may be some time far into the future, for example a month or more.

This set of functions facilitates this alarm functionality.

Note that there are some limitations regarding the device OS:

• The number of iOS concurrent notifications is limited due to a limitation in the OS. It may be possible to schedule up to 64, but this number may be significantly lower depending on the surveys that are loaded in the app.
• Major device or OS upgrades may discard set alarms.

SetSurveyNotification

SetSurveyNotification(reminderName, displayLabel, notificationTimestamp)

• reminderName (String) - Unique identifier for this alarm
• displayLabel (String) - Text to display in notification. Plain text only. Recommended max length: 70
• notificationTimestamp (Date) - Date and time when to display notification. Max value < 60 days in future

This function sets a one-time reminder to display at a specific time in the future. This reminder will display regardless of whether the app is in use or not. Tapping on the reminder notification starts the app and enters the survey inside which the call was made.

Calling the function with the same reminderName overwrites previous settings.

Example: Remind user at the same time tomorrow

// Gets the current date and time
var date = new Date();
// Adds 24 hours to the date
date.setHours(date.getHours() + 24);
SetSurveyNotification("tomorrow", "Please record your diary input now.", date);

Example: Remind on the 12, 14, 16th of the current month

// create 3 separate reminders

// Gets the current date and time
var reminder1 = new Date();
// Sets the date to the 12th of the month
reminder1.setDate(12);
// Gets the current date and time
var reminder2 = new Date();
// Sets the date to the 14th of the month
reminder2.setDate(14);
			
// Gets the current date and time
var reminder3 = new Date();
// Sets the date to the 16th of the month
reminder3.setDate(16);
			
SetSurveyNotification("MonReminder", "Please record your diary now.", reminder1 );
SetSurveyNotification("WedReminder", "Please record your diary now.", reminder2 );
SetSurveyNotification("FriReminder", "Please record your diary now.", reminder3 );

SetAppNotification

SetAppNotification(reminderName, displayLabel, notificationTimestamp)

• reminderName (String) - Unique identifier for this alarm
• displayLabel (String) - Text to display in notification. Plain text only. Recommended max length: 70
• notificationTimestamp (Date) - Date and time when to display notification. Max value < 60 days in future

This function sets a single-shot reminder to display at a specific time in the future. This reminder will display regardless of whether the app is in the foreground or background. Tapping on the reminder notification starts the app.

In contrast to SetSurveyNotifications, this does not start a specific survey. This allows for situations where the user may need to continue where they left off providing an opportunity to resume.

Calling the function with the same reminderName overwrites previous settings.

SetRepeatingSurveyNotification

SetRepeatingSurveyNotification(reminderId, displayLabel, minuteOfHour, hourOfDay, dayOfWeek)

• reminderName (String) - Unique identifier for this alarm
• displayLabel (String) - Text to display in notification. Plain text only. Recommended max length: 70
• minuteOfHour (Number) - The minute for the hour to trigger (0-59)
• hourOfDay (Number) - The hour of the day to trigger (0-23)
• dayOfWeek (String, optional) - Day of the week labels (mon, tue, wed, thu, fri, sat, sun)

This function sets a recurring reminder. This reminder will display regardless of whether the app is in the foreground or background. Tapping on the reminder notification starts the app and enters the survey inside which the call was made.

The firing of this notification is based on the minuteOfHour, hourOfDay and dayOfWeek settings. At every time where there is a match of these values with the current time, the notification will fire. For example, if we desire the notification to fire every Monday at 9am, we would set minuteOfHour to 0, hourOfday to 9 and dayOfWeek to "mon".

The dayOfWeek parameter is optional. If not provided, the reminder will recur every day.

Calling the function with the same reminderId overwrites previous settings.

Example: Remind every day for next 3 days at 10am

SetRepeatingSurveyNotification("10amReminder", "Please record your daily diary now.", 0, 10);
			// NOTE: survey multiple complete set to Max 3 which will stop alarms once 3 surveys are completed

Example: Remind every week on Saturday mornings

SetRepeatingSurveyNotification("SatReminder", "Please let us know your weekly activities.", 0, 10, "sat");

CancelSurveyNotification

CancelSurveyNotification(reminderId)

• reminderName (String) - Unique identifier for this alarm

This function cancels the notification associated with reminderId.

CancelSurveyNotifications

CancelSurveyNotifications()

This function cancels all notifications set in this survey.

GetLastSurveyNotificationDate

GetLastSurveyNotificationDate()

This function returns the timestamp of the last time a notification was displayed to the user from this survey based on the set notifications.

It is important to understand that this returns the expected last notification timestamp, not the timestamp of the last actual display of a notification.

Example: Provide time window for when survey can be completed

// ensure the user started the survey within 15 minutes of receiving the survey reminder
var d = new Date();
d.setMinutes(d.getMinutes() - 15);
if( GetLastSurveyNotificationDate() < d )
{
//show an informational question - "Sorry, you didn't start the survey in time. You will get another chance tomorrow"

Example: Check if user has notifications enabled for app

if(!IsAppNotificationPermissionEnabled())
{
// Show informational node to ask user to enable notifications

IsAppNotificationEnabled

IsAppNotificationEnabled()

This function checks if the user has enabled notification permissions for the app.

ShowAppNotificationSettingsDialog

ShowAppNotificationSettingsDialog()

This function displays the notification permissions screen to allow the user to change the setting for the app.