In Tutorial 4: Saying hello to your users, we wrote some code to send messages to anyone who added our test application as a contact. This time we'll be digging into the User API to get and set user status messages. Along the way we'll discuss Mxit's user authentication and how to add some functionality to the PHP API we've been using. Let's get started!
Authentication and the User API
In order to develop more engaging Mxit apps, quite often you will want to access the attributes of a user: their profile information, status, media library, social graph and so on. To do this from a Mobi Portal App requires asking the user for permission and then calling the appropriate method in the API. The way you ask for permission is to send a request to Mxit's authorization server. The basic procedure is detailed in the Authorization API (OAuth 2.0) documentation:
"The Mxit Authorization server will check Application authentication (ClientId & ClientSecret correct) and Application authorization (your Application is allowed access to the requested API). The user will also be required to supply their credentials to the Authorization Server and authorize the access by the Application."
If this seems complicated, don't worry. It's actually quite straightforward:
1. We get a Mxit user's ID
2. We contact the Mxit Authorisation server at auth.mxit.com with a request to perform an action (see the next section Scope for what these actions are).
3. The server checks out if our request is OK and if it is, pops up a menu for the user asking them to give their permission.
4. It then redirects us back to a URL we supply along with an OAuth2 token that we can use for subsequent requests. This token is just a unique number and lasts for a limited period of time.
The actual control flow of OAuth2 behind the scenes is quite complicated, but Ashley Kleynhans' Mxit API PHP wrapper that we're going to be using again wraps it all nicely in a simple function call. Remember that for certain API calls you will need to get user permission, without it you will not be able to access certain attributes or make certain changes through the API.
Scope
The scope is just a list of permissions that OAuth2 can grant us.For a complete list of OAuth scopes please see OAuth Scopes.
We want to get a user's status message and also change it so we'll be asking for 'profile/public' and 'status/write' permission. You can ask for multiple permissions in one go by sending them separated by spaces in your request but then you run the risk of the user deciding that your application is asking for too much and turning you down. Keep it short.
Getting a Status Message - The Code
Here's a small PHP script to retrieve a user's current status and echo it to the screen:
<?phpTo understand the control flow, have a look at the 'else' clause first. We request access using the API with the method call of the same name, our app's URL on AppFog and the scope - profile/public in this case. When this code is first called, it will jump to a user menu that looks like this:
require_once('MxitAPI.php');
$key = 'your-app-key';
$secret = 'your-app-secret';
$api = new MxitAPI($key, $secret);
if (isset($_GET) && isset($_GET['code']))
{
$api->get_user_token($_GET['code'], 'http://testappmxt.eu01.aws.af.cm');
$userid = $_SERVER['HTTP_X_MXIT_USERID_R'];
$status = $api->get_user_statusmessage();
echo "Your status is: " . $status . "";
} elseif (isset($_GET) && isset($_GET['error']) && isset($_GET['error_description']))
{
echo "<h2>There was an error requesting access from the API</h2>";
echo '<strong>Error:</strong> '. $_GET['error'] .'';
echo '<strong>Error Description:</string> '.
} else {
$api->request_access('http://testappmxt.eu01.aws.af.cm','profile/public');
} catch (Exception $e) {
echo $e->getMessage(
}
?>
Figure 1: In-app OAuth screen, asking for user permission to retrieve the status message from your profile.
If the user grants us permission, then auth.mxit.com redirects to our page and the script is called again but the 'if' clause is true - the $_GET variable exists and it has a field in the headers called 'code' which is our authorisation token. You can see it in the URL if you follow along in a browser. Now that we have the code we grab the user's Mxit_ID - the internal representation of their user name - then get the status message and display it. If there are errors, they get displayed.
We decided to get our hands a little dirty by coding our own method to retrieve the actual status message, please see below. You are more than welcome to use the method in the MxitAPI.php class the method public functionget_status($login).
public function get_user_statusmessage()
{
$this->_check_scope('get_user_statusmessage','profile/public');
$url = $this->_base_user_api_url . "statusmessage";
$this->_api_headers();
$this->_call_api($url, 'GET');
return $this->result;
}
Put this class method into the body of the class MxitAPI, somewhere around the other user functions is fine, and save the file. Then you can update your test app, add it as a contact, give yourself permission and see the status message you get back.
Setting a status message - the code
Here's the code to change the status message of a user. As you can see it's very similar to our first example:
<?php
require_once('MxitAPI.php');
try {
$key = 'your-app-key';
$secret = 'your-app-secret';
$api = new MxitAPI($key, $secret);
if (isset($_GET) && isset($_GET['code']))
{ $api->get_user_token($_GET['code'], 'http://testappmxt.eu01.aws.af.cm');
$mxitid = $_SERVER['HTTP_X_MXIT_USERID_R'];<
$status = "I feel awesome today!";
$result = $api->put_user_statusmessage($status)
echo "Status is now " . $status . "";
}
elseif (isset($_GET) && isset($_GET['error']) && isset($_GET['error_description']))
{
echo "<h2>There was an error requesting access from the API</h2>";
echo '<strong>Error:</strong> '. $_GET['error'] .'';
echo '<strong>Error Description:</strong> '. $_GET['error_description'] .'';
}
else {
$api->request_access('http://testappmxt.eu01.aws.af.cm','status/write');
}
} catch (Exception $e) {echo $e->getMessage();
You can now use the public functionset_status($message) in the MxitAPI.php class. Note the use of the status/write OAuth permission which is used as well as the need to encode the message.
Test it from a mobile Mxit client and watch your status change.
What's next?
In the next tutorial (coming soon) we will be querying some more user information, including avatars. See you then!