Creative Concepts

A creative concept is a set of creative assets that all share the same message, but have various sizes and formats. You can assign the creative concept to an ad, which gets assigned directly to placements, or to targeting groups. The creative concept lives at the advertiser level, meaning that you can reuse one across multiple campaigns for the same advertiser.

To avoid overusing a specific message, you can apply a frequency cap to a creative concept. The frequency cap applys across all the ads and decision groups that the creative concept is used in.

Atlas supports delivery of creative across browsers and devices. We support HTML5 creative, using HTML, CSS, JavaScript, and images, for cross-device ad serving compatible with most browsers and devices.

Creating Concepts

To create a concept, make a POST request to /{atlas_advertiser_id}/creative_sets. Note that name is the only required attribute when making the call.

Sample Request

curl \
-F "creative_sets=
[{
'name':'My first creative concept',
'description':'A description goes here.',
},
{
'name':'My second creative concept',
'description':'A description goes here.',
},
]" \
-F "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/<atlas_advertiser_id>/creative_sets"

See Atlas Creative Set to see all the fields that you can specify for a new creative concept.

If the request succeeds, you get a response that includes the IDs of the creative concepts.

Response

{
   "data":[
      {
         "id":"11077207531",
         "success":true
      },
      {
         "id":"11077201137",
         "success":true
      }
   ]
}

Adding Assets

To add an asset to a creative concept, make a POST request to /{creative_set_id}/creatives. {creative_set_id} is the id of the creative concept. In the example above, it is the id returned in the response when you created the concept.

The following types of creative assets are supported: * Images (.jpg, .gif, .png) * HTML5 (.html, .zip)

For more details on HTML5 assets, see Atlas HTML 5 Creative Specifications and Guidelines.

Sample Request

curl \
-F "creatives=[{'name':'<CREATIVE_FILE_NAME.EXTENSION>'}]" \
-F "source_0=@<PATH_TO_CREATIVE_FILE>" \
"https://graph.atlassolutions.com/<API_VERSION>/<CREATIVE_SET_ID>/creatives?access_token=<ACCESS_TOKEN>"

If the request succeeds, you get a response that includes the IDs of the uploaded assets.

Response

{
   "data":[
      {
         "id":"110711775",
         "success":true
      }
   ]
}

Updating Creative Assets

Once uploaded, an asset for a creative concept can not be deleted. To replace an asset that you added to your creative concept, set the status of the creative to replace to inactive and then submit a new creative with the same dimensions as the one you replace. Request to disable:

curl \
-F "status=inactive" \
-F "access_token=<ACCESS_TOKEN>" \
"https://graph.atlassolutions.com/<API_VERSION>/<CREATIVE_ID>"

Sample response

{
    "success":true
}

Upload new asset:

curl \
-F "creatives=[{'name':'<NEW_CREATIVE_FILE_NAME.EXTENSION>'}]" \
-F "source_0=@<PATH_TO_NEW_CREATIVE_FILE>" \
"https://graph.atlassolutions.com/<API_VERSION>/<CREATIVE_SET_ID>/creatives?access_token=<ACCESS_TOKEN>"

If the request succeeds, you get a response that includes the ID of the uploaded assets.

Response

{
   "data":[
      {
         "id":"110711334",
         "success":true
      }
   ]
}

Alternatively, you can upload the new creative first as long as you set its status to draft, then disable the creative you're replacing by setting its status to inactice and then finally updating the status of the new creative to active.

Click-through URLs

These are the destination URLs that appear on Atlas-served or Atlas-tracked ads; they are the URLs a user goes to when they click on an ad's links.

Creating Click-through URLs

To create a click-through URLs, make a POST request to /{atlas_campaign_id}/click_throughs. Please note that name and standard_url are required fields.

Sample Request

curl \
-F "click_throughs=
[{
  'name':'My first click-through',
  'standard_url':'http://example.com?cid={{CAMPAIGN.ID}}',
},
{
  'name':'My second click-through',
  'standard_url':'http://example.com?w={{PLACEMENT.WIDTH}}',

},
]" \
-F "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/<atlas_campaign_id>/click_throughs"

See Atlas Click Through to see all the fields that you can specify when creating click-through URLs.

See Atlas Macros to see all the macros supported by Atlas that you can use in the standard_url.

If the request succeeds, you get a response that includes the IDs of the created click-through URLs.

Response

{
   "data":[
      {
         "id":"1107720365",
         "success":true
      },
      {
         "id":"1107720116",
         "success":true
      }
   ]
}

Updating Click-through URLs

You can update a click-through URL by making a POST request to /{atlas_click_through_id}:

curl \
-F "name=My updated click-through" \
-F "standard_url=http://example2.com?cid={{CAMPAIGN.ID}}" \
-F "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/<atlas_click_through_id>"

Response

{
  "success":true
}

Ads

An ad is a creative concept plus a click-through URL. To apply targeting such as audiences, or sequencing, add the ad to a targeting group. You can assign an ad directly to a placement, but you have fewer options for controlling when someone sees an ad.

Creating Display Ads

To create display ads, make a POST request to /{atlas_campaign_id}/ads. creative_set_id, name, and type are all required fields. For display ads, set type to display:

curl \
-F "ads=
[
   {
      'name':'My first ad',
      'creative_set_id':'2323231122',
      'type':'display',

   },
   {
      'name':'My second ad',
      'creative_set_id':'23233231125',
      'type':'display',

   },

]" \
-F "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/<atlas_campaign_id>/ads"

Response

{
   "data":[
      {
         "id":"110772011831",
         "success":true
      },
      {
         "id":"110772011832",
         "success":true
      }
   ]
}

Tracking Pixels

For display ads that run on other advertising platforms, create tracking pixels to send data on impressions, clicks, and other actions to Atlas for reporting.

When you create a tracking pixel, Atlas creates a script that you insert into the ad on the ad platform that delivers your ads. When the ad runs, the code snippet requests a transparent 1x1 pixel image from the Atlas server. When the ad loads the image, it pings Atlas and records the interaction, even if Atlas doesn’t serve the ad. This is how the Atlas server records the ad delivery, even when Atlas doesn’t serve the ad. You can then report on tracking pixels through Atlas.

Since the pixel sends an Atlas-redirected URL for the ad, use custom parameters to update parts of the URL and pass product IDs or other information.

To create a tracking pixel, make a POST request to /{atlas_campaign_id}/ads. creative_set_id should not be set and type should be set to tracking:

curl \
-F "ads=
[
   {
      'name':'My first tracking ad',
      'type':'tracking',
      'custom_fields': [
        {'key': 'custom1', 'value': '200'},
        {'key': 'custom2', 'value': 'val'}
      ]

   },
   {
      'name':'My second tracking ad',
      'type':'tracking',

   },

]" \
-F "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/<atlas_campaign_id>/ads"

Response

{
   "data":[
      {
         "id":"11077201183",
         "success":true
      },
      {
         "id":"11077201183",
         "success":true
      }
   ]
}

Setting Click-through URLs

After you create an ad or tracking pixel, assign a click-through URL to it by creating an ad event. To create an ad event, make a POST request to /{atlas_ad_id}/ad_events:

curl \
-F "ad_events=
[{
'name':'Ad Event Name',
'click_through_id': '1107720135',
'is_default_ad_event': true,
},
]" \
-F "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/<atlas_ad_id>/ad_events"

Response

{
   "data":[
      {
         "id":"10772139842",
         "success":true
      }
   ]
}