Media Plan Management

Related Topic

After you create a campaign you can create a media plan. In the Atlas App, select one campaign, there is a session to create Media Plan, under which you can create Placement and Cost Package.

A Campaign can contain multiple Cost Packages and Placements. A Placement may be associated with one or none of Cost Packages.

Define Cost Package

A Cost Package is the total price associated with a campaign charged to the advertiser by the publisher. All media costs are stored in USD.

You can create Cost Packages for a Campaign by making an HTTP POST request to the cost_packages endpoint. It will update the Cost Packages if it already exists.

/<ATLAS_CAMPAIGN_ID>/cost_packages

When you create Cost Packages, you typically define the following attributes:

  1. Publisher (publisher_id)
  2. Name of the cost_packages (name) - Label for this cost package.
  3. Cost Method (cost_method) - How Facebook calculates the costs of ads. Default value is "cpm" or "Cost Per Mille" which is cost per 1000 impressions.
  4. Event value (cost_basis) - What value you place on your event occurring.
  5. Billing Period (flight_dates) - Time period for billing for ads.
  6. Units Associated (units) - Number of units associated with a Cost Package.
curl \
-F "cost_packages=
[{
  'name':'TestCostPackage',
  'publisher_id': <PUBLISHER_ID>,
  'flight_dates':
      {
        'begin_date':'2015-10-22T00:00:00-0400',
        'end_date':'2015-11-01T23:59:59-0500',
        'time_zone':'America/New_York'
      },
  'cost_basis': 1000000,
  'units': '1'
}]" \
-F "access_token=<ACCESS_TOKEN>" \
https://graph.atlassolutions.com/<API_VERSION>/<ATLAS_CAMPAIGN_ID>/cost_packages

Retrieve cost packages

After creation, you can see a list of cost packages under Media Plan Tab on Atlas App. Also, you can make a GET request to retrieve all cost packages accociated with the campaign:

curl -G \
  -d 'access_token=<ACCESS_TOKEN>' \
https://graph.atlassolutions.com/<API_VERSION>/<CAMPAIGN_ID>/cost_packages

Read Details

You can see details of each Cost Package by making an HTTP GET request to the package node:

curl -G \
  -d 'access_token=<ACCESS_TOKEN>' \
https://graph.atlassolutions.com/<API_VERSION>/<ATLAS_PACKAGE_ID>/

Update Cost Packages

You can update an existing package by making an HTTP POST request.

An example of the request and response:

POST <API_VERSION>/<ATLAS_PACKAGE_ID>?units=1000 HTTP/1.1
Host: graph.atlassolutions.com

On success, you see this response:

{
  "success": true
}

Delete Cost Packages

You can delete an AtlasCostPackage by making a DELETE request.

curl -XDELETE \
  -F 'access_token=<ACCESS_TOKEN>' \
https://graph.atlassolutions.com/<API_VERSION>/<ATLAS_PACKAGE_ID>
Reference: Atlas Cost Package Object

Create a Placement

A Placement represents the area on a publisher site where an ad is displayed.

You can create placements for a campaign by making an HTTP POST request to campaign endpoint. This updates the placement for ads in this campaign if the campaign already exists. When you create a placement associated with a campaign, you need to specify:

  1. Publisher and Site ( publisher_id / site_id (required) / url ) - Which publisher and site you want to place your Ads.
  2. Placement Name (name)
  3. How you want your ads to be optimized (optimization_goal) - We optimize delivery of your ads based on this goal, for example app installs.
  4. Placement Dimensions (height / width)
  5. Duration (flight_dates) - Time period the placement lasts.
  6. Placement Type (type) - For display campaigns, choose between a display placement or a tracking placement. Use display placement when ads are served through Atlas. Use a tracking placement when ads are served by other ad servers but tracked in Atlas.

*If you are running ads for search engines, you cannot choose search type placement for general Atlas Campaigns. You need to provide an alias and create a search campaign, see SEMP integration development guide.

curl \
  -F "placements=
  [{
    'publisher_id':<PUBLISHER_ID>,
    'site_id':<SITE_ID>,
    'name':'TestPlacement',
    'height':123,
    'width':234,
    'url':<SITE_URL>,
    'type':'tracking',
    'flight_dates': {
      'begin_date': '2015-11-03T00:00:00-0500',
      'end_date': '2015-11-05T23:59:59-0500',
      'time_zone': 'America/New_York'
    },
  }]" \
  -F "access_token=<ACCESS_TOKEN>" \
https://graph.atlassolutions.com/<API_VERSION>/<CAMPAIGN_ID>/placements

If your request succeeds, you can get a new placement ID in the response:

{
  "data": [
    {
      "id": "<ATLAS_PLACEMENT_ID>", 
      "success": true
    }
  ]}

Verify Placements

From Atlas APP, you can see placements you created under campaign Media Plan page.

Also, you can make a GET request to get all placements associated with a campaign.

curl -G \
  -d 'access_token=<ACCESS_TOKEN>' \
https://graph.atlassolutions.com/<API_VERSION>/<CAMPAIGN_ID>/placements

The response is a list of placement objects:

{
  "data": [
    {
      "alias": "", 
      "campaign_id": "<CAMPAIGN_ID>", 
      "created_date": "2014-09-04T17:12:32+0000", 
      "flight_dates": {
        "begin_date": "2014-09-04T00:00:00-0400", 
        "end_date": "2014-10-03T23:59:59-0400", 
        "time_zone": "America/New_York"
      }, 
      "height": "123", 
      "id": "<ATLAS_PLACEMENT_ID>", 
      "is_coppa_sensitive": false, 
      "last_modified_date": "2014-09-09T17:33:31+0000", 
      "name": "TestPlacement", 
      "publisher_id": "<PUBLISHER_ID>", 
      "site_id": "<SITE_ID>", 
      "type": "tracking", 
      "url": "<SITE_URL>", 
      "version": "2", 
      "width": "234"
    }
  ]
}

Verify Publisher

You can call the publishers endpoint can get a list of publishers associated with a campaign:

GET /<API_VERSION>/<ATLAS_campaign_ID>/publishers 
HTTP/1.1 Host: graph.atlassolutions.com

Response:

{
 "data": [
   {
    "created_date": "2013-12-04T19:07:53+0000", 
    "id": "<PUBLISHER_ID>", 
    "last_modified_date": "2013-12-04T19:07:53+0000", 
    "name": "Google", 
    "version": "1", 
    "visibility_type": "external"
   } 
]}

Verify placements associated with publisher

You may want to check the number of ad placements made by a certain publisher for specific type of ads in a campaign. For example, if you want the number of placements for a search ads campaign only, first call:

GET /<ATLAS_ADVERTISER_ID>/campaigns?filter_by={"types": ["search"],}&summary=count   

This returns a list of search campaign ids. Then you can make a GET request to the edge placements on the publisher_id node. Provide the list of search campaign ids you just received as filter parameter in your request:

GET /<API_VERSION>/<PUBLISHER_ID>/placements?
filter_by={
    "campaign_ids": [
        "<ATLAS_campaign_ID_1>",
        "<ATLAS_campaign_ID_2>",
     ],
}&summary=count
HTTP/1.1 Host: graph.atlassolutions.com

On success you get a response like this:

{
  "data": [
    {
      "alias": "",
      "campaign_id": "<ATLAS_campaign_ID_1>",
      "cost_package_id": "0",
      "created_date": "2015-01-27T01:06:56+0000",
      "flight_dates": {
        "begin_date": "2014-12-01T00:00:00-0800",
        "end_date": "2014-12-26T23:59:59-0800",
        "time_zone": "America/Los_Angeles"
      },
      "height": "1",
      "id": "<PLACEMENT_ID>",
      "is_coppa_sensitive": false,
      "last_modified_date": "2015-01-29T19:35:27+0000",
      "name": "27",
      "publisher_id": "<PUBLISHER_ID>",
      "site_id": "<SITE_ID>",
      "type": "search",
      "url": "",
      "version": "3",
      "width": "1"
    }
  ],
  "summary": {
    "count": 1
  }
}

Update Placements

You can update an existing placement by making an HTTP POST request. Here is an example to associate an existing cost package to the placement. Note that the publisher of the cost package and placement should be identical.

Request:

POST <API_VERSION>/<ATLAS_PLACEMENT_ID>?cost_package_id=<ATLAS_PACKAGE_ID> HTTP/1.1
Host: graph.atlassolutions.com

On success, you see this response:

{
  "success": true
}

Delete Placement

You can delete placements by making an HTTP DELETE request.

curl -XDELETE \
  -F 'access_token=<ACCESS_TOKEN>' \
https://graph.atlassolutions.com/<API_VERSION>/<ATLAS_PLACEMENT_ID>
References: Atlas Placement ObjectReferences: Atlas Publisher Object