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: http://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:
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