Introduction to Action Spec

What is the Action Spec?

The Open Graph presents a simple, consistent view of the Facebook social graph, uniformly representing objects in the graph and the connections between them. The Action Spec is a comprehensive and precise query language within the API that provides you with access to the Open Graph. The Action Spec enables you to specify the sub-graph of interest for the purpose of running and measuring marketing activities on Facebook. You can specify the action type and properties of the object of interest using selectors. In essence, selectors are the building blocks of an Action Spec query. You can apply these to a number of marketing applications such as:

Creating sponsored stories – filter for the stories you want people to see
Targeting your ads or sponsored stories – filter for the people you want to reach

The Action Spec is an extremely powerful framework that gives you complete and precise access to the entire social graph to manage and optimize your marketing presence on Facebook. See the list of available on site objects and actions in Defining Action Specs.

Defining Sponsored Stories from the Action Spec

Marketers can use the Action Spec for Sponsored Stories to selectively sponsor nearly any relevant action taken on any Facebook object. The Action Spec enables marketers to reach users with a wide range of relevant stories to achieve specific marketing objectives. Below are three examples of sponsored stories:

If you are interested in acquiring fans for your page, you can use “Page Like” sponsored stories shown to friends of users who have recently Liked your page. The Action Spec for this would be

{'action.type':'like', 'page': 'https://www.facebook.com/JaspersMarket'}

This Action Spec will select all the like actions that happened on the Jasper’s Market Facebook page located at https://www.facebook.com/JaspersMarket.

Note that {'action.type':'like', 'page': 130533530354972} would accomplish the same thing since 130533530354972 is the id for https://www.facebook.com/JaspersMarket.

If you are interested in driving awareness for a product, you can run a photo page post featuring that product and run ads and sponsored stories from that page post. You can then sponsor user comments, likes, and shares of that photo post as sponsored stories so that any engagement with the photo post will also be promoted to the friends of those who have engaged with that page post. All of these stories originate from your post, and because these stories lead with the voice of your fan, they are integral for spreading your message to friends of fans.

The Action Spec for the likes and comments would be:

{'action.type':['like', 'comment'],'post':[266401036768220]}

This Action Spec will select all the like and comment actions that happened on the page that is Jaspers Market. Here is an example of a page post comment sponsored story.

And you would create a separate Action Spec for the share:

{'action.type':'post', 'post.object': 266401036768220}

Finally, if you are interested in driving application installs or uses, you can use the Action Spec to boost a custom open graph action [Beta].

The Action Spec for this would be

{'action.type':''bookreader:rate',  'application': 12345678}

This Action Spec will select all the ‘rated’ actions that happened on the Application that is BookReader.

Because some sponsored stories are dependent on users’ interactions, available inventory (stories) may take time to accumulate. For example, if you are sponsoring page post likes, eligible stories to be sponsored will be based on the number of users who like that particular page post once its been posted.

Targeting using the Action Spec

The Action Spec can be used to target ads or sponsored stories based on connections that have been established as a result of a specific action. For example, using the Action Spec, you can target users (or friends of users) who listened to music on a specific application or commented on a specific page post. Action Spec Targeting is an extremely powerful way to segment your target audience based on connections they have made on the social graph. Except for a few action types (Page Likes, App Installs, and Credit Spent), you can target your ad or sponsored story using any action on any object. Below are three examples of ways you can use the Action Spec to target your ads and sponsored stories:

You can create a target audience based on users who have interacted with a specific page post. If you have a wide spectrum of product categories that you offer, you can target ads to users who have engaged with posts (liked, shared or commented) about a specific category to segment your audience.
You can use Open Graph actions as an indication of users’ interests and target them. For example, you can target users interested in a specific music genre by using the Action Spec to identify listens to the most popular artists in that genre across several music apps on Facebook.
Finally, you can use the Action Spec in combination with exclusion targeting to create a target audience based on Open Graph actions that they did not do. For example, you can target users who have installed your app but not used the app in the past 6 months in your app.

Action Spec Targeting Considerations

Similar to Sponsored Stories, you can use the Action Spec to target ads based on only actions that create stories that are eligible for News Feed. For example, you cannot use the Action Spec to target an ad based on users who have viewed a photo or played a video since neither of these actions creates a News Feed story.
For more information on Action Spec targeting, go here.

To learn more about how to define Action Specs see here.

Measuring Conversions using the Action Spec

When running ads that point to a page, application, or website with social plugins, you can use the conversion spec to define specific actions to track back to an ad group using multiple click and view through attribution windows. Conversion specs enable marketers to measure and optimize their ad campaigns to very specific downstream actions.

Below are three examples of ways you can use the Action Spec to measure the performance of your ads and sponsored stories.

If you are interested in driving awareness for a product, you can sponsor a video page post featuring that product as a sponsored story. For the sponsored story, you can set up a custom conversion spec to track actions such as:

Number of video plays on that page post
Number of video plays on any video on the page
Number of likes on that specific page post
Number of users posting on the page’s wall

If you are running an offer and sponsoring the offer claims through sponsored stories, you can set up the conversion spec to track actions such as:

Number of users who claimed the offer
Number of users who became fans of the page
Number of users who commented, liked, or shared any page post on the page

If you are promoting a page and interested in acquiring new fans, you can create a page like sponsored story and set up a custom conversion spec to track actions such as:

Number of page likes

Number of views of a specific page tab (e.g., “wall”). If you do not specify a conversion spec for a given ad or sponsored story that points to an application or website, the default conversion spec will be used.

Ads or sponsored stories that point to a page will be set up with “page_story” as the conversion spec. This will track any action that impacts the “people talking about this” metric (page likes, page post likes, comments, @mentions, check-ins, photo tags, page post shares (including offer shares), votes, follows, and offer claims)
App stories will be set up with “app_engagement” as the conversion spec. This will track "App install," "App used," and "credits spent" (does not include app shares)
Event ads will be set up with RSVPs- Number of RSVPs (yes and maybe) to an event

Action Measurement Considerations

You cannot create a conversion spec for an object for which you do not have permissions.
Because the default conversion spec for ads pointing to apps contains potentially sensitive insights, we will also disable the default conversion spec for app ads if those ads are created by someone who is not an admin of that app For more information on conversion specs, go here

Updated about 4 months ago

Best Practices

Reference

Specs

Advanced Targeting

Queries

Objects