Survicate Unity 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.
Unity 2019.4 or later
iOS 12.0 or later
Android 5.0 (API level 21) or later

Installation

iOS

Add content of the iOS directory to your Assets/Plugins/iOS
Add SurvicatePluginIOS.cs and file inside your Assets/Plugins
Download the latest iOS SDK from here. Copy this file to your xcode project folder.

Inside your exported Xcode project, on Build Phases -> Link Binary With Libraries, add

survicate.xcframework

Android

Add content of the Android directory to your Assets/Plugins/Android
Add SurvicatePluginAndroid.cs file inside your Assets/Plugins
Download the latest android SDK from here. Place the downloaded AAR file inside Assets/Plugins/Android
Make sure Android is selected as plugin platform on Inspector window

Add dependencies listed in developers documentations here

Configuration

Configuration for Android

Configure your workspace key in AndroidManifest.xml file.

Add missing Survicate dependencies 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.

Initialization

Initialize the SDK in your application using initializeSdk() method. Call this method only once, in the main script of your project.

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.
int: an integer.
double: a decimal.
bool: a logic value.
DateTime: 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:

onSurveyDisplayed - occurs when survey is loaded and appears in the User Interface
onQuestionAnswered - occurs after a question is answered ( Survicate stores incomplete survey submissions )
onSurveyClosed - occurs when a user closes the survey using the close button
onSurveyCompleted - occurs when a user finishes the survey

SurvicateAnswer properties (QuestionAnsweredEvent.answer)

Property	Type	Description
type	string	Answer type. One of: ['text', 'single', 'multiple', 'smiley_scale', 'rating', 'csat', 'numerical_scale', 'nps', 'date', 'form', 'matrix', 'button_close', 'button_next', 'button_link'].
id	long?	Answer ID. Applicable only for types: ['single', 'smiley_scale', 'csat', 'rating', 'numerical_scale'].
ids	List<long>	Selected answer IDs. Applicable only for type = ['multiple'].
value	string	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.4.0 (2024-10-23)

Updated: Version Alignment: Updated the Unity SDK version to 5.4.0 to match the latest minor release of the native Android SDK (Version 5.4.0) and iOS SDK (Version 5.4.0).

5.3.0 (2024-09-13)

Updated: Version Alignment: Updated the Unity SDK version to 5.3.0 to match the latest minor release of the native Android SDK (Version 5.3.0) and iOS SDK (Version 5.3.0).

5.2.0 (2024-09-05)

Updated: Version Alignment: Updated the Unity SDK version to 5.2.0 to match the latest minor release of the native Android SDK (Version 5.2.0) and iOS SDK (Version 5.2.0).

5.1.1 (2024-08-01)

Updated: Version Alignment: Updated the Unity SDK version to 5.1.1 to match the latest patch release of the native Android SDK (Version 5.1.1) and iOS SDK (Version 5.1.2).

5.1.0 (2024-07-19)

Updated: Version Alignment: Updated the Unity SDK version to 5.1.0 to match the latest minor release of the native Android SDK (Version 5.1.0) and iOS SDK (Version 5.1.1).

5.0.0 (2024-06-18)

Updated: Version Alignment: Updated the Unity SDK version to 5.0.0 to match the latest major release of the native Android and iOS SDKs (Version 5.0.0).

4.4.0 (2024-05-07)

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.
SDK now supports listeners

4.0.0 (2024-01-19)

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
Please note aforementioned changes are only available when using native SDK version 4.0.0 and above
Updated: SetUserTrait(string, string) is deprecated, please use SetUserTrait(UserTrait) instead.
Fixed: Fixed issue with argument name and use mismatch in Android
Fixed issue with setting UserTraits in Android