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