iOS SDK

Survey library to monetize your mobile app. Provided by InBrain.
Check the InBrainSurveys_Demo app for an example on how to integrate with this SDK.

Requirements

iOS 12.0+ / Catalyst(macOS 10.15.1+)
Swift 5.0+
Xcode 13+

Installation

Swift Package Manager (SPM)

The Swift Package Manager is a tool for automating the distribution of Swift code and is integrated into the swift compiler.

File > Add Packages...
Add https://github.com/inbrainai/inBrainSurveys_SDK
Select "Up to Next Major" with "2.0.0"
Add import InBrainSurveys to begin using SDK in your code.

CocoaPods

CocoaPods is a dependency manager for Cocoa projects. To integrate InBrainSurveys 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 you can now open the .xcworkspace file for your project.
Add import InBrainSurveys to begin using the SDK in your code.

Please visit CocoaPods website for additional information.

Manual

Drag and drop the InBrainSurveys.xcframework file into the same folder level as your [AppName].xcodeproj or [AppName].xcworkspace file;
Then open 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.framework file in your file hierarchy.
2) Once selected, press "Add";
3) Check that "Embed" option is "Embed & Sign". If you select the "Do Not Embed" option the app will crash with the following error:

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

4) Add import InBrainSurveys to begin using the SDK in your code.

Configuration

The SDK configuration is pretty simple and can be completed at app launch or before using the SDK. Follow these instructions to configure the SDK:

Set the API keys and reward callback target setInBrain(apiClientID: String, apiSecret: String, isS2S: Bool) right after app launch
Set the inBrainDelegate if you would like to receive a events
Set the userID using inBrain.set(userID: "userID") function. If no userID is provided the UIDevice.current.identifierForVendor will be used instead.

apiClientID and apiSecret is provided by InBrain. isS2S - Is your app enabled with Server-to-Server (S2S) callbacks? If so, set to true. If not, set to false.

Main setup completed and InBrainSurveys is ready to use. Additional configuration options may be found below.

Usage

Survey Wall

For the best user experience we recommend to check if surveys are available prior to calling showSurveys(). This can be done using the checkForAvailableSurveys(completion: @escaping ((_ hasSurveys: Bool, _ error: Error?) -> (Void) method.

InBrainSurveys provides 2 options to show the Survey Wall:
1) Using the showSurveys() function. In this case, InBrain will try to get top UIViewController from the hierarchy. If the SDK is unable to get top UIViewController a message in the console will be shown.
2) Using showSurveys(from viewController: UIViewController).

Sample code:

import InBrainSurveys

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

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

    }
    
    @IBAction func showInBrain(_ sender: UIButton) {
        inBrain.checkForAvailableSurveys { [weak self] hasSurveys, _  in
            guard hasSurveys else { return }
            self?.inBrain.showSurveys()
        }
    }
}

Native surveys

InBrainSurveys SDK provides two options for Native Surveys. Important: After a survey is completed it cannot be completed again.

The first option is to use the NativeSurveysDelegate. Here's how to set it up: 1) Set the InBrain.shared.nativeSurveysDelegate 2) Call the InBrain.shared.getNativeSurveys(filter: nil) function to fetch Native Surveys 3) Handle the surveys using the nativeSurveysReceived(_ surveys: [InBrainNativeSurvey], filter: InBrainSurveyFilter?) function from the nativeSurveysDelegate and show them to the user 4) Once a user selects a survey you can call the showNativeSurveyWith(id surveyId: String, searchId: String, from viewController: UIViewController? = nil) or showNativeSurvey(_ survey: InBrainNativeSurvey, from viewController: UIViewController? = nil) function to open the survey.

Important notes:

Please ensure you are refreshing surveys with the appropriate filter(s). You should fetch Native Surveys after the InBrainWebView has closed and some survey(s) have been completed.
The same NativeSurvey may be matched under various different filters. If you are using a multiple filters you will need to refresh the surveys for each filter.
If you are using the Survey Wall ensure you are refreshing Native Surveys after some survey(s) have been completed. Use the surveysClosed(byWebView: Bool, completedSurvey: Bool, rewards: [InBrainSurveyReward]?) method of InBrainDelegate to detect the InBrainWebView dismissal

Sample code:

import InBrainSurveys

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
        
        let filter = InBrainSurveyFilter(placementId: "placementId",
                                         categories: [.business],
                                         excludedCategories: nil)
        inBrain.getNativeSurveys(filter: filter)
    }
}

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

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

The second option is to get Native Surveys with callbacks:
1) Fetch Native Surveys using the InBrain.shared.getNativeSurveys(filter: InBrainSurveyFilter? = nil, success: @escaping ([InBrainNativeSurvey]) -> (), failed: @escaping ErrorCallback) function and show them to the user. 2) Once user selected some survey - call showNativeSurveyWith(id surveyId: String, searchId: String, from viewController: UIViewController? = nil) or showNativeSurvey(_ survey: InBrainNativeSurvey, from viewController: UIViewController? = nil) function to open the survey.

Important notes:

Please ensure you are refreshing surveys with the appropriate filter(s). You should fetch Native Surveys after the InBrainWebView has closed and some survey(s) have been completed.
The same NativeSurvey may be matched under various different filters. If you are using a multiple filters you will need to refresh the surveys for each filter.
If you are using the Survey Wall ensure you are refreshing Native Surveys after some survey(s) have been completed. Use the surveysClosed(byWebView: Bool, completedSurvey: Bool, rewards: [InBrainSurveyReward]?) method of InBrainDelegate to detect the InBrainWebView dismissal

Important Note: The SDK should be configured before using the Survey Wall or Native Surveys.

Advanced Usage

Reward Hooks For Server2Server Apps

You can add your callbacks in the Dashboard and test the response!

Currency Sale

The SDK provides an option to get active currency sale. That may be done with method getCurrencySale(success:failed:):

InBrain.shared.getCurrencySale(success: { [weak self] sale in
  // Show the info to the user
            }, failed: { error in
 // Handle the error
            })

Custom tracking data

Value to track each user session. This value is provided via S2S Callbacks as SessionId. See more here: S2S Docs

inBrain.setSessionId("test_session")

Please Note: All configuration should be done before showing the surveys or it will have no effect.

Customize inBrain

InBrainSurveys allows customization of the InBrainWebView. In order to do that you can use the below methods prior to showing InBrainWebView:

setNavigationBarTitle(_ title: String) - Sets the title of InBrainWebView.

setNavigationBarConfig(_ config: InBrainNavBarConfig) - Customizes the UINavigationBar of InBrainWebView. Color values should be in sRGB (Device RGB) profile.

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

setStatusBarConfig(_ config: InBrainStatusBarConfig) - Customizes the Status Bar. In order to customize status bar you need to set View controller-based status bar appearance to YES.

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

Migration

InBrainSurveys 2.0 Migration Guide

InBrainSurveys 2.0.0 is the latest major release of InBrainSurveys Survey library to monetize your mobile app. 2.0 introduces several breaking changes that one should be aware of.

SDK renaming

New name of the SDK is InBrainSurveys. As a result or renaming the build will fail with errors. Possible errors using CocoaPods and manual installation:

No such module 'InBrainSurveys_SDK_Swift' error
Solution: Replace import InBrainSurveys_SDK_Swift with import InBrainSurveys
InBrainSurveys_SDK_Swift/InBrainSurveys_SDK_Swift.h' file not found error
Solution: Replace #import <InBrainSurveys_SDK_Swift/InBrainSurveys_SDK_Swift.h> with #import <InBrainSurveys/InBrainSurveys.h>.

Possible errors using Manual installation:

There is no XCFramework found at '.../InBrainSurveys_SDK_Swift.xcframework' error
Solution: Remove reference to InBrainSurveys_SDK_Swift.xcframework from your project and add InBrainSurveys.xcframework instead and check that "Embed" option is "Embed & Sign".
Highly recommended to clean the build folder (CMD + SHIFT + K) and derived data after those updates.

New entities

InBrainSurveyCategory - An enum that represents all the supported categories.
InBrainSurveyFilter - A struct to specify survey fetching rules. It provides an option to get Native Surveys filtered by placement, categories and excluded categories. All of the options may be used separately or simultaneously. The only limitation is that categories and excluded categories shouldn't intersect.

Updated methods

InBrain

getNativeSurveys(placementID: String?)
Changed to: getNativeSurveys(filter: InBrainSurveyFilter?)
getNativeSurveys(placementID: String?, success: ([InBrainNativeSurvey]) -> (), failed: ErrorCallback)
Changed to: getNativeSurveys(filter: InBrainSurveyFilter?, success: ([InBrainNativeSurvey]) -> (), failed: ErrorCallback)
showNativeSurveyWith(id: String, placementId: String?, from viewController: UIViewController?)
Changed to: showNativeSurveyWith(id: String, searchId: String, from: UIViewController?)

NativeSurveyDelegate

nativeSurveysLoadingStarted(placementId: String?)
Changed to: nativeSurveysLoadingStarted(filter: InBrainSurveyFilter?)
nativeSurveysReceived(_ surveys: [InBrainNativeSurvey], placementId: String?)
Changed to: nativeSurveysReceived(_ surveys: [InBrainNativeSurvey], filter: InBrainSurveyFilter?)
failedToReceiveNativeSurveys(error: Error, placementId: String?)
Changed to: failedToReceiveNativeSurveys(error: Error, filter: InBrainSurveyFilter?)

Other changes

NativeSurvey's placementId property replaced with searchId;
added categories (categoryIds for Obj-C) property to NativeSurvey.

Available types and interfaces

Native Survey

Native Survey is an object which represents a survey and has the following properties:

Property	Description
`id`	Id of the survey and the value that should be used when passing parameter to `showNativeSurvey()`
`rank`	A normalized value of 1-N where 1 is highest ranked survey and N is the lowest ranked survey
`time`	An estimation of how many minutes will be required for the user to complete the survey
`value`	The reward the user will earn by completing the survey. This value is in the currency type (points, coins, cents) you specified within the publisher dashboard and already takes into consideration the `revenue share` you've allocated to share with the user for a survey completion.
`isProfilerSurvey`	Boolean value to indicate whether the survey represents an inBrain Profiler survey
`currencySale`	Boolean value to indicate if the `value` of the survey is adjusted based on an active currency sale
`multiplier`	The currency sale multiplier value applied to the survey `value`
`conversionLevel`	Value that indicates the approximate `conversion` rate of the survey. See possible values here
`categories`	Array of values indicating what categories this survey belongs to. See possible values here
`searchId`	This value should be used when opening a native survey. It includes important encoded information related to placement and category filters

Survey Category

The survey may belong to one or a few categories, as well as may have no categories at all. The list of all possible categories may be found bellow:

Automotive
Beverages Alcoholic
Beverages Non Alcoholic
Business
Children & Parenting
Coalition Loyalty Programs
Destinations & Tourism
Education
Electronics, Computer Software
Entertainment And Leisure
Finance, Banking, Investing & Insurance
Food
Gambling, Lottery
Government & Politics
HealthCare
Home
Media & Publishing
Personal Care
Restaurants
Sensitive & Explicit Content
Smoking & Tobacco
Social Research
Sports Recreation Fitness
Telecommunications
Transportation
Travel - Airlines
Travel - Hotels
Travel - Services, Agency, Booking
Credit Cards
Video Games
Fashion & Clothing - Other
Fashion & Clothing - Department Store

Conversion Level

The Conversion Level buckets indicate how the survey has been performing platform-wide at inBrain, not necessarily how well the survey will perform for the user its shown to. Its recommended to use these tags only to portray a unique UI. Possible values are:

New Survey;
Very Poor Conversion
Poor Conversion;
Fair Conversion;
Good Conversion;
Very Good Conversion;
Excellent Conversion.

Full list of SDK's function

InBrain Functions

setInBrain(apiClientID: String, apiSecret: String, isS2S: Bool)
setInBrain(apiClientID: String, apiSecret: String, isS2S: Bool, userID: String)

Initial configuration of InBrain SDK

set(userID: String?)

Provides an app userID to InBrain SDK;
If no userID provided - UIDevice.current.identifierForVendor will be used instead.

setSessionID(_ sessionID: String?)

sessionID: the session identifier

showSurveys()
showSurveys(from viewController: UIViewController?)

Presents the Survey Wall with configuration, provided before.
Please note that the SDK should be configured before showing the surveys or it will have no effect.
Important: If you are using Native Surveys, ensure that you are refreshing after some survey(s) have been completed. Additional details may be found at Native Surveys section description.

showNativeSurveyWith(id: String, searchId: String, from viewController: UIViewController?)
showNativeSurvey(_ survey: InBrainNativeSurvey, from viewController: UIViewController?)

Presents the Native Survey with configuration, provided before.
Please, note: SDK should be configured before showing the survey, or it will have no effect.
Important: If you are using Native Surveys, ensure that you are refreshing after some survey(s) have been completed. Additional details may be found at Native Surveys section description.

InBrainDelegate functions

surveysClosed(byWebView: Bool, completedSurvey: Bool, rewards: [InBrainSurveyReward]?)

This delegate function calls back whenever the InBrainWebView is dismissed.
byWebView == true - dismissed automatically by the WebView; byWebView == false - dismissed by the user;
completedSurvey == true - some survey(s) completed (succeeded or disqualified);
rewards - information about completed surveys and earned rewards. NOTE: At the moment only the first Native Survey reward is delivered. That means if the user complete a Native Survey and then proceeds to the Survey Wall and completes one more survey, only the first reward will be delivered. If using only the Survey Wall, no rewards will be delivered.

NativeSurveysDelegate functions

func nativeSurveysLoadingStarted(filter: InBrainSurveyFilter?)

Called just after loading of Native Surveys started.

nativeSurveysReceived(_ surveys: [InBrainNativeSurvey], filter: InBrainSurveyFilter?)

Provides a fresh batch of Native surveys.

failedToReceiveNativeSurveys(error: Error, filter: InBrainSurveyFilter?)

Called if loading of Native Surveys failed

Side note - Things to double check:

Be sure you have configured InBrain SDK with the proper values;
Ensure that you are setting InBrainDelegate and implementing didReceiveInBrainRewards() if you are using a serverless application.

Troubleshooting

Library not loaded

If Objective-C projects are failing to build:

  dyld: library not loaded: @rpath/libswiftCore.dylid
  Library not loaded: @rpath/libswiftCore.dylib
    Referenced from: .../Debug-iphonesimulator/InBrainSurveys.framework/InBrainSurveys
    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.

M1/M2 Cocoapods Troubles

The SDK is built with the support of M1 architecture in mind. In the unlikely event you experience any issues, follow the steps below: 1) Open Terminal;
2) Install Homebrew;
3) Remove currently installed CocoaPods - sudo gem uninstall cocoapods;
4) Install CocoaPods using Homebrew - brew install cocoapods;
5) Go to project's folder at Terminal;
6) Remove pods from the project - pod deintegrate;
7) Clean the project cmd+shift+k at Xcode;
8) Clean Derived data;
9) Install the pods - pod install at Terminal.

iOS SDK

Requirements​

Installation​

Swift Package Manager (SPM)​

CocoaPods​

Manual​

Configuration​

Usage​

Survey Wall​

Native surveys​

Advanced Usage​

Reward Hooks For Server2Server Apps​

Currency Sale​

Custom tracking data​

Customize inBrain​

Migration​

InBrainSurveys 2.0 Migration Guide​

SDK renaming​

New entities​

Updated methods​

InBrain​

NativeSurveyDelegate​

Other changes​

Available types and interfaces​

Native Survey​

Survey Category​

Conversion Level​

Full list of SDK's function​

InBrain Functions​

InBrainDelegate functions​

NativeSurveysDelegate functions​

Side note - Things to double check:​

Troubleshooting​

Library not loaded​

M1/M2 Cocoapods Troubles​