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.
Top comments (1)
This blog is a fantastic starting point for developers looking to integrate push notifications into their dApps using the Push Protocol SDK. The breakdown of features like fetching user notifications, subscriptions, and sending notifications is clear and well-illustrated with practical code examples.
Looking forward to seeing more features and use cases in future posts—this SDK has the potential to become a standard for decentralized communication! 🚀