[TMF] Use the ManiaHome PHP Library

[gouxim]

Latest ManiaHome SDK version
1.01, April 20th

With the new version of ManiaHome just released, we also updated the ManiaHome PHP Library. It's now easier to use and hopefully many community services will interact with ManiaHome.

The ManiaHome PHP Library allows you to post notifications to ManiaHome, more precisely you can:

Post a notification to everyone who bookmarked your Manialink
eg. "Keep your fans posted about new updates on your Manialink or your Website"

Post a public notification to a Player
eg. "Tell to someone's buddies that he just uploaded a track on ManiaSpace, or beat a World record, etc."

Post a private notification to a Player
eg. "Information that is no need to be public, for example 'Your ad has been validated on ManiaPub'."

In this how-to, we'll see how to integrate ManiaHome notification posting into your system. It's very easy and does not require any particular skill (except basic PHP skills that you should already have if you are reading this...).

1 - Requirements

In order to use the ManiaHome library you need a few things.
* PHP 5.2
* CURL extension http://php.net/manual/en/book.curl.php
* JSON extension http://php.net/manual/en/book.json.php
* Your Web Server must be configured to that you can make HTTPS requests to external servers (namely api.maniastudio.com)

2 - Create an API user

In order to communicate with our API, you will need an API user. To do that:

* Head to http://developers.trackmania.com
* Login with your TrackMania account
* Go to API > Create new API user

3 - Register your Manialink on ManiaHome

You need to register your Manialink so you can post notifications, and you need to allow the API user you just created to post notifications for that Manialink. To do that:

Launch TrackMania
Go to maniahome
Go to Options > Manager > Your Manialink > Add a Manialink
Note: you need to be the owner of the Manialink!
On the "API username" page, select in the list the API user you created at step 2.

4 - Download the ManiaHome PHP Library

Download the latest version of the ManiaHome SDK at:
http://code.google.com/p/manialib/downloads/list

5 - Basic usage

Put the file "maniahome.php" in your project, so you can include it where you want to use it.
The code to use could not be simplier, so let's take a look at a quick example:

Code: Select all

require_once '/path/to/maniahome.php';

$maniahome = new ManiaHome('your_manialink', 'api_username', 'api_password');

 // To everyone who bookmarked your manialink:
 $maniahome->sendNotificationFromManialink('Hello world');
 
 // Public notification to a player:
 $maniahome->sendPublicNotificationToPlayer('player_login', 'rocks!');
 
 // Private notification to a player:
 $maniahome->sendPrivateNotificationToPlayer('player_login', 'This is a private message for you');

6 - Advanced usage

Error handling

All the methods to send notifications return true on success, false on failure. You can check errors like that:

Code: Select all

if( ! $maniahome->sendNotificationFromManialink('Lorem ipsuml dolor sit amet') )
{
	echo 'ERROR: ' . $maniahome->lastResponse;
}

Send a notification to a player with a custom Icon

The methods to send notifications have several optional parameters. Look at the code for more information. Let's however do a little example (note that it does not work on private notifications!) :

Code: Select all

$maniahome->sendPublicNotificationToPlayer('player_login', 'rocks!', 'Icons128x128_1', 'Solo');

Choose your Icons wisely. You can see the available styles and substyles on this page:

http://fish.stabb.de/styles/

Hope it helps!

Appendix - SDK changelog

1.01 - April 20th 2011
- Fixed bug when posting notifications with Icons style+substyle

1.0 - April 19th 2011
+ Initial release

[musterman]

Thank you will try to have all its

[gouxim]

We just updated the SDK, fixing a bug when posting a notification with icons style+substyle. You can download the updated version and override the "maniahome.php" file.

http://code.google.com/p/manialib/downloads/list

[fastforza]

Any future website possibilities for this or is this an ingame only feature? For example, I could probably an ASP.NET version and integrate it with TMX.

[gouxim]

Any future website possibilities for this or is this an ingame only feature? For example, I could probably an ASP.NET version and integrate it with TMX.

Well it's just a PHP library that does some http requests so it definitely will work if you integrate with a website. It'd be very nice too see TMX integration on ManiaHome

As for the ASP.NET version, I guess it can be done quite easily since the code of the PHP lib is pretty straightforward.

[fastforza]

It should be straightforward, CURL is essentially a WebRequest anyway. I'll see what I can do and test.

[arttrain]

thats a great tutorial, but how am i going to position the image file on my manialink?

[gouxim]

thats a great tutorial, but how am i going to position the image file on my manialink?

Are you talking about positioning the bookmark button? If so, you can check my last post in the dedicated topic:

http://forum.maniaplanet.com/viewtopic. ... 768#p16768

[gouxim]

The ManiaHome class is now integrated in the TrackMania Web Services SDK for PHP. I will deprecate the current lib and update the documentation accordingly in a few days. It should hardly change anything in your current code anyway.

In the meantime here's some info for the more curious of you:

* Download link: http://code.google.com/p/trackmania-ws- ... loads/list
* The file to require is now called "trackmania-ws.php"
* Error handling has changed. "$maniahome->lastException" contains an exception if one of the sendXxxx() methods returned false.
* A batch script to test the posting of notification on ManiaHome is included as an example in the SDK. See: http://code.google.com/p/trackmania-ws- ... iahome.php

Here's a quick code example, inspired from the file above

Code: Select all

<?php
require_once '/path/to/trackmania-ws.php';

$username = 'your_api_username';
$password = 'your_api_password';
$manialink = 'your_manialink';

$maniahome = new ManiaHome($username, $password, $manialink);

// To everyone who bookmarked your manialink:
if( ! $maniahome->sendNotificationFromManialink('Hello world') )
{
   // In case of error we print debug information
   $e = $maniahome->lastException;
   printf("HTTP Response: %d %s\n", $e->getHTTPStatusCode(), $e->getHTTPStatusMessage());
   printf("API Response: %s (%d)\n", $e->getMessage(), $e->getCode());
}

?>

[jonthekiller]

This library works on ManiaPlanet yet?