What you will learn

This tutorial will teach you how to generate a notification 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 should 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 Login, a Password and a Company Key
  • 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 key you received from Connecthings
[self initAdtagInstanceWithUrlType:ATUrlTypePreprod
                              userLogin:@"YOUR_USER"
                              userPassword:@"API_KEY"
                              userCompany:@"YOUR_COMPANY_KEY"
                              beaconUuid:@"beaconUuid"];

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

Step 3: Disable all the SDK-notifications from the application

You can disable the SDK mobile notification through this code in the ATBeaconAooDelegate class:

	 [self disableNotifications];

Step 4: 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

  • 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 {
    if (_beaconContent) {
        ILog(@"create notification from app delegate");
        UILocalNotification *notification = [[UILocalNotification alloc]init];
        [notification setAlertBody:[_beaconContent getNotificationDescription]];
        if(SYSTEM_VERSION_GREATER_THAN(@"7.99")){
            [notification setAlertTitle:[_beaconContent getAlertTitle]];
        }
        NSDictionary *infoDict = [NSDictionary dictionaryWithObject:[_beaconContent toJSONString] forKey: KEY_NOTIFICATION_CONTENT];
        [notification setUserInfo:infoDict];
        [[UIApplication sharedApplication] presentLocalNotificationNow: notification];
        return notification;
    }
    return nil;
}

Note 2:

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:

  • getNotificationTitle: retrieves the title of the notification
  • 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.

  • Explicitly implement the applicationDidBecomeActive method, in the AppDelegate.m file.
- (void)applicationDidBecomeActive:(UIApplication *)application {
    [super applicationDidBecomeActive:application];
}

Warning:

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.

Step 5: Generate the Beacon Notification analytics

  • Open the AppDelegate.m file
  • Override the didReceiveLocalNotification method and call the super method:
-(void) application:(UIApplication *)application didReceiveLocalNotification:(UILocalNotification *)notification{
    [super application:application didReceiveLocalNotification:notification];
}

Note:

The super method will call the didReceiveLocalNotification from the ATBeaconManager class that permits:

  • to call the didReceiveNotificationContentReceived method of the ATBeaconReceiveNotificationContentDelegate when necessary
  • to generate analytics associated to the beacon notifications

Step 6: Open a ViewController associated to a Beacon Notification

  • Open the AppDelegate.h file

  • Add the ATBeaconReceiveNotificatonContentDelegate. This delegate permits to be notified when a beacon local notification is clicked

@interface AppDelegate : ATBeaconAppDelegate <UIApplicationDelegate,ATBeaconReceiveNotificatonContentDelegate,ATBeaconNotificationDelegate>

  • Open the AppDelegate.m file

  • In the didFinishLaunching method, register the new delegate after the SDK initialization with the method registerNotificationContentDelegate from the ATBeaconManager

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    NSArray *uuids = @[@"UUID"];
    [self initAdtagInstanceWithUrlType:ATUrlTypeItg userLogin:@"User" userPassword:@"PSWD" userCompany:@"COMPANY" beaconArrayUuids:uuids];
    [[ATBeaconManager sharedInstance] registerNotificationContentDelegate:self];
    [...]
}
  • Implement the didReceiveNotificationContentReceived method of the ATBeaconReceiveNotificationContentDelegate
-(void)didReceiveNotificationContentReceived:(ATBeaconContent *)_beaconContent {
    NSDictionary* dict = [NSDictionary dictionaryWithObject: _beaconContent forKey:@"beaconContent"];
    [[NSNotificationCenter defaultCenter] postNotificationName:@"BeaconNotification" object:nil userInfo:dict];
}

Note:

This method is called when a beacon notification is clicked permetting to redirect the user to the ViewController associated to the beaconContent

Step 7: 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.

  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