CAPI and AskMe App Shared Functions

Note: For surveys targeting the AskMe app, the following functions must be added after the first question presented in a survey. These functions only work successfully if executed while in the app. Since the survey is first opened using the participant’s mobile device browser before opening within the AskMe app, the functions will attempt to run in the browser if included on/before the first question.

GetDeviceUniqueId

Return the unique ID for the device being used. Note that the identifier is retained/persisted even if the app is uninstalled.

GetDeviceUniqueId()

Alternatively, see GetOfflineInfo() for related information.

GetOfflineInfo

Use GetOfflineInfo() function, to access app and device information:

AppVersion returns the application version in use.
BatteryLevel returns the battery level in the device.
DeviceLanguage returns the language code as exposed by the operating system (e.g. "fr").
DeviceLanguageId returns the Forsta language code determined by the device locale (e.g. fr-be = 2060 French Belgium). Note that this is the derived Forsta language code and may not be the language set for a survey if the survey does not contain the same language. To determine if the survey contains the same language, you are recommended to use CurrentLang() to determine if the target device language is supported by the current survey.
DeviceLocale returns the device country code exposed by the operating system (e.g. "be").
DeviceModel - returns the model information exposed by the operating system.
DeviceOs returns the operating system the device is using.
DeviceOsVersion returns the operating system version.
DeviceUniqueId returns the device's unique id code.
DeviceName returns the name of the device (if exposed by the operating system).
LastGeoAccuracy returns the estimated distance in meters for the last captured geolocation question. For example, a value of 25 means that the mobile device operating system reported that the geolocation coordinates recorded for the question should be within 25 meters of the actual geolocation coordinates.

Examples of use:

var lvl = GetOfflineInfo().AppVersion
var lvl = GetOfflineInfo().DeviceOs
var lvl = GetOfflineInfo().DeviceOsVersion
var lvl = GetOfflineInfo().BatteryLevel
var lvl = GetOfflineInfo().DeviceModel
var lvl = GetOfflineInfo().DeviceUniqueId
var lvl = GetOfflineInfo().DeviceName

GetSurveyDeviceVariable, SetSurveyDeviceVariable, GetUserDeviceVariable and SetUserDeviceVariable

AskMe and the CAPI app support the ability to write to and read from local storage on the device, either in the scope of the current survey, or the same user. These functions allow data to be stored within the app for future reference, which can be very useful for preventing re-asking questions or for building workflows between respondents/interviews or surveys. To access this information there are four scripting functions:

SetSurveyDeviceVariable()GetSurveyDeviceVariable()SetUserDeviceVariable()GetUserDeviceVariable()

SetUserDeviceVariable is scoped to the same user but can share between surveys. This can be used for example, to store information relevant to the currently logged in CAPI interviewer.

SetSurveyDeviceVariable scope is local to the same survey only, shared between respondents. This can be used for example, to track a counter for every completed survey in AskMe.

To clear a device variable, set the value to null. Example:

SetSurveyDeviceVariable("diaryIteration", null);

GetUserDeviceVariable and GetSurveyDeviceVariable will return null if key is not found.

Example usage

Here we are setting/getting a counter for the survey local variable (just referencing the value of QID q1):

SetSurveyDeviceVariable("diaryIteration", f('q1'));GetSurveyDeviceVariable('diaryIteration')

And here we are setting/getting the user's name from a user-level local variable (just referencing the value of QID fullname):


			SetUserDeviceVariable("AskMeUsername", f('fullName'));


			GetUserDeviceVariable('AskMeUsername')

Note: You cannot set the value for an Audio Capture question.

startAudioCapture

startAudioCapture

Starts the audio recording.

f(qID).startAudioCapture()

Where qID is an audio capture question contained anywhere within the survey.

This feature allows audio to be recorded in “the background”, essentially at the same time as the survey is being conducted. This can be used for quality control or fraud detection purposes. The feature even allows the audio capture to continue while the app is not in the foreground.

Note: If this is the first time audio recordings have been initiated by the application on the device, the user may be prompted to allow access to the microphone. This could be confusing to the user as it may not be obvious why this is being requested. It may therefore be advantageous to include an Information node to explain what is happening and why.

Recommended Setup

Add an audio capture question to the survey and place in a section that is not shown to the user or add a question script masking
Ensure that the maximum recording length (in seconds) is set to a value that is higher than you anticipate the total recording length to be.
At the point in the survey you would like to start recording, add a Script node and call the startAudioCapture() function, referencing the audio capture question added above.
At a later point in the survey, stop the recording, use the stopAudioCapture() function (see below).

Best Practices

startAudioCapture() should be placed at a point where the user is not able to re-execute the same script node. If the function is called repeatedly, it will stop the current recording and start a new recording, overwriting the existing recording.
Background audio capture is an advanced capability and can be interrupted by other activities that use the device microphone. For example, any of the following activities will cause the background audio to be stopped:
The user taking a phone or video call.
The user is requested to capture audio in another question in the survey.
Due to the possibility of the recording being interrupted, it is recommended to keep the background recording to a reasonable duration such as less than 20 minutes. For example, if the interview is expected to take 30 minutes, consider using two separate audio capture questions and start and stop the recording for each section of the interview.
The recording will be automatically stopped when the survey is completed or closed (e.g. quota reached, postponed, cancelled). If it is expected that an interview could be paused and resumed at various points in the interview, this will require a check to determine where to resume the recording.

stopAudioCapture

stopAudioCapture

Stops the audio recording.

f(qID).stopAudioCapture()

The audio recording will be saved to the audio capture question referenced by qID.

Note that the following conditions will also cause the recording to be stopped:

If the survey is closed (postponed, canceled, etc).
If another audio recording is initiated either via startAudioCapture or a visible audio (or video) capture question.
When the Max property set for the audio capture question (qID) has been reached.

Note: You cannot set the value for an Audio Capture question, and the Min property will be ignored.

openVideoInApp

Function to play a video using the device built-in video player triggered by a button or other event:

openVideoInApp()

Example question text HTML source:

<a onclick="openVideoInApp('/isa/BDJPDAVIOEQJR/p5165/demo.mp4');return false;">Play Video</a>

Alternatively, videos can be presented using the <video> HTML tag:

<video playsinline width="100%" controls preload="none">
			<source src="/isa/BDJPDAVIOEQJR/p5165/demo.mp4" type="video/mp4" />
			</video>

Video files can be added to the File Library making them available for offline viewing.

Device specific behavior for playsinline option (e.g. within same survey view):

iPhone: always plays fullscreen regardless (inline not supported)
iPad: plays inline
Android (phone or tablet): plays inline if playsinline property provided.

openAudioinApp

This function plays an audio file:

openAudioInApp(url,openExternalPlayer)

where:

url is the file library path to the audio file.
openExternalPlayer is a boolean value. Setting to true (default) plays the audio file using the default built-in audio player on the device. Setting to false will play the audio directly in the app without any controls. This can be helpful for playing short audio clips where controls are not needed.

Example question text HTML source:

<a onclick="openAudioInApp('/isa/BDJPDAVIOEQJR/p5165/demo.mp3');return false;">Play Audio</a>

Alternatively, audio can be presented using the <audio> HTML tag:

<audio playsinline width="100%" controls preload="none">
	<source src="/isa/BDJPDAVIOEQJR/p5165/demo.mp3" type="audio/mpeg />
            
</audio>

Audio files can be added to the File Library, making them available for offline playback.

Forsta Scripting Support

Articles in this section

Example usage

Best Practices