Share via

Bidders - Creative macro check service

  • Article

If you are running third party creatives, you can use this service to allow Xandr to check third party tags and append parameters in the query string, replace the domain, or insert Xandr click tracking macros in the appropriate place for you. We currently support the following ad servers: MediaMind, Atlas, Fetchback, and DoubleClick.

If we are able to insert the Xandr macros, then the new tag or URL will be returned in the response. If we are unable to ensure that the right macro was inserted (the value in the existing_other_macros or unmatched fields is not 0 within the response), then the value within the new_content or new_media_url field will not be displayed in.

REST API

HTTP method End point Description
PUT [https://api..com/creative-macro-check](https://api..com/creative-macro-check) (replace_pattern_in_content_url JSON) Replace content within a URL based on predefined patterns.
PUT [https://api..com/creative-macro-check?include_tests=1](https://api..com/creative-macro-check?include_tests=1) (replace_pattern_in_content_url JSON) Replace content within a URL based on predefined patterns and test patterns.

JSON fields

Field Type Description
content string Field is used when modifying content. The content that is being modified to include Xandr macros.
Required On: PUT, when transforming content
found_urls int The number of 'src=' or 'href=' URLs found in the creative content.
macro_replacements array An array with information about replacements that were done, listed out by macro type (e.g. cachebuster). See Macro Replacements below for more information.
matched_urls int The number of found_urls that are from a recognized ad server.
media_url string Field is used when modifying a media URL. The media URL that is being modified to include Xandr macros.
Required On: PUT, when transforming a media URL
new_content string Field is populated when modifying content. The updated content where all non-secure macros have been evaluated. This field will contain the same value as content unless all Xandr macros are successfully inserted.
new_content_secure string Field is populated when modifying content. The updated content where all macros, both secure and non-secure, have been evaluated. This field will contain the same value as content unless all Xandr macros are successfully inserted.
new_media_url string Field is populated when modifying a media URL. The updated media URL where all non-secure macros have been evaluated. This field will contain the same value as media_url unless all Xandr macros are successfully inserted.
new_media_url_secure string Field is populated when modifying a media URL. The updated media URL where all macros, secure and non-secure, have been evaluated. This field will contain the same value as media_url unless all Xandr macros are successfully inserted.
recognized_servers array of strings The names of the adservers that contain a URL pattern matching the value within the content or media_url field. See Macro Replacements below for more information.
warning string This field displays a warning message if the value within the new_content_secure or new_media_url_secure is not secure.

Macro replacements

Field Type Description
existing_appnexus_macro int The number of URLs where we were able to determine where to insert the macros.
existing_other_macro int The number of URLs where we were able to determine where to insert the macro, but there was already something there, so we left it alone. If this value is not 0, then the value within the new_content or new_media_url field will not be displayed in .
replaced int The number of URLs that had a macro for that type successfully inserted.
type string Specifies whether the object has information about the cachebuster or the click_url.
unmatched int Number of URLs for which we could not determine how to insert the macros. If this value is not 0, then the value within the new_content or new_media_url field will not be displayed in .

Recognized servers

Field Type Description
adserver_name string The name of the adserver.

Examples

Replace macros within a third-party tag (content)

The content field can include multiple URLs, however in this example the content field only contains one URL.

replace_pattern_in_content_url
{
        "creative-macro-check": {
                "content": "<a href=\"https://clk.atdmt.com/CCC/go/329458985/direct/01">test</a>"
        }
}

{
  "response": {
    "status": "OK",
    "creative-macro-check": {
      "new_content": "<a href=\"${CLICK_URL}https:\/\/clk.atdmt.com\/CCC\/go\/329458985\/direct\/01\">test<\/a>",
      "new_content_secure": "<a href=\"${CLICK_URL}https:\/\/clk.atdmt.com\/CCC\/go\/329458985\/direct\/01\">test<\/a>",
      "content": "<a href=\"https:\/\/clk.atdmt.com\/CCC\/go\/329458985\/direct\/01\">test<\/a>",
      "media_url": null,
      "new_media_url": null,
      "new_media_url_secure": null,
      "recognized_servers": [
        "Atlas"
      ],
      "recognized_server": "Atlas",
      "found_urls": 1,
      "matched_urls": 1,
      "macro_replacements": [
        {
          "type": "click",
          "replaced": 1,
          "existing_other_macro": 0,
          "existing_appnexus_macro": 0,
          "unmatched": 0
        }
      ],
      "warning": "new_content_secure contains some non secure urls"
    },
    "count": 1,
    "start_element": null,
    "num_elements": null
  }
}

Replace macros within a third-party URL (media URL)

replace_pattern_in_media_url
{
        "creative-macro-check": {
                "media_url": "https://clk.atdmt.com/CCC/go/329458985/direct/01"
        }
}

$ curl -b cookies -c cookies -X PUT -d 'https://api.adnxs.com/creative-macro-check'
{
  "response": {
    "status": "OK",
    "creative-macro-check": {
      "content": null,
      "new_content": null,
      "new_content_secure": null,
      "media_url": "https:\/\/clk.atdmt.com\/CCC\/go\/329458985\/direct\/01",
      "new_media_url": "${CLICK_URL}https:\/\/clk.atdmt.com\/CCC\/go\/329458985\/direct\/01",
      "matched_urls": 1,
      "new_media_url_secure": "${CLICK_URL}https:\/\/clk.atdmt.com\/CCC\/go\/329458985\/direct\/01",
      "recognized_servers": [
        "Atlas"
      ],
      "recognized_server": "Atlas",
      "found_urls": 1,
      "macro_replacements": [
        {
          "type": "click",
          "replaced": 1,
          "existing_other_macro": 0,
          "existing_appnexus_macro": 0,
          "unmatched": 0
        }
      ],
      "warning": "new_media_url_secure is not secure"
    },
    "count": 1,
    "start_element": null,
    "num_elements": null
  }
  }