diff --git a/content/docs/platform/integrations/push/(providers)/expo-push.mdx b/content/docs/platform/integrations/push/(providers)/expo-push.mdx index 5f936ac7d..ccb5c8704 100644 --- a/content/docs/platform/integrations/push/(providers)/expo-push.mdx +++ b/content/docs/platform/integrations/push/(providers)/expo-push.mdx @@ -3,35 +3,47 @@ title: 'Expo Push' description: 'Learn how to use the Expo push provider to send push notifications using Novu' --- -import { Tab, Tabs } from 'fumadocs-ui/components/tabs'; +This guide will walk you through the entire process of configuring and using Expo Push with Novu, from getting your credentials to sending your first notification. -[Expo Push](https://docs.expo.dev/push-notifications/overview/) is a notification delivery service provided by Expo. +## How to configure Expo with Novu -To enable Expo Push integration, you need to create an [Expo Application Services (EAS)](https://expo.dev/)account and generate an access token in the EAS dashboard. +Before you can send notifications, you need to connect your Expo project to Novu by generating an access token and adding it to your integration settings. -The overrides field supports all [Message Request](https://docs.expo.dev/push-notifications/sending-notifications/#message-request-format) values. An example of the same follows: +### Step 1: Generate your access token from Expo Push -```typescript -import { Novu } from '@novu/api'; +First, you need to generate an access token from your dashboard. This token authorizes Novu to send notifications on behalf of your project. -const novu = new Novu({ - secretKey: "", - // Use serverURL for EU region - // serverURL: "https://eu.api.novu.co", -}); +1. Log in to the Expo console. +2. Navigate to the **Credentials** section in the project settings sidebar. +3. Click **Access Token**. +![Create Expo token](/images/channels-and-providers/push/expo-push/create-token.png) +4. Click **Create Token** and a menu will appear +5. Give it a descriptive name and then Click **Generate New Token**. +![Generate Expo token](/images/channels-and-providers/push/expo-push/generate-token.png) +6. Copy the generated access token, you will need it in the next step. +![Copy Expo token](/images/channels-and-providers/push/expo-push/copy-token.png) -await novu.trigger({ - workflowId: "workflowId", - to: { - subscriberId: "subscriberId", - }, - payload: { - key: "value", - }, -}); -``` +### Step 2: Connect Expo Push to Novu + +Next, add the access token to your Expo integration in the Novu dashboard. + +1. Log in to the Novu dashboard +2. Navigate to the **Integration Store** page on the Novu dashboard. +3. Click **Connect provider**. +4. Under the **Push** tab, select **Expo Push**. +5. In the Expo integration form, paste the **Access Token** you copied from Expo into the **Access Token** field. +![Expo Integration in Novu](/images/channels-and-providers/push/expo-push/expo-integration.png) +6. Click **Create Integration**. + +## Using Expo 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. -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: +You can do this by making an API call to [update the subscriber's credentials](/api-reference/subscribers/update-provider-credentials). @@ -49,9 +61,12 @@ await novu.subscribers.credentials.update( { providerId: ChatOrPushProviderEnum.Expo, // Use integrationIdentifier to store device tokens for a specific integration - integrationIdentifier: "expo-MnGLxp8uy", + integrationIdentifier: "string", credentials: { - deviceTokens: ["token1", "token2", "token3"], + deviceTokens: [ + "token1", + "token2" + ] }, }, "subscriberId" @@ -67,11 +82,69 @@ curl -L -X PUT 'https://api.novu.co/v1/subscribers//credentials' -d '{ "providerId": "expo", "deviceTokens": ["token1", "token2"], - "integrationIdentifier": "expo-MnGLxp8uy" + "integrationIdentifier": "string" }' ``` - -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 in the editor and trigger it. Novu will send the notification to all devices associated with the subscriber. + +The example below demonstrates a simple trigger using Novu’s SDK. + +```typescript +import { Novu } from '@novu/node'; + +const novu = new Novu('YOUR_NOVU_API_KEY'); + +await novu.trigger('your-workflow-id', { + to: { + subscriberId: 'SUBSCRIBER_ID', + }, + payload: { + // Your payload data + }, +}); +``` + +## Using overrides to customize notifications + +Novu provides an verrides fields that let you send additional Expo-specific message fields. You can use this to control how messages are displayed or to attach custom payloads. + +The overrides field supports all Expo Message Request values. Here is an example: + +```typescript +import { Novu } from '@novu/api'; + +const novu = new Novu({ + secretKey: "", + // Use serverURL for EU region + // serverURL: "https://eu.api.novu.co", +}); + +await novu.trigger({ + workflowId: "workflowId", + to: { subscriberId: "subscriber-id-123" }, + payload: { + orderId: "12345", + }, + overrides: { + providers: { + expo: { + title: "Order Update", + body: "Your order #12345 has been shipped!", + data: { + deepLink: "myapp://orders/12345", + orderId: "12345", + }, + sound: "default", + priority: "high", + ttl: 3600, + }, + }, + }, +}); +``` \ No newline at end of file diff --git a/content/docs/platform/integrations/push/(providers)/fcm.mdx b/content/docs/platform/integrations/push/(providers)/fcm.mdx index 873f27b11..133828b37 100644 --- a/content/docs/platform/integrations/push/(providers)/fcm.mdx +++ b/content/docs/platform/integrations/push/(providers)/fcm.mdx @@ -5,132 +5,208 @@ description: 'Learn how to use the Firebase Cloud Messaging (FCM) provider to se --- import { Accordion, Accordions } from 'fumadocs-ui/components/accordion'; -import { Tab, Tabs } from 'fumadocs-ui/components/tabs'; -[Firebase Cloud Messaging](https://firebase.google.com/docs/cloud-messaging) is a free notification delivery service provided by Google Firebase. +This guide will walk you through the entire process of configuring and using FCM with Novu, from getting your credentials to sending your first notification. -To enable the FCM integration, you need to get your service account key from the [Firebase Console](https://console.firebase.google.com/). - -## Generating a service account key JSON - -To acquire the account key JSON file for your service account - -1. Select your project, and click the gear icon on the top of the sidebar. -2. Head to project settings. -3. Navigate to the service account tab. -4. Click **Generate New Private Key,** then confirm by clicking **Generate Key.** -5. Clicking **Generate Key** downloads the JSON file. - -After that, paste the entire JSON file content in the Service Account field of the FCM provider in the integration store on Novu's web dashboard. - -Make sure your service account json content contains these fields + Novu uses FCM version V1 -```json -{ - "type": "service_account", - "project_id": "PROJECT_ID", - "private_key_id": "PRIVATE_KEY_ID", - "private_key": "PRIVATE_KEY", - "client_email": "FIREBASE_ADMIN_SDK_EMAIL", - "client_id": "CLIENT_ID", - "auth_uri": "https://accounts.google.com/o/oauth2/auth", - "token_uri": "https://oauth2.googleapis.com/token", - "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs", - "client_x509_cert_url": "CLIENT_X509_CERT_URL" -} -``` +## Step 1: Generate your service account key from Firebase + +First, you need to get your project's service account credentials from the Firebase Console. + +1. Log in to the Firebase console. +2. Created a new Firebase project or select an existing project. +![Select Firebase Project](/images/channels-and-providers/push/select-firebase-project.png) +3. Click the gear icon ⚙️ next to **Project Overview**. +4. Select **Project settings**. +![Firebase Project Settings](/images/channels-and-providers/push/firebase-project-settings.png) +5. Go to the **Service accounts** tab. +6. Click the **Generate new private key** button. A confirmation menu will appear. +![Firebase Service Accounts](/images/channels-and-providers/push/firebase-service-accounts.png) +7. Click **Generate key** to download a JSON file containing your credentials. +![](/images/channels-and-providers/push/confirmation-menu.png) +8. Open the downloaded JSON file and ensure it contains these fields + ```json + { + "type": "service_account", + "project_id": "PROJECT_ID", + "private_key_id": "PRIVATE_KEY_ID", + "private_key": "PRIVATE_KEY", + "client_email": "FIREBASE_ADMIN_SDK_EMAIL", + "client_id": "CLIENT_ID", + "auth_uri": "https://accounts.google.com/o/oauth2/auth", + "token_uri": "https://oauth2.googleapis.com/token", + "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs", + "client_x509_cert_url": "CLIENT_X509_CERT_URL" + } + ``` + +## Step 2: Connect FCM to Novu + +Now, you'll add the credentials to your FCM integration in the Novu dashboard. + +1. Log in to the Novu dashboard +2. Navigate to the **Integration Store** page on the Novu dashboard. +3. Click **Connect provider**. +4. Under the **Push** tab, select **Firebase Cloud Messaging (FCM)**. +5. Open the JSON file you downloaded from Firebase in [Step 1](/platform/integrations/push/fcm#step-1-generate-your-service-account-key-from-firebase). +6. Copy the entire content of the JSON file and paste it into the **Service Account** field in the FCM integration modal. + +5. Click **Create Integration** to save the integration. + +## Step 3: Register a subscriber's device token + +Before Novu can send a push notification to your subscriber, 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). -## FCM overrides + + + ```typescript + import { Novu } from "@novu/api"; + import { ChatOrPushProviderEnum } from "@novu/api/models/components"; + + const novu = new Novu({ secretKey: "YOUR_SECRET_KEY_HERE",}); + + async function run() { + const result = await novu.subscribers.credentials.update({ + providerId: ChatOrPushProviderEnum.Fcm, + credentials: { + deviceTokens: [ + "token1", + "token2", + ], + }, + }, "subscriberId"); + } + run(); + ``` + + + ```bash + curl -L -X PUT 'https://api.novu.co/v1/subscribers//credentials' \ + -H 'Content-Type: application/json' \ + -H 'Accept: application/json' \ + -H 'Authorization: ApiKey ' \ + -d '{ + "providerId": "fcm", + "credentials": { + "deviceTokens" : [ + "token1", + "token2" + ] + }, + "integrationIdentifier": "string" + }' + ``` + + -The overrides field supports apns, android, webpush and fcmOptions overrides +### Using multiple FCM integrations -| Override Field | Type / Interface | Link | -| -------------- | ---------------- | -------------------------------------------------------------------------------------------- | -| android | AndroidConfig | https://firebase.google.com/docs/reference/admin/node/firebase-admin.messaging.androidconfig | -| apns | ApnsConfig | https://firebase.google.com/docs/reference/admin/node/firebase-admin.messaging.apnsconfig | -| webPush | WebpushConfig | https://firebase.google.com/docs/reference/admin/node/firebase-admin.messaging.webpushconfig | -| fcmOptions | FcmOptions | https://firebase.google.com/docs/reference/admin/node/firebase-admin.messaging.fcmoptions | +If you have multiple active FCM integrations, you can specify which integration to associate the tokens with by providing the `integrationIdentifier`. -## Managing device tokens +You can find this identifier in your Novu dashboard on the integration's settings page. -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: +![Integration identifier](/images/channels-and-providers/push/integrationidentifier.png) - - ```typescript import { Novu } from '@novu/api'; -import { ChatOrPushProviderEnum } from "@novu/api/models/components"; const novu = new Novu({ secretKey: "", - // Use serverURL for EU region - // serverURL: "https://eu.api.novu.co", }); await novu.subscribers.credentials.update( { - providerId: ChatOrPushProviderEnum.Fcm, + providerId: "fcm", + // Use integrationIdentifier to store device tokens for a specific integration + integrationIdentifier: "string", credentials: { - deviceTokens: ["token1", "token2", "token3"], + deviceTokens: [ + "token1", + "token2" + ] }, }, "subscriberId" ); ``` - - -```bash -curl -L -X PUT 'https://api.novu.co/v1/subscribers//credentials' \ --H 'Content-Type: application/json' \ --H 'Accept: application/json' \ --H 'Authorization: ApiKey ' \ --d '{ - "providerId": "fcm", - "credentials": { - "deviceTokens" : [ - "token1", - "token2" - ] + +## Step 4: Send a notification + +Now you're ready to send a push notification. You can trigger a notification to a subscriber who has a registered device token. + +```typescript +import { Novu } from '@novu/node'; + +const novu = new Novu('YOUR_NOVU_API_KEY'); + +await novu.trigger('your-workflow-id', { + to: { + subscriberId: 'SUBSCRIBER_ID', }, - "integrationIdentifier": "fcm-MnGLxp8uy" -}' + payload: { + // Your payload data + }, +}); ``` - - +## Using overrides to customize notifications -Checkout the [API reference](/api-reference/subscribers/update-provider-credentials) for more details. +Novu lets you customize the behavior of push notifications by using the overrides field when triggering workflows. Overrides give you full control over message content and delivery parameters that aren’t configurable from the Novu workflow editor. -### Managing device tokens for multiple integrations +To learn more about how overrides work across all channels, see the [Trigger Overrides](/platform/integrations/trigger-overrides) documentation. -Novu supports multiple active integrations per provider for push channel. There can be more than one FCM integration active at a time. By default, device tokens are stored for recently created integration. To store device tokens for a specific integration, you can use the `integrationIdentifier` field. `integrationIdentifier` is the identifier of the integration in the Novu dashboard. +### Override FCM field -```typescript -import { Novu } from '@novu/api'; -import { ChatOrPushProviderEnum } from "@novu/api/models/components"; +Overrides lets you to send platform-specific data that is not available in the workflow editor. The overrides field supports `apns`, `android`, `webpush` and `fcmOptions` overrides. -const novu = new Novu({ - secretKey: "", - // Use serverURL for EU region - // serverURL: "https://eu.api.novu.co", -}); +| Override Field | Type / Interface | Link | +| -------------- | ---------------- | -------------------------------------------------------------------------------------------- | +| android | AndroidConfig | https://firebase.google.com/docs/reference/admin/node/firebase-admin.messaging.androidconfig | +| apns | ApnsConfig | https://firebase.google.com/docs/reference/admin/node/firebase-admin.messaging.apnsconfig | +| webPush | WebpushConfig | https://firebase.google.com/docs/reference/admin/node/firebase-admin.messaging.webpushconfig | +| fcmOptions | FcmOptions | https://firebase.google.com/docs/reference/admin/node/firebase-admin.messaging.fcmoptions | -await novu.subscribers.credentials.update( - { - providerId: ChatOrPushProviderEnum.Fcm, - // Use integrationIdentifier to store device tokens for a specific integration - integrationIdentifier: "fcm-MnGLxp8uy", - credentials: { - deviceTokens: ["token1", "token2", "token3"], +You can use these fields to customize how notifications are sent to Android, iOS (via APNs), or web clients. + +``` +await novu.trigger('your-workflow-id', { + to: { + subscriberId: 'SUBSCRIBER_ID', + }, + payload: { + // Your payload data + }, + overrides: { + fcm: { + // For a data-only notification (silent push) + type: 'data', + data: { + custom_key: 'custom_value', + }, + // Platform-specific overrides + android: { + // See FCM AndroidConfig options + }, + apns: { + // See FCM ApnsConfig options + }, + webPush: { + // See FCM WebpushConfig options + }, + fcmOptions: { + // See FCM FcmOptions + } }, }, - "subscriberId" -); +}); ``` -## SDK trigger example +### Override FCM notification content -By default, Novu will send the FCM notification content written in the step editor workflow. You can override the notification content by using the `overrides` field. Use type: `data` and `data` to send data type notification. +By default, Novu will send the FCM notification content written in the step editor workflow. However, you can override the notification content by using the `overrides` field. Use type: `data` and `data` to send data type notification. ```typescript import { Novu } from '@novu/api'; @@ -173,9 +249,40 @@ await novu.trigger({ }); ``` - Novu uses FCM version V1 +Overrides can be applied at runtime to customize or enrich notifications based on user context, device type, or workflow logic. -## Relative link in webpush +## Sending notifications to FCM topics + +FCM topics are used to send notifications to multiple devices at once. Use trigger overrides to send notifications to a topic. In this case, subscriber device tokens are not required. + +```typescript +import { Novu } from '@novu/api'; + +const novu = new Novu({ + secretKey: "", + // Use serverURL for EU region + // serverURL: "https://eu.api.novu.co", +}); + +await novu.trigger({ + workflowId: "workflowId", + to: { + subscriberId: "subscriberId", + }, + payload: { + key: "value", + }, + overrides: { + providers: { + fcm: { + topic: "topic-123", + }, + }, + }, +}); +``` + +## Web push with relative links Suppose you're using the Firebase (FCM) provider to send push notifications to web browsers via Novu and want users to be returned to the website after clicking the notification. @@ -239,66 +346,15 @@ curl --location --request POST 'https://url.to.our.selfhosted.novu' \ -## Sending notifications to FCM topics - -[FCM topics](https://firebase.google.com/docs/cloud-messaging/android/topic-messaging) are used to send notifications to multiple devices at once. Use trigger overrides to send notifications to a topic. In this case, subscriber device tokens are not required. - -```typescript -import { Novu } from '@novu/api'; - -const novu = new Novu({ - secretKey: "", - // Use serverURL for EU region - // serverURL: "https://eu.api.novu.co", -}); - -await novu.trigger({ - workflowId: "workflowId", - to: { - subscriberId: "subscriberId", - }, - payload: { - key: "value", - }, - overrides: { - providers: { - fcm: { - topic: "topic-123", - }, - }, - }, -}); -``` - -## FCM cost - -As per Firebase [pricing](https://firebase.google.com/pricing), **Cloud Messaging** product is free of cost to use. If other Firebase products are used, the cost will be charged as per the product. - ## Frequently asked questions -While using the FCM provider, you may encounter the following issues. - -### The registration token is not a valid FCM registration token - -You may come across an error like so: - -``` -Sending message failed due to "The registration token is not a valid FCM registration token" -``` - -This error happens because of invalid or stale token. The fix for this is to remove old tokens, generate a new token and save it into user subscribers. - -### FCM notifications sent successfully with no error but push notification is not received in device - -Try to generate a new token after clearing device cache and retry with this fresh token. - -### Sending message failed due to 'Requested entity was not found' - -This error occurs when your token is no longer valid. To fix this, generate a new token and use it. - -### Subscriber does not have a configured channel error - -This error occurs if the fcm integration is active but subscriber is missing from the fcm credentials (deviceTokens). The credentials (deviceTokens) for the subscriber needs to be set. - -### How to send desktop notifications using FCM -Desktop notifications for websites can be sent using FCM webpush. + + As per Firebase pricing, **Cloud Messaging** product is free of cost to use. If other Firebase products are used, the cost will be charged as per the product. + + You may come across an error like so: `Sending message failed due to "The registration token is not a valid FCM registration token"`. This error happens because of invalid or stale token. The fix for this is to remove old tokens, generate a new token and save it into user subscribers. + + Try to generate a new token after clearing device cache and retry with this fresh token. + This error occurs when your token is no longer valid. To fix this, generate a new token and use it. + This error occurs if the fcm integration is active but subscriber is missing from the fcm credentials (deviceTokens). The credentials (deviceTokens) for the subscriber needs to be set. + Desktop notifications for websites can be sent using FCM webpush. + \ No newline at end of file diff --git a/content/docs/platform/meta.json b/content/docs/platform/meta.json index 9216a570b..216a2e6c2 100644 --- a/content/docs/platform/meta.json +++ b/content/docs/platform/meta.json @@ -22,7 +22,7 @@ "workflow/step-conditions", "workflow/tags", "workflow/translations", - "---Channels---", + "---Channels Provider Integration---", "...integrations", "---Account---", "account/authentication", diff --git a/public/images/channels-and-providers/push/confirmation-menu.png b/public/images/channels-and-providers/push/confirmation-menu.png new file mode 100644 index 000000000..372114302 Binary files /dev/null and b/public/images/channels-and-providers/push/confirmation-menu.png differ diff --git a/public/images/channels-and-providers/push/expo-push/copy-token.png b/public/images/channels-and-providers/push/expo-push/copy-token.png new file mode 100644 index 000000000..ff45b16b9 Binary files /dev/null and b/public/images/channels-and-providers/push/expo-push/copy-token.png differ diff --git a/public/images/channels-and-providers/push/expo-push/create-token.png b/public/images/channels-and-providers/push/expo-push/create-token.png new file mode 100644 index 000000000..293f8e184 Binary files /dev/null and b/public/images/channels-and-providers/push/expo-push/create-token.png differ diff --git a/public/images/channels-and-providers/push/expo-push/expo-integration.png b/public/images/channels-and-providers/push/expo-push/expo-integration.png new file mode 100644 index 000000000..db5f48351 Binary files /dev/null and b/public/images/channels-and-providers/push/expo-push/expo-integration.png differ diff --git a/public/images/channels-and-providers/push/expo-push/generate-token.png b/public/images/channels-and-providers/push/expo-push/generate-token.png new file mode 100644 index 000000000..692321209 Binary files /dev/null and b/public/images/channels-and-providers/push/expo-push/generate-token.png differ diff --git a/public/images/channels-and-providers/push/firebase-project-settings.png b/public/images/channels-and-providers/push/firebase-project-settings.png new file mode 100644 index 000000000..cae5a399d Binary files /dev/null and b/public/images/channels-and-providers/push/firebase-project-settings.png differ diff --git a/public/images/channels-and-providers/push/firebase-service-accounts.png b/public/images/channels-and-providers/push/firebase-service-accounts.png new file mode 100644 index 000000000..525627ff0 Binary files /dev/null and b/public/images/channels-and-providers/push/firebase-service-accounts.png differ diff --git a/public/images/channels-and-providers/push/integrationidentifier.png b/public/images/channels-and-providers/push/integrationidentifier.png new file mode 100644 index 000000000..02667ba77 Binary files /dev/null and b/public/images/channels-and-providers/push/integrationidentifier.png differ diff --git a/public/images/channels-and-providers/push/select-firebase-project.png b/public/images/channels-and-providers/push/select-firebase-project.png new file mode 100644 index 000000000..9921d9eea Binary files /dev/null and b/public/images/channels-and-providers/push/select-firebase-project.png differ