ComRaidComRaid Docs

Images and action buttons (iOS)

Add a Notification Service Extension so iOS shows push images and cold-device action buttons — Expo, bare React Native, and native iOS.

ComRaid always sets mutable-content on alert Notifications so a Notification Service Extension can run. iOS only shows the image — and, on a device that has not seen the buttons yet, the action buttons — when the extension enriches the notification before the system displays it.

Without the extension, OS-drawn alerts still show title, body, sound, badge, subtitle and thread. Images are missing, action buttons may be missing the first time that category appears on the device, and delivered is not acknowledged from the background or a killed app. The extension sends the delivered ACK (queued on failure) so delivery tracking does not depend on the host's didReceiveRemoteNotification.

Use RemoteNotificationDisplay.enrich (or the ObjC bridge) inside the extension. Pass the same App Group id you use as storageSuiteName in configure / ComRaid.initialize so the extension can read SDK config and the durable ACK queue. Images download over HTTP(S) with a 10 s timeout and a 5 MB cap (JPEG, PNG, GIF, or HEIC); on failure the notification shows without the attachment. Sister pages: iOS SDK, React Native SDK, Notifications.

App Group (storageSuiteName)

Create an App Group in the Apple Developer portal (id typically group.com.example.app.comraid) and enable it on both the main app and the Notification Service Extension. Pass that id as storageSuiteName when you configure the SDK. The main app writes config and ACK state into the shared suite; the extension reads the same suite when it enriches a push.

Without the shared App Group, image/button enrichment still works, but the delivered ACK from the NSE cannot find the persisted SDK config and is skipped.

Expo

The Expo config plugin can add the extension. It is opt-in because the extension needs its own App ID and provisioning profile.

Set ios.notificationServiceExtension: true and ios.storageSuiteName (your App Group id) on @comraid/react-native:

{
  "expo": {
    "ios": {
      "bundleIdentifier": "com.example.app",
      "appleTeamId": "ABCD123456"
    },
    "plugins": [
      [
        "@comraid/react-native",
        {
          "ios": {
            "apnsEnvironment": "sandbox",
            "storageSuiteName": "group.com.example.app.comraid",
            "notificationServiceExtension": true
          }
        }
      ]
    ]
  }
}

Then run npx expo prebuild (or your usual EAS Build prebuild). The plugin:

  • Adds a ComRaidNotificationService Notification Service Extension target (bundle id <app bundle id>.ComRaidNotificationService) that calls RemoteNotificationDisplay.enrich with your storageSuiteName
  • Adds the App Group entitlement on the main app and the extension (and registers it with EAS Build)
  • Links that target to the ComRaid CocoaPod
  • Registers the extension with EAS Build under extra.eas.build.experimental.ios.appExtensions so signing can provision it
  • Signs with ios.appleTeamId from the plugin option or Expo ios.appleTeamId, otherwise the app target's team

Pass the same storageSuiteName to ComRaid.initialize at runtime.

EAS Build provisioning

The extension is a separate App ID. On the first EAS Build after enabling the option, confirm Apple Developer / EAS has a provisioning profile for <app bundle id>.ComRaidNotificationService with the App Group capability. The plugin registers the extension with EAS; if signing fails, create or refresh that profile (or let EAS credentials sync) and rebuild. Do not expect the main app profile alone to cover the extension.

Podfile :path / :git for ComRaid

If your Podfile pins ComRaid to a local :path or remote :git source (instead of the default CocoaPods trunk / SPM path the plugin expects), give the ComRaidNotificationService target the same source:

target 'ComRaidNotificationService' do
  pod 'ComRaid', :path => '../comraid-ios' # or :git => '…', :tag => '…'
end

Mismatched sources leave the extension on a different ComRaid revision than the app.

App ID is still passed at runtime via ComRaid.initialize — the plugin only wires native targets. Full plugin options: React Native SDK.

Bare React Native

  1. In Xcode, File → New → Target → Notification Service Extension. Use a product name such as NotificationService (bundle id typically <app bundle id>.NotificationService).
  2. Enable the same App Group on the main app and the extension (see App Group above). Pass that id as ios.storageSuiteName / storageSuiteName when initializing ComRaid.
  3. Replace the generated Swift file with (use your App Group id):
import ComRaid
import UserNotifications

final class NotificationService: UNNotificationServiceExtension {
  override func didReceive(
    _ request: UNNotificationRequest,
    withContentHandler contentHandler: @escaping (UNNotificationContent) -> Void
  ) {
    Task {
      contentHandler(
        await RemoteNotificationDisplay.enrich(
          request,
          storageSuiteName: "group.com.example.app.comraid"
        )
      )
    }
  }
}
  1. Link ComRaid to the extension in your Podfile, outside the main app target (same source as the app if you pin :path / :git):
target 'NotificationService' do
  pod 'ComRaid'
end
  1. Run pod install, then build. Provision the extension App ID the same way you provision the main app (separate profile / capability set for the extension bundle id, including the App Group).

Native iOS

Add a Notification Service Extension target that links the ComRaid package product (Swift Package Manager) or pod 'ComRaid' (CocoaPods). Enable a shared App Group on the app and the extension, configure ComRaid with that id as storageSuiteName, then call enrich from didReceive:

import ComRaid
import UserNotifications

final class NotificationService: UNNotificationServiceExtension {
  override func didReceive(
    _ request: UNNotificationRequest,
    withContentHandler contentHandler: @escaping (UNNotificationContent) -> Void
  ) {
    Task {
      contentHandler(
        await RemoteNotificationDisplay.enrich(
          request,
          storageSuiteName: "group.com.example.app.comraid"
        )
      )
    }
  }
}

Objective-C hosts can call ComraidBridge.shared.enrichNotificationRequest(_:storageSuiteName:completion:) instead.

ComRaid is extension-safe: requestPermission / requestAuthorization (and the bridge's requestNotificationPermission) are unavailable in app extensions; nothing else in the module requires UIApplication. Method details: iOS SDK — Display helpers.

Verify

Send a Notification with content.push.image_url (Dashboard Test send or POST /messages). On a physical device or simulator with the extension installed, the tray item should show the image. Action buttons on a fresh install should appear after the extension runs once for that category.

On this page