Action Specs

Action Specs

The Open Graph is a simple, consistent view of the Facebook social graph that represents objects in the graph and the connections between them. Action Spec is a query language in the API for access to the Open Graph. It enables you to specify the sub-graph of interest to run and measure marketing activities on Facebook. Specify the action type and properties of the object of interest using selectors. For example, you can use it to Measuring your ad performance and see what actions people perform due to your ad

See the list of available on site objects and actions in Defining Action Specs.


Measuring Conversions using Action Spec

When running ads that point to a page, app, or website with social plugins, you can use the conversion spec to define specific actions to track back to ads 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.

If you are interested in driving awareness for a product, you can sponsor a video page post featuring that product. For the page post, 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 news feed posts, 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 page post 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 page post that points to an app or website, the default conversion spec will be used.

  • Ads 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

Considerations

You cannot create a conversion spec for an object for which you do not have permission to advertise. 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

Action Spec Reference

Overview

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

Action are the actions performed. The key is action.type and the value is the action performed. The action has of two parts: the namespace of the verb and the verb itself, such as myreaderapp:read. There is always at least one action per action spec with this format:

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

Objects are or more objects involved in the Action Spec. Objects are application performing actions, object acted upon, or both. The object has two parts: the selector and the value. The selector defines the object or the field of the object to match. The value matches object instances based on the selector. There is always at least one object per action spec. The format of object is as follows

 "<object>":["<value>"]

The full action-object pair action spec is then

 {"action.type":["<namespace>:<action>"], "<object>":["<value>"]}

On-Site Actions

Below are all on-site actions and attributes along with their connected object types. Attributes are additional details about an action. To use an attribute append it:

 {"action.type":["<namespace>:<action>"], "<object>":["<value>"], "<attribute>:["<value>"]}
ActionDescriptionConnected Object TypesAttributes

receive_offer

Claiming an Offer

offer

None

rsvp

Rsvping into an Event

event

response: valid values are yes, maybe, and no

like

Liking an object

page post object

None

checkin

Checking in to a Place

page

None

comment

Commenting on a Page post

post

None

post

Sharing a story

application post

None

photo_view

Viewing a photo

post

None

video_view

Viewing a video

post

None

video_play

Watching a video

post

None

link_click

Clicking on a link

post

None

vote

Voting on a question

question

None

follow

Following a question

question

None

apps.uses

Using an App

application

None

mention

Mentioning of a Page

page

None

app_install

Installing an app

application

None

credit_spent

Instances of spending credit in an app

application

None

tab_view

Viewing a page tab

page (specifying a page object is mandatory while specifying page.tab.name is optional)

None


On-site Objects

The table below lists all on-site objects and their attributes. Attributes are additional object types that are connected to the base object. To use an attribute append it like so:

 {"action.type":["<namespace>:<action>"], "<object>.<attribute>":["<value>"]}
ObjectDescriptionValueAttributes

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

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).

question

Specifies a question object

The ID of a question-poll

creator: The ID of the Page that posted this question

page

Specifies a Facebook Page

The ID of the Page

parent: The ID of the parent Page of this Page (if any)

tab.name: The name of a tab on the Page Timeline

post

Specifies a Page post, retrieved from the Page Timeline.

The ID of a Page post

author: The ID of the Facebook Page that published the post

wall: The ID of the Page or Event that the post was published to

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


Limits

  • 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.

Examples

For an App with the namespace flightsim with action fly, you can specify the fly actions in that app:

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

If that same fly action takes place using an object type called plane, specify the fly actions taking place against a specific instance of the plane object type with the following syntax

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

You can also specify multiple apps, multiple objects, or multiple action types (though this example is contrived to show the syntax, it would not make sense in a real app as the actions will belong only to a single app)

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

Measurement Examples

Tracking specs allow you to track actions taken by users interacting with your ad. Tracking specs only track; they do not optimize for that action nor are you billed based on that action. To specify tracking specs, use the ad object field tracking_specs that takes an action spec.

Conversion specs enables advertisers using Optimized CPM to optimize ad delivery for specific actions and include those actions in conversion reports. To specify conversion specs, use the ad object field conversion_specs that takes an action spec. If conversion_specs are specified for ads that are not eligibile to be optimized based on your bid, we automatically track the desired actions by including the desired action spec in the ads tracking_specs field.

Create an ad for an application with app ID 12345 and track installs of the app.

use FacebookAds\Object\Ad;
use FacebookAds\Object\Fields\AdFields;

$fields = array(
  AdFields::NAME => 'test',
  AdFields::ADSET_ID => <AD_SET_ID>,
  AdFields::CREATIVE => array(
    'creative_id' => <CREATIVE_ID>,
  ),
  AdFields::TRACKING_SPECS => array(
    'action.type' => 'app_install',
    'application' => <APP_ID>,
  ),
);

$ad = new Ad(null, 'act_<AD_ACCOUNT_ID>');
$ad->create($fields);
from facebookads.adobjects.ad import Ad

ad = Ad(parent_id='act_<AD_ACCOUNT_ID>')
ad[Ad.Field.name] = 'test'
ad[Ad.Field.adset_id] = <AD_SET_ID>
ad[Ad.Field.creative] = {
    'creative_id': <CREATIVE_ID>
}
ad[Ad.Field.tracking_specs] = {
    'action.type': 'app_install',
    'application': <APP_ID>
}
ad.remote_create()
Ad ad = new AdAccount(act_<AD_ACCOUNT_ID>, context).createAd()
  .setName("test")
  .setAdsetId(<AD_SET_ID>)
  .setCreative(
    new AdCreative()
      .setFieldId(<CREATIVE_ID>)
  )
  .setTrackingSpecs("{\"action.type\":\"app_install\",\"application\":\"" + <APP_ID> + "\"}")
  .execute();
String ad_id = ad.getId();
curl \
  -F 'name=test' \
  -F 'adset_id=<AD_SET_ID>' \
  -F 'creative={"creative_id":"<CREATIVE_ID>"}' \
  -F 'tracking_specs={"action.type":"app_install","application":"<APP_ID>"}' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.8/act_<AD_ACCOUNT_ID>/ads

Create a Page Post ad and track likes of the post.

use FacebookAds\Object\Ad;
use FacebookAds\Object\Fields\AdFields;

$fields = array(
  AdFields::NAME => 'test',
  AdFields::ADSET_ID => <AD_SET_ID>,
  AdFields::CREATIVE => array(
    'object_story_id' => '<POST_ID>',
  ),
  AdFields::TRACKING_SPECS => array(
    'action.type' => 'like',
    'post' => '<POST_ID>'_without_page,
    'post.wall' => <PAGE_ID>,
  ),
);

$ad = new Ad(null, 'act_<AD_ACCOUNT_ID>');
$ad->create($fields);
from facebookads.adobjects.ad import Ad

ad = Ad(parent_id='act_<AD_ACCOUNT_ID>')
ad[Ad.Field.name] = 'test'
ad[Ad.Field.adset_id] = <AD_SET_ID>
ad[Ad.Field.creative] = {
    'object_story_id': <POST_ID>
}
ad[Ad.Field.tracking_specs] = {
    'action.type': 'like',
    'post': post_id.split('_')[1],
    'post.wall': <PAGE_ID>
}
ad.remote_create()
Ad ad = new AdAccount(act_<AD_ACCOUNT_ID>, context).createAd()
  .setName("test")
  .setAdsetId(<AD_SET_ID>)
  .setCreative(
    new AdCreative()
      .setFieldObjectStoryId(<OBJECT_STORY_ID>)
  )
  .setTrackingSpecs("{\"action.type\":\"like\",\"post\":\"" + <POST_ID_WITHOUT_PAGE> + "\",\"post.wall\":\"" + <PAGE_ID> + "\"}")
  .execute();
String ad_id = ad.getId();
curl \
  -F 'name=test' \
  -F 'adset_id=<AD_SET_ID>' \
  -F 'creative={"object_story_id":"<POST_ID>"}' \
  -F 'tracking_specs={ 
    "action.type": "like", 
    "post": "<POST_ID>_without_page", 
    "post.wall": "<PAGE_ID>" 
  }' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.8/act_<AD_ACCOUNT_ID>/ads

Create a Page Post ad and track likes of the page.

use FacebookAds\Object\Ad;
use FacebookAds\Object\Fields\AdFields;

$fields = array(
  AdFields::NAME => 'test',
  AdFields::ADSET_ID => <AD_SET_ID>,
  AdFields::CREATIVE => array(
    'object_story_id' => <POST_ID>,
  ),
  AdFields::TRACKING_SPECS => array(
    'action.type' => 'like',
    'page' => <PAGE_ID>,
  ),
);

$ad = new Ad(null, 'act_<AD_ACCOUNT_ID>');
$ad->create($fields);
from facebookads.adobjects.ad import Ad

ad = Ad(parent_id='act_<AD_ACCOUNT_ID>')
ad[Ad.Field.name] = 'test'
ad[Ad.Field.adset_id] = <AD_SET_ID>
ad[Ad.Field.creative] = {
    'object_story_id': <POST_ID>
}
ad[Ad.Field.tracking_specs] = {
    'action.type': 'like',
    'page': <PAGE_ID>,
}
ad.remote_create()
Ad ad = new AdAccount(act_<AD_ACCOUNT_ID>, context).createAd()
  .setName("test")
  .setAdsetId(<AD_SET_ID>)
  .setCreative(
    new AdCreative()
      .setFieldObjectStoryId(<OBJECT_STORY_ID>)
  )
  .setTrackingSpecs("{\"action.type\":\"like\",\"page\":\"" + <PAGE_ID> + "\"}")
  .execute();
String ad_id = ad.getId();
curl \
  -F 'name=test' \
  -F 'adset_id=<AD_SET_ID>' \
  -F 'creative={"object_story_id":"<POST_ID>"}' \
  -F 'tracking_specs={"action.type":"like","page":"<PAGE_ID>"}' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.8/act_<AD_ACCOUNT_ID>/ads

Create an ad optimized for page likes and mentions:

use FacebookAds\Object\Ad;
use FacebookAds\Object\Fields\AdFields;

$fields = array(
  AdFields::NAME => 'test',
  AdFields::ADSET_ID => <AD_SET_ID>,
  AdFields::CREATIVE => array(
    'object_story_id' => <POST_ID>,
  ),
  AdFields::TRACKING_SPECS => array(
    'action.type' => ['like'],
    'page' => <PAGE_ID>,
  ),
);

$ad = new Ad(null, 'act_<AD_ACCOUNT_ID>');
$ad->create($fields);
from facebookads.adobjects.ad import Ad

ad = Ad(parent_id='act_<AD_ACCOUNT_ID>')
ad[Ad.Field.name] = 'test'
ad[Ad.Field.adset_id] = <AD_SET_ID>
ad[Ad.Field.creative] = {
    'creative_id': <CREATIVE_ID>,
}
ad[Ad.Field.tracking_specs] = {
    'action.type': ['like'],
    'page': <PAGE_ID>,
}
ad.remote_create()
Ad ad = new AdAccount(act_<AD_ACCOUNT_ID>, context).createAd()
  .setName("test")
  .setAdsetId(<AD_SET_ID>)
  .setCreative(
    new AdCreative()
      .setFieldObjectStoryId(<OBJECT_STORY_ID>)
  )
  .setTrackingSpecs("{\"action.type\":[\"like\"],\"page\":\"" + <PAGE_ID> + "\"}")
  .execute();
String ad_id = ad.getId();
curl \
  -F 'name=test' \
  -F 'adset_id=<AD_SET_ID>' \
  -F 'creative={"object_story_id":"<POST_ID>"}' \
  -F 'tracking_specs={"action.type":["like"],"page":"<PAGE_ID>"}' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.8/act_<AD_ACCOUNT_ID>/ads

Create an ad optimized for music.listen OG actions

use FacebookAds\Object\Ad;
use FacebookAds\Object\Fields\AdFields;

$fields = array(
  AdFields::NAME => 'test',
  AdFields::ADSET_ID => <AD_SET_ID>,
  AdFields::CREATIVE => array(
    'creative_id' => <CREATIVE_ID>,
  ),
  AdFields::TRACKING_SPECS => array(
    'action.type' => 'music.listens',
    'application' => <APP_ID>,
  ),
);

$ad = new Ad(null, 'act_<AD_ACCOUNT_ID>');
$ad->create($fields);
from facebookads.adobjects.ad import Ad

ad = Ad(parent_id='act_<AD_ACCOUNT_ID>')
ad[Ad.Field.name] = 'test'
ad[Ad.Field.adset_id] = <AD_SET_ID>
ad[Ad.Field.creative] = {
    'creative_id': <CREATIVE_ID>
}
ad[Ad.Field.tracking_specs] = {
    'action.type': 'music.listens',
    'application': <APP_ID>
}
ad.remote_create()
Ad ad = new AdAccount(act_<AD_ACCOUNT_ID>, context).createAd()
  .setName("test")
  .setAdsetId(<AD_SET_ID>)
  .setCreative(
    new AdCreative()
      .setFieldId(<CREATIVE_ID>)
  )
  .setTrackingSpecs("{\"action.type\":\"music.listens\",\"application\":\"" + <APP_ID> + "\"}")
  .execute();
String ad_id = ad.getId();
curl \
  -F 'name=test' \
  -F 'adset_id=<AD_SET_ID>' \
  -F 'creative={"creative_id":"<CREATIVE_ID>"}' \
  -F 'tracking_specs={"action.type":"music.listens","application":"<APP_ID>"}' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.8/act_<AD_ACCOUNT_ID>/ads