[TMF] Use the ManiaHome PHP Library

Discuss all the publishing tools, including ManiaHome, ManiaPub, ManiaFlash and ManiaPress in this forum

Moderator: NADEO

User avatar
gouxim
Nadeo
Nadeo
Posts: 1188
Joined: 14 Jun 2010, 17:20

[TMF] Use the ManiaHome PHP Library

Post by gouxim » 19 Apr 2011, 18:12

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
Please do not PM for support. Instead, create a thread so that everyone can contribute or benefit from the answer! 8-)

User avatar
musterman
Posts: 176
Joined: 15 Jun 2010, 18:07
Location: france/picardie/somme
Contact:

Re: HOW TO - Use the ManiaHome PHP Library

Post by musterman » 19 Apr 2011, 18:25

Thank you will try to have all its

User avatar
gouxim
Nadeo
Nadeo
Posts: 1188
Joined: 14 Jun 2010, 17:20

Re: HOW TO - Use the ManiaHome PHP Library

Post by gouxim » 20 Apr 2011, 11:34

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
Please do not PM for support. Instead, create a thread so that everyone can contribute or benefit from the answer! 8-)

User avatar
fastforza
Posts: 859
Joined: 15 Jun 2010, 11:19
Contact:

Re: HOW TO - Use the ManiaHome PHP Library

Post by fastforza » 20 Apr 2011, 13:16

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.
Mania Exchange - Share your maps!

ASUS Maximus IV GENE Z / i7 2600K 3.40Ghz QC / 16GB G.Skill Ripjaws DDR3 / GTX 560 Ti

Need technical help for ManiaPlanet? Click here. :)

User avatar
gouxim
Nadeo
Nadeo
Posts: 1188
Joined: 14 Jun 2010, 17:20

Re: HOW TO - Use the ManiaHome PHP Library

Post by gouxim » 20 Apr 2011, 13:18

fastforza wrote: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.
Please do not PM for support. Instead, create a thread so that everyone can contribute or benefit from the answer! 8-)

User avatar
fastforza
Posts: 859
Joined: 15 Jun 2010, 11:19
Contact:

Re: HOW TO - Use the ManiaHome PHP Library

Post by fastforza » 20 Apr 2011, 13:24

It should be straightforward, CURL is essentially a WebRequest anyway. :P I'll see what I can do and test.
Mania Exchange - Share your maps!

ASUS Maximus IV GENE Z / i7 2600K 3.40Ghz QC / 16GB G.Skill Ripjaws DDR3 / GTX 560 Ti

Need technical help for ManiaPlanet? Click here. :)

arttrain
Posts: 1
Joined: 23 Apr 2011, 06:45

Re: [HOW-TO] Use the ManiaHome PHP Library

Post by arttrain » 23 Apr 2011, 06:48

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

User avatar
gouxim
Nadeo
Nadeo
Posts: 1188
Joined: 14 Jun 2010, 17:20

Re: [HOW-TO] Use the ManiaHome PHP Library

Post by gouxim » 23 Apr 2011, 17:45

arttrain wrote: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
Please do not PM for support. Instead, create a thread so that everyone can contribute or benefit from the answer! 8-)

User avatar
gouxim
Nadeo
Nadeo
Posts: 1188
Joined: 14 Jun 2010, 17:20

Re: [HOW-TO] Use the ManiaHome PHP Library

Post by gouxim » 13 Jun 2011, 17:23

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());
}

?>
Please do not PM for support. Instead, create a thread so that everyone can contribute or benefit from the answer! 8-)

User avatar
jonthekiller
Translator
Translator
Posts: 4655
Joined: 15 Jun 2010, 11:07
Location: In Maniaplanet Alpha
Contact:

Re: [HOW-TO] Use the ManiaHome PHP Library

Post by jonthekiller » 09 Oct 2011, 13:16

This library works on ManiaPlanet yet?
Image

Post Reply

Return to “Ingame Publishing”

Who is online

Users browsing this forum: No registered users and 2 guests