Stability: 2 - Unstable


Hydra and the client SDKs implement a notification system that lets gamers know about relevant, and potentially time-sensitive, game and player events. Example events include: achievements awarded, matches updated, players joining and leaving matches, broadcast messages triggering on the timeline. The specifics about when these notifications are sent will be documented on the individual feature pages. This document covers some of the higher level concepts.

The Hydra notification system is an abstraction over platform specific delivery mechanisms. This means that there are unified APIs in the client SDKs for developers to hook into regardless of delivery mechanism. For any given notification, a delivery mechanism is chosen that is appropriate to the notification type and the client’s connection and capabilities.

There are several features that allow specifying notification settings. The following options are available:

Delivery Types :
The channels to send the notification over.
Persistence :
Notifications marked as persistent will be stored in Hydra until the client deletes them or they expire. Notifications that are not marked persistent will be lost if they’re not successfully delivered to the client.
Duration :
(Only applies if notification is marked as persistent) The number of hours after creation that a notification will expire.

Notifications that aren’t configurable have an expiration of 7 days.

Delivery Types

We provide several ways to receive Hydra notifications in your game.


Clients that are connected to Hydra’s realtime messaging servers may receive notifications via this connection. Notifications sent via this mechanism are delivered very quickly, making this mechanism appropriate for cases where notifications are sent at higher frequencies. The realtime messaging connection also provides player presence information that may be used for various purposes (e.g. player matchmaking, etc.).

Android (GCM)

Hydra can send notifications via Google’s Cloud Messaging system. In order to use this delivery mechanism, you need to setup an application on Google servers and supply Hydra with the API key and project number - we handle the rest. These notifications are delivered fairly quickly, but not as quickly as our realtime messaging system. One key advantage of this mechanism is that players will receive GCM notifications even if they are not in the game on their Android device.


Hydra can send notifications via Apple’s Push Notification Service. In order to use this delivery mechanism, see the iOS iOS Push Notifications guide. Notifications sent via APNS will generally be delivered quickly, on par with GCM. Again, as with GCM, notifications sent via APNS will be delivered even if your players are not in the game on their iOS device.


As a fallback, we offer the ability to poll for new messages. This will be the slowest way to retrieve notifications and the player will need to be in the game. The benefit is that this will work on all platforms even if no native push notification or realtime connection is available.

Each SDK automatically retrieves unread notifications during Client startup, but you can retrieve notifications at any time.


When a persistent notification is first generated, it is unread and not consumed. You can retrieve all notifications or just unread ones. You can mark individual notifications as read.


Each notification has a consumed flag that can be set once and only once. Subsequent attempts to mark the same notification as consumed will result in an error. Consuming a notification has no meaning in Hydra. It is up to you to implement any actions that happen when a notification is consumed. You may be able to handle this in the game client but many cases are better handled using the beforeConsume and afterConsume Server Side Code event hooks.

Table Of Contents

Previous topic


Next topic

Server Side Code