Survicate React Native 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.
Your React Native application can be used in Expo and React Native CLI. Please note that due to custom native code in this package "Expo Go" is not available.
Additionally, please check iOS and Android library requirements, as they're applicable too.
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.

Apps using Survicate SDK after February 1st 2025 will require:

React Native:

Using Survicate SDK version 4.0.0 or higher (versions below 4.0.0 are reaching EoL).
We recommend using React Native version 0.70.0 or higher.

Android:

CompileSdk version 34 or higher (for Survicate SDKs released after February 1st 2025).
Using Android Gradle Plugin version 8.1.1 or higher with compatible Gradle version (for Survicate SDKs released after February 1st 2025).

iOS:

Respondent's device running iOS 14 or higher. (for Survicate SDKs released after February 1st 2025).

Installation in React Native CLI

Mobile SDK is compatible with React Native apps. Use these React Native bindings to install Mobile SDK in your app.

To install run: npm install @survicate/react-native-survicate --save

To create linking for iOS and Android in your react native app run react-native link @survicate/react-native-survicate

Note: Our bindings are compatible with the Autolinking feature introduced in React Native 0.60, so there is no need to run this command on 0.60 and newer versions.

Installation in Expo

To use @survicate/react-native-survicate in an Expo managed project, use npm, yarn or expo-cli.

Configuration

Configuration for Android

Configure your workspace key in AndroidManifest.xml file.
Add the Survicate Maven repository to your project build.gradle located under android directory.

Configuration for iOS

Add workspace key to your Info.plist file.
- Create Survicate Dictionary.
- Define WorkspaceKey String in Survicate Dictionary. Your Info.plist file should looks like this:
Run pod update in your ios directory.

Configuring Survicate Bindings for Expo

Add config plugin to plugins array of your app.json or app.config.js

_Note: Please note that every time you change the props or plugins, you'll need to rebuild the native app.

Initialization

Initialize the SDK in your application using initializeSdk() method. Call this method only once, in the main component (e.g src/App.js file).

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
Language of the device
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.

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

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

Passing user attributes

You can provide user attributes to Survicate as an extra layer of information about your users. The attributes have various use cases:

Identification of survey participants (answers are anonymous by default).
Directing surveys to particular users (Audience filters).
Filtering responses.
Recalling data in questions.

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

Attribute types

string: any text.
number: an integer or decimal.
boolean: a logic value.
Date: a Date object suitable for use with date or time interval Audience filters (the time interval filter measures 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 set your own attribute keys without any prior registration. They will show up in the panel once any response with the attribute is uploaded.

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 properties (QuestionAnsweredEvent.answer)

Property	Type	Description
type	string \| null	Answer type. One of: ['text', 'single', 'multiple', 'smiley_scale', 'rating', 'csat', 'numerical_scale', 'nps', 'date', 'form', 'matrix', 'button_close', 'button_next', 'button_link'].
id	number \| null	Answer ID. Applicable only for types: ['single', 'smiley_scale', 'csat', 'rating', 'numerical_scale'].
ids	number[]	Selected answer IDs. Applicable only for type = ['multiple'].
value	string \| null	Text representation of an answer, e.g. "Happy" for smiley scale. A `null` value in case of a skipped question. 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.5.2 (2024-12-20)

Fixed: Fixed an issue with Android's getNetworkCapabilities method that could occasionally cause exceptions during SDK initialization.
Fixed a crash on iOS caused by non-thread-safe access to localizedDescription during error logging.

5.5.1 (2024-12-10)

Fixed: Fixed an issue on iOS where comments were missing in event listeners.
Fixed an issue on iOS where in Smiley Scale question in some cases the submit button was disabled.
Fixed an issue on iOS with missing submit button in Multiple Answer question.
Fixed an issue on iOS with missing comment field in CSAT question when answer is mandatory.

5.5.0 (2024-12-06)

New: You can now add a comment field to NPS, Smiley scale, Rating scale, Matrix, and Date question types. There is also a comment title available for all comment fields. You can use it to ask a question and give your respondents some context of what you would like to see in the comment.
Updated: AndroidX Annotation to 1.9.1
Coroutines Android to 1.9.0

5.4.0 (2024-10-23)

New: Each question type except Welcome message, Date, and Thank you screen can be set as mandatory or optional.
Improved: Accessibility features for Matrix question, survey progress indicator, and navigation buttons.

5.3.0 (2024-09-13)

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

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.
Updated: Bumping up reference of Android to 5.2.0.
Bumping up reference of iOS to 5.2.0.
Fixed: Fixed an issue with submit button visibility in single choice question on iOS.

5.1.1 (2024-08-01)

Updated: Bumping up reference of Android to 5.1.1.
Bumping up reference of iOS to 5.1.2.
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 on Android.
An issue on Android where "Submit" was displayed instead of "Start Survey" on the welcome CTA point after navigating back to it.
Issue on iOS with non visible Submit button in multiple choice questions.

5.1.0 (2024-07-19)

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 on Android.
Updated: Bumping up reference of Android to 5.1.0.
Bumping up reference of iOS to 5.1.1.
Fixed: Propagating Matrix answer in SurvicateAnswer.value of event listener.
An issue on Android that resulted in unexpected vertical padding for Matrix question in full screen mode.
Configuration json will be printed in console only in verbose log level on iOS.

5.0.0 (2024-06-14)

New: Matrix question type added.
Added setWorkspaceKey method. It is now possible to set workspace key in code
Breaking: Removed initialize method from native modules. In consequence Survicate SDK no longer initializes by itself so please use initializeSdk.
Updated: Bumping up reference of Android to 5.0.0.
Bumping up reference of iOS to 5.0.0.
Fixed: UI state bugs related to Activity's configuration changes.
Animation resource names that could conflict with resources of the app or other libraries on Android.

4.4.0 (2024-05-14)

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: Bumping up reference of Android to 4.4.0.
Bumping up reference of iOS to 4.4.0.
Fixed: Issue with non triggering questionAnswered delegate method in iOS.
A bug in Android 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 in Android.

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.
Updated: Bumping up reference of Android to 4.3.0.
Bumping up reference of iOS to 4.3.0.
Fixed: Issue with recursive display of non-recurring survey on iOS.

4.2.0 (2024-03-19)

New: SDK now supports Expo managed apps.
New targeting filter is available - screen orientation (portrait mode or landscape mode targeting). You can either include or exclude one of the orientation modes.
Updated: Bumping up reference of Android to 4.2.0.
Bumping up reference of iOS to 4.2.0.

4.1.1 (2024-02-29)

Updated: Bumping up reference of Android to 4.1.1.
Added backward compatiblity for AGP below 7.3.
New API for event listeners in native modules.
Improved: Performance enhancements in answers synchronization on Android.
Fixed: Readme update for initialization and listener

4.1.0 (2024-02-16)

New: SDK now supports listeners.
Updated: Bumping up reference of iOS to 4.1.1.

4.0.2 (2024-02-14)

Updated: Bumping up reference of Android to 4.1.0.
Bumping up reference of iOS to 4.1.0.
Fixed: An issue on Android where SurveyActivity could crash when it was restored after process termination.
A race condition on Android in the recalling feature.

4.0.1 (2024-01-23)

Updated: Bumping up reference of Android to 4.0.2.
Bumping up reference of iOS to 4.0.2.
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 in Android
An issue where Thank you screen don't close survey in classic theme in iOS

4.0.0 (2024-01-08)

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
Migrated from DefinitelyTyped types to library types using builder-bob
Breaking: Library types no longer contain initialize method, use initializeSdk instead
Updated: Bumping up reference of Android to 4.0.1.
Bumping up reference of iOS to 4.0.0
Use NetworkCapabilities to check internet connection (API 24+)
Migrate to WindowCompat APIs for setting full screen background
Fixed: Fixed invalid survey closing when app has specified android:enableOnBackInvokedCallback="true" in the AndroidManifest.xml

3.1.2 (2023-12-06)

Update: Bumping up reference of Android to 3.0.6.
Android TargetSdk to 33.
AGP to 8.1.2.
Kotlin to 1.9.10.
AndroidX Appcompat to 1.6.1.
AndroidX RecyclerView to 1.3.2.
AndroidX Annotation to 1.7.3.
Moshi to 1.15.0.
Coil to 2.4.0.
Creating User Trait requires non null key.
Added a Proguard rule for User Traits.
Fixed: An issue where workspaceKey metadata was not provided in AndroidManifest.xml would cause a crash.
An issue where answers saved without internet were not synchronized in next app sessions.
An issue with javadoc generation.
An issue with saving User Traits that could cause crash whenever saved User Trait key was null.

3.1.0 (2023-09-28)

New: Support for React Native New Architecture.
Update: Bumping up reference of Android to 3.0.3.
Bumping up reference of iOS to 3.0.4.
Fixed: On Android added image scaling to shapes rating questions to fit all answers on the screen in horizontal layout.
On Android fixed issue on Thank You question with button's title not using text from survey settings.
On iOS fixed issue where rating scale question answer ID was missing in listener.
On iOS fixed issue where surveys were not translated when app language was set to dialect.

3.0.3 (2023-09-12)

Update: React peer dependency to 16.8.6
React-Native peer dependency to 0.60.0
Added initializeSdk method to initialize Survicate (replacing initialize)
Deprecated: Initialize method is now deprecated and will be removed in version 4.0

3.0.2 (2023-08-23)

Update: Repository name has been changed to survicate-react-native-sdk
Bumping up references of Android to 3.0.2
Bumping up references of iOS to 3.0.2
Not displaying surveys on iOS when alerts are visible.
Fixed: Issue in Android where in some cases survey was not dismissible.

3.0.1 (2023-08-09)

Update: Bumping up references: Android to 3.0.1 and iOS to 3.0.1

3.0.0 (2023-07-27)

Update: Bumping up references: Android to 3.0.0 and iOS to 3.0.0

2.4.0 (2023-07-17)

Update: Bumping up references: Android to 2.4.0 and iOS to 2.4.0

2.3.0 (2023-05-30)

Update: Bumping up references: Android to 2.3.1 and iOS to 2.3.0

2.1.0 (2023-04-07)

Update: Bumping up references: Android to 2.1.0 and iOS to 2.1.0

2.0.0 (2023-03-10)

Update: Bumping up references: Android to 2.0.0 and iOS to 2.0.0

1.1.19 (2023-01-09)

Update: Bumping up references: Android to 1.7.5 and iOS to 1.8.7

1.1.18 (2022-11-23)

Update: Bumping up references: iOS to 1.8.5

1.1.17 (2022-11-17)

Update: Bumping up references: Android to 1.7.4 and iOS to 1.8.4

1.1.16 (2022-09-12)

Fix: build.gradle file cleanup to fix gradle sync.

1.1.15 (2022-09-07)

Update: Bumping up references: Android to 1.7.0
Update: The minimum supported version of Android changed to 5 (API 21).

1.1.13 (2022-08-05)

Update: Bumping up references: iOS to 1.8.2

1.1.12 (2022-08-04)

Update: Bumping up references: Android to 1.6.5

1.1.11 (2022-07-01)

Update: Bumping up references: Android to 1.6.1 and iOS to 1.8.0
Fixed: Gradle sync failure if referring to React Native 0.68.* and using gradle version lower than 7.2.*