@maccesar/titools 5.2.5 → 5.4.0

package/skills/ti-howtos/references/notification-services.md

@@ -1,551 +1,131 @@
-# Push and local notifications
+# Notifications
 
-Guide to local and push notifications on iOS and Android.
+Based on the [current official guide](https://titaniumsdk.com/docs/build/notifications.md). Examples target released SDK 13.4.1; verify the selected SDK before adopting version-specific behavior.
 
-<!-- TOC-START -->
-## Contents
+Two kinds, and they share almost nothing in Titanium. A **local** notification
+is scheduled by the app on the device. A **push** notification arrives from a
+server through APNs or FCM.
 
-- [Local notifications: Android](#local-notifications-android)
-- [Local notifications: iOS](#local-notifications-ios)
-- [Interactive notifications: iOS (iOS 8+)](#interactive-notifications-ios-ios-8)
-- [Push notifications](#push-notifications)
-- [Common patterns](#common-patterns)
-- [Platform-specific notes](#platform-specific-notes)
+Both need the user's permission on both platforms. Android has required it
+since Android 13.
 
-<!-- TOC-END -->
+## Local notifications
 
-## Local notifications: Android
+The APIs are platform-specific, so this is one of the places you write both
+halves.
 
-### Notification display locations
+**iOS**
 
-- Notification drawer: swipe down from status bar
-- Lock screen: Android 5.0+ (API 21+)
-- Status bar: icon and ticker text
-
-### Create a notification
-
-Basic layout:
-```javascript
-const notification = Ti.Android.createNotification({
-  contentTitle: 'Notification Title',
-  contentText: 'Notification message',
-  contentIntent: Ti.Android.createPendingIntent({
-    intent: Ti.Android.createIntent({})
-  }),
-  icon: Ti.App.Android.R.drawable.warn, // or '/images/warn.png'
-  number: 5, // Badge number
-  when: new Date(), // Timestamp (does not schedule)
-  tickerText: 'Text in status bar when notification first appears'
-});
-
-// Send immediately
-Ti.Android.NotificationManager.notify(1, notification);
-```
-
-Icon paths:
-- Density-specific: `/app/assets/android/images/` (Alloy) or `/Resources/android/images/` (Classic), reference as `/images/filename.png`
-- Drawable folder: `/platform/android/res/drawable/filename.png`, reference as `Ti.App.Android.R.drawable.filename`
-
-### Sound
-
-```javascript
-const notification = Ti.Android.createNotification({
-  // ... other properties
-  sound: `${Ti.Filesystem.getResRawDirectory()}sound.wav`
-});
-```
-
-Play only once (add flag):
-```javascript
-notification.flags |= Ti.Android.FLAG_ONLY_ALERT_ONCE;
-```
-
-### Custom layout with RemoteViews
-
-1. Create XML layout (`/platform/android/res/layout/customview.xml`):
-```xml
-<?xml version="1.0" encoding="utf-8"?>
-<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
-    android:layout_width="match_parent"
-    android:layout_height="match_parent"
-    android:orientation="horizontal">
-    <TextView android:id="@+id/message"
-        android:layout_width="wrap_content"
-        android:layout_height="wrap_content"
-        android:text="Default text" />
-    <Button android:id="@+id/okbutton"
-        android:layout_width="wrap_content"
-        android:layout_height="wrap_content"
-        android:text="OK" />
-</LinearLayout>
-```
-
-2. Create RemoteViews and bind intents:
-```javascript
-const customView = Ti.Android.createRemoteViews({
-  layoutId: Ti.App.Android.R.layout.customview
-});
-
-// Modify text
-customView.setTextViewText(Ti.App.Android.R.id.message, 'Update available!');
-
-// Bind intents to buttons
-const downloadIntent = Ti.Android.createPendingIntent({ intent: Ti.Android.createIntent() });
-customView.setOnClickPendingIntent(Ti.App.Android.R.id.okbutton, downloadIntent);
-
-const notification = Ti.Android.createNotification({
-  contentView: customView // Avoid setting contentTitle/contentText or they override this
-});
-```
-
-### Additional properties
-
-Defaults (device settings):
-```javascript
-notification.defaults = Ti.Android.DEFAULT_ALL; // or DEFAULT_SOUND, DEFAULT_VIBRATE, DEFAULT_LIGHTS
-```
-
-Flags (behavior):
-```javascript
-notification.flags |= Ti.Android.FLAG_AUTO_CANCEL; // Clear on tap
-notification.flags |= Ti.Android.FLAG_INSISTENT; // Repeat sound until canceled
-notification.flags |= Ti.Android.FLAG_NO_CLEAR; // Do not clear with "clear all"
-notification.flags |= Ti.Android.FLAG_ONGOING_EVENT; // Ongoing event (for example, music player)
-notification.flags |= Ti.Android.FLAG_ONLY_ALERT_ONCE; // Do not replay sound/vibrate
-notification.flags |= Ti.Android.FLAG_SHOW_LIGHTS; // Use LED (if device allows)
-```
-
-Priority (Android 4.1+):
-```javascript
-notification.priority = Ti.Android.PRIORITY_HIGH; // or PRIORITY_MAX, PRIORITY_DEFAULT, PRIORITY_LOW, PRIORITY_MIN
-```
-
-Category (Android 5.0+):
-```javascript
-notification.category = Ti.Android.CATEGORY_MESSAGE; // or CATEGORY_ALARM, CALL, EMAIL, ERROR, EVENT, etc.
-```
-
-Visibility (Android 5.0+ - lock screen):
-```javascript
-notification.visibility = Ti.Android.VISIBILITY_PUBLIC; // Show all
-// or VISIBILITY_PRIVATE (hide content), VISIBILITY_SECRET (do not show)
-```
-
-### Update notification
-
-```javascript
-notification.setLatestEventInfo('New Title', 'New Message', notification.contentIntent);
-```
-
-### Remove notifications
-
-```javascript
-// Remove specific notification
-Ti.Android.NotificationManager.cancel(1);
-
-// Remove all notifications
-Ti.Android.NotificationManager.cancelAll();
-```
-
-### Respond to notification tap
-
-Launch app when tapped:
-```javascript
-const intent = Ti.Android.createIntent({
-  action: Ti.Android.ACTION_MAIN,
-  className: 'com.titaniumsdk.testapp.MyappActivity', // ProjectName + Activity
-  packageName: 'com.titaniumsdk.testapp'
-});
-intent.flags |= Ti.Android.FLAG_ACTIVITY_RESET_TASK_IF_NEEDED | Ti.Android.FLAG_ACTIVITY_SINGLE_TOP;
-intent.addCategory(Ti.Android.CATEGORY_LAUNCHER);
-
-notification.contentIntent = Ti.Android.createPendingIntent({ intent: intent });
-```
-
-### Delete intent (notification cleared)
-
-```javascript
-// Execute intent when user clears notification
-notification.deleteIntent = Ti.Android.createPendingIntent({
-  intent: Ti.Android.createIntent({
-    action: 'com.myapp.NOTIFICATION_CLEARED'
-  })
-});
-```
-
-### Schedule future notification (background service)
-
-`tiapp.xml`:
-```xml
-<android xmlns:android="http://schemas.android.com/apk/res/android">
-    <services>
-        <service url="ExampleService.js" type="interval" />
-    </services>
-</android>
-```
-
-`ExampleService.js`:
-```javascript
-const service = Ti.Android.currentService;
-const serviceIntent = service.getIntent();
-const timestamp = new Date(serviceIntent.getStringExtra('timestamp'));
-
-if (new Date() > timestamp) {
-  const title = serviceIntent.getStringExtra('title');
-  const message = serviceIntent.getStringExtra('message');
-
-  const notification = Ti.Android.createNotification({
-    contentTitle: title,
-    contentText: message,
-    contentIntent: Ti.Android.createPendingIntent({ intent: Ti.Android.createIntent() })
-  });
-
-  Ti.Android.NotificationManager.notify(1, notification);
-  Ti.Android.stopService(serviceIntent);
-}
-```
-
-Main app:
-```javascript
-const intent = Ti.Android.createServiceIntent({ url: 'ExampleService.js' });
-intent.putExtra('interval', 5000); // Check every 5 seconds
-intent.putExtra('timestamp', new Date(new Date().getTime() + (30 * 1000))); // Fire in 30 seconds
-intent.putExtra('title', 'Scheduled Notification');
-intent.putExtra('message', 'This was scheduled!');
-Ti.Android.startService(intent);
-```
-
-## Local notifications: iOS
-
-### Notification display locations
-
-- Alert dialog: Open or Close buttons (background, unlocked)
-- Banner message: swipe down for actions, tap to launch (background, unlocked)
-- Lock screen: swipe right to launch
-- Notification Center: queued notifications
-- Badge: number on app icon
-- Sound: audio alert
-
-### Register for notifications (iOS 8+)
-
-```javascript
-if (Ti.Platform.name === 'iPhone OS' && parseInt(Ti.Platform.version.split('.')[0]) >= 8) {
-  Ti.App.iOS.registerUserNotificationSettings({
-    types: [
-      Ti.App.iOS.USER_NOTIFICATION_TYPE_ALERT,
-      Ti.App.iOS.USER_NOTIFICATION_TYPE_SOUND,
-      Ti.App.iOS.USER_NOTIFICATION_TYPE_BADGE
-    ]
-    // Add 'categories' for interactive notifications
-  });
-}
-```
-
-Note: iOS shows a system prompt the first time. Check current settings with:
-```javascript
-Ti.App.iOS.addEventListener('usernotificationsettings', (e) => {
-  Ti.API.info(`Notification types allowed: ${e.types}`);
-});
-```
-
-### Schedule local notification
-
-```javascript
-const notification = Ti.App.iOS.scheduleLocalNotification({
-  date: new Date(new Date().getTime() + 3000), // 3 seconds from now
-  alertBody: 'New content available!',
-  alertAction: 'update', // Changes "slide to view" to "slide to update" or "Open" to "Update"
-  alertLaunchImage: 'splash.png', // Custom splash image
-  badge: 1, // Set badge number (negative to clear)
-  sound: '/alert.wav', // Sound file in Resources or app/assets
-  category: 'CATEGORY_ID', // For interactive notifications
-  repeat: 'daily', // or 'weekly', 'monthly', 'yearly'
-  timezone: 'America/Los_Angeles', // Optional (default: system timezone)
-  userInfo: { url: 'http://example.com/data.json', id: '123' } // Custom data
-});
-```
-
-### Monitor notifications
-
-While app is in foreground or returns to foreground:
-```javascript
-Ti.App.iOS.addEventListener('notification', (e) => {
-  // Process custom data
-  if (e.userInfo && e.userInfo.url) {
-    // Handle URL
+```js
+// Install the result listener before requesting permission.
+Ti.App.iOS.addEventListener('usernotificationsettings', onSettings);
+function onSettings(event) {
+  Ti.App.iOS.removeEventListener('usernotificationsettings', onSettings);
+  if (!event.types || event.types.length === 0) {
+    Ti.API.warn('Notification presentation permission denied');
+    return;
   }
-
-  // Reset badge
-  if (e.badge > 0) {
-    Ti.App.iOS.scheduleLocalNotification({
-      date: new Date(),
-      badge: -1
-    });
-  }
-});
-```
-
-### Cancel notifications
-
-```javascript
-// Cancel all
-Ti.App.iOS.cancelAllLocalNotifications();
-
-// Cancel specific notification
-const notification = Ti.App.iOS.scheduleLocalNotification({ ... });
-notification.cancel();
-
-// Or by ID
-Ti.App.iOS.scheduleLocalNotification({
-  userInfo: { id: 'foo' },
-  alertBody: 'Test'
-});
-Ti.App.iOS.cancelLocalNotification('foo');
-```
-
-## Interactive notifications: iOS (iOS 8+)
-
-### Create notification actions
-
-```javascript
-const acceptAction = Ti.App.iOS.createUserNotificationAction({
-  identifier: 'ACCEPT_IDENTIFIER',
-  title: 'Accept',
-  activationMode: Ti.App.iOS.USER_NOTIFICATION_ACTIVATION_MODE_FOREGROUND, // or BACKGROUND
-  destructive: false,
-  authenticationRequired: true // Require device unlock
-});
-
-const rejectAction = Ti.App.iOS.createUserNotificationAction({
-  identifier: 'REJECT_IDENTIFIER',
-  title: 'Reject',
-  activationMode: Ti.App.iOS.USER_NOTIFICATION_ACTIVATION_MODE_BACKGROUND,
-  destructive: true, // Red background in lock screen/notification center
-  authenticationRequired: false
-});
-```
-
-### Create notification category
-
-```javascript
-const category = Ti.App.iOS.createUserNotificationCategory({
-  identifier: 'INVITE_CATEGORY',
-  actionsForDefaultContext: [acceptAction, rescheduleAction, delayAction, rejectAction], // Alert dialog (4 max)
-  actionsForMinimalContext: [acceptAction, rejectAction] // Other styles (2 max)
-});
-```
-
-### Register categories
-
-```javascript
+  scheduleReminder();
+}
 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: [category]
+    Ti.App.iOS.USER_NOTIFICATION_TYPE_SOUND,
+    Ti.App.iOS.USER_NOTIFICATION_TYPE_BADGE
+  ]
 });
+
+function scheduleReminder() {
+  Ti.App.iOS.scheduleLocalNotification({
+  alertTitle: 'Standup',
+  alertBody: 'Daily standup in five minutes',
+    date: new Date(Date.now() + 5 * 60 * 1000)
+  });
+}
 ```
 
-### Monitor interactive notifications
+Use `Ti.App.iOS.UserNotificationCenter.getPendingNotifications()` and `removePendingNotifications()` to cancel pending alerts; `removeDeliveredNotifications()` clears delivered entries. The older `cancelLocalNotification`, `cancelAllLocalNotifications` and returned object's `cancel()` are deprecated since SDK 7.3.0. Canceling a delivered entry is different from canceling its future schedule.
 
-Local notifications:
-```javascript
-Ti.App.iOS.addEventListener('localnotificationaction', (e) => {
-  // e.category: category identifier
-  // e.identifier: action identifier
-  // e.userInfo: custom data
+**Android**
 
-  if (e.category === 'INVITE_CATEGORY' && e.identifier === 'ACCEPT_IDENTIFIER') {
-    // Handle accept
-    if (e.userInfo && e.userInfo.url) {
-      // Process URL
-    }
-  }
+Declare `android.permission.POST_NOTIFICATIONS` in `<android><manifest>` and request Android 13+ permission from an opened window before posting. `Ti.Network.registerForPushNotifications({ success, error })` requests that permission on Android; its success callback does not supply an FCM token. Handle denial and settings restrictions.
 
-  // Reset badge
-  if (e.badge > 0) {
-    Ti.App.iOS.scheduleLocalNotification({ date: new Date(), badge: -1 });
-  }
+```js
+const channel = Ti.Android.NotificationManager.createNotificationChannel({
+  id: 'reminders',
+  name: 'Reminders',
+  importance: Ti.Android.IMPORTANCE_DEFAULT
 });
-```
 
-Push notifications:
-```javascript
-Ti.App.iOS.addEventListener('remotenotificationaction', (e) => {
-  // e.category: category identifier
-  // e.identifier: action identifier
-  // e.data: push notification payload (JSON)
-
-  if (e.category === 'DOWNLOAD_CATEGORY' && e.identifier === 'ACCEPT_IDENTIFIER') {
-    if (e.data && e.data.url) {
-      // Process URL
-    }
-  }
+const notification = Ti.Android.createNotification({
+  contentTitle: 'Standup',
+  contentText: 'Daily standup in five minutes',
+  channelId: 'reminders'
 });
-```
 
-### Schedule interactive local notification
-
-```javascript
-Ti.App.iOS.scheduleLocalNotification({
-  date: new Date(new Date().getTime() + 3000),
-  alertBody: 'New content available! Download now?',
-  badge: 1,
-  userInfo: { url: 'http://example.com/data.json' },
-  category: 'INVITE_CATEGORY' // Must match registered category identifier
-});
+Ti.Android.NotificationManager.notify(1, notification);
 ```
 
-### Send interactive push notification
+The integer passed to `notify` is the notification's id: notify again with the
+same one and it replaces rather than stacks.
 
-Payload format:
-```json
-{
-  "alert": "New content available! Download now?",
-  "badge": 1,
-  "url": "http://example.com/data.json",
-  "category": "INVITE_CATEGORY"
-}
-```
+> [!IMPORTANT]
+> **Android needs a channel.** Since Android 8 a notification without a valid
+> `channelId` is dropped by the system, with nothing in the log to say so. Create
+> the channel once at startup - creating it again with the same id is a no-op.
+>
+> Channel importance is not freely reconfigured after creation. The user owns it
+> from then on, and a release that wants a channel to behave differently needs a
+> new id.
 
 ## Push notifications
 
-### Overview
-
-Push notifications allow server-to-device communication. Infrastructure differs by platform:
-
-- Android: Firebase Cloud Messaging (FCM)
-- iOS: Apple Push Notification service (APNs)
-
-Note: the legacy Appcelerator Cloud Services (ACS/ArrowDB) push backend is no longer available. Use FCM for Android and APNs for iOS, either directly or via a third-party service.
-
-Google has deprecated Google Cloud Messaging (GCM) in favor of FCM. All new implementations should use FCM.
-
-For FCM on Titanium, use the community module `titanium-firebase-cloud-messaging` (by Hans Knöchel).
+APNs and FCM registration are platform-specific. Send the resulting platform token to your backend, which sends the notifications. The following core API example is for **iOS APNs**, after the `usernotificationsettings` callback; it is not an Android FCM registration recipe.
 
-### Register for push notifications
-
-```javascript
+```js
 Ti.Network.registerForPushNotifications({
-  success: (e) => {
-    // e.deviceToken: token to send to your push server
-    Ti.API.info(`Device Token: ${e.deviceToken}`);
-    // Send this token to your server
+  success(e) {
+    Ti.API.info(`device token ${e.deviceToken}`);
+    // POST it to your own server here.
   },
-  error: (e) => {
-    Ti.API.error(`Push registration error: ${e.error}`);
+  error(e) {
+    Ti.API.error(`push registration failed: ${e.error}`);
   },
-  callback: (e) => {
-    // Incoming push notification
-    // e.data: push payload (iOS)
-    // e.data: JSON object (Android)
-    Ti.API.info(`Push received: ${JSON.stringify(e.data)}`);
+  callback(e) {
+    // A notification arrived. `e.data` is the payload.
+    Ti.API.info(e.data);
   }
 });
 ```
 
-### APNs configuration (iOS)
-
-1. Register an explicit App ID (not wildcard) with Push Notifications enabled in Apple Developer Portal.
-2. Generate an APNs certificate (Development for sandbox, Production for App Store).
-3. Export the certificate as PKCS#12 (.p12) from Keychain Access.
-4. Upload the .p12 to your push service provider.
-5. In your app, call `Ti.Network.registerForPushNotifications()` to get the device token.
-
-### FCM configuration (Android)
-
-1. Create a project in Firebase Console.
-2. Add your Android app (use your app's package name).
-3. Download `google-services.json` and place it in the project root.
-4. Add `titanium-firebase-cloud-messaging` to `tiapp.xml`.
-5. Register for push and obtain the FCM token.
-
-### Push notification payload format
-
-iOS:
-```json
-{
-  "aps": {
-    "alert": "Message text",
-    "badge": 1,
-    "sound": "default"
-  },
-  "custom_field": "custom_value"
-}
-```
-
-Android:
-```json
-{
-  "message": "Message text",
-  "title": "Notification Title",
-  "custom_field": "custom_value"
-}
-```
-
-### Send push notifications
-
-Send push notifications from your server using the FCM HTTP API or APNs. Collect device tokens from client registration and target them with your push payload.
-
-### Best practices
-
-1. Permissions: iOS requires user permission (prompted on first call to `registerForPushNotifications`).
-2. Device tokens: cache and send to your server; they can change on app updates.
-3. Background handling: use proper activation modes for interactive notifications.
-4. Badge management: reset the badge after processing a notification.
-5. Error handling: handle registration failures gracefully.
-6. Testing: use development certificates/sandbox for iOS testing.
-
-## Common patterns
-
-### Check notification permissions
-
-```javascript
-// Android 4.1+ can disable notifications per app
-// Check via Settings or handle gracefully (notification may not be shown)
-```
-
-### PendingIntent for notification actions
-
-```javascript
-const intent = Ti.Android.createIntent({
-  action: 'com.example.MY_ACTION'
-  // Add data/flags
-});
-const pendingIntent = Ti.Android.createPendingIntent({
-  intent: intent,
-  flags: Ti.Android.FLAG_UPDATE_CURRENT
-});
-```
-
-### Notification groups (Android 7.0+)
+`callback` fires when a notification is received **and** when one is tapped, so
+if opening a screen is the response, check whether the app was in the
+foreground first - otherwise a notification arriving while someone is using the
+app navigates them away from what they were doing.
 
-```javascript
-// Requires API 24+; check documentation for latest implementation
-```
+On iOS, ask for notification permission with
+`registerUserNotificationSettings` before registering for push. On Android, use a native FCM integration and its own token/message APIs. The guide mentions `google-services.json` and `ti.playservices`, but those alone do not implement FCM registration. Follow the selected integration's current installation instructions, including dependencies and configuration-file placement. Core `callback` / `success.deviceToken` are Apple-only.
 
-### Rich notifications (iOS 10+)
+The token changes. It changes on reinstall, on restore to a new device, and at
+the platform's discretion. Send it on every launch rather than once.
 
-Use `UNMutableNotificationContent` with attachments (images, video, audio).
+## Testing
 
-### Silent push
+Use a signed device build to validate APNs end to end; simulator capabilities depend on the selected OS/Xcode environment. An Android emulator needs the required Play Services/FCM integration. Local notification testing does not prove remote delivery.
 
-```javascript
-// iOS: include "content-available": 1 in payload
-// Android: use data messages (FCM)
-```
+The most common "push is broken" causes, in the order worth checking:
 
-## Platform-specific notes
+1. **The wrong environment.** A development APNs token is not valid against the
+   production gateway, and the failure is silent.
+2. **No permission.** Handle permission denial and explain the relevant system settings; do not assume another request will always show a dialog.
+3. **Missing channel on Android.** See above.
+4. **The token is stale.** See above.
 
-### Android
+![An expanded notification in the Android shade, posted by an app called Hello. Its icon sits at the left, the title reads Standup and the body reads Daily standup in five minutes.](https://titaniumsdk.com/docs/guides/notification-shade-android.png)
 
-- Service lifecycle: services may be killed if app is swiped away. For critical notifications, use FCM instead of local services.
-- Notification channels: Android 8.0+ requires notification channels.
+## Next
 
-### iOS
+[Using modules](https://titaniumsdk.com/docs/build/modules.md) covers adding capabilities the core SDK
+does not have, which is what `ti.playservices` above is.
 
-- Sandbox vs production: use correct certificates and endpoints.
-- Background app refresh: may be needed for certain push scenarios.
-- LiveView: callbacks only work properly when LiveView is enabled.
+Contract corrections: [released Network API](https://github.com/tidev/titanium-sdk/blob/13_4_1_GA/apidoc/Titanium/Network/Network.yml), [UserNotificationCenter](https://github.com/tidev/titanium-sdk/blob/13_4_1_GA/apidoc/Titanium/App/iOS/UserNotificationCenter.yml), [NotificationManager](https://github.com/tidev/titanium-sdk/blob/13_4_1_GA/apidoc/Titanium/Android/NotificationManager/NotificationManager.yml).