iOS SDK

Requirements

iOS 10.0+ / Catalyst (macOS 10.15.1+)
Swift 4.2+
Xcode 11.3.1+

Installation#

CocoaPods#

CocoaPods is a dependency manager for Cocoa projects. To integrate the inBrain iOS SDK into your Xcode project using CocoaPods, specify it in your Podfile:

pod 'InBrainSurveys'

Then, from Terminal within the project folder, run

pod install

Once pod install command is complete, from now on open .xcworkspace file for your project. Add import InBrainSurveys_SDK_Swift to begin using SDK in your code.

Please, visit CocoaPods website for additional information.

Manual Installation#

Drag and drop the InBrainSurveys_SDK_Swift.xcframework file into the same folder level as your [AppName].xcodeproj or [AppName].xworkspace file.

Next...
Visit your app’s Target in the Project Settings and Choose the General tab.
Scroll down until you hit the Frameworks, Libraries and Embedded Content section…
1) Press ‘+’ to Locate the InBrainSurveys_SDK_Swift.framework file in your file hierarchy.
2) Once selected, press "Add";
3) Check that "Embed" option is "Embed & Sing". In case of "Don Not Embed" chosen - the app will crash with the following error:

dyld: Library not loaded: @rpath/libswiftCore.dylib ...

Configuration#

InBrain SDK configuration can be completed at app launch or before SDK usage. Follow the steps below as our recommendation for properly configuring the InBrain SDK before use:

1.) Use the following to pass your API keys. See our Getting Started guide to generating your ClientId and Secret Key. Also note that by default you should pass true for isS2S by default.

inBrain.setInBrain(apiClientID: String, apiSecret: String, isS2S: Bool);

2.) If you would like to receive events, add the following:

inBrain.inBrainDelegate = self

3.) The final step in configuration is passing a unique user id with the following:

inBrain.set(userID: String)

All put together, it should look something like this:

import InBrainSurveys_SDK_Swift

class ViewController: UIViewController {
    
    let inBrain: InBrain = InBrain.shared

    override func viewDidLoad() {
        super.viewDidLoad()
        
        inBrain.setInBrain(apiClientID: String,
                           apiSecret: String,
                           isS2S: Boolean)
        
        inBrain.inBrainDelegate = self
        inBrain.set(userID: String)

    }
    
}

Once the above configuration is complete, the inBrain experience is ready for use as described in the next section.

Usage#

inBrain offers two methods of displaying surveys to your users. The simplest method is use of the inBrain Survey Wall, which presents the inBrain experience with no additional work required. See the this section

A second method is use of the inBrain Native Surveys, which acts as an API to fetch surveys and leaves the display of those surveys up to you. It's explained in detail here

Survey Wall#

There are two options to present inBrain Survey Wall:

1.) Use the following function to display the inBrain Survey Wall. Using this function, inBrain will attempt to get the top UIViewController from the hierarchy. If the SDK unable to get top UIViewController - an error message at the console will be shown:

inBrain.showSurveys()

2.) As an alternative you can display the Survey Wall with:

inBrain.showSurveys(from viewController: UIViewController)

Full 'Survey Wall' Sample code:

import InBrainSurveys_SDK_Swift

class SurveyWallViewController: UIViewController {
    
    let inBrain: InBrain = InBrain.shared

    override func viewDidLoad() {
        super.viewDidLoad()
        
        inBrain.setInBrain(apiClientID: "apiClientID",
                           apiSecret: "apiSecret",
                           isS2S: false)
        
        inBrain.set(userID: "userID")

        inBrain.showSurveys()
    }
}

//MARK: - InBrainDelegate
extension SurveyWallViewController: InBrainDelegate {
    func surveysClosed() {
        //This delegate function calls back whenever the Survey Wall is dismissed and control returned to your App
    }
}

Native surveys#

Native Surveys act as a simple API via the SDK to fetch surveys.

The first step is to setup delegate functions as shown below:

//MARK: - NativeSurveyDelegate
extension NativeSurveysViewController: NativeSurveyDelegate {
    func nativeSurveysLoadingStarted() {
        //Show some activity to the user while surveys loading is in process
    }

    func nativeSurveysReceived(_ surveys: [InBrainNativeSurvey]) {
        //show the returned surveys to the user
    }
    
    func failedToReceiveNativeSurveys(error: Error) {
        //Handle error depends on app logic
    }

}

Next you can fetch surveys from inBrain. This will return an array of survey objects which includes rank, time, and value for each survey. Surveys are returned pre sorted from highest rank to lowest rank. Time indicates the estimated time in minutes to complete the survey. Value indicates the amount of In-App Currency (points, currency, etc.) that the user will earn from completing the survey. More about In-App currency here

inBrain.shared.getNativeSurveys(placementId: String)

Note: placementId is optional and is discussed in detail here

Surveys will be returned via this delegate where you will then present them within your app UI

nativeSurveysReceived(_ surveys: [InBrainNativeSurvey])

When a user selects one of the surveys within your UI, present the survey within the inBrain experience using the following:

inBrain.showNativeSurveyWith(nativeId: String)

inBrain.showNativeSurveyWith(nativeId: String, from viewController: UIViewController)

Important Note: When the inBrain experience returns control to your app after survey completion, you will need to call inBrain.shared.getNativeSurveys() again to get a fresh list of surveys for the user.

Full 'Native Surveys' Sample code:

import InBrainSurveys_SDK_Swift

class NativeSurveysViewController: UIViewController {
    
    let inBrain: InBrain = InBrain.shared

    override func viewDidLoad() {
        super.viewDidLoad()
        
        inBrain.setInBrain(apiClientID: "apiClientID",
                           apiSecret: "apiSecret",
                           isS2S: false)
        
        inBrain.set(userID: "userID")

        inBrain.nativeSurveysDelegate = self
        inBrain.getNativeSurveys()
    }
}

//MARK: - NativeSurveyDelegate
extension NativeSurveysViewController: NativeSurveyDelegate {
    func nativeSurveysLoadingStarted() {
        //Show some activity to the user while surveys loading is in process
    }

    func nativeSurveysReceived(_ surveys: [InBrainNativeSurvey]) {
        //Cache surveys and show them to the user
    }
    
    func failedToReceiveNativeSurveys(error: Error) {
        //Handle error depends on app logic
    }

}

//MARK: - InBrainDelegate
extension NativeSurveysViewController: InBrainDelegate {
    func surveysClosedFromPage() {
        //This delegate function calls back whenever Native Surveys flow is completed and control returned to your App
    }
}

Custom Tracking Data & Demographic Data#

The inBrain SDK provides an additional function setInBrainValuesFor() which allows you to do two things:

1.) Provide demographic data to provide an even more seamless on-boarding of your users into the inBrain experience. You can pass gender and age with the following

let data: [[String : Any]] = [["gender": "male"], ["age" : 34]]
inBrain.setInBrainValuesFor(sessionID: null, dataOptions: data)

2.) Provide tracking data that can be used internally within your system. The tracking data you supply as SessionId will be provided in the Server to Server Callback inBrain sends to your server.

let trackingData = "{ someCustomField: 'tracking_data'}";
inBrain.setInBrainValuesFor(sessionID: trackingData, dataOptions: null)

Please, note: The above configuration should be done before showing the surveys, or it will have no effect.

Setup Server-to-Server Callbacks#

The inBrain system will send JSON payload callbacks to your server upon various events such as Survey Completion, Survey Disqualification, etc. Setup these callbacks within the Publisher Dashboard as shown here

Recieve and Process Rewards in App#

If you would like to receive rewards within your app from the survey flow, set InBrainDelegate and utilize the following implementation:

extension ViewController: InBrainDelegate {
    func didReceiveInBrainRewards(rewardsArray: [InBrainReward]) {
        var idsToConfirm : [Int] = []
        var points: Float = 0
        
        for reward in rewardsArray {
            //use the results in your app
        }

        //IT IS IMPORTANT to call this method to ensure rewards are not received again from inBrain
        inBrain.confirmRewards(txIdArray: idsToConfirm)
    }
}

Supported Country Language List#

By default, the device locale language will be used. This controls which language the inBrain experience will be presented with as well as surveys for that specific country/language locale

Accepted languages: "de-de", "en-au", "en-ca", "en-gb", "en-in", "en-us", "es-es", "es-mx", "es-us", "fr-ca", fr-fr", "fr-br"

InBrainDelegate functions#

didReceiveInBrainRewards(rewardsArray: [InBrainReward])

This delegate function provides an array of InBrainReward objects

didFailToReceiveRewards(error: Error)

This delegate function provides an error if getRewards() failed

surveysClosed()

This delegate function calls back whenever the Survey Wall is dismissed and control returned to your App

surveysClosedFromPage()

This delegate function calls back whenever Native Surveys flow is completed and control returned to your App

func nativeSurveysLoadingStarted()

Сalled just after loading of NativeSurveys started.

nativeSurveysReceived(_ surveys: [InBrainNativeSurvey])

Called when Native surveys have been returned

failedToReceiveNativeSurveys(error: Error)

Called if loading of Native Surveys failed

Customize inBrain UI#

In order to customize the InBrain UI, the following is made available to customize the UI prior to showing the inBrain experience:

Set title for InBrain WebView controller

setNavigationBarTitle(_ title: String)

Customize InBrain's UINavigationBar. Note: color values should be in sRGB (Device RGB) profile

setNavigationBarConfig(_ config: InBrainNavBarConfig)

Example:

let config = InBrainNavBarConfig(backgroundColor: UIColor(hex: "00a5ed"), buttonsColor: .white,
                                       titleColor: .white, isTranslucent: false, hasShadow: false)
inBrain.setNavigationBarConfig(config)

Customize Status Bar. Note: In order to customize status bar - needs to set View controller-based status bar appearance to YES

setStatusBarConfig(_ config: InBrainStatusBarConfig)

let statusBarConfig = InBrainStatusBarConfig(statusBarStyle: .lightContent, hideStatusBar: false)
inBrain.setStatusBarConfig(statusBarConfig)

Troubleshooting#

Library not loaded#

In case of Objective-C projects building for simulator may be failed with error:

  dyld: library not loaded: @rpath/libswiftCore.dylid
  Library not loaded: @rpath/libswiftCore.dylib
    Referenced from: .../Debug-iphonesimulator/InBrainSurveys_SDK_Swift.framework/InBrainSurveys_SDK_Swift
    Reason: no suitable image found.  Did find:
      /usr/lib/swift/libswiftCore.dylib: mach-o, but not built for iOS simulator

To resolve this issue open Project -> Target -> Build Settings -> set Always Embed Swift Standard Libraries to YES.

No such module#

Xcode 12 introduced architecture-related updates, which caused to No such module InBrainSurveys_SDK_Swift`error alongside with[CP] Unable to find matching .xcframework slice in 'path_to_InBrainSurveys_SDK InBrainSurveys_SDK_Swift framework ios-i386_x86_64-simulator ios-armv7_arm64' for the current build architectures (arm64 x86_64)` warning.

In order to fix the issue for Xcode 12 - please, add following lines to the .podfile:

post_install do |installer|
  installer.pods_project.targets.each do |target|
    target.build_configurations.each do |config|
      #config.build_settings["EXCLUDED_ARCHS[sdk=iphonesimulator*]"] = "arm64"
     end
  end
end

This issue is not fixed at our side in order to keep Xcode 11 compatible.