Customise Your notification with Payload

Since 2015 April, we have had a payload feature[see here] in the Sensorberg Management Platform. In this post we will highlight the usage of the payload object for actionable notifications on iOS devices and show different usages of the payload object.

Use Case:

We would like to show an actionable notification with custom content to our users based on the payload which we have entered user into the management platform. Using this article you can see how to set an actionable notification with a custom payload and how to handle it.

Add content in payload of your campaign

  1. Select a campaign first.
  2. Select the Advanced option.
  3. Enter your custom payload contents
  4. Save the Campaign.

“onEnter” is the object which contains the content for one actionable notification.

  • “onEnter” object will contain contents for any actions which have triggerType “On Enter”
  • “onExit” object will contain contents for any actions which have triggerType “On Exit”

“confirmationAction” can have one of following 2 options : open, share

  • open : open the URL which is given in campaign.
  • share : share the URL, which is given in campaign, on Facebook or elsewhere.

“actInForeground” is a boolean value

  • if it’s true, the app will come to the foreground and do its required actions when the user taps the ‘ok’ button or taps directly on the notification. Otherwise the app will do the specified “confirmationAction” in the background.

The following 3 language objects (“de”, “en”, “ko”) are localised strings for notification. Of course you can add more languages with ISO 639-1 language codes.

  • “okButtonTitle” : ok button title on notification.
  • “cancelButtonTitle” : cancel button title on notification.
  • “title”: subject on notification
  • “message” : message on notification

Ex : custom payload

{
  "onEnter": {
    "confirmAction": "open",
    "actInForeground": true,
    "de": {
      "okButtonTitle": "Zur Website",
      "cancelButtonTitle": "Schließen",
      "title": "Hallo!!",
      "message": "Wilkommen in Sensorberg!"
    },
    "en": {
      "okButtonTitle": "Open Website",
      "cancelButtonTitle": "Close",
      "title": "Hi!!",
      "message": "Welcome to Sensorberg!"
    },
    "ko": {
      "okButtonTitle": "사이트 열기",
      "cancelButtonTitle": "닫기",
      "title": "안녕하세요!!",
      "message": "Sensorberg에 오신것을 환영합니다!"
    }
  }
}

Get content of payload from SBCampaignAction

To get SBMCampaignAction, you need to subscribe “SBEventPerformAction” with Tolo.

  • SUBSCRIBE(SBEventPerformAction){ SBMCampaignAction *action = event.campaign; }

And check for a payload in the SBMCampaignAction object

  • if (action.payload) { ... }

Get the “onEnter” content from the payload

  • NSDictionary *actionDict = [action.payload @"onEnter"]

Register UserNotificationSettings.

NSDictionary *localizedDict = [actionDict objectForKey:@"en"];
UIMutableUserNotificationAction *okAction = [UIMutableUserNotificationAction new];
okAction.identifier = @"okActionIdentifier";
okAction.title = [localizedDict objectForKey:@"okButtonTitle"];
okAction.authenticationRequired = NO;
okAction.activationMode = [[actionDict objectForKey:@"actInForeground"] boolValue] ?UIUserNotificationActivationModeForeground : UIUserNotificationActivationModeBackground;

UIMutableUserNotificationAction *cancelAction = [UIMutableUserNotificationAction new];
cancelAction.identifier = @"cancelButtonIdentifer";
cancelAction.title = [localizedDict objectForKey:@"cancelButtonTitle"];
cancelAction.authenticationRequired = NO;
// cancel action should not activate app.
cancelAction.activationMode = UIUserNotificationActivationModeBackground;
UIMutableUserNotificationCategory *actionCategory;
actionCategory = [[UIMutableUserNotificationCategory alloc] init];
[actionCategory setIdentifier:@"myOnEnterActionCategoryIdeintifier"];
[actionCategory setActions:@[okAction, cancelAction] forContext:UIUserNotificationActionContextDefault];

NSSet *categories = [NSSet setWithObject:actionCategory];
UIUserNotificationType types = (UIUserNotificationTypeAlert|
                                UIUserNotificationTypeSound|
                                UIUserNotificationTypeBadge);

UIUserNotificationSettings *settings;
settings = [UIUserNotificationSettings settingsForTypes:types categories:categories];

[[UIApplication sharedApplication] registerUserNotificationSettings:settings];

Create a local notification with a “notification category” and then schedule the notification.

UILocalNotification *n = [UILocalNotification new];
n.alertTitle = [localizedDict objectForKey:@"title"];
n.alertBody = [localizedDict objectForKey:@"message"];
n.category =  @"myOnEnterActionCategoryIdeintifier";
n.userInfo =@{@"action": @"User Info what you need to handle"};
if (action.fireDate)
{
    n.fireDate = action.fireDate;
}
else
{
    n.fireDate = [NSDate dateWithTimeIntervalSinceNow:1];
}

[[UIApplication sharedApplication] scheduleLocalNotification:n];

The Result

Let’s see how it works on iPhone :D