Skip to content

Installation and first steps

Kontakt.io iOS SDK is a dynamic library written in Objective-C. However, it follows all of the latest best practices (e.g. nullability annotations) making it a perfect fit for apps written in Swift as well.

It is distributed as a precompiled framework available on our GitHub repository, but it's possible to integrate Kontakt.io iOS SDK using dependency managers like CocoaPods or Carthage. If you prefer to do this manually, you will find instructions below as well.

Please be aware that if you want to use our SDK in your project, the minimum deployment target must be set to iOS 8.0, OS X 10.9 or tvOS 9.0.

CocoaPods

CocoaPods is currently one of the easiest ways to add Kontakt.io iOS SDK to your project. If you haven't used it before, this tutorial from AppCoda should give you a good intro.

To integrate Kontakt.io iOS SDK into your project, modify your Podfile by adding/changing these lines:

platform :ios, '8.0'
use_frameworks!

pod 'KontaktSDK', '~> 1.3'

After that it's only a matter of running the pod install command. The new Xcode Workspace will have Kontakt.io iOS SDK already included.

Carthage

Carthage is a dependency manager, preferred by some over CocoaPods for its simplicity. It will download the right version of Kontakt.io iOS SDK as well, but it won't automatically add it to your project. You will need to do this on your own.

If you haven't used Carthage before, we recommend reading this tutorial from raywenderlich.com.

Once you have Carthage installed, it's time to set it up for your project. In the root directory of your app's project create an empty file named Cartfile, open it in your favorite text editor and add this line:

github "kontaktio/kontakt-ios-sdk"

After that run carthage update to build the framework.

When it's done, open your project in Xcode, select your application target, go to the General settings tab and drag the KontaktSDK.framework from <YourProjectDirectory>/Carthage/Build/(iOS/tvOS/Mac) directory under the Linked Frameworks and Libraries.

Then switch to the Build Phases tab, click the + icon and choose New Run Script Phase. Create a Run Script with the following contents:

/usr/local/bin/carthage copy-frameworks

and add the paths to the frameworks you want to use under Input Files, e.g.:

$(SRCROOT)/Carthage/Build/iOS/KontaktSDK.framework

This script works around an App Store submission bug triggered by universal binaries and ensures that necessary bitcode-related files and dSYMs are copied when archiving.

With the debug information copied into the built products directory, Xcode will be able to symbolicate the stack trace whenever you stop at a breakpoint. This will also enable you to step through third-party code in the debugger.

When archiving your application for submission to the App Store or TestFlight, Xcode will also copy these files into the dSYMs subdirectory of your application's .xcarchive bundle.

Installing the SDK manually

If you don't want to use any dependency managers in your project, you can always add Kontakt.io iOS SDK as a git submodule. In order to do that, open a Terminal.app and navigate to your project's top-level directory and initialize a git repository if you don't have it yet:

$ git init

When you're in your project directory, add a submodule:

$ git submodule add https://github.com/kontaktio/kontakt-ios-sdk.git

Drag the KontaktSDK.framework from the new kontakt-ios-sdk directory into the Project Navigator of your Xcode project. Make sure your target is checked in Add to targets section.

Next, select your application project in the Project Navigator (blue project icon) to navigate to the target configuration window and select the application target under the "Targets" heading in the sidebar.

In the tab bar at the top of that window, open the General panel. Click on the + button under the Embedded Binaries section.

Select the KontaktSDK.framework and click the add button.

In the Build Phases tab, click the + button at the top and select New Run Script Phase. Enter the following code into the script text field:

bash "${BUILT_PRODUCTS_DIR}/${FRAMEWORKS_FOLDER_PATH}/KontaktSDK.framework/strip-frameworks.sh"

(The last step, courtesy of Realm, is required for working around an iOS App Store bug when archiving universal binaries.)

First steps after installation

There are few things you need to do before you can start using Kontakt.io iOS SDK

Import

Wherever you want to use Kontakt.io iOS SDK you will need to import it:

import KontaktSDK
#import <KontaktSDK/KontaktSDK.h>

API Key

Since many features of Kontakt.io iOS SDK depend on Kontakt.io Cloud we recommend that you set up your API access right away, for example in application:didFinishLaunchingWithOptions:

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool {
    Kontakt.setAPIKey("yourSuperSecretAPIKey")
    return true
}
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    [Kontakt setAPIKey:@"yourSuperSecretAPIKey"];
    return YES;
}

Info.plist keys

Working with Beacons in iOS app requires an access to some resources that provide sensitive user data. In order to protect user privacy, an app needs to explicitly ask a permission to use them.

Location Services

Monitoring and ranging iBeacons (not Eddystone beacons) is handled by Core Location, so in order to use this functionality, your app needs to get permission to use Location Services. The first step is to add a right entry to your info.plist:

Depending on what type of permission you require in your app, you need to add one of these keys:

  • NSLocationWhenInUseUsageDescription
  • NSLocationAlwaysUsageDescription

with a corresponding value explaining why do you need access to Location Services. This description will be displayed on a prompt asking the user to grant the requested permission.

Bluetooth usage

All apps linked on or after iOS 10.0, that accesses the Bluetooth interface (needed to scan Beacons), must declare the intent to do so. Similarly to Location Services permission, it's handled by including the NSBluetoothPeripheralUsageDescription key in your app’s Info.plist file with a value set to a string that provides users an explanation why the app needs to use Bluetooth.

Running your app

Apps with Kontakt.io iOS SDK will launch in iOS Simulator, although all functionality that requires Bluetooth (detecting beacons, connecting to them, writing new configuration, etc.) works only on a physical device.