Push Notifications

WalletKit provides the functionality for wallets to receive push notifications through Firebase Cloud Messaging (FCM) and Apple Push Notification Service (APNs) via the Push Server. This feature ensures that wallets are promptly notified of incoming signature requests. Each push notification contains the encrypted details of the signature request. Upon receiving the notification, it can be decrypted and presented to the developer, allowing for customization of the message according to their requirements.

Server setup

For the push notifications to be forwarded to FCM or APNs, the Push Server will need to be configured with your FCM or APNs server API credentials.

App setup

Register the device token

To enable a device for push notifications, it's essential to register the device token using Web3Wallet.registerDeviceToken. This token can be obtained from either FCM or APNS, depending on the platform used.

To receive push notifications from WalletConnect's Push Server via Firebase Cloud Messaging, you will need to setup Firebase in your project. You can follow their docummentation - Firebase documentation. Once you have Firebase configured, you can obtain the device token by calling messaging().getToken(). This unique token is used to identify each device.

import messaging from '@react-native-firebase/messaging'

const token = await messaging().getToken()

The device token will be used to register for WalletConnect push notifications by calling Web3Wallet.registerDeviceToken and passing the token as an argument. The registerDeviceToken should be called every time the client is initialized.

web3wallet.registerDeviceToken({
  token: await messaging().getToken(), // device token
  clientId: await web3wallet.core.crypto.getClientId(), //your instance clientId
  notificationType: 'fcm', // notification type
  enableEncrypted: true // flag that enabled detailed notifications
})

With that the base setup is complete and you can start receiving push notifications from WalletConnect's Push Server for your sessions.

Note, that from time to time, the device token is refreshed, so you must make sure to register it again.

impoprt messaging from '@react-native-firebase/messaging';

messaging().onTokenRefresh(async token => {
    await web3wallet.registerDeviceToken({
        token: await messaging().getToken(), // device token
        clientId: await web3wallet.core.crypto.getClientId(), //your instance clientId
        notificationType: 'fcm', // notification type
        enableEncrypted: true // flag that enabled detailed notifications
    });
});

Receiving push notifications

After the device token is registered, the next step involves setting up the notification service specific to the platform being used. This service will decrypt the incoming requests and forward them to the developer for further processing and integration.

To receive the actual push notifications, you will need to subscribe to firebase messaging events.

import messaging from '@react-native-firebase/messaging';

// emitted when the app is open and a notification is received
messaging().onMessage(async notification => {
    ...
});

// emitted when the app is in the background or closed and a notification is received
messaging().setBackgroundMessageHandler(async notification => {
    ...
});

Now that we have the notifications listeners setup, we can start processing the incoming notifications.

import { Web3Wallet } from '@walletconnect/web3wallet';
import messaging from '@react-native-firebase/messaging';

messaging().onMessage(async notification => {
    // get the topic, encrypted message & tag from the notification payload
    const { topic, message, tag } = notification.data;

    // decrypt the message
    // note this is static method and can be called without initializing the Web3Wallet
    const decryptedMessage = await Web3wallet.notifications.decryptMessage({
    topic,
    encryptedMessage: message,
  });

    /*
    * `decryptedMessage` is JsonRpcRequest object, with the full payload of the incoming request such as method, params, id, etc.
    * You can use it to emit local push notification with the request to the user and ask for their approval.
    **/

   /*
   * the metadata contains name, description, icon and url of the dapp that initiated the request
   * note that only notifications with tag `1108`(session requests) will have metadata,
   **/
   let metadata

   if(tag == 1108) {
        metadata = await Web3Wallet.notifications.getMetadata({ topic });
   } else {
        // session proposals contain metadata in the request itself
        metadata = decryptedMessage.params.proposer.metadata
   }

    // with this information you can show a local push notification to the user
   ...
});