Client

Server

In-app Notifications

In-app notifications make it easy to broadcast a message to one or more users. They are great for sending announcements, alerts, or notices of in-game rewards and gifts.

A notification can be stored until read when the app is next opened or it can be pushed so only a connected user will see it. You can also use notifications to trigger custom actions within your game and change client behavior.

These notifications are viewed within the app which makes them a great companion to push notifications viewed outside the app.

Send notifications

You can send a notification to one or more users with server-side code. It can be sent to any user in the game - there’s no need to be friends to be able to exchange messages. A number of notifications are also sent by the server implicitly on certain events.

Each notification has a code which is used to categorize it. The code you choose for your notifications must start at 0 and increase upwards. See below for reserved message codes.

A notification has a content object which will be encoded as JSON.

Notifications can be marked as persistent when sent. A non-persistent message will only be received by a client which is currently connected to the server (i.e. a user who is online). If you want to make sure a notification is never lost before it’s read, it should be marked as persistent when sent.

Receive notifications

A callback can be registered for notifications received when a client is connected. The handler will be called whenever a notification is received as long as the client socket remains connected. When multiple messages are returned (batched for performance) the handler will be called once for each notification.

List notifications

You can list notifications which were received when the user was offline. These notifications are ones which were marked “persistent” when sent. The exact logic depends on your game or app but we suggest you retrieve notifications after a client reconnects. You can then display a UI within your game or app with the list.

A list of notifications can be retrieved in batches of up to 100 at a time. To retrieve all messages you should accumulate them with the cacheable cursor. You can keep this cursor on the client and use it when the user reconnects to catch up on any notifications they may have missed while offline.

You will usually want to list only 100 notifications at a time, otherwise you might cause user fatigue. A good solution could be to have the UI fetch the next 100 notifications when the user scrolls to the bottom of your UI panel.

It can be useful to retrieve only notifications which have been added since the list was last retrieved by a client. This can be done with the cacheable cursor returned with each list message. Sending the cursor through a new list operation will retrieve only notifications newer than those seen.

The cacheable cursor marks the position of the most recent notification retrieved. We recommend you store the cacheable cursor in device storage and use it when the client makes its next request for recent notifications.

Delete notifications

You can delete one or more notifications from the client. This is useful to purge notifications which have been read or consumed by the user and prevent a build up of old messages. When a notification is deleted all record of it is removed from the system and it cannot be restored.

Notification codes

The server reserves all codes that are less than or equal to 0 for messages sent implicitly on certain events. You can define your own notification codes by simply using values greater than 0.

The code is useful to decide how to display the notification in your UI.

Code	Purpose
0	Reserved
-1	Message received from user X while offline or not in channel.
-2	User X wants to add you as a friend.
-3	User X accepted your friend invite.
-4	You’ve been accepted to X group.
-5	User X wants to join your group.
-6	Your friend X has just joined the game.
-7	Final notifications to sockets closed via the single_socket configuration.
-8	You’ve been banned.