Overview

Learn about your campaign performance with Atlas universal tags. These are HTML snippets you add to your website to see how actions on a website tie back to ads. For example, you can measure and optimize performance based on the number of website sales or conversions generated by ads.

Other actions you can track are page loads, clicks on a call to action, 45 seconds of a video played, or other events of interest.

With Atlas you can add a single universal tag to track your entire website and measure all activity relevant to your advertising goals. For more complex scenarios or separate websites you can implement more tags.

With each tag you can also attach additional relevant information you want to track. This includes order IDs, revenue, quantity, and other custom information. With this extra data you can see:

  • Revenue generated per placement.
  • Rlacements resulting in the highest sales.
  • Placements generating the most sales by product.

We describe how to implement Atlas universal tags in common website scenarios. Your actual implementation is specific to your site and may vary from this.

Universal Tags

Atlas generates universal tags as HTML code and you add them to the header code of an advertiser's digital properties, like websites and apps.

These tags collect data about activity people take on a website or app. To generate reports about this activity, set up actions.

You can create, read, update and delete universal tags for an advertiser by calling the Atlas multi action tag API endpoint, see Atlas Multi Action Tag Reference for details.

Create

To create a tag, make a POST request to /{atlas_advertiser_id}/multi_action_tags. A new tag name is the only parameter you need to provide.

curl \
-F "multi_action_tags=
[{
  'name':'A Universal Tag', 
  'description':'A description of the tag goes here.',
}]" \
-F "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/<atlas_advertiser_id>/multi_action_tags"

If the request succeeds, you get a response that includes the new tag id.

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

Using with Extended Data

Extended data lets you capture information about your campaign, such as order IDs or when people use coupon codes.

You should not send personally-identifiable information (PII) in tag requests.

To add extended data to a universal tag, make a POST request to /{atlas_multi_action_tag_id}/extended_data_columns with a list of JSON objects that define each extended data field. For each field, you must specify:

  • key - The name that links this item with the relevant data. The key is also used in the URL string that requests the data.
  • name - The name that appears for this extended data everywhere in Atlas, including the action rule builder, segment creation form, and reports.
  • aggregation_usage - Either a dimension, or value that isn’t a number, such as a product name, or metric, which is a number such as the number of minutes spent on the page.
curl \
-F "extended_data_columns=
[
   {
      'aggregation_usage':'metric',
      'key':'qty',
      'name':'Quantity'
   },
   {
      'aggregation_usage':'dimension',
      'key':'currency_code',
      'name':'Currency Code'
   },
   {
      'aggregation_usage':'dimension',
      'key':'order_id',
      'name':'Order Id'
   },

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

Each JSON object in the response corresponds to an extended data column in the request.

{
   "data":[
      {
         "id":"1107715542",
         "success":true
      },
      {
         "id":"110772015541",
         "success":true
      },
      {
         "id":"110772035543",
         "success":true
      }
   ]
}

Trafficking Universal Tags

Trafficking a universal tag is when you get tag code and implement it on your advertiser’s website or app. You can get tag code in four different formats: JavaScript, iFrame, Image, and In-App.

All four versions pass the same data to Atlas to report on conversions, with the exception of In-App, which requires extra mobile parameters. You should implement the JavaScript tag for your website if possible, since this tag best supports future tracking abilities.

Getting the Tags

Make a GET request to https://graph.facebook.com/<API_VERSION>/<atlas_multi_action_tag_id> and specify trafficking_tags as one of the fields.

curl "https://graph.facebook.com/<API_VERSION>/<atlas_multi_action_tag_id>?access_token=<ACCESS_TOKEN>&fields=trafficking_tags"

On success, you get this response with the universal tag code:

{
  "trafficking_tags": {
    "iframe_tag": "<iframe\n  style=\"display:none;\"\n  src=\"https://ad.atdmt.com/m/a.html;m=11077201135535;cache=?currency_code={currency_code}&amp;custom1={custom1}&amp;qty={qty}&amp;custom2={custom2}\">\n</iframe>",
    "image_tag": "<img src=\"https://ad.atdmt.com/m/img;m=11077201135535;cache=?currency_code={currency_code}&amp;custom1={custom1}&amp;qty={qty}&amp;custom2={custom2}\" />",
    "javascript_tag": "<script>\n  var e = document.createElement(\"script\");\n  e.async = true;\n  e.src = \"https://ad.atdmt.com/m/a.js;m=11077201135535;cache=\" + Math.random() +\n    \"?currency_code={currency_code}\" +\n    \"&custom1={custom1}\" +\n    \"&qty={qty}\" +\n    \"&custom2={custom2}\";\n  var s = document.getElementsByTagName(\"script\")[0];\n  s.parentNode.insertBefore(e, s);\n</script>\n<noscript>\n<iframe\n  style=\"display:none;\"\n  src=\"https://ad.atdmt.com/m/a.html;m=11077201135535;noscript=1?currency_code={currency_code}&amp;custom1={custom1}&amp;qty={qty}&amp;custom2={custom2}\">\n</iframe>\n</noscript>",
    "in_app_tag": "https://ad.atdmt.com/m/img;m=11077201135535;idfa=;idfa_lat=;aaid=;aaid_lat=;cache=;ua=;client_ip=;timestamp=?currency_code={currency_code}&custom1={custom1}&qty={qty}&custom2={custom2}"
  },
  "id": "11070135535"
}

Place this code in all website pages or apps where you want to collect data. When you add or edit extended data associated with a universal tag, you need to customize all code in {...}.

To enable cache busting in IFrames, images and in-app versions, add a random number after cache=. JavaScript tags have automatic cache busting. You may have to run the tag code through a decoder to remove escaped and special characters.

Adding to Websites

The most common scenario for universal tags is when you add it to all pages of a site and track all page loads. To do this, you should add a tag to the top of the page, right after the <body> tag so the tag loads on every page load.

Do not put the tag in an iFrame otherwise it cannot properly track your site activities.

Universal tags are in three formats, listed from most to least recommended:

  • JavaScript
  • IFrame
  • Image

Javascript Tags

You should use JavaScript universal tags on your site whenever possible. This format has the most flexibility, comprehensive functionality, and compatibility with future Atlas features. They minimize the need to re-tag your site.

The JavaScript tag format automatically enables cache-busting and asynchronous tag loading which reduces impact to page load times and increases the accuracy of your tag.

Example JavaScript Tag

This is the most common tag you can add to your website.

<script>
    var an = document.createElement("script");
    an.async = !0, an.src = "http://ad.atdmt.com/m/a.js;m={Universal Tag ID};cache="+Math. random();var s=document.getElementsByTagName("script")[0];s.parentNode.insertBefore(an,s);
</script>
<noscript>
    <iframe frameborder='0' scrolling='no' marginheight='0' marginwidth='0' topmargin='0' leftmargin='0' allowtransparency='true' style='display:none;' src='http://ad.atdmt.com/m/a.html;m={Universal Tag ID};noscript=1'></iframe>
</noscript>

Example JavaScript Tag with Extended Data

<script>
    var an = document.createElement("script");
    an.async = !0, an.src = "http://ad.atdmt.com/m/a.js;m={Universal Tag ID};cache="+Math. random()+"?nights={nights}&revenue={revenue}&order_id={order_id}&qty={qty}";var s=document.getElementsByTagName("script")[0];s.parentNode.insertBefore(an,s);
</script>
<noscript>
    <iframe frameborder='0' scrolling='no' marginheight='0' marginwidth='0' topmargin='0' leftmargin='0' allowtransparency='true' style='display:none;' src='http://ad.atdmt.com/m/a.html;m={Universal Tag ID};noscript=1?nights={nights}&revenue={revenue}&order_id={order_id}&qty={qty}'></iframe>
</noscript>

There are events you cannot track on page loads; for example you cannot track clicks on an Expand button. To do this, change the JavaScript so the tag fires when the button is clicked.

The JavaScript code sample below tracks page events. You need to update the event syntax depending on your website code structure and stack:

Example Javascript Tag on an Event

In this example, when someone clicks on the HTML element with ID #expand-btn, the tag records that as a page event.

$('#expand-btn').on('click', function(){
$.getScript('http://ad.atdmt.com/m/a.js;m={Universal Tag ID}?event=expand');
});

Example Javascript Tag with Extended Data on an Event

This example shows how to track events beyond page load with additional data about the page event. We run a function getProductName() to get the name of the product someone clicks. We send this information in the tag back to Atlas.

$('#expand-btn').on('click', function(){
var extended_data = {
event: 'expand',
location: 'bottom',
product: getProductName()
};
$.getScript(‘http://ad.atdmt.com/m/a.js;m={Universal Tag ID}?’ + $.param(extended_data));
});

IFrame Tags

If you cannot use JavaScript on your site, implement an iFrame tag. Some features available in the JavaScript tag are unavailable in the iFrame tag format. Make sure your implementation of iFrame tags includes a cache buster for higher quality data.

Example IFrame Tag

Below is a basic iFrame tag:

<iframe frameborder='0' scrolling='no' marginheight='0' marginwidth='0' topmargin='0' leftmargin='0' allowtransparency='true' style='display:none;' src='http://ad.atdmt.com/m/a.html;m={Universal Tag ID};cache='></iframe>

Example IFrame Tag with Extended Data

This tag shows how you can pass extra data like order_id, revenue and quantity to Atlas.

<iframe frameborder='0' scrolling='no' marginheight='0' marginwidth='0' topmargin='0' leftmargin='0' allowtransparency='true' style='display:none;' src='http://ad.atdmt.com/m/a.html;m={Universal Tag ID};cache=;?nights={nights}&revenue={revenue}&order_id={order_id}&qty={qty}'></iframe>

Image Tags

If you cannot use JavaScript or IFrame tags, you can use image tags. These are similar to an iFrame tag, however some features available in the JavaScript or iFrame tags are unavailable in the image tag format.

The tag displays a 1x1 gif. Make sure your implementation of image tags includes a cache buster for higher quality data.

Example Image Tag

Below is a basic image tag you can place on pages you want tracking on.

<img src='http://ad.atdmt.com/m/img;m={Universal Tag ID};cache=' />

Example Image Tag with Extended Data

Below is an image tag that passes extra data back to Atlas.

<img src='http://ad.atdmt.com/m/img;m={Universal Tag ID};cache=;?nights={nights}&revenue={revenue}&order_id={order_id}&qty={qty}' />

This code samples contain {Universal Tag ID} which you replace with the Atlas universal tag id you exported from Atlas UIs or received with the API.

If your tags include extended data, replace the {...} sections of the code with actual data values.

Adding Tags to Mobile Apps

With universal tags, you can track important in-app events on your own or through an app event partner. Events that you can track include app-installs, in-app engagements or in-app purchases.

You can also attach additional information as extended data with each tag request. This include app-engagement events, revenue and quantity for in-app purchases and other information for your advertising goals. With extended data you can see:

  • How many people took a specific action in your app because of an ad
  • Which placements resulted in the highest in-app sales
  • Which placements drove the most app-installs

Do not send personally identifiable information (PII) in tag requests.

We describe how to implement Atlas universal tags in a few common scenarios for in-app measurement. Your implementation may vary from this guide depending on your requirements.

There are two main methods to add tracking in your app: client-side or server-side. In addition, server-side can be directly from your advertiser's domain or via an app event partner you may already have a relationship with and is your preferred method.

In-App universal tag format

The syntax for calls to Atlas are the same in both methods, but the logic for constructing these requests differ from client-side to server-side. Since there is no referring URL for in-app activity, you need to pass extended data to Atlas in order to create actions.

The format below is how to structure all requests to the Atlas endpoint in a server-to-server scenario. In this example, “ed_key” and “ed_value” are arbitrary extended data keys and values. You can replace them with any naming convention you want. See specific examples below. The table below explains all the non-extended data keys that are required to be passed to Atlas.

http://ad.atdmt.com/m/a.html;m={Universal_Tag_ID};idfa={idfa};idfa_lat={idfa_lat};aaid={aaid};aaid_lat={aaid_lat};cache={cachebuster};ua={ua};client_ip={client_ip};timestamp={timestamp}?ed_key1={ed_value1}&ed_key2={ed_value2}
RequiredCategoryParameter NameDescriptionExampleNotes

Required

Device Identifier

idfa

Apple identifier for advertisers

clear: AEBE52E7-03EE-455A-B3C4-E57283966239

sha1: d681a3fe9f34df 2cbf914a0 04f4e7c75a58ede2e

md5: 0a7d55 fae 162c03876813 18190 657f68

We can accept the idfa in the clear (hexadecimal UID), or unsalted sha1 or md5 hashes of the idfa (make sure to include the dashes in idfa value when performing the hash).

Required

Device Identifier

aaid

Android advertising id

clear: AEBE52E7-03EE-455A-B3C4-E57283966239

sha1: d681a3fe9f34df 2cbf914a0 04f4e7c75a58ede2e

md5: 0a7d55 fae 162c03876813 18190 657f68

We can accept the aaid in the clear (hexadecimal UID), or unsalted sha1 or md5 hashes of the idfa (make sure to include the dashes in aaid value when performing the hash).

Required

Device Identifier

idfa_lat

Apple iOS limit ad tracking signal for idfa

false: limit ad tracking not enabled

true: limit ad tracking is enabled

Required

Device Identifier

idfa_lat

Android "opt out of interest based advertising" signal for aaid

false: limit ad tracking not enabled

true: limit ad tracking is enabled

Required

Other

cache

random string for cache busting

234398131

Required for server to server

Server to Server

ua

user agent string for the client device's ad request

Mozilla/5.0 (Linux; U; Android 4.0.3; ko-kr; LG-L160L Build/IML74K) AppleWebkit/534.30 (KHTML, like Gecko) Version/4.0 Mobile Safari/534.30

This is usually specified by default in the HTTP request header. In some server-to-server scenarios, the user agent string in the request header could be the UA of the server. In those cases, we require that the client device user agent is specified as an HTTP request parameter.

Required for server to server

Server to Server

client_ip

ip address of the client device's HTTP connection

171.65.92.220

This is usually specified by default in the HTTP request header. In some server-to-server scenarios, the ip address in the request header could be the UA of the server. In those cases, we require that the client device ip address is specified as an HTTP request parameter or alternatively speci-fied as a X-Forwarded-For field in the HTTP request header.

Required for server to server

Server to Server

timestamp

Unix timestamp in seconds of the client device's request

1427238954

When making server-to-server requests to our ad server, there can be delays between when a client device makes a request and when the server makes a request to the Atlas servers. In order to make sure that we apply filtering logic correctly, it's important to pass the timestamp of the client device's request as a query string parameter.


Sample Call from Mobile Client

URL url = new URL("https://ad.atdmt.com/m/img;m=11077201133223;idfa=;idfa_lat=;aaid={aaid};aaid_lat={aaid_lat};cache=;ua=;client_ip=;timestamp=?revenue={revenue}&event=purchase");

HttpURLConnection urlc = (HttpURLConnection) url.openConnection();
urlc.setRequestProperty("User-Agent", "Android Application:"+Z.APP_VERSION);
urlc.setRequestProperty("Connection", "close");
urlc.connect();

Limit Ad Tracking

You should always pass Atlas the Limit Ad Tracking flags, such as idfa_lat, or aaid_lat. You can use universal tag data to create retargeting segments from website or app data so you must also respect any user opt-outs. Pass Atlas the Limit Ad Tracking flags every time so we can honor the user's choice to opt-out of ads.

Server-to-Server Implementations

You should send ad calls for ad campaigns via server-to-server. We can accept calls to Atlas directly from the client-side when this is not possible. In these instances, the standard required parameters still apply. When the call is server-to-server then the user agent string, ip address, and timestamp of the client device's request need to be present in the Atlas request so we can properly filter and attribute conversions.

Sample Call from Server

Submit a GET request to

https://ad.atdmt.com/m/img;m=11077201133223;idfa=;idfa_lat=;aaid={aaid};aaid_lat={aaid_lat};cache=;ua=;client_ip=;timestamp=?revenue={revenue}&event=purchase

App Event Partnerships

Atlas works with any app event partner you work with, and Atlas has existing relationships with some app event partners so the setup is simpler. If you have questions about how to work with Atlas and your app event partner, contact your Atlas account or support team.

Creating Actions

Actions are rules that track and report specific website activity, such as if someone visited a URL on your website, or whether an event occurred, such as a conversion. To generate reports about this, add a universal tag to a website, then set up actions to filter and report activity collected by the tag. You then can run conversion reports to see how many people who saw ads went to the website and completed actions important to you.

To run conversion reports for your campaign, implement actions with your universal tag before your campaign starts.

Click here to see the API reference documentation and see below for examples.

To create an action, make a POST request to /{atlas_advertiser_id}/action_tags. For each action, specify action specific data such as name, multi_action_tag_id and view_window_seconds as well as rule_set which is an array of rules to filter data from the universal tag.

The key value you provide in the ruleset must be present in the tag that you specify in multi_action_tag_id.

You must also set type to atlas_new.

See a full list of fields and descriptions at Atlas Action, Reference.

curl \
-F "action_tags=
[
   {
      'click_window_seconds':7776000,
      'multi_action_tag_id':'1240771135450',
      'name':'My action name',
      'order_id_window_seconds':0,
      'repeat_conversion_window_seconds':60,
      'view_window_seconds':1209600,
      'type': 'atlas_new',
      'rule_set':{
         'rules':[
            [
               {
                  'aggregation_usage':'dimension',
                  'key':'preference',
                  'name':'Preference',
                  'op':'string_contains',
                  'operand':'yes'
               }
            ],
            [
               {
                  'aggregation_usage':'metric',
                  'key':'revenue',
                  'name':'Revenue',
                  'op':'number_greater_than',
                  'operand':'2000'
               }
            ]
         ]
      },
   }
]" \
-F "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/<atlas_advertiser_id>/action_tags"
{
   "data":[
      {
         "id":"110201135687",
         "success":true
      }
   ]
}

Third-Party Tags

This is code that vendors outside of Atlas use to collect data about actions taken on websites. Before you send Atlas data to a third-party tag, you should associate your third-party tag with your actions. Actions include rules to gather data when specific events happen. For example, if your associated action tracks when people sign-up for a newsletter, it fires your third-party tag when someone takes this action. Use existing actions or create new ones and work with your third-party partner to get the JavaScript or HTML code for your third-party tracking tag.

Note the following:

  • You must have a JavaScript or iFrame universal tag implemented on your website.
  • You must agree to the terms of service for third-party tag management.
  • Do not pass any personally identifiable information (PII) through the third-party tag. Atlas automatically prevents you from passing email addresses, social security numbers, phone numbers, ZIP and postal codes. In addition, do not pass anything else that might be considered personally identifiable information (PII) such as cookie IDs, device IDs, loyalty IDs
  • If you use a third-party tag currently being used for an ad campaign run outside of Atlas, you may count conversions twice if you combine the reports: once in Atlas, and once in your third-party tracking system.

Atlas currently supports all third-party tags, however not all third-party tracking systems support associations with an action. Work with your partner to obtain the right JavaScript or HTML code block for your third-party tracking.

See a full list of fields and their descriptions here.

Creating Third-Party Tags

To create a third-party tag, make a POST request to /{atlas_advertiser_id}/external_tags. Please note that name and body are required fields.

curl \
-F "external_tags=[
   {
      'body':'<script>(function(){//call to 3rd party tracking here})()</script>',
      'is_active':true,
      'name':'Third Party Tag Name',
      'vendor':'Vendor Name',
   }
]" \
-F "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/<atlas_advertiser_id>/external_tags"
{
   "data":[
      {
         "id":"11070113720",
         "success":true
      }
   ]
}

Firing Third-Party Tags

Before you send Atlas data to a third party, you need to associate your third-party tag with some of your actions. Actions are the rules that fire third-party tags. Anytime an action collects data from an advertiser's site it will fire your third-party tag. You can use existing actions or create new ones.

To associate actions with a third party tag, make a POST request to /{third_party_tag_id}/action_tags with a list of action ids.

curl \
-F "action_tags=[
   {
      'id':'1107723568'
   },
   {
      'id':'11070113562'
   }
]" \
-F "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/<third_party_tag_id>/action_tags"
{
   "data":[
      {
         "id":"11077201162",
         "success":true
      },
      {
         "id":"11020113567",
         "success":true
      }
   ]
}