Notification API

From Neuron Interactive

If you game supports OpenID, you can implement our Notification API. This API is build by special OpenID providers and allow you to send messages and updates to your players. This is a very powerful tool, especially with providers that build a bridge between a social network and your game (for example: browser games enable players to play your game trough facebook).

The OpenID provider will receive and handle your notification, posting it to the social network or just showing users a list of their notifications.

Receiving Notification URL

When a user logs in using the OpenID of one of these special providers, an additional parameter is sent using the Attribute Exchange OpenID extension. This parameter will have type "http://www.browser-games-hub.org/schema/openid/notify_url.xml" and will contain an anyURI element.

This URL should contain a user ID and a secret key. This key should be unique for every game and user and can be updated without further notice. This means that your game should check if the URL is updated every time the user logs in, so not only on registration!

API Notification Calls

When you have received the personal notification URL, you are ready to start posting notification. Mind that SPAM and notifications are completely unrelated. Security and notification limits are managed by the providers. However, I'm sure everyone knows when a notification is spam and when it isn't.

The Notification API must receive all data in POST values.

These notifications must contain the following fields:

• notification_text, a plaintext explanation in the language of the user. If your game is not localised, use your games language.
• notification_date in xs:dateTime format

Additionally, a post variable notification_xml can be used to define a more advanced notification. This field is optional, if not present, the plaintext notification_text should be displayed.

However, the notification_xml contains more information about the users involved and allow the provider to customise the notification.

notification_xml example:

<?xml version="1.0" encoding="UTF-8"?>
<notification version="1" visibility="private">
	<id>received</id>
	<group>messsage</group>
	<text>You have received a message from Daedeloth.</text>
	<skeleton>You have received a message from {0}.</skeleton>
	<arguments>
		<argument type="user">
			<value>Daedeloth</value>
			<name>Daedeloth</name>
			<openids>
				<openid hash="md5">de0f3dcc69a3078fb98d66527d486747</openid>
			</openids>
		</argument>
	</arguments>
	<target>
		<name>Timmy</name>
		<openids>
			<openid hash="md5">a456c7894567895a45634db48795123a</openid>
		</openids>
	</target>
	<sender>
		<name>Daedeloth</name>
		<openids>
			<openid hash="md5">de0f3dcc69a3078fb98d66527d486747</openid>
		</openids>
	</sender>
</notification>

So, what is all this?

• attribute visibility can be 'private' (if you want to notify only the user) or 'public' (if everyone may read it). Public notifications shouldn't really be thought of as notifications, but more like news messages.
• id and group are used to identify this notification. This way, users can filter out all notification from one group (for example: who cares about when you have logged in)
• text should contain a plaintext version of the notification
• A skeleton is the plaintext, with placekeepers for extra information. In this example, {0} will be replaced with username daedeloth, the first element in the argument list.
• arguments contain a list of argument elements. A value of type user has to contain a name and a list of openids, used to identify the user with the provider. This information is hashed for privacy purpose.
• target contains data about the user who is receiving this notification.
• sender contains data about the user who is sending this notification. This is optional, since some notifications are not user to user.

Public (news) messages

Public messages can be read by other people, in most cases the friends of the target and sometimes even everyone. Public messages should always be in 3rd person and should start with the targets name. Therefore, the tag {target} must be used in the skeleton.

The target in Public Messages is always the person performing the action or event. Thus, the {target} tag is the name of the person whose profile is performing the action. Example: "John is attacking another player.", John is the target, as the message will be published on his profile.

<?xml version="1.0" encoding="UTF-8"?>
<notification version="1" visibility="public">
	<id>battle</id>
	<group>attack</group>
	<text>Timmy has attacked Daedeloth.</text>
	<skeleton>{target} has attacked {0}.</skeleton>
	<arguments>
		<argument type="user">
			<value>Daedeloth</value>
			<name>Daedeloth</name>
			<openids>
				<openid hash="md5">de0f3dcc69a3078fb98d66527d486747</openid>
			</openids>
		</argument>
	</arguments>
	<target>
		<name>Timmy</name>
		<openids>
			<openid hash="md5">a456c7894567895a45634db48795123a</openid>
		</openids>
	</target>
</notification>