Migration Guide: Adding Extension

Migrate your existing ContextPush integration to use the required Notification Service Extension for reporting.

This guide walks you through adding the required Notification Service Extension to an existing ContextPush integration.

Who should follow this guide? Developers who have already integrated ContextPush and need to add the required Notification Service Extension for reporting.

Overview

Adding required extension support involves three changes:

1. Creating an App Group for data sharing

2. Updating your main app initialization

3. Adding the Notification Service Extension

Estimated time: 15-30 minutes

Important: You must complete all three steps. When you add the appGroupIdentifier to your Configuration (Step 2), you are enabling delivery tracking. If you don't complete Step 3 (the extension), your delivery metrics will be inaccurate because ContextSDK expects the extension to report deliveries.

---

Before You Begin

Ensure you have:

• ContextSDK version 5.13.0 or later

• Working ContextPush integration in your main app

• Access to Apple Developer Portal for App Group creation

Check Your SDK Version

CocoaPods

Check your Podfile.lock for the ContextSDK version:

grep ContextSDK Podfile.lock

Update if needed:

pod update ContextSDK

SPM

---

Step 1: Create App Group

1

Register App Group

1. Go to Apple Developer Portal

2. Create a new App Group identifier (e.g., group.com.yourcompany.yourapp)

2

Add to Main App

1. Open Xcode project settings for your main app target

2. Go to Signing & Capabilities

3. Add App Groups capability

4. Select your app group

---

Step 2: Update Main App Initialization

Before (Current Code)

AppDelegate.swift

import ContextSDK

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {

    ContextManager.applicationDidFinishLaunchingWithOptions(
        launchOptions,
        licenseKey: "YOUR_LICENSE_KEY"
    )

    ContextPush.applicationDidFinishLaunchingWithOptions()

    return true
}

After (With App Group)

AppDelegate.swift

import ContextSDK

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {

    // Add Configuration with App Group
    let config = Configuration(appGroupIdentifier: "group.com.yourcompany.yourapp")

    ContextManager.applicationDidFinishLaunchingWithOptions(
        launchOptions,
        licenseKey: "YOUR_LICENSE_KEY",
        configuration: config  // Pass configuration
    )

    ContextPush.applicationDidFinishLaunchingWithOptions()

    return true
}

What Changed

Before	After
No configuration parameter	Configuration object with appGroupIdentifier
Data stored in app sandbox	Data shared via App Group

Important: After this change, launch your main app at least once before testing the extension. This creates the shared license token.

---

Step 3: Add Notification Service Extension

1

Create Extension Target

1. File → New → Target

2. Select Notification Service Extension

3. Name it (e.g., NotificationServiceExtension)

4. Click Finish

2

Configure Extension

1. Select extension target → Signing & Capabilities

2. Add App Groups capability

3. Select the same App Group as main app

3

Add Dependency

CocoaPods

Update your Podfile:

Podfile

target 'YourApp' do
  pod 'ContextSDK'
end

# Add this new target block
target 'NotificationServiceExtension' do
  pod 'ContextSDKExtension'
end

Run:

pod install

SPM

4

Implement Extension

Replace NotificationService.swift:

NotificationService.swift

import UserNotifications
import ContextSDKExtension

class NotificationService: UNNotificationServiceExtension {

    var contentHandler: ((UNNotificationContent) -> Void)?
    var bestAttemptContent: UNMutableNotificationContent?

    override func didReceive(
        _ request: UNNotificationRequest,
        withContentHandler contentHandler: @escaping (UNNotificationContent) -> Void
    ) {
        self.contentHandler = contentHandler
        bestAttemptContent = (request.content.mutableCopy() as? UNMutableNotificationContent)

        guard let bestAttemptContent = bestAttemptContent else {
            contentHandler(request.content)
            return
        }

        // Use same App Group and license key as main app
        let success = ContextManager.setupForExtension(
            appGroupIdentifier: "group.com.yourcompany.yourapp",
            licenseKey: "YOUR_LICENSE_KEY"
        )

        guard success else {
            contentHandler(bestAttemptContent)
            return
        }

        ContextPush.handleNotification(request.content.userInfo) {
            contentHandler(bestAttemptContent)
        }
    }

    override func serviceExtensionTimeWillExpire() {
        if let contentHandler = contentHandler, let bestAttemptContent = bestAttemptContent {
            contentHandler(bestAttemptContent)
        }
    }
}

---

Step 4: Verify Migration

Checklist

• Main app has App Groups capability with correct identifier

• Extension has App Groups capability with same identifier

• Main app uses Configuration(appGroupIdentifier:) in initialization

• Extension uses setupForExtension with same App Group and license key

• ContextSDKExtension pod/package added to extension target

• Main app launched at least once after changes

Test Delivery Tracking

1. Force-quit your app completely

2. Send a test notification from the dashboard

3. Verify reporting events appear in analytics

---

FAQ

Will this affect existing users?

No. The migration is transparent to users. Existing notification behavior is unchanged - you're adding additional tracking capabilities.

What if the main app was never launched?

setupForExtension returns false if the main app hasn't stored the license token yet. The extension gracefully handles this by delivering the notification without tracking.

Do I need to update my push notification payloads?

No changes to your server-side push configuration are required.

What data is shared via the App Group?

• License verification token (hash of license key)

• Device token

• User ID

• APS environment (sandbox/production)

No sensitive user data or context is stored in the App Group.