Link Search Menu Expand Document

Survicate Android SDK

Platform Maven

Table of contents

  1. Installation
    1. Installing using Maven
    2. Installing manually
  2. Configuration
    1. ProGuard configuration of Survicate Android SDK
    2. setWorkspaceKey() method
  3. Using Android SDK
    1. Targeting a survey by screen name
    2. Events-based survey targeting
    3. User identification & attributes
    4. Reseting user data for testing purposes
    5. Event listeners
  4. Changelog

Installation

Requirements: Survicate Mobile SDK works with respondent devices using Android version 4.4+

Installing using Maven

The recommended installation method.

  1. Define https://repo.survicate.com Maven repository in project’s build.gradle file. Make sure that the repository is defined in allprojects section, not buildscript.
  2. Add com.survicate:survicate-sdk:1.+ dependency to your app’s build.gradle file.

Note: When configuring the SDK on a production environment, we recommended defining the exact SDK version. To achieve it, replace the last part of dependency, 1.+, with the exact number of the version you want to use.

Project’s build.gradle

allprojects {
    repositories {
        // ...
        maven { url 'https://repo.survicate.com' }
    }
}

App’s build.gradle for Maven installation

dependencies {
    // ...
    implementation 'com.survicate:survicate-sdk:1.+'
}

Installing manually

  1. Download Survicate for Android
  2. Copy Survicate.aar to app/libs directory of your project.
  3. Add dependencies for manual installation to your app’s build.gradle file.

App’s build.gradle for manual installation

dependencies {
    // ...
    implementation files('libs/Survicate.aar')
    implementation 'androidx.appcompat:appcompat:1.4.1'
    implementation 'androidx.cardview:cardview:1.0.0'
    implementation 'androidx.recyclerview:recyclerview:1.2.1'
    implementation 'androidx.constraintlayout:constraintlayout:2.1.3'
    implementation "androidx.transition:transition:1.4.1"
    implementation "androidx.annotation:annotation:1.3.0"
    implementation "com.google.android.material:material:1.5.0"
    implementation "com.squareup.moshi:moshi:1.12.0"
    implementation "com.squareup.moshi:moshi-kotlin:1.12.0"
}

Note: Keep in mind that when updating the version by manual installation, you need to update SDK dependencies versions too.


Configuration

The following configuration will require workspace key. You can get your workspace key in the Access Keys section of the Survicate panel.

  1. Configure your workspace key in AndroidManifest.xml file. Create meta-data: com.survicate.surveys.workspaceKey.
  2. Initialize the SDK in your application class using init() method. If your project doesn’t have a custom application class yet, you’ll need to create one. Make sure that your custom application class is defined in AndroidManifest.xml.

AndroidManifest.xml

<application
    android:name=".MyApp"
>
    <!-- ... -->
    <meta-data android:name="com.survicate.surveys.workspaceKey" android:value="YOUR_WORKSPACE_KEY"/>
</application>

Application class

Kotlin Java

import android.app.Application
import com.survicate.surveys.Survicate

class MyApp : Application() {
    override fun onCreate() {
        super.onCreate()
        Survicate.init(this)
    }
}   
import android.app.Application;
import com.survicate.surveys.Survicate;

public class MyApp extends Application {
  @Override public void onCreate() {
    super.onCreate();
    Survicate.init(this);
  }
}   

ProGuard (optional)

If your application uses ProGuard, add the following rules to your proguard-rules.pro file:

-keep @com.squareup.moshi.JsonQualifier class *
-keep public class com.survicate.surveys.entities.**
-keep public class com.survicate.surveys.infrastructure.network.**
-keep public class com.survicate.surveys.infrastructure.serialization.**

Make sure that you have the latest Gradle version with R8 enabled in gradle.properties file:

android.enableR8=true

ProGuard configuration of Survicate Android SDK

The ProGuard configuration of the Survicate SDK looks as follows:

  • SDK has shrinking, obfuscation and optimization enabled in the build.gradle file
  • SDK refers under the hood to the Moshi, and all public elements of Moshi are excluded in the ProGuard config
  • Config contains the following flags:
-printmapping out.map
-keepparameternames
-renamesourcefileattribute SourceFile
-keepattributes Exceptions,InnerClasses,Signature,Deprecated,
                SourceFile,LineNumberTable,EnclosingMethod
-repackageclasses
  • Config also:

    • preserves all annotations
    • preserves all public classes, and their public and protected fields and methods
    • preserves all .class method names
    • preserves all native method names and the names of their classes
    • preserves the special static methods that are required in all enumeration classes
    • explicitly preserve all serialization members

setWorkspaceKey() method

As an alternative to the main way of specifying the Workspace Key, you can also use the setWorkspaceKey() method.

Important:

  • Using setWorkspaceKey() method overrides the Workspace Key defined in the configuration.
  • setWorkspaceKey() method must be used before init() method is called.

Kotlin Java

Survicate.setWorkspaceKey("your_workspace_key")
Survicate.setWorkspaceKey("your_workspace_key");

Using Android SDK

Survicate allows you to launch precisely targeted surveys inside your app. In the Survicate Panel, you can set conditions that need to be met for the surveys to appear. Users matching conditions defined in the Survicate panel will see the survey automatically. Here’s a list of conditions you can use to target your surveys:

  • Name of the screen that a user currently sees
  • Any application event
  • User attributes and identities
  • Device language
  • Operating system

Make sure to list all the screens and events described in your application. Once you got this covered, you or any person responsible for creating and managing surveys will be able to trigger surveys from the Survicate panel with no need for you to update the application.

Warning Warning The SDK utilizes SharedPreferences to store information used by the targeting engine described in this section. Clearing SharedPreferences will cause the targeting system to malfunction; f.e. by showing the same survey twice to a single user.

Targeting a survey by screen name

A survey can appear when a user is viewing a specific screen. For example, a survey can be triggered to show up on the application’s home screen after a user spends more than ten seconds there. To set it up, you need to send information to Survicate about the user entering and leaving a screen.

Kotlin Java

class PurchaseSuccessActivity : Activity() {

    val SCREEN_NAME = "purchaseSuccess"

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        // ...
        Survicate.enterScreen(SCREEN_NAME)
    }

    override fun onDestroy() {
        super.onDestroy()
        Survicate.leaveScreen(SCREEN_NAME)        
    }
}
public class PurchaseSuccessActivity extends Activity {

    public static final String SCREEN_KEY = "purchaseSuccess";

    @Override
    protected void onCreate(@Nullable Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        // ...
        Survicate.enterScreen(SCREEN_KEY);
    }

    @Override
    protected void onDestroy(){
        super.onDestroy();
        Survicate.leaveScreen(SCREEN_KEY);
    }

}

Screen name is case sensitive. If there’s any discrepancy between what’s declared in the ‘Screens’ tab of the Target section in the Survicate panel and the application code, the survey will not appear.

Events-based survey targeting

Survicate Android SDK allows you to launch surveys based on events your users trigger in your app. Your survey will instantly after an event occurs in your app.

Kotlin Java

button.setOnClickListener {
    Survicate.invokeEvent("userPressedPurchase")
}
purchaseBtn.setOnClickListener(new View.OnClickListener() {
    public void onClick(View v) {
        // ...
        Survicate.invokeEvent("userPressedPurchase");
    }
});

Event name is case sensitive. If there is any discrepancy between what’s declared in the ‘Triggers’ tab of the Target section in the Survicate panel and the application code, the survey will not appear.

User identification & attributes

You can pass user attributes to Survicate as an additional layer of information about your users. Attributes can be used to:

  • Identify respondents (by default survey responses are anonymous)
  • Trigger surveys
  • Filter survey results

Kotlin Java

val traits = ArrayList<UserTrait>()
traits.add(UserTrait.UserId("YourUserID"))
traits.add(UserTrait.FirstName("John"))
traits.add(UserTrait("subscription_status", "active"))
Survicate.setUserTraits(traits)

// or just
Survicate.setUserTrait(UserTrait.UserId("someOtherUserId"))
List<UserTrait> traits = new ArrayList<>();
traits.add(new UserTrait.UserId("YourUserID"));
traits.add(new UserTrait.FirstName("John"));
traits.add(new UserTrait("subscription_status", "active"));
Survicate.setUserTraits(traits);

// or just
Survicate.setUserTrait(new UserTrait.UserId("someOtherUserId"));

Bear in mind that user attributes are cached. You only need to provide them once, e.g. when user logs in, not after each init(). You can also change their values at any time to trigger a survey.

Reseting user data for testing purposes

If you need to test surveys on your device, reset() method might be helpful. This method will reset all user data stored on your device (survey views, attributes, information about answered surveys for the targeting engine).

Kotlin Java

Survicate.reset()
Survicate.reset();

Event listeners

SDK allows you to utilize event listeners. You may find them useful to trigger actions in your application based on actions performed by respondents. Here’s a list of events you can subscribe to:

  • survey_displayed - occurs when survey is loaded and appears in the User Interface
  • question_answered - occurs after a question is answered ( Survicate stores incomplete survey submissions )
  • survey_closed - occurs when a user closes the survey using the close button
  • survey_completed - occurs when a user finishes the survey

Kotlin Java

Survicate.setEventListener(object: SurvicateEventListener() {
    override fun onSurveyDisplayed(surveyId: String) {
        Toast.makeText(this@MainActivity, "on survey displayed", Toast.LENGTH_SHORT).show()
    }
    override fun onQuestionAnswered(surveyId: String, questionId: Long, answer: SurvicateAnswer) {
        Toast.makeText(this@MainActivity, "on question answered", Toast.LENGTH_SHORT).show()
    }
    override fun onSurveyClosed(surveyId: String) {
        Toast.makeText(this@MainActivity, "on survey closed", Toast.LENGTH_SHORT).show()
    }
    override fun onSurveyCompleted(surveyId: String) {
        Toast.makeText(this@MainActivity, "on survey completed", Toast.LENGTH_SHORT).show()
    }
})
Survicate.setEventListener(new SurvicateEventListener() {
    @Override
    public void onSurveyDisplayed(@NonNull String surveyId) {
        Toast.makeText(MainActivity.this, "on survey displayed", Toast.LENGTH_SHORT).show();
    }
    @Override
    public void onQuestionAnswered(@NonNull String surveyId, long questionId, @NonNull SurvicateAnswer answer) {
        Toast.makeText(MainActivity.this, "on question answered", Toast.LENGTH_SHORT).show();
    }
    @Override
    public void onSurveyClosed(@NonNull String surveyId) {
        Toast.makeText(MainActivity.this, "on survey closed", Toast.LENGTH_SHORT).show();
    }
    @Override
    public void onSurveyCompleted(@NonNull String surveyId) {
        Toast.makeText(MainActivity.this, "on survey completed", Toast.LENGTH_SHORT).show();
    }
});

SurvicateAnswer object properties

Property Type Description
type string Answer type.
id integer Answer ID. Applicable only for type = [‘single’, ‘smiley_scale’, ‘dropdown_list’].
ids integer[] Array of answer IDs. Applicable only for type = [‘multiple’].
value string Context value of the answer. Applicable only for type = [‘text’, ‘nps’, ‘date’, ‘rating’].

Note: at the moment we support passing the id, ids and value properties only for the cases enlisted in the table above. Therefore, expect that there might be answer objects that consist only of the type property.


Changelog

1.6.3 (2022-06-15)

Fixed
Tracking the SDK version for internal purposes.
Fixed
Memory leak on the Survicate SDK backend communication.

1.6.1 (2022-05-27)

Fixed
A bug causing SDK to crash when using custom audience targeting.

1.6.0 (2022-05-20)

New
Detailed answer value for the Smile scale question is provided in the Question answered event listener.

1.5.15 (2022-05-17)

Fixed
A bug causing SDK to crash when using event based targeting in some particular cases.

1.5.14 (2022-04-25)

Fixed
Memory leaks on the Survicate SDK backend communication.

1.5.13 (2022-04-13)

Fixed
Crash in landscape mode on the NPS screen.

1.5.12 (2022-03-21)

Fixed
ProGuard configuration has been improved to avoid exceptions.

1.5.11 (2022-03-18)

Fixed
A bug causing SDK to crash when using event based targeting in some particular cases.

1.5.10 (2022-03-15)

Fixed
In some cases it was possible that the survey would reappear to some respondents (when it shouldn’t).

1.5.9 (2022-03-03)

Updated
Version of gradle used to build SDK is now bumped to 7.2.

1.5.8 (2022-02-18)

Fixed
When setting the survey to appear to less than 1% of targeted users, the survey was not displayed. In general, the audience sampling feature in the targeting engine had issues with interpreting numbers with decimal points.

1.5.7 (2022-02-04)

Fixed
ProGuard configuration has been improved to avoid exceptions.
Updated
Survey settings Time to Live(TTL) reduced to 10 minutes.

1.5.6 (2022-01-20)

Fixed
In some cases, loading survey data from device storage caused the application to crash.

1.5.5 (2022-01-13)

Fixed
In some cases using survey background overlay caused the application to crash.

1.5.3 (2021-12-10)

Updated
Improved initialization time on the Survicate SDK startup.

1.5.2 (2021-12-03)

Fixed
Memory leaks and initialization time on the Survicate SDK startup.

1.5.1 (2021-12-02)

Fixed
In some scenarios, respondents were asked to answer only the last survey question.

1.5.0 (2021-11-18)

New
Surveys can now be set to appear on a recurring basis. This means respondents can answer the same mobile survey again, and again - on a daily, weekly, monthly, or quarterly basis.
Fixed
Crashing caused by missing overlay theme.

1.4.5 (2021-10-26)

New
Scale labels can now be displayed below the smiley scale question

1.4.4 (2021-10-21)

New
Survey settings Time to Live(TTL) mechanism on respondent's device. The mechanism ensures that the survey settings are up to date on the respondent's side. If the current version of survey settings is older than 60 minutes, the survey configuration is checked for updates.
Fixed
Memory leaks on the list based questions views.

1.4.3 (2021-09-30)

Fixed
A bug causing SDK to crash when the survey was about to appear in some cases.

1.4.2 (2021-09-29)

New
The method setWorkspaceKey() allows to specify Survicate workspace key from code.

1.4.1 (2021-09-23)

New
Native support for Android X
Fixed
ProGuard configuration has been improved to avoid exceptions.
Please refer to the documentation to see, how to configure Survicate SDK with ProGuard.

1.3.0 (2021-06-15)

New
SDK uses currently respondent API v3 endpoints

1.2.5 (2021-03-24)

Fixed
Visual bugs with padding and font size on CTA questions.

1.2.4 (2021-01-29)

Fixed
A bug causing SDK to malfunction when it was initialized multiple times.

1.2.3 (2020-12-23)

Fixed
When taping two answers simoultaneously SDK crashed on some devices.

1.2.2 (2020-09-22)

New
It’s now possible to suppress a survey if other was answered during the current visit to your app.

1.2.1 (2020-06-17)

Fixed
A bug causing SDK to crash when the “Survey invitation” question had “next step” logic branching configured.

1.2.0 (2020-04-22)

Fixed
A bug causing surveys not to appear when targeted only at logged in users.
Fixed
A minor issue causing the survey not to appear when targeted at multiple values of the same attribute.

1.1.2 (2020-03-05)

Fixed
Minor bug causing issues when targeting with user traits.
Fixed
Proper handling of 4xx error codes.
Updated
Unnecessary spacing on the left side of the question has been removed.
New
It's now possible to clear user trait by setting them to 'null' value.

1.1.1 (2020-02-11)

Fixed
SDK listeners - answer object fixes.

1.1.0 (2020-01-24)

New
SDK now supports listeners.

1.0.19 (2019-12-23)

New
SDK now supports survey completion rate.

1.0.18 (2019-12-19)

Fixed
Survey ends after Thank you message and CTA.

1.0.17 (2019-09-04)

Updated
SDK now supports new installation flow.

1.0.16 (2019-08-12)

Fixed
Survey close counters weren't functioning properly in some cases.

1.0.15 (2019-08-08)

Fixed
reset() method didn't clear user attributes.

1.0.14 (2019-08-07)

Fixed
Targeting surveys using multiple user attributes wasn't working.

1.0.13 (2019-06-05)

Fixed
Building React Native project couldn't be completed in some cases.

1.0.12 (2019-04-01)

Fixed
Survey logic was broken when next step was set up to "Finish".

1.0.11 (2019-03-20)

Fixed
Targeting over screen name did't work when screen delay was set up.

1.0.10 (2019-03-08)

Fixed
View & response counters weren't functioning properly in some cases.

👋 If you bump into any problems or need more support, just start a conversation using Intercom in the bottom-right corner and you will be immediately routed to our Customer Support Engineers.