Knowledge Base

The BlueConic SDK for iOS makes it easy for developers to collect profile data from their apps. This section explains how to integrate BlueConic into your iOS apps. If you are looking for information on Android apps, see the BlueConic SDK for Android.

You can use the BlueConic iOS SDK to do the following:

• Set and retrieve profile property values
• Serve (custom) dialogues 
• Track user behavior using listeners

BlueConicClient Framework

The BlueConicClient Framework provides the basis for communication with BlueConic. It provides possibilities to develop your own interactions by creating mobile plugins. There is a tutorial on how to create an iOS Plugin, see Tutorial: Mobile plugin for iOS. In addition to creating your own plugins, BlueConicClient Framework allows you to make use of the standard BlueConic plugins. It contains several plugins that are mobile variants of the standard BlueConic plugins, such as Listeners and Dialogues.  

Before you begin

Before you start implementing the BlueConic SDK for iOS, make sure you have the following:

• The latest version of Xcode (v14.2 or higher)
• The BlueConic SDK for iOS (v2.8.10) Develop, for testing your app on devices and simulator devices. Valid architectures: arm64, armv7, armv7s, x86_64, i386
• The BlueConic SDK for iOS (v2.8.10) Release, for submitting your app to the appstore. Valid architectures: arm64, armv7, armv7s
• The BlueConic SDK for iOS (v2.8.10) Source
• An iOS app that you can use to implement the BlueConicClient SDK for iOS

The binary distribution files of the SDK have been built for iOS 9. If your mobile app supports iOS 8, be sure to embed the Source distribution in your source code.

Note: As of the most recent version of the SDK, the use of the BlueConic Simulator is restricted to Debug mode only.

To test your mobile app you will want to have access to a BlueConic environment. There are two options:

• Are you working on behalf of a BlueConic Customer that has a BlueConic environment set up? Then ask a representative of the BlueConic Customer to request a Sandbox environment in which you can test your mobile app.
• Alternatively, request a free Pyxis environment for yourself, and test your mobile app with that.

Updates to iOS Mobile SDK for Apple iOS 14

At the yearly Apple developers’ conference, Apple announced new data privacy and security changes to IDFA (identifier for advertisers) for iOS 14 that affect all iOS mobile SDK developers. Updates to Apple’s privacy policies will require mobile SDK apps to notify and request permission to track in order to collect the user’s Mobile Ad ID beginning in 2021. Our developers are monitoring Apple’s privacy policies and creating a new BlueConic iOS SDK, which will no longer be able to autodetect and collect the Mobile Ad ID via the BlueConic Global Listener.

If you want to release a new version of your app to the app store, you will need to integrate this new SDK and meet Apple’s privacy requirements. If you choose to collect these data points, you will need to request user permissions, and can use our new method “setMobileAdId”. Contact your BlueConic Customer Success Manager for more information on these changes.

Disclosing the data BlueConic automatically collects

Starting with the release of iOS 14.5, developers using the BlueConic SDK for iOS need to disclose to their customers what data they are collecting. Apple publishes a list of data types that require disclosure. This table describes how BlueConic collects data types that require disclosure:

Getting Started

Before you start implementing the SDK, use the following steps to set up your environment:

1. Add the BlueConicClient framework to your app:
   There are three ways to do this:
   1. Install with CocoaPods
      Add pod 'BlueConicClient' to your Podfile.
   2. Add the BlueConicClient framework
      In Xcode add the BlueConicClient.framework for iOS by dragging the BlueConicClient.framework folder into the "Embedded Binaries" section on the General tab.
   3. Add the BlueConicClient as Source (Support for iOS 7)
      Deprecated: Use BlueConicPlugin protocol instead of Plugin class, and then this is not necessary anymore. In Xcode add the BlueConicClient source into your Project, and add #import "BlueConicPlugin.h" to your Bridging-Header.h file.
2. Add the configuration key for BlueConic:
   Locate your app's Information Property List file under "Supporting Files".
   Select <project>-Info.plist and add a new row by right clicking the top row and selecting "Add row". Set the following key name:
   

   bc_server_url

   Double-click the value field and enter the URL for the hostname of your BlueConic server. For example:

   https://example.blueconic.net

3. Add an URL Scheme key for BlueConic simulator:
   Locate your app's Information Property List file under "Supporting Files".
   Select <project>-Info.plist and add a new row by right clicking the top row and selecting "Add row". Set the following key name:
   

   URL types

   This creates an array which contains more property rows. Open "URL types" by clicking the triangle icon in front of the name to display the rows. Right click "Item 0" and select "Add row". You can also add a new item, and add the new row within that item. Set the following key name:
   

   URL Schemes

   This creates another array. Add a new row to this array's "Item 0" and enter your apps "Bundle Identifier", for example:

   com.blueconic.testApp

   Full example of the URL Schemes:
   

   

4. Optionally, add a debug key for BlueConic:
   Locate your app's Information Property List file under "Supporting Files".
   Select <project>-Info.plist and add a new row by right clicking the top row and selecting "Add row". Set the following key name:
   

   bc_debug

   Click the type and select 'Boolean'. Set the value to "YES" if you want to receive debug logs from the BlueConic SDK. Adding a debug key is optional; if you do not want to receive debug logs from the SDK, you do not need to add it.
   Setting Debug to true will provide more logging and enable the use of the BlueConic Simulator.
   Warning: When you publish your apps, Debug should always be set False.
5. Import BlueConic:
   The BlueConic SDK for iOS enables you to set and retrieve profile property values for a BlueConic profile and enables interactions specific to this BlueConic profile. These methods can be used anywhere in the app. Make sure that you import the framework and get the instance before using the BlueConicClient methods:

   // Swift:
   import BlueConicClient
   
   let client = BlueConicClient.getInstance(self)
   
   // Objective C:
   #import <BlueConicClient/BlueConicClient-swift.h>
   
   BlueConicClient *client = [BlueConicClient getInstance:self]; 

   ** Note: Make sure that you provide the current ViewController as argument when invoking getInstance. If no ViewController is available, pass an empty ViewControl.
   
   

6. After you have added the URL Scheme value, select the AppDelegate class and add the following method to enable simulator functionality:

   // Swift: in the AppDelegate.swift file
   func application(_ application: UIApplication, open url: URL, options: 
   [UIApplication.OpenURLOptionsKey: Any] ) -> Bool {    
   BlueConicClient.getInstance(nil).setURL(url)    
       return true
   }
   
   // Objective-C: in the AppDelegate.m file
   - (BOOL)application:(UIApplication *)application openURL:(NSURL *)url 
   options:(NSDictionary<UIApplicationOpenURLOptionsKey,id> *)options {
       [[BlueConicClient getInstance:nil] setURL:url];
       return YES;
   }
   

For more information, be sure to check out the following:

• Tutorial: Mobile Plugin for iOS
• Enabling a mobile app for BlueConic
• Testing a native mobile app in BlueConic

Using the BlueConic iOS SDK

1. Create a page view event each time the user switches screens. 
   Retrieve an instance of the BlueConicClient in the "viewDidAppear(animated: Bool)" of every ViewController and create a page view event. Make sure that a unique screen name is passed in the call. The screen name is shown in the BlueConic Simulator, and it can be used in listener rules or to restrict dialogue interactions to specific screens.
   
   Make sure that you provide the current ViewController as argument when invoking "getInstance" on the BlueConicClient. If no ViewController is available, pass an empty ViewController.

   // Swift: in the ExampleViewController.swift file
   import UIKit
   import BlueConicClient
   
   class ExampleViewController: UIViewController {
     private var _blueConicClient: BlueConicClient?
       
     override func viewDidAppear(animated: Bool) {
       super.viewDidAppear(animated)
       // Get the BlueConicClient instance.
       self._blueConicClient = BlueConicClient.getInstance(self)
   
       // Set screen name to identify the ViewController
       self._blueConicClient?.createEvent("PAGEVIEW", 
       properties: ["screenName": "Main/ExampleViewController"])
     }
   }
   
   

   // Objective-C: in the ExampleViewController.h file
   #import <UIKit/UIKit.h>
   #import <BlueConicClient/BlueConicClient-Swift.h>
   
   @interface ExampleViewController : UIViewController
   @end
   
   // Objective-C: in the ExampleViewController.m file
   #import "ExampleViewController.h"
   
   @interface ExampleViewController ()
   
   @property BlueConicClient* client;
   
   @end
   
   @implementation ExampleViewController
   
   - (void)viewDidAppear:(BOOL)animated {
     [super viewDidAppear:animated];
     // Get the BlueConic instance
     self.client = [BlueConicClient getInstance:self];
   
     // Set screen name to identify the ViewController
     [self.client createEvent:@"PAGEVIEW" properties:@{@"screenName": 
     @"MAIN/ExampleViewController"}];  
   }
   
   @end
   

2. Retrieve and store profile properties:
   The BlueConic SDK for iOS enables you to set and retrieve profile property values for a BlueConic profile. These methods can be used anywhere in the app. The following example counts the number of times a specific activity is opened and stores this number in the BlueConic profile:

   // Swift: in the ExampleViewController.swift file
   import UIKit
   import BlueConicClient
   
   class ExampleViewController: UIViewController {
     private var _blueConicClient: BlueConicClient?
     private let PROPERTY_ID = "views";
       
     override func viewDidAppear(animated: Bool) {
       super.viewDidAppear(animated)
       // Get the BlueConicClient instance.
       self._blueConicClient = BlueConicClient.getInstance(self)
   
       // Get the current value from the profile. 
        This value is returned as a String.
       let profileValue: String? = self._blueConicClient?.getProfileValue(self.PROPERTY_ID)
   
       var newValue = 1
       if (profileValue != nil && Int(profileValue!) != nil) {
         newValue = Int(profileValue!)! + 1
       }
   
       // Set the new value in the profile
       self._blueConicClient?.setProfileValue(self.PROPERTY_ID, value:String(newValue))
     }
   }
   
   

   // Objective-C: in the ExampleViewController.h file
   #import <UIKit/UIKit.h>
   #import <BlueConicClient/BlueConicClient-Swift.h>
   
   @interface ExampleViewController : UIViewController
   @end
   
   // Objective-C: in the ExampleViewController.m file
   #import "ExampleViewController.h"
   
   @interface ExampleViewController ()
   
   @property BlueConicClient* client;
   
   @end
   
   @implementation ExampleViewController
   
   static NSString *PROPERTY_ID = @"views";
   
   - (void)viewDidAppear:(BOOL)animated {
     [super viewDidAppear:animated];
     // Get the BlueConic instance
     self.client = [BlueConicClient getInstance:self];
   
     // Get the current value from the profile. This value is returned as a String.
     NSString* profileValue = [self.client getProfileValue:PROPERTY_ID];
   
     int newValue = [profileValue intValue] + 1;
   
   // Set the new value in the profile
   [self.client setProfileValue:PROPERTY_ID value:[NSString stringWithFormat:@"%d", newValue]];
   }
   
   @end
   

3. Register events:
   Calls to register an event can be done in the onLoad of a custom developed mobile Plugin. The code fragment shows how to trigger a click event. Possible events are: "CLICK", "VIEW" and "CONVERSION"

   // Swift: in the ExamplePlugin.swift file
   import Foundation
   import BlueConicClient
   
   public class TestPlugin: BlueConicPlugin {
     private var _client: BlueConicClient?
     private var _context: InteractionContext?
       
     override init() {
       super.init()
     }
       
     public required convenience init(client: BlueConicClient, context: InteractionContext) {
       self.init()
       self._client = client
       self._context = context
     }
       
     public func buttonClicked() {
       self._client?.createEvent("CLICK", properties: ["interactionId": 
       self._context?.getInteractionId()])
     }
       
     public func onLoad() {
       let component: UIView? = self._context?.getView()
       if let button = position as UIButton {
         button.addTarget(self, action: Selector("buttonClicked"), 
         forControlEvents: UIControlEvents.TouchUpInside)
       }  
     }
   }
   
   

   // Objective-C: in the ExamplePlugin.h file
   
   #import <Foundation/Foundation.h>
   #import <BlueConicClient/BlueConicClient-Swift.h>
   
   @interface ExamplePlugin: NSObject <BlueConicPlugin>
   
   - (instancetype) initWithClient: (BlueConicClient *)client 
   context:(InteractionContext *)context;
   - (void) onLoad;
   - (void) onDestroy;
   
   @end
   
   // Objective-C: in the ExamplePlugin.m file
   
   #import "ExamplePlugin.h"
   
   @interface ExamplePlugin ()
   
   @property BlueConicClient* client;
   @property InteractionContext* context;
   
   @end
   
   @implementation ExamplePlugin
   
   - (instancetype) initWithClient: (BlueConicClient *)client 
   context:(InteractionContext *)context {
     self = [super init];
     if (self) {
       self.client = client;
       self.context = context;
     }
     return self;
   }
   
   - (void) buttonClicked {
     [self.client createEvent:@"CLICK" properties:@{@"interactionId": 
     [self.context getInteractionId]}];
   }
   
   - (void) onLoad {
     UIView* component = [self.context getView];
     if ([component isKindOfClass:[UIButton class]]) {
       UIButton* button = (UIButton*)component;
       [button addTarget:self action:@selector(buttonClicked) 
        forControlEvents:UIControlEventTouchUpInside];
     }
   }
   
   @end
   

Configuring BlueConic

This section describes how to add the channel for your mobile application to your BlueConic domains as well as how to define your custom profile properties so that you can use them in BlueConic segments.

Add the mobile channel

Before you can start measuring activity in your mobile applications and maintain values in visitor profile properties, the channel for your mobile application must be added to a domain in your BlueConic tenant. The very first time that you start your application, BlueConic will detect it. It must then be added as a channel of the type "Mobile App" in a domain. See Managing channels for complete information.

Custom profile properties

If you want your mobile application to be able to add custom properties to visitor profiles and use them in BlueConic segments, those custom profile properties must be added to your plugin. For complete information on writing a custom plugin, see Plugin Types. For information about adding custom profile properties, see profile properties.

Create a position

Connect your UIView element to your ViewController, so your ViewController has a connection/ property of your UI element.
This can be done in a storyboard. Open your storyboard and click on the 'Assistant Editor'-button in the top-toolbar of Xcode, this allows you to have a splitscreen. On the left side you will see the actual storyboard and on the right-side the ViewController bound to the selected view. Hold the 'Control'-key and drag one of the View-elements inside your storyboard to the ViewController. After releasing the mouse button it should show a configuration pop-up, the Connection should be an 'Outlet' and the Name needs to be set. (The name should equal your position id.) Press the connect button; it should look like:

// Swift:
@IBOutlet weak var viewName: UIView!

// Objective-C
@property (strong, nonatomic) IBOutlet UIView* viewName;

The position id of this element is 'viewName' and can be used in the domain as '#viewName'. The BlueConic SDK currently only supports selecting elements using their ids.

See also: How can I test my native mobile app?

BlueConicClient Methods

Implementation of the BlueConic client, handling the profile retrieval and storage. This may be from cache, persistent storage on the client or direct requests to the BlueConic server.

// Swift:
import BlueConicClient

// Objective-C:
#import <BlueConicClient/BlueConicClient-Swift.h>

// Swift:
let client: BlueConicClient = BlueConicClient.getInstance(self)

// Objective-C:
BlueConicClient* client = [BlueConicClient getInstance:self];

// Swift:
let profileId: String = client.getProfileId()

// Objective-C:
NSString* profileId = [client getProfileId];

// Swift:
let hobby: String = client.getProfileValue("hobby")

// Objective-C:
NSString* hobby = [client getProfileValue:@"hobby"];

// Swift:
let hobbies: [String] = client.getProfileValues("hobbies")

// Objective-C:
NSArray* hobbies = [client getProfileValues:@"hobbies"];

// Swift:
let segments: [BlueConicSegment] = client.getSegments() 

// Objective-C: 
NSArray* segments = [client getSegments];

// Swift:
let hasSegment: Bool = client.hasSegment("4a622c61-68d7-4d3e-b5a2-8fd5da43c6a0") 

// Objective-C: 
BOOL hasSegment = [client hasSegment:@"4a622c61-68d7-4d3e-b5a2-8fd5da43c6a0"];

// Swift:
let viewController = client.getViewController()

// Objective-C:
UIViewController* viewController = [client getViewController];

// Swift:
@IBOutlet weak var view: UIView!
let view: UIView? = client.getView("#view")

// Objective-C:
@property (weak, nonatomic) IBOutlet UIView* view;
UIView* view = [client getView:@"#view"];

// Swift:
client.createEvent("PAGEVIEW", properties: ["screenName": "Main/HOMETAB"])
var screenName: String = client.getScreenName()

// Objective-C:
[client createEvent:@"PAGEVIEW" properties:@{@"screenName": @"MAIN/HOMETAB"}];
NSString* screenName = [client getScreenName];

// Swift:
client.addProfileValue("hobbies", value:"tennis")

// Objective-C:
[client addProfileValue:@"hobbies" value:@"tennis"];

// Swift:
let hobbyArray = ["tennis", "soccer"]
client.addProfileValues("hobbies", values:hobbyArray)

// Objective-C:
NSArray* hobbyArray = [NSArray arrayWithObjects:@"tennis", @"soccer", nil];
[client addProfileValues:@"hobbies" values:hobbyArray];

// Swift:
client.setProfileValue("hobbies", value:"tennis")

// Objective-C: 
[client setProfileValue:@"hobbies" value:@"tennis"];

// Swift: 
let hobbyArray = ["tennis", "soccer"]
client.setProfileValues("hobbies", values:hobbyArray) 

// Objective-C: 
NSArray* hobbyArray = [NSArray arrayWithObjects:@"tennis", @"soccer", nil];
[client setProfileValues:@"hobbies" values:hobbyArray];

// Swift: 
client.incrementProfileValue("hobbiesCount", value: "1")

// Objective-C: 
[client incrementProfileValue:@"hobbiesCount" value:@"1"];

// Swift: 
client.setLocale("en_US")

// Objective-C: 
[client setLocale:@"en_US"];

// Swift: 
// Implement in AppDelegate.swift 
func application(application: UIApplication, openURL url: NSURL, 
    sourceApplication: String?, annotation: AnyObject?) -> Bool { 
    BlueConicClient.getInstance(nil).setURL(url)
    return true
} 

// Objective-C: 
// Implement in AppDelegate.m 
- (BOOL)application:(UIApplication *)application openURL:(NSURL *)url 
    sourceApplication:(NSString *)sourceApplication annotation:(id)annotation { 
    [[BlueConicClient getInstance:nil] setURL:url];
    return YES; 
}

// Swift: 
client.createEvent("PAGEVIEW", properties: ["screenName": "Main/HOMETAB"])
client.createEvent("CLICK", properties: ["interactionId": self._context.getInteractionId()])

// Objective-C: 
[client createEvent:@"PAGEVIEW" properties:@{@"screenName": @"MAIN/HOMETAB"}];
[client createEvent:@"CLICK" properties:@{@"interactionId": 
[self._context getInteractionId]}];

// Swift:
let consentedObjectives: [String] = client.getConsentedObjectives()

// Objective-C:
NSArray* consentedObjectives = [client getConsentedObjectives];

// Swift:
let refusedObjectives: [String] = client.getRefusedObjectives()

// Objective-C:
NSArray* refusedObjectives = [client getRefusedObjectives];

// Swift:
client.addConsentedObjective("objective_1")

// Objective-C:
[client addConsentedObjective:@"objective_1"];

// Swift: 
let objectiveIds = ["objective_1", "objective_2"]
client.setConsentedObjectives(objectiveIds) 

// Objective-C: 
NSArray* objectiveIds = [NSArray arrayWithObjects:@"objective_1", @"objective_2", nil];
[client setConsentedObjectives: objectiveIds];

// Swift:
client.addRefusedObjectives("objective_1")

// Objective-C:
[client addRefusedObjective:@"objective_1"];

// Swift: 
let objectiveIds = ["objective_1", "objective_2"]
client.setRefusedObjectives(objectiveIds) 

// Objective-C: 
NSArray* objectiveIds = [NSArray arrayWithObjects:@"objective_1", @"objective_2", nil];
[client setRefusedObjectives: objectiveIds];

InteractionContext Methods

Interface InteractionContext

// Swift: 
let interactionId: String? = context.getInteractionId()

// Objective-C: 
NSString* interactionId = [context getInteractionId];

// Swift: 
let parameters: Dictionary<String, [String]> = context.getParameters()

// Objective-C: 
NSDictinoary* parameters = [context getParameters];

// Swift:
let context: InteractionContext!
let connection: Connection? = context.getConnection(connectionId)

// Objective-C:
InteractionContext* context;
Connection* connection = [context getConnection:connectionId];

// Swift: 
let view: UIView? = context.getView()

// Objective-C: 
UIView* view = [context getView];

// Swift: 
let position: String? = context.getPositionIdentifier()

// Objective-C: 
NSString* position = [context getPositionIdentifier];

BlueConicPlugin Methods

Interface BlueConicPlugin

// Swift:
public required convenience init(client: BlueConicClient, context: InteractionContext) { 
    self.init()
}

// Objective-C:
- (instancetype) initWithClient: (BlueConicClient *)client 
   context:(InteractionContext *)context {
    self = [super init];
    return self;
}

// Swift:
public func onLoad() {
    // Implementation of the plugin
}

// Objective-C:
- (void) onLoad {
    // Implementation of the plugin
}

// Swift:
public func onDestroy() {
    // Implementation of the plugin
}

// Objective-C:
- (void) onDestroy {
    // Implementation of the plugin
}

Connection Methods

Interface Connection

// Swift:
let context: InteractionContext!
let connection: Connection? = context.getConnection(connectionId)
let connectionId = connection.getId()

// Objective-C:
InteractionContext* context;
Connection* connection = [context getConnection:connectionId];
NSString* connectionId = [connection getId];

// Swift:
let context: InteractionContext!
let connection: Connection? = context.getConnection(connectionId)
let connectionParameters: Dictionary<String, 
  [String]> = connection.getParameters()

// Objective-C:
InteractionContext* context;
Connection* connection = [context getConnection:connectionId];
NSDictionary* connectionParameters = [connection getParameters];