Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Table of Contents

Introduction

Starting with Release 3.4.0, you You can create interactive notifications, where users can respond to application notifications without launching the application to the foreground. The user needs to reveal notification actions in the notification, then press a notification action to respond to the notification. This feature is available on devices running iOS 8 or later.

...

Interactive notification types

The following screen shots screenshots illustrate how iOS presents and the user interacts with the notification:

...

Like notification types, you also need to register notification categories with iOS by using the Titanium.App.iOS.registerUserNotificationSettings() methodmethod.  Pass Pass the method a dictionary with the type property set to the notification types to use and the categories property to an array of notification category objects the application needs to use.

...

If you are using push notifications, the application needs to call the Titanium.Network.registerForPushNotifications() method.  The The application should monitor the usernotificationsettings to register for push notifications. 

...

The application can monitor interactive notifications and respond to them in the background by using the  iOS application-level level localnotificationaction  event event for local notifications and remotenotificationaction event for push notifications.  The The event is triggered when the user selects a notification action.

localnotificationaction

Monitor the  the iOS application-level localnotificationaction event to respond to an interactive local notification.  The event is passed the same object as the  notification  event except it returns two extra properties:

...

 

Code Block
linenumberstrue
languagejs
Ti.App.iOS.addEventListener('localnotificationaction', function(e) {
    // Switch for categories
    switch (e.category) {
        case "DOWNLOAD_CATEGORY":
            // Switch for actions
            switch (e.identifier) {
                case "ACCEPT_IDENTIFIER":
                    if (e.userInfo && "url" in e.userInfo){
                        httpGetRequest(e.userInfo.url);
                    }
                    break;
                // more actions...
            }
            break;
        // more categories...
        default:
            break;
    };
});	

remotenotificationaction

Monitor the iOS application-level remotenotificationaction event to respond to an interactive push notification.  The The event is passed an object with the following  properties:

  • category: string identifier indicating the notification category that triggered the event
  • data: push notification payload as a JSON object
  • identifier: string identifier indicating the notification action the user pressed
Use the properties to have the application decide how to respond to the interactive notification.

 

Code Block
linenumberstrue
languagejs
Ti.App.iOS.addEventListener('remotenotificationaction', function(e) {
    // Switch for categories
    switch (e.category) {
        case "DOWNLOAD_CATEGORY":
            // Switch for actions
            switch (e.identifier) {
                case "ACCEPT_IDENTIFIER":
                    if (e.data && "url" in e.data){
                        httpGetRequest(e.data.url);
                    }
                    break;
                // more actions...
            }
            break;
        // more categories...
        default:
            break;
    };
});

 

Schedule an interactive local notification

To send an interactive local notification, use the Titanium.App.iOS.scheduleLocalNotification() method.  Use Use it the same way when scheduling a non-interactive local notifications except when creating the dictionary of options to pass to the method, the application must specify the category property and set it to the identifier of the notification category to use.  The notification category indicates which group of actions to use with the notification.  The notification category must also be registered or else the notification will be presented as a default non-interactive notification.

Code Block
linenumberstrue
languagejs
Ti.App.iOS.scheduleLocalNotification({
    date: new Date(new Date().getTime() + 3000),
    alertBody: "New content available! Download now?",
    badge: 1,
    userInfo: {"url": "http://www.download.com/resource/asset.json"},
    category: "DOWNLOAD_CATEGORY"
});

Send an interactive push notification

To send an interactive push notification, send a payload with the category field set to the identifier of the notification category to use.

Code Block
linenumberstrue
languagejs
{
    "alert": "New content available! Download now?",
    "badge": 1,
    "url": "http://www.download.com/resource/asset.json",
    "category": "DOWNLOAD_CATEGORY"    
}
To send the payload, you can use either the:

Example

In the following example, run the code on an iOS device or simulator.  Click Click the "Trigger Notification" button, then either lock the phone or place the application in the background.  You will have three seconds or else the application will respond to the notification in the foreground.  If If the device or simulator is running iOS 8 or later, you will receive the interactive local notification.  If If not, you will receive a regular local notification.

Code Block
linenumberstrue
languagejs
// Check for iOS 8 or greater
if (Ti.Platform.name == "iPhone OS" && parseInt(Ti.Platform.version.split(".")[0]) >= 8) {
    Ti.API.info("I am iOS 8!");
    // Create notification actions
    var acceptAction = Ti.App.iOS.createUserNotificationAction({
        identifier: "ACCEPT_IDENTIFIER",
        title: "Accept",
        activationMode: Ti.App.iOS.USER_NOTIFICATION_ACTIVATION_MODE_FOREGROUND,
        destructive: false,
        authenticationRequired: true
    });
    
    var rejectAction = Ti.App.iOS.createUserNotificationAction({
        identifier: "REJECT_IDENTIFIER",
        title: "Reject",
        activationMode: Ti.App.iOS.USER_NOTIFICATION_ACTIVATION_MODE_BACKGROUND,
        destructive: true,
        authenticationRequired: false
    });

    // Create a notification category
    var downloadContent = Ti.App.iOS.createUserNotificationCategory({
      identifier: "DOWNLOAD_CONTENT",
      actionsForDefaultContext: [acceptAction, rejectAction]
    });    

    // Register for user notifications and categories
    Ti.App.iOS.registerUserNotificationSettings({
        types: [
            Ti.App.iOS.USER_NOTIFICATION_TYPE_ALERT,
            Ti.App.iOS.USER_NOTIFICATION_TYPE_BADGE,
            Ti.App.iOS.USER_NOTIFICATION_TYPE_SOUND
        ],
        categories: [downloadContent]
    });

    // Monitor notifications received while app is in the background
    Ti.App.iOS.addEventListener('localnotificationaction', function(e) {
        if (e.category == "DOWNLOAD_CONTENT" && e.identifier == "ACCEPT_IDENTIFIER") {
            alert("start download");
        }
        
        // Reset the badge value
        if (e.badge > 0) {
            Ti.App.iOS.scheduleLocalNotification({
                date: new Date(new Date().getTime() + 3000),
                badge: "-1"
            });
        }
        Ti.API.info(JSON.stringify(e));
    });
}

// Monitor notifications received while app is in the foreground 
Ti.App.iOS.addEventListener('notification', function(e) { 
    // Reset the badge value
    if (e.badge > 0) {
        Ti.App.iOS.scheduleLocalNotification({
            date: new Date(new Date().getTime() + 3000),
            badge: "-1"
        });
    }
    Ti.API.info(JSON.stringify(e));
});
// App UI
var win = Ti.UI.createWindow({backgroundColor: 'white'});
var button = Ti.UI.createButton({title: 'Trigger Notification'});
button.addEventListener('click', function(e){ 
    // Send a notification in 3 seconds
    var note = Ti.App.iOS.scheduleLocalNotification({
        date: new Date(new Date().getTime() + 3000),
        alertBody: "New content available! Download now?",
        badge: 1,
        userInfo: {"url": "http://www.download.com/resource/asset.json", id:"1"},
        category: "DOWNLOAD_CONTENT"
    });    
});
win.add(button);
win.open();