The Facebook platform offers a number of features that we can easily implement using AIRFacebook ANE and provide great social experience for our users. In this post, we’ll take a look how to use the ANE to perform the following tasks in our app:
If your app is not configured with Facebook, please, read a previous post on how to set up an AIR app with Facebook.
The very first thing to do is initialize the native Facebook SDK. It’s recommended to do so soon after our app is launched so somewhere in our main/document class we use the following snippet:
Now let’s take a look what are all those parameters.
- Our Facebook app ID, nothing too special about that.
Booleanthat defines if we want the ANE to automatically log events (to Facebook server) once our app activates (i.e. user is using it) and deactivates (i.e. it’s put to background or shut down). We’re not interested in these logs at the moment so we pass in
- Third parameter is a URL scheme suffix and it is valid for iOS only. This value can be useful when having two different apps using single Facebook app ID – more about shared app ID is available at Facebook docs. We won’t use it right now.
- Next parameter is
Booleanthat we’ll want to set to
trueduring development as it enables log messages.
- Last three parameters accept objects which implement
IAIRFacebookSDKInitListenerinterfaces. The easiest way to provide such object is to implement those interfaces in our main class and simply pass in the value of
thiswhich references instance of our main class. More about the idea behind this interface API is available in the post Using AIRFacebook listener interfaces.
So we make our class implement the aforementioned interfaces and add the required methods. Our main class will look something like this:
AIRFacebookEvent.SDK_INITevent listener before calling
AIRFacebook.init()or by implementing
After the Facebook SDK intializes, we’ll get a response if a cached access token was loaded or not. That way we know if user has logged in before and doesn’t have to do it again this time around. Also, if a cached access token exists, user’s basic profile will become available.
If a cached access token was not loaded after initialization, we’ll have to log our user in before we start using the Facebook API on user’s behalf. First, we have to determine what type of requests we’ll want to execute and ask for the correct permissions based on that:
- Reading – for example, asking for user’s information like email and friends.
- Publishing – for example, updating user’s status or posting a new high score.
During each login attempt we can only ask for permissions which all belong to the same group; we cannot ask user for email and publish permissions in a single call – these have to be separate. The idea is to ask for only those permissions that are necessary at one particular moment. After we figure out the permissions we want we simply call one of the login methods:
We are passing in reference to
this which means we’ll need to implement
The successful callback gives us list of permissions which were denied/granted by the user during the last login attempt. We can check them to determine if we’re allowed to do what we intended in the first place and control our application flow appropriately.
If we need another permission later somewhere in our app, we can call the corresponding login method again – user won’t have to enter his password, instead he’ll be prompted with a dialog that allows him to grant or deny the new permission(s).
AIRFacebook.grantedPermissionsto check for all permissions that user has denied/granted to our app.
Displaying user profile
Now that the user has logged in, we can finally start doing some serious stuff! Let’s begin with the basics like displaying user’s name and profile picture. Important thing to note is that user’s profile is not available immediately after logging in, thus accessing
AIRFacebook.basicUserProfile inside of our login handler would get us nowhere – the property will return
null (unless the user wasn’t logging in for the first time but only answering a new permission request). When user logs in for the first time then the listener object we set for basic user profile in
AIRFacebook.init() will be notified (and only this one time). If user logs out then it’s a good idea to add the listener again to know when the basic profile is ready for us to access:
BasicUserProfileinstance returned in the callback is globally accessible using
AIRFacebook.basicUserProfileso there’s no need to store the object manually.
Now we have some user information available but we are still missing the profile picture. We can get the picture URL using
AIRFacebook.requestUserProfilePicture() and load the returned value using
flash.display.Loader class, or we can ask the ANE to do it for us:
The first 2 parameters define the size of the picture, third parameter tells the ANE to load the picture for us and the last parameter is an object that will be notified once the picture is loaded (or if an error occurs). This object must implement
Now let’s say we want to know user’s birthday and gender. As you can see,
BasicUserProfile instance doesn’t have these properties. That’s because Facebook doesn’t give us access to such information by default and we have to explicitly ask for it. We can use
AIRFacebook.grantedPermissions to check if user have granted us
gender permissions, otherwise we have to use the
AIRFacebook.loginWithReadPermissions() method and ask for them. After we’re given these permissions, we can make the following request:
With this request we are asking for user’s birthday and gender, we are telling the ANE to force the request (otherwise it could return a cached
ExtendedUserProfile from previous request) and using
this as a listener object that implements
IAIRFacebookExtendedUserProfileListener. The callback methods are as follows:
Updating user’s status
Updating user’s status is simply a POST request to Facebook’s Open Graph. Let’s see how we can use the
/feed node of our user to post a message to his feed.
Since we want to publish content on user’s behalf, we need to be granted
publish_actions permission – we can ask for it using:
Assuming user has granted the permission to our app, we’re ready to make POST requests to the Open Graph. The ANE exposes three different methods which work directly with Open Graph:
Since our intention is to post new content, we’ll use the second option. The method’s first parameter is an Open Graph path where the content should be created, or in some cases updated. By having our user logged in we’re in possesion of his access token, thus we can use the
/me node followed by
/feed. This gives us the Open Graph path where we want to post the content. Next, we must provide at least one of the required fields for this node. We’ll use the field
place to post a message from Seattle, Washington. The full request then looks like this:
Last parameter is object implementing
IAIRFacebookOpenGraphListener interface that defines the following methods:
The success callback gives us response in the form of a parsed JSON (where you will usually find an ID of the newly created post) as well as raw data returned by the native SDK.
Getting user’s friends
Facebook have changed its friend list policy in the last few years and we can no longer read user’s entire friend list. We can only retrieve those friends who have also used (i.e. logged in) our app. Furthermore, if any friend denied the
user_friends permission during his login, that friend won’t appear in our retrieved list of friends. Let’s see how we can get at least those who like to use our app!
Essentially, getting user’s friends is just another Open Graph request, only this time we can make use of a helper method
AIRFacebook.requestUserFriends() that also parses the response for us so that we can focus on the more important stuff. The method accepts
fields parameter which is a list of properties that we want to retrieve from our user’s friends.
Last parameter is object implementing
IAIRFacebookUserFriendsListener interface that defines the following methods:
In addition to the POST request method that is useful for creating and updating content anywhere on the Open Graph, there are 5 helper methods for sharing specific content:
Methods with the
Message suffix are great for sharing content directly to a friend using the Facebook’s Messenger app. Actual availability of all these methods is subject to device’s capabilities and if Facebook or Messenger app is installed. We can use one of the following properties to check if the current device is able to share the corresponding content:
Open Graph Story
Now, let’s assume we’ve made an amazing role-playing game where players can craft various items, like weapons, armors and magic potions. When player crafts an item we’d like him to be able to share his accomplishment, in the form of an Open Graph story. Open Graph story is a combination of Action (craft) and Object (weapon, armor…). Sharing a custom content similar to this can lead to an increased engagement and audience.
To create a custom story for our game we need to define action and object. We can do that by going to our Facebook app and selecting Open Graph from the menu on the left. We click the + Add Custom Story button in the middle of our screen. Note we could create our action and object separately but it’s quicker to do it in the Create a story dialog that is presented to us. We type our action’s name into the left input, our object’s name into the field on the right and hit the plus signs.
We continue by selecting our newly created action and object and click Create to create our story.
We’re presented with a page where we can edit our story name, tenses, default titles for variety of scenarios and so on. Let’s say we’re happy with the defaults for now. The story is now ready to be shared with the world!
Before we jump into code, we need to set namespace for our Facebook app by going to the Settings page that is accessible using the menu on the left. Now we’re ready to share our story using the following:
Last parameter is a listener object implementing
Sword image created by Sammy65.
If our weapon object had a custom property called
rarity we could specify it in the code like this:
To see more examples of AIRFacebook’s API take a look at the source codes for a demo app on GitHub.