Survicate Android SDK

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.

Define https://repo.survicate.com Maven repository in one of the following ways:

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.

Installing manually

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

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.

Configure your workspace key in AndroidManifest.xml file. Create meta-data: com.survicate.surveys.workspaceKey.
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)

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

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

Make sure that you have the latest Gradle version 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 instantly after an event occurs in your app.

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

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

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

SurvicateAnswer object properties

Property	Type	Description
type	string	Answer type.
id	integer	Answer ID. Applicable only for type = ['single', 'smiley_scale', 'dropdown_list', 'rating'].
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'].

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

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.