Feed.registerTemplateBundle
From Facebook Developers Wiki
Contents |
[edit] Description
Builds a template bundle around the specified templates, registers them on Facebook, and responds with a template bundle ID that can be used to identify your template bundle to other Feed-related API calls. You need to register at least one bundle for each of your applications, if you have more than one. A template bundle consists of:
- An array of one line story templates
- An array of short story templates
- A single full story template
Each array consists of one or more templates in a given size. And each template consists of one or more tokens (for the story actor, friends, items, and so forth), some static text, and some FBML. Tokens must be wrapped in curly braces and asterisks, as in {*actor*}. The {*actor*} token must appear at the beginning of all one line templates and short story and full story template titles. More details are discussed below.
[edit] Usage note
You must be sending requests to http://api.new.facebook.com/restserver.php for this call to work.
[edit] Ordering Your Template Arrays
The order of the templates in an array is very important. In general, you want to specify the most flexible template first in the array. The most flexible template has the most tokens in it.
However, the more tokens you include in a template, the less likely those stories are to be aggregated.
To help illustrate what this means, consider the following array of one line templates:
- {*actor*} just purchased {*album*} by {*artist*} at FacebookMusic.
- {*actor*} just purchased music by {*artist*} at FacebookMusic.
- {*actor*} just purchased music at FacebookMusic.
The first template has three tokens -- for actor, album, and artist. The second template has two (for actor and artist), and the third template has just the actor token. Notice that the tokens in the first template are a superset of the tokens in the second template, and that the tokens in the second template are a superset of the tokens in the third template.
The first (that is, most flexible) template will always be used for Mini-Feed stories. This template should be as detailed and user-specific as possible. Any additional one line templates must include tokens that are strict subsets of the template that precedes it.
The last one-line template in the array must be the least flexible of all the templates in the bundle. Thus, it should include only tokens that are a strict subset of all other templates. These tokens are the bare minimum needed for aggregating stories.
Because you specify fewer tokens in each of the succeeding templates, you make it more likely that multiple Feed stories can be aggregated and increase the chances that your application story appears in users' News Feeds.
When considering these templates, the first template makes for the best story, but the last template has the highest aggregation potential. When you publish a story using feed.publishUserAction, you're posting the first version of the story to a user's Mini-Feed, and you're posting one of three different stories to that user's friends' News Feeds. Which of the three stories gets published depends on which one is deemed to be the most engaging. If four of your friends all purchase the same album, then we'd most certainly publish an aggregated story to your News Feed based on the first template. If four of your friends all buy different albums, then we might publish an aggregated story using the last template instead of a single-friend-specific story based on the first.
Short story templates work the same as the one line templates, in that the first template must be the most flexible, and the last one must be the most constrained.
However, the tokens used in a short story template are the union of the tokens used in its title and its body. Short story templates are optional, but if they're provided, they need to be expressed as an array of JSON-encoded dictionaries, where each dictionary includes the template_title and template_body and fields.
[edit] The Interaction Between Story Size and Aggregation
Note that the story size the user selects for a Mini-Feed story does not affect whether the story gets aggregated. Facebook always aggregates Feed stories whenever possible.
But the selection the user makes does correspond to the size of the story displayed in the user's friends' News Feeds. So if a user has a story appear as a one line story in her Mini-Feed, then that story appears as a one line story in her friends' News Feeds. If she chooses to display a story as a short or full story, then the story appears as a short story in her friends' News Feeds (full stories do not appear in News Feed, only Mini-Feed). When a number of stories are being aggregated, the short stories will get displayed in News Feed unless a majority of the actors involved in the story chose to display this story as a one line story.
Facebook will not aggregate multiple full stories, so you should provide just one full story template.
[edit] Parameters
| Required | Name | Type | Description | |
| required | api_key | string | The application key associated with the calling application. | |
|---|---|---|---|---|
| sig | string | An MD5 hash of the current request and your secret key, as described in the How Facebook Authenticates Your Application. | ||
| v | string | This must be set to 1.0 to use this version of the API. | ||
| one_line_story_templates | string | A JSON-encoded array of FBML templates that can be used to render one line Mini-Feed and News Feed stories. The array must be of length 1 or greater. If two or more FBML templates are specified, then the first one most be the most flexible of the templates, in that its token set is a proper superset of all other one line story template token sets in the same bundle. If two or more FBML templates are specified, then the last one must be the least flexible of the templates, in that its token set is a proper subset of all other one line story template token sets in the same bundle. The first template will always be used for one line Mini-Feed stories, but all of them will be considered for News Feed, and the one offering the best aggregation scenario will be used. | ||
| optional | format | string | Desired response format. Either XML (default) or JSON. | |
| short_story_templates | string | A JSON-encoded array of dictionaries, where each dictionary represents a short story template. Each dictionary should include two fields: template_title, which should be mapped to the FBML template used to render a short story’s title, and template_body, which should map to the FBML template used to render a short story’s body. Short story templates are optional, but if provided, it must be the case that the first short story template is the most flexible, in that its token set is a proper superset of all other short story template token sets in the same bundle. If two or more stories are provided, then the last one must be the least flexible, in that its token set is a proper subset of all other short story template token sets in the same bundle. The token set of a short story template is taken to be the union of the template_title and the template_body templates. The first template will always be used for short Mini-Feed stories, but all of them will be considered for News Feed, and the one offering the best aggregation scenario will be used. | ||
| full_story_template | string | A string that spells out a JSON-encoded dictionary with two fields: template_title, which should be mapped to the FBML template used to render a full story’s title, and template_body, which should map to the FBML template used to render a full story’s body. |
[edit] Example Requests
| 'one_line_story_templates' -> ["{*actor*} just bought {*album*} by {*artist*} from FacebookMusic.","{*actor*} have been listening to a lot of {*artist*} at FacebookMusic.","{*actor*} have been listening to a lot of their favorite artists at FacebookMusic."] 'short_story_templates' -> [{"template_title":"{*actor*} just bought {*album*} by {*artist*} from FacebookMusic.","template_body":"{*actor*} just bought {*album*} by {*artist*} from FacebookMusic, which includes {*song*}, {*song2*}, and {*song3*}."},{"template_title":"{*actor*} have been listening to a lot of {*artist*} at FacebookMusic.","template_body":"{*actor*} have been listing to a lot of {*artist*} at FacebookMusic. Click the image to listen to 30 seconds of his latest single, {*song*}."}] 'full_story_template' -> {"template_title":"{*actor*} just bought {*album*} by {*artist*} from FacebookMusic.","template_body":"Click below to watch the latest {*artist*} video, available only through FacebookMusic."} |
| Ruby Using RFacebook one_line_story_templates = [ '{*actor*} liked the cover of {*linked_edition*}', '{*actor*} have a favourite Comic Book cover' ] short_story_templates = [ { :template_title => '{*actor*} really liked the cover of {*linked_edition*}', :template_body => 'this is the body of the short story' }, { :template_title => '{*actor*} have a really favourite Comic Book Cover', :template_body => 'this is the body of a more generic short story that gets aggregated' } ] full_story_template = { :template_title => '{*actor*} liked the cover of {*linked_edition*} a lot', :template_body => '{*medium_cover*}<p>Do you like it too?</p>' } User.find(1).facebook_session.feed_registerTemplateBundle( :one_line_story_templates => one_line_story_templates.to_json, :short_story_templates => short_story_templates.to_json, :full_story_template => full_story_template.to_json ) bundle_id = 0 # get the bundle id from the response edition = Edition.find 'superman-675' User.find(1).facebook_session.feed_publishUserAction( :template_bundle_id => bundle_id, :template_data => { :linked_edition => "<a href=\"#{edition.url}\">#{edition.long_name}</a>", :medium_cover => "<img src='#{edition.cover_src(380)}' />" }.to_json ) |
[edit] Example Return XML
| <?xml version="1.0" encoding="UTF-8"?> <feed_registerTemplateBundle_response xmlns="http://api.facebook.com/1.0/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://api.facebook.com/1.0/...> 17876842716 </feed_registerTemplateBundle_response> |
[edit] Example Return JSON
| [17876842716] |
[edit] Response
This method returns a unique integer identifier that the developer can use to publish actual stories using that template bundle.
