Survicate Android SDK

The Survicate Android SDK will increase your app's size by approximately 4MB when obfuscated and uncompressed. Note that the SDK features a Time To Live (TTL) mechanism of 60 seconds. This means any modifications made to your survey will be reflected on your respondents' devices after a delay of up to 60 seconds.

Requirements:

  • Using Survicate Mobile SDK requires an account at survicate.com. You can create your account here for free, or become invited to your company account by one of your colleagues.
  • Android Gradle plugin in version 3.0.0+.
  • Compatibility with Java 8 language features.
  • Respondent's device running Android version 5 or above.

Installation

Installing using Maven

The recommended installation method.

  1. Define https://repo.survicate.com Maven repository in one of the following ways:
  1. Add Survicate SDK dependency to your app's build.gradle file.

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:
Show dependencies

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.

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.

ProGuard (optional)

The SDK provides built-in proguard rules, so you don't have to specify them manually.

Included rules

Since 2.0.0 Survicate Android SDK depends on Coil library. Please refer to Coil website for more information about their proguard rules.

We recommend using the most recent version of Gradle with R8 enabled in gradle.properties file:


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

Note: Multiple active screens are allowed. In specific, calling enterScreen() does not make the previous screen to be discarded. Be sure to call leaveScreen() when you no longer want the screen to be treated as active.

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 show instantly after an event occurs in your app.

Event name and property keys are 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).
  • Target surveys to specific users with Audience filters.
  • Recall information in survey questions (e.g. include user name).
  • Filter survey results.

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.

Attribute types

  • String: any text, e.g. user name or e-mail.
  • Number: an integer or decimal.
  • Boolean: a logic value.
  • Date: a java.util.Date that can be used in date or time interval filters (the latter measure elapsed time from a given timestamp).

Special attributes

  • user_id: This corresponds to the "Logged-in status" in the panel's Audience filter. A user is considered logged-in when a trait with the "user_id" key has been set on the device, regardless of the value.

  • first_name, last_name, email: If none of these is specified, a response will be marked as Anonymous in the panel.

Additional notes

  • You can freely use custom attribute keys without the need to register them anywhere.

  • In some panel functionalities (e.g. autocompletion), the attribute key will be available only after a survey response with the given attribute is uploaded (unless the key was added in the panel manually). By that time, the trait is saved only locally on the user's device.

  • Note that the predefined attribute classes (UserTrait.UserId, UserTrait.FirstName, etc.) have been deprecated in version 4.0. Instead, you should use the UserTrait(key, value) constructor. You will find migration details in the deprecation messages.

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

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

Deprecation note: The Survicate.setEventListener method has been deprecated since version 4.1.0. You should use the addEventListener and removeEventListener methods instead.

SurvicateAnswer properties (QuestionAnsweredEvent.answer)

PropertyTypeDescription
typeStringAnswer type. One of: ['text', 'single', 'multiple', 'smiley_scale', 'rating', 'csat', 'numerical_scale', 'nps', 'date', 'form', 'matrix', 'button_close', 'button_next', 'button_link'].
idLong?Answer ID. Applicable only for types: ['single', 'smiley_scale', 'csat', 'rating', 'numerical_scale'].
idsSet<Long>?Selected answer IDs. Applicable only for type = ['multiple'].
valueString?Text representation of an answer, e.g. "Happy" for smiley scale. Not applicable for call-to-action answers: ['button_close', 'button_next', 'button_link'].

The id, ids and value properties are provided 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

5.3.0 (2024-09-12)

New
Once an event is invoked in the app, its name and property names are also sent to Survicate’s panel now. They will be shown as suggestions when a user configures event targeting of a survey.

5.2.0 (2024-09-04)

New
New conditions are available in event targeting:
Time delay after event occurrence
Number of event occurrences
Time of the first occurrence
Time of the last occurrence
If multiple conditions are applied, all of them should be met for a survey to appear.

5.1.1 (2024-07-25)

Improved
More distinguishable emojis in the 3-choice Smiley scale.
Fixed
Excessive spacing between Smiley scale emojis in the 3-choice layout.
Back button icon color on dark backgrounds.
An issue where "Submit" was displayed instead of "Start Survey" on the welcome CTA point after navigating back to it.

5.1.0 (2024-07-17)

New
Navigation buttons are available now. When enabled, your survey respondents can go back to the previous questions, see their selected answers, and change them if necessary.
Improved
Higher resolution of Smiley scale icons.
Fixed
Propagating Matrix answer in SurvicateAnswer.value of event listener.
An issue that resulted in unexpected vertical padding for Matrix question in full screen mode.

5.0.0 (2024-06-10)

New
Matrix question type added.
Updated
AndroidX Annotation to 1.8.0
Coroutines Android to 1.8.1
Fixed
UI state bugs related to Activity's configuration changes.
Animation resource names that could conflict with resources of the app or other libraries.

4.4.0 (2024-04-30)

New
New targeting option available - event properties. You can add multiple properties to one event and join them with either “or” or “and” operator.
Property names and values are case-sensitive. Only string values are supported.
Updated
AndroidX Annotation to 1.7.1
Coroutines Android to 1.8.0
Moshi to 1.15.1
Fixed
A bug that could prevent a survey from being displayed if a delay was set for multiple screens in the panel.
Horizontal mode support for Numerical Rating question for up to 5 items.

4.3.0 (2024-03-26)

New
More flexible survey recurring options are available now. Now you can specify how many days / weeks / months / years should pass before the survey can appear again. It’s also possible to set after how many days / weeks / months / years the survey should stop recurring.
If you run several mobile surveys, now you can use survey throttling settings to specify a time frame that should pass between showing them. Use global throttling to set the same time frame for all your mobile surveys. Or use the survey level throttling to override the global settings and specify a different period before showing a particular survey.

4.2.0 (2024-03-15)

New
New targeting filter is available - screen orientation (portrait mode or landscape mode targeting). You can either include or exclude one of the orientation modes.

4.1.1 (2024-02-26)

Improved
Performance enhancements in answers synchronization.
Support the milliseconds part when parsing ISO date-time strings within a UserTrait.

4.1.0 (2024-02-08)

New
Events like onSurveyDisplayed, onQuestionAnswered, onSurveyClosed, and onSurveyCompleted now utilize specific event objects: SurveyDisplayedEvent, QuestionAnsweredEvent, SurveyClosedEvent, SurveyCompletedEvent.
The SDK now supports the registration of multiple event listeners.
Updated
Reverted Coil to version 2.4.0 for better compatibility with cross-platforms (compileSdk 34 is no longer required).
Fixed
An issue where SurveyActivity could crash when it was restored after process termination.
A race condition in the recalling feature.

4.0.2 (2024-01-09)

This version requires compileSdkVersion to be at least 34. If you are not ready to use API level 34, please stay on the Survicate version 3.0.4.
Improved
Date format in user traits recalling
Fixed
A bug where users could see survey more times than specified in recurrence settings if SDK was updated in meantime
Sending user attributes to backend only when necessary

4.0.1 (2023-12-11)

This version requires compileSdkVersion to be at least 34. If you are not ready to use API level 34, please stay on the Survicate version 3.0.4.
Updated
Use NetworkCapabilities to check internet connection (API 24+)
Migrate to WindowCompat APIs for setting full screen background
Fixed
Issue with recurring period calculation

4.0.0 (2023-11-30)

This version requires compileSdkVersion to be at least 34. If you are not ready to use API level 34, please stay on the Survicate version 3.0.4.
New
User conditions targeting is changed to the audience targeting: create an audience that will be available for usage among all your mobile surveys. Enable multiple audiences at the same time in one survey if necessary
User attributes now support not only string values but also numbers, boolean, and datetime values
New attribute operators are available to support new data types
Survey audience can be set not only by including a set of respondents who met the required criteria but also by excluding those who should not see the survey
And / or operators in audience targeting are switchable now: within one attribute filter that has several attributes in it and between different filters
Fixed
Fixed invalid survey closing when app has specified android:enableOnBackInvokedCallback="true" in the AndroidManifest.xml

3.0.6 (2023-11-28)

Updated
This version requires compileSdkVersion to be at least 34. If you are not ready to use API level 34, please stay on the Survicate version 3.0.4.
Creating User Trait requires non null key
Added a Proguard rule for User Traits
Fixed
An issue with saving User Traits that could cause crash whenever saved User Trait key was null

3.0.5 (2023-11-20)

Updated
This version requires compileSdkVersion to be at least 34. If you are not ready to use API level 34, please stay on the Survicate version 3.0.4.
AGP to 8.1.2
Kotlin to 1.9.10
AndroidX RecyclerView to 1.3.2
Coil to 2.5.0
Fixed
An issue where answers saved without internet were not synchronized in next app sessions.
An issue with javadoc generation.

3.0.4 (2023-10-25)

Updated
Android TargetSdk to 33
AndroidX Appcompat to 1.6.1
AndroidX RecyclerView to 1.3.1
AndroidX Annotation to 1.7.3
Moshi to 1.15.0
Coil to 2.4.0
Fixed
An issue where workspaceKey metadata was not provided in AndroidManifest.xml would cause a crash.

3.0.3 (2023-09-27)

Fixed
Added image scaling to shapes rating questions to fit all answers on the screen in horizontal layout
Fixed issue on Thank You question with button's title not using text from survey settings

3.0.2 (2023-08-11)

Fixed
Issue where in some cases survey was not dismissible

3.0.1 (2023-08-08)

Updated
AGP version to 8.1.0
Gradle version to 8.1.1
Kotlin version to 1.8.22
Removed Material Design dependency

3.0.0 (2023-07-25)

New
New logic settings have been added to all question types (except Welcome message, Date and Thank you screen).

2.4.0 (2023-07-11)

New
Now it's possible to select how to position answer choices in the NPS question: vertically (default option) or horizontally.
Fixed
An issue in recurring surveys where in some cases survey progress was calculated incorrectly.
Adjusted text color for nps descriptions in classic theme.
Adjusted text color for forms disclaimer in classic theme.

2.3.2 (2023-06-06)

Fixed
An issue when it was not possible to filter survey responses by language in the panel.
An issue where after synchronization failure the SDK was not respecting refresh interval.
An issue in rating scale questions where in some cases UI was not displayed correctly.

2.3.1 (2023-05-25)

Fixed
An issue where recalling fallback value was not respected when related text answer is blank.

2.3.0 (2023-05-25)

New
Now while adding introduction or question texts you can recall information from attributes passed to Survicate or from answers to other questions in the survey.
Updated
Updated Moshi to 1.13.0
Fixed
An issue that could cause an ANR during SDK initialization.

2.2.0 (2023-05-04)

New
Surveys can be translated into an app language if a corresponding translation is added in the panel.
Fixed
On SDK initialization survey cache is cleared now, and only surveys fetched from the server are shown.

2.1.1 (2023-04-18)

Updated
Close animation for standard theme surveys.
Fixed
An issue where one survey in a session flag was not respected.
An issue where surveys delay trigger timer was restarted after any other screen or event was triggered.

2.1.0 (2023-04-06)

New
Rating question type added.
Question and introduction texts can be made bold, italics, or hyperlinked.
New look of a date picker in the date question type.

2.0.1 (2023-03-14)

Updated
Updated proguard rules.
Improved
When using R8 proguard rules are included automatically.

2.0.0 (2023-03-09)

New
21 new design themes.
2 new survey settings - “Progress bar” and “Remove Survicate branding”.
New customization options: add a company's logo or a survey sender's avatar and a greeting message from them.

1.7.7 (2023-02-14)

Improved
Accuracy of survey sampling.

1.7.6 (2023-01-17)

Update
Remove character limit from text fields.

1.7.5 (2023-01-09)

Updated
Removed explicit setting of usesCleartextTraffic flag in Survicate SDK manifest file.

1.7.4 (2022-10-25)

Fixed
An issue causing concurrency-related exceptions when initializing Survicate.

1.7.3 (2022-10-12)

Fixed
An issue in Single Answer Question where in some cases switching from answer with comment with focus on input to answer without comment would cause a crash.
Fixed
An issue where surveys with triggering by screen and events would not show.

1.7.2 (2022-09-20)

Fixed
An issue causing NPS button labels to be displayed in incorrect colors.

1.7.1 (2022-09-14)

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

1.7.0 (2022-09-07)

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

1.6.5 (2022-08-04)

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

1.6.3 (2022-06-15)

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

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.