App Groups for push tracking

Updated

Configure App Groups for reliable push delivery tracking. App Groups let the SDK recover delivery metrics that iOS might otherwise discard when it terminates the Notification Service Extension.

App Groups are required for reliable push delivery tracking. Without this setup, delivery metrics may be lost if iOS terminates the Notification Service Extension before the tracking request completes. With App Groups configured, the SDK automatically recovers any lost metrics on the next app launch.

Before you begin

Before you configure App Groups, make sure you’ve completed the following:

1. Add the App Group capability in Xcode

You need to add the App Groups capability to both your main app target and your Notification Service Extension target in Xcode.

If you use automatic signing (the most common setup), this is the only step outside of code. Xcode registers the group and updates provisioning profiles automatically.

  1. In Xcode, select your main app target > Signing & Capabilities > + Capability > App Groups.
  2. Click + and enter your group identifier—for example, group.com.example.myapp.cio.
  3. Select your Notification Service Extension target > Signing & Capabilities > + Capability > App Groups.
  4. Select the same App Group you created in step 2.

Both targets must reference the exact same App Group string.

If you use manual signing, you need to register the group in the Apple Developer Portal and regenerate your provisioning profiles.

  1. Sign in to the Apple Developer Portal and go to Certificates, Identifiers & Profiles.
  2. Click Identifiers > + > App Groups.
  3. Enter your identifier. It must start with group.—for example, group.com.example.myapp.cio.
  4. Under Identifiers, select your main app’s App ID, enable App Groups, click Configure, and select your group.
  5. Repeat step 4 for your Notification Service Extension’s App ID.
  6. Regenerate provisioning profiles for both your main app and Notification Service Extension. Enabling App Groups invalidates your existing provisioning profiles.

 You must regenerate your provisioning profiles in the Apple Developer Portal after enabling App Groups. You don’t need to regenerate certificates.

 Already have an App Group?

You can reuse an existing App Group by passing its identifier to .appGroupId(). There’s no conflict in having multiple App Groups on a target.

2. Pass the App Group ID in your SDK configuration

After you add the App Group capability, pass the App Group ID to the SDK in both your host app and your Notification Service Extension. Both are required—App Groups work by sharing storage between the two targets, so the SDK needs the identifier in each place to read and write delivery metrics. The App Group ID must be identical in both places and must match the entitlements you set up in Xcode.

Host app initialization

MessagingPushAPN.initialize(
    withConfig: MessagingPushConfigBuilder()
        .appGroupId("group.com.example.myapp.cio")
        .build()
)

MessagingPushFCM.initialize(
    withConfig: MessagingPushConfigBuilder()
        .appGroupId("group.com.example.myapp.cio")
        .build()
)

Notification Service Extension initialization

MessagingPushAPN.initializeForExtension(
    withConfig: MessagingPushConfigBuilder(cdpApiKey: "YOUR_CDP_API_KEY")
        .appGroupId("group.com.example.myapp.cio")
        .build()
)

MessagingPushFCM.initializeForExtension(
    withConfig: MessagingPushConfigBuilder(cdpApiKey: "YOUR_CDP_API_KEY")
        .appGroupId("group.com.example.myapp.cio")
        .build()
)

 App Group ID must match everywhere

The .appGroupId() value must be identical in your host app initialization, your NSE initialization, and the App Group entitlements on both targets. A mismatch prevents the SDK from accessing shared storage.

Fallback behavior

If you omit .appGroupId(...), the SDK attempts to infer the identifier using the convention group.{bundleId}.cio. This can work as a fallback, but we recommend explicitly passing the value to avoid configuration issues.

Copied to clipboard!
  Contents
Version