Skip to content

Messaging

Apple Push Notification service_

Send push notifications to apps on Apple devices through Apple Push Notification service (APNs) using Appwrite Messaging.

8 min read

Raw

Apple Push Notification service (APNs) lets you send push notifications to Apple devices like macOS, iOS, tvOS, iPadOS, and watchOS devices. APNs is a best-effort service, and will attempt to deliver you messages to your device when it's online and available again. APNs will save the last message for 30 days or less and attempt delivery as soon as it's online.

One-click setup with the CLI

The Appwrite CLI sets up APNs for an iOS app in one command. Run it from your app's project folder:

Bash
appwrite init apns

The command reads the bundle ID and team ID from your Xcode project (or app.json for Expo), and the key ID from the AuthKey_<KEYID>.p8 file name. It then:

  • Creates or updates two APNs providers, production and sandbox, and enables them.
  • Adds the aps-environment entitlement and the remote-notification background mode to your Xcode target. If the target has no entitlements file or Info.plist, the CLI tells you which capability to add in Xcode instead.
  • Adds an Apple platform for the bundle ID to your project if it has none. Without one, Appwrite rejects your app's requests, device registration included.
  • Checks with Apple that the bundle ID is registered as an App ID with Push Notifications turned on. APNs rejects pushes for any other bundle ID with TopicDisallowed. The CLI asks before it signs in to Apple or changes anything.

In an Expo project, also set the entitlement and background mode in app.json, because expo prebuild regenerates the ios folder. The CLI prints the exact keys to add.

Provide a key

The CLI needs an APNs auth key (.p8). Use one you already have, or let the CLI create one:

  • A .p8 in your project folder. Run appwrite init apns. The CLI uses the key without asking, or lets you pick one if there are several.
  • A .p8 stored somewhere else. Pass --key-path with the file's path. Add --team-id if your project doesn't set a team.
  • A new key from your Apple ID. Pass --create-key. The CLI signs in with your Apple ID, password, and two-factor code, then creates the key. This option is experimental.
  • A new key from the Apple Developer portal. Run appwrite init apns and pick the portal. The CLI opens it and waits up to 15 minutes for the downloaded .p8 to appear in your project folder or ~/Downloads.

When the CLI finds no key and you don't pass --create-key or --key-path, it asks which way you want.

When the CLI creates a key:

  • It saves the key as AuthKey_<KEYID>.p8 in your project folder. Apple lets you download a key only once, so keep the file somewhere safe and out of version control. The CLI warns you when git would commit it.
  • Apple allows two APNs keys per team, and one key works for every app on the team. When both are taken, the CLI lists them and stops. Pass --key-path with a key you saved earlier, or revoke one you no longer use in the Apple Developer portal.
  • It saves your Apple sign-in, so later runs skip the password and two-factor code until Apple expires the session. The appwrite and expo setups keep it in ~/.appwrite/apns/<setup>/, readable only by you. The fastlane setup uses fastlane's own saved session. --reset signs in again and creates a new key.

The CLI can sign in to Apple in three ways. Pick one with --provider or the APPWRITE_APNS_SETUP environment variable. If one stops working, switch to another.

SetupBuilt on
appwrite (default)The CLI's own Apple client
expo@expo/apple-utils
fastlanefastlane's spaceship

--provider only picks how the CLI signs in to Apple. It doesn't change the APNs providers in your Appwrite project.

Run it again

You can run appwrite init apns as often as you like. It never creates duplicate providers. What it does with the key depends on the providers you already have:

  • Both providers are set up and enabled. The CLI keeps both providers and their key. It still updates Xcode, adds the Apple platform if it's missing, and checks the App ID. --create-key alone changes nothing here.
  • You pass --force, --key-path, or --reset. The CLI puts the new key on both providers.
  • One or both providers are missing or disabled. The CLI gets a key as on a first run, then creates or updates both providers with it, including one that was already working.

To create a new key for providers that already work, pass --create-key --force.

Options

FlagDescriptionWhen omitted
--bundle-id <id>iOS bundle ID.PRODUCT_BUNDLE_IDENTIFIER of the app target, or ios.bundleIdentifier in Expo's app.json or app.config.json. If there are several apps, the CLI lets you pick one. If there are none, it asks.
--team-id <id>10-character Apple Developer team ID.The target's DEVELOPMENT_TEAM, Expo ios.appleTeamId, or the team on an existing provider. With --create-key, picked during the Apple sign-in.
--key-path <file>An existing APNs auth key (.p8). Replaces the key on providers that are already set up.A valid .p8 in the project folder. If there is none, the CLI asks.
--key-id <id>10-character key ID.Read from the AuthKey_<KEYID>.p8 file name. If the name has no key ID, the CLI asks. A created key uses the ID Apple gives it.
--create-keyCreate the key by signing in with your Apple ID. When both providers are already set up and enabled, also pass --force.Offered when no key is found.
--provider <setup>How the CLI signs in to Apple: appwrite, expo or fastlane. Not an Appwrite messaging provider.APPWRITE_APNS_SETUP if set, otherwise appwrite.
--environment <env>production, sandbox or all.all
--resetSign in to Apple again instead of reusing the saved sign-in. Implies --create-key, so it creates a new key.The saved sign-in is reused.
--register-app-idRegister the App ID and turn on Push Notifications without asking. Fails if that can't be done. Experimental.The CLI still checks the App ID on every run, and asks before it changes anything.
--forceReplace the key on providers that are already set up.When both providers are set up and enabled, they keep their key. Otherwise, both get the key you provide.

--create-key and --reset can't be combined with --key-path or --key-id.

Run in CI

Without a terminal, the CLI can't ask for a two-factor code or show a picker. In CI:

  • Pass an existing key with --key-path. Creating a key always needs a two-factor code.
  • Pass --bundle-id when your project has more than one app, and --team-id when it doesn't set a team.
  • Set APPWRITE_APPLE_ID and APPWRITE_APPLE_PASSWORD to answer the Apple ID and password prompts. The CLI never prints their values.
  • The App ID check uses a saved Apple sign-in if there is one, and otherwise reports that it skipped the check. It only fails the command when you pass --register-app-id.
Bash
appwrite init apns --key-path ./AuthKey_Q4GAU66T2N.p8 --bundle-id com.example.app --team-id ABCDE12345

What the CLI leaves to you

The CLI sets up the providers and your project, not your app's code. To receive pushes, request notification permission in the app, register the device token as a push target, and send a test message, as described in Send push notifications.

To set up APNs from the Console instead, follow the steps below.

1. Add provider

To add APNs as a provider, navigate to Messaging > Providers > Create provider > Push notification.

Add a FCM provider
Add a FCM provider

Give your provider a name > choose APNS > click Save and continue. The provider will be saved to your project, but not enabled until you complete its configuration.

2. Configure provider

In the Configure step, you will need to provide details from your Apple developer account to connect your Appwrite project with your Apple developer account.

You will need to provide the following information from the Apple Developer Member Center.

After adding the following details, click Save and continue to enable the provider.

3. Configure app

Some additional configuration is required to enable push notifications in your iOS app. Add push notification capability to your app by clicking your root-level app in XCode > Signing & Capabilities > Capabilities > Search for Push Notifications.

Enable PN on Xcode
Enable PN on Xcode

4. Test provider

Push notification requires special handling on the client side. Follow the Send push notification flow to test your provider.

5. Manage provider

You can update or delete a provider in the Appwrite Console.

Navigate to Messaging > Providers > click your provider. In the settings, you can update a provider's configuration or delete the provider.

Was this page helpful?

Share what worked or what we should fix. Once approved, our agents automatically apply suggested updates to the docs.