Action Spec Targeting

Facebook is beta testing a targeting feature – called “Action Spec Targeting" -- for our interested Ads API partners. The new feature is designed to help advertisers target users based on actions they have performed. Because this feature is still in beta, we expect it to change. Please keep that in mind as you test this new feature in your campaigns and tools.

Action specs are used to describe actions people have taken on Open Graph objects via an application or on on-Facebook objects directly. Action Specs can be used to target Ads at users or friends of users who have performed a specific action, e.g. target an ad group at users who listened to music on a specific app or commented on a page post. Please review the the action spec documentation for more details on how action specs are defined.

Note: It is not possible to target a 'like' of a Facebook page via action specs (unless you have admin access to the page)

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

Targeting a user

Targeting by app activity

Users can be targeted based on the user's use of an app. For example, to target Facebook users who listen to music on the app with app ID 174829001234, specify the following for the ad group's targeting array:

"targeting={'countries':['US'],
'action_spec':[{'action.type':'music.listens','application':174829001234}]}"

To target an ad group at a user who performed a particular action an 'action_spec' parameter must be added to the targeting array for the adgroup. For information about using the targeting array, see the targeting section of the ad group object.

Targeting by app activity in a time range

By default, ads will only be created from stories that happened in the last 14 days. You can choose to specify another time range that's shorter than 14 days.

"targeting={'countries':['US'],
'action_spec':[{'action.type':'music.listens','application':174829001234, 'time_expire':9}]}"

Targeting by action and object

Users can be targeted based on them performing an action on an object. This object could be an on facebook object like a page post or an off facebook open graph object. For example, to target Facebook users who listen to a specific song (i.e., an open graph object), specify the following for the ad group's targeting array (Graph API):

"targeting={'countries':['US'],
'action_spec':[{'action.type':'music.listens','song':388773468386}]}"

Alternatively, you can include the URL to the open graph object rather than the open graph object ID.

"targeting={'countries':['US'],
'action_spec':[{'action.type':'music.listens','song':'http://URL_TO_OPEN_GRAPH_SONG_OBJECT'}]}"

Targeting by action, object and app

Users can be targeted based on them performing an action on an object via an app. This object could be an open graph object. For example, to target Facebook users who listen to a specific song (i.e., an open graph object), via an app with app ID 174829001234, specify the following for the ad group's targeting array:

"targeting={'countries':['US'],

'action_spec':[{'action.type':'music.listens','song':388773468386,'application':174829001234 }]}"

Excluding users from targeting

Users can be excluded from targeting based on them having performed a specific action. For example, to exclude users who have listened to music on the app with app ID 174829001234, specify the following for the Ad group's targeting array:

"targeting={'countries':['US'],
'action_spec_excluded':[{'action.type':'music.listens','application':174829001234}]}"

Anything which can be targeted by an action_spec can also be excluded by an action_spec_excluded. To exclude users who have performed a specific action from targeting an 'action_spec_excluded' parameter must be added to the targeting array for the adgroup. For information about using the targeting array, see the targeting section of the ad group object.

Note: The action_spec_negative is only valid for targeting, not Sponsored Story definition.

Targeting friends of a user

Friends of users can be targeted based on the user performing a specific actions on objects or via apps. For example, to target the friend of a Facebook users who listens to music on the app with app ID 174829001234, specify the following for the ad group's targeting array:

"targeting={'countries':['US'],
'action_spec_friend':[{'action.type':'music.listens','application':174829001234}]}"

Anything which can be targeted by an action_spec can also be targeted by an action_spec_friend. To target an ad group at friends of a user who performed a particular action an 'action_spec_friend' parameter must be added to the targeting array for the adgroup. For information about using the targeting array, see the targeting section of the ad group object.

Note: The action_spec_friend is only valid for targeting, not Sponsored Story definition.