Connecthings SDK

What you will learn

This tutorial will teach you how to generate a notification thanks to Connecthings' Mobile SDK, when a beacon is detected around a user's mobile phone.

Pre-requisites - What you need to get started

A Gitlab Account: the SDK is available through a private Gitlab. You must have received an email with your user account, including a link to create a password
Your SDK user information: in order to initialize the Mobile SDK, you must have received a User Name, a Password and a Company name
A BLE beacon: a BLE beacon configured on your account is mandatory to test the application
An iOS Device: you need a compatible Bluetooth Low Energy iOS device that is able to detect beacons
The Xcode application: you must have downloaded Xcode from the App store
You must have completed the 5 minutes QuickStart Tutorial.

Step 1: Clone the beacon-tutorial repository

Clone the beacon-tutorial repository

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

Open the iOs>beacon>2-Notification>Notification-Starter folder

Step 2: Configure the SDK

Configure your CocoaPod files and .plist
Configure your SDK with:
- the UUID of your beacon
- the appropriate Adtag Environment
- your login, password, and company details you received from Connecthings

If you need more information, take a look at the 5-minute quickstart tutorial

Step 3: Create your first notification

Open the AppDelegate.m file
Register the application on the notification center in the didFinishLaunchingWithOptions method

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

Note 1:

Starting with iOS 8, you must register the application on the notification center, even if you are only using local notifications

Explicitly implement the applicationDidBecomeActive method, in the AppDelegate.m file.

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

Note 2: If the AppDelegate class does not explicitly call the super applicationDidBecomeActive method, the beacons won't be detected when the application is in the background.

Open the AppDelegate.h file, and add the ATBeaconNotificationDelegate protocole
Open the AppDelegate.m file, and implement the createNotification delegate method

-(UILocalNotification *)createNotification:(ATBeaconContent *)_beaconContent {}

Create the local notification using the corresponding beaconContent information

-(UILocalNotification *)createNotification:(ATBeaconContent *)_beaconContent{
    UILocalNotification *notification = [[UILocalNotification alloc]init];
    [notification setAlertBody:[_beaconContent getNotificationDescription]];
    if(SYSTEM_VERSION_GREATER_THAN(@"7.99")){
        [notification setAlertTitle:[_beaconContent getAlertTitle]];
    }
    [[UIApplication sharedApplication] presentLocalNotificationNow: notification];
    return notification;
}

Note 3: The BeaconContent object contains the content associated to the beacon in Adtag.

The BeaconContent object has 2 methods to retrieve the default content for a notification:

BeaconContent.getNotificationTitle(): retrieves the title of the notification

BeaconContent.getNotificationDescription(): retrieves the description of the notification

You can also generate your own text for the title and description of the notification, based on other categories & fields, using the method BeaconContent getValueFromCategory:CATEGORY andField:FIELD.

For example, BeaconContent getValueFromCategory:@"LINE" andField:@"DIRECTION" allows to retrieve the DIRECTION field of the LINE category.

Implement the didReceiveLocalNotification method in your AppDelegate.m file

 -(void)application:(UIApplication *)application didReceiveLocalNotification:(UILocalNotification *)notification {
	/**
		Open the right controller
	**/
}

Note 4:

When a local notification is triggered, the system calls the didReceiveLocalNotification method to allow the application to open the controller linked to the notification.

Retrieve the BeaconContent object associated with the notification

-(void)application:(UIApplication *)application didReceiveLocalNotification:(UILocalNotification *)notification {
	if ([UIApplication sharedApplication].applicationState!=UIApplicationStateActive) {
		ATBeaconContent *beaconContent = [adtagBeaconManager getNotificationBeaconContent];
	}
}

Send the BeaconContent object to the dedicated controller

 -(void)application:(UIApplication *)application didReceiveLocalNotification:(UILocalNotification *)notification {
	if ([UIApplication sharedApplication].applicationState!=UIApplicationStateActive) {
		ATBeaconContent *beaconContent = [adtagBeaconManager getNotificationBeaconContent];
		NSDictionary* dict = [NSDictionary dictionaryWithObject: beaconContent forKey:@"beaconContent"];
		[[NSNotificationCenter defaultCenter] postNotificationName:@"LocalNotificationMessageReceivedNotification" object:nil userInfo:dict];
	}
}

Step 4: Start testing

If your beacon is already emitting, you must stop/restart the emission process in order to simulate a new region entry for the smartphone, and generate a notification.

There are 2 solutions to stop/restart 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)