Adverse script bundle · Adverse user guide

Ad Group Targeting Criteria

Within Adverse, Ad Groups will use publisher-provided criteria to target visitors via whitelist and blacklists.

In addition, any criteria given to the Adverse client may be used as macros in creative target urls and conversion pixels.

For example, if targeting based on "credit rating" is important, the Publisher can provide this information about the visitor and an Advertiser can use it for targeting in an Ad Group.

When the publisher is rendering the script, they can provide it as criteria:

<script
  src="https://adverse.lincx.la/ad"
  data-zone-id="abc123"
  data-credit-rating="excellent">
</script>

When Adverse is choosing ads to render in this zone it will be limited to the constraints of the available Ad Groups. For example, if an Ad Group has a targeting whitelist of creditRating: ['excellent', 'good'], it will be eligible to show Ads in this zone. Conversely, if instead it had a blacklist of creditRating: ['excellent'], it would not show ads in this zone.

In addition, the Advertiser may use this criteria as a macro in the Creative target url. Example: https://advertiser.com/offer?rating={{creditRating}}

Advertisers may use criteria as macros even if they do not wish to use them for targeting. This is commonly used for passing click ids or other tracking data through (aff-click-id is used as example below).

Publishers and advertisers may use any criteria for targeting as long as it does not conflict with a reserved setting name (listed below).

There are multiple ways to provide criteria to the Adverse client

Passing them to the script tag via data-* attributes (shown above)
Allowing the client to pull them from the URL query parameters
Providing them as an argument to the window.adverse() method

In addition to targeting criteria, the Adverse client accepts special settings that change its behavior. Below are the name, purpose, and example of each. With the exception of "Zone ID", all are optional.

Name	Value type	Meaning	Example
zone-id	A valid ID	REQUIRED: The id of a zone, `zoneId` should be already available when you copy the script tag	data-zoneId="12ik3b"
geo-state	2-char geo code (CA, AL...etc)	U.S. state used in adgroup targeting	data-geo-state="CA"
ad-feed-count	Integer Number	The number of ads rendered in a publisher's ad feed	data-ad-feed-count="3"
score-key	String	A special key used to optimize traffic, different keys will make the zone order differently depending on the source	data-score-key="A"
zone-load-cost	Real Number	This can be used to assign a traffic aquisition cost for reporting	data-zone-load-cost="0.123"
manual-render	true/false (default)	Whethere you want the script tag to render automatically or you want to control where to render the ads	data-manual-render="true"

Automatic Mode

By default, the client will use automatic render mode. That means the script tag will render the ads into its nearest parent HTML element. For example:

<div id="target">
  <script
    src="https://adverse.lincx.la/ad"
    data-zone-id="dg65mc">
  </script>
</div>

When the ads data is loaded from server, it will become:

<div id="target">
  <div id="ad-1">ad 1</div>
  <div id="ad-2">ad 2</div>
  <div id="ad-3">ad 3</div>
  <script
    src="https://adverse.lincx.la/ad"
    data-zone-id="dg65mc">
  </script>
</div>

This is an example of using more optional settings and criteria for targeting:

<div id="target">
  <script
    src="https://adverse.lincx.la/ad"
    data-zone-id="dg65mc"
    data-s1="trafficSourceA"
    data-s2="trafficSourceSubID"
    data-s3="otherNonUniqueIdentifier"
    data-aff-click-id="jrnt5zp9"
    data-score-key="trafficSourceA">
  </script>
</div>

Manual Render Mode Using `window.adverse`

When data-manual-render="true", manual render is enabled. After the script tag has finished loading its content, a helper method is available: window.adverse

window.adverse method definition:

window.adverse(target, opts)

Param	Value	Meaning
target	A valid HTML DOM Node	The container target that you want your ads rendered into
opts	Object	Options for rendering, equivalent to the `data-` params. For example `data-geo-state` will be `opts.geoState`

Example usage:

<!DOCTYPE html>
<html lang="en" dir="ltr">
  <head>
    <meta charset="utf-8">
    <title>Publisher.com</title>
  </head>
  <body>
    <div>
      <h1>Offers</h1>
      <div id="target">
        <!-- Ads will render here -->
      </div>
    </div>

    <!-- Load the Adverse Client in "manual" mode -->
    <script
      src="https://adverse.lincx.la/ad"
      data-manual-render="true">
    </script>

    <!-- Tell the Adverse Client where you would like ads to be rendered -->
    <script>
      var target = document.getElementById('target')
      window.adverse(target, {
        zoneId: 'abc123',
        // s1: 'trafficSourceA', // included in "default" reporting
        // s2: 'trafficSourceSubID', // included in "default" reporting
        // s3: 'otherNonUniqueIdentifier', // included in "default" reporting
        // affClickId: 'jrnt5zp9', // available as a macro
        // scoreKey: 'trafficSourceA', // segments scoring to only this label
      })
    </script>
  </body>
</html>

Using `data-` attributes through URL query string params

Instead of using data-* attributes or providing them to window.adverse(), they can be pulled from the URL query string params. Any URL query params prefixed with adverse- will be used.

https://publisher.com/somepage?adverse-color=red&adverse-otherCriteria=value

is the same as:

<script
  src="https://adverse.lincx.la/ad"
  data-zone-id="abc123"
  data-color="red"
  data-other-criteria="value">
</script>

which is also the same as:

window.adverse(target, {
  zoneId: 'abc123',
  color: 'red',
  otherCriteria: 'value'
})

Name conversion

data-* attributes have rules for name conversion and this is how it works:

dash-style to camelCase conversion:

Lowercase all ASCII capital letters (A to Z);
Remove the prefix data- (including the dash);
For any dash (U+002D) followed by an ASCII lowercase letter a to z, remove the dash and uppercase the letter;
Other characters (including other dashes) are left unchanged.

For example, a data-template-id attribute converted to templateId.

For more information, please check HTMLElement.dataset documentation.

Ad Group Targeting Criteria

Automatic Mode

Manual Render Mode Using window.adverse

Using data- attributes through URL query string params

Name conversion

Manual Render Mode Using `window.adverse`

Using `data-` attributes through URL query string params