Facebook Timeline App – Built in actions, objects, scores, achievements

In this tutorial we will see how to publish built in actions and object which facebook has provided. Plus, we will also see about publishing of achievement and scores for game apps.

In the previous tutorial we saw how to create and publish custom user defined actions, please go through the previous tutorial before reading this one.

Built in Objects and Actions

Facebook provides some built-in actions which we can use in our application. The advantage of using these built-in actions and objects in my opinion is that, these have a different UI customized to each object type, where as all custom actions,objects have same pre-defined UI. Also these built-in action can be read of a user profile using open graph. Here is a list of built-in actions and objects.

To show how to publish these i will taken a example of read action with article object. As written in the previous tutorial objects can be publish only with a valid access token, so we need to integrate facebook login in our page. Also to publish actions we need to add the facebook-php sdk.
Of course we need to add the actions and object which we will use in our facebook app -> Open Graph.

Facebook App Open Graph

The code publish action read is

<?php
require_once 'src/facebook.php';
$facebook = new Facebook(array(
		'appId'  => 'XXXX',
		'secret' => 'XXXXXXXXXXXXXXXX',
));
$user = $facebook->getUser();
if ($user) {
	try {
		// Proceed knowing you have a logged in user who's authenticated.
		$user_profile = $facebook->api('/me');
			try{
				$params = array('article'=>'http://excellencetechnologies.co.in/fb/article.php?id='.rand(0,100));
				$out = $facebook->api('/me/news.reads','post',$params);
				print_r($out);
			}catch(Exception $e){
				echo $e->getMessage().'<br>';
			}
	}catch(Exception $e){
		echo $e->getMessage().'<br>';
	}
}

and code inside the file article.php is

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head prefix="og: http://ogp.me/ns# fb: http://ogp.me/ns/fb# article: http://ogp.me/ns/article#">
  
  <meta property="fb:app_id"      content="182741145117428" /> 
  <meta property="og:type"        content="article" /> 
  <meta property="og:url"         content="http://excellencetechnologies.co.in/fb/article.php?id=<?php echo $_REQUEST['id'] ?>" /> 
  <meta property="og:title"       content="Test Article Title2" /> 
  <meta property="og:description" content="Test Article Description2" /> 
  <meta property="og:image"       content="https://s-static.ak.facebook.com/rsrc.php/v1/yj/r/nsnBUoPJHHW.png" /> 
  <meta property="article:published_time"  content="<?php echo strtotime('now'); ?>" /> 
  <meta property="article:modified_time"  content="<?php echo strtotime('+30min'); ?>" /> 
  <meta property="article:expiration_time"  content="<?php echo strtotime('+30min'); ?>" /> 
  <meta property="article:author"  content="529981003" /> 
  <meta property="article:section"  content="Technology Blog2" /> 
  <meta property="article:tag"  content="Facebook" /> 
  <meta property="article:tag"  content="Advanced" /> 
</head>
<body class="index">
</body>
</html>

article.php has all the meta tags required for publishing an article.

The output of publishing articles looks like

Facebook Article

There are few error i encountered when publishing the article first time
Error1: (#3501) User is already associated to a article10150656304499272 object on a unique action type Read. Original Action ID: 354912064550990
Solution: It seems facebook doesn’t allow multiple article’s to be published for a single user. To identify an unique article, facebook does it on the basis of article url we pass. That’s why i have added the rand(0,100) function in the article publish url to fix this error.

Error2: The action you’re trying to publish is invalid because it does not specify any reference objects. At least one of the following properties must be specified: article.
Solution: This error comes up when there is an error in the api call. i.e if the parameters passed are misspelled

$params = array('article'=>'http://excellencetechnologies.co.in/fb/article.php?id='.rand(0,100));

the key ‘article’ here, if misspelled generates this error.

Now lets see another example of an built in action type ‘watch’ and built in object ‘movie’.
The code to publish action is

try{
$params = array('movie'=>'http://excellencetechnologies.co.in/fb/movie.php?id='.rand(0,100));
$out = $facebook->api('/me/video.watches','post',$params);
print_r($out);
}catch(Exception $e){
 echo $e->getMessage().'<br>';
}

And the code to write in the file movie.php is

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head prefix="og: http://ogp.me/ns# fb: http://ogp.me/ns/fb# article: http://ogp.me/ns/article#">
  
  <meta property="fb:app_id"      content="182741145117428" /> 
  <meta property="og:type"        content="movie" /> 
  <meta property="og:url"         content="http://excellencetechnologies.co.in/fb/movie.php?id=<?php echo $_REQUEST['id'] ?>" /> 
  <meta property="og:image"                content="http://ia.media-imdb.com/images/M/MV5BMTc3NzQ3OTg3NF5BMl5BanBnXkFtZTcwMjk5OTcxNw@@._V1._SY317_.jpg">
  <meta property="og:title"                content="21 Jump Street">
  <meta property="og:description"          content="21 Jump Street">
  <meta property="video:release_date"      content="<?php echo strtotime('now'); ?>">
  <meta property="video:actor"             content="113615648714404">
  <meta property="video:actor:role"        content="Lead">
  <meta property="video:actor"             content="9964154115">
  <meta property="video:actor:role"        content="Lead2">
  <meta property="video:duration"          content="<?php echo 109 * 60 ;?>">
  <meta property="video:director"          content="http://www.imdb.com/name/nm0588087/">
  <meta property="video:writer"            content="http://www.imdb.com/name/nm0588087/">
  <meta property="video:tag"               content="action">
 
</head>
<body class="index">
</body>
</html>

The output that we see in facebook is

Facebook Timeline Movie

Achievement and Scores API

Facebook provides with some special timeline api’s for game app’s. If your app category is selected as ‘Game’, then you can use these 2 api’s in your app.

Here is the office blog provided by facebook on publishing scores and achievements.

To publish it the code is explain below

1. You need generated an app access token

$app_id = 'XXXX';
$app_secret = 'XXXXXX';
// Get an App Access Token
$token_url = 'https://graph.facebook.com/oauth/access_token?'
	. 'client_id=' .$app_id
	. '&client_secret='.$app_secret
	. '&grant_type=client_credentials';

 $token_response = file_get_contents($token_url);
 $params = null;
 parse_str($token_response, $params);
 $app_access_token = $params['access_token'];

2. You need to register an achievement. You can read more details about achievements here as it has many restrictions.

$achievement = 'http://excellencetechnologies.co.in/fb/achievement.php?id='.rand(0,100);
print('Register a User Achievement<br/>');
$achievement_display_order = 1;
$achievement_registration_URL = 'https://graph.facebook.com/'.$app_id.'/achievements';
$achievement_registration_result=https_post($achievement_registration_URL,
	'achievement=' . $achievement
        . '&display_order=' . $achievement_display_order
	. '&access_token=' . $app_access_token
 );

3. In the achievement.php file you need add this code

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head prefix="og: http://ogp.me/ns# fb: http://ogp.me/ns/fb# article: http://ogp.me/ns/article#">
  
  <meta property="fb:app_id"      content="APP_ID" /> 
  <meta property="og:type"        content="game.achievement" /> 
  <meta property="og:url"         content="http://excellencetechnologies.co.in/fb/achievement.php?id=<?php echo $_REQUEST['id'] ?>" /> 
  <meta property="og:image"                content="http://ia.media-imdb.com/images/M/MV5BMTc3NzQ3OTg3NF5BMl5BanBnXkFtZTcwMjk5OTcxNw@@._V1._SY317_.jpg">
  <meta property="og:title"                content="Game Points Test">
  <meta property="og:description"          content="Game Points Test">
  <meta property="game:points" content="100" />
 
</head>
<body class="index">
</body>
</html>

4. Finally publish a user achievement

print('Publish a User Achievement<br/>');
$achievement_URL = 'https://graph.facebook.com/'.$user_profile['id'].'/achievements';
	  $achievement_result = https_post($achievement_URL,
	'achievement=' . $achievement
	. '&access_token=' . $app_access_token
  );
 print('<br/><br/>');

This is how an achievement looks when published

Facebook Achievements

I got few errors before i was able to publish achievements
Error1: (#3) Method allowed only for games
Solution: Your app should have category as ‘Game’

Error2: This method must be called with an app access_token.
Solution: A valid app access token should be generated using the above method. App access token is different from the normal access token.

Error3:
{“error”:{“message”:”(#3502) Object at achievement URL is not of type game.achievement”,”type”:”OAuthException”,”code”:3502}}
Solution: the og:type property is set wrongly in achievement.php file. it should be game.achievement

If you want to publish score for a user you need do the below.

$score = 1;
 // POST a user score
 print('Publish a User Score<br/>');
  $score_URL = 'https://graph.facebook.com/' . $user_profile['id'] . '/scores';
  $score_result = https_post($score_URL,
'score=' . $score . '&access_token=' . $app_access_token
 );
 print('<br/><br/>');

you can create more about scores here.

Attached is the source code