Tracking and Conversion Specs

With Tracking Specs, you log actions taken by people on your ad. This feature does not optimize ads delivery for an action nor does it charge your ads account based on that action occurring.

In Marketing API v2.3 and earlier, Conversion Specs are ad settings for Optimized CPM. They optimizes ad delivery for specific actions and show those actions in conversion reports. After v2.4, conversion_specs is read-only. Use the optimization_goal on ad set to select ad delivery optimization.

Set Tracking Specs

Use with any bid type and creative. To specify tracking specs, you need an additional field in an ad, named tracking_specs. The tracking_specs field takes arguments identical to action spec. To create an ad, see ad creation.

Default Tracking Specs

For the following ad objectives, default tracking specs apply. If you change to the default spec, it will be appended to the existing spec rather than overwriting the existing one.

If your objective is NONE or App Install/Engagement Ads, the default tracking specs will be overwritten. If you want to have the defaults you must add them to your custom specs.,

You can use both string or array notation in the spec such as 'APPLICATION_ID' or ['APPLICATION_ID'].

  • CPM refers to billing_event=IMPRESSIONS, optimization_goal=IMPRESSIONS
  • CPC refers to billing_event=CLICKS, optimization_goal=CLICKS
  • oCPM refers to billing_event=IMPRESSIONS, optimization_goal set to an action
  • CPA refers to both billing_event and optimization_goal set to an action
Objective Creative, Bid type Tracking Spec Description

CANVAS_APP_
ENGAGEMENT

Canvas app engagement ads with optimization_goal= APP_INSTALLS

[{'action.type':
'app_engagement',
'application':
'APPLICATION_ID'}, {'action.type':
'post_engagement',
'post':'POST_ID', 'page':'PAGE_ID'}]

See app_engagement and post_engagement meta specs

CANVAS_APP_
INSTALLS

Canvas app install ads with optimization not set to optimization_goal= APP_INSTALLS

[{'action.type':
'app_engagement',
'application':
'APPLICATION_ID'}, {'action.type':
'post_engagement',
'post':'POST_ID', 'page':'PAGE_ID'}]

See app_engagement and post_engagement meta specs

CONVERSIONS

Page post link and photo ads with promoted_object set to a pixel ID and optimization_goal= OFFSITE_CONVERSIONS

{'action.type':
'post_engagement',
'post':'POST_ID', 'page':'PAGE_ID'},
{'action.type':'like',
'page':PAGE_ID}

Post Engagement, Page Like specs. Number of link clicks on the specific page post if there is only one link, number of engagements on the post, and number of times users generate stories or engage with a page

CONVERSIONS

Page post link and photo ads with optimization not set to optimization_goal= OFFSITE_CONVERSIONS

{'action.type':
'offsite_conversion',
'fb_pixel':
'FACEBOOK_PIXEL_ID'}, {'action.type':{'action.type':
'post_engagement',
'post':'POST_ID', 'page':'PAGE_ID'},
{'action.type':'like',
'page':PAGE_ID}

Conversions, Post Engagement, Page Like specs. Number of link clicks on the specific page post if there is only one link, number of engagements on the post, and number of times users generate stories or engage with a page

CONVERSIONS

Domain ads with promoted_object set to a pixel ID and optimization_goal= OFFSITE_CONVERSIONS

{'action.type':
'link_click',
'object':'URL'}, {'action.type':'like',
'page':PAGE_ID}

Page Likes, Link Clicks specs. Number of link clicks on the specific page post if there is only one link, number of engagements on the post, and number of times users generate stories or engage with a page.

CONVERSIONS

Domain ads with optimization not set to optimization_goal= OFFSITE_CONVERSIONS

{'action.type':
'offsite_conversion',
'fb_pixel':
'FACEBOOK_PIXEL_ID'}, {'action.type':
'link_click',
'object':'URL'}, {'action.type':'like',
'page':PAGE_ID}

Conversion, Page Likes, Link Clicks specs. Number of link clicks on the specific page post if there is only one link, number of engagements on the post, and number of times users generate stories or engage with a page.

EVENT_RESPONSES

Event ads with optimization not set to optimization_goal= EVENT_RESPONSES

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

Number of RSVPs (yes, maybe, no) to an event.

EVENT_RESPONSES

Event ads with optimization_goal= EVENT_RESPONSES

empty (conversion spec will cover the tracked actions)

Number of RSVPs (yes, maybe, no) to an event.

LINK_CLICKS

Page post link and photo ads with any bid option

{'action.type':
'post_engagement',
'post':'POST_ID', 'page':'PAGE_ID'}

Post Engagement.
Number of times an offsite url link, link with particular url domain, offsite link on a page, offsite link on a post was clicked.

LINK_CLICKS

Domain ads with optimization_goal= LINK_CLICKS

{'action.type':'like',
'page':PAGE_ID}]

Page likes.
Number of times an offsite url link, link with particular url domain, offsite link on a page, offsite link on a post was clicked.

LINK_CLICKS

Domain ads with optimization not set to optimization_goal= LINK_CLICKS

{'action.type':
'link_click',
'object':'URL'}, {'action.type':'like',
'page':PAGE_ID}

Website Click, Page Likes.
Number of times an offsite url link, link with particular url domain, offsite link on a page, offsite link on a post was clicked.

MOBILE_APP_
ENGAGEMENT

Mobile app engagement ads with any bid option

{'action.type':
'post_engagement',
'post':'POST_ID', 'page':'PAGE_ID'}
For App Engagement Ads you must specify a tracking spec explicitly using the Facebook App ID:
[{'action.type': 'mobile_app_install', 'application': 'APP_ID'}, {'action.type':
'app_custom_event',
'application':APP_ID}]

See post_engagement meta spec. Also, number of times an app event occurs.

MOBILE_APP_
INSTALLS

Mobile app install ads with any bid option

{'action.type':
'post_engagement',
'post':'POST_ID', 'page':'PAGE_ID'}
For App Install Ads you must specify a tracking spec explicitly using the Facebook App ID:
[{'action.type':
'app_custom_event',
'application':APP_ID}, {'action.type': 'mobile_app_install', 'application': 'APP_ID'}]

See post_engagement meta spec. Also, number of times users install the app through a mobile app install ad if there is an iOS/Android version and the number of times an app event occurs.

NONE

Any ad type

See default tracking
specs by ad type

PAGE_LIKES

Page Like ads or page post ads with any bid option

{'action.type':
'page_engagement', 'page':'PAGE_ID'}

See Page Engagement meta spec

POST_ENGAGEMENT

Page post ads with optimization not set to optimization_goal= POST_ENGAGEMENT

{'action.type':
'post_engagement',
'post':'POST_ID', 'page':'PAGE_ID'}

See Page Post Engagement meta spec

POST_ENGAGEMENT

Page post ads with optimization_goal= POST_ENGAGEMENT

empty

See Page Post Engagement meta spec

POST_ENGAGEMENT (testing)

any

{'action.type':
'dwell',
'post':'POST_ID', 'page':'PAGE_ID'}

A small percentage of this kind of ads has dwell tracking type, forcusing on users spending at least a min time on the ads.

PRODUCT_ CATALOG_SALES

Dynamic Product Ads

{'action.type': 'post_engagement', 'page': PAGE_ID, 'post': POST_ID}

Number of link clicks on the specific page post if there is only one link, number of engagements on the post, number of times users generate stories or engage with a page. You can specify a product set that is different from the product set in the promoted object but the default is the product set specified in the promoted object.

Meta Specs

You can specify multiple types of actions on a single object using a single spec.

Object Conversion Spec Description

Application

{"action.type":["app_engagement"], "application":["APPLICATION_ID"]}

Number of times users generate stories app_story or engage with content via app_use, app_install, credit_spent.

Page

{"action.type":["page_engagement"], "page":["PAGE_ID"]}

Number of times users perform any of the following actions in the context of the specified page: checkin, comment, follow, like, page post like, mention, post on page, share a post, answer a question. Plus the number of times users perform any of the following actions in the context of the specified page: click a link, view a photo, play a native FB video.

Page Post

{"action.type":["post_engagement"], "post":["POST_ID"], "page":["PAGE_ID"]}

Number of times users perform any of the following actions in the context of the specified post: comment, follow question, like, share, answer question. Plus the number of times users perform any of the following actions: click a link, page like, view photo, play a video hosted on Facebook or an inline Youtube video play. For non embedded videos use link_click.

Custom Tracking Specs

To define your own tracking specs, use the action spec framework. See the Action Specs, Reference.

Action (Object Types) Description, Tracking spec details Tracking or Conversion Spec

app_custom_event (application)

Custom event on an aplication.
Number of custome events on a mobile app.

{'action.type':
'app_custom_event',
'application':APP_ID}

app_install (application)

Installing an app.
Number of installs
on canvas or mobile app

[{'action.type':'app_install',
'application':APP_ID},
{'action.type':
'mobile_app_install',
'application':APP_ID}]

app_use (application)

Number of times app was used.

{'action.type':'app_use',
'application':APP_ID}

checkin (place)

Check in a place.
Number of checkins into the place or into any child places of this page.

{'action.type':'checkin',
'page': PAGE_ID},
{'action.type':'checkin',
'page.parent:PAGE_ID}

comment (post)

Commenting on a post.
Number of comments on any or specific page post.

{'action.type':'comment',
'post.wall':PAGE_ID},
{'action.type':'comment',
'post':POST_ID,
'post.wall':PAGE_ID}

credit_spend (application)

Instances of spending credit in an app.

'action.type':'credit_spent',
'application':APP_ID}

follow (question)

Subscribing to an object.
Number of answers or follows to a question.

{'action.type':'vote', 'question':QUESTION_ID, 'question.creator':PAGE_ID}, {'action.type':'follow', 'question':QUESTION_ID, 'question.creator':PAGE_ID}

leadgen_quality_conversion (pixel)

Down funnel lead conversion (CRM) events.

{'action.type': 'leadgen_quality_conversion', 'fb_pixel': 'FACEBOOK_PIXEL_ID'}, {'action.type': 'leadgen_quality_conversion', 'dataset': 'OFFLINE_EVENT_SET_ID'}

like
(page, post)

Liking an object.
Number of likes on a page or a post.

{'action.type':'like',
'page':PAGE_ID}
, {'action.type':'like',
'post.wall':PAGE_ID}
, {'action.type':'like',
'post':POST_ID,
'post.wall':PAGE_ID}

link_click (page,post, url, url domain)

Clicking on a link.
Number of times an offsite url link, link with particular url domain, offsite link on a page, offsite link on a post was clicked.

{'action.type':['link_click'],
'object':['URL']},
{'action.type':['link_click'],
'object.domain':
['URL_DOMAIN']},
{'action.type':['link_click'],
'post.wall':['PAGE_ID']},
{'action.type':['link_click'],
'post':['POST_ID'],
'post.wall':['PAGE_ID']}

mention (page)

Mentioning of a Page.
Number of mentions of a page.

{'action.type':'mention',
'object':PAGE_ID'}

offsite_conversion (pixel)

Number of offsite conversions, and accumulated revenue.

{'action.type':
'offsite_conversion',
'fb_pixel':
'FACEBOOK_PIXEL_ID'}

photo_view (page)

Viewing a photo.
Number of photo views,
video_plays or link_clicks of the photos/videos/link-shares of any or specific post on a page.

{'action.type':'photo_view', 'post.wall':PAGE_ID}
{'action.type':'photo_view', 'post':POST_ID,
'post.wall':PAGE_ID}

post (post)

Sharing a story.
Number of users post on a page.

{'action.type':'post',
'post.wall':PAGE_ID}

receive_offer (offer)

Claiming an Offer.
Number of people who claimed a specific offer.

{'action.type':'receive_offer',
'offer':OFFER_ID}

rsvp (event)

Rsvping into an Event.
Number of RSVPs (yes and maybe) to an event. Valid values are yes, maybe, and no.

{'action.type':'rsvp',
'event': EVENT_ID},

{'action.type':'rsvp',
'response':'yes',
'event': EVENT_ID},

{'action.type':'rsvp',
'response':'no',
'event': EVENT_ID},
{'action.type':'rsvp',
'response':'maybe',
'event': EVENT_ID}

tab_view (page)

Viewing a page tab
Number of views of a specific page tab. If you want all tab views just specify the page.

{'action.type':'tab_view',
'page.tab.name':
'PAGE_TAB_NAME', 'page':PAGE_ID},
{'action.type':'tab_view',
'page':PAGE_ID}

video_play (post)

Watching a video.
Number of video watches for any or a specific video post on a page.

{'action.type':'video_play', 'post.wall':PAGE_ID},{'action.type':'video_play', 'post':POST_ID,
'post.wall':PAGE_ID}

Examples

Pixel Tracking

Track the performance of different pixels in an ad by specifying the tracking pixel in the ad's tracking_specs field. For example:

tracking_specs="[
  {'action.type':'offsite_conversion','fb_pixel':1},
  {'action.type':'offsite_conversion','fb_pixel':2},
  {'action.type':'offsite_conversion','fb_pixel':3}
]"

This tracks the performance of pixels "1", "2" and "3". If you want to optimize for pixel "1" only, define the promoted_object of the parent ad set. This is useful when you want to optimize for CHECKOUT, but also want to track the number of REGISTRATION and ADD_TO_CART.

Pixels optimized by specifying the pixel ID in the promoted_object are automatically tracked, so you do not need to specify the same pixel in tracking_specs.

Using Conversion Specs

conversion_specs is a field for ad. It follows the format {'action.type':'{ACTION}', ... } where each action applies to an object. Here are examples of conversion specs for various ad types:

Ad type Conversion Spec

Domain ad with social context

{'action.type':'link_click', 'object':'URL'}

Page like ad

{'action.type':'like', 'page':PAGE_ID}

Page post link ad

{'action.type':['link_click'], 'post': [POST_ID], 'post.wall':[PAGE_ID]}

All other page post ads

{'action.type':'post_engagement', 'post':'POST_ID', 'page':'PAGE_ID'}

Event ad

{'action.type':'rsvp' , 'response':'yes', 'event':'EVENT_ID'}

Offer ad

{'action.type':'receive_offer', 'offer':OFFER_ID, 'offer.creator':PAGE_ID}

Mobile app install ad

N/A - cannot create such an ad with NONE objective.

Mobile app engagement ads

N/A - only CPC and CPM bid types are supported

Canvas app install ad

N/A - cannot create such an ad with NONE objective

Canvas app engagment ad

N/A - cannot create such an ad with NONE objective

Some conversion specs contain multiple actions that apply to a single object. These are called meta specs. Below are examples:

Object Conversion Spec Description

Page

{"action.type":["page_engagement"], "page":["PAGE_ID"]}

Times someone takes the following actions in a specific page: checkin, comment, follow, like, page post like, mention, post on page, share a post, answer a question. Includes the number of times someone performs these actions in a specific page: view a photo, play a native Facebook video.

Page Post

{"action.type":["post_engagement"], "post":["POST_ID"], "page":["PAGE_ID"]}

Number of times somone takes one of these actions in a specific post: comment, follow question, like, share, claim offer, answer question. Includes the number of times someone perform these actions: click a link, page like, view photo, play a video hosted on Facebook or an inline Youtube video play. For non-embedded videos use link_click.

Application

{"action.type":["app_engagement"], "application":["APPLICATION_ID"]}

Number of times someone generate app_story or engage with content as app_use, app_install, or credit_spent.