QualarooSDK for iOS

Qualaroo helps companies identify and capitalize on mobile visitor revenue opportunities.

Requirements

In order to integrate the QualarooMobileSDK into a 3rd-party app, the app must satisfy the following requirements:

Minimum deployment target set to iOS 8.0 or later, but if you use iOS 8.x surveys will not be shown in generally
Xcode 7 or later

Integration

Using Cocoapods

The recommended way to install QualarooSDK for iOS is via Cocoapods since it means you can create a build with specific integrations, and because it makes it dead simple to install and upgrade.

Add the QualarooSDK dependency to your Podfile, like so:

pod `QualarooSDK`, '~> 2.0'

2. Using as Git Submodule

You probably already know what you are doing if you are following this method, but if you need a guideline, here’s a possible procedure:

Run git submodule add github.com:qualaroo/iOSMobileSDK.git vendor/iOSMobileSDK

(optionally) Checkout a specific tag:

cd vendor/iOSMobileSDK
git checkout 2.0
cd ../.. # back to your SRCROOT
git commit -m "Using QualarooSDK 2.0"

Open your Xcode project and add QualarooSDK.framework as an embedded framework on your app’s target.

Code Integration

Important: Our SDK requires a hosting view controller where any Qualaroo surveys will be displayed.

The typical integration procedure is as follows:

In your application delegate’s -application:didFinishLaunchingWithOptions: method, setup the SDK:

Swift

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool {
    do {
        try Qualaroo.setup(with: QualarooConfiguration(apiKey: "your api key"))
    } catch let error as NSError {
        // catch for any error
    }
}

Objective-C

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    NSError *error;
    [Qualaroo setupWithConfiguration:[QualarooConfiguration configurationWithAPIKey:@"your api key" error:&error]];
}

And of course, import the SDK in the files that you use it with:

Swift
```
import QualarooSDK
```
Objective-C
```
#import "QualarooSDK.h"
```

Attach the Qualaroo instance to your view controller and, optionally, specify an attachment position (bottom or top on iPhone, or a corner on iPad) more here.

Swift

override func viewDidAppear(animated: Bool) {
    override func viewDidAppear(_ animated: Bool) {
        do {
            try Qualaroo.shared().attach(to: self, at: .top)
        } catch let error as NSError {
            // catch for any error
        }
    }
}

Objective-C

- (void)viewDidAppear:(BOOL)animated {
    NSError *error;
    [[Qualaroo sharedQualaroo] attachToViewController:self atPosition: QualarooSurveyPositionTop error:&error];
}

Show a survey with a given Alias.

Swift

@IBAction func tappedButton(_ sender: UIButton) {
    Qualaroo.shared().showSurvey(byAlias: "your alias")
}

Objective-C

- (IBAction)tappedButton:(UIButton *)sender {
    [[Qualaroo sharedQualaroo] showSurveyByAlias;@"alias" completion:nil];
}

Cleanup: Remove Qualaroo from the hosting view controller.

Swift
```
override func viewWillDisappear(_ animation: Bool) {
    Qualaroo.shared().removeFromViewController()
}
```
Objective-C
```
- (void)viewWillDisappear:(BOOL)animated {
    [[Qualaroo sharedQualaroo] removeFromViewController];
}
```
Note: It is very important to remember removing the Qualaroo attachment from the hosting view controller whenever it is no longer necessary and before the view controller is destroyed, otherwise we will incur into a retain cycle.

Configuration

The QualarooConfiguration class provides a set of properties that control various policies of the Qualaroo instance. You initialize it with a APIKey like so:

Swift

do {
 try Qualaroo.setup(with: QualarooConfiguration(apiKey: "your api key"))
} catch let error as NSError {
    // catch for any error
}

Objective-C

NSError *error;
[Qualaroo setupWithConfiguration:[QualarooConfiguration configurationWithAPIKey@"your api key" error:&error]];

APIKey
`NSString *`	Your Qualaroo source’s API key

Automatic Screen Tracking

Our SDK can automatically instrument screen calls. It uses method swizzling to detect when ViewController’s did appear or will disappear and uses the label of the view controller (or the class name if a label is not available) as the screen name and used it to search for matches with aliases of surveys. And if it finds then the survey will be shown.

Important: In additionally, if you use auto tracking you no longer need to attach and remove survey from ViewController! But you can still show the survey independently!

Swift

var configuration: QualarooConfiguration!
do {
    configuration = try QualarooConfiguration(apiKey: "your api key")
} catch {
    // catch for any error
}
configuration.autoScreenView = true
Qualaroo.setup(with: configuration)

Objective-C

NSError *error;
QualarooConfiguration *configuration = [QualarooConfiguration configurationWithAPIKey:@"your api key" error:&error];

configuration.autoScreenView = YES;
[Qualaroo setupWithConfiguration:configuration];

Identify

identifier lets you tie a user to their actions. It includes a unique Qualaroo User ID based on the string. We recommend set identifier a single time when user’s account is first created, and only identifying again later when their trails change. We automatically assign an UUID to users before you identify them.

Example of setting an identifier:

Swift

let configuration = try! QualarooConfiguration(apiKey: "your api key")
configuration.identifier = "user ID"

Objective-C

NSError *error;
QualarooConfiguration *configuration = [QualarooConfiguration configurationWithAPIKey@"your api key"];
configuration.identifier = @"user id";

SDK Documentation

Please refer to the documentation available here.

License

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the Software), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED AS IS, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.