iOS

This is for:

Developer

In this article, you’ll learn how to set up the Coveo Experience Hub on your iOS mobile apps in the ecommerce vertical.

SDK repository on GitHub

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.

In the repository, you’ll find the SDK’s source code, as well as the README file, which contains the most up-to-date information on the SDK. Also, you can find the privacy manifest, which details the data collected by the SDK:

Data type What it’s used for

Device ID

Product personalization and analytics

Product Interaction

Product personalization and analytics

Email Address

Product personalization and analytics

User ID

Product personalization and analytics

Coarse Location

Product personalization and analytics

Other Data Types

Note

Other Data Types here represent system version and system name of the devices that use the SDK.

Analytics

The SDK collects metadata about the device (such as the application version and iOS version) automatically. It also collects any additional data that you chose to implement, which means data passed through QubitSDK.sendEvent() calls. This level of access is reflected in the NSPrivacyAccessedAPITypeReasons key via the CA92.1 value.

Important

If you choose to include additional data in sent events, you must update the privacy manifest accordingly.

Examine the file for more details: https://github.com/qubitdigital/qubit-sdk-ios/blob/master/QBTracker/QubitSDK/PrivacyInfo.xcprivacy

For more general information about privacy manifest files, see the Apple documentation: Privacy manifest files.

Installing

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

If you use another dependency management system or don’t wish to implement one, 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 from 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 Experience Hub 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 configuration file will need to be generated by the Experience Hub on S3. Here are the settings that can be set in the configuration:

  • 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 Experience Hub 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 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()