Push Notifications

Push notification management in the @espressif/rainmaker-base-sdk allows you to register your app for receiving push notifications about RainMaker events such as device sharing, node updates, and other important notifications.

note

The userInstance mentioned below refers to the ESPRMUser instance obtained during User Sign in.

Prerequisites

Before using the push notification methods in the SDK, you must configure push notifications for your app platform:

• For Android: Configure Firebase Cloud Messaging (FCM)
• For iOS: Configure Apple Push Notification service (APNS)

Follow the detailed setup guide at: Push Notifications Configuration Guide

This setup includes:

1. Configuring your app for push notifications (FCM for Android / APNS for iOS)
2. Creating platform applications in the RainMaker Dashboard
3. Enabling push notifications in deployment settings

Once your app is configured, you can use the SDK methods below to register device endpoints and manage push notifications.

Platform Endpoint Management

Create Platform Endpoint

Register a mobile device endpoint for push notifications using the createPlatformEndpoint method. This method associates your device token with the RainMaker platform, enabling your app to receive push notifications.

/*
- platform: The platform type ('FCM' for Android, 'APNS' for iOS production, 'APNS_SANDBOX' for iOS development)
- deviceToken: The device token received from FCM (Android) or APNS (iOS)
- type: Optional platform-specific type identifier
*/

try {
  const platformEndpoint = await userInstance.createPlatformEndpoint({
    platform: "FCM",
    deviceToken: "your-device-token-here",
  });
  console.log("Platform endpoint created:", platformEndpoint);
} catch (error) {
  console.error("Error creating platform endpoint:", error);
}

Parameters:

The method accepts an object with the following properties:

Property	Type	Required	Description
platform	string	Yes	The mobile platform type. Use 'FCM' for Android, 'APNS' for iOS production, or 'APNS_SANDBOX' for iOS development/testing.
deviceToken	string	Yes	The device token obtained from FCM (Android) or APNS (iOS) for push notifications.
type	string	No	Optional platform-specific type identifier for additional categorization.

Returns: Promise<string> - A promise that resolves to the platform endpoint ARN (Amazon Resource Name) assigned by the RainMaker platform.

Example: Create Platform Endpoint for Android (FCM)

try {
  // Device token obtained from Firebase Cloud Messaging
  const fcmToken = "eDqGvN8xRZy..."; // Your FCM token

  const platformEndpoint = await userInstance.createPlatformEndpoint({
    platform: "FCM",
    deviceToken: fcmToken,
  });

  console.log("Android platform endpoint created:", platformEndpoint);
  // Output: arn:aws:sns:region:account-id:endpoint/FCM/AppName/endpoint-id
} catch (error) {
  console.error("Error creating Android platform endpoint:", error);
}

Example: Create Platform Endpoint for iOS Production (APNS)

try {
  // Device token obtained from Apple Push Notification service
  const apnsToken = "a1b2c3d4..."; // Your APNS token

  const platformEndpoint = await userInstance.createPlatformEndpoint({
    platform: "APNS",
    deviceToken: apnsToken,
  });

  console.log("iOS production platform endpoint created:", platformEndpoint);
  // Output: arn:aws:sns:region:account-id:endpoint/APNS/AppName/endpoint-id
} catch (error) {
  console.error("Error creating iOS platform endpoint:", error);
}

Example: Create Platform Endpoint for iOS Development (APNS_SANDBOX)

try {
  // Device token obtained from Apple Push Notification service (sandbox)
  const apnsToken = "a1b2c3d4..."; // Your APNS sandbox token

  const platformEndpoint = await userInstance.createPlatformEndpoint({
    platform: "APNS_SANDBOX",
    deviceToken: apnsToken,
  });

  console.log("iOS sandbox platform endpoint created:", platformEndpoint);
  // Output: arn:aws:sns:region:account-id:endpoint/APNS_SANDBOX/AppName/endpoint-id
} catch (error) {
  console.error("Error creating iOS sandbox platform endpoint:", error);
}

tip

The device token is typically obtained when your app initializes push notification services. On Android, use Firebase Cloud Messaging's getToken() method. On iOS, use the didRegisterForRemoteNotificationsWithDeviceToken delegate method.

Delete Platform Endpoint

Remove a registered platform endpoint using the deleteEndpoint method. This is useful when a user logs out or when you need to update the registration.

/*
- deviceToken: The mobile device token associated with the platform endpoint
- endpoint: The platform endpoint ARN to delete
*/

try {
  const response = await userInstance.deleteEndpoint(
    "your-device-token",
    "arn:aws:sns:region:account-id:endpoint/FCM/AppName/endpoint-id"
  );
  console.log("Platform endpoint deleted:", response);
} catch (error) {
  console.error("Error deleting platform endpoint:", error);
}

Parameters:

Both parameters are required (at least one must be provided):

Parameter	Type	Required	Description
deviceToken	string	Yes*	The device token that was used to create the platform endpoint.
endpoint	string	Yes*	The platform endpoint ARN returned from createPlatformEndpoint.

*At least one parameter must be provided, though typically both are provided for clarity.

Returns: Promise<ESPAPIResponse> - A promise that resolves to the API response indicating success or failure.

Example: Delete Platform Endpoint

try {
  const deviceToken = "eDqGvN8xRZy..."; // Your device token
  const endpointArn =
    "arn:aws:sns:region:account-id:endpoint/FCM/AppName/endpoint-id";

  const response = await userInstance.deleteEndpoint(deviceToken, endpointArn);
  console.log("Endpoint deleted successfully:", response);
} catch (error) {
  console.error("Error deleting endpoint:", error);
}

Real-World Implementation

The ESP RainMaker Home app demonstrates a production implementation where the platform endpoint is created using helper methods upon successful user login.

See the Login.tsx implementation where createPlatformEndpoint() is called after successful login. You can also explore the helper methods in the app's utils/notifications directory for a complete implementation pattern.

Notification Types

Once configured, your app will receive push notifications for the following RainMaker events:

• Node Sharing: When a device/node is shared with the user
• Node Addition or Removal: When a node get added or removed
• Node Updates: When device parameters change
• Automation Events: When automation rules trigger
• Alert Notifications: System alerts and important updates

You can customize which events trigger notifications in the RainMaker Dashboard under Deployment Settings > Push Notifications.

For details on notification payload structures, see RainMaker Push Notification Payloads.

Troubleshooting

Common Issues

Issue: Platform endpoint creation fails

• Verify that push notifications are configured in the RainMaker Dashboard
• Ensure the platform type matches your app configuration (FCM/APNS/APNS_SANDBOX)
• Check that the device token is valid and not expired

Issue: Not receiving notifications

• Verify that notifications are enabled in Deployment Settings
• Check that the correct platform application is created in the Dashboard
• Ensure the app has notification permissions granted by the user
• For iOS, verify you're using the correct environment (sandbox vs production)

Related Resources

• Push Notifications Configuration Guide - Setup guide for FCM and APNS
• RainMaker Push Notification Payloads - Notification payload structures
• Firebase Cloud Messaging - FCM documentation
• Apple Push Notification service - APNS documentation