New Design Platform Changes

From Facebook Developer Wiki

Jump to: navigation, search

With the new design comes a series of new API calls and FBML tags. In addition, there are changes to existing Platform elements (including API calls, FBML tags, profile integration points, and session keys) of which you should take note.

Contents

[edit] Registering Templates: New API Methods

Since each News Feed-worthy story can potentially be rendered in one line, short, or full versions, Facebook encourages you to register all your templates ahead of time, using a new API method, feed.registerTemplateBundle. This method stores all the registered templates in whatever capacity Facebook finds suitable, and returns a unique integer identifier that the developer can use to publish actual stories using that template bundle. Other API methods can be used to extract information about any or all of an application’s registered template bundles.

  • feed.registerTemplateBundle: Builds a template bundle around the specified templates, registers them with Facebook servers, and responds with a template bundle identifier that can be used to identify your template bundle to other feed-related API calls.
  • feed.getRegisteredTemplateBundles: Retrieves the full list of all the template bundles registered by the requesting application.
  • feed.getRegisteredTemplateBundleByID: Retrieves information about a specified template bundle previously registered by the requesting application.
  • feed.deactivateTemplateBundleByID: Deactivates a previously registered template bundle.
  • feed.publishUserAction: Publishes a story on behalf of the user owning the session, using the specified template bundle. Unlike the previous four API calls, this method requires an active session key in order to be called.

[edit] Application Info Sections: New API Methods and FBML Tag

Users can personalize the Info tab on their profiles by adding application info sections, which are structured sections of application information, like a list of best friends or favorite books.

  • profile.setInfo: Configures an application info section that the specified user can install on the Info tab of her profile.
  • profile.getInfo: Returns the specified user’s application info section for the calling application.
  • profile.setInfoOptions: Specifies the objects for a field for an application info section. These options populate the typeahead for a thumbnail.
  • profile.getInfoOptions: Returns the options associated with the specified field for an application info section.
  • fb:add-section-button: Renders an Add to Info button on an application’s canvas page, which allows a user to add a new application info section to the Info tab of the profile. Takes a section="info" parameter that sets the title of the section.

[edit] Integrating an Application into a User Profile

The integration points that currently appear on the application add page are being decentralized throughout the profile. Users can decide how to integrate the application into their profiles at those integration points as well as the new integration points (like tabs). The following table illustrates how users will interact with the integration points that are currently on the add page.

Integration Point New Behavior
Receiving email You need to ask the user to approve an extended permission before you can send the user email. Use the fb:prompt-permission tag to prompt the user to approve.
Adding a profile box A user's current application boxes will be migrated over to the new profile and appear either on the main profile left column or the “Boxes” tab, as previously described. Users can also add a profile box to the main profile by clicking an Add New Profile Section button which the application can insert into their canvas pages via the fb:add-section-button FBML tag.
Left side navigation link Users can directly bookmark applications they are using.
Profile action link There are no profile action links for third party applications. Instead, users interact with their friends using applications in the Publisher box.
Feed stories By default, applications can send Feed stories to users. Users can choose to opt out of having applications send Feed stories.
Accessing user information The user grants an application access to his information when the user logs in and accepts the application's Terms of Service.

[edit] Changes to Existing Platform Components

Some Platform API methods and FBML tags are changing to accommodate the new design.

Call/Tag Change
profile.setFBML Now has a new parameter, a string called profile_main that contains the FBML for the application profile box on the main part of the user's profile.

Also, the profile_action parameter is being deprecated.

require_add You should use require_login instead. If you use require_login, it will open a simple Ajax authorization window instead of requiring a redirect to another page at all.

During the user preview period, require_add will continue to work on the old profile only. When calls are made to require_add on the new site, the user will get redirected to login.php instead. There will be a simplified authorization screen (a much friendlier version of login.php) that will be available on the sandbox soon.

We plan to deprecate require_add entirely in the future.

notifications.send With the new profile, there will be two types of notifications: general and announcement notifications. General notifications require active user sessions, which use the sending user's active session (with the same allocation amounts as today).
fb:profile-action With the new design, this tag is deprecated. There are no application profile action links.
fb:if-user-has-added-app This tag will behave like fb:if-is-app-user, so start using fb:if-is-app-user instead.
fb:visible-to-added-app-users This tag will behave like fb:visible-to-app-users, so start using fb:visible-to-app-users instead.

[edit] Changes to Session Keys

Note: You can read this FAQ, which should answer questions you might have about session key changes.

Since the flow for adding applications is changing, Facebook is going to stop granting infinite sessions to Web-based applications automatically, as is done today (we will announce on the Developer Blog when this change will occur). Desktop applications will continue to be granted a 24 hour session key, and mobile clients will continue to receive infinite sessions, like they currently do.

The session key you'll get will last one hour, so, for example, you won't be able to post News Feed stories for a user after the user's session expires. However, when the user approves your application's Terms of Service, you can offer the user the option to grant an infinite session (provided the user agrees to be kept logged into your application). And you can store a session key each time a user interacts with your application.

During the user preview period, this is how sessions will work:

  • We will still grant infinite sessions to your Web applications for users on the old profile.
  • Users who added your application on the old profile who then switch to the new profile, will continue to have an infinite session.
  • We'll grant temporary sessions to Web applications for new users on the new profile.

Temporary sessions last 1 hour, or until the user logs out, whichever comes first. Each time the user interacts with your application, we'll grant another session key or renew the existing one, so we recommend you store the most recent key.

After we launch the profile to all users, we will grant temporary sessions to all new users of Web applications. You can prompt your users to grant your application the offline_access extended permission.

At the same time, we're also removing sessions from many calls so there's less need for infinite sessions. For example, calls like profile.setFBML, photos.upload, and users.hasAppPermission no longer require session keys today. And we're changing more methods so you won't need a session key to do something when the user is offline, like send a notification. Check out the list below. We’ll add more methods to the list as we change them.

Our Developer Terms of Service prevent caching of data for longer than 24 hours, so this change mainly affects those developers who were batching up some calls that currently require an active session. The result is that we'll do a better job distinguishing whether certain API calls should require an active user session.

The following API calls no longer require a session key, and should not reference a session key. If you continue to pass valid session keys, we'll ignore them. We recommend you remove session keys from these calls now.

The following API calls no longer require a session key for Web applications, but if a session key is included, it must be valid and will use the current user. Desktop applications still require a session key for security reasons.

Retrieved from "http://wiki.developers.facebook.com/index.php/New_Design_Platform_Changes"
reference