Action Specs

Action specs are used to describe actions people have taken on Open Graph objects via an application or an on-Facebook object directly. Actions can be any verb e.g "Listen", "Watch", "Comment", "Played", "Purchase", "Drive", "Fly", "Drink" etc. Object can be any Open Graph object such as a song, book, product, virtual good etc. For background information about Open Graph actions, see the Open Graph tutorial

Note: Action specs are limited to be a maximum of 4096 characters in length.

Action specs are comprised of Actions and Objects each of which is a key value pair.

Action Spec action

The Action Spec action specifies the action being performed. The key to the action is always "action.type" and the value is the action being performed. The action being performed is comprised of two pieces of information; the namespace of the verb and the verb itself. e.g. myreaderapp:read, og:watch, incarapp:drive etc. There is always at least one action per action spec. The format of the action is as follows:

"action.type":["<namespace>:<verb>"]

Examples of actions are:

 "action.type":["flightsim:fly"]
 "action.type":["og:video.watch"]
 "action.type":["fashionapp:wear"]

Flightsim:fly and fashionapp:wear are custom actions defined by the developer of those apps. For more details on defining custom actions please review the Open Graph Tutorial

og:video.watch is a built in action. Read more about Built in action types.

Action Spec object

The Action spec object specifies one or more objects involved in the Action Spec. This object could be the application performing the action, an object the action is being performed on or a combination of the two. The object is comprised of two sections, the selector and the value. The selector defines the object and/or the field of the object to match and the value is used to match object instances based on the selector. There is always at least one object per action spec. The format of object is as follows

"<selector>":[<value>]

Examples of selector and values are:

 "song.musician":[68764758347] : This selects all songs where the musician is represented by ID 68764758347
 "application":[67568576783] : This selects the application with ID 67568576783
 "book.author":[66787648454] : This selects any book where the author is represented by the ID 66787648454

Objects in Action Spec can also be defined by URLs, for example:

  "book.author":["http://og.mybookapp.com/author.php?id=34342"] : Where http://og.mybookapp.com/author.php?id=34342 is the url of an Open Graph object identifying the author.

Example: Performing an action via an app

When a user flies a plane via a fight simulator app the user is said to have performed an action via that app. For example a user flying a plane in a flight simulator with an app ID of 174829001234 would be described as:

{"action.type":["flightsim:fly"], "application":[174829001234]}

In this case flightsim:fly is the name of the action being performed and 174829001234 is the app ID of the app the user is using fly the pane.

Example: Performing an action on an object

When a user flies a plane in a flight simulator app the user is said to have performed an action on the plane object. For example a user flying a Boeing 747 (Object ID 68764758347) in a flight simulator app would be described as:

{"action.type":["flightsim:fly"], "plane":[68764758347]}

In this case flightsim:fly is the name of the action being performed,"plane" is the selector of the object and 68764758347 is the object ID of the plane the user is flying.

Example: Performing an action on an object with an app

{"action.type":["flightsim:fly"], "plane":[68764758347], "application":[174829001234]}

In this case flightsim:fly is the name of the action being performed,"plane" is the selector of the object, 68764758347 is the object ID of the plane the user is flying and 174829001234 is the app ID of the app the user is using fly the pane .

Example: Grouping together actions and objects.

It is valid to have multiple actions and objects within a single action spec.

{"action.type":["flightsim:fly","flightsim:land","flightsim:crash"], 
"plane":[68764758347,68764712345,68764723424], 
"application":[174829001234, 174829001234]}

This example selects every valid combination of action, object and app.

It is also valid to group multiple action specs together, this will OR all of the action specs together. For example

[{"action.type":["flightsim:fly"],"plane":[68764758347], 
"application":[174829001234]},
{"action.type":["flightsim:land"], "plane":[68764712345], 
"application":[174829001234]}, 
{"action.type":["flightsim:crash"],  "plane":[68764723424], 
"application":[174829001234]}]

Restrictions for action specs

Please note the following restrictions for using action specs:

Every action spec must have at least one action type.
Every action spec must have at least one object reference. This reference can be an app or Open Graph object.
The action spec has two reserved keywords: "action.type" and "application". All other keys can come from an Open Graph definition.

Using Action Specs

Ad Targeting

Action spec can be used to target ads to users who have performed certain actions and to friends of those users. For more information on Action Spec Targeting, see the Action Spec Targeting Reference.

Conversion Specs Definition

Action spec can be used to define conversion spec for an ad group. For more information on defining conversion specs, see the Conversion Spec Reference.

Action Specs for Facebook Objects

This section details the action spec formats for various Facebook actions and objects that are referred to as on-site Action Spec here.

Examples of on-site actions are

Publishing a post
Sharing a post
Commenting on a post
Liking a post

Examples of on-site objects are

Page
Page (or user) post
Event
Video
Photo

Action spec models on-site objects and actions similar to Open Graph objects and actions. That is, on-site objects, like Open Graph objects, may have one or more attributes, and on-site actions, Open Graph actions, may have one or more connected object types.

This tables explain on-site objects, actions, and their attribute so that you can see how to mix and match on-site objects and actions for selecting a set of stories.

On-site Objects

Below table lists all on-site objects and their attributes.

Object	Description	Type	Attributes
`application`	Specifies an app Object	The ID of the app	None
`offer`	Specifies an Offer object	The ID of the Offer	`creator`: The ID of the Page that posted the Offer
`event`	Specifies an event object	The ID Of the Event	`creator`: The ID of the Page that created the Event
`domain` (deprecated)	Specifies an external domain	The ID or URL of the domain	this selector is being replaced by `object.domain`. `domain`: The ID of the domain that is claimed by an admin (see claiming your domain)
`object`	Specifies an external web page that implements Open Graph	The URL of the web page	`domain`: The URL of the domain e.g., `http://www.my-domain-name.com` or the name of the domain, e.g., `www.my-domain-name.com`, or the ID of a domain if it is claimed by an admin (see claiming your domain). Note that you no longer need to be an admin of a domain in order to boost its stories
`question`	Specifies a question object	The ID of a question-poll	`creator`: The ID of the Page that posted this question
`page`	Specifies a Page object	The ID of the Page	`parent`: The ID of the parent Page of this Page (if any) `tab.name`: The name of the Page app
`post`	Specifies a Page or a user's post object. Note that a user's post is not available for boosting unless it is a user's sharing of a Page post	The ID of a Page post	`author`: The ID of the Page that published the post `wall`: The ID of the Page or Event that the post was published on its wall `object`: The ID of an object that is attached to this post (e.g., a photo, a post, an event, etc.) or the URL of an external web page `domain` (deprecated): the ID of a domain that implements Open Graph. Note that the domain should be claimed by an admin (see claiming your domain) this selector is being replaced by `object.domain` (see above)

On-site Actions

Below table lists all on-site actions and attributes along with their connected object types.

Action	Description	Connected Object Types	Attributes	Application
`receive_offer`	Claiming an Offer	`offer`	None	`story_spec` `targeting_spec` `conversion_spec`
`rsvp`	Rsvping into an Event	`event`	`response`: valid values are `yes`, `maybe`, and `no`	`story_spec` `targeting_spec` `conversion_spec`
`like`	Liking an object	`page` `post` `object`	None	`story_spec` `targeting_spec` `conversion_spec` (available only for `page` and `post`)
`follow`	Subscribing to an object	`page`	None	`story_spec` `targeting_spec` (available only for `page`)
`checkin`	Checking in to a Place	`page`	None	`story_spec` `targeting_spec` `conversion_spec`
`comment`	Commenting on a Page post	`post`	None	`story_spec` `targeting_spec` `conversion_spec`
`post`	Sharing a story	`application` `post`	None	`story_spec` `targeting_spec` `conversion_spec` (available only for `post`)
`photo_view`	Viewing a photo	`post`	None	`conversion_spec`
`video_play`	Watching a video	`post`	None	`conversion_spec`
`link_click`	Clicking on a link	`post`	None	`conversion_spec`
`vote`	Voting on a question	`question`	None	`story_spec` `targeting_spec` `conversion_spec`
`follow`	Following a question	`question`	None	`conversion_spec`
`games.plays`	Playing a game	`application`	None	`story_spec` `targeting_spec`
`apps.uses`	Using an App	`application`	None	`story_spec` `targeting_spec` `conversion_spec`
`mention`	Mentioning of a Page	`page`	None	`conversion_spec`
`app_install`	Installing an app	`application`	None	`conversion_spec`
`credit_spent`	Instances of spending credit in an app	`application`	None	`conversion_spec`
`tab_view`	Viewing a page tab	`page` (specifying a page object is mandatory while specifying page.tab.name is optional)	None	`conversion_spec`

Examples

Select likes of a Page post whose ID is 12345

{'action.type':'like', 'post`:12345}

Select likes of a domain

{'action.type':'like', 'object.domain':'http://my-domain-name.com'}

Selects likes of a web page that implements Open Graph

{'action.type':'like', 'object':'http://my-example-domin.com/path-to-webpage'}

Select shares of a story about a domain whose ID is 12345 (e.g. a feed dialog on a website)

{'action.type':'post', 'post.object.domain': 12345}

Select shares of a story about a web page

{'action.type':'post', 'post.object':'http://my-example-domin.com/path-to-webpage'}

Select subscribe to a Page whose ID is 54321

{'action.type':'follow', 'page`:54321}

Select RSVPs responses of yes and maybe an Event whose ID is 1234456

{'action.type':'rsvp' , 'response':['yes','maybe'], 'event':123456}

Select shares of any story that was posted by a Page admin on a Page whose ID is 1234567.

{'action.type':'post', 'post.object.author': 1234567}

Updated about 2 months ago

Best Practices

Reference

Specs

Advanced Targeting

Queries

Objects

Defining Action Specs