Android

Latest Version: 1.2.9

GitHub Example App: View Example

Below are the various processes involved in setting up SpotChecks on Android.

Installation

Insert the following in your build.gradle file at the end of the repositories section.

allprojects {
  repositories {
    ...
    ...
    maven { url 'https://jitpack.io' }
  }
}

Add the following line to your app modules, present in the build.gradle file within the dependencies section.

implementation 'com.github.surveysparrow:surveysparrow-android-sdk:1.2.9'

Permissions

Add to AndroidManifest.xml as needed.

Required (network)

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

Optional — photo capture

<uses-permission android:name="android.permission.CAMERA" />
<queries>
    <intent>
        <action android:name="android.media.action.IMAGE_CAPTURE" />
    </intent>
</queries>

Optional — voice transcription

<uses-permission android:name="android.permission.RECORD_AUDIO" />
<uses-permission android:name="android.permission.MODIFY_AUDIO_SETTINGS" />

Below are the necessary imports before initializing the Spotchecks.

import com.surveysparrow.surveysparrow_android_sdk.SpotCheck
import com.surveysparrow.surveysparrow_android_sdk.trackEvent
import com.surveysparrow.surveysparrow_android_sdk.SpotCheckConfig
import com.surveysparrow.surveysparrow_android_sdk.trackScreen
import com.surveysparrow.surveysparrow_android_sdk.spotCheckListener //callback functions

Initialization

• SpotCheckConfig needs to be declared in the composable function

Anonymous users

If you wish not to keep track of users' data, you can follow the below syntax for initialization.

val context = LocalContext.current 
val spotCheckConfig = remember {
 SpotCheckConfig(
   domainName = "<your_domain>",
   targetToken = "<target_token>", 
   userDetails = hashMapOf(),
   variables = mapOf(
       "sparrowLang" to "ta" // Eg: ta, en
   ),
   customProperties = mapOf(), 
   preferences = context.getSharedPreferences("spotcheck", Context.MODE_PRIVATE)// Mandatory for Anonumous Users
 )
}

Known Users

If you wish to keep track of users' data and perform conditional Survey triggers, you can follow the below syntax for initialization.

val spotCheckConfig = remember {
 SpotCheckConfig(
   domainName = "<your_domain>",
   targetToken = "<target_token>", 
   variables = mapOf(
       "sparrowLang" to "ta", // Eg: ta, en,
       "<api_identifier_of_variable>" to "<variable_value>"
   ),
   customProperties = mapOf(
       "<custom_property_name>" to "<custom_property_value>"
   ), 
   userDetails = hashMapOf(
       "email" to "[email protected]",
       "firstName" to "<your-first-name>",
       "lastName" to "<your-last-name>",
       "mobile" to "<user_mobile>",
       "uuid" to "<uuid_value>" // Optional
   )
  )
}

• Then, add the SpotCheck Composabe Function to all the screens where you want to display the surveys.

@Composable
fun SpotCheckScreen(spotCheckConfig: SpotCheckConfig) {
    Scaffold() {}
    SpotCheck(spotCheckConfig)
}

Note: Add the spotCheckConfig variable outside of the scaffold.

Screen Track

It provides the ability to keep track of screens the users are visiting and to enable the survey trigger on that screen.

Syntax:

LaunchedEffect(Unit) {
    trackScreen(screen= "ScreenName", config = spotCheckConfig)
}

Example:

If a survey needs to be triggered on the payment page, the name of the ScreenName should be specified in the TrackScreen function.

LaunchedEffect(Unit) {
    trackScreen(screen= "paymentScreen", config = spotCheckConfig)
}

Event Track

It provides the ability to keep track of events which when triggered, will enable the survey to be popped.

Syntax:

spotCheck.trackEvent("ScreenName", {"EventName": {}});

Example:

If a survey needs to be triggered when the user completes a payment, then the TrackEvent function should be called with the respective ScreenName and optional custom properties.

spotCheck.trackEvent("paymentScreen", {"paymentComplete": {
    "email":"[email protected]",
    "paymentStatus":true
}});

Make sure to have the eventName configured in the Checks section of the configure panel

Callbacks (Optional)

Callbacks are used to listen to events that are part of the SpotChecks. All callback functions are optional — you can implement only the ones you need. The available callbacks include:

• Survey Response - triggers when the user submits a response.

• Survey Loaded - triggers when the SpotChecks is loaded on the user's page.

• Survey Close - triggers when the SpotChecks is closed by the user.

• Partial Submission - triggers when the PartialSubmission is enabled and recieved.

Syntax:

// Step 1: Add callbacks to the SpotChecks Initialization

val spotCheckConfig = remember {
 SpotCheckConfig(
    //...
    spotCheckListener = spotCheckListener
 )
}

// Step 2: Listen to the SpotChecks events
val spotCheckListener = object : SsSpotcheckListener {
        override suspend fun onSurveyLoaded(response: Map<String, Any>) {}

        override suspend fun onSurveyResponse(response: Map<String, Any>) {}

        override suspend fun onCloseButtonTap() {}

        override suspend fun onPartialSubmission(response: Map<String, Any>) {}
    }