Getting Started With PUSH SDK uiweb API

The @pushprotocol/uiweb package is a collection of React components for building dapps that interact with the Push Protocol, web3's communication protocol. It includes components for rendering notifications, spam notifications, and forms for subscribing and unsubscribing to spam notification channels.

In this blog post, we'll take a closer look at the components included in the @pushprotocol/uiweb package and how you can use them in your dapp.

Components

NotificationItem

This component displays a single notification item. It takes the following props:

• notificationTitle (string): The title of the notification.
• notificationBody (string): The body of the notification.
• app (string): The name of the app that sent the notification.
• icon (string): The URL of an icon to display next to the notification title.
• image (string): The URL of an image to display in the notification.
• url (string): The URL to open when the notification is clicked.
• theme (string): The theme to use for the notification. Possible values are 'light' and 'dark'.
• chainName (string): The name of the blockchain the notification was sent on. Possible values are "ETH_TEST_GOERLI", "POLYGON_TEST_MUMBAI”.
• isSpam (boolean, optional): Set to true if the notification is spam.
• subscribeFn (function, optional): A function to call when the user clicks the "Opt-in" button on a spam notification.
• isSubscribedFN (function, optional): A function that returns a boolean indicating whether the user is subscribed to the spam notification's channel.

Example:

import { NotificationItem } from "@pushprotocol/uiweb";

function MydApp() {
  const notifications = [
    {
      title: "Notification 1",
      message: "This is the first notification",
      app: "My App",
      icon: "https://my-app.com/icon.png",
      image: "https://my-app.com/image.png",
      url: "https://my-app.com/notification-1",
      blockchain: "ETH_TEST_GOERLI"
    },
    {
      title: "Notification 2",
      message: "This is the second notification",
      app: "My App",
      icon: "https://my-app.com/icon.png",
      image: "https://my-app.com/image.png",
      url: "https://my-app.com/notification-2",
      blockchain: "ETH_TEST_GOERLI"
    }
  ];

  return (
    <div>
      {notifications.map((notification, i) => (
        <NotificationItem
          key={i}
          notificationTitle={notification.title}
          notificationBody={notification.message}
          app={notification.app}
          icon={notification.icon}
          image={notification.image}
          url={notification.url}
          theme={{ background: "blue", color: "white" }}
          chainName={notification.blockchain}
        />
      ))}
    </div>
  );
}

The Notification Item component can also be used to render spam notifications. To get the spam data, you can use the PushAPI.user.getFeeds() method with the spam parameter set to true.

The NotificationItem component is a general-purpose component that can be used to render any type of notification item, including spam notifications. It accepts props such as notificationTitle, notificationBody, cta, app, icon, image, and url to customize the appearance and behavior of the component.

The Spam component is a specialized variant of the NotificationItem component that is specifically designed for rendering spam notifications. It includes additional props such as isSpam, subscribeFn, and isSubscribedFn that allow the user to interact with the spam notification channel. It also includes an unsubscribe form that is displayed if the user is subscribed to the spam notification channel.

You can use the PushAPI.user.getFeeds() method with the spam parameter set to true to get the spam data. Here's an example of how you can use it:

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

To render the Notification Item component for each spam notification, you'll need to pass in the additional props isSpam, subscribeFn, and isSubscribedFn.

• isSpam: A boolean value indicating whether the notification is a spam notification
• subscribeFn: A function that opts the user in to the spam notification's channel
• isSubscribedFn: A function that returns a boolean value indicating whether the user is subscribed to the spam notification's channel

Here’s an example of how you can render the Notification Item component for each spam notification:

{spams.map((oneNotification, i) => {
  const { 
    cta,
    title,
    message,
    app,
    icon,
    image,
    url,
    blockchain,
    secret,
    notification
  } = oneNotification;

return (
    <NotificationItem
      key={`spam-${i}`}
      notificationTitle={title}
      notificationBody={message}
      cta={cta}
      app={app}
      icon={icon}
      image={image}
      url={url}
      theme={theme}
      chainName={blockchain}
      isSpam={true}
      subscribeFn={subscribeFn}
      isSubscribedFn={isSubscribedFn}
    />
  );
})}

To implement the subscribeFn and isSubscribedFn functions, you can use the PushAPI.channel.subscribe() and PushAPI.channel.subscriptions() methods from @pushprotocol/restapi package, respectively.

Here’s an example of how you can implement these functions:

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

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

Putting it all together

Here is an example using subscribeFn that demonstrates the uiweb components used together.

import React, { useState, useEffect } from "react";
import { NotificationItem, chainNameType } from "@pushprotocol/uiweb";

function MydApp() {
  const [notifications, setNotifications] = useState([]);
  useEffect(() => {
    const fetchNotifications = async () => {
      // fetch user notifications using the PushAPI
      const notifications = await PushAPI.user.getFeeds({
        user: 'eip155:5:0xD8634C39BBFd4033c0d3289C4515275102423681', // user address in CAIP
        env: 'staging'
      });
      setNotifications(notifications);
    };
    fetchNotifications();
  }, []);
  return (
    <div>
      <h1>MydApp</h1>
      <h2>Notifications</h2>
      {notifications.map((notification, i) => {
        const {
          title,
          message,
          app,
          icon,
          image,
          url,
          blockchain
        } = notification;
        return (
          <NotificationItem
            key={i}
            notificationTitle={title}
            notificationBody={message}
            app={app}
            icon={icon}
            image={image}
            url={url}
            theme={theme}
            chainName={blockchain as chainNameType}
          />
        );
      })}
    </div>
  );
}

MydApp is a component that renders a list of notifications and spam notifications, as well as a form for subscribing to or unsubscribing from spam notifications. It uses the following components from the @pushprotocol/uiweb package:

• NotificationItem: A React component for rendering a single notification item.
• Spam: A React component for rendering a single spam notification item, with options for subscribing or unsubscribing to the spam notification channel.
• Subscribe: A React component for rendering a form for subscribing to a spam notification channel.
• Unsubscribe: A React component for rendering a form for unsubscribing from a spam notification channel.

MydApp uses the useState and useEffect Hooks to fetch and display the user's notifications and spam notifications using the PushAPI. It also defines event handlers for subscribing to and unsubscribing from spam notifications.

MydApp returns a JSX element that contains the following elements:

• A div element with a h1 element for the title of the application and a h2 element for the section heading for the notifications.
• A loop that renders a NotificationItem component for each notification in the notifications array.
• A h2 element for the section heading for the spam notifications.
• A loop that renders a Spam component for each spam notification in the spamNotifications array.
• A h2 element for the section heading for the subscription form.
• An Unsubscribe component if the user is subscribed to spam notifications, or a Subscribe component if the user is not subscribed to spam notifications.

There are of course other React components that you can to compliment the uiweb API. For instance: the Feed component is a container for displaying a list of notifications in a UI. It takes the following props:

• notifications (array of Notification objects): An array of notifications to be displayed in the feed. Each Notification object should have the following shape:
• cta (string): The call-to-action text for the notification.
• title (string): The title of the notification.
• message (string): The body of the notification.
• app (string): The name of the app that sent the notification.
• icon (string): The URL of an icon to be displayed with the notification.
• image (string): The URL of an image to be displayed with the notification.
• url (string): The URL to be opened when the notification is clicked.
• blockchain (string): The name of the blockchain on which the notification was sent.
• theme (Theme object): An object defining the colors and styles to be used in the feed. The Theme object should have the following shape:
• background (string): The background color of the feed.
• color (string): The text color of the feed.
• chainName (string): The name of the blockchain to be displayed in the feed.

Example:

import NotificationItem from "@pushprotocol/uiweb/NotificationItem";
import Feed from "./Feed"; // User-implemented component

const notifications = [
  {
    cta: "Learn More",
    title: "Notification 1",
    message: "This is the first notification",
    app: "My App",
    icon: "<https://my-app.com/icon.png>",
    image: "<https://my-app.com/image.png>",
    url: "<https://my-app.com/notification-1>",
    blockchain: "Ethereum"
  },
  {
    cta: "Get Started",
    title: "Notification 2",
    message: "This is the second notification",
    app: "My App",
    icon: "<https://my-app.com/icon.png>",
    image: "<https://my-app.com/image.png>",
    url: "<https://my-app.com/notification-2>",
    blockchain: "Ethereum"
  }
];
function MydApp() {
  return (
    <Feed
      notifications={notifications}
      theme={{ background: "blue", color: "white" }}
      chainName="Ethereum"
    />
  );
}

That’s it! You now know how to use the components of the @pushprotocol/uiweb 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

Comments

[Pratik Mondal]

Great breakdown of the @pushprotocol/uiweb API! 🔥 This guide makes it so much easier for devs to integrate Push notifications into their dapps seamlessly. Can’t wait to see how this SDK continues to evolve! 👏