Integration: How To Programmatically Start a SurveyToGo Survey from an external android app

Customer Support Manager

August 18, 2024 13:46

Overview

SurveyToGo exposes an Android activity that allows programmers to start a survey from their own Android app. A common use case would be an application that would need to run a custom survey from within the application and the developer doesn't want the user to switch between the app and the SurveyToGo app. In this case, the developer can initiate a survey directly from within his own app by using the below details.

Downloading The Sample App

You can download the STGCaller sample app that includes full source code and shows how to use the SurveyToGo activity to perform the supported activities. To download the sample app, click here or download from this link: https://dblstg.dooblo.net/downloads/STGCaller_1_0_0_1.zip

How To Use the STGCaller Sample App

The STGCaller sample app looks like this:

The 3 buttons correlate to the 3 functions available:

PRIMARY FUNCTION: Start Survey: this function takes all parameters (text boxes) and uses them to start SurveyToGo and immediately start a survey. You can choose whether to provide either a surveyid or a survey name, you don’t have to provide both even though you can. You can decide to only use this function and none of the others as it encapsulates the others too.
SECONDARY FUNCTION: Login: this function takes the first 3 parameters and initiates a login of SurveyToGo. It can be used to speed up things as it can save the primary function (Start Survey) the need to login so we advise you call this function on the start of your app but again, this is not mandatory as the Start survey function will login if necessary.
SECONDARY FUNCTION: Sync: this function takes the first 3 parameters and initiates a sync.surveys action of SurveyToGo. You can choose to call this periodically to ensure the surveys are always updated if changes have been made to them (as the primary function Start Survey will only perform sync.surveys by itself if the script is not present on the device but not upon script changes).

The Params box allows you to pass in custom parameters to the survey by following the syntax: key1=value1;key2=value2

For example, to pass to the survey the paramters FirstName and LastName you would put in: FirstName=Johhn;LastName=Doe

Please note that you can then later use the logic function ExternParam("FirstName") to access the parameter from within the survey script.

In addition you can pass parameters from the survey back to the calling app by using the OutputParams["myResult"] in the survey logic code (you can add as many output params as you need, more than one is supported). The engine will add the STG_OUT_COUNT (int) to the intent and multiple STG_OUTPUT_XXXX (string) fields to the intent where XXX will be replaced with the output variable name. The STGCaller demo app will wrap these with theSTGCallerResult::OutputParams hashmap for you to use.

How the demo app is coded:

The demo app includes these important parts:

STGCaller - static class used to call SurveyToGo
STGCallerResult - wrapper for intent returned on onActivityResult
STGStartSurveyParams - wrapper for intent params for "StartSurvey" action
STGUser - wrapper for intent params for ALL the actions
STGCallerActivity - example activity that uses the STGCaller

You are advised to re-use the first 4 classes in your app project as they were designed for your usage.

STG_STATUS_SS (string) STGCallerResult::START_SURVEY_Status

will be one of:

UserCanceled

CodeCanceled

DefaultCancel

Completed

Partial

FilteredOut

StartSurvey Return Statuses

Once the interview is completed, whether due to a submit, cancel, filter, or partial complete (stop) action - the Activity will provide you the reason in the STGCallerResult::START_SURVEY_Status parameter. The values can be:

Completed - the interview was successfully submitted
Partial - the interview was stopped
FilteredOut - the interview was filtered out (see here more about filtered out)

UserCanceled - the interview was cancelled by the interviewer
CodeCanceled - the script cancelled the interview (see here more about cancelling)
DefaultCancel - the interview was cancelled due to quota

How To Start a Previously Stopped Interview

When an interview is stopped, the Activity will provide a parameter called STGCallerResult::START_SURVEY_DeviceIndex that holds the local unique interview ID. If you save this ID, you can then use it when calling StartSurvey to continue the interview from where it was stopped.

One of the parameters passed to the StartSurvey is the STGSSP_DeviceIndex string parameter that can contain the ID received from the Activity (from the previous paragraph). If you populate this parameter it will continue that interview instead of starting a new one.

That's It !

Visit us at: http://www.dooblo.net