Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
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
151 changes: 99 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,69 @@ 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 will walk you through the entire process of configuring and using the <a href="https://developer.apple.com/notifications/" target="_blank" rel="noopener noreferrer">Apple Push Notification Service (APNS)</a> with Novu.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
This guide will walk you through the entire process of configuring and using the <a href="https://developer.apple.com/notifications/" target="_blank" rel="noopener noreferrer">Apple Push Notification Service (APNS)</a> with Novu.
This guide walks you through the entire process of configuring and using the <a href="https://developer.apple.com/notifications/" target="_blank" rel="noopener noreferrer">Apple Push Notification Service (APNS)</a> with Novu.


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.
## How to configure APNS with Novu
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
## How to configure APNS with Novu
## Configure 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 you can send notifications, you must configure your Apple Developer account to get the necessary credentials and add them to your Novu integration.

To generate the p8 key for your account:
### Step 1: Get your 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 methods to make a secure connection to APNs. The first is a 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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Apple provides two authentication methods to make a secure connection to APNs. The first is a 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.
Apple provides two authentication methods to make a secure connection to APNS. The first is a certificate-based authentication using a `.p12` certificate. The second is token based authentication using a `.p8` key. For this guide, you'll use the `.p8` key.


You also need the following to connect to APNs:
To enable APNS integration, create 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).

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.
Follow <a href="https://developer.apple.com/help/account/keys/create-a-private-key" target="_blank" rel="noopener noreferrer">this Apple’s official guide</a> to generate and download the p8 key for your account.

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:
You also need the following to connect Novu to APNs:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

APNs or APNS? Choose one and use it throughout.


```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>: 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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
* <a href="https://developer.apple.com/help/account/keys/get-a-key-identifier/" target="_blank" rel="noopener noreferrer">**Key ID**</a>: 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.
* <a href="https://developer.apple.com/help/account/keys/get-a-key-identifier/" target="_blank" rel="noopener noreferrer">**Key ID**</a>: 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.

* **Team ID**: This is available in your Apple developer account.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
* **Team ID**: This is available in your Apple developer account.
* **Team ID**: Available in your Apple developer account.

* **Bundle ID**: This is the ID of your app. You can find it in the app info section of your Apple developer account.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
* **Bundle ID**: This is the ID of your app. You can find it in the app info section of your Apple developer account.
* **Bundle ID**: The ID of your app. You can find it in the app info section of your Apple developer account.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should "app info" be capitalized? Match the Apple UI if possible.


const novu = new Novu({
secretKey: "<NOVU_SECRET_KEY>",
// Use serverURL for EU region
// serverURL: "https://eu.api.novu.co",
});
### Step 2: Connect APNS 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',
},
},
},
},
},
});
```
Next, add these credentials to your APNS integration in the Novu dashboard.

1. Log in to the Novu dashboard
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
1. Log in to the Novu dashboard
1. Log in to the Novu dashboard.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please remember to run a spelling and grammar check before you submit. It would probably have caught the missing period.

2. On the Novu dashboard, navigate to the **Integration Store**.
3. Click **Connect provider**.
4. In the **Push** tab, select **APNS**.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Only bold the tab if the user needs to click it.

5. In the APNS integration form, fill in the **Name** and **Identifier** fields and in the **Delivery Provider Crendetials** section fill in the following fields:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This should be two or three separate steps.

* **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)
6. Click **Create Integration**.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What happens next? How do I know the integration was created successfully?


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:
## Using APNS with Novu

Once your integration is configured, you can start sending push notifications by registering your subscribers' device tokens and triggering a workflow.

### Step 1: Add subscriber device token

Before Novu can send a push notification to a subscriber(user), you must associate their device's unique push token with their Novu subscriber profile.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Before Novu can send a push notification to a subscriber(user), you must associate their device's unique push token with their Novu subscriber profile.
Before Novu can send a push notification to a subscriber (user), you must associate their device's unique push token with their Novu subscriber profile.


You can do this by making an API call to [update the subscriber's credentials](/api-reference/subscribers/update-provider-credentials).

<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 +86,70 @@ 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.
### Step 2: Send a notification

Now you're ready to send a push notification. [Create a workflow with a Push step](/platform/workflow/build-a-workflow) and trigger it. Novu will send the notification to all devices associated with the subscriber.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Now you're ready to send a push notification. [Create a workflow with a Push step](/platform/workflow/build-a-workflow) and trigger it. Novu will send the notification to all devices associated with the subscriber.
Now you're ready to send a push notification. [Create a workflow with a Push step](/platform/workflow/build-a-workflow) and trigger it. Novu sends the notification to all devices associated with the subscriber.


The example below demonstrates a simple trigger using Novu’s SDK.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do you also want to link to instructions for more complex triggers so that the user can iterate on this simple one?


```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
  },
});
```

## Using overrides to customize notifications

Novu provides an overrides field that lets you send additional APNS-specific payload fields. You can use this to control how messages are displayed or to attach custom data.

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, the payload will be sent as the data
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
abc: 'def', // If the notification is a data notification, the payload will be sent as the data
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.