Marketing API Version
Action Spec Reference

Action Spec Reference

Overview

Action specs are used to describe actions people have taken on Open Graph objects via an application or an on-Facebook object directly. Action specs are comprised of Actions and Objects, each of which is a key value pair.

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>:<action>"]

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

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

The full action-object pair action spec is then

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

On-Site Actions

Below lists 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 like so:

 {"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

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.

Examples

For an example App with the namespace flightsim which has an action called fly, you can specify the fly actions taking place in that app with the following syntax

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

If that same fly action takes place using an object type called plane you can 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 what actions are taken by users interacting with your ad. Tracking specs will only track, it will not optimize for that action nor does it charge based on that action. In order to specify tracking specs, you need an additional field in the ad, named tracking_specs that takes an action spec.

Conversion specs allow advertisers using Optimized CPM to optimize ad delivery for specific actions and also include those actions in conversion reports. In order to specify conversion specs, you need an additional field in the ad, named conversion_specs that takes an action spec. If conversion_specs are specified in an ad which is not eligibile to be optimized based on the provided bid, we will 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.7/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.7/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.7/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.7/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.7/act_<AD_ACCOUNT_ID>/ads