Survicate iOS SDK

Table of contents

1. Installation
   1. Installing as Swift Package
   2. Installing using CocoaPods
   3. Installing manually
2. Configuration
   1. Initialization using the AppDelegate class
   2. Initialization in SwiftUI projects, with no AppDelegate class
   3. setWorkspaceKey() method
3. Using iOS SDK
   1. Targeting a survey by the screen name
   2. Events-based survey targeting
   3. User identification & attributes
   4. Reseting user data for testing purposes
   5. Listeners
4. Changelog

General information:

• The iOS SDK is distributed in a binary version and developed using Swift 5.7.
• For apps downloaded from the App Store, the Survicate iOS SDK adds ~ 7.2MB to your uncompressed app size on device.

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.

• Xcode 14 is required to to build iOS SDK.
• Respondent’s device running iOS 12 or above

Installation

There are three ways to install the Survicate Mobile SDK in the iOS applications:

Installing as Swift Package

The recommended installation method.

1. Once your iOS application project is ready, open it in the Xcode and select your project’s Package Dependencies tab

2. Copy the Survicate SDK Swift package repository URL https://github.com/Survicate/survicate-ios-sdk into the search field

3. Under the Dependency Rule, select the version of your preference.

4. After the package download completes, select Add Package.

Survicate SDK should now be listed under Swift Package Dependencies in the Xcode Project Navigator.

Installing using CocoaPods

Define pod in your Podfile and run pod install.

Podfile

platform :ios, '10.0'

target 'MyApp' do
    pod 'Survicate'
end    

Installing manually

1. Download and extract the Survicate for iOS

2. Drag Survicate.framework into your project. Make sure “Copy items if needed” is selected and click Finish.

3. In the target settings for your app, set the Survicate.framework to “Embed & Sign”. You’ll find it in the “Frameworks, Libraries, and Embedded Content” section of the “General” tab.

Configuration

The following configuration will require a Workspace Key. You can get your workspace key in the Access Keys section of the Survicate panel.

1. Add workspace key to your Info.plist file.
   • Create Survicate Dictionary.
   • Define WorkspaceKey String in Survicate Dictionary. This is how your Info.plist file should look like:
2. Initialize the SDK using the initialize method. Choose an initialization method described below based on whether your project utilizes ‘AppDelegate’ class.

Make sure that import Survicate line exists in all classes where you call SDK methods.

Initialization using the AppDelegate class

Swift Objective-C

// ...
import Survicate

class AppDelegate: UIResponder, UIApplicationDelegate {
    // ...
    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool {
        SurvicateSdk.shared.initialize()
        return true
    }
}

// ...
@import Survicate;

@implementation AppDelegate
// ...
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    [[SurvicateSdk shared] initialize];
    return YES;
}
@end

Initialization in SwiftUI projects, with no AppDelegate class

Survicate iOS SDK can be used in SwiftUI projects. If your SwiftUI project doesn’t use the AppDelegate class, the initialization of the Survicate Mobile SDK can be done in the constructor of the main application class:

Swift Objective-C

// ...
import Survicate

@main
struct SwiftUIApp: App {
    
    init() {
        SurvicateSdk.shared.initialize()
    }
    // ...
}

// N/A

setWorkspaceKey() method

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.

Swift Objective-C

try? SurvicateSdk.shared.setWorkspaceKey("your_workspace_key")

NSError *error;
[[SurvicateSdk shared] setWorkspaceKey:@"your_workspace_key" error: &error];

Using iOS SDK

Survicate allows you to launch precisely targeted surveys inside your app. In Survicate Panel, you’ll be able to define conditions that your users have to meet 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 The SDK utilizes UserDefaults to store information used by the targeting engine described in this section. Clearing UserDefaults will cause the targeting system to malfunction; f.e. by showing the same survey twice to a single user.

Targeting a survey by the 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 achieve that, you need to send information to Survicate about the user entering and leaving a screen.

Swift Objective-C

// UIKit version
class PurchaseSuccessViewController: UIViewController {

    static var SCREEN_KEY: String = "purchaseSuccess"

    override func viewWillAppear(_ animated: Bool) {
        super.viewWillAppear(animated)
        SurvicateSdk.shared.enterScreen(SCREEN_KEY)
    }

    override func viewWillDisappear(_ animated: Bool) {
        super.viewWillDisappear(animated)
        SurvicateSdk.shared.leaveScreen(SCREEN_KEY)
    }
}

// SwiftUI version
struct ContentView: View {
    // ...    
    var body: some View {
        VStack{
            // ...    
        }.onAppear {
            SurvicateSdk.shared.enterScreen(value: "Showcase")
        }
    }
}

@implementation PurchaseSuccessViewController

- (void)viewWillAppear:(BOOL)animated {  
  [super viewWillAppear:animated];
  [[SurvicateSdk shared] enterScreenWithValue:@"purchaseSuccess"];
}

-(void)viewWillDisappear:(BOOL)animated {  
  [super viewWillDisappear:animated];  
  [[SurvicateSdk shared] leaveScreenWithValue:@"purchaseSuccess"];  
}

@end

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

You can log custom user events throughout your application. They can later be used in the Survicate panel to trigger your surveys. Your survey will instantly after an event occurs in your app.

Swift Objective-C

// UIKit version
@IBAction func didPressButton(_ sender: Any) {
    SurvicateSdk.shared.invokeEvent(name: "userPressedPurchase")
}

// SwiftUI version
struct ContentView: View {
    // ...    
    var body: some View {
        VStack{
            // ...    
            Button(action: {
                // ...    
                SurvicateSdk.shared.invokeEvent(name: "userPressedPurchase")
                // ...    
            })
            // ...    
        }
    }
}

- (IBAction)didPressButton:(id)sender {
    [[SurvicateSdk shared] invokeEventWithName:@"userPressedPurchase"];
}

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

Swift Objective-C

let traits: [UserTrait] = [
    UserTrait.userId("someUserId"),
    UserTrait.firstName("John"),
    UserTrait(withName: "eyes", value: "blue")
]
SurvicateSdk.shared.setUserTraits(traits: traits)

// or just
SurvicateSdk.shared.setUserTrait(.userId("someOtherUserId"))

[[SurvicateSdk shared] setUserTraitsWithNamesAndValues:@{
    @"user_id": @"someUserId",
    @"first_name": @"John",
    @"eyes": @"blue"
}];

// or just
[[SurvicateSdk shared] setUserTraitWithName:@"user_id" value:@"someOtherUserId"];

Bear in mind that user attributes are cached, you only have to provide them once, e.g. when user logs in, not after each init(). You can also change their values at any time (which may potentially trigger showing the 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, and information about answered surveys for the targeting engine).

Swift Objective-C

SurvicateSdk.shared.reset()

[SurvicateSdk.shared reset];

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.

Swift Objective-C

class YourClassName{
    // ...
        SurvicateSdk.shared.initialize()
        SurvicateSdk.shared.delegate = self
    // ...
}

extension YourClassName: SurvicateDelegate {
    func surveyDisplayed(surveyId: String) {
        print("DELEGATE survey_displayed \(surveyId)")
    }

    func questionAnswered(surveyId: String, questionId: Int, answer: SurvicateAnswer) {
        print("DELEGATE question_answered \(surveyId) \(questionId) \(answer)")
    }

    func surveyCompleted(surveyId: String) {
        print("DELEGATE survey_completed \(surveyId)")
    }

    func surveyClosed(surveyId: String) {
        print("DELEGATE survey_closed \(surveyId)")
    }
}

@import Survicate;

@interface AppDelegate () <SurvicateDelegate>
@end

@implementation AppDelegate

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
// ...
    [[SurvicateSdk shared] initialize];
    [[SurvicateSdk shared] setDelegate:self];
// ...
}

- (void)questionAnsweredWithSurveyId:(NSString * _Nonnull)surveyId questionId:(NSInteger)questionId answer:(SurvicateAnswer * _Nonnull)answer {
    NSLog(@"DELEGATE questionAnsweredWithSurveyId: %@, questionId: %ld, answer: %@", surveyId, (long)questionId, answer);
}

- (void)surveyClosedWithSurveyId:(NSString * _Nonnull)surveyId {
    NSLog(@"DELEGATE surveyClosedWithSurveyId: %@", surveyId);
}

- (void)surveyCompletedWithSurveyId:(NSString * _Nonnull)surveyId {
    NSLog(@"DELEGATE surveyCompletedWithSurveyId: %@", surveyId);
}

- (void)surveyDisplayedWithSurveyId:(NSString * _Nonnull)surveyId {
    NSLog(@"DELEGATE surveyDisplayedWithSurveyId: %@", surveyId);
}

SurvicateAnswer object properties

Note: We currently support passing the id, ids and value properties only for the cases enlisted in the table above. You can expect to stumble upon answer objects that consist only of the type property.

Changelog

2.0.2 (2023-03-20)

Fixed

Special characters encoding issue.

2.0.1 (2023-03-14)

Fixed

Disabled dismiss on overlay tap.

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.8.10 (2023-02-9)

Improved

Accuracy of survey sampling.

Fixed

Code causing priority inversion warning to be displayed.

1.8.9 (2023-01-24)

Fixed

Language detection issues.

1.8.8 (2023-01-1)

Update

Remove character limit from text fields.

1.8.7 (2022-12-6)

Fixed

An issue of not showing the survey on dismissing the view controller.

1.8.6 (2022-12-5)

Fixed

Problem with truncating endings in long answer texts.

1.8.5 (2022-11-22)

Fixed

An issues causing a survey to be displayed repeatedly, when using a delayed display feature.

1.8.4 (2022-11-16)

Fixed

A possible race condition when multiple SDK methods are called at the same time.

1.8.3 (2022-09-03)

Fixed

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

Changed

The minimum iOS version requirement for the respondent's device is now iOS 12.

1.8.2 (2022-08-05)

Fixed

Layout fixes for large displays.

Fixed

Answers for smiley scale questions could be not stored.

1.8.1 (2022-06-14)

Fixed

Tracking the SDK version for internal purposes.

1.8.0 (2022-05-19)

New

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

1.7.3 (2022-05-10)

Fixed

Survey layout issues.

1.7.1 (2022-04-05)

Fixed

Memory leaks.

1.7.0 (2022-03-22)

New

Survicate Mobile SDK can now be integrated using Swift Package Manager.
Please refer to the installation documentation to see, how to integrate Survicate Mobile SDK using Swift Package Manager.

1.6.7 (2022-03-15)

Updated

Improved UI rendering speed, we fixed minor layout glitches and some memory leaks.

1.6.6 (2022-03-08)

Fixed

UI rendering speed and layout glitches.

1.6.5 (2022-02-23)

Fixed

Memory leaks and UI rendering speed.

1.6.4 (2022-02-16)

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.6.3 (2022-02-04)

Fixed

In some cases survey settings (TTL) mechanism was not refreshed correctly.

Updated

Survey settings Time to Live(TTL) reduced to 10 minutes.

1.6.2 (2022-01-26)

Fixed

The setWorkspaceKey() method is now working properly, as described in the documentation.

1.6.1 (2021-12-08)

Updated/Fixed

The minimum Xcode version required to run Survicate Mobile SDK is now: 12.5.1

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

1.5.8 (2021-10-26)

New

Scale labels can now be displayed below the smiley scale question

1.5.7 (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.

1.5.6 (2021-09-29)

New

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

1.5.5 (2021-08-26)

Fixed

Locales used by SDK were improved to resolve issue related to warning WARNING ITMS-90176 appearing during upload the app using SDK to the AppStore

1.5.4 (2021-08-26)

Fixed

We restored the minimum iOS version required for the SDK to work to 10.0.

1.5.3 (2021-08-23)

Updated

Survicate iOS SDK is now distributed as an XCFramework binary, making the SDK compatible with Swift 5.x. As a result, the main class of Survicate Mobile SDK had to be renamed.
The version 1.5.3 of the Survicate iOS SDK introduces support for binary framework, which causes a minor backward compatibility break. Until the version 1.5.3 the main SDK class was called Survicate, in the version 1.5.3 that class was renamed to SurvicateSdk. The change was introduced to make it possible to distribute Survicate Mobile SDK as the XCFramework binary.

1.5.2 (2021-07-23)

Fixed

Support for using the Survicate Mobile SDK with Swift 5.x

1.5.1 (2021-06-24)

Updated

Provides support for using the Survicate Mobile SDK with Swift 5.4.1

1.5.0 (2021-06-15)

New

Multiple choice question are shown as checkboxes instead of radio buttons

SDK uses currently respondent API v3 endpoints

Fixed

The cornerRadius extension was renamed in order to avoid conflict in apps that would use SDK

1.4.5 (2021-04-28)

Updated

Supported Swift version 5.4.

1.4.4 (2021-04-19)

Fixed

An issue that caused targeting by attributes to malfunction in some cases.

1.4.3 (2020-12-02)

Updated

Supported Swift version 5.3.1.

1.4.2 (2020-09-23)

Updated

Supported Swift version 5.3.

1.4.1 (2020-09-22)

New

It’s now possible to suppress a survey if other was answered during the current visit to your app.

1.4.0 (2020-04-22)

Updated

Unnecessary spacing on the left side of the question has been removed.

Fixed

Proper handling of 4xx error codes.

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.3.2 (2020-04-01)

Updated

Supported Swift version 5.2.

1.3.1 (2020-02-11)

Fixed

SDK listeners - answer object minor fixes.

1.3.0 (2020-01-23)

New

SDK now supports listeners.

1.2.0 (2019-12-19)

Fixed

Survey ends after Thank you message and CTA.

New

SDK now supports survey completion rate.

1.1.5 (2019-10-11)

Fixed

Surveys layout leaned on right column.

1.1.4 (2019-09-25)

Updated

Supported Swift version 5.1.

1.1.3 (2019-09-10)

Updated

SDK now supports new installation flow.

1.1.2 (2019-08-08)

Fixed

Skip-logic wasn't functioning properly in some cases.

Fixed

reset() method didn't clear user attributes.

1.1.0 (2019-04-05)

Updated

Supported Swift version 5.0.

1.0.8 (2019-03-19)

Fixed

Surveys were sometimes shown on a wrong 'ViewController'.

1.0.7 (2019-01-30)

Fixed

UserTrait default constructor was missing.