Localising a Facebook Tab with Signed Request

Localising a Facebook Tab with Signed RequestEvery now and again we put together a Facebook tab to promote various campaigns across various countries around the world. With the introduction of Facebook's business manager we are starting to properly localise our applications so we can use one application that handles multiple localisations with one Facebook developer application. Facebook passes two pieces of data via its signed request that we can use to achieve this. The country that the page is being viewed from and the users language that they select with they initially sign up. This provides us with enough information to appropriately display content based on their region. When we localise tab applications we normally use an XML document to hold all the content on the page and links to images etc... This allows us to pass on the XML document to people in the office so that it can be populated with the locale content accordingly. Obviously this can be achieved in other ways such as localised through a PHP page or different localised database tables.

In order to get a signed request you need to deploy and include the Facebook SDK. For this example we will use the PHP SDK which you can either download from Github or use the PHP dependancy manager Composer to install into your project.

To install the library with Composer just add the following into your composer.json file:

{
    "require": {
        "facebook/php-sdk": "@stable"
    }
}

Once you have done this and run 'composer install' in your terminal in the root of your project it will download the PHP SDK into your folder.

Next enter the following into your PHP page:

//include the Facebook Library
if (($loader = require_once __DIR__ . '/vendor/autoload.php') == null)  {
  die('Vendor directory not found, Please run composer install.');
}
//create the Facebook application
$facebook = new Facebook(array(
    'appId' => '{{YOUR_APP_ID}}',
        'secret' => '{{YOUR_APP_SECRET}}'
));
//get the signed request
$signed_request = $facebook->getSignedRequest();
//display contents of the signed request
print_r($signed_request);

This will display something like the following inside your pages tab application:

Array (
[algorithm] => HMAC-SHA256
[issued_at] => 1372676199
[page] => Array
    (
        [id] => {{YOUR_PAGE_ID}}
        [liked] => 
        [admin] => 0
    )
[user] => Array
    (
        [country] => en
        [locale] => en_GB
        [age] => Array
            (
                [min] => 21
            )
    )
)

The main part of this response that we need is the user part of the object which contains both our country and locale that we need to get our locale's content.

You can read more about what Facebook returns in the signed request here.

Now we are going to retrieve these values and determine which localised XML document to load.

<?php
//default to the gb locale
$locale = "en_GB";
//first check for the users native language
switch( $signed_request["user"]["locale"] )
{
    //SPANISH LOCALE
    case "es_LA":
    case "es_ES":
    //get the locale
        $locale = 'es';
        break;
    //ITALIAN LOCALE
    case "it_IT":
        $locale = 'it';
        break;
    //DUTCH LOCALE
    case "nl_NL":
        $locale = 'nl';
        break;
    //FRENCH LOCALE
    case "fr_CA":
    case "fr_FR":
        $locale = 'fr';
        break;
    //GERMAN LOCALE
    case "de_DE":
        $locale = 'de';
    break;
    //etc...
}
echo $locale;
?>

This will now access what localised XML we will need and what content we need to place on the page. The next problem is how we test this! Because you will have a Facebook account that uses the locale that you set when you signed up, how will you be able to test the locale that is coming back from the signed request. Test Users to the rescue!

Test users are provided by the Facebook application and allow you to signup, sign in and test with a dummy user. You can access this functionality by going to your application and you will see a 'Roles' option on left hand panel like below:

You will now see a 'Test Users' tab appear on the top right of the application. Select this and click the 'Add' button in the top right of the Test Users section. You will now be displayed with the below along with various options:


You are now able to select a test users language which will allow you to login and test your Facebook tab application with that user! This should then deliver you content that is specific to that users language!