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)
  1. In Xcode, click on "Play" to launch the installation process of the application you just built on your phone

  2. Put the application in the background.

  3. Activate your beacon and put your device in its correct action range (as defined in Adtag)

  4. Remove the beacon from the microwave or put the battery back.

  5. Wait for a few seconds (maximum 1 minute)

  6. The notification appears on your screen