Skip to main content Link Search Menu Expand Document (external link)

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



The development environment of the Android mobile app utilizing Survicate Mobile SDK requires:

Survicate Mobile SDK works with respondent devices using Android version 5+.

Installing using Maven

The recommended installation method.

  1. Define 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 '' }

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


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.


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

Application class

Kotlin Java

import com.survicate.surveys.Survicate

class MyApp : Application() {
    override fun onCreate() {
import com.survicate.surveys.Survicate;

public class MyApp extends Application {
  @Override public void onCreate() {

ProGuard (optional)

If your application uses ProGuard, add the following rules to your file:

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

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


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:
-renamesourcefileattribute SourceFile
-keepattributes Exceptions,InnerClasses,Signature,Deprecated,
  • 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.


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

Kotlin Java


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?) {
        // ...

    override fun onDestroy() {
public class PurchaseSuccessActivity extends Activity {

    public static final String SCREEN_KEY = "purchaseSuccess";

    protected void onCreate(@Nullable Bundle savedInstanceState) {
        // ...

    protected void onDestroy(){


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 {
purchaseBtn.setOnClickListener(new View.OnClickListener() {
    public void onClick(View v) {
        // ...

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("subscription_status", "active"))

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

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


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() {
    public void onSurveyDisplayed(@NonNull String surveyId) {
        Toast.makeText(MainActivity.this, "on survey displayed", Toast.LENGTH_SHORT).show();
    public void onQuestionAnswered(@NonNull String surveyId, long questionId, @NonNull SurvicateAnswer answer) {
        Toast.makeText(MainActivity.this, "on question answered", Toast.LENGTH_SHORT).show();
    public void onSurveyClosed(@NonNull String surveyId) {
        Toast.makeText(MainActivity.this, "on survey closed", Toast.LENGTH_SHORT).show();
    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.


1.7.2 (2022-09-20)

An issue where NPS scores texts weren't properly colored.

1.7.1 (2022-09-14)

An issue causing concurrency-related exceptions when processing survey data.
Memory leak when closing a survey.

1.7.0 (2022-09-07)

An issue causing exceptions on Android 6 and lower.
The minimum supported version of Android changed to 5 (API 21).

1.6.5 (2022-08-04)

An issue causing concurrency-related exceptions when responses were processed to the server.
Removed TLSv1.1 and added TLSv1.3 support.
Answers for smiley scale questions could be not stored.

1.6.3 (2022-06-15)

Tracking the SDK version for internal purposes.
A bug causing SDK to send single answer multiple times in some edge case scenarios.

1.6.1 (2022-05-27)

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

1.6.0 (2022-05-20)

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

1.5.15 (2022-05-17)

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

1.5.14 (2022-04-25)

Memory leaks on the Survicate SDK backend communication.

1.5.13 (2022-04-13)

Crash in landscape mode on the NPS screen.

1.5.12 (2022-03-21)

ProGuard configuration has been improved to avoid exceptions.

1.5.11 (2022-03-18)

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

1.5.10 (2022-03-15)

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

1.5.9 (2022-03-03)

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

1.5.8 (2022-02-18)

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)

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

1.5.6 (2022-01-20)

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

1.5.5 (2022-01-13)

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

1.5.3 (2021-12-10)

Improved initialization time on the Survicate SDK startup.

1.5.2 (2021-12-03)

Memory leaks and initialization time on the Survicate SDK startup.

1.5.1 (2021-12-02)

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

1.5.0 (2021-11-18)

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.
Crashing caused by missing overlay theme.

1.4.5 (2021-10-26)

Scale labels can now be displayed below the smiley scale question

1.4.4 (2021-10-21)

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.
Memory leaks on the list based questions views.

1.4.3 (2021-09-30)

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

1.4.2 (2021-09-29)

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

1.4.1 (2021-09-23)

Native support for Android X
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)

SDK uses currently respondent API v3 endpoints

1.2.5 (2021-03-24)

Visual bugs with padding and font size on CTA questions.

1.2.4 (2021-01-29)

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

1.2.3 (2020-12-23)

When taping two answers simoultaneously SDK crashed on some devices.

1.2.2 (2020-09-22)

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)

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

1.2.0 (2020-04-22)

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

1.1.2 (2020-03-05)

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

1.1.1 (2020-02-11)

SDK listeners - answer object fixes.

1.1.0 (2020-01-24)

SDK now supports listeners.

1.0.19 (2019-12-23)

SDK now supports survey completion rate.

1.0.18 (2019-12-19)

Survey ends after Thank you message and CTA.

1.0.17 (2019-09-04)

SDK now supports new installation flow.

1.0.16 (2019-08-12)

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

1.0.15 (2019-08-08)

reset() method didn't clear user attributes.

1.0.14 (2019-08-07)

Targeting surveys using multiple user attributes wasn't working.

1.0.13 (2019-06-05)

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

1.0.12 (2019-04-01)

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

1.0.11 (2019-03-20)

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

1.0.10 (2019-03-08)

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.