Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
24 commits
Select commit Hold shift + click to select a range
752c280
Update content for APNS push guide
Aviatorscode2 Oct 22, 2025
a35a920
Update Apns docs based on feedback
Aviatorscode2 Oct 27, 2025
e6bf2a3
Update the links on the page
Aviatorscode2 Oct 27, 2025
b9b9248
Update content/docs/platform/integrations/push/(providers)/apns.mdx
Aviatorscode2 Nov 3, 2025
9ef2da5
Update content/docs/platform/integrations/push/(providers)/apns.mdx
Aviatorscode2 Nov 3, 2025
d41ee53
Update content/docs/platform/integrations/push/(providers)/apns.mdx
Aviatorscode2 Nov 3, 2025
d41e57d
Update content/docs/platform/integrations/push/(providers)/apns.mdx
Aviatorscode2 Nov 3, 2025
4c6d30d
Update content/docs/platform/integrations/push/(providers)/apns.mdx
Aviatorscode2 Nov 3, 2025
338ee65
Update content/docs/platform/integrations/push/(providers)/apns.mdx
Aviatorscode2 Nov 3, 2025
7640477
Update content/docs/platform/integrations/push/(providers)/apns.mdx
Aviatorscode2 Nov 3, 2025
a8d23fe
Update content/docs/platform/integrations/push/(providers)/apns.mdx
Aviatorscode2 Nov 3, 2025
91e94c7
Update content/docs/platform/integrations/push/(providers)/apns.mdx
Aviatorscode2 Nov 3, 2025
25e3c7f
Update content/docs/platform/integrations/push/(providers)/apns.mdx
Aviatorscode2 Nov 3, 2025
0d933c4
Update APNS content
Aviatorscode2 Nov 3, 2025
6327d10
Update content based on Diana feedback
Aviatorscode2 Nov 5, 2025
073fc13
Update content/docs/platform/integrations/push/(providers)/apns.mdx
Aviatorscode2 Nov 5, 2025
1f84803
Update content/docs/platform/integrations/push/(providers)/apns.mdx
Aviatorscode2 Nov 5, 2025
6f4c25b
Update content/docs/platform/integrations/push/(providers)/apns.mdx
Aviatorscode2 Nov 5, 2025
0a9907b
Update content/docs/platform/integrations/push/(providers)/apns.mdx
Aviatorscode2 Nov 5, 2025
57195a4
Update content/docs/platform/integrations/push/(providers)/apns.mdx
Aviatorscode2 Nov 5, 2025
aa76904
implement changes based on feedback
Aviatorscode2 Nov 5, 2025
c1690a6
Update content/docs/platform/integrations/push/(providers)/apns.mdx
Aviatorscode2 Nov 5, 2025
a1deb40
Update content/docs/platform/integrations/push/(providers)/apns.mdx
Aviatorscode2 Nov 5, 2025
aeaa948
Add sdk link
Aviatorscode2 Nov 5, 2025
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
154 changes: 102 additions & 52 deletions content/docs/platform/integrations/push/(providers)/apns.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -6,82 +6,74 @@ description: 'Learn how to use the Apple Push Notification Service (APNS) provid

import { Tab, Tabs } from 'fumadocs-ui/components/tabs';

[Apple Push Notification Service](https://docs.expo.dev/push-notifications/overview/), as the name suggests, is a notification delivery service provided by Apple.
This guide explains how to configure and use the <a href="https://developer.apple.com/notifications/" target="_blank" rel="noopener noreferrer">Apple Push Notification Service (APNS)</a> with Novu to deliver push notifications to iOS devices. It outlines:
- The required setup in your Apple Developer account.
- The connection process in Novu.
- How to manage device tokens and message payloads.

Apple provides two authentication methods to make a secure connection to APNs. The first is Certificate-Based Authentication (using a .p12 certificate). The second is Token-Based Authentication (using a .p8 key). We'll make use of the **.p8** key.
## Configuring APNS with Novu

To enable APNS integration, you need to create an [Apple Developer](https://developer.apple.com/) account with an [Admin role](https://appstoreconnect.apple.com/access/users).
Before sending notifications, APNS must be configured with the correct credentials from your Apple Developer account. Novu uses these credentials to securely authenticate with Apple’s servers.

To generate the p8 key for your account:
### Obtain APNS credentials

1. Head over to **Certificates, Identifiers & Profiles > Keys**.
2. Register a new key and give it a name.
3. Enable the Apple Push Notifications service (APNs) checkbox by selecting it.
4. Click the **Continue** button and on the next page, select **Register**.
5. Download the **.p8** key file.
Apple provides two authentication options for connecting to APNS:
- A certificate-based `.p12` certificate
- A token-based `.p8` key

You also need the following to connect to APNs:
Novu supports both, but this guide focuses on the `.p8` token-based approach, which is recommended for most production setups.

1. **Key ID** - This is a 10-character unique identifier for the authentication key. You can find it in the key details section of the newly created key in your Apple developer account.
2. **Team ID** - This is available in your Apple developer account.
3. **Bundle ID** - This is the ID of your app. You can find it in the app info section of your Apple developer account.
To generate the required credentials, use an <a href="https://developer.apple.com/" target="_blank" rel="noopener noreferrer">Apple Developer account</a> with an [Admin role](https://appstoreconnect.apple.com/access/users). Follow <a href="https://developer.apple.com/help/account/keys/create-a-private-key" target="_blank" rel="noopener noreferrer">Apple’s official steps</a> to create and download a private `.p8` key.

The overrides field supports all [Notification payload](https://developer.apple.com/documentation/usernotifications/setting_up_a_remote_notification_server/generating_a_remote_notification?language=objc) values, as shown below:
The following identifiers are also needed for integration:

```typescript
import { Novu } from '@novu/api';
- <a href="https://developer.apple.com/help/account/keys/get-a-key-identifier/" target="_blank" rel="noopener noreferrer">**Key ID**</a>: A unique 10-character identifier for the authentication key.
- **Team ID**: This is found in your Apple Developer account.
- **Bundle ID**: The identifier for your app, which is available in the app info section.

const novu = new Novu({
secretKey: "<NOVU_SECRET_KEY>",
// Use serverURL for EU region
// serverURL: "https://eu.api.novu.co",
});
### Add APNS credentials to Novu

await novu.trigger({
workflowId: "workflowId",
to: {
subscriberId: "subscriberId",
},
payload: {
abc: 'def', // If the notification is a data notification, the payload will be sent as the data
},
overrides: {
apns: {
payload: {
aps: {
notification: {
title: 'Test',
body: 'Test push',
},
data: {
key: 'value',
},
},
},
},
},
});
```
Once the Apple credentials are available, you can add them in Novu’s Integration Store.

1. Log in to your Novu account.
2. On your dashboard, click **Integration Store**.
3. Click **Connect provider**.
4. Click the **Push** tab.
5. Select **APNS**.
6. In the APNS integration form, fill in the **Name** and **Identifier** fields.
7. In the **Delivery Provider Credentials** section, fill in the following fields:
* **Private Key**: The content of your `.p8` file.
* **Key ID**: Your 10-character Key ID.
* **Team ID**: Your 10-character Team ID.
* **Bundle ID**: Your app's Bundle ID.
![APNS Integration in Novu](/images/channels-and-providers/push/apns/apns-integration.png)
8. Click **Create Integration**.

## Sending notifications with APNS

After configuration, APNS can be used in any Novu workflow that includes a Push step. The process involves registering device tokens for subscribers and then triggering workflows to deliver messages.

### Registering subscriber device tokens

Before triggering the notification to a subscriber(user) with push as a step in the workflow, make sure you have added the subscriber's device token as follows:
Each subscriber (user) must have one or more device tokens registered to receive push notifications. Tokens can be added or updated through Novu’s API using the [Update Subscriber Credentials](/api-reference/subscribers/update-provider-credentials) endpoint.

<Tabs items={['Node.js', 'cURL']}>
<Tab value="Node.js">
```javascript
```typescript
import { Novu } from '@novu/api';
import { ChatOrPushProviderEnum } from "@novu/api/models/components";

const novu = new Novu({
secretKey: "<NOVU_SECRET_KEY>",
// Use serverURL for EU region
// serverURL: "https://eu.api.novu.co",
// serverURL: "[https://eu.api.novu.co](https://eu.api.novu.co)",
});

await novu.subscribers.credentials.update(
{
providerId: ChatOrPushProviderEnum.Apns,
// Use integrationIdentifier to store device tokens for a specific integration
integrationIdentifier: "apns-MnGLxp8uy",
integrationIdentifier: "string",
credentials: {
deviceTokens: ["token1", "token2", "token3"],
},
Expand All @@ -99,10 +91,68 @@ curl -L -X PUT 'https://api.novu.co/v1/subscribers/<SUBSCRIBER_ID>/credentials'
-d '{
"providerId": "apns",
"deviceTokens": ["token1", "token2"],
"integrationIdentifier": "apns-MnGLxp8uy"
"integrationIdentifier": "string"
}'
```
</Tab>
</Tabs>

Checkout the [API reference](/api-reference/subscribers/update-provider-credentials) for more details.
### Triggering workflows

Once subscribers’ devices are registered, push notifications are delivered through [workflows that include a Push step](/platform/workflow/build-a-workflow). A workflow can be triggered using the Novu [SDK](/platform/sdks/overview) or [API](/api-reference/events/trigger-event).

```typescript
import { Novu } from '@novu/node';

const novu = new Novu('<NOVU_SECRET_KEY>');

await novu.trigger('your-workflow-id', {
  to: {
    subscriberId: 'SUBSCRIBER_ID',
  },
  payload: {
    // Your payload data
  },
});
```

## Customizing notifications with overrides

Novu supports an `overrides` field that lets you attach APNS-specific payload parameters when triggering a workflow. This feature is useful for customizing the behavior or presentation of notifications, such as setting titles, bodies, or custom data fields.

The `overrides` field supports all <a href="https://developer.apple.com/documentation/usernotifications/setting_up_a_remote_notification_server/generating_a_remote_notification?language=objc" target="_blank" rel="noopener noreferrer">APNS Notification payload</a> values. Here is an example:

```typescript
import { Novu } from '@novu/api';

const novu = new Novu({
secretKey: "<NOVU_SECRET_KEY>",
// Use serverURL for EU region
// serverURL: "https://eu.api.novu.co",
});

await novu.trigger({
workflowId: "workflowId",
to: {
subscriberId: "subscriberId",
},
payload: {
abc: 'def', // If the notification is a data notification, then the payload is sent as the data
},
overrides: {
apns: {
payload: {
aps: {
notification: {
title: 'Test',
body: 'Test push',
},
data: {
key: 'value',
},
},
},
},
},
});
```
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.