CoderTakeout - Facebook Development

Recently we announced a new way of creating Featured Stories (previously "Sponsored Stories") on the Ads API by using action specs. These changes make the Ads API more flexible and will make it easier for developers to adapt to new story types as we launch them. We will be deprecating the old sponsored stories creative types as of May 1.

Prior to this change Sponsored Stories were defined by choosing the correct Ad Creative type for the specific Sponsored Story type. E.g. a page like sponsored story was type 9, a page post like sponsored story was type 17 etc. This made it complicated for developers to incorporate new Sponsored Story types as each Sponsored Story required different fields per story type.

By defining Sponsored Stories via Action Specs we are making it easier for new Sponsored Story types to be integrated into Ad Tool apps as they will all make use of the same standard fields.

For example, the old way of creating a Page Like Sponsored Story (Type 9) was as follows:

 curl --silent --location -F "campaign_id=6004176938239" 
      -F "bid_type=1" 
      -F "max_bid=30" 
      -F "targeting={'countries':['US']}" 
      -F "creative={'type':9,'object_id':'115632122684'}" 
      -F "name=AdGroup Name"  "https://graph.facebook.com/act_123456789/adgroups?access_token=____"

While the new Action Spec format is as follows:

 curl --silent --location 
      -F "campaign_id=6004176938239" 
      -F "bid_type=1" 
      -F "max_bid=30" 
      -F "targeting={'countries':['US']}" 
      -F "creative={'type':25,'action_spec':'{\'action.type\':\'like\', \'page\':115632122684}'}" 
      -F "name=AdGroup Name"  "https://graph.facebook.com/act_123456789/adgroups?access_token=____"

Similarly the old way of creating a Specific Page Post like Sponsored Story (Type 25 with query template 6) was as follows:

 curl --silent --location 
      -F "campaign_id=6004176938239" 
      -F "bid_type=1" 
      -F "max_bid=30" 
      -F "targeting={'countries':['US']}" 
      -F "creative={'type':25, 'object_id':115632122684, 'story_id':10150420410887685, 'query_templates':[6]}" 
      -F "name=AdGroup Name"  "https://graph.facebook.com/act_123456789/adgroups?access_token=____"

While the new Action Spec format is as follows:

 curl --silent --location 
      -F "campaign_id=6004176938239" 
      -F "bid_type=1" 
      -F "max_bid=30" 
      -F "targeting={'countries':['US']}" 
      -F "creative={'type':25,'action_spec':'{\'action.type\':\'like\', \'post\':10150420410887685}'}" 
      -F "name=AdGroup Name"  "https://graph.facebook.com/act_123456789/adgroups?access_token=____"

You will notice that the Action Spec based requests use very similar structures in a fixed format while the older process's format depended on the ad type being created. This adoption of a fixed format for defining Sponsored Stories will made it much easier for Ads API developers to support new Sponsored Stories in the future.

The following table lists a mapping from the old Sponsored Story ad creative types to the new Action Spec equivalent.

This post relates to the Ads API which is part of the Marketing API Program. Apps must be whitelisted in order to call this API. For more details on the Marketing API program and how to apply please click here.

This week, we published a How-To on subscribing to data changes using the Real-time Updates API, as well as a games update on driving more discovery for games and shared Single Sign-On best practices for iOS and Android mobile developers. Lastly we announced a guide on How to Migrate you Application Profile Page.

Ability to set the Password on Test Users

We have long had a feature on the Developer App to enable you to create a new test user and to switch to it as needed. We've heard that it was still difficult for developers to test their mobile apps. To address this need, we have added the ability to set the password of the a user now from the Developer App. If you need to change the password of a test user, visit the "Roles" section of the Developer App and click on the "Set Password" link.

Open Graph Actions Continue to Be Approved

This is a reminder that we have started approving Open Graph actions. If you are new to the Open Graph, please review the Tutorial on how to use the Open Graph to integrate your app with Facebook. Please review and check your actions against the required criteria by using the submissions checklist prior to submission.

Reminder that Access Tokens are not to be shared between applications

Please remember that you cannot share access tokens between applications. The access token you receive is only for use within the application for which it was granted, and developers on Facebook platform have a responsibility to take appropriate steps to ensure the security of those tokens.

Posting historical Open Graph activity

Apps can post historical actions to help people fill out their timelines and/or queue up activity from an offline state. For example, a photo app can let people add photos from their past vacations to their timeline.

Any past activity that is posted will not appear in News Feed or ticker. Past activity will have the same privacy that the user chose for the app, and users can control and delete the activity from their Activity Log or directly from timeline.

You must prompt users before publishing historical activity and providing explicit controls. For example, Goodreads, a book recommendations website, created a settings page to let people select which activities to include on their timeline.

Upcoming Breaking Changes

Upcoming Breaking Changes on February 15, 2012

• Pages Insights Metrics Deprecations. We are in the process of deprecating some old Page Insights. We announced this in a number of forums, but failed to outline this change in our Platform Roadmap per our breaking change policy. Our apologies. You can find a full list of the Insights to be deprecated from the Insights documentation. These Insights will be completely removed from API on Feb 15th 2012. Please make all necessary updates as soon as possible so that you can transition smoothly.

• Improved Auth Dialog. On February 15, 2012, all apps will be enabled for the improved dialog, but those that haven’t fully configured their dialog can disable the setting in the Developer App until March 1, at which time it will be turned on for all apps.

Upcoming Breaking Changes on March 1, 2012

• Removing the third settled callback from Payments. To ensure the best experience for users, we are asking developers to ensure that they are fulfilling the order in the callback with status=placed. We assure you that once we call you with status=placed and you respond with settled, the transaction will be complete and you will be paid. You should not be waiting for the settled callback before fulfilling the order.
  
  To reduce confusion we are completely removing the settled callback. For more information please read here.

• Returning up to 960px wide photos in "photo" FQL table and photo Graph API. On 1st March 2012 we will begin returning photos up to 960px wide in the src_big field of the photo FQL table, as well as the source field of the photo object, increasing the current max width of 720px.

New Breaking Changes

• Deprecation of group_type and group_subtype columns from group FQL table. Facebook will be deprecating the group_type and group_subtype columns of the group FQL tables. Please ensure that your applications are not utilizing these columns. These will be eliminated on May 1, 2012.

• XMPP Connections must be done over TLS. Apps connecting to Facebook's XMPP service will be required to use STARTTLS for all connections. We will start rejecting unencrypted connections on June 1, 2012.

• Changes to Domain Insights Metrics. Some domain insights metrics (i.e., domain_active_users_*) were removed in May, 2011, but we failed to update the documentation at that time. These have been removed from the documentation and we have corrected the list of metrics that were deprecated last year. We sincerely apologize for this miscommunications.
  
  Please refer to the Platform Roadmap for more info.

Bugs activity between Tuesday, January 24 and Tuesday, January 31

• 291 bugs were reported
• 46 bugs were reproducible and accepted (after duplicates removed)
• 29 bugs were by design
• 27 bugs were fixed
• 94 bugs were duplicate, invalid, or need more information

Bugs fixed between Tuesday, January 24 and Tuesday, January 31

• creator_uid is not editable
• Broken link in FB.init
• broken link to request dialog page
• Upload a Logo / Upload an Icon doesn't work
• Canceled migrate, app page deleted anyway
• Comment Moderation on Facebook Social Plugin Not Working
• Did not not migrate, app page deleted anyway
• Comments moderation not working
• callback param in graph url causes picture value to be object instead of string
• Moderation-option fails comments
• Auth Dialog Settings Page is Blank
• Likes not transferred after migrating to new page (cause unkown)
• Long graph requests still break when IE falls back to flash
• Login popup window footer bar not anchored to bottom of window in some browsers
• "Play" button in canvas ticker translated incorrectly
• fb.logout still returning active session even with destroySession();
• No Timeline for Test Users
• Insights: Ticker flyout impressions reporting not accurate
• Back Dated Open Graph Action Aggregations No Longer Showing Correctly
• fb:multi-friend-selector returning string "on" in ids[] param in IE
• Object Debugger result "Value cannot be null"
• sample function handleStatusChange code is incorrect
• Can't add test users to another app though developer app.
• Incorrect tense for action in the future
• FB.ui Send Button is oddly displayed when using long list name, and long text.
• Liked page title shown as single letter when multiple pages are liked.
• Please set SKIP_INSTALL to YES

Facebook Stack Overflow Activity

Activity on facebook.stackoverflow.com this week:

• 282 questions asked
• 88 answered, 31% answered rate
• 136 replied, 48% reply rate

In December, we announced that we will be deprecating App Profile Pages on Feburary 1st. Many developers have asked for some tips on how to smoothly migrate their page. Below are some common issues, questions, and pro-tips for how to handle.

What happens when users go to my deprecated App Profile Page?

We recommend updating any links that you've shared to your App Profile Page to point to your new target Page. Existing links to the old App Profile Page will go to the following destinations, in this order:

1. Canvas (if you have specified a Canvas URL for your app)
2. Page (if you have associated a Page with your app)
3. Website (if you have a Website URL)
4. Facebook Homepage (if none of the above has been specified)

What happens to my Likes?

When you migrate to a target Page, your Likes will transfer. You can view the number of Likes that your app has via the Insights tab in the Developer App. Please allow 14 days for the complete transfer to take place.

What about the Vanity URL for my App Profile Page?

The Vanity URL for your App Profile Page will get transferred to the target Page if the Page doesn't already have a Vanity URL. If a Vanity URL already exists for the target Page, the Vanity URL for the App Profile Page will now go to the app (see above).

Why don't I see any eligible target Pages to choose from?

We've seen the following common mistakes:

• Target Page does not have the same name as the app
• Target Page is not set to the "Products/App" category

When is the last day to migrate Likes?

Thursday, February 2, 2012 at 11:59pm Pacific Time.

What about existing content on my App Profile Page (Page Posts, Photos, Events, etc.)?

You will lose this content if you don't save it manually. This content is accessible via the Graph API with any valid access token.

Photos

To retrieve a list of your Page's photos albums (example):

https://graph.facebook.com/YOUR_APP_ID/albums

To get a list of all the photos in the album (example):

https://graph.facebook.com/YOUR_ALBUM_ID/photos

Posts

To access the Page's status updates (example):

https://graph.facebook.com/YOUR_APP_ID/statuses

To access the Page's wall (example):

https://graph.facebook.com/YOUR_APP_ID/feed

To access the Page's own posts (example):

https://graph.facebook.com/YOUR_APP_ID/posts

Click here to review the Page documentation.

A common question we get from developers is how to keep information of Users or Pages using their apps up to date. We wanted to share some of the best practices that can improve the reliability and performance of apps you write on Facebook.

We often see developers querying the Graph API each time a User logs in to their apps to fetch information and update their records. This presents several issues and has a huge hit on performance.

Instead, we encourage you to use the Real-time Updates API that we designed especially for this purpose, allowing developers to subscribe to changes in data in Facebook. Rather than polling Facebook’s servers, your app can then cache data and receive updates whenever the data changes.

For example, many apps rely on a User's location to fetch and display relevant information, it is very important that this data stays up to date on the app’s backend.

Real-time updates allows you to set up a subscription on the location field of the User object, whenever that field changes, Facebook will make an HTTP POST request to a callback URL you specified by with a list of changes.

You can currently subscribe to updates for these types of objects:

• User – Get notifications about particular fields and connections corresponding to User objects in the Graph API.
• Permissions – Get notifications when Users change the permissions they afford your applications. The fields are like those in the corresponding FQL table.
• Page - Get notifications when Pages that have installed your app as a Tab change their public properties.
  Note that the page topic is only used for subscribing to changes to public attributes of the page (like name, category, picture etc). This is the same information that is returned by the Graph API call https://graph.facebook.com/. However, you can subscribe to the page's feed in the same way you subscribe to a User's feed - the subscription topic should be User and the subscription field should be feed

Below is PHP Sample code that sets up an endpoint that will receive both GET (for subscription verification) and POST requests (for actual change data).

<?php

  $verify_token = 'YOURVERIFYTOKEN';

  if ($_SERVER['REQUEST_METHOD'] == 'GET' && isset($_GET['hub_mode'])
    && $_GET['hub_mode'] == 'subscribe' && isset($_GET['hub_verify_token'])
    && $_GET['hub_verify_token'] == $verify_token) {
      echo $_GET['hub_challenge'];
  } else if ($_SERVER['REQUEST_METHOD'] == 'POST') {
    $post_body = file_get_contents('php://input');
    $obj = json_decode($post_body, true);
    // $obj will contain the list of fields that have changed
  }

?>

Once this endpoint is set up, you will need to make a POST request to the actual Real-Time updates API to subscribe to a field.

<?php

  $app_id = 'YOUR_APP_ID';
  $app_secret = 'YOUR_APP_SECRET';
  $app_url = 'http://YOURAPPURL';
  $fields = 'location';
  $verify_token = 'YOURVERIFYTOKEN';

  // Fetching an App Token
  $app_token_url = 'https://graph.facebook.com/oauth/access_token?client_id='
                   .$app_id.'&client_secret='.$app_secret
                   .'&grant_type=client_credentials';
  $ch = curl_init();
  curl_setopt($ch, CURLOPT_URL, $app_token_url);
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
  $res = curl_exec($ch);
  parse_str($res, $token);

  if (isset($token['access_token'])) {
    // Let's register a callback
    $params = array(
      'object'
        =>  'user',
      'fields'
        =>  $fields,
      'callback_url'
        // This is the endpoint that will be called when
        // a User updates the location field
        =>  $app_url . '/index.php?action=callback',
      'verify_token'
        =>  $verify_token,
    );

    curl_setopt($ch, CURLOPT_URL, 'https://graph.facebook.com/'
                                  .$app_id.'/subscriptions?access_token='
                                  .$token['access_token']);
    curl_setopt($ch, CURLOPT_POST, 1);
    curl_setopt($ch, CURLOPT_POSTFIELDS, $params);
    $res = curl_exec($ch);
    if ($res && $res != 'null') {
      print_r($res);
    }

    // Fetch list of all callbacks
    curl_setopt($ch, CURLOPT_POST, 0);
    $res = curl_exec($ch);
  }
  if ($res && $res != 'null') {
    print_r($res);
  }
  curl_close($ch);

?>

The code above should return a similar object listing current subscriptions:

{
   "data":[
      {
         "object":"user",
         "callback_url":"http:\/\/YOURAPPURL\/index.php?action=callback",
         "fields":[
            "location"
         ],
         "active":true
      }
   ]
}

It’s important to note that for security reasons, the POST request made by Facebook’s servers to your endpoint will never actually contain the data that changed but only the field.

This is what a query from Facebook's servers to your endpoint may look like:

{
   "object":"user",
   "entry":[
      {
         "uid":"499535393",
         "id":"499535393",
         "time":1326210816,
         "changed_fields":[
            "location"
         ]
      }
   ]
}

Once your endpoint gets called you can either query the Graph API immediately to fetch the new information or schedule it for a later call (next user login for example).

You can find more information about the Real-Time Updates API here.

Today we are announcing new ways to drive greater discovery and engagement with games on Facebook, including games stories in News Feed and a games Timeline unit. We are also testing the addition of a prominent link to app requests on the homepage, a games-only activity feed and changes to the live ticker.

Enabling social discovery of games through News Feed

After launching games stories in mobile feed, we are now bringing this feature to Facebook.com. Gamers and non-gamers alike will see stories that list games their friends are playing the most. These stories are designed to bring new users and significant re-engagement to games by encouraging users to discover games their friends are playing. We will continue to refine the design of these stories based on performance.

You can track referral traffic from these stories by referring to your app insights. Go to the Open Graph tab and look for the Action: Play in the drop down on the top.

Showcasing games on timeline

All users now have the option to have their games activity appear on timeline. We recently launched a new Timeline unit that deeply integrates a user's top game activity over a given period of time into their timeline. This unit highlights the games users play the most, as well as top scores and achievements, allowing for quick re-engagement for the user and discovery among friends.

Outstanding App Request on the home page

We are testing a new link to outstanding games and apps requests on the upper right corner of the home page. The new link will increase the visibility of outstanding requests and is designed to drive more traffic to games and apps.

Games-only activity feed

We are testing a new games-only feed with friends' game activity on the Apps and Games dashboard. The "Friend Activity" sub-menu sits directly beneath the "Apps and Games" bookmark in the left hand navigation and is accessible to users who visit the dashboard.

Updating the games and apps ticker

As we work to optimize the canvas experience, we've found the live ticker alongside games and apps has not been a substantial driver of traffic. As a result, we are experimenting with removing the current version of the ticker on games and apps pages, and are exploring other ways to improve and simplify the games experience. We will continue to show the bookmarks on games and apps pages, which drive significant traffic and re-engagement.

Reminder: Removing App Profile Pages

On February 1st, we will remove all App Profile Pages. If you haven't already, follow our instructions to migrate your Likes and vanity URL to an existing Facebook page.

We continue to work on additional features to drive greater discovery and engagement with games and apps. Please provide your thoughts and feedback in the comment below.

Over a year ago, we introduced Single Sign-On (SSO) for Android and iOS. Today, more than 350 million active users currently access Facebook through their mobile devices. Users logged into the Facebook for iOS or Facebook for Android app can use the “Login with Facebook” button and, in one-click through a permissions dialog, login to your app. This saves users from typing in an e-mail address and password for apps that require registered users. Since the launch of SSO, developers implementing it in their apps have enjoyed increased user registrations and access to the Graph API to build in-app social experiences.

SSO Product Update

We have made significant stability and performance improvements in SSO as well as making it a core part of enabling Social Mobile App Discovery that we announced last October. In addition, we created a simpler authentication flow for users who have already authenticated your app. If a user has previously given your app the requested permissions, SSO will immediately pass an OAuth 2 access token back to your app. For example, if you already have a connected Facebook user on your website or canvas app, users will be able to login faster into your mobile native apps.

Pro-tip 1: Include Facebook Login at User Registration

Apps will often only use SSO and Facebook Login when asking the user to enable Facebook features in the app. You should also include Facebook Login anywhere you prompt the user to Register for your app, often times when users launch your app for the first time. Users can enjoy a simplified registration process, and you can request the same information, such as e-mail address, that you would normally collect manually from the user.

Pro-tip 2: Store the user’s session in your app

After your user authenticates for the first time, you should immediately store the authentication result locally. This way, you can keep the user logged-in to your app without having the user re-authenticate each time. Here are some Android and iOS Code samples that demonstrate how you can easily do this in your app:

iOS Example:
In the fbDidLogin delegate method, when the user has logged in via SSO, save the session:

- (void)fbDidLogin {
  NSUserDefaults *defaults = [NSUserDefaults standardUserDefaults];
  [defaults setObject:[facebook accessToken] forKey:@"FBAccessTokenKey"];
  [defaults setObject:[facebook expirationDate] forKey:@"FBExpirationDateKey"];
  [defaults synchronize];
}

Then, when your app starts in the future, set the accessToken and expirationDate in your Facebook object if they exists:

NSUserDefaults *defaults = [NSUserDefaults standardUserDefaults];
if ([defaults objectForKey:@"FBAccessTokenKey"]
  && [defaults objectForKey:@"FBExpirationDateKey"]) {
  facebook.accessToken = [defaults objectForKey:@"FBAccessTokenKey"];
  facebook.expirationDate = [defaults objectForKey:@"FBExpirationDateKey"];
}

Android Example:
When the user has logged in via SSO, save the session:

Editor editor = context.getSharedPreferences("facebook-session", 
                                             Context.MODE_PRIVATE).edit();
editor.putString("access_token", session.getAccessToken());
editor.putLong("expires_in", session.getAccessExpires());

When you app starts, in onCreate, restore the session if it exists:

SharedPreferences savedSession = context.getSharedPreferences
                                 ("facebook-session",Context.MODE_PRIVATE);
session.setAccessToken(savedSession.getString("access_token", null));
session.setAccessExpires(savedSession.getLong("expires_in", 0));

Pro-tip 3: Request only the permissions your app needs

We have streamlined the SSO permissions dialog, along with all permission dialogs in our recently announced Improved Auth Dialog. You should only request the permissions you need to get the user registered and using your app’s social features.

As part of our ongoing efforts to improve privacy protections for Facebook users, we've deprecated the 'offline_access' permission. Instead, you now have the option to extend the expiration of existing, valid access tokens for a limited amount of time without requiring the user to login again. Learn more about upgrading access tokens. Also, many apps incorrectly ask for 'publish_stream' when using our Feed Dialog. Your app only needs 'publish_stream' if it will be publishing to the user’s feed programmatically with the Graph API.

Pro-tip 4: Complete all iOS and Android Fields in your App Settings

Be sure to fill out every field related to your app in your app settings in the Native iOS App and the Native Android App fields. You can access these app settings for your app here. On iOS, If these fields are not configured, we will not be able to drive traffic to your app or the iOS App Store. In addition, we use the iOS Bundle ID to streamline authentication for users who have already authenticated your app.

In the coming weeks, we will be posting additional best practices for leveraging the Facebook Platform in iOS and Android Apps. Implementing SSO is the first step to taking advantage of improved distribution and engagement with the Facebook Platform in these environments.

Get started with our step-by-step documentation and sample code available in the iOS Getting Started and Android Getting Started guides.

This week we announced how to implement flashHideCallback to support "wmode=window". We are also announcing the following changes:

Getting SubscribedTo and Subscribers via Graph API

We are now providing the ability of reading a user's subscribers and subscribees list via the Graph API. To access this information, your app is required to have the user_subscriptions permission for the user, and friends_subscriptions permission for their friends' info. Refer to the documentation for SubscribedTo and Subscribers for more details.

To access a user's subscribers list, issue an HTTP GET request to the subscribers connection like the following:

https://graph.facebook.com/USER_ID/subscribers?access_token=...

Similarly, to access a user's subscribees list, issue an HTTP GET request to the subscribedto connection.

https://graph.facebook.com/USER_ID/subscribedto?access_token=...

The following PHP example demonstrates how to read the subscribed-to list:

<?php
  $app_id = 'YOUR_APP_ID';
  $app_secret = 'YOUR_APP_SECRET';
  $my_url = 'YOUR_URL';

  $code = $_REQUEST["code"];

  if (!$code) {
    // user_subscriptions and  friend_subscriptions permissions 
    // are required
    $dialog_url = "http://www.facebook.com/dialog/oauth?client_id="
     . $app_id . "&redirect_uri=" . urlencode($my_url)
     . "&scope=user_subscriptions";
    echo('<script>top.location.href="' . $dialog_url . '";</script>');
  } else {
    $token_url = "https://graph.facebook.com/oauth/access_token?client_id="
     . $app_id . "&redirect_uri=" . urlencode($my_url)
     . "&client_secret=" . $app_secret
     . "&code=" . $code;
    $access_token = file_get_contents($token_url);

    // Get request for the subcribed-to list
    $subscribedto_url =
      "https://graph.facebook.com/me/subscribedto?"
     . "access_token=".$access_token;
    $subscribedto_resp_obj =
      json_decode(file_get_contents($subscribedto_url), true);

    // Parse the return value and get the array of people subscribed to.
    // This is in returned in the data[] array
    $subscribedto = $subscribedto_resp_obj['data'];

    print_r($subscribedto);
  }
?>

Improved Search Results on the Developer Site

We improved search results on the Dev Site. Search now includes Technical Q&A from Stack Overflow and Bugs. You can also filter your results to only show the type of information you are looking for (e.g., blog posts, documentation, API reference, technical Q&A, bugs).

manage_notifications Permission Now Required for Managing a User's Notifications.

As announced on the blog on July 29, 2011 and on the Roadmap, to read or manage a user's notifications we now require the manage_notifications permission. The "Require manage_notifications" migration has now been removed per our 90-day breaking change policy. For more information, see the User object documentation.

Upcoming Breaking Changes on February 1st 2012

• Removing FeatureLoader JavaScript SDK. As part of the OAuth2 migration, we announced that the FeatureLoader SDK is no longer supported as of October 1st, 2011. On February 1st 2012, we will remove FeatureLoader. Please ensure that your app is using the JS SDK.
• Removing canvas_name Field from Application Object We will be deprecating the canvas_name field in favor of namespace field on the application object on February 1st 2012.
• Removing App Profile Pages We will be deleting all App Profile Pages and redirecting all traffic directly to the App on February 1st 2012. For more information, please refer to the blog post.
• Removing REST support for Ads API We will be removing REST support for the Ads API on February 1st 2012. All Ads API developer must move their applications to use the Graph API.
• Improved Auth Dialog On February 1st 2012, all apps will be enabled for the improved dialog, but those that haven’t fully configured their dialog can disable the setting in the Developer App until February 15, at which time it will be turned on for all apps.

New Breaking Changes

• Pages Insights Metrics Deprecations. We are in the process of deprecating some old Page Insights. We announced this in a number of forums, but failed to outline this change in our Platform Roadmap per our breaking change policy. Our apologies. You can find a full list of the Insights to be deprecated from the Insights documentation. These Insights will be completely removed from API on Feb 15th 2012. Please make all necessary updates as soon as possible so that you can transition smoothly.

• Throwing an Exception for Invalid filter_key. We will throw an exception if you try to query the stream FQL table with an invalid filter key. Currently if you call stream.get with an invalid filter_key value, the query silently fails, and with this change we will be throwing an exception. Refer to FQL stream documentation for details on using a filter_key. This change will take effect on May 1st 2012.

Please refer to the Platform Roadmap for more info.

Bug Activity from 1/18/12 to 1/24/12

Bugs fixed from 1/18/12 to 1/24/12

Facebook Stack Overflow Activity

Activity on facebook.stackoverflow.com this week:

• 145 questions asked
• 39 answered, 27% answered rate
• 86 replied, 59% reply rate

One of the Pro-Tips we mentioned late last year in our Games Tutorial to Developers creating Flash based Apps was to use wmode=opaque whenever possible. Setting wmode to any value other than "opaque" or "transparent" prevents any HTML content from being displayed at a higher z index than the Flash object. This results in Dialogs, Notifications and Ticker Flyouts being displayed under the Flash object and creates a pretty poor user experience on Canvas.

As a result when Canvas Apps set wmode to "window" or "direct" Facebook automatically hides the Flash object when any Dialogs, Notifications or Ticker Flyouts are opened. To help improve the user experience we have recently introduced a new parameter for FB.init in the JavaScript SDK called flashHideCallback. This allows developers to specify their own behavior for the auto hiding of Flash objects with wmode=window or direct, so long as the custom behavior completes in 200ms or less. After 200ms we will hide the Flash Object automatically regardless.

This How-To will walk you through the process of creating a temporary dynamic screenshot of your Flash App and replacing the Flash Object with this image within 200ms. This allows Dialogs to display correctly and creates a more pleasing user experience.

The How-To is divided into the following sections:

1. Creating a Dynamic Screenshot in Flash
2. Enabling ActionScript to JavaScript Communication
3. Using a Data URI
4. Setting up the flashHideCallback Functionality
5. Source Code for the Example App

Developers are expected to be familiar with JavaScript and ActionScript 3.0 in order to continue.  

Creating a Dynamic Screenshot in Flash

The first step will be to implement a method within your Flash App that creates a dynamic screenshot of the Stage object, compresses this into a JPEG format and then Base64 encodes this string. Fortunately there are public libraries available that will take care of most of these steps. For this example we will use: http://www.blooddy.by/en/crypto/ or feel free to use any lib that you prefer.

Next we will create the ActionScript exportScreenshot method that will return our screenshot data string, ready for use.

ActionScript

import by.blooddy.crypto.Base64;
import by.blooddy.crypto.image.JPEGEncoder;

...

private function exportScreenshot():String {
  var scale:Number = 0.25;
  var result:String = null;
  var blurFilter:BlurFilter = new BlurFilter(3, 3, BitmapFilterQuality.HIGH);

  var bData:BitmapData = new BitmapData(stage.stageWidth * scale,
    stage.stageHeight * scale,false,0x0);
  var matrix:Matrix = new Matrix();
  matrix.scale(scale, scale);

  bData.draw(stage, matrix);
  bData.applyFilter(bData, bData.rect, new Point(0, 0), blurFilter);

  var jpgBytes:ByteArray = JPEGEncoder.encode(bData,80);
  if (jpgBytes) {
    var screenshotBase64:String = Base64.encode(jpgBytes);
    if (screenshotBase64) {
      result = screenshotBase64;
    }
  }

  return result;
}

Walking through the code line by line you will notice that we are scaling the image to 25% of the full Stage dimensions. This is to reduce the size of our screenshot image and increase overall performance. Next we apply a BlurFilter to smooth out the jagged edges that result. Finally we encode our Bitmap as a JPEG, base64 encode it and then return the string.  

Enabling ActionScript to JavaScript Communication

Now that we have a method in our Flash App that can create a dynamic screenshot image we will need to support JavaScript communication from within the Flash Object. This will allow us to create a screenshot dynamically through a JavaScript call.

To do this we will need to import the ExternalInterface class in our Flash App and register a callback method.

ActionScript

import flash.external.ExternalInterface

...

ExternalInterface.addCallback('exportScreenshot', exportScreenshot);

The code registers a callback method called exportScreenshot in JavaScript allowing us to call our ActionScript method of the same name from JavaScript directly.  

Using a Data URI

Next we will create a image HTML element that will contain our dynamic screenshot and replace the Flash Object temporarily. To implement this we will use a Data URI allowing us to define the image data inline without having to make any requests back to a web server, increasing our performance.

Note: This is only available in modern browsers, Internet Explorer 8 and above. For IE7 and below you will have to fallback to a static image and cannot use the method described in this How-To.

In the HTML below we define a div HTML element that will contain our Flash content and directly underneath, a div HTML element that contains our img element that will hold our screenshot image. Finally we set both of these elements to have absolute position within a relative positioned parent. This allows us to place the img element beneath our Flash Object.

HTML

<div id="allContent" style="position:relative;">
  <div id="flashContent" style="position:absolute">
    <div id="flashHolder"></div>
  </div>
<div id="imageContent" style="position:absolute; top: -10000px;">
  <img id="screenshotObject"
    src="blank.gif"
    style="margin: 0 auto; display:block;" />
</div>

After we call the exportScreenshot method from JavaScript to get our dynamic screenshot, we set the dimensions of our img element to match the Flash Object, move the Flash Object out of the display area and put the screenshot image in it's place.

JavaScript

// Call the Flash Actionscript method to create the dynamic screenshot
var screenshotData =
  document.getElementById('flashObject').exportScreenshot();

// Set the screenshot image data as a base64 encoded data URI
// in the img src attribute
document.getElementById('screenshotObject').src = 'data:image/jpeg;base64,'
  + screenshotData;

// Set the screenshot img dimensions to match the Flash object tag.
document.getElementById('screenshotObject').width = flashObject.width;
document.getElementById('screenshotObject').height = flashObject.height;
  
// Move the Flash object off the screen and put the screenshot in it's place
document.getElementById('flashContent').style.top = '-10000px';
document.getElementById('imageContent').style.top = '';

Setting up the flashHideCallback Functionality

The last step is putting all of this code together and executing it based on the flashHideCallback callback. To do this, we wrap our JavaScript code (above) into a function called displayFlashScreenshot and create a new method hideFlashScreenshot which will do the reverse: hide our screenshot and then display our Flash Object again. Basically, when a Dialog is opened we want to execute displayFlashScreenshot to display our screenshot and when the Dialog is closed we want to execute hideFlashScreenshot to display our Flash content.

Next we create a new method onFlashHide to handle the open/close state and assign it to the flashHideCallback parameter in FB.init. In onFlashHide we check the info.state property and then call the corresponding JavaScript method.

JavaScript

function displayFlashScreenshot() {
  // Call the Flash Actionscript method to create the dynamic screenshot data
  var screenshotData =
    document.getElementById('flashObject').exportScreenshot();

  // Set the screenshot image data as a base64 encoded data URI
  // in the img src attribute
  document.getElementById('screenshotObject').src = 'data:image/jpeg;base64,'
    + screenshotData;

  // Set the screenshot img dimensions to match the Flash object tag.
  document.getElementById('screenshotObject').width = flashObject.width;
  document.getElementById('screenshotObject').height = flashObject.height;
        
  // Move the Flash object off the screen and place the screenshot img
  document.getElementById('flashContent').style.top = '-10000px';
  document.getElementById('imageContent').style.top = '';
}

function hideFlashScreenshot() {
  // Move the screenshot img off the screen and place the Flash object
  document.getElementById('flashContent').style.top = '';
  document.getElementById('imageContent').style.top = '-10000px';
}

function onFlashHide(info) {
  if(info.state == 'opened') {
    displayFlashScreenshot();
  } else {
    hideFlashScreenshot();
  }
}

FB.init({
  appId  : 'APP_ID',
  hideFlashCallback : onFlashHide
});

For more information on the flashHideCallback parameter see the JavaScript SDK Docs.  

Full Source Code for the Example App

Download the source code for the Example App which includes the HTML, JavaScript and ActionScript code referenced in the examples above.

This week, we launched the improved auth dialog and over 60 new Open Graph apps.

Approving Open Graph Actions

We are now approving Open Graph Actions. If you are new to the Open Graph, please review the Tutorial on how to use the Open Graph to integrate your app with Facebook. Please review and check your Actions against the required criteria prior to submission.

Writing Questions via Graph API

We recently announced the ability to read questions via the Graph API. We are now adding the option to write them. To create a question for the current user, issue an HTTP POST to the questions connection like this:

  curl -F 'access_token=...' \
       -F 'question=What is your favorite color?' \
       https://graph.facebook.com/me/questions

Here's a PHP example that shows the optional parameters: options and allow_new_options -- and how to post a question as a Page using its access token:

<?php
  $question = 'What are you doing this weekend?';
  $options = json_encode(array('Hiking','Watching a movie','Hacking'));

  $page_id = 'YOUR_PAGE_ID';
  $app_id = 'YOUR_APP_ID';
  $app_secret = 'YOUR_APP_SECRET';
  $my_url = 'YOUR_URL';

  $code = $_REQUEST["code"];

  echo '<html><body>';

  if (!$code) {
    // manage_pages permissions is required for accounts the user
    // has access to, and posting to the Page
    $dialog_url = "http://www.facebook.com/dialog/oauth?client_id="
     . $app_id . "&redirect_uri=" . urlencode($my_url)
     . "&scope=manage_pages";
    echo('<script>top.location.href="' . $dialog_url . '";</script>');
  } else {
    $token_url = "https://graph.facebook.com/oauth/access_token?client_id="
     . $app_id . "&redirect_uri=" . urlencode($my_url)
     . "&client_secret=" . $app_secret
     . "&code=" . $code;
    $access_token = file_get_contents($token_url);
    $accounts_url = 
         "https://graph.facebook.com/me/accounts?" . $access_token;
    $response = file_get_contents($accounts_url);

    // Parse the return value and get the array of accounts - this is
    // returned in the data[] array.
    $resp_obj = json_decode($response,true);
    $accounts = $resp_obj['data'];

    // Find the access token for the Page
    $page_access_token = '';
    foreach($accounts as $account) {
         if($account['id'] == $page_id) {
           $page_access_token = 'access_token=' . $account['access_token'];
           break;
         }
    }

    // Post the question to the Page
    $post_question_url = 
        "https://graph.facebook.com/" . $page_id . '/questions' .
    "?question=" . urlencode($question) .
    '&options=' . urlencode($options) .
    '&allow_new_options=false' .
    "&method=post&" . $page_access_token;

    echo file_get_contents ($post_question_url);
  }
  echo '</body></html>';
?>

Questions may be removed by issuing an HTTP DELETE to their id. More information is available in the Question documentation, User documentation, and Page documentation.

Subscribe to the Developer and HTML5 blog

We recently built an Email Settings dashboard that lets you easily manage your subscriptions to the Developer and HTML5 blog. To access your email settings, click on the arrow on the top right and select "Email Settings."

Improved Search typeahead on the Dev Site

We want to help you more quickly access the information you need on the Developer Site. The search typeahead now includes Bugs along with Apps and Documentation.

Policy Training Videos

We added two policy training videos to help new developers better understand our Platform Policies and Promotion Guidelines.

Upcoming Breaking Changes

• Removing FeatureLoader JavaScript SDK. As part of the OAuth2 migration, we announced that the FeatureLoader SDK is no longer supported as of October 1st, 2011. On 2/1/2012, we will remove FeatureLoader. Please ensure that your app is using the JS SDK.
• Removing canvas_name Field from Application Object We will be deprecating the canvas_name field in favor of namespace field on the application object on 2/1/2012.
• Removing App Profile Pages We will be deleting all App Profile Pages and redirecting all traffic directly to the App on 2/1/2012. For more information, please refer to the blog post.
• Removing REST support for Ads API We will be removing REST support for the Ads API. All Ads API developer must move their applications to use the Graph API.
• Improved Auth Dialog On February 1, 2012, all apps will be enabled for the improved dialog, but those that haven’t fully configured their dialog can disable the setting in the Developer App until February 15, at which time it will be turned on for all apps.

Please refer to the Platform Roadmap for more info.

Bug Activity from 1/11/12 to 1/17/12

Bugs fixed from 1/11/12 to 1/17/12

Facebook Stack Overflow Activity

Activity on facebook.stackoverflow.com this week:

• 244 questions asked
• 87 answered, 36% answered rate
• 165 replied, 68% reply rate

At f8, we announced Timeline and the Open Graph - the next generation of the platform which enables people to tell their stories through the apps they use. The Open Graph has already had a significant impact on music, news, and video, but this was just the beginning. Starting today, developers can build apps that let people add anything they love to their Timelines - whether it is eating, traveling, shopping, running or taking pictures.

As a part of the this launch, more than 60 apps are going live today - including Pinterest, Rotten Tomatoes / Flixster, Foodspotting, Gogobot, and more. These are great examples of how the Open Graph brings experiences to Facebook. The developers took things that users already enjoy and made it easy for users to express them on their timeline.

If you are new to Open Graph, please check out the tutorial on how to use the Open Graph to integrate your app with Facebook. If you've already submitted Open Graph actions, we are starting to approve actions that meet our guidelines today, and hope to have all actions previously submitted approved within the next month.

The apps launching today are just starting to demonstrate the types of self-expression that are possible with the Open Graph. There are many more stories to tell and great apps to tell them. Get started today!