Getting Started with Push SDK: Socket API🔔

The Socket API is a package that helps you connect to the Push backend using WebSockets, built on top of Socket.IO. With this API, you can easily subscribe to real-time notifications and updates from the Push network.

In this article, we’ll go over the PUSH-SDK Socket API and how to use it in your dApp.

caution

Socket API is deprecated. Push has revamped it's socket API into stream API which is more versatile and developer friendly, click on the link below to learn more 👇.

Learn about Push Stream API

Note on Addresses

In any of the specified methods (unless explicitly stated otherwise), you can use either CAIP format (specifically CAIP-10) or the ETH address format.

Recall that 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. For example, an ETH mainnet address would be in the form:

eip155:1:0xab16a96d359ec26a11e2c2b3d8f8b8942d5bfcdb

The sockets API uses CAIP-10 (but defaults to the Ethereum address format), which is a specific proposal within the CAIP specification that focuses on the identification of blockchain addresses. It defines a format for representing addresses in a way that is both chain-agnostic and human-readable.

The ETH address format is supported for backwards compatibility. For example, an ETH mainnet address would be in the form 0xab16a96d359ec26a11e

Creating a Socket Connection

To create a socket connection, you’ll need to create a socket connection object.

createSocketConnection(options: SocketConnectionOptions): SocketConnection

You can use the createSocketConnection method to create a socket connection object. This method takes an options object as an argument, which allows you to specify the following parameters:

• user (string, required): The user account address, in CAIP format.
• env (string, optional, default: 'prod'): The API environment to connect to. Can be 'prod', 'staging', or 'dev'.
• socketOptions (object, optional): Options to pass to SocketIO.

This method returns a SocketConnection object that you can use to connect, disconnect, and subscribe to events.

For Notifications

To create a socket connection for notifications, you’ll need to create a socket connection object.

const pushSDKSocket = createSocketConnection({
  user: 'eip155:11155111:0xab16a96d359ec26a11e2c2b3d8f8b8942d5bfcdb', // CAIP-10 format
  env: 'staging',
  socketOptions: { autoConnect: false },
});

For Push Chat

To create a socket connection for chat, you should define the socket type as “chat” when instantiating the socket client. The user address can be in any format, including non-CAIP-10 formats.

const pushSDKSocket = createSocketConnection({
  user: '0xFd6C2fE69bE13d8bE379CCB6c9306e74193EC1A9',
  env: 'staging',
  apiKey:
    'jVPMCRom1B.iDRMswdehJG7NpHDiECIHwYMMv6k2KzkPJscFIDyW8TtSnk4blYnGa8DIkfuacU0',
  socketType: 'chat',
  socketOptions: { autoConnect: true, reconnectionAttempts: 3 },
});

This method takes an options object as an argument, which allows you to specify the following parameters:

• user (string, required): The user account address.
• env (string, optional, default: 'prod'): The API environment to connect to. Can be 'prod', 'staging', or 'dev'.
• apiKey (string, optional): The API key to use for authentication.
• socketType (string, optional, default: 'notification'): The type of socket connection to create. Can be 'notification' or 'chat'.
• socketOptions (object, optional): Options to pass to SocketIO.

This method returns a SocketConnection object that you can use to connect, disconnect, and subscribe to events.

Connecting and Disconnecting

Once you have a SocketConnection object, you can use the connect and disconnect methods to establish or close the connection:

SocketConnection.connect(): void

Use the connect method to establish a connection to the backend.

SocketConnection.disconnect(): void

Use the disconnect method to close the connection to the backend.

Subscribing to Events

Once you have a connection, you can subscribe to events to receive updates in real-time.

SocketConnection.on(event: SocketEvent, callback: (data: any) => void):

Use the on method to subscribe to a socket event. This method takes an event name and a callback function as arguments. The callback function will be called whenever the specified event is triggered.

The following events are supported:

• EVENTS.CONNECT: Triggered when the socket connection is established.
• EVENTS.DISCONNECT: Triggered when the socket connection is closed.
• EVENTS.USER_FEEDS: Triggered when a new notification is received by the user after the last socket connection.
• EVENTS.USER_SPAM_FEEDS: Triggered when a new spam notification is received by the user after the last socket connection.
• EVENTS.CHAT_RECEIVED_MESSAGE: Triggered when a new chat message is received.

Example:

const pushSDKSocket = createSocketConnection({
  user: 'eip155:11155111:0xab16a96d359ec26a11e2c2b3d8f8b8942d5bfcdb',
  env: 'staging',
  socketOptions: { autoConnect: false },
});
pushSDKSocket.connect();
pushSDKSocket.on(EVENTS.CONNECT, () => {
  console.log('Connected to socket!');
});
pushSDKSocket.on(EVENTS.DISCONNECT, () => {
  console.log('Disconnected from socket!');
});
pushSDKSocket.on(EVENTS.USER_FEEDS, (feedItem) => {
  console.log(`Received notification: ${feedItem.title}`);
});
pushSDKSocket.on(EVENTS.USER_SPAM_FEEDS, (feedItem) => {
  console.log(`Received spam notification: ${feedItem.title}`);
});
pushSDKSocket.on(EVENTS.CHAT_RECEIVED_MESSAGE, (message) => {
  console.log(`Received chat message: ${message.text}`);
});

. . .

That’s it! You now know how to use the main features of the Push Protocol Socket 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.
• Push developer docs to get started on building right away!

#PoweredbyPush