Tracking Client Documentation

The following documentation is for v2.

Configuration Changes

Please see the Full Config section for the new config layout.

Storage Engine Changes

The storage engine was rewritten to support cookies as alternative storage. Storage keys, names, variables and content were changed to reduce the storage volume for cookies.

Please verify that you are not accessing any localstorage entries starting with assertive_analytics_. If you are using them, please take a look at the new storage keys in your browsers dev tools. Depending on the storage mode selected they can be found under Local Storage or Cookies on your domain.

For example: assertive_analytics_sessionUTM was renamed to ay_utm_s.

Configuration

Important the configuration needs to be defined before the client is initialized otherwise certain modules won't load.

window.assertive = {
    debug: true, // append the query string 'assertiveYield=debug' or add this local storage entry 'localStorage.setItem("assertiveYield", "debug")' to enable dynamically
    entityId: "...", // your entity id from the dashboard see: https://suite.assertiveyield.com/welcome
    analytics: {
        sampleRate: 1, // 1 = all sessions are tracked, 0.5 = 50% of the sessions are tracked...
        custom: {
            // optional dimensions for custom data, they expect null or string
            layout: null,
            userState: null,
            custom_1: null,
            custom_2: null,
            custom_3: null,
            custom_4: null,
            custom_5: null,
            custom_6: null,
            custom_7: null,
            custom_8: null,
            custom_9: null,
        },
    },
};

Loading the Client

For loading the tracking client you have two options:

1. Provided (hosted on our CDN and updated automatically)
2. Self-Hosted (hosted by you, updates are in your control)

Provided

To load the client just copy and paste the following. Please don't forget to replace the < your entity id > placeholder with your entity id.

<script src="https://< your entity id >.ay.delivery/client-v2.js" async></script>

Self-Hosted

When hosting the client yourself or bundling it with your other javascript code, please fetch the latest version from the link above.

Staying up to Date

On the Welcome page of Assertive Yield (in the Version column) you can see the latest version in use and will be informed when your client is outdated.

Debug Mode

The debug mode can be enabled in three different ways:

1. URL Param
2. LocalStorage (persistent within the browser)
3. Config (persistent across browsers)

URL Param

When appending the following param to your URL, Assertive Yield will log debugging information: ?assertiveYield=debug. When navigating to different pages within the website this param is being removed and debugging disabled.

LocalStorage

The following local storage entry, will enable the AY debug logging mode. Local storage is persistent within the browser it was set. To do this run the following code in your browser console on the domain you want to enable it on:

localStorage.setItem("assertiveYield", "debug");

Config

The config option will enable the debugging mode globally for every user on every device. To enable it set or change the debug variable in the settings to true.

window.assertive.debug: true

API Reference

nextPage

Initiates a new page view event for single page apps. Unless your Website is a single page app, this is not necessary.

Syntax

assertive.nextPage()

logCustomImpression

Allows sending custom impression data in order to track various revenue sources.

Important sending data in the wrong format or form can cause reporting limitations and issues. We highly advise you to consult with us before implementing this.

Syntax

assertive.logCustomImpression(data)

Parameters

Return value

The passed slotId.

Examples

var data = {
    slotId: 'video_player',
    adUnitPath: 'video_player',
    highestPreBid: 0,
    highestPreBid_partner: 'video_bidder',
    mediaType: 'video',
    creative_width: 300,
    creative_height: 250,
    preBidWon: true,
    timeToRespond: null,
};
window.assertive.logCustomImpression(data);

logCustomView

Mark the last impression of slotId as viewable.

Syntax

assertive.logCustomView(slotId)

Parameters

logCustomClick

Mark the last impression of slotId as clicked.

Syntax

assertive.logCustomClick(slotId)

Parameters

setConfig

Overwrites and extends the existing config with the given option values.

Syntax

assertive.setConfig(config, value)

Parameters

Examples

assertive.setConfig('analytics.custom.custom_1', 'new value');

assertive.setConfig({
    analytics: {
        custom: {
            custom_1 'new value',
            custom_2 'new value 2',
        }
    }
});

assertiveQueue

Function command queue for asynchronous execution of tracker functions.

Syntax

assertiveQueue.push(callback)

Parameters

Examples

window.assertiveQueue = window.assertiveQueue || [];
window.assertiveQueue.push(function () {
    console.log('Assertive Yield ready!');
});

Full Config

Important please do not copy this config. It will configure parts you don't use and won't work without being fully adjusted to your needs. This should only be used as a reference on what is possible/available. Only configure what you need or need to overwrite from the defaults.

Please see the feature sections for details.

window.assertive = {
    debug: true, // append the query string 'assertiveYield=debug' or add this local storage entry 'localStorage.setItem("assertiveYield", "debug")' to enable dynamically
    entityId: '...',
    analytics: {
        sampleRate: 1, // 1 = all sessions are tracked, 0.5 = 50% of the sessions are tracked...
        custom: {
            // optional dimensions for custom data
            layout: '...',
            userState: '...',
            custom_1: '...',
            custom_2: '...',
            custom_3: '...',
            custom_4: '...',
            custom_5: '...',
            custom_6: '...',
            custom_7: '...',
            custom_8: '...',
            custom_9: '...',
            timeout: 0, // if not defined the timeout is retrieved from prebid
            revenueBias: 1, // multiplies the revenue based on the value
        },
        integrations: {
            nativo: true, // defaults to true
            ima: false, // defaults to false
            webAnalytics: false, // defaults to false
        },
        logUnfilled: false, // defaults to false
        useHistoryChangeTrigger: false, // Initiates a new page view event when the URL changes
        override: {
            adid: 'hb_adid',
            creativeRegex: '...',
            pbjs: 'pbjs',
            adServerCurrency: false, // if defined, all values are converted to this currency before they are logged (for secondary currency)
            utm: {
                // AY picks this up from the URL, if you don't use the utm schema you can override the value here, expects a string.
                utm_source: false,
                utm_medium: false,
                utm_campaign: false,
                utm_term: false,
                utm_content: false
            }
        },
    },
    // options for the precise AdX revenue on any dimension feature
    hash: {
        generator: ..., // 'server' or 'client'
        key: '...', // function returning a string
        values: 5000,
        subCacheId: '', // allows setting of sub cache, each unique sub cache id will have its own allocation of key-values. Only works with generator server (default undefined)
        override: {
            targetingKey: 'ay_hash',
        },
    },
    acquisition: {
        enabled: true, // defaults to false
        costParams: ['utm_cost'], // list (array) of url parameters to check for the cost. Will check for numeric as well as encrypted values behind these parameters - defaults to undefined (disabled)
        currency: 'USD', // default USD
        clickIdParams: undefined,
        // default is an array of common clickId url parameters:
        // [
        //     'fbclid', // facebook
        //     'gclid', // google
        //     'tblci', // taboola
        //     'obclid', // outbrain
        //     'vmcid', // gemini (yahoo)
        // ],
        // !!!only change if needed!!!
    },
    // options for the flooring feature
    floor: {
        enabled: true,
        paused: false, // if set to true, it will stop setting floors while keeping the logging active
        entityId: '...', // defaults to assertive.entityId
        currency: 'USD', // ISO currenc codes
        paramMappings: { ... },
        prebid: true, // Set prebid floors before sending requests to bidders
        limit: {
            slotIds: ['...', '...'], // Whitelist of slotIds to enabled flooring on (default all)
            percentage: 0.9, // Run on 90% of the users (default 98%)
        },
    },
    // options for the revenue prediction feature
    predict: {
        enabled: false,
        entityId: '...', // defaults to assertive.entityId
        limit: {
            slotIds: ['...', '...'], // Whitelist of slotIds to enabled prediction on (default all)
            percentage: 0.9, // Run on 90% of the users (default 98%)
        },
    },
    // options for the bid request reduction feature
    reduction: {
        enabled: false,
        entityId: '...', // defaults to assertive.entityId
        limit: {
            slotIds: ['...', '...'], // Whitelist of slotIds to enabled reduction on (default all)
            excludeBidders: [], // defaults to no exclude
            includeBidders: [], // defaults to all bidders
            percentage: 0.9, // Run on 90% of the users (default 98%)
        },
    },
    // storage engine option
    storage: {
        general: 'localStorage', // or 'cookie'
        utm: 'localStorage', // or 'cookie'
        bids: 'localStorage', // or 'cookie'
        session: {
            timeout: 30, // minutes of user inactivity after which a session is closed (default 30)
            resetOn: {
                paramChange: [
                    'utm_campaign',
                    'utm_medium',
                    'fbclid', // facebook
                    'gclid', // google
                    'tblci', // taboola
                    'obclid', // outbrain
                    'vmcid', // gemini (yahoo)
                ], // default empty array
                referrerChange: false, // default false,
                func: function() {return false;}, // custom function, true = session reset
            }
        },
    },
}