Using Titanium SDK ti.push for cross-platform push notifications

Push notifications split across two platforms

Your app needs to notify users on both iOS and Android, but Apple Push Notification service (APNs) and Firebase Cloud Messaging (FCM) require separate certificates, permissions, and registration code. Writing two native flows duplicates effort and increases the chance that a missing entitlement silently breaks delivery. Titanium SDK 10+ includes the ti.push module to abstract those differences behind one JavaScript interface.

What ti.push handles and what it does not

The module exposes a single registration path and a single push event for incoming notifications. It returns a device token you can send to your backend. It does not provision APNs certificates, create Firebase projects, or override platform payload limits. You still configure those native pieces yourself.

Registering for a device token

Call the registration method after the app starts. On iOS, use Ti.App.iOS.registerForPushNotifications(); on Android, use Ti.App.registerForPushNotifications(). Both are asynchronous and report the token through the module's registration event.

1. Confirm ti.project.properties sets ti.version to 10.x or higher.
2. Confirm the ti/push folder exists under ti/modules in your SDK installation.
3. Call registration once the UI is ready, typically on the first window open.
4. Listen for the registration event and capture the device token before sending it to your backend.

Native configuration to verify before building

Platform	Required setting	Where to check
iOS	UIBackgroundModes = remote-notification and a valid APNs push certificate	Info.plist and Xcode project settings
Android	com.google.android.c2dm.permission.C2D_MESSAGE permission and a Firebase project with an API key	AndroidManifest.xml and tiapp.xml

Missing these settings usually produces a registration error at runtime, not a build failure, so the app may appear to work until the first push attempt.

Payload size and background delivery

Keep notification payloads under 4 KB. iOS truncates larger payloads, and Android may drop them entirely. Background behavior also depends on platform configuration:

• iOS: add UIBackgroundModes = remote-notification to Info.plist; otherwise the system may deliver notifications silently or not at all when the app is backgrounded.
• Android: declare the C2DM permission and a background service in the manifest; data-only pushes otherwise may not wake the app.

Worked example: register and listen

// app.js
function registerForPush() {
    if (Ti.Platform.osname === 'android') {
        Ti.App.registerForPushNotifications();
    } else {
        Ti.App.iOS.registerForPushNotifications();
    }
}

// Handle incoming notification payloads
Ti.App.addEventListener('push', function (e) {
    Ti.API.info('Push payload received: ' + JSON.stringify(e));
    // Handle foreground and background notification data here
});

// Verify token event shape for your installed SDK 10.x release
Ti.App.addEventListener('change', function (e) {
    if (e.source && e.source.name === 'ti.push' && e.source.token) {
        Ti.API.info('Push device token: ' + e.source.token);
        // Send e.source.token to your backend here
    }
});

registerForPush();

This example checks the platform before calling the platform-specific registration method. Incoming notification payloads arrive through push, while the device token is delivered through the module's registration event. Do not assume the token is available immediately after calling registration; wait for the event.

Diagnostic checks

1. Run ti build -log --platform ios or ti build -log --platform android from the project root.
2. Look for log output indicating that ti.push is being packaged into the native project.
3. Install on a physical device, not a simulator, because push registration often fails or returns no token on simulators.
4. Open the device or console log and confirm the token appears after registration.

Required permissions: none beyond standard Titanium CLI access. Risks: an expired APNs certificate or incorrect Firebase API key causes registration to fail or return an error event, so verify credentials before testing on production builds.

Limitation: silent truncation and certificate dependencies

ti.push cannot compensate for a missing push certificate or a payload over the platform limit. If the token registers but notifications never arrive, check the payload size first, then confirm the APNs certificate matches the app bundle identifier and provisioning profile. On Android, confirm the Firebase project is linked and the manifest declares the required service.

Actionable closing

1. Update ti.project.properties to a supported 10.x SDK version.
2. Add the iOS background mode and Android manifest entries shown above.
3. Implement the registration and listener pattern from the worked example.
4. Build with ti build -log and confirm ti.push appears in the packaging output.
5. Test on a physical device with a real push certificate and Firebase configuration.

When the native prerequisites are in place, ti.push gives you one registration flow and one event listener for both platforms. Stay under 4 KB, verify background modes, and test on real devices before relying on push in production.