Atlas Audiences and Targeting Groups (Ad Sets)

Audiences let you narrow the focus of your ad so that only those people who you care about get to see the ad, and you apply them using targeting groups (Ad Sets). Use targeting groups when you want to apply targeting and other settings to multiple ads within the same campaign. You can add audience targeting, ad weight or rotation, audience-level frequency caps, and start and end dates. You will assign targeting groups to placements in order to traffic ads for your campaigns.

Atlas Audience

Audiences are used to set up targeting for targeting groups in your campaigns, and they're groups of people with special characteristics who you want to see your ad, such as “women based in London, who are between the ages of 25 and 35.” You can customize the messages in the ads targeted at specific audiences, so you get the most out of each impression in your campaign.

Once you create an audience, you can reuse it across your campaigns under an advertiser.

Create an Atlas audience

You can make a POST request to audiences edge from advertiser. Pass an array of audiences you want to create. Each audience should be a JSON object with required parameters:

  • name of your audience
  • definition is a JSON structure indicating audience features. You can customize audience definition based on following features:
    • Age and gender – You can target ads to people age 13 and up, and you can target ads to men, women or everyone. We use information derived from Facebook data to infer the likely age and gender of the people who you want to see your ad.
    • Location – You can target ads to people based on their country, state/province, city, and ZIP code. (ZIP code targeting is available in the United States only.) As with age and gender above, we use information derived from Facebook data plus the person's IP address to infer the likely location of a person. You can also choose which location signals you want us to use when targeting people.
    • Device type – You can target people using desktops and laptops, people on mobile devices (which includes both tablets and phones), or everyone. We use information from the app or browser to determine what kind of device someone is using when they see your ad.
    • Remarketing segments – If you're using universal tags to track site engagement, you can target ads to people based on the things they have done on your website. To build your remarketing segment, you can use information from universal tags. For example, you can build a segment based on people who visited the shopping cart page of your website, but didn't click the buy button. This practice is sometimes called retargeting or remessaging. Details can be found in next section.

Full list is in Atlas Audience Definition reference document

Sample Request

curl \
-F 'audiences=[{
  "definition": {
    "age": {
      "max": "60",
      "min": "32"
    },
    "device_types": [
      "mobile"
    ],
    "genders": [
      "female"
    ],
    "location_targeting_type": "home_or_current",
    "locations": {
      "countries": [
        {
          "key": "US",
          "name": "United States"
        }
      ]
    },
  },
  "description": "",
  "name": "test audience",
}]' \
-F 'access_token=<ACCESS_TOKEN>' \
'https://graph.atlassolutions.com/<API_VERSION>/<ATLAS_ADVERTISER_ID>/audiences'

Response

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

References: Atlas Audience

Targeting groups (Atlas Ad Sets)

Use targeting groups when you want to apply targeting and other settings to multiple ads within the same campaign. In other words, targeting group is a set of ads with similar function. You can add audience targeting, ad weight or rotation, audience-level frequency caps, and start and end dates. You'll assign ad sets to placements in order to traffic ads for your campaigns. See Atlas Ad Set reference for details.

Create Targeting Groups (Atlas Ad Sets)

curl \
-F 'ad_sets=[{
  "alias": "",
  "audience_id": "<ATLAS_AUDIENCE_ID>",
  "decisioning_type": "weighted",
  "flight_dates": {
    "begin_date": "2016-01-12T00:00:00-0500",
    "end_date": "2016-01-15T23:59:59-0500",
    "time_zone": "America/New_York"
  },
  "frequency_cap": "1",
  "frequency_cap_period_hours": "24",
  "name": "my adset",
  "priority": "1",
}]' \
-F 'access_token=<ACCESS_TOKEN>' \
'https://graph.atlassolutions.com/<API_VERSION>/<ATLAS_CAMPAIGN_ID>/ad_sets'

Response is a list of AtlasAdSet nodes.

Response

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

Add Ads to Targeting Group

You can assign or unassign many ads to targeting groups. Before you begin, make sure you've created ads and targeting groups for the campaign.

You can make a POST request to ad_set_ads edge from atlas_ad_id or atlas_ad_set_id, which defines the association edge between an ad and an ad set.

curl \
-F 'ad_set_ads=[{
  "ad_set_id": "<ATLAS_AD_SET_ID>",
  "ad_id": "<ATLAS_AD_ID>",
  "weight": "2"
}]' \
-F 'access_token=<access_token>' \
'https://graph.atlassolutions.com/<API_VERSION>/<ATLAS_AD_SET>/ad_set_ads'

where you can specify

Ad rotation - specifically sequence and weight -- lets you control how often an ad shows in comparison to other ads, or the order in which those ads run. These settings are different from frequency caps, which limit the total number of times that an individual can see a specific ad.

  • sequence_number: The order in which the ad is served
  • weight: The probability of the ad being selected

Verify

Then from Atlas App UI, you can see a list of ads under the page

  • app.atlassolutions.com/campaigns/<ATLAS_CAMPAIGN_ID>/targeting-groups/<ATLAS_AD_SET_ID>

Also, you can make a GET request to ads edge to retrieve ads associated with the ad set

GET /<API_VERSION>/{atlas-ad-set-id}/ads HTTP/1.1
Host: graph.atlassolutions.com

Remove Ads from Ad Set

You can delete the association of ad and ad set by making a DELETE request to /{atlas_ad_set_ad_id}

curl -XDELETE \
  -F 'access_token=<ACCESS_TOKEN>' \
https://graph.atlassolutions.com/<API_VERSION>/<atlas_ad_set_ad_id>

Response

{
  "success": true
}

Assign Targeting Groups to Placements

You can make a POST request to placement_ad_sets edge from the following paths: /{atlas_campaign_id}/placement_ad_sets

curl \
-F 'assignments=[{
  "ad_set_id": "<ATLAS_AD_SET_ID>",
  "placement_id": "<ATLAS_PLACEMENT_ID>",
}]' \
-F 'access_token=CAAB3rQQzTFABANTZBvYCZABZAtLC2OgqZCCqQowUGzTRBysBCwlAON7OHeRw7WxZB7WqMnB4Brd3JHznvKreJZAfGZBohyI006VhIdGuAew8aDQK0OjpCZCwtHQCi1Jg4KukNUKsrj43lB0D5fZB3W1UYZB5yZCY9IB5JOrkoDmovXqmZCnOELduqVVwDv7acqauRk4ZD' \
'https://graph.atlassolutions.com/v2.5/11077201137864/placement_ad_sets'

Note that if you assign both ads and targeting groups to a placement, the targeting group will show because it has a higher priority than an individual ad.

Keep in mind that the maximum number of assignments for an Atlas campaign is 50,000. Assignments include placements to tracking pixels, placements to ads, and placements to targeting groups.

Verify

Then from Atlas App UI, you can see a list of targeting groups under the page

  • app.atlassolutions.com/campaigns/<ATLAS_CAMPAIGN_ID>/placements/<ATLAS_PLACEMENT_ID>

Also, you can make a GET request to ad_sets edge to retrieve ad sets associated with the placement

GET /<API_VERSION>/{atlas-placement-id}/ad_sets HTTP/1.1
Host: graph.atlassolutions.com

Unassign

You can delete the assignment by making a DELETE request to /{atlas_placement_ad_set_id}

curl -XDELETE \
  -F 'access_token=<ACCESS_TOKEN>' \
https://graph.atlassolutions.com/<API_VERSION>/<atlas_placement_ad_set_id>

Response

{
  "success": true
}

References: Atlas Ad SetAtlas Ad Set AdAtlas Placement Ad Set

Remarketing segments

Remarketing segments let you target ads to groups of people who have already been to your advertiser’s website. You can target people (audience) based on pages they’ve visited, or actions that they’ve taken, such as making a purchase.

You must have universal tags and actions implemented on your advertiser’s website in order to create remarketing segments. Refer to Conversion Tracking guide for more information

Create an Atlas Segment

You can make a POST request to segments edge from the Atlas Advertiser to create a segment.

  • You need to specify segment definition which represents the constraints and action groups associated with the segment.
    • 'action_groups' defines a list of Atlas Segment Action Group which is a JSON format object with fields, actions (List of segment action definitions) and is_negtive (specifies if the segment action is negative)
    • segment action defines <ATLAS_ACTION_TAG_ID> and frequency constrainsts.

For example, you want to target people who have been to your website and added items to their shopping cart, but haven’t completed a purchase. You create an audience (a group of people with specific characteristics who you want to see your ad), and add a remarketing segment that says “show my ad to people who

  • added items to their shopping cart at least once the last month
    • include ("is_negative": false) event 1 (<ATLAS_ACTION_TAG_ID_1> in sample code)
    • time and frequency constraints ("lookback_begin_days_ago": "30", "min_count": "1")
  • but didn’t complete a purchase last month
    • exclude (is_negative": false) event 2 (<ATLAS_ACTION_TAG_ID_2> in sample code)
    • time and frequency constraints ("lookback_begin_days_ago": "30", "min_count": "1").

When you apply your audience to a targeting group, we’ll only show ads in that targeting group to people who completed action 1, but didn’t complete action 2.

Sample Code

curl \
-F 'segments=[{
   "definition": {
    "action_groups": [
      {
        "actions": [
          {
            "action_tag_id": "<ATLAS_ACTION_TAG_ID_1>",
            "lookback_begin_days_ago": "30",
            "min_count": "1"
          }
        ],
        "is_negative": false
      },
      {
        "actions": [
          {
            "action_tag_id": "<ATLAS_ACTION_TAG_ID_2>",
            "lookback_begin_days_ago": "30",
            "min_count": "1"
          }
        ],
        "is_negative": true
      }
    ],
  },
  "description": "test segment",
  "name": "My segment",
}]' \
-F 'access_token=<ACCESS_TOKEN>'  \
'https://graph.atlassolutions.com/<API_VERSION>/<ATLAS_ADVERTISER_ID>/segments'

Assign Segments to Audience

To assign segments to an exsisting audience, you need to update the audience with new complete definition including segments field. Updating an audience is similar to creation, making a POST request to audiences from path /<ATLAS_ADVERTISER_ID>/audiences, but need to specify id of the audience you want to update as a parameter.

curl \
-F 'audiences=[{
  "id": "<ATLAS_AUDIENCE_ID>",
  "definition": {
    "age": {
      "max": "60",
      "min": "32"
    },
    "device_types": [
      "mobile"
    ],
    "genders": [
      "female"
    ],
    "location_targeting_type": "home_or_current",
    "locations": {
      "countries": [
        {
          "key": "US",
          "name": "United States"
        }
      ]
    },
    "segments": [
        "<ATLAS_SEGMENT_ID>",
    ],
  },
  "description": "",
  "name": "test audience",
}]' \
-F 'access_token=<ACCESS_TOKEN>' \
'https://graph.atlassolutions.com/<API_VERSION>/<ATLAS_ADVERTISER_ID>/audiences'

Then make a GET request on that audience_id with fields=definition{segments} to explicitly fetch segments associated with the audience

curl -i -X GET \
 "https://graph.atlassolutions.com/<API_VERSION>/<ATLAS_AUDIENCE_ID>?fields=definition{segments{id}}&access_token=<ACCESS_TOKEN>"

You can get a list of segments in audience definition:

{
  "definition": {
    "segments": [
      {
        "id": "<ATLAS_SEGMENT_ID>"
      }
    ]
  },
  "id": "<ATLAS_AUDIENCE_ID>"
}

Reference: Atlas Segment