iOS

This is for:

Developer

In this article, we’ll walk you through the steps for setting up CMH on your iOS mobile apps in the ecommerce vertical.

Tip

Check out Coveo Qubit iOS SDK on Github. This public repository provides the code to be installed and is the best place to keep up with the releases.

Installing

CocoaPods is a dependency management system for iOS. If you haven’t configured Cocoa pods, please refer to their Getting Started guide.

If you use another dependency management system or do not wish to implement one, please contact your Coveo representative for alternative options.

Install the QubitSDK package

You can find releases of this SDK here.

Insert the following lines into your Podfile:

target 'MyApp' do
  pod 'QubitSDK', '~> 1.0.15'
end

Then run a pod install inside your terminal or from CocoaPods.app.

Alternatively, to give it a test run, run the command:

pod try QubitSDK

You can also install the SDK GitHub. Once you have CocoaPods installed, navigate to the Podfile in your app’s root directory. In the file, add the lines:

use_frameworks!

target 'MyApp' do
    pod "QubitSDK", :git =>
    "https://github.com/qubitdigital/qubit-sdk-ios.git", :tag => "1.0.15"
end

Specify a GitHub tag to ensure you only opt-in to new releases of this SDK.

If you access the repo via SSH instead of HTTPS, the target URL will be git@github.com:qubitdigital/qubit-sdk-ios.git.

Then, from your command line, run:

pod install

If you encounter permission issues, ensure the GitHub username step has been completed. Consult the Cocoapods documentation if you have any other problems with this step. If your process freezes on “Analysing dependencies”, try running pod repo remove master, pod setup, then pod install again.

Integrating using a framework

If you wish to use QubitSDK without a package manager such as CocoaPods, take a look at our framework options.

Starting the QubitSDK

Starting the QubitSDK with a tracking Id will allow us to identify your data correctly.

When starting the SDK, you can specify the log level of the SDK to determine the amount of logging the SDK will produce.

The log level options for Objective-C are:

  • QBLogLevelDisabled

  • QBLogLevelError

  • QBLogLevelInfo

  • QBLogLevelDebug

  • QBLogLevelVerbose

  • QBLogLevelWarning

The log level options for Swift are:

  • .disabled

  • .error

  • .info

  • .debug

  • .verbose

  • .warning

To start the QubitSDK (preferably in your AppDelegate didFinishLaunchingWithOptions), use the following method:

Objective-C

CocoaPods:

@import QubitSDK;

Framework:

#import "QubitSDK/QubitSDK.h"

Launch:

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    [QubitSDK startWithTrackingId: @"XXXXX" logLevel: QBLogLevelDisabled];
    return YES;
}

Swift

import QubitSDK

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool {
    QubitSDK.start(withTrackingId: "XXXXX", logLevel: .disabled)
    return true
}

Where:

  • XXXXX is your CMH Tracking Id, a unique string representing your account, and provided to you during onboarding. If you haven’t received a tracking Id or don’t know what yours is, please contact your Coveo representative.

Sending events

Before sending events from inside the app, a config file will need to be generated by CMH on S3. Here are the settings that can be set in the config:

  • tracking_id

  • endpoint

  • configuration_reload_interval

  • queue_timeout

  • send_auto_view_events

  • send_auto_interaction_events

  • send_geo_data

  • vertical

  • property_id

  • namespace

  • disabled

To send an event, call the sendEvent method. The following example emits an “ecUser” event:

#import "QubitSDK/QubitSDK.h"

[QubitSDK sendEventWithType:@"ecUser" dictionary:userDictionary];
[QubitSDK sendEventWithType:@"ecUser" data:userJsonAsString];
import QubitSDK

QubitSDK.sendEvent(type: "ecUser", dictionary: userDictionary)
QubitSDK.sendEvent(type: "ecUser", data: userJsonAsString)

Where:

  • userDictionary is of type NSDictionary in Objective-C, Dictionary in Swift, and takes the form:

    {
userId: "jsmith",
currency: "USD",
email: "jsmith@gmail.com",
firstName: "John",
firstSession: false,
gender: "Mr",
hasTransacted: true,
lastName: "Smith",
language: "en-gb",
title: "Mr",
username: "jsmith"
}

Integrating experiences

Use fetchExperiences() to integrate Experiences into your app.

Swift

// Fetch an experience by ID (143640 in this example)
QubitSDK.fetchExperiences(withIds: [143640], onSuccess: { (experiences) in
    if let exp = experiences.first {

        // list out the payload key/values
        print("Got experience - payload:")
        for (key, value) in exp.payload {
            print("\(key) -> \(value)")
        }
        // mark the experience as shown
        exp.shown()
    }
},
onError: { (error) in
    print("Got error: \(error.localizedDescription)")
},
preview: false, ignoreSegments: false, variation: nil)

Objective-C

[QubitSDK fetchExperiencesWithIds:@[@1] onSuccess:^(NSArray<QBExperienceEntity *> * _Nonnull experiences) {
    // select the first experience returned
    QBExperienceEntity* firstEntity = experiences.firstObject;

    // make a POST call to the returned callback URL
    [firstEntity shown];
} onError:^(NSError * _Nonnull error) {
    NSLog(@"%@", error.description);
} preview:false variation:false ignoreSegments:false];

The above call takes optional parameters such as preview, ignoreSegments, and variation.

Adding placements

Use getPlacement() to add CMH Placements into your app.

Swift

QubitSDK.getPlacement(withId: "83f6b528-9336-11eb-a8b3", onSuccess: { (placement) in
    if let placement = placement {

        // fetch our content payload
        print("Got placement - content:")
        print("placement content -> \(placement.content)")

        // send an impression event
        placement.impression()

        // send a clickthrough event
        placement.clickthrough()
    }
}, onError: { (error) in
    print("Got error: \(error.localizedDescription)")
})

Objective-C

[QubitSDK getPlacementWithId:@"123456" onSuccess:^(QBPlacementEntity *> * _Nonnull placement) {
    [placement clickthrough];
    [placement impression];
} onError:^(NSError * _Nonnull error) {
    NSLog(@"%@", error.description);
};

Get in touch with your CMH customer success team for more on this feature.

Disabling tracking

If you would like to disable tracking, use the following method:

#import "QubitSDK/QubitSDK.h"

[QubitSDK stopTracking];
import QubitSDK

QubitSDK.stopTracking()