News for Developers

Back to News

Creating Sponsored Stories with Action Specs

Jonathan Dean
February 4, 2012

Related News

2012 in Review

December 20 2012

Recently we announced a new way of creating Sponsored Stories on the Ads API by using action specs. These changes make the Ads API more flexible and will make it easier for developers to adapt to new story types as we launch them. We will be deprecating the old sponsored stories creative types as of May 1.

Prior to this change Sponsored Stories were defined by choosing the correct Ad Creative type for the specific Sponsored Story type. E.g. a page like sponsored story was type 9, a page post like sponsored story was type 17 etc. This made it complicated for developers to incorporate new Sponsored Story types as each Sponsored Story required different fields per story type.

By defining Sponsored Stories via Action Specs we are making it easier for new Sponsored Story types to be integrated into Ad Tool apps as they will all make use of the same standard fields.

For example, the old way of creating a Page Like Sponsored Story (Type 9) was as follows:

 curl --silent --location -F "campaign_id=6004176938239" 
      -F "bid_type=1" 
      -F "max_bid=30" 
      -F "targeting={'countries':['US']}" 
      -F "creative={'type':9,'object_id':'115632122684'}" 
      -F "name=AdGroup Name"  "https://graph.facebook.com/act_123456789/adgroups?access_token=____"

While the new Action Spec format is as follows:

 curl --silent --location 
      -F "campaign_id=6004176938239" 
      -F "bid_type=1" 
      -F "max_bid=30" 
      -F "targeting={'countries':['US']}" 
      -F "creative={'type':25,'action_spec':'{\'action.type\':\'like\', \'page\':115632122684}'}" 
      -F "name=AdGroup Name"  "https://graph.facebook.com/act_123456789/adgroups?access_token=____"

Similarly the old way of creating a Specific Page Post like Sponsored Story (Type 25 with query template 6) was as follows:

 curl --silent --location 
      -F "campaign_id=6004176938239" 
      -F "bid_type=1" 
      -F "max_bid=30" 
      -F "targeting={'countries':['US']}" 
      -F "creative={'type':25, 'object_id':115632122684, 'story_id':10150420410887685, 'query_templates':[6]}" 
      -F "name=AdGroup Name"  "https://graph.facebook.com/act_123456789/adgroups?access_token=____"

While the new Action Spec format is as follows:

 curl --silent --location 
      -F "campaign_id=6004176938239" 
      -F "bid_type=1" 
      -F "max_bid=30" 
      -F "targeting={'countries':['US']}" 
      -F "creative={'type':25,'action_spec':'{\'action.type\':\'like\', \'post\':10150420410887685}'}" 
      -F "name=AdGroup Name"  "https://graph.facebook.com/act_123456789/adgroups?access_token=____"

You will notice that the Action Spec based requests use very similar structures in a fixed format while the older process's format depended on the ad type being created. This adoption of a fixed format for defining Sponsored Stories will made it much easier for Ads API developers to support new Sponsored Stories in the future.

The following table lists a mapping from the old Sponsored Story ad creative types to the new Action Spec equivalent.

align="left"align="left"align="left"
8Promotes stories published through an app.{'action.type':'post', 'application':APP_ID}
9Promotes stories about a user liking a page/place.{'action.type':'like', 'page': PAGE_ID}
10Promoting stories about a user checking into a place.{'action.type':'checkin','page':PAGE_ID}
10Promoting stories about a user checking into any child place of this page.{'action.type':'checkin', 'page.parent':PAGE_ID}
16Promotes stories about a user using an app*.{'action.type':'app_use', 'application':APP_ID}
17Promotes stories about a fan liking any post from a page.{'action.type':'like', 'post.author':PAGE_ID,'post.wall':PAGE_ID}
19Promotes stories about a user liking a domain.{'action.type':'like', 'domain':DOMAIN_ID}
19Promotes stories about a user sharing something from a domain.{'action.type':'post', 'post.domain':DOMAIN_ID}
25 + query_template=6Promotes stories about a user liking a specific page post.{'action.type':'like', 'post':PAGE_POST_ID}
25 + query_template=7Promotes stories about a user commenting on a specific page post.{'action.type':'comment','post':PAGE_POST_ID}
25 + query_template=7Promotes stories about a fan commenting on any post from a page.{'action.type':'comment', 'post.author':PAGE_ID,'post.wall':PAGE_ID}
25 + query_template=8Promotes stories about a user RSVPing into an event.{'action.type':'rsvp', 'event': EVENT_ID}

Please note that query_template is being retired from the API and is not used in the Action Spec framework.

This post relates to the Ads API which is part of the Marketing API Program. Apps must be whitelisted in order to call this API. For more details on the Marketing API program and how to apply please click here.


Related News

December 20 2012

December 19 2012

December 19 2012

December 18 2012

December 13 2012

December 12 2012