Getting Started With PUSH SDK uiweb API
Tags: web3, api, blockchain, beginners
Published: 2023-02-22 06:28:11

The `@pushprotocol/uiweb` package is a collection of React components for building dapps that interact with the [Push Protocol](https://push.org/), 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](https://docs.push.org/developers/developer-tooling/push-sdk) — if you’d like more reference material to chew on.

- Push SDK on [GitHub](https://github.com/ethereum-push-notification-service/push-sdk)