Inserting Macros for Third-Party Ad Tags
When using third-party ad tags, you need to insert various macros into the tag so it correctly tracks clicks in Basis.
Below lists how to insert macros in tags from common third-party ad servers.
Aarki is a mobile rich media vendor.
Aarki supports receiving other values that the DSP can provide using macros. See the Aarki Tag Tracking Guide for more information.
Remember to traffic MRAID ads using the MRAID option in Basis or they may not deliver correctly. Use MRAID 1 unless you know otherwise.
By default, Aarki activates the Basis click tracker only on clicks through to the destination page ("clickthrough"). They don't fire it on interactions within the ad. This differs from how other rich media vendors do it.
Celtra, for example, fires on first interaction. If you want Aarki to fire a Basis click tracking link on other events replace click_esc with one of the following:
-
expand_esc: For tracking ad expansions
-
int_esc: For tracking user’s first interaction (similar to Celtra behaviour)
This is how Aarki defines each event:
-
Expansion: When an expandable banner is expanded
-
Interaction: Any first touch or click within the ad
-
Clickthrough: When a user clicks out of the creative
In the examples below, the string &click_esc={clickMacroEsc}
is added in the example with macros.
Example tag without macros inserted:
<script type="text/javascript" src="mraid.js"></script><script type="text/javascript" id="aarki_1234">
(function() { document.write('<script id="mobspire-ad-tag" '+'src="http://rm.aarki.net/v1/ads/1234/aarki_inapp.js?
cb='+Math.random()+'&ots='+(new Date()).getTime()+'&channel=Basis"></scr'+'ipt>');})();</script>
Example with macros inserted:
<script type="text/javascript" src="mraid.js"></script><script type="text/javascript" id="aarki_1234">
(function() { document.write('<script id="mobspire-ad-tag" '+'src="http://rm.aarki.net/v1/ads/1234/aarki_inapp.js?
cb='+Math.random()+'&ots='+(new Date()).getTime()+'&channel=Basis&click_esc={clickMacroEsc}"></scr'+'ipt>');})();</script>
To make Adform tags work with Basis, make the following edits to the tag:
-
;click={clickMacro}
: add to theSCRIPT SRC
attribute after"?bn=XXXXX"
-
XXXXX
should be a number, but could have letters as well.
-
-
{clickMacro}
: add to the aA HREF
beforehttp://track.adform.net
-
Replace
[timestamp]
with{ts}
Example tag from AdForm
<script language="javascript" src="http://track.adform.net/adfscript/?bn=1234"></script>
<noscript>
<a href="http://track.adform.net/C/?bn=1234;C=0" TARGET="_blank">
<img src="http://track.adform.net/adfserve/?bn=1234;srctype=4;ord=[timestamp]" border="0" width="468" height="60" alt="">
</a>
</noscript>
Use auto macro insertion by selecting Insert macros when uploading ad tags.
Celtra provides a tag generator page to allow buyers to collect an appropriately formatted ad tag. If you receive an actual tag from a customer instead of the link to the tag generator page, you should ask for this link so you can collect the right type of tag.
Be aware that MRAID ad tags cannot be directly tested on the Basis preview page, as they require the MRAID environment to be present.
To generate tags, go to the provided tag generator page. You must collect two different types of tags for in-app and mobile web. The ad formats supported depend on the inventory type as shown in the table below.
Inventory Type | Ad Formats Supported | SDK to Select on Celtra tag generator |
---|---|---|
Mobile App |
Mobile and tablet expandable banners (320x50, 728x90) Mobile and tablet interstitials (320x480, 480x320, 1024x768, 768x1024) |
MRAID |
Mobile Web | Mobile and tablet expandable banners (320x50, 728x90) | Web |
Desktop, Mobile Web, Mobile App | Standard, non-expandable banners | Web |
Scale is very limited for mobile web expandables due to a lack of mobile web inventory carrying the signal where expandables are supported.
In-app (expandable banners and interstitials)
Select the following settings on the tag generator page:
-
Select SDK: MRAID
-
Ad Server: Basis
Collect the ad markup from the bottom of the page, and upload to Basis as an MRAID 1 Ad Tag.
You must upload the ad as an MRAID Ad Tag. Uploading as a regular ad tag or an Expandable (Web) ad tag will result in the ad running in environments where it will not render correctly.
Web
Select the following settings on the tag generator page:
-
Select SDK: Web
-
Ad Server: Basis
Collect the ad markup from the bottom of the page, and upload to Basis as an Ad Tag (if non-expanding) or Expandable (Web) Ad Tag if it has expansion.
If the ad has expansion, you must upload the ad as an Expandable (Web) Ad Tag. Uploading as a regular ad tag or an MRAID ad tag will result in the ad running in environments where it will not render correctly.
OS version targeting
Celtra tags are only compatible with Android 4+ or iOS 6+. Consider targeting only these OS versions using the Device Targetingsection in Basis.
You will receive a tag sheet similar to the one shown below.
<!-- Tag : --><SCRIPT LANGUAGE="JavaScript1.1" SRC="http://www5.smartadserver.com/call/adj/1234/1234/xxxx.xxxxxx/320x50/[timestamp]/no?[countgo]"></SCRIPT>
<NOSCRIPT><a href="http://www5.smartadserver.com/call/jumpi/1234/1234/xxxx.xxxxxx/320x50/[timestamp]/no?" target="_blank">
<img src="http://www5.smartadserver.com/call/adi/1234/1234/xxxx.xxxxxx/320x50/[timestamp]/no?" border="0"></a></NOSCRIPT>
To insert macros:
-
Insert
{clickMacroEnc}
where it says[countgo]
. -
Replace
[timestamp]
with{ts}
. -
Insert
{clickMacro}
before the URL in theA HREF
section.
Example of modified tag
<!-- Tag : -->
<SCRIPT LANGUAGE="JavaScript1.1" SRC="http://www5.smartadserver.com/call/adj/1234/1234/xxxx.xxxxxx/320x50/{ts}/no?{clickMacroEnc}"></SCRIPT>
<NOSCRIPT><a href="{clickMacro}http://www5.smartadserver.com/call/jumpi/1234/1234/xxxx.xxxxxx/320x50/{ts}/no?" target="_blank">
<img src="http://www5.smartadserver.com/call/adi/1234/1234/xxxx.xxxxxx/320x50/{ts}/no?" border="0"></a></NOSCRIPT>
Flashtalking is a rich media vendor.
To modify Flashtalking tags:
-
Add
{clickMacro}
before URL inA HREF
-
var ftClick = "";
→var ftClick = "{clickMacro}";
Below is an example of one of their tags and an example of the modified tag.
Example of Flashtalking tags
<noscript>
<a href="http://servedby.flashtalking.com/click/3/34022;123123;0;209;0/?ft_width=160&ft_height=600&url=5254895" target="_blank">
<img border="0" src="http://servedby.flashtalking.com/imp/3/34022;123123;205;gif;AcmeMedia;Acme160x600/?"></a>
</noscript>
<script language="Javascript1.1" type="text/javascript">
var ftClick = "";
var ftExpTrack_123123 = "";
var ftX = "";
var ftY = "";
var ftZ = "";
var ftOBA = 1;
var ftContent = "";
var ftCustom = "";
var ft160x600_OOBclickTrack = "";
var ftRandom = Math.random()*1000000;
var ftBuildTag1 = "<scr";
var ftBuildTag2 = "</";
var ftClick_123123 = ftClick;
if(typeof(ft_referrer)=="undefined"){var ft_referrer=(function(){var r="";if(window==top){r=window.location.href;}else{try{r=window.parent.location.href;}catch(e){}r=(r)?r:document.referrer;}while(encodeURIComponent(r).length>1500){r=r.substring(0,r.length-1);}return r;}());}
var ftDomain = (window==top)?"":(function(){var d=document.referrer,h=(d)?d.match("(?::q/q/)+([qw-]+(q.[qw-]+)+)(q/)?".replace(/q/g,decodeURIComponent("%"+"5C")))[1]:"";return (h&&h!=location.host)?"&ft_ifb=1&ft_domain="+encodeURIComponent(h):"";}());
var ftTag = ftBuildTag1 + 'ipt language="javascript1.1" type="text/javascript" ';
ftTag += 'src="http://servedby.flashtalking.com/imp/3/34022;123123;201;js;AcmeMedia;Moes160x600/?ftx='+ftX+'&fty='+ftY+'&ftadz='+ftZ+'&ftscw='+ftContent+'&ft_custom='+ftCustom+'&ftOBA='+ftOBA+ftDomain+'&ft_referrer='+encodeURIComponent(ft_referrer)+'&cachebuster='+ftRandom+'" id="ftscript_160x600" name="ftscript_160x600"';
ftTag += '>' + ftBuildTag2 + 'script>';
document.write(ftTag);
</script>
Example of Modified Ad Tag
<noscript>
<a href="{clickMacro}http://servedby.flashtalking.com/click/3/34022;123123;0;209;0/?ft_width=160&ft_height=600&url=5254895" target="_blank">
<img border="0" src="http://servedby.flashtalking.com/imp/3/34022;123123;205;gif;AcmeMedia;Acme160x600/?"></a>
</noscript>
<script language="Javascript1.1" type="text/javascript">
var ftClick = "{clickMacro}";
var ftExpTrack_123123 = "";
var ftX = "";
var ftY = "";
var ftZ = "";
var ftOBA = 1;
var ftContent = "";
var ftCustom = "";
var ft160x600_OOBclickTrack = "";
var ftRandom = Math.random()*1000000;
var ftBuildTag1 = "<scr";
var ftBuildTag2 = "</";
var ftClick_123123 = ftClick;
if(typeof(ft_referrer)=="undefined"){var ft_referrer=(function(){var r="";if(window==top){r=window.location.href;}else{try{r=window.parent.location.href;}catch(e){}r=(r)?r:document.referrer;}while(encodeURIComponent(r).length>1500){r=r.substring(0,r.length-1);}return r;}());}
var ftDomain = (window==top)?"":(function(){var d=document.referrer,h=(d)?d.match("(?::q/q/)+([qw-]+(q.[qw-]+)+)(q/)?".replace(/q/g,decodeURIComponent("%"+"5C")))[1]:"";return (h&&h!=location.host)?"&ft_ifb=1&ft_domain="+encodeURIComponent(h):"";}());
var ftTag = ftBuildTag1 + 'ipt language="javascript1.1" type="text/javascript" ';
ftTag += 'src="http://servedby.flashtalking.com/imp/3/34022;123123;201;js;AcmeMedia;Acme160x600/?ftx='+ftX+'&fty='+ftY+'&ftadz='+ftZ+'&ftscw='+ftContent+'&ft_custom='+ftCustom+'&ftOBA='+ftOBA+ftDomain+'&ft_referrer='+encodeURIComponent(ft_referrer)+'&cachebuster='+ftRandom+'" id="ftscript_160x600" name="ftscript_160x600"';
ftTag += '>' + ftBuildTag2 + 'script>';
document.write(ftTag);
</script>
Basis is certified by Innovid, and Innovid tags are compatible with Basis regardless of certification status.
Innovid does both display and video.
For display ad tags, you need to insert our {ts}
macro for cachebusting and our encoded click macro, which is: {clickMacroEnc}
.
For VAST, like all third-party VAST URLs, no macro insertion is required.
Example of Basis macro insertion
<IFRAME SRC="https://rtr.innovid.com/html/r1.12341234.1234?cb={ts}&ivc_click_through={clickMacroEnc}" WIDTH=300 HEIGHT=250 MARGINWIDTH=0 MARGINHEIGHT=0 HSPACE=0 VSPACE=0 FRAMEBORDER=0 SCROLLING=no BORDERCOLOR="#000000"></IFRAME>
Basis is certified for the following creative sizes:
-
Mobile 320x50 NE
-
IBV Desktop NE 300x250
-
IBV Desktop NE 300x600
-
Mobile 300x250
-
Tablet 300x250
-
Pre-roll VAST
-
Pre-roll VPAID
-
Mobile Interstitial
-
Tablet Interstitial
Be aware of following about count differences:
-
Tablet or mobile interstitial impressions: Netsertive counts impressions served whereas Basis typically counts impressions rendered. Given the difference in counting methodologies and impact of tablet and mobile serving environments, such as tag caching in app, expected impression discrepancy for interstitials can be up to 20-40% with Basis counts being lower than Netsertive.
-
Click discrepancy: Basis counts unique clicks per impression and filters out ad verification click data, whereas Netsertive counts every clickthrough on an ad. Given these differences and the impact of how various exchanges enable click tracking using different methods, there is an expected discrepancy with Netsertive clicks being higher than Basis-reported clicks.
If the tag has a double-encoded macro in the template ("%%CLICK_URL_ESC_ESC%%"
), try using just {clickMacro}
. Make sure to test before verifying.
Use auto macro insertion by selecting Insert macros when uploading ad tags.