iOS setup · Payghaam Docs

The Flutter plugin registers for APNs, forwards the device token to Payghaam, and handles notification taps. iOS does not use Firebase for push in this SDK.

App capabilities (Runner target)

In Xcode → Runner → Signing & Capabilities, add:

Push Notifications
Background Modes → Remote notifications
App Groups → e.g. group.com.yourcompany.app.payghaam

warning

Warning

Don't reuse the same App Group id across multiple apps you own — the NSE and Runner target write to shared storage under that id, and two unrelated apps sharing it can clobber each other's config or receipts.

Info.plist

xml

<key>PayghaamAppGroup</key>
<string>group.com.yourcompany.app.payghaam</string>

Dart configuration

dart

await push.shareConfig(
  appGroup: 'group.com.yourcompany.app.payghaam',
  apiBase: config.baseUrl,
  apiKey: config.apiKey,
  externalId: 'your-user-id',
);

Notification Service Extension (recommended)

Adds terminated-state delivered receipts and rich images.

Xcode → File → New → Target → Notification Service Extension (e.g. PayghaamNSE).
Replace NotificationService.swift with the template from ios_extension/NotificationService.swift in the SDK repo.
The template imports the native SDK (import Payghaam), so add it as a dependency of the new NSE target — Xcode → NSE target → General → Frameworks and Libraries → + (or a target 'PayghaamNSE' do pod 'Payghaam', :path => '...' end block in your Podfile, then pod install, if using CocoaPods).
Add the same App Group to the NSE target.
Add PayghaamAppGroup to the NSE Info.plist.
Match minimum deployment target to your app (iOS 15+ recommended).

Delivery by app state

State	Mechanism	Receipt
Foreground	Plugin `willPresent`	`delivered`
Background / cold-start tap	Plugin `didReceive`	`opened`
Terminated (no tap)	NSE → `/api/sdk/receipts`	`delivered`

Custom notification sound

To play a custom sound, add a short audio file (.caf, .aiff, .wav, or .mp3; 30 seconds or shorter) to the Runner target's Build Phases → Copy Bundle Resources.

Drag the file into the Xcode project and confirm it's in Copy Bundle Resources.
In the dashboard composer or a journey push node, enter the filename with extension (e.g. chime.caf) in the iOS sound field.

Payghaam sends that value as aps.sound and iOS plays it automatically from the bundle — no extension code required. Leave the field blank for the default sound. See Rich notifications for the cross-platform overview.

warning

Warning

Custom sounds are not supported inside the Notification Service Extension — the file must live in the main app bundle, not the NSE.

info

Note

APNs credentials (.p8, Key ID, Team ID, Bundle ID) are configured in the dashboard under Project settings → Channels → iOS · APNs. The device never sees them.

warning

Warning

The App Bundle ID in the dashboard must match Xcode exactly. A mismatch causes APNs topic errors; invalid Key ID / Team ID / .p8 causes InvalidProviderToken.

Troubleshooting

No terminated-state receipts. The NSE and Runner target must use the same App Group id — check both under Signing & Capabilities and in each target's Info.plist. A mismatch silently drops delivered receipts for pushes received while the app is terminated.
NSE build fails with "no such module 'Payghaam'". The Notification Service Extension is a separate build target and doesn't inherit the Runner's dependencies — add the native SDK to the NSE target explicitly (step 3 above).