Skip to main content

Notification Standards Overview

All notifications passed to the network are eventually transformed to JSON payload. The following glossaries help cover some of the basics that can help in understanding what is happening and how to customize the behavior.

Important glossaries​

  • Verification Proof - Each notification sent carries with itself a verification proof that allows the network to validate that the notification is coming from a channel or one of it's delegate.

    note

    Verification Proof is handled automatically by the SDK but you if you want to, you can read about it over here.

  • Notification Identity - Each notification passed to the network is actually an identity which defines how the notification is formatted, where it's stored, etc.

    note

    Notification identity is abstracted away by the SDK except when invoking directly from your smart contracts. Advance section has detailed explaination about Notification Identity.

  • Identity Type - Defines the format in which the notification json payload is sent to the network. Common types you need to know about.

    Identity TypeRemarksDescription
    0MinimalRecommended for Smart Contract
    2Direct PayloadRecommended for PUSH SDK

  • Notification Type - Defines the type of notification that is sent:

    • Broadcast (Type 1) - Is sent out to all the users who have opted in to your channel
    • Targeted (Type 3) - Is sent out to an individual user
    • Subset (Type 4) - Is sent out to a subset of users of your channel

  • Notification Content - Defines the notification content which consists of:

    • Notification JSON Object - What is shown on your home screen
    • Payload JSON Object - What is shown and stored on your feed
    • Recipients - 0x0 for type 1 (broadcast), 0xTarget for type 3 (Targeted) and [0x01, 0x02, 0x03, ..., 0xN] for type 4 (Subset)
      // Example Raw Content for targeted notifcation, abstracted away by SDK
      {
        "notification": {
          "title": "The title of your message displayed on screen (50 Chars)",
          "body": "The intended message displayed on screen (180 Chars)"
        },
        "data": { // Is defined as payload most of the time
          "type": "3" // notification type
          "sectype": null // enables encrypted notifications
          "asub": "[Optional] The subject of the message displayed inside app (80 Chars)",
          "amsg": "[Optional] The intended message displayed inside app (500 Chars)",
          "acta": "[Optional] The cta link parsed inside the app",
          "aimg": "[Optional] The image url which is shown inside the app",
          "etime": "[Optional] if given, notif will be deleted after this in epoch"
          "hidden" :"[Optional] if given, notif will not show in user feed"
        },
          "recipients": 0xtarget
      }
    note

    These concepts are for your understanding as most of them are abstracted away but if you wish to dive deeper then read more about notification payload here.

  • Content Markdown - Defines how the content markdown should be passed to enable variety of notifications. Covered in detail in the advanced section - Notification Content.

  • Sender - Defines who is sending the message. The sender is the channel address or the alias address. The address should be represented in chain specific format as depicted over here

    Examples:

    • Ethereum(Mainnet): eip155:1:<Address>
    • Ethereum(Goerli): eip155:42:<Address>
    • Polygon(Mumbai): eip155:80001:<Address>
    caution

    One exception to chain specific format is for smart contract to smart contract interaction (ie: Send Notification (via smart contract)), For this specific feature, the native blockchain address is required and not chain specific format.

  • Source - The source from which the notification is coming from. Currently supports ETH_MAINNET, POLYGON_MAINNET, BNB_MAINNET, ARB_MAINNET, THE_GRAPH, ETH_TEST_SEPOLIA ETH_TEST_GOERLI, POLYGON_TESTNET, BNB_TESTNET.

    Source is determined by the chain at which the user is inititialized from Push SDK, by the network it is coming from in case of smart contracts.

  • Recipient(s) - The address to the notification should reach. Push supports multiple address formats as depicted over here.

    Few examples:

    • Ethereum(Mainnet): eip155:1:<Address>
    • Ethereum(Sepolia): eip155:11155111:<Address>
    • Polygon(Mumbai): eip155:80001:<Address>
    caution

    One exception to address format support is for smart contract to smart contract interaction (ie: Send Notification (via smart contract)), For this specific feature, the native blockchain address is required. for example: 0x99A08ac6254dcf7ccc37CeC662aeba8eFA666666

Sending notification examples​

// userAlice.channel.send([recipients], {options?})
// to send a broadcast notification - pass '*' in recipients array
const broadcastNotif = await userAlice.channel.send(['*'], {
  notification: { title: 'test', body: 'test' },
});

// userAlice.channel.send([recipients], {options?})
// to send a targeted notification - pass that single wallet address in recipients array
const targetedNotif = await userAlice.channel.send(
  ['0x99A08ac6254dcf7ccc37CeC662aeba8eFA666666'],
  {
    notification: {
      title: 'test',
      body: 'test',
    },
  }
);

// userAlice.channel.send([recipients], {options?})
// to send a subset notification - pass the list of wallet address in recipients array
const subsetNotif = await userAlice.channel.send(
  [randomWallet1, randomWallet2, randomWallet3],
  {
    notification: {
      title: 'test',
      body: 'test',
    },
  }
);