Intermediate Level Tutorial

What you will learn

The Facebook commands provided within AppGameKit provide functionality allowing users of an app to login to Facebook, post information about the app and find friends who are using the app. It's a great way of raising awareness of an app. Please note that this functionality is aimed at iOS and Android users.

Creating an app on Facebook

There's a few prerequisites for dealing with Facebook.

If your app is being deployed on iOS then you must register your app on iTunes Connect. If you app is being deployed on Android then your app must be registered on the Play Store. The reason for this is that Facebook needs to know information about the application it's connecting to, for example, the package name of your app when deploying to Android. This guide assumes you are familiar with the process of setting up an app for these platforms.

If you don't already have a Facebook account then you will need to register.

The final stage before getting into any programming, is to create an application listing on Facebook, which will be used as a way of connecting your AppGameKit app to Facebook. To get started with this visit the Facebook for developers page. Once logged in look at the top right of the screen where you will see a drop down menu showing "My Apps". Select this and click on "Add New App". After doing this you will be asked to provide some information, such as the name of the app, a contact email address and what category the app comes under. When you have filled in the form click the "Create App ID" button, which will take you to another page. There's a great deal of settings that can be configured at this stage, for now the most important part is to to handle the Facebook login. To set this up click on "Add Products" on the left panel and then select "Facebook Login", then select "Quickstart" and choose the first platform you want to deal with e.g. Android. You can add other platforms later. Once you add a platform you will be asked to go through these steps.

Much of the steps are not required as AppGameKit takes care of it. The key points are the information about your app and the key hashes from your certificates.

When an application listing has been made make a note of your App ID from the Dashboard, as AppGameKit will require this so that it can connect to the application.

Logging into Facebook

For an app to login to Facebook it needs to perform the following.

Prior to attempting to login to Facebook it's a good idea to first of all determine if the user has a viable internet connection. This can be handled by calling the command GetInternetState. If this returns a value of 1 then you can attempt to login to Facebook.

When FacebookLogin is called the user will be presented with a Facebook login dialog, that provides the user with the name of the Facebook app they are logging into. At this point the user enters their details and continues.

The login process isn't going to happen instantaneously, it may take several seconds before knowing whether the login has failed or succeeded, so the login code needs to handle this. Here's an example of how it might work.

FacebookSetup ( "358083327620324" )

loggedIn = Login ( )
do print ( loggedIn )
sync ( ) loop
function Login ( ) if GetInternetState ( ) = 0 exitfunction 0 endif
FacebookLogin ( )
do loggedIn = GetFacebookLoggedIn ( )
select loggedIn case 0: print ( "waiting to login..." ) endcase
case 1: print ( "logged in" ) exitfunction 1 endcase
case -1: print ( "an error has occurred" ) exitfunction -1 endcase endselect
sync ( ) loop endfunction 0

The program begins by calling FacebookSetup and passing in the App ID from the application listing on Facebook. This is followed by a call to the function Login.

Given that this function may take several seconds to complete it would be a good idea to provide some information on screen for the user letting them know that the program is waiting to login to Facebook. As an extra precaution the function could be modified so that the Facebook login was given a set amount of time to complete, for example, 60 seconds. If the return value from GetFacebookLoggedIn was still 0 at this point then you could exit out of the function assuming the login had failed.

Posting information to the user's wall

Once a user has been logged into Facebook you can post information to their wall / page. The command to do this is called FacebookPostOnMyWall. When it is called in your program the command will display a dialog on screen, prompting the user to post the message to their Facebook page. It takes the following parameters.

This command is a great way to help promote your app. It could be used, for example, when a player reaches a certain score in a game, or perhaps when a player meets certain targets. Here's an example of how it can be used in the previous program, after a login attempt.

if loggedIn = 1
	link$ = "www.game-guru.com"
	image$ = "https://www.thegamecreators.com/images/banners/gameguru-tgc-banner.jpg"
	name$ = "Game Guru"
	caption$ = "Check out Game Guru"
	description$ = "Create, play and share fun games on your PC with absolutely no technical knowledge needed!"
FacebookPostOnMyWall ( link$, image$, name$, caption$, description$ ) endif

Finding friends

A few commands are provided that allow you to obtain a list of friends who are also playing your app. Through the use of these commands it would be possible to create something like a high score table, showing a list of your friends and how successful they are at the game. It's also possible to post a message on a friends wall instead of your own.

Once logged into Facebook the command FacebookGetFriends can be called to retrieve a list of your friends who have your app. Like the login command this will not necessarily complete immediately, so it may be that your app has to wait several seconds before the information is available. After calling FacebookGetFriends the command FacebookGetFriendsState is used to determine whether the information has been obtained or if there is a problem. Once the list has downloaded you can get information such as a user's name and also download their profile picture.

Getting a list of friends could be handled with this function.

function GetFriends ( )
	FacebookGetFriends ( )
do friends = FacebookGetFriendsState ( )
select friends case 0: print ( "waiting to download friends list..." ) endcase
case 1: print ( "obtained information" ) exitfunction 1 endcase
case -1: print ( "an error has occurred" ) exitfunction -1 endcase endselect
sync ( ) loop endfunction

It's similar to the login process in that it may take several seconds before the information has been passed from Facebook to the app, so again at this stage it would be useful to display information on screen letting the user know what is happening, and also consider a timeout event to ensure the function does not remain here continually waiting to obtain a list of friends.

Once a list of friends has been downloaded you can find out how many people are in it by calling FacebookGetFriendsCount. From there you can obtain the name of a friend in that list by calling FacebookGetFriendsName and their ID with FacebookGetFriendsID as shown in this function.

function ShowFriends ( )
		for i = 0 to FacebookGetFriendsCount ( )
			print ( FacebookGetFriendsName ( i ) )
			print ( FacebookGetFriendsID ( i ) )
		next i
sync ( ) loop endfunction

Posting information to a friends wall

This is similar to posting information onto the user's wall, except the command is called FacebookPostOnFriendsWall, which takes an extra parameter at the start, letting you control which friends wall you want to post to. Here's a function that shows how you could post onto a friends wall.

function PostToFriendsWall ( index as integer )
	link$ = "www.game-guru.com"
	image$ = "https://www.thegamecreators.com/images/banners/gameguru-tgc-banner.jpg"
	name$ = "Game Guru"
	caption$ = "Check out Game Guru"
	description$ = "Create, play and share fun games on your PC with absolutely no technical knowledge needed!"
FacebookPostOnFriendsWall ( FacebookGetFriendsID ( index ), link$, image$, name$, caption$, description$ ) endfunction

Bringing it all together

To conclude this guide a small program has been created that does the following.

// a type to store information about facebook friends
type friendType
	ID as string
	name as string
	photo as string
	image as integer
	sprite as integer

// array to store friends friends as friendType [ 1 ]
// current state state as integer = 1
// index for current friend currentFriend as integer = 0
// switch to new fonts UseNewDefaultFonts ( 1 )
// set up facebook FacebookSetup ( "358083327620324" )
// our main loop do // take action dependent on the state select state case 1: // login to facebook if GetInternetState ( ) = 1 print ( "attempting to login to facebook..." ) FacebookLogin ( ) state = 2 else state = 8 endif endcase
case 2: // wait for login and then get list of friends print ( "waiting to login to facebook..." )
if GetFacebookLoggedIn ( ) = 1 FacebookGetFriends ( ) state = 3 endif endcase
case 3: // get list of friends print ( "waiting to get list of friends..." )
if FacebookGetFriendsState ( ) = 1 if FacebookGetFriendsCount ( ) >= 1 state = 4 else state = 8 endif endif endcase
case 4: // download photo for friend FacebookDownloadFriendsPhoto ( currentFriend ) state = 5 endcase
case 5: // check download state download = GetFacebookDownloadState ( )
// still downloading, or downloading or failed if download = 1 print ( "downloading photo for friend" ) elseif download = 2 // store information about this friend in our array friends [ currentFriend ].ID = FacebookGetFriendsID ( currentFriend ) friends [ currentFriend ].name = FacebookGetFriendsName ( currentFriend ) friends [ currentFriend ].photo = GetFacebookDownloadFile ( ) friends [ currentFriend ].image = LoadImage ( friends [ currentFriend ].photo ) friends [ currentFriend ].sprite = CreateSprite ( friends [ currentFriend ].image )
SetSpriteSize ( friends [ currentFriend ].sprite, 20, 10 )
// either download information about the next friend or move on if currentFriend < FacebookGetFriendsCount ( ) friends.length = friends.length + 1 currentFriend = currentFriend + 1 state = 4 else state = 6 endif else state = 8 endif endcase case 6: // position photos of friends on screen to the right y = 0
for i = 0 to friends.length SetSpritePosition ( friends [ currentFriend ].sprite, 80, y ) y = y + 10 next i
state = 7 endcase
case 7: // post on wall
// print out friends names for i = 0 to friends.length print ( friends [ i ].name ) next i
// deal with any input if GetPointerPressed ( ) = 1 x = GetPointerX ( ) y = GetPointerY ( )
for i = 0 to friends.length if GetSpriteHitTest ( friends [ currentFriend ].sprite, x, y ) = 1
link$ = "www.game-guru.com" image$ = "https://www.thegamecreators.com/images/banners/gameguru-tgc-banner.jpg" name$ = "Game Guru" caption$ = "Check out Game Guru" description$ = "Create, play and share fun games on your PC with absolutely no technical knowledge needed!"
// to post this information on a friends wall FacebookPostOnFriendsWall ( friends [ currentFriend ].ID, link$, image$, name$, caption$, description$ ) endif next i endif endcase
case 8: // no friends using the app or some kind of problem getting information endcase endselect
sync ( ) loop


Although there's only a small set of commands relating to Facebook they are incredibly useful. Adding Facebook functionality to your app could make a big difference in making it more visible to others.