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

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. 

How To Use the STGCaller Sample App

The STGCaller sample app looks like this:

The 3 buttons correlate to the 3 functions available:

1. 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.
2. 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.
3. 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).

Passing Parameters to and from a Survey

The Params field allows you to pass custom parameters into a SurveyToGo survey when it is launched from an external application.

Input Parameters

Parameters must be supplied using the following format:

key1=value1;key2=value2

Example

To pass the values FirstName and LastName to the survey:

FirstName=John;LastName=Doe

Within the survey script, these values can be accessed using the ExternParam() function:

ExternParam("FirstName")

This example returns:

John

Returning Parameters to the Calling Application

SurveyToGo also allows a survey to return values back to the application that launched it.

To do this, assign values to the OutputParams collection within the survey script:

OutputParams["myResult"] = "Completed";

You can define multiple output parameters as needed.

Example

OutputParams["RespondentID"] = "12345";
OutputParams["SurveyStatus"] = "Completed";

How Output Parameters Are Returned

When the survey finishes, SurveyToGo adds the following information to the return intent:

• STG_OUT_COUNT – The number of output parameters returned.

• STG_OUTPUT_XXXX – One entry for each output parameter, where XXXX is replaced by the output parameter name.

For example:

STG_OUT_COUNT = 2
STG_OUTPUT_RespondentID = 12345
STG_OUTPUT_SurveyStatus = Completed

When using the STGCaller demo application, these values are automatically wrapped into the STGCallerResult::OutputParams hashmap, making them easy to access from the calling application.

 

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. 

• UserCanceled - the interview was cancelled by the interviewer

• CodeCanceled - the script cancelled the interview.

• 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.