What you will learn

In our Welcome Notifications document, you learned that you could display an additional notification on your users’ smartphones, the first time they interact with a beacon after a given period of time.

Just like it contains an Auto Beacon Notification, our SDK features a built-in, default Auto Welcome Beacon Notification that allows you to automatically generate a Welcome Notification once the SDK is synchronized with AdTag.

You can choose either to keep this default notification, or replace it with your own custom-built Welcome notification.

This tutorial teaches you how to configure both types of Welcome Notifications.

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.
  • You must have completed the Beacon Notification Tutorial.

Initialize the SDK

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>4-WelcomeNotification folder

SWIFT:

  • Open the sdk-tutorial>ios>SWIFT>Beacon>4-WelcomeNotification 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 (DEMO / PREPROD / PROD / PROD_US)
    • your SDK credentials
    [[[ATAdtagInitializer sharedInstance] configureUrlType:ATUrlTypeProd andLogin:@"__USER__" andPassword:@"__PSWD__" andCompany:@"__COMPANY__"] synchronize];

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

Enable your app to receive local Welcome Notifications

Step 1: Generate Beacon Welcome 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 calls the didReceiveLocalNotification method from the ATBeaconManager, which allows your app:

  • to generate analytics associated with your beacon notifications and 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)

If you cannot use the ATBeaconAppDelegate, you can call that same didReceiveLocalNotification method as follows:

[[ATBeaconManager sharedInstance] didReceiveLocalNotification:notification];

Step 2: Open a ViewController associated with a Beacon Welcome Notification

  • Open the AppDelegate.h file

  • Add the ATBeaconReceiveNotificationContentDelegate to the AppDelegate, to allow your app to be notified when a user clicks on a local beacon notification

@interface AppDelegate : ATBeaconAppDelegate <UIApplicationDelegate, ATBeaconReceiveNotificatonContentDelegate>

Note 1:

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];
}
  • Implement the didReceiveBeaconWelcomeNotification method of the ATBeaconReceiveNotificationContentDelegate
-(void)didReceiveBeaconWelcomeNotification:(id<ATBeaconWelcomeNotification>)_welcomeNotificationContent {
    //Simple way to redirect to a ViewController - not the best
    NSDictionary* dict = [NSDictionary dictionaryWithObject: _welcomeNotificationContent forKey:@"welcomeNotification"];
    [[NSNotificationCenter defaultCenter] postNotificationName:@"BeaconWelcomeNotification" object:nil userInfo:dict];
}

Note 2:

This method is called when users click on a welcome notification, to open the ViewController associated with the ATBeaconWelcomeNotification

If your application uses deep links, you can use the welcomeNotification.deepLink field to retrieve the deep link associated with the notification.

Activate & configure your Welcome Notifications in AdTag

Welcome Notifications can be activated and configured directly on our AdTag platform, in the Application Management section.

For additional information on Welcome Notification settings, refer to our Introduction to Welcome Notifications.

Choose your Welcome Notification configuration

Work with Auto Welcome Notifications

Once the Welcome Notification feature is enabled on AdTag, and a content is defined, our SDK automatically starts generating Auto Welcome Notifications.

Configure a custom-built Welcome Notification

If you would like to implement notifications that are more customizable than our Auto Welcome Beacon notifications, you can create your own Welcome Notification Builder, as described in the following section.

Welcome Notification model overview

First, let’s go through an overview of the Welcome Notification model, with the corresponding interfaces and built-in objects.

The ATAsyncBeaconWelcomeNotificationDelegate

The ATAsyncBeaconNotificationDelegate is an interface that:

  • alerts your application when it has to create a Welcome beacon notification, using the createBeaconWelcomeNotification method.
  • allows your application to complete an asynchronous task of your choice before displaying a Welcome notification.

The createBeaconWelcomeNotification method has two arguments:

  • ATBeaconWelcomeNotification: the content defined in the App Management section on the Adtag Platform.
  • ATAsyncBeaconWelcomeNotificationManager: the object used to notify the SDK when the notification is ready to be displayed.
The ATAsyncBeaconWelcomeNotificationManager

The ATAsyncBeaconWelcomeNotificationManager is an interface that is mainly in charge of displaying Welcome notifications.

To notify the ATAsyncBeaconWelcomeNotificationManager of the need to display a notification, you must call the displayBeaconWelcomeNotification method.

The displayBeaconWelcomeNotification method has two arguments:

  • ATBeaconWelcomeNotification: the content used to create the notification.
  • Notification: the notification that will be displayed, which can either be an UNMutableNotificationContent or an UILocalNotification object.
The AsyncBeaconWelcomeNotificationImageCreator

The ATAsyncWelcomeBeaconNotificationImageCreator is a specific implementation of the ATAsyncWelcomeBeaconNotificationDelegate interface. It directly download the notification image from ADTAG, and display the beacon notification with the corresponding image for iOs 10 and above.

The ATAsyncBeaconWelcomeNotificationImageCreator must be initialized with an ATBeaconWelcomeNotificationImageBuilder.

The ATBeaconWelcomeNotificationImageBuilder

The ATBeaconWelcomeNotificationImageBuilder interface allows to create native local Notifications once images are loaded.

It must implement the buildBeaconWelcomeNotification method, which has two arguments:

  • welcomeNotification: content used to create the notification
  • urlImage: local url of the Adtag image used in the notification attachment. It can be nil.

This method must return a UILocalNotification or an UNMutableNotificationContent

Note:

You have two options to customize your beacon notifications:

  • Option 1: you can use our pre-built ATBeaconWelcomeNotificationImageCreator, to simply customize your notifications with images
  • Option 2: or you can implement your own ATAsyncBeaconWelcomeNotificationDelegate for wider customization abilities

Option 1 is the simpler of the two; option 2 is great if you need to implement your own async tasks

Option 1 will be explored in the following step. If you are interested in option 2, you can find a basic implementation of the ATAsyncBeaconWelcomeNotificationDelegate inside the notification demo code folder.

Step 1: Create your own BeaconWelcomeNotificationImageBuilder
  • Create a new class named MyBeaconWelcomeNotificationBuilder
  • In the MyBeaconWelcomeNotificationBuilder.h file:
    • Import the ATLocationBeacon
    • Implement the ATBeaconWelcomeNotificationImageBuilderDelegate
#import <Foundation/Foundation.h>
#import <ATLocationBeacon/ATLocationBeacon.h>

@interface MyBeaconWelcomeNotificationBuilder : NSObject <ATBeaconWelcomeNotificationImageBuilder>

@end
  • Declare the buildBeaconNotification method in the MyBeaconWelcomeNotificationBuilder.m file
@implementation MyBeaconWelcomeNotificationBuilder

-(NSObject *)createBeaconWelcomeNotification:(id<ATBeaconWelcomeNotification>)content andImageUrl:(NSURL *)imageUrl{
    
}

@end
Step 2: Generate the local notification
  • Enable your app to create the appropriate notification based on the user’s iOS version
-(NSObject *) createBeaconWelcomeNotification:(id<ATBeaconWelcomeNotification>)content andImageUrl:(NSURL *)imageUrl{
    NSDictionary *infoDict = [NSDictionary dictionaryWithObject:[((ATJSONModel *)content) toJSONString] forKey:[content mKey]];
    
    if (SYSTEM_VERSION_GREATER_THAN_OR_EQUAL_TO(@"10.0")) {
        UNMutableNotificationContent *notificationContent = [[UNMutableNotificationContent alloc] init];
        notificationContent.title = [content mTitle];
        notificationContent.body = [content mDescription];
        notificationContent.userInfo = infoDict;
        if(imageUrl){
            UNNotificationAttachment *attachement1 = [UNNotificationAttachment attachmentWithIdentifier:@"com.connecthings.beaconWelcomeNotificationImage" URL:imageUrl options:nil error:nil];
            notificationContent.attachments=@[attachement1];
        }
        return notificationContent;
    }else{
        UILocalNotification *notification = [[UILocalNotification alloc]init];
        [notification setAlertBody:[content mDescription]];
        if(SYSTEM_VERSION_GREATER_THAN(@"7.99")){
            [notification setAlertTitle:[content mTitle]];
        }
        [notification setUserInfo:infoDict];
        return notification;
    }
}

Note:

The ATBeaconWelcomeNotification is saved as a JSON String in the NSDictionnary associated with the notification. NSDictionary *infoDict = [NSDictionary dictionaryWithObject:[((ATJSONModel *)content) toJSONString] forKey:[content mKey]]; > This allows the SDK to generate analytics, and enables you to easily get the ATBeaconWelcomeNotification associated with the notification.

Step 3: Register your AsyncBeaconWelcomeNotificationDelegate
  • Open the AppDelegate.m file
  • Register an ATAsyncBeaconWelcomeNotificationImageCreator with a MyBeaconWelcomeNoficationBuilder.
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    [...]

    [self registerAsyncBeaconWelcomeNotificationDelegate:[[ATAsyncBeaconWelcomeNotificationImageCreator alloc] initWithWelcomeNotificationImageBuilder:[[MyBeaconWelcomeNotificationBuilder alloc] init]]];
}

Note:

If your AppDelegate does not extend the ATBeaconAppDelegate, you can use:

[[ATBeaconManager sharedInstance] registerAsyncBeaconWelcomeNotificationDelegate:[[ATAsyncBeaconWelcomeNotificationImageCreator alloc] initWithWelcomeNotificationImageBuilder:[[MyBeaconWelcomeNotificationBuilder alloc] init]]];

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. 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, for instance to check both your “Offline” and “Online” Welcome notifications, 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 (default setting).
  2. When the application starts, popups ask for permission to access your phone location, Bluetooth & notifications: grant them!

  3. Close your application or leave it running in the background

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

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

  6. 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 that the user is interacting with.