What you will learn

You will learn to create a Welcome Notification associated with the first beacon the SDK detects.

Prerequisites - What you need to get started

  • A Gitlab Account: The SDK is available through a private Gitlab. You must have received an email with an user account including a link to create a password.
  • Your SDK user information: To initialize the SDK, your should have received a Login, a Password and a Company name.
  • A beacon: A 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: Xcode should be downloaded from the App store
  • You must have completed the notification tutorial..

Step 1: Clone the sdk-tutorial repository

  • Clone the sdk-tutorial repository
git clone https://github.com/opsct/sdk-tutorial.git

objectivec:

  • Open the sdk-tutorial>ios>ObjectiveC>Beacon>5-WelcomeNotification folder

SWIFT:

  • Open the sdk-tutorial>ios>SWIFT>Beacon>5-WelcomeNotification folder

Step 2: Configure the SDK

  • Configure your CocoaPod and .plist files

  • Configure the SDK with:

    • the UUID of your beacon
    • the Adtag Platform you would like to connect,
    • and the login, password, and company informations received from Connecthings.

If you need more informations, have a look to the 5 minutes quickstart tutorial

Note:

This project extends the Notification tutorial project.

We recommand you to realize it before to continue.

Step 3: Create your first Welcome Notification

  • Open the AppDelegate.h

  • Create a Beacon Welcome Notification in the didFinishLaunchingWithOptions method

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    [...]
    ATBeaconWelcomeNotification *welcomeNotificationNetworkOn = [[ATBeaconWelcomeNotification alloc] initTitle:@"Nice Welcome Notification" description:@"Good news: You have got network" minDisplayTime:1000 * 60 * 2 welcomeNotificationType:ATBeaconWelcomeNotificationTypeNetworkOn];

    return YES;
}

Note:

It exists several constructors to create a Welcome Notification.
The most complete is the constuctor:

(id)initTitle:(NSString *) title
   description:(NSString *) description
       iconeId:(int) iconeId
minDisplayTime:(int) minDisplayTime
welcomeNotificationType:(ATBeaconWelcomeNotificationType) welcomeNotificationType
displayCurrentBeaconNotification:(bool) displayCurrentBeaconNotification
  • TYPE: defines the type of Welcome Notification, either:
    • ATBeaconWelcomeNotificationTypeNetworkOn: Welcome Notification displayed only when the device has access to the internet
    • ATBeaconWelcomeNotificationTypeNetworkDown: Welcome Notification displayed only when the device is offline
  • title: title of the notification
  • description: description of the notification
  • iconId: icon associated with the notification
  • minDisplayTime: minimum time the notification is displayed
  • displayCurrentBeaconNotification:
    • If set to true, the current beacon notification will be displayed in addition of the welcome notification (The user will received two notifications)
    • if set to false, only the welcome notification will be displayed (The user will receive only one notification - the Welcome Notification)

Step 4: Register your Welcome Notification

  • Use the [ATBeaconAppDelegate addDefaultNotification:WELCOME_NOTIFICATION] method to register your Welcome Notification
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    [...]
    ATBeaconWelcomeNotification *welcomeNotificationNetworkOn = [[ATBeaconWelcomeNotification alloc] initTitle:@"Nice Welcome Notification" description:@"Good news: You have got network" minDisplayTime:1000 * 60 * 2 welcomeNotificationType:ATBeaconWelcomeNotificationTypeNetworkOn];
    [self addWelcomeNotification:welcomeNotificationNetworkOn];

    return YES;
}

Step 5: Configure another Welcome Notification for when a user's device network is offline

  • Repeat steps 3 and 4 to create and register another Welcome Notification that can be displayed when a user's smartphone has no internet access.
ATBeaconWelcomeNotification *welcomeNotificationNetworkOff = [[ATBeaconWelcomeNotification alloc] initTitle:@"Nice Welcome Notification" description:@"No network? Lucky you are, a free wifi is available!" minDisplayTime:1000 * 60 * 2 welcomeNotificationType:ATBeaconWelcomeNotificationTypeNetworkOff];

[self addWelcomeNotification:welcomeNotificationNetworkOff];

Step 6: About Auto Welcome Notification

Once you have registered a welcome notification, the SDK is able to generate welcome notifications automatically. You don't need more set-up.

If you need more control over the notification, there is the possibility to implement your own Welcome Notification creator. This point is discussed in the next step.

Disable the Welcome Notifications

You can disable the welcome notifications through this code in the ATBeaconAppDelegate :

[self disableWelcomeNotifications]

Step 7: Configure your own Welcome Notification Delegate

This step is only requiered if you want more control over the Welcome Notification.

  • Open the AppDelegate.m file

  • Add the ATBeaconWelcomeNotificationDelegate to your AppDelegate.m file

@interface AppDelegate : ATBeaconAppDelegate <UIApplicationDelegate,ATBeaconWelcomeNotificationDelegate>
  • Implement the ATBeaconWelcomeNotificationDelegate in the AppDelegate.h file
-(UILocalNotification *)createWelcomeNotification:(ATBeaconWelcomeNotification*) _beaconWelcomeNotification{
}

Note:

When the ATBeaconAppDelegate implements the ATBeaconWelcomeNotificationDelegate, the ATBeaconWelcomeNotificationDelegate is automatically registered in the ATBeaconManager

If you don't use the ATBeaconAppDelegate, the ATBeaconWelcomeNotificationDelegate can be registered using the [ATBeaconManager registerAdtagBeaconWelcomeNotificationDelegate: WELCOME_NOTIFICATION_DELEGATE]

  • Create a notification based on the content of the BeaconWelcomeNotification object
 -(UILocalNotification *)createWelcomeNotification:(ATBeaconWelcomeNotification *)_welcomeNotification {

    if (_welcomeNotification) {

        ILog(@"create welcome notification from app delegate");
        UILocalNotification *notification = [[UILocalNotification alloc]init];

        [notification setAlertBody:_welcomeNotification.description];
        if(SYSTEM_VERSION_GREATER_THAN(@"7.99")){
            [notification setAlertTitle:_welcomeNotification.title];
        }

        NSDictionary *infoDict = [NSDictionary dictionaryWithObject:[_welcomeNotification toJSONString] forKey:KEY_WELCOME_NOTIFICATION_CONTENT];
        [notification setUserInfo:infoDict];

        [[UIApplication sharedApplication] presentLocalNotificationNow: notification];
        return notification;

    }
    return nil;
}

Step 8: Generate the Beacon Welcome Notification analytics

  • Override the didReceiveLocalNotification 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 generate analytics associated to the beacon notifications and the beacon welcome notifications
  • to call the didReceiveNotificationContentReceived method of the ATBeaconReceiveNotificationContentDelegate when necessary
  • to call the didReceiveWelcomeNotificationContentReceived method of the ATBeaconReceiveNotificationContentDelegate when necessary (see next step)

Step 9: Open a ViewController associated to a Welcome 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,ATBeaconNotificationDelegate, ATBeaconWelcomeNotificationDelegate, ATBeaconReceiveNotificatonContentDelegate>
  • 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 didReceiveWelcomeNotificationContentReceived method of the ATBeaconReceiveNotificationContentDelegate
-(void)didReceiveWelcomeNotificationContentReceived:(ATBeaconWelcomeNotification *)_welcomeNotificationContent {
    NSDictionary* dict = [NSDictionary dictionaryWithObject: _welcomeNotificationContent forKey:@"welcomeNotification"];
    [[NSNotificationCenter defaultCenter] postNotificationName:@"BeaconWelcomeNotification" object:nil userInfo:dict];
}

Note:

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

Step 10: Ready to test

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. From Xcode, launch the installation of the application you have just built on your mobile phone.

    • If you want to perform several tests in a row, to check all situations (with or without internet connection), make sure that you completely uninstall and reinstall the application each time. Otherwise, you will not be able to see any new Welcome Notifications for the next 12 hours.
  2. Put the application in the background.

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

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

  5. Click on the notification that has appeared on your screen just for fun.

Reminder:

Welcome Notifications are configured for the whole app, and not at beacon level.

This means that the content of the notification is not associated with the specific beacon with which the user is interacting.