iOS Push Notifications

​

APNs Setup

1. In Xcode, enable the Push Notifications capability under your target’s Signing & Capabilities tab.
2. Generate an APNs authentication key (.p8 file) in the Apple Developer Portal.
3. In the AppDNA Console under Settings > Push, in the APNs (iOS) card, paste the contents of the .p8 file into P8 Auth Key, fill in Key ID, Team ID and Bundle ID, pick the Environment, and click Save.

​

Request Permission

let granted = await AppDNA.registerForPush()

if granted {
    print("Push permission granted")
} else {
    print("Push permission denied")
}

​

Set Token Manually

func application(
    _ application: UIApplication,
    didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data
) {
    AppDNA.setPushToken(deviceToken)
}

​

Set Permission Status

AppDNA.setPushPermission(granted: true)

​

How push works on iOS

• Tap (warm or cold start) — tracked once as push_tapped, onPushTapped fires, and the AppDNA action is routed (show_screen, deep link / URL). A push delivered or tapped before configure (for example a cold-start tap) is buffered — up to 8 — and handled once configure has set up push; beyond 8, further ones are dropped. No forwarding code is needed.
• Foreground delivery — tracked as push_delivered and onPushReceived(…, inForeground: true) fires when AppDNA handles foreground presentation (below). Through the proxy, delivered tracking covers foreground delivery only: AppDNA pushes do not wake the app in the background, so background delivery is not tracked. A delivery you forward with handleMessageData is tracked too.

​

Info.plist keys

​

Forwarding yourself (proxy disabled)

func userNotificationCenter(_ center: UNUserNotificationCenter,
                            willPresent notification: UNNotification,
                            withCompletionHandler completionHandler: @escaping (UNNotificationPresentationOptions) -> Void) {
    let userInfo = notification.request.content.userInfo
    if AppDNA.pushModule.isAppDNAMessage(userInfo) {
        AppDNA.pushModule.handleMessageData(userInfo)          // tracks delivered, fires onPushReceived
        completionHandler([.banner, .list, .sound, .badge])
        return
    }
    completionHandler([]) // your own notifications
}

func userNotificationCenter(_ center: UNUserNotificationCenter,
                            didReceive response: UNNotificationResponse,
                            withCompletionHandler completionHandler: @escaping () -> Void) {
    let userInfo = response.notification.request.content.userInfo
    AppDNA.pushModule.handleNotificationTap(userInfo, actionIdentifier: response.actionIdentifier)
    completionHandler()
}

func scene(_ scene: UIScene, willConnectTo session: UISceneSession,
           options connectionOptions: UIScene.ConnectionOptions) {
    if let response = connectionOptions.notificationResponse {
        AppDNA.pushModule.handleNotificationTap(response.notification.request.content.userInfo,
                                                actionIdentifier: response.actionIdentifier)
    }
}

​

installNotificationProxy()

​

Track Delivery and Taps (manual)

AppDNA.trackPushDelivered(pushId: "push-123")
AppDNA.trackPushTapped(pushId: "push-123", action: "open_workout")

​

Push Module

let pushModule = AppDNA.pushModule

​

PushModule Methods

​

AppDNAPushDelegate Protocol

• onPushTokenRegistered(token:) — fires whenever the SDK registers a new APNs token (or detects a change). Token registration with the AppDNA backend continues regardless of whether you implement this method.
• onPushReceived(notification:, inForeground:) — fires when an AppDNA push is delivered: in the foreground through the proxy, or whenever you forward it with handleMessageData (then inForeground reports the app state). It does not fire for your own notifications.
• onPushTapped(notification:, actionId:) — fires when the user taps an AppDNA push or one of its action buttons (through the proxy or handleNotificationTap).

protocol AppDNAPushDelegate: AnyObject {
    func onPushTokenRegistered(token: String)
    func onPushReceived(notification: PushPayload, inForeground: Bool)
    func onPushTapped(notification: PushPayload, actionId: String?)
}

​

Example Implementation

class MyPushHandler: AppDNAPushDelegate {
    func onPushTokenRegistered(token: String) {
        print("Token registered: \(token)")
    }

    func onPushReceived(notification: PushPayload, inForeground: Bool) {
        if inForeground {
            // Show in-app notification banner
            showBanner(title: notification.title, body: notification.body)
        }
    }

    func onPushTapped(notification: PushPayload, actionId: String?) {
        if let action = notification.action {
            // Handle deep link or custom action
            handleAction(action)
        }
    }
}

// AppDNA holds the push delegate weakly — keep a strong reference yourself,
// for example in a property of your AppDelegate.
let pushHandler = MyPushHandler()
AppDNA.pushModule.setDelegate(pushHandler)

​

Action buttons and custom sound

• Buttons. The push carries its buttons as an actions array and aps.category. Each distinct button set gets its own category id, appdna_ plus a hash of the set. A category set in the campaign (ios.category) is sent only when the push has no buttons; with buttons the generated category is always sent, so the SDK never registers AppDNA buttons over a category your app owns. iOS shows buttons only for a category that is registered before the notification is displayed. The SDK registers it in three places:
  1. In a Notification Service Extension (recommended). Add a Notification Service Extension target whose principal class subclasses NotificationService from the AppDNANotificationExtension library. Link that library to the extension, not AppDNASDK: AppDNASDK uses API that is unavailable in an app extension (UIApplication.shared) and installs its notification handler at launch, so it must not run inside the extension. AppDNANotificationExtension has no dependencies and builds with application-extension-only API. It registers the category on receipt, before display, and downloads the image. Every push with buttons is sent with mutable-content: 1, so the extension runs for it. This is the only way the first push with a new button set shows its buttons while the app is not running.
  2. When the app sees the push: foreground delivery, or a tap.
  3. At configure, from the AppDNA notifications still in Notification Centre.
  Without the extension, a new button set shows its buttons only after the app has registered it (points 2 and 3). That usually means from the second push with the same buttons.
  // NotificationService.swift in your Notification Service Extension target
  import AppDNANotificationExtension
  
  class NotificationService: AppDNANotificationExtension.NotificationService {}
  
  Add the library to the extension target only:
  • Swift Package Manager: the AppDNANotificationExtension product of the AppDNA iOS package.
  • CocoaPods: pod 'AppDNANotificationExtension' in the extension’s own target block (the app keeps pod 'AppDNASDK'). Make that block a top-level target, not one nested inside the app’s target block: a nested target inherits the app’s pods, so AppDNASDK and Firebase would be linked into the extension. If you keep it nested, add inherit! :none to it:
    target 'YourApp' do
      pod 'AppDNASDK'
    end
    
    target 'NotificationService' do
      pod 'AppDNANotificationExtension'
    end
    
    The Podfile needs use_frameworks!, dynamic or :linkage => :static, as for any app that uses AppDNASDK through CocoaPods (Installation). With pods built as static libraries (no use_frameworks!), pod install stops: “The Swift pod FirebaseCoreInternal depends upon GoogleUtilities, which does not define modules”. Adding modular headers does not fix it: use_modular_headers! gets past pod install, but then gRPC-C++ does not compile (“module map file ’…/gRPC-Core.modulemap’ not found”); :modular_headers => true on GoogleUtilities and FirebaseFirestoreInternal only gets through the compile, but the app does not link (“ld: framework ‘FirebaseFirestoreInternal’ not found”), because FirebaseFirestore links FirebaseFirestoreInternal as a framework, which a static-library build does not produce.
  The app and the extension register categories through the same code, so a button’s title is the same whichever registered it. A button label’s {{…}} variables resolve to their fallback ({{user.name | there}} → there), or to nothing without one, in the registered button, because a category is shared by every push with the same buttons and the extension has no user data; the actions in PushPayload keep the app’s values. The SDK caps the AppDNA button categories it keeps registered at 16: when a new one would pass that, it keeps the new one, the categories of notifications still in Notification Centre (all of them, even past 16) and then the most recently registered ones up to 16. “Most recently registered” is per process: the extension and the app each keep their own list. Your own categories are never touched. The extension and the app register in separate processes, and each registration rewrites the whole category set, so one can overwrite a category the other has just registered. After writing, a registration reads the set back and, if its category is gone, adds it again (up to three times). A category that is still lost is registered again the next time the app sees a push with those buttons, or at configure while one of its notifications is in Notification Centre.
• Button taps go through the same path as a body tap. The tap is tracked as push_tapped with the button’s id as action, and onPushTapped(notification:, actionId:) fires with the button’s id. The SDK then routes the button’s own action: deep_link and open_url (the Console’s URL type) go to your deep-link handler, and show_screen opens that screen. dismiss routes nowhere and is shown as a destructive button; it never opens the app, even if a payload marks it foreground. A button with Open app in foreground switched off is handled without bringing the app to the foreground.
• Text reply. A text_reply button is a text-input action whose placeholder is the button’s value. The typed text reaches onPushTapped as notification.data["reply_text"]. If you forward taps yourself with handleNotificationTap, copy (response as? UNTextInputNotificationResponse)?.userText into the userInfo under appdna_reply_text first.
• Custom sound is aps.sound: the file name exactly as authored (for example chime.wav). Bundle the file in the app’s main bundle or Library/Sounds. default plays the system sound.

​

PushPayload

​

PushAction

​

Auto-Tracked Events

​

Full Example

import AppDNASDK

class AppDelegate: UIResponder, UIApplicationDelegate {
    let pushHandler = MyPushHandler()

    func application(
        _ application: UIApplication,
        didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
    ) -> Bool {
        AppDNA.configure(
            apiKey: "adn_live_xxx",
            environment: .production
        )

        AppDNA.pushModule.setDelegate(pushHandler)

        Task {
            let granted = await AppDNA.registerForPush()
            print("Push permission: \(granted)")
        }

        return true
    }

    func application(
        _ application: UIApplication,
        didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data
    ) {
        AppDNA.setPushToken(deviceToken)
    }
}

​

Scheduled pushes in the user’s time zone

1. the timezone trait your app passes to identify (an IANA name such as Europe/Berlin), if you set one — it always takes precedence, and the device’s zone never overwrites it;
2. the zone the user’s device last reported;
3. the app’s time zone;
4. UTC.

AppDNA.identify(userId: "user-123", traits: ["timezone": "Europe/Berlin"]) // the zone the user chose in your app