-
Couldn't load subscription status.
- Fork 111
Update content for APNS push guide #988
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
base: push-provider-guides
Are you sure you want to change the base?
Changes from all commits
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change | ||||
|---|---|---|---|---|---|---|
|
|
@@ -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. | ||||||
|
|
||||||
| 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 | ||||||
|
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
Suggested change
|
||||||
|
|
||||||
| 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. | ||||||
|
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
Suggested change
|
||||||
|
|
||||||
| 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: | ||||||
|
There was a problem hiding this comment. Choose a reason for hiding this commentThe 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. | ||||||
|
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
Suggested change
|
||||||
| * **Team ID**: This is available in your Apple developer account. | ||||||
|
There was a problem hiding this comment. Choose a reason for hiding this commentThe 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. | ||||||
|
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
Suggested change
There was a problem hiding this comment. Choose a reason for hiding this commentThe 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 | ||||||
|
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
Suggested change
There was a problem hiding this comment. Choose a reason for hiding this commentThe 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**. | ||||||
|
There was a problem hiding this comment. Choose a reason for hiding this commentThe 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: | ||||||
|
There was a problem hiding this comment. Choose a reason for hiding this commentThe 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. | ||||||
|  | ||||||
| 6. Click **Create Integration**. | ||||||
|
There was a problem hiding this comment. Choose a reason for hiding this commentThe 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. | ||||||
|
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
Suggested change
|
||||||
|
|
||||||
| 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"], | ||||||
| }, | ||||||
|
|
@@ -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. | ||||||
|
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
Suggested change
|
||||||
|
|
||||||
| The example below demonstrates a simple trigger using Novu’s SDK. | ||||||
|
There was a problem hiding this comment. Choose a reason for hiding this commentThe 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 | ||||||
|
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
Suggested change
|
||||||
| }, | ||||||
| overrides: { | ||||||
| apns: { | ||||||
| payload: { | ||||||
| aps: { | ||||||
| notification: { | ||||||
| title: 'Test', | ||||||
| body: 'Test push', | ||||||
| }, | ||||||
| data: { | ||||||
| key: 'value', | ||||||
| }, | ||||||
| }, | ||||||
| }, | ||||||
| }, | ||||||
| }, | ||||||
| }); | ||||||
| ``` | ||||||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.