[beta] SDK 2.0 with Namespaces and OAuth2 support!

Trackmania Forever public API and its open source PHP SDK.

Moderator: NADEO

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

[beta] SDK 2.0 with Namespaces and OAuth2 support!

Post by gouxim »

Hi fellow coders,

We are releasing a new version of the SDK, so let's make a quick beta phase first. If you are using the 1.0 release of the SDK, it will still work as the API hasn't changed.

What has changed?
  • It now uses namespaces, so you need PHP 5.3. The project now has the same architecture as ManiaLib and ManiaLive so it's easy to mix the 3 of them.
  • OAuth 2.0 (experimental) support. That's a big thing ; it allows authentication via TMF account on both Websites and Manialinks, and it allows third party apps to access private information such as email etc. More on that later.
Download link

http://code.google.com/p/trackmania-ws- ... loads/list

How to migrate from 1.0 to 2.0

It's really simple. Let's look at an example.

This is the basic example from the 1.0 release:

Code: Select all

<?php
require_once '/path/to/trackmania-ws.php';
$tmPlayers = new TrackMania_Players('your_api_username', 'your_api_password');
$player = $tmPlayers->get('gou1');
?>
This is the same example for the 2.0 release:

Code: Select all

<?php
require_once '/path/to/autoload.php';
$tmPlayers = new \TrackMania\WebServices\Players('your_api_username', 'your_api_password');
$player = $tmPlayers->get('gou1');
?>
Basically only two things have changed:

The require statement:

Code: Select all

require_once '/path/to/trackmania-ws.php';
becomes:

Code: Select all

require_once '/path/to/autoload.php';
The class names:

Code: Select all

new TrackMania_Players();
new TrackMania_Xxxx();
new ManiaHome();
become:

Code: Select all

new \TrackMania\WebServices\Players();
new \TrackMania\WebServices\Xxxx();
new \TrackMania\WebServices\ManiaHome();
All the return types remain the same.

OAuth 2.0

Introduction

Today we are introducing OAuth2.0 support on the TrackMania Web Services API! Here's two quotes that describe what OAuth does:

http://oauth.net/
An open protocol to allow secure API authorization in a simple and standard method from desktop and web applications.
http://en.wikipedia.org/wiki/OAuth
OAuth (Open Authorization) is an open standard for authorization. It allows users to share their private resources (e.g. photos, videos, contact lists) stored on one site with another site without having to hand out their credentials, typically username and password.
OAuth 2.0 is a standard protocol and is thuss beeing adopted by more and more API providers such as Facebook, Google, Microsoft, Twitter, etc. We believe that providing such technology on our API will help the community build better applications by providing well known & standardized building blocks.

Let's imagine a few use cases for TrackMania. With OAuth 2.0 you will be able to:
  • Securely authentify someone with his TrackMania Forever account on your Website or your Manialink
  • Get access to protected information, provided the player gave your application the permission to do so ; for example you will be able to access the list of buddies, the online status, and maybe even the email.
  • "Do stuff" on behalf of the player (once again, provided he gave you the permission), for example posting a notification on ManiaHome as if the player was posting it himself.
Example

Here's how it works (the code of this example is in the SDK under /example/oauth2/basic/index.php)

First you go the page, and you're not logged in yet. So you have a "log-in link" (we will provide an official login button later if you want to use a button).
OAuth2 example screenshot 1
OAuth2 example screenshot 1
oauth2-example-screen1.png (5.75 KiB) Viewed 6176 times
When you click on the link, if you are not already logged-in on the player page, you are asked to do so. This is the authentication part.
OAuth2 example screenshot 2
OAuth2 example screenshot 2
Then the player is asked to give his permission. The application can request different permissions (basic, buddies, email, etc.). This is the authorization part.
OAuth2 example screenshot 3
OAuth2 example screenshot 3
When the player accepts, he's redirected to the application. Using the API, the application can retrieve a player object in a secure way (if the login is "gou1", the application is sure that it's actually that player).
OAuth2 example screenshot 4
OAuth2 example screenshot 4
After that, the application have an access token that can be used to call different services.

How to create an OAuth2 application?
  • Go to http://developers.trackmania.com/
  • Login and go to the page to manage one of your API user
  • Click of the "Request access to TMF game data" button if it's not already done
  • Click on the "Create an OAuth2 application" and follow the instructions
You can know use OAuth2. Test the basic example included in the SDK !
OAuth2 - developers.trackmania.com
OAuth2 - developers.trackmania.com
How do players manage authorized applications?

It all takes place on the Player Home: http://home.trackmania.com/authorizations/
OAuth2 - home.trackmania.com
OAuth2 - home.trackmania.com
Basic code example

This is a very basic code example.

Code: Select all

<?php

require_once __DIR__.'/../../../src/autoload.php';

define('API_USERNAME', 'api_username');
define('API_PASSWORD', 'api_password');
define('SCOPE', '');

try
{
	$trackmania = new \TrackMania\WebServices\OAuth2\Player(API_USERNAME, API_PASSWORD);
	$loginURL = $trackmania->getLoginURL(SCOPE);
	$player = $trackmania->getPlayer();
}
catch(\TrackMania\WebServices\Exception $e)
{
	var_dump($e->getHTTPStatusCode(), $e->getHTTPStatusMessage(), $e->getMessage());
	$player = null;
}

if($player)
{
	var_dump($player);
}
else
{
	echo '<a href="'.$loginURL.'">Login with your TMF account</a>';
}

?>
Available scopes

For now only those scopes are available:
  • basic - Access your account information: Basic account information: login, nickname, zone, tags, rankings.
  • buddies - Access your buddies: List of your buddies
  • email - View your email: View the email address associated with your account, if there is one.
  • online_status - Access your online status: Whether you are connected to the game or an online multiplayer server.
TODO: work in progress

Maniaplanet

What about the Maniaplanet API?

It's not in production yet. But it will be exactly the same. It will be called the Maniaplanet Web Services, and we'll release the Maniaplanet Web Services SDK for PHP which will be pretty much the same as this one. So you can start experimenting with the TMF SDK, and you will be ready for Maniaplanet! I don't have a release date yet, but I believe it will be avaible during the summer.
Please do not PM for support. Instead, create a thread so that everyone can contribute or benefit from the answer! 8-)
User avatar
Jojo_44
Posts: 485
Joined: 12 Jul 2010, 15:58
Location: Germany->Bavaria
Contact:

Re: [beta] SDK 2.0 with Namespaces and OAuth2 support!

Post by Jojo_44 »

Really cool stuff, I will have a look this evening.

regards, Jojo

Edit:

After entering my login and password I get:
Something went wrong, please try again later
But I don´t know what´s wrong ?
Image
my english sounds very unfriendly but it isn´t ;)
User avatar
Jojo_44
Posts: 485
Joined: 12 Jul 2010, 15:58
Location: Germany->Bavaria
Contact:

Re: [beta] SDK 2.0 with Namespaces and OAuth2 support!

Post by Jojo_44 »

Jojo_44 wrote:After entering my login and password I get:
Something went wrong, please try again later
But I don´t know what´s wrong ?
My api user: zeroladder46
request for: jojo_dragon

It still not work, maybe you overlooked my post above because I edited ;)

best regards, Jojo
Image
my english sounds very unfriendly but it isn´t ;)
User avatar
gouxim
Nadeo
Nadeo
Posts: 1186
Joined: 14 Jun 2010, 17:20

Re: [beta] SDK 2.0 with Namespaces and OAuth2 support!

Post by gouxim »

Jojo_44 wrote: My api user: zeroladder46
request for: jojo_dragon

It still not work, maybe you overlooked my post above because I edited ;)
Can you tell me when it happens exactly? I'll look into it tomorow.
Please do not PM for support. Instead, create a thread so that everyone can contribute or benefit from the answer! 8-)
User avatar
Jojo_44
Posts: 485
Joined: 12 Jul 2010, 15:58
Location: Germany->Bavaria
Contact:

Re: [beta] SDK 2.0 with Namespaces and OAuth2 support!

Post by Jojo_44 »

Directly after press "Connexion" at the player page.

regards, Jojo
Image
my english sounds very unfriendly but it isn´t ;)
User avatar
gouxim
Nadeo
Nadeo
Posts: 1186
Joined: 14 Jun 2010, 17:20

Re: [beta] SDK 2.0 with Namespaces and OAuth2 support!

Post by gouxim »

This one was tricky. Your redirect URI was'nt beeing validated, which is weird because it was obviously valid ; plus on my local dev environement, it worked perfectly with that URL. Turned out it's a bug that fixed after the 5.3.2 (our production version) release https://bugs.php.net/bug.php?id=51192.

Anyways, it's fixed now. Thanks for the report!
Please do not PM for support. Instead, create a thread so that everyone can contribute or benefit from the answer! 8-)
User avatar
Jojo_44
Posts: 485
Joined: 12 Jul 2010, 15:58
Location: Germany->Bavaria
Contact:

Re: [beta] SDK 2.0 with Namespaces and OAuth2 support!

Post by Jojo_44 »

Works perfectly, thanks for the nice service.

regards, Jojo
Image
my english sounds very unfriendly but it isn´t ;)
User avatar
gouxim
Nadeo
Nadeo
Posts: 1186
Joined: 14 Jun 2010, 17:20

Re: [beta] SDK 2.0 with Namespaces and OAuth2 support!

Post by gouxim »

Btw don't forget to test the example both in a web browser and in the manialink explorer :)
Please do not PM for support. Instead, create a thread so that everyone can contribute or benefit from the answer! 8-)
User avatar
Jojo_44
Posts: 485
Joined: 12 Jul 2010, 15:58
Location: Germany->Bavaria
Contact:

Re: [beta] SDK 2.0 with Namespaces and OAuth2 support!

Post by Jojo_44 »

gouxim wrote:Btw don't forget to test the example both in a web browser and in the manialink explorer :)
Works too. If you already accessed the app with the website you don´t have to allow access again and if not you have to access it. So it seems to work fine. I will try the guestbook later this day.

regards, Jojo
Image
my english sounds very unfriendly but it isn´t ;)
User avatar
gouxim
Nadeo
Nadeo
Posts: 1186
Joined: 14 Jun 2010, 17:20

Re: [beta] SDK 2.0 with Namespaces and OAuth2 support!

Post by gouxim »

calaagree wrote:I have the same problem.

I have the error something went wrong.
I tried with my api: tmf_calaagree_2
And tried to connect with my account.

I think it's again the url but i'm not sure.
The error is "redirect_uri_mismatch". You registered a URI with www.*** and here you are using ***.

I'll update the error handling to you have better error messages.
Please do not PM for support. Instead, create a thread so that everyone can contribute or benefit from the answer! 8-)
Post Reply

Return to “Trackmania Forever Web Services”

Who is online

Users browsing this forum: No registered users and 0 guests