facebook api之Marketing API

General information on the Marketing APIs, access, versioning and more. The main use cases for the Marketing API are ads insights, audience management, and ads management:

• Ads Insights and Insights API Reference
• Audience Management: manage your first party data, find new customers, and reengage existing customers through Custom Audience targeting on Facebook. Getting started on the Audience Management API and Custom Audiences Reference
• Ads Management API: The full suite of APIs, from ad creation and management, reporting, and audience management. Getting started on the Ads Management API and Ads Management API Guides

Learn the basic structure and usage of the Marketing API.

• Access and Authentication - Marketing API has three levels of access: development, basic, and standard access levels. Each level of access has certain restrictions, described in this article. Set up your dev environment and obtain an access token.
• Testing - Learn how to test the Marketing API.
• Graph API - REST-based foundation for Marketing API, how to make all CRUD operations, error handling, and debugging tips.
• Object Structure - Campaigns, ad sets, ads and ad creatives.

Versioning

Learn more about upcoming changes and deprecations using our versioning and migration systems.

• Versioning Overview - Facebook's Marketing API supports versioning cycles for app development stability. Learn more here.
• Migrations - Future and past Facebook Platform Migrations. Migrations are used to apply changes across all existing versions.
• Changelog - This changelog covers what's changed in Facebook's Marketing API. These changes include Facebook's server-side APIs and SDKs.
• Upgrade Guide - Details about the individual changes in each version and helps you upgrade your apps across versions.

Ads Management

Create ad campaigns, provide bids for ads auction, and manage ad creative.

Quickstart

Here are the basics steps to manage ad campaigns with the Facebook Marketing API.

1. Create a Campaign

2. Define Targeting

3. Define Budget, Billing, Optimization, and Duration

4. Create Ad Creative

5. Book Ad

#Create a Campaign
curl \
  -F 'name=My campaign' \
  -F 'objective=LINK_CLICKS' \
  -F 'status=PAUSED' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.11/act_<AD_ACCOUNT_ID>/campaigns

#Define Targeting
curl -G \
  -d 'type=adinterest' \
  -d 'q=baseball' \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.11/search

#Define Budget, Billing, Optimization, and Duration
curl \
  -F 'name=My Ad Set' \
  -F 'optimization_goal=REACH' \
  -F 'billing_event=IMPRESSIONS' \
  -F 'bid_amount=2' \
  -F 'daily_budget=1000' \
  -F 'campaign_id=<CAMPAIGN_ID>' \
  -F 'targeting={"geo_locations":{"countries":["US"]}}' \
  -F 'start_time=2018-02-06T04:45:17+0000' \
  -F 'end_time=2018-02-13T04:45:17+0000' \
  -F 'status=PAUSED' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.11/act_<AD_ACCOUNT_ID>/adsets

#Provide Ad Creative

#First, create an AdImage from an image file.
curl \
  -F 'filename=@<IMAGE_PATH>' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.11/act_<AD_ACCOUNT_ID>/adimages

#Then, use the image hash to create the AdCreative.
curl \
  -F 'name=Sample Creative' \
  -F 'object_story_spec={
    "link_data": {
      "image_hash": "<IMAGE_HASH>",
      "link": "<URL>",
      "message": "try it out"
    },
    "page_id": "<PAGE_ID>"
  }' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.11/act_<AD_ACCOUNT_ID>/adcreatives

#The AdCreative with your link is not yet visible in Ads Manager. You see this data once you book you ad. You can debug your ad creative with Graph API Explorer:
#GET /{my-creative-id} HTTP/1.1
#Host: graph.facebook.com

#Schedule Delivery
curl \
  -F 'name=My Ad' \
  -F 'adset_id=<AD_SET_ID>' \
  -F 'creative={"creative_id":"<CREATIVE_ID>"}' \
  -F 'status=PAUSED' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.11/act_<AD_ACCOUNT_ID>/ads

more detail……

Campaign Structure

Facebook's campaign structure has 3 levels: campaign, ad set and ad. In the API, there is a fourth level available for developers, called the creative.

• Campaigns contains your advertising objective and one or more ad sets. This helps you optimize and measure results for each advertising objective.

• Ad Sets have one or more ads. You define budget and schedule for each ad set. Create an ad set for each target audience with your bid; ads in the set target the same audience with the same bid. This helps control the amount you spend on each audience, determine when audience will see your ads, and provides metrics for each audience.

• Ads contain ad creative). Create multiple ads in each ad set will to optimize ad delivery based different images, links, video, text or placements.

• Ad creatives contain just the visual elements of the ad and once created, are immutable. Each ad account has a creative library to store creatives for reuse in ads.

	Objective	Schedule	Budget	Bidding	Targeting	Creative
Campaign	✓
Ad Set		✓	✓	✓	✓
Ad						✓

Mapping between the public facing naming of the object and API endpoints:

Public facing name	API endpoint
Campaign	/campaigns
Ad Set	/adsets
Ad	/ads
Creative	/adcreatives

#To read the campaigns associated with a specific account
curl -G \
  -d 'effective_status=["ACTIVE","PAUSED"]' \
  -d 'fields=name,objective' \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.11/act_<AD_ACCOUNT_ID>/campaigns

#We also show some high level insights, including impressions, clicks and the amount spent. You can retrieve these by calling the following endpoint, optionally specifying the start and/or end time:
curl -G \
  -d 'end_time=1517287567' \
  -d 'fields=impressions,inline_link_clicks,spend' \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.11/<CAMPAIGN_ID>/insights

#Ad sets are groups of ads, and are used to configure the budget and period the ads should run for. All ads contained within an ad set should have the same targeting.
curl \
  -F 'name=My First AdSet' \
  -F 'lifetime_budget=20000' \
  -F 'start_time=<START_TIME>' \
  -F 'end_time=<END_TIME>' \
  -F 'campaign_id=<CAMPAIGN_ID>' \
  -F 'bid_amount=500' \
  -F 'billing_event=IMPRESSIONS' \
  -F 'optimization_goal=POST_ENGAGEMENT' \
  -F 'targeting={
    "age_max": 24,
    "age_min": 20,
    "behaviors": [{"id":6002714895372,"name":"All travelers"}],
    "genders": [1],
    "geo_locations": {
      "countries": ["JP"],
      "regions": [{"key":"3886"}],
      "cities": [
        {
          "key": "2420605",
          "radius": 10,
          "distance_unit": "mile"
        }
      ]
    },
    "home_ownership": [{"id":6006371327132,"name":"Renters"}],
    "interests": [{"id":6003107902433,"name":"Association football (Soccer)"}],
    "life_events": [{"id":6002714398172,"name":"Newlywed (1 year)"}],
    "publisher_platforms": ["facebook","audience_network"]
  }' \
  -F 'status=PAUSED' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.11/act_<AD_ACCOUNT_ID>/adsets

# list all ad sets within a campaign.
curl -G \
  -d 'fields=name,start_time,end_time,daily_budget,lifetime_budget' \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.11/<CAMPAIGN_ID>/adsets

#Ads：An ad object contains all of the information neccessary to display an ad on Facebook, such as the creative.
curl \
  -F 'name=My Ad' \
  -F 'adset_id=<AD_SET_ID>' \
  -F 'creative={"creative_id":"<CREATIVE_ID>"}' \
  -F 'status=PAUSED' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.11/act_<AD_ACCOUNT_ID>/ads

# list all of the ads for an ad set within your UI.
curl -G \
  --data-urlencode 'effective_status=[
    "ACTIVE",
    "PAUSED",
    "PENDING_REVIEW",
    "PREAPPROVED"
  ]' \
  -d 'fields=name,configured_status,effective_status,creative' \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.11/<AD_SET_ID>/ads

more detail……

Objectives

Objectives are actions you want people to make when they see the ad and objects are what people act upon. See Help Center.

#Setting Objectives：After you create new campaign, ad set, ad, and ad creative objects, provide the required fields for each object creation. 

#The minimum API call needed to create a campaign:

curl \
  -F 'name=My First Campaign' \
  -F 'objective=<OBJECTIVE>' \
  -F 'status=PAUSED' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.11/act_<AD_ACCOUNT_ID>/campaigns

#Explicitly setting the objective has the following benefits:
    #You get correct tracking, optimization, and bidding options for your ad.
    #You can view unique UI and analytics dashboards for each objective
#See campaign for acceptable values for the objective parameter. For this example, let's choose POST_ENGAGEMENT:
curl \
  -F 'name=My First Campaign' \
  -F 'objective=POST_ENGAGEMENT' \
  -F 'status=PAUSED' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.11/act_<AD_ACCOUNT_ID>/campaigns

more detail……

　

Reference

• Ad Units
• Dynamic Ads - Ads based on your product catalog.
• Offer Ads - Ads promting an offer.
• Bidding and Optimization - How bidding and budgeting works.
• Targeting - Reach the right audience.
• Instagram Ads