Getting Started With Push SDK REST API

The PUSH-SDK, is a growing JavaScript-based SDK that allows developers to add push notification functionality to their dapps. Using the SDK, developers can:

Build PUSH features into their dapps
Get access to Push Nodes APIs
Render Push Notifications UI

It is written in Typescript and supports React, React Native, Plain JS, and Node JS-based platforms. (We are adding support for more!) It is also built on top of standard Web3 packages like ethers, @web3-react.

If you’re looking for our full documentation on Push-SDK REST API, you can find that here.

But for now, let’s walk you through the main features of the Push-SDK REST API and how to use them in your code.

Fetching user notifications

You can use the getFeeds method to fetch a user's notifications. This method takes an options object as an argument, which allows you to specify the following parameters:

user (mandatory, string): The user’s address in CAIP format.
page (optional, number): The page index of the results. Default is 1.
limit (optional, number): The number of items per page. Default is 10.
spam (optional, boolean): Whether to fetch spam notifications. Default is false.
env (optional, string): The API environment to use. Possible values are ‘prod’ and ‘staging’. Default is ‘prod’.
raw (optional, boolean): Whether to return the raw, unformatted API response. Default is false.

Here’s an example of how you might use the getFeeds method in your code:

const notifications = await PushAPI.user.getFeeds({
  user: 'eip155:5:0xD8634C39BBFd4033c0d3289C4515275102423681',
  env: 'staging'
});

In this example, we define a user address using the CAIP format. CAIP, or Chain Agnostic Improvement Proposal, is a way to describe standards for blockchain projects that are not specific to a single chain. It was developed by the Ethereum Improvement Proposal (EIP) process and is used to identify and encode information about Ethereum addresses, contract addresses, and other crypto-assets.

It is important to note that CAIP is not a standardized way of identifying and encoding information about crypto-assets; it is under development by the Ethereum community and is not yet widely adopted in the ecosystem.

CAIP addresses are composed of three parts:

The namespace: This is a string designed to uniquely identify a blockchain ecosystem or set of ecosystems as a namespace.
The network ID: This is an integer that identifies the Ethereum network the asset belongs to. For example, 1 is the main network, 3 is the Ropsten test network, and 5 is the Goerli test network.
The address: This is the actual address of the asset, encoded as a hexadecimal string.

For instance:

eip155:5:0xD8634C39BBFd4033c0d3289C4515275102423681

In this example, the namespace is eip155 which identifies EVM chains, the network ID is 5 (Goerli test network) and the address is

0xD8634C39BBFd4033c0d3289C4515275102423681

CAIP is designed to be flexible and extensible, allowing for the inclusion of additional information as needed. It is used by the Push Protocol and other Ethereum-based projects as a standardized way of identifying and encoding information about crypto-assets, and distinguishing information from different chains.

Continuing with getFeeds, to fetch spam notifications, set the spam parameter to true:

const spams = await PushAPI.user.getFeeds({
  user: 'eip155:5:0xD8634C39BBFd4033c0d3289C4515275102423681',
  spam: true,
  env: 'staging'
});

The getFeeds method returns a list of notifications for the specified user.

Fetching user subscriptions

You can use the getSubscriptions method to fetch a user's subscriptions. This method takes an options object as an argument, which allows you to specify the following parameters:

user (mandatory, string): The user’s address in CAIP format.
env (optional, string): The API environment to use. Possible values are ‘prod’ and ‘staging’. Default is ‘prod’.

Here’s an example of how you might use the getSubscriptions method in your code:

const subscriptions = await PushAPI.user.getSubscriptions({
  user: 'eip155:5:0xD8634C39BBFd4033c0d3289C4515275102423681',
  env: 'staging'
});

The getSubscriptions method returns a list of channels [{ channel: '0xaddress', ... }] subscribed by the user.

Fetching channel details

You can use the getChannel method to fetch information about a specific channel. This method takes an options object as an argument, which allows you to specify the following parameters:

channel (mandatory, string): The channel’s address in CAIP format.
env (optional, string): The API environment to use. Possible values are ‘prod’ and ‘staging’. Default is ‘prod’.

Here’s an example of how you might use the getChannel method in your code:

const channelData = await PushAPI.channels.getChannel({
  channel: 'eip155:5:0xD8634C39BBFd4033c0d3289C4515275102423681',
  env: 'staging'
});

The getChannel method returns an object with information about the channel.

Searching for channels

You can use the search method to search for channels based on a specified query. It takes an options object as an argument, which allows you to specify the following parameters:

query (mandatory, string): The search query.
page (optional, number): The page index of the results. Default is 1.
limit (optional, number): The number of items per page. Default is 10.
env (optional, string): The API environment to use. Possible values are ‘prod’ and ‘staging’. Default is ‘prod’.

Here’s an example of how you might use the search method in your code:

const channelsData = await PushAPI.channels.search({
  query: 'push',
  page: 1,
  limit: 20,
  env: 'staging'
});

The search method returns a list of channels that match the search criteria.

Opting into a channel

You can use the subscribe method to allow a user to opt into a specific channel. This method takes an options object as an argument, which allows you to specify the following parameters:

signer (mandatory, object): The object that signs the subscription transaction.
user (mandatory, string): The user’s address in CAIP format.
channel (mandatory, string): The channel’s address in CAIP format.
env (optional, string): The API environment to use. Possible values are ‘prod’ and ‘staging’. Default is ‘prod’.

Here’s an example of how you might use the subscribe method in your code:

await PushAPI.channels.subscribe({
  signer: _signer,
  user: 'eip155:5:0xD8634C39BBFd4033c0d3289C4515275102423681',
  channel: 'eip155:5:0xD8634C39BBFd4033c0d3289C4515275102423681',
    env: 'staging'
    });

The subscribe method returns a confirmation of the subscription.

Opting out of a channel

You can use the unsubscribe method to allow a user to opt out of a specific channel. This method takes an options object as an argument, which allows you to specify the following parameters:

signer (mandatory, object): The object that signs the unsubscription transaction.
user (mandatory, string): The user’s address in CAIP format.
channel (mandatory, string): The channel’s address in CAIP format.
env (optional, string): The API environment to use. Possible values are ‘prod’ and ‘staging’. Default is ‘prod’.

Here’s an example of how you might use the unsubscribe method in your code:

await PushAPI.channels.unsubscribe({
  signer: _signer,
  user: 'eip155:5:0xD8634C39BBFd4033c0d3289C4515275102423681',
  channel: 'eip155:5:0xD8634C39BBFd4033c0d3289C4515275102423681',
  env: 'staging'
});

The unsubscribe method returns a confirmation of the unsubscription.

Sending a notification

You can use the sendNotification method from the payloads object to send a direct payload notification to a specific recipient, group of recipients, or all recipients. This method takes an options object as an argument, which allows you to specify the following parameters:

signer (mandatory, object): The object representing the signer for the transaction.
type (mandatory, number): The type of recipient. Possible values are 1 (broadcast), 3 (single recipient), and 4 (group of recipients).
identityType (mandatory, number): The identity type of the recipient. Possible values are 2 (direct payload).
notification (mandatory, object): An object representing the notification.

title (mandatory, string): The title of the notification.
body (mandatory, string): The body of the notification.

payload (mandatory, object): An object representing the payload.

title (mandatory, string): The title of the payload. body (mandatory, string): The body of the payload.
cta (optional, string): The call-to-action of the payload.
img (optional, string): The image of the payload.

recipients (optional, string or array of strings): The recipient address(es) in CAIP format. Only required for type 3 (single recipient) or type 4 (group of recipients).
channel (mandatory, string): The channel’s address in CAIP format.
env (optional, string): The API environment to use. Possible values are ‘prod’ and ‘staging’. Default is ‘prod’.

Here are examples of how you might use the sendNotification method in your code:

Single recipient (target):

const apiResponse = await PushAPI.payloads.sendNotification({
  signer,
  type: 3, // target
  identityType: 2, // direct payload
  notification: {
    title: `[SDK-TEST] notification TITLE:`,
    body: `[sdk-test] notification BODY`
  },
  payload: {
    title: `[sdk-test] payload title`,
    body: `sample msg body`,
    cta: '',
    img: ''
  },
  recipients: 'eip155:5:0xD8634C39BBFd4033c0d3289C4515275102423681', // recipient address
  channel: 'eip155:5:0xD8634C39BBFd4033c0d3289C4515275102423681', // your channel address
  env: 'staging'
});

Group of recipients (subset):

const apiResponse = await PushAPI.payloads.sendNotification({
  signer,
  type: 4, // subset
  identityType: 2, // direct payload
  notification: {
    title: `[SDK-TEST] notification TITLE:`,
    body: `[sdk-test] notification BODY`
  },
  payload: {
    title: `[sdk-test] payload title`,
    body: `sample msg body`,
    cta: '',
    img: ''
  },
  recipients: ['eip155:5:0xD8634C39BBFd4033c0d3289C4515275102423681', 'eip155:5:0xCdBE6D076e05c5875D90fa35cc85694E1EAFBBd1'], // recipients addresses
  channel: 'eip155:5:0xD8634C39BBFd4033c0d3289C4515275102423681', // your channel address
  env: 'staging'
});

All recipients (broadcast):

const apiResponse = await PushAPI.payloads.sendNotification({
  signer,
  type: 1, // broadcast
  identityType: 2, // direct payload
  notification: {
    title: `[SDK-TEST] notification TITLE:`,
    body: `[sdk-test] notification BODY`
  },
  payload: {
    title: `[sdk-test] payload title`,
    body: `sample msg body`,
    cta: '',
    img: ''
  },
  channel: 'eip155:5:0xD8634C39BBFd4033c0d3289C4515275102423681', // your channel address
  env: 'staging'
});

The sendNotification method returns a confirmation (apiResponse) of the notification being sent, with a status code of 204 indicating success.

--
That’s it! You now know how to use the main features of the Push Protocol REST API to add push notification functionality to your application!

We’ll cover other parts of the Push SDK in coming posts so stay tuned!

Push Protocol SDK documentation here — if you’d like more reference material to chew on.
Push SDK on GitHub
Our Discord — we’ve got devs ready to give your project whatever support and consultation you need.

Blog