Tagging guide 3 - advanced features

Overview

Related articles

• Tagging guide 1 - overview
• Tagging guide 2 - implementation  

Refreshing ads

sas.refresh([formatId]) / sas.refresh([tagId])

• the formatId can be integer, string or array
• if no formatId is specified, all the ad calls done in the page will be reloaded
• if a formatId is specified, the ad will be called using the standard call type; this applies even if the ad was previously called using the OneCall call type

sas.refresh([options])

• forceMasterFlag – Forces the master flag which is used for page view counting. If the master flag is true, the ad call returns an ad (as usual) and the ad call is logged and reported as a page view (page impression); type: boolean, default value: false;
• resetTimestamp – Resets the timestamp which is used for features such as links (displaying ads from insertions always together on a page) or exclusions (never display ads from certain insertions together on a page); type: boolean, default value: true;
• target – Updates the target criteria for the specified format. For more information on the target parameter, see above chapters; type: string, default value: undefined; you can alter the target criteria of a specified format. The following rules apply:
  • If the target option is unspecified (value undefined), the original target will not be altered.
  • If the target option is set to an empty string (""), the target will be cleared.
  • If the target option is set to a non-empty string, the specified string will become the new target.

sas.refresh method examples 

// refresh the format id 12345
sas.refresh(12345);
// refresh the format and force master flag
sas.refresh(12345, { forceMasterFlag: true });
 
// refresh all formats
sas.refresh();
// refresh all formats and force master flag
sas.refresh({ forceMasterFlag: true });
 
// refresh all formats and clear the target
sas.refresh({ target: "" });
// refresh all formats and update the target
sas.refresh({ target: "age=42" });
 
// refresh the format id 12345 and update its target
sas.refresh(12345, { target: "sex=m" });

// refresh the format id 12345, update its target, and force master flag
sas.refresh(12345, { target: "country=uk", forceMasterFlag: true });

// refresh the tagId sas_tag_001 and update its target 
sas.refresh("sas_tag_001", { target: "sex=m" });

Lazy loading

Lazy loading example

// Configuration of lazy loading
    sas.cmd.push(function () {
    sas.enableLazyLoading({
        fetchRatio: 0.3, 
        mobileFetchRatio: 1.1,
        formats: [84313]

GDPR consent data

Example

sas.setGdprConsentData("BONmEt0ONmEt0AtABBFRAR-AAAAJqABgAQASoA");

Extended user IDs

Digital Services Act (DSA) transparency data

Seller defined Audiences/Context data

• sas.setSda for SDA (corresponds to the user.data object in open RTB integrations)
• sas.setSdc for SDC (corresponds to the site.content.data object in open RTB integrations)

Sda / Sdc object

Segment object

Sample

Header Bidding data

• bidder – name of the bidder; type: string;
• cpm – bidder CPM; type: number;
• currency – CPM currency symbol ("EUR", "USD", etc.); type: string;
• dealId – (optional) deal id in case of a preferred deal; type: string;

Examples

// no deal
sas.setHeaderBiddingWinner("myTagId", {
    bidder: "AppNexus",
    cpm: "1.4",
    currency: "USD"
});

// with deal
sas.setHeaderBiddingWinner("myTagId", {
    bidder: "AppNexus",
    cpm: "1.4",
    currency: "USD",
    dealId: "12334-ad-1267821-fhe"
});

Events

• event – string: the event to listen to;
• callback(data)– function: called every time the event is fired;
• id – string: optional, allows you to filter an event and to be notified only on this id;

Supported events

• "call" : triggered every time sas.call is called
  • data – object: contains the data provided in sas.call (callType, ad, options)
  • id – represents the tagId

var onCallCallback = function(event) { /* put your event logic here */ };

// register to all "call" events
sas.events.on("call", onCallCallback);

// register to standard call events
sas.events.on("call", onCallCallback, "std");

• "noad": triggered every time there is no ad in a placement
  • data –  object: contains the placement data (formatId, instance, tagId)
  • id –  represents the tagId

var onNoadCallback = function(event) { /* put your event logic here */ };

// register to all "noad" events
sas.events.on("noad", onNoadCallback);

// register to noad only for tag "sas_1234"
sas.events.on("noad", onCallCallback, "sas_1234");

• "clean": triggered every time a placement is cleaned
  • data –  object: contains the placement data (formatId, instance, tagId)
  • id –  represents the tagId

// clean the format 300
sas.clean(300);

// clean all formats
sas.clean();

Callbacks

• onLoad – callback is called after an asynchronous call has been successfully performed;
• onError – callback is called in case an error occurred during the call;
• onClean(formatId, element) – callback is called before cleaning the placement;
• beforeRender(data) – callback is called before the format rendering (sas.render); it is only called when OneCall tag call has returned; if sas.render is called before the OneCall has returned (sas_manager created), beforeRender will not be called; the data (object) contains the rendering context (formatId, tagId);
• onAd(data) – callback is called when Equativ returns an ad to be displayed for a given format;
• onNoad(data) – callback is called if there is no ad to display for the given format, if provided for callType="onecall"; the callback will be triggered for each empty format; data.tagId (string): the tag id of the noad; data.formatId (string): the format id of the noad;

Retrieving event history

Examples

// retrieve all events already fired
var events = sas.events.history();

// retrieve all "noad" events already fired
var noadEvents = sas.events.history("noad");

Updating the keyword targeting string

Related articles

• Tagging guide 1 - overview
• Tagging guide 2 - implementation