IOS SDK Integration Manual

Learn how to integrate our SDK with iOS platform

Blippar Documentation Centre

Requirements

Blippar iOS SDK can only be linked as a part of an Xcode project, we advice to use Xcode 8.3.3 or later. The SDK supports iOS 9.0 and later.

The BlipparSDK cannot use Bitcode, therefore Bitcode must be disabled for your entire project by setting the 'Enable Bitcode' Build Setting to 'No'.

Currently the BlipparSDK only supports portrait mode. This can be set in the Target→General in your app

Distribution

The iOS SDK bundle is distributed as a framework.

License Key

You must obtain a license key from Blippar to use the SDK in your app. This key must be embedded into your app source code and then given to the SDK during its initialisation (this is shown in the example below).

If you have more than one app then you will need separate keys for each app.

Linking

1. Select your project in the Project Navigator (⌘+1).

2. Select your app target.

3. Select the tab Build Phases.

4. Expand Link Binary With Libraries.

5. Use the 'Add Other...' option to add the following SDK framework: BlipparSDK.framework

6. In project→General→Embedded Binaries add BlipparSDK.framework (see screenshot below)

7. Build and run.

Integration

There are two frameworks provided: the 'fat' framework which includes all architectures for the device and simulator (armv7, arm64, x86_64 and i386) and the 'thin' framework that contains just device architectures (armv7 and arm64). It is recommended you use the fat framework during development and switch to the thin framework when submitting to the store (simply copy, rename to BlipparSDK.framework and replace in your project). Apple rejects apps with x86_64 or i386 architectures included so you will not be able to submit your app with the fat framework.

The Blippar SDK uses a camera feed to display the AR experience. We recommend that the developer takes care of getting the camera permission before launching the SDK. If this is not done the SDK will handle the camera permission request, but you must include the Privacy - Camera Usage Description message in your app's plist. If this message is not added, the app will crash. This crash behaviour required by Apple to protect user's privacy. It is not possible to prevent this crash behaviour if the privacy message is missing. There are three additional permissions that are required to take full advantage of the Blippar SDK, Privacy - Calendars Usage Description, Privacy - Microphone Usage Description and Privacy - Photo Library Usage Description.

Privacy - Location When In Use Usage Description is optional and is only needed if the client custom app is going to display a location based AR experience. The SDK will not request permission automatically for location, it is up to the app to request this permission itself.

SDK Registration

Objective-C

1. Open your AppDelegate.h file.

2. Add the following line at the top of the file below your own import statements:

   #import 

3. Add the BlipparSDKDelegate to your AppDelegate declaration.

   @interface AppDelegate : UIResponder 

4. Open your AppDelegate.m file. Search for the method application:didFinishLaunchingWithOptions:

5. Add the following lines to setup and start the iOS Blippar SDK (you will need your SDK license key to initialise the SDK):

   // Initialise the SDK
   [BlipparSDK setKey: your_license_key];
   BlipparSDK* sdk = [BlipparSDK sharedInstance];
   [sdk addSDKDelegate:self];
   [sdk initialise];

   The initialise function will return to your code immediately, but the initialise process is not complete. The initialise process will continue in the background and will eventually call the success or failure delegates. You cannot use any other SDK functions until the onBlipparInitialiseSuccess gets called (see below). The Blippar SDK will contact our servers to validate your license key, therefore an internet connection must be available during the initialisation process. If the internet connection isn't working properly then the SDK will keep trying to validate until it eventually times out after 30 seconds.

Please keep your key secure. Do not store it inside your application's plist or any obviously textual files inside your application bundle.

6. Add BlipparSDKDelegate methods to your AppDelegate.m file.

- (void) onBlipparInitialiseSuccess {

    // You can do anything specific to your app with a successfully initialised SDK.
}

- (void) onBlipparInitialiseError:(BlipparSDKError *)error {

    // Handle any error that may have occurred when trying to initialise the SDK.
    // If your license key is invalid then this function will also be called.
    NSLog(@"%@",error.description);
}

- (void) onBlipparShutdown {

    // You can do anything specific to your app when the SDK is successfully shutdown.
}

Swift 3

1. You will need to create an Objective-C bridging header. The Objective-C bridging header is set in Target→Build Settings→Objective-C bridging header. Add the import for the BlipparSDK header.

   #import 

2. Open your AppDelegate.swift file.

3. Add the BlipparSDKDelegate to your AppDelegate declaration.

   class AppDelegate: UIResponder, UIApplicationDelegate, BlipparSDKDelegate

4. Search for func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool

5. Add the following lines to setup and start the iOS Blippar SDK (you will need your SDK license key to initialise the SDK):

   BlipparSDK.setKey(appKey)
   let sdk = BlipparSDK.sharedInstance()
   sdk.addSDKDelegate(self)
   sdk.initialise()

   The initialise function will return to your code immediately, but the initialise process is not complete. The initialise process will continue in the background and will eventually call the success or failure delegates. You cannot use any other SDK functions until the onBlipparInitialiseSuccess gets called (see below). The Blippar SDK will contact our servers to validate your license key, therefore an internet connection must be available during the initialisation process. If the internet connection isn't working properly then the SDK will keep trying to validate until it eventually times out after 30 seconds.

Please keep your key secure. Do not store it inside your application's plist or any obviously textual files inside your application bundle.

Add BlipparSDKDelegate methods to your AppDelegate.swift file.

func onBlipparInitialiseSuccess() {

    // You can do anything specific to your app with a successfully initialised SDK.
}

func onBlipparInitialiseError(_ error: BlipparSDKError) {

    // Handle any error that may have occurred when trying to initialise the SDK.
    // If your license key is invalid then this function will also be called.
    print(error.description)
}

func onBlipparShutdown() {

    // You can do anything specific to your app when the SDK is successfully shutdown.
}

Connecting SDK to a View Controller

Objective-C

You have two options if you want to use the SDK in your app once it has been successfully initialised:

1. (Recommended) In the interface builder add the VC that derives from the BlipparSDKViewController:

2. Create a new ViewController class. In your view controller class header file add the framework import at the top of the file below your own import statements:

   #import 

3. In your view controller class header file make sure that your class derives from BlipparSDKViewController:

@interface SDKViewController : BlipparSDKViewController

Create or open your storyboard file, and select the view controller you want to be the VC to contain your Blippar SDK view.

1. Go to the View Identity Inspector and in the Custom Class section there change the Class of your view controller to the class you have just created (SDKViewController in this example).

2. Add a view onto the view controller's view. Set the class type to BlipparSDKView.

3. Once you have the BlipparSDKView in the storyboard, you can drag from the VC to the view and select the outlet 'BlipparSDKView'.

4. You can create the view controller programatically and push it onto a navigation controller.

   If you do this then you need to set the BlipparSDKView as the BlipparSDKViewController base class property value.

Swift 3

You have two options if you want to use the SDK in your app once it has been successfully initialised:

(Recommended) In the interface builder add the VC that derives from the BlipparSDKViewController:

1. Create a new ViewController class. In it's header file make sure that your class derives from BlipparSDKViewController:

   class BlipparSDKViewController: BlipparSDKViewController

2. Create or open your storyboard file, and select the view controller you want to be the VC to contain your Blippar SDK view.

3. Go to the View Identity Inspector and in the Custom Class section there change the Class of your view controller to the class you have just created (SDKViewController in this example).

4. Add a view onto the view controller's view. Set the class type to BlipparSDKView.

5. Once you have the BlipparSDKView in the storyboard, you can drag from the VC to the view and select the outlet 'BlipparSDKView'.

6. You can create the view controller programatically and push it onto a navigation controller.

7. If you do this then you need to set the BlipparSDKView as the BlipparSDKViewController base class property value.

Adding an SDK View to a View Controller

To see the camera and AR experiences in the Blippar SDK you need to add a BlipparSDKView to your View Controller. It can be added either using Interface Builder or programmatically.

Adding an BlipparSDKView to a View Controller Using Interface Builder

1. To add Blippar SDK view to your view controller, create or open your storyboard/xib file, select the view controller you want to modify and add a new View to it.

2. Go to the View Identity Inspector and in the Custom Class section there change the Class to BlipparSDKView.

3. We recommend that the BlipparSDKView is put behind all other views. Currently only fullscreen views are supported.

BlipparSDKView MUST be added as full screen, i.e. match the screen width and height. Running a different size BlipparSDKView will likely result in SDK and blipps unpredictable behaviour and decrease in overall stability of the SDK.

Adding an SDK View to a View Controller Programmatically

Objective-C

1. In your ViewController class search for the method viewWillAppear:animated.

2. Add following code there:

   BlipparSDKView* blippView = [[BlipparSDKView alloc] initWithFrame:self.view.bounds];// Blippar SDK is meant to be run full screen. Running it in resized view will cause issues in content display.
   [self.view addSubview:blippView];

Swift 3

1. In your ViewController class search for the method viewWillAppear(_ animated: Bool).

2. Add following code there:

   // Blippar SDK is meant to be run full screen. Running it in resized view will cause issues in content display.
   let blippView = BlipparSDKView(frame: view.bounds)
   view.addSubview(blippView)

Using an SDK View in Your App

Introducing a BlipparSDKView to a view controller is not enough to start displaying blipps. To display a blipp you need to override several SDK callbacks. The provided BlipparSDKViewController takes care of a lot of functionality for you but you can override behaviour yourself. Here is an example of what should be done.

Objective-C

1. In your view controller class search for the method viewDidLoad.

2. Add the following lines to setup and start the Blippar SDK:

   BlipparSDK* blipparSDK = [BlipparSDK sharedInstance];
   [blipparSDK addSDKDelegate:self];

3. Override the BlipparSDKDelegate onBlipparInitialiseSuccess callback (assuming your View Controller is implementing the BlipparSDKDelegate protocol):

   - (void) onBlipparInitialiseSuccess {
       [super onBlipparInitialiseSuccess];
   
       BlipparSDK* blipparSDK = [BlipparSDK sharedInstance];
       [blipparSDK startDetection];  //Camera view screenshots will only be sent for recognition after this method is called
   }

4. That's it! The base BlipparSDKViewController will take care of the rest. It automatically handles detection and starting of blipps. If you need to close a blipp just call

   [self closeCurrentBlipp];

   Should you want to do some more complex behaviour then you can start implementing the BlipparDetectionDelegate and BlipparBlippDelegate protocols yourself.

Swift 3

1. In your view controller class search for the method viewDidLoad.

2. Add the following lines to setup and start the Blippar SDK:

   let sdk = BlipparSDK.sharedInstance()
   sdk.addSDKDelegate(self)

3. Override the BlipparSDKDelegateonBlipparInitialiseSuccess callback (assuming your View Controller is implementing the BlipparSDKDelegate protocol):

   override func onBlipparInitialiseSuccess() {
       super.onBlipparInitialiseSuccess()
   
       let sdk = BlipparSDK.sharedInstance()
       sdk.startDetection()
   }

4. That's it! The base BlipparSDKViewController will take care of the rest. It automatically handles detection and starting of blipps. If you need to close a blipp just call

   closeCurrentBlipp()

   Should you want to do some more complex behaviour then you can start implementing the BlipparDetectionDelegate and BlipparBlippDelegate protocols yourself.

Adding a SDK Debug View to Your App

If you want to add the SDK debug view to your app, simply add a new view to your Blippar view controller's view and set the class type to BlipparSDKDebugView.

Testing Your App

Once you have a running app you may wish to test against some real markers. See the provided Sample Markers document.

In your AppDelegate method onBlipparInitialiseSuccess add the SDK's debugTestBlippsEnabled flag and set this to true in order to see the sample markers.

Make sure you turn off this flag (it's default is off) before releasing your app to the public.

Objective-C

BlipparSDK* sdk = [BlipparSDK sharedInstance];
sdk.debugTestBlippsEnabled = YES;

Swift 3

let sdk = BlipparSDK.sharedInstance()
sdk.debugTestBlippsEnabled = true

You can also change the log level of the SDK, this may be helpful to see more detailed logs.

Objective-C

[BlipparSDK sharedInstance].logLevel = BlipparLogLevelDebug;

Swift

let sdk = BlipparSDK.sharedInstance()
sdk.logLevel = .debug

Sample Apps

• There are two sample apps provided, one in Swift and one in Objective C.

• They are an example of the most basic integration of the SDK.

• The keys have been removed from the project so you need to provide your own key. You can change this in AppDelegate.m or AppDelegate.swift

• You will also need to change the bundle id to your licensed bundle id to validate the SDK. You can do this in General → Bundle Identifier.

• To deploy to a device you'll also need to select a development team as usual in iOS development.