5-minutes Quickstart with beacons | IOS

What you will learn

You will learn:

to configure your Podfile with our Gitlab and our SDK
to configure the SDK in your application

Pre-requisites - What you need to get started

Your SDK credentials, including an SDK Login, Password, and Company Key to initialize the SDK.
A BLE beacon, which has been configured on your account, in order to test interactions with your app.
An iOS Device, with Bluetooth 4.0 and iOs 8 and above.
The Xcode application, which you can download from the App store.

Step 1: Clone the sdk-tutorial repository

Clone the sdk-tutorial repository

git clone https://github.com/Connecthings/sdk-tutorial.git

objectivec

In the cloned sdk-tutorial folder, navigate to iOs>ObjectiveC>Beacon>1-QuickStart>QuickStart-starter

SWIFT

In the cloned sdk-tutorial folder, navigate to iOs>SWIFT>Beacon>1-QuickStart>QuickStart-starter

Step 2: Configure a Podfile with our Gitlab link

Install CocoaPods $ gem install cocoapods
At the root of the sample repository, check if a Podfile already exists and if not, create it. This can be done by running
$ touch Podfile
Add the following parameters to your Podfile:

source 'https://github.com/CocoaPods/Specs.git'
source 'https://forge.adtag.eu/pub/Specs'
platform :ios, '8.0'
target 'QuickComplete' do
  # Uncomment this line if you are using Swift or would like to use dynamic frameworks
  use_frameworks!
  pod "ATLocationBeacon", '~> 2.7'
  # Pods for QuickComplete
  target 'QuickCompleteTests' do
    inherit! :search_paths
    # Pods for testing
  end
  target 'QuickCompleteUITests' do
    inherit! :search_paths
    # Pods for testing
  end
end

Run $ pod upate in your project directory

Note:
Your project is linked to the CoreLocation and libsqlite3 frameworks

Step 3: Configure the info.plist

Our SDK accesses two critical frameworks:

the CoreLocation framework to detect iBeacons
the CoreBluetooth framework to check Bluetooth status

Both of them require explicit permission from the user.

To ask any permission, the iOS system requires an application to provide a description of the framework usage.

This description can be configured in the info.plist file, by adding the following keys:

"Privacy - Location Always Usage Description"" for location permission

<key>Privacy - Location Always Usage Description</key>
<string>Your description goes here</string>

"Privacy - Bluetooth Peripheral Usage Description"" for Bluetooth permission

<key>Privacy - Bluetooth Peripheral Usage Description</key>
<string>Your description goes here</string>

Warning:
If you forget to configure any of these usage descriptions:
the application may crash when trying to use the CoreLocation or CoreBluetooth framework
the App Review Team will reject your application

Step 4: Configure the SDK inside the AppDelegate

Use the ATBeaconAppDelegate

Open the AppDelegate.h file
To simplify the integration process, extend your AppDelegate with the ATBeaconAppDelegate

Switch to Swift

@interface AppDelegate : ATBeaconAppDelegate <UIApplicationDelegate>

class AppDelegate: ATBeaconAppDelegate, UIApplicationDelegate {

Open the AppDelegate.m file
Implement the applicationDidBecomeActive method and call the super method:

Switch to Swift

- (void) applicationDidBecomeActive:(UIApplication *)application{
    [super applicationDidBecomeActive:application];
}

override func applicationDidBecomeActive(_ application: UIApplication) {
    super.applicationDidBecomeActive(application);
}

Warning 1:
If the AppDelegate class does not explicitly call the super applicationDidBecomeActive method, the beacons will not be detected when your application is running in the background.

Warning 2:
The ATBeaconApDelegate class implements several methods of the UIApplicationDelegate.
Always call the super method when implementing a method from the UIApplicationDelegate, to ensure that you do not override its SDK implementation.

Initialize the SDK

In the didFinishLaunchingWithOptions method, configure the ATAdtagInitialize object with your SDK credentials & environment, and launch synchronization with the Adtag Platform

Switch to Swift

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    [[[ATAdtagInitializer sharedInstance] configureUrlType:ATUrlTypeProd andLogin:@"__USER__" andPassword:@"__PSWD__" andCompany:@"__COMPANY__"] synchronize];
    return YES;
}

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool {
    ATAdtagInitializer.sharedInstance().configureUrlType(__UrlType__, andLogin: "__USER__", andPassword: "__PSWD__", andCompany: "__COMPANY__").synchronize();
    return true
}

Note 1:
The synchronize method allows to set up the SDK with a configuration file downloaded from the AdTag platform.
The SDK will start the beacon detection process only when the file download is complete.
This configuration file is saved in cache, and the SDK checks for updates at regular intervals.

Note 2:
The ATAdtagInitializer allows you to configure your access to the various AdTag platforms. Connecthings gives you access to one or several of the following environments:
The Demo platform is ideal for technical Proof of Concept (POC) phases
The Pre-production platform is generally used for beta versions
The Production & Production US platforms are our live environments, and used when you are ready to publish your application

Warning:
You will get two different access keys for each platform that you can access:
An access key to log into the Adtag Platform
An access key to use with our mobile SDK, called API_KEY. Make sure you use the API_KEY (login, password, and platform) to connect the SDK to the correct Adtag Platform, otherwise your application won't be able to detect the beacons.

Step 5: Enable your app to receive local beacon Notifications

Register your application on the notification center

Open the AppDelegate.m file
For iOS 9 or below: in the didFinishLaunchingWithOptions method, register your application on the notification center:

Switch to Swift

-(BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions{
  [...]
  if (SYSTEM_VERSION_LESS_THAN(@"10.0") && [application respondsToSelector:@selector(registerUserNotificationSettings:)]) {
      [application registerUserNotificationSettings:[UIUserNotificationSettings settingsForTypes:UIUserNotificationTypeAlert|UIUserNotificationTypeBadge|UIUserNotificationTypeSound categories:nil]];
  }
  return YES;
}

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool {
    [...]
    if #available(iOS 10.0, *) {
        let center = UNUserNotificationCenter.current()
        center.requestAuthorization(options: [.alert, .sound]) { (granted, error) in
            // Enable or disable features based on authorization.
        }
        let setting = UIUserNotificationSettings(types: [.alert, .badge, .sound], categories: nil)
        UIApplication.shared.registerUserNotificationSettings(setting)
        UIApplication.shared.registerForRemoteNotifications()
    } else {
        if(UIApplication.instancesRespond(to: #selector(UIApplication.registerUserNotificationSettings(_:)))){
            let notificationCategory:UIMutableUserNotificationCategory = UIMutableUserNotificationCategory()
            notificationCategory.identifier = "INVITE_CATEGORY"
            //registerting for the notification.
            UIApplication.shared.registerUserNotificationSettings(UIUserNotificationSettings (types: [.alert, .badge, .sound], categories: nil))
        }
    }
    return true
}

Open the ViewController.m file
For iOS 10 and above: in the viewDidLoad method, register the application on the notification center

- (void)viewDidLoad {
    [super viewDidLoad];
    [...]
    if (SYSTEM_VERSION_GREATER_THAN_OR_EQUAL_TO(@"10.0")) {
        UNUserNotificationCenter *center = [UNUserNotificationCenter currentNotificationCenter];
        [center requestAuthorizationWithOptions:(UNAuthorizationOptionBadge | UNAuthorizationOptionSound | UNAuthorizationOptionAlert)
                              completionHandler:^(BOOL granted, NSError * _Nullable error) {
                                  if (!error) {
                                      NSLog(@"request authorization succeeded!");
                                  }
                              }];
    }
}

Note 1:
On iOS 8 and above, you must register your application on the notification center, even if you are only using local notifications.

Note 2:
With iOs 10, Apple has introduced a new way of managing registration with the UNUserNotificationCenter.
Apple recommends to use it, but it is not mandatory.
For instance, an application that is registered on the notification center using the old code style will still be able to display notifications with pictures, generated with the new UNMutableNotificationContent.

Retrieve the content of the notification

Open the AppDelegate.h file
Add the ATBeaconReceiveNotificatonContentDelegate. This delegate allows the app to be notified when a user clicks on a local beacon notification

Switch to Swift

@interface AppDelegate : ATBeaconAppDelegate <UIApplicationDelegate, ATBeaconReceiveNotificatonContentDelegate>{

class AppDelegate: ATBeaconAppDelegate, UIApplicationDelegate, ATBeaconReceiveNotificatonContentDelegate {

Implement the didReceiveBeaconNotification method of the ATBeaconReceiveNotificationContentDelegate

Switch to Swift

-(void)didReceiveBeaconNotification:(ATBeaconContent *)_beaconContent

func didReceiveBeaconNotification(_ _beaconContent: ATBeaconContent!) {
}

Note:
If your AppDelegate extends the ATBeaconAppDelegate, the ATBeaconReceiveNotificationContentDelegate is registered automatically on the ATBeaconManager.
Otherwise, you must:
Register the delegate using:
[[ATBeaconManager sharedInstance] registerNotificationContentDelegate:YourDelegate];
Allow the ATBeaconManager to receive location notification events, by extending the didReceiveLocalNotification of your AppDelegate with the following code:
-(void)application:(UIApplication *)application didReceiveLocalNotification:(UILocalNotification *)notification{
   [adtagBeaconManager didReceiveLocalNotification:notification];
}

Step 6: Test your configuration

Connect your iOS Device to your computer (it must be registered on Apple’s developer portal)
Start your beacon
In Xcode, click on "Play" to launch the installation process on your phone
When the application starts, popups ask for permission to access your phone location, Bluetooth & notifications: grant them!
Once the application is running:
- if you see "BACKEND_SUCCESS, 1 beacon(s) detected, 1 content(s) attached to the beacon in the Adtag Platform", this means your SDK and your beacon are correctly configured. You can go to the next step.
- If you see "BACKEND_SUCCESS, 0 beacon(s) detected, 0 content(s) attached to the beacon in the Adtag Platform", check that your beacon is active, and that you have configured the SDK with the correct UUID
- If you see "BACKEND_SUCCESS, 1 beacon(s) detected, 0 content(s) attached to the beacon in the Adtag Platform", this means your beacon is not registered on the Adtag Platform, or no content has been attached. You can learn how to associate content to a beacon in the beacon content tutorial.
- If you see "BACKEND_ERROR, 1 beacon(s) detected, 0 content(s) attached to the beacon in the Adtag Platform", make sure you used the correct credentials to initialize the SDK.
Before moving on to the next step, stop the beacon emission, and wait until you see "0 beacon(s) detected".

Note:
There are 2 solutions to stop the emission process:
You can put the beacon inside a microwave (but don't start it!)
You can remove the battery from the beacon (in that case, depending on the model, it can take up to 30 seconds for the beacon to start emitting again when you put the battery back in)
This is to simulate a new region entry for the smartphone, and generate a notification.

Step 7: Generate your first beacon notification

Close your application or leave it running in the background
Remove the beacon from the microwave or put the battery back.
Wait for a few seconds (maximum 1 minute)
Click on the notification that has appeared on your screen just for fun.