Mocean Mobile Macros Documentation

From Mocean Mobile Wiki

(Redirected from Macro Documentation)
Jump to: navigation, search

Contents

Overview

Mocean Mobile platform allows for MACROs (placeholders) to replace a certain text wherever it appears in your ad code or requests. After being processed by the ad server, all the MACROs used will be replaced with the corresponding values (see tables below).

All Mocean Mobile MACROs can be divided into next groups: Click URL Placeholders, Rich Media Placeholders, Video Placeholders and Tag Based Network Placeholders.

* Mocean Mobile MACROs use the PII compliant IP address with removed last octet.

Click URL Placeholders

While making settings for a creative, users are allowed to specify external Click-Thru URL. For the link address the following placeholders are supported in the Mocean Mobile platform.

Placeholder Description
%DID% Replaced with domain (site) ID where the ad is served.
%SITEURL% Replaced with domain URL of the site where the ad is served.
%ADVID% Replaced with an advertiser ID.
%ADVNAME% Replaced with an advertiser name.
%CPID% Replaced with a unique ID of the ad (creative ID).
%LPID% Replaced with the line item ID.
%OPID% Replaced with an order ID.
%SID% Show ID passed through the landing page.
%UID% * Unique ID parameter. If there is no network preference setting about device ids, then MD5 hashed value of the UDID parameter, or the SHA1-hashing of UA and IP is used. If you opted out from collecting information via cookies about your Internet visits, the macro is replaced with the automatically regenerated unique user ID.
%RANDOM% Replaced with a random number.
%TIMESTAMP% Replaced with the Unix timestamp.
%REFURL% Encoded URL of a website the ad is requested from. It is replaced with value of the “url” parameter passed in the ad request.
%PHONE_BRAND% Replaced with the corresponding phone brand name from WURFL.
%PHONE_MODEL% Replaced with the corresponding phone model name from WURFL.


Click URL Placeholders Usage

If Click URL placeholders are specified in ad requests, they will be populated with the appropriate values and users will be successfully redirected to the creative landing page.

Just specify the required macros in your click-thru URL address as it is shown below:

http://test.domain.com/?sid=%SID%&cid=%CPID%&lpid=%LPID%&did=%DID%

After backend processing, your click URL will look like this:

http://test.domain.com/?sid=a73cc290-20fc-11e1-ac3b-0019b9f99000&cid=13243&lpid=7856&did=4596

Parameters %CPID%, %LPID%, %SID% and %DID%, being added to Click-Tru URL, can be used for tracking multiple conversion (see User Defined Conversion Code).


Rich Media Placeholders

When you create a rich media ad, you can also use MACROs designed for rich media ads. All MACROs supported for rich media ads are listed in the table below.

Placeholders Description
%LINK% Replaced with a link (wrap URL) for tracking the click back to the destination URL.
%ELINK% Replaced with an encoded link for tracking the click back to the destination URL.
%ASSETURL1% Replaced with an asset url for using the uploaded image on the ad request.
%WIDTH% Replaced with MMA max image width based on the size parameter sent in ad request, zone settings or UA passed in the ad call.
%HEIGHT% Replaced with MMA max image height based on the size parameter sent in ad request, zone settings or UA passed in the ad call.
%DEVICEWIDTH% Replaced with the device screen width.
%DEVICEHEIGHT% Replaced with the device screen height.
%TRACKURL% Replaced with the pixel tracking URL.
NOTE: When using the %TRACKURL% macro, make sure either the "Custom Impression Pixel URL" field is filled in or the "Enable Pixel Tracking" option is enabled for the related line item. Also, %TRACKURL% and %IMPTRACKURLS% should not be used together.
%TRACKPIXEL% Replaced with the 1x1 image pixel tracker.
NOTE: When using the %TRACKPIXEL% macro, make sure either the "Custom Impression Pixel URL" field is filled in or the "Enable Pixel Tracking" option is enabled for the related line item. Also, %TRACKPIXEL% and %IMPTRACKPIXELS% should not be used together.
%IMPTRACKURLS% Replaced with urls of tracking pixels separated by '#'.
NOTE: Tracking pixels are sorted by id (ascendent).
NOTE: When using the %IMPTRACKURLS% macro, make sure either the "Tracking Pixels" field is filled in or the "Enable Pixel Tracking" option is enabled for the related line item. Also, %TRACKURL% and %IMPTRACKURLS% should not be used together.
%IMPTRACKPIXELS% Replaced with the 1x1 image for each tracking pixel.
NOTE: Tracking pixels are sorted by id (ascendent).
NOTE: When using the %IMPTRACKPIXELS% macro, make sure either the "Tracking Pixels" field is filled in or the "Enable Pixel Tracking" option is enabled for the related line item. Also, %TRACKPIXEL% and %IMPTRACKPIXELS% should not be used together.


Rich Media Placeholders Usage

One of the ways of using rich media MACROs is to specify them in the ad code. Here is an example of a rich media ad code with replaceable parameters:

Using Rich Media Placeholder

The full ad code content is below.

<div class="celtra-ad-v2"> <script> (function() { var c = "celtra.com"; var sticky = ""; var scripts = document.getElementsByTagName("script"); var me = scripts[scripts.length-1]; var req = document.createElement("script"); req.id = "celtra-"+(Math.random()+"").slice(2); req.src = "http://api.celtra.com/v1/creatives/6290/compiled/ExpandableBanner/banner.js?channel=test&c="+encodeURIComponent(c)+"&scriptId="+req.id+"&sticky="+sticky; me.parentNode.insertBefore(req, me.nextSibling); })(); </script> </div>

Finally, the code of the ad after replacing MACROs with the corresponding values will be as follows:

<div class="celtra-ad-v2"> <script> (function() { var c = "%LINK%"; var sticky = ""; var scripts = document.getElementsByTagName("script"); var me = scripts[scripts.length-1]; var req = document.createElement("script"); req.id = "celtra-"+(Math.random()+"").slice(2); req.src = "http://api.celtra.com/v1/creatives/6290/compiled/ExpandableBanner/banner.js?channel=test&c="+encodeURIComponent(c)+"&scriptId="+req.id+"&sticky="+sticky; me.parentNode.insertBefore(req, me.nextSibling); })(); </script> </div>


Size MACROs

If you would like to use size placeholders in your rich media ad, you may add them to the related ad tag:

<a href="hello.html">%DEVICEWIDTH% %DEVICEHEIGHT%, %WIDTH% %HEIGHT%</a>

As a result, you will get the following ad:

<a href="hello.html">800 600, 320 50</a>


Custom Redirection

If you would like to have more than one click URL with different destinations in your ad, additionally to the %LINK% MACRO use the redir GET parameter (%LINK%?redir=...). In this case, the backend will just count the click (regardless of what the click url textbox) and redirect you to whatever is in redir.

NOTE: URL specified in redir must be encoded.

Example,

<a href="%LINK%?redir=http%3A%2F%2Fdomain1.com%2Flink1">Click Link 1</a>
<a href="%LINK%?redir=http%3A%2F%2Fdomain2.com%2Flink2">Click Link 2</a>


Placeholders Common To Rich Media And Click URL

Placeholder Description
%IP% * Replaced with ip detected by a carrier gateway which the user device is connecting over (either passed directly in the ad call).
%USERAGENT% Replaced with user agent of the mobile device (either passed in the ad call as the ‘ua’ parameter).
%COUNTRYCODE% Replaced with a country code extracted from ad call or auto detected by IP.
%REGIONCODE% Replaced with a region code (a state code in case of US) or auto detected by IP.
%LATITUDE% ** Replaced with the latitude value of the user device (either passed in the call or auto detected by IP).
%LONGITUDE% ** Replaced with the longitude value of the user device (either passed in the call or auto detected by IP).
%LOCSOURCE% Replaced with an integer value reflecting the source the user location is defined by:
  • “1” - latitude/longitude are obtained from the ad request,
  • “2” - user location is defined by IP.
%ZIP% Replaced with zip code as entered in the ad call.
%DMA% Replaced with dma (metro) code as entered in the ad call using ‘dma’ parameter.
%VAR_param% Replaced with the custom parameter (‘param’) value passed in the ad request. NOTE: You may use any number of custom parameters and name them as you wish.
If you opted out from collecting information via cookies about your Internet visits, the macro is sent only if the custom parameter value does not contain Device ID.


MACROS in Rich Media Tags

If you would like to use the listed placeholders in your rich media ad, you may simply add the desired MACROs into the corresponding ad text.

For example,

<a href="%LINK%">Test code macro %COUNTRYCODE%, %REGIONCODE%, %LATITUDE%, %LONGITUDE%, %ZIP%, %DMA%, %VAR_p1%, %VAR_p2%, %IP%, %USERAGENT%</a>

Suppose the following ad request comes in:

http://ads.moceanads.com/ad?zip=10013&dma=702&p1=123&p2=abc

As a result, your ad text will be as follows:

Test code macro RU, 75, 56.5, 84.966705, 10013, 702, 123, abc, 91.221.60.18, Mozilla%2F5.0+%28Linux%3B+U%3B+U%3B+Android+2.3.4%3B+ru-ru%3B+SonyEricssonMT15i+Build%2F4.0.2.A.0.42%29+AppleWebKit%28KHTML%2C+like+Gecko%29+Version%2f4.0+Mobile+Safari%2F533.1


MACROS in Click URL

Placeholders listed in the table above can be also used in click URLs. You may add them to the ad call using the appropriate ad request parameters.
To obtain the list of available request parameters, see Mocean Ad Request API.

http://www.example.com/?ip=%IP%&ua=%USERAGENT%&country=%COUNTRYCODE%&region=%REGIONCODE%&lat=%LATITUDE%&long=%LONGITUDE%&zip=%ZIP%&dma=%DMA%&param=%VAR_param%


Video Placeholders

When you create a video ad, use the following MACROs allowed for video ads.

NOTE: Video MACROs are the same for VAST 2.0 and VAST 3.0.
Placeholders Description
%TRACKURL% Replaced with a non-wrapped impression tracking URL.
%CLICKTRACKURL% Replaced with a non-wrapped URL for tracking the click.
%VASTERROR% Replaced with a URI for tracking errors occurred while video ad serving.
%VASTEVENT% Replaced with a URI for tracking video events.
NOTE: The %VASTEVENT% macro should be followed by the event metric you would like to track, e.g., %VASTEVENT%event=start.
The full list of tracking events you can find here.
For more details, please refer to Video Ads.
NOTE: Video players supporting VAST 3.0 ads also allow advertisers to use additional placeholders. To learn more, please refer to the IAB VAST 3.0 documentation.


Video Placeholders Usage

When creating a video ad, specify video MACROs in the VAST tag.

  • %TRACKURL% should be added into the <Impression> element
  • %CLICKTRACKURL% - into the <ClickTracking> element
  • %VASTEVENT% - into <Tracking>
  • %VASTERROR% - into <Error>


InLine Linear Ads
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<VAST xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" version="3.0" xsi:noNamespaceSchemaLocation="vast3_draft.xsd">
    <Ad id="602680" sequence="1">
        <InLine>
            <!-- Other elements -->
            <Error>%VASTERROR%</Error>
            <Impression>%TRACKURL%</Impression>
            <Creatives>
                <Creative sequence="1" AdID="2135373">
                    <Linear skipoffset="00:00:03">
                        <TrackingEvents>
                            <Tracking event="start">%VASTEVENT%event=start</Tracking>
                            <Tracking event="firstQuartile">%VASTEVENT%event=firstQuartile</Tracking>
                        <TrackingEvents>
                        <!-- Other elements -->
                        <VideoClicks>
                            <!-- Other elements -->
                            <ClickTracking id="Alex">%CLICKTRACKURL%</ClickTracking>
                        </VideoClicks>
                        <!-- Other elements -->
                    </Linear>
                </Creative>
                <!-- Other creatives -->
            </Creatives>
            <!-- Other elements -->
	</InLine>
    </Ad>
    <!-- Other ads -->
</VAST>


Wrapper Linear Ads
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<VAST xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" version="3.0" xsi:noNamespaceSchemaLocation="vast3_draft.xsd">
    <Ad id="602681" sequence="5">
        <Wrapper>
            <!-- Other elements -->
            <Error>%VASTERROR%</Error>
            <Impression>%TRACKURL%</Impression>
            <Creatives>
                <Creative sequence="1" AdID="">
                    <Linear skipoffset="00:00:03">
                        <TrackingEvents>
                            <Tracking event="start">%VASTEVENT%event=start</Tracking>
                            <Tracking event="firstQuartile">%VASTEVENT%event=firstQuartile</Tracking>
                        <TrackingEvents>
                        <!-- Other elements -->
                        <VideoClicks>
                            <!-- Other elements -->
                            <ClickTracking id="Alex">%CLICKTRACKURL%</ClickTracking>
                        </VideoClicks>
                        <!-- Other elements -->
                    </Linear>
                </Creative>
                <!-- Other creatives -->
            </Creatives>
            <!-- Other elements -->
	</Wrapper>
    </Ad>
    <!-- Other ads -->
</VAST>


NOTE: Video macros are optional. You may save a video creative without these macros, but you won't be able to get any reporting data for the ad through the Mocean system in this case.

Audio Placeholders

When you create an audio ad, use the following MACROs allowed for audio ads.

Placeholders Description
%TRACKURL% Replaced with a non-wrapped impression tracking URL.
%CLICKTRACKURL% Replaced with a non-wrapped URL for tracking the click.
NOTE: Audio players supporting DAAST 1.0 ads also allow advertisers to use additional placeholders. To learn more, please refer to the IAB DAAST 1.0 documentation.


Audio Placeholders Usage

When creating an audio ad, specify audio MACROs in the DAAST tag.

  • %TRACKURL% should be added into the "Impression" element
  • %CLICKTRACKURL% - into the "CompanionClickTracking" element


InLine Ads

<?xml version="1.0" encoding="UTF-8"?>
<DAAST version="1.0">
    <Ad id="229">
        <InLine>
            <!-- other elements -->
            <Impression><![CDATA[%TRACKURL%]]></Impression>
            <Creatives>
                <Creative sequence="1" AdID="2135373">
                    <CompanionAds>
                        <Companion width="300" height="60">
                            <!-- other elements -->
                            <CompanionClickTracking><![CDATA[%CLICKTRACKURL%]]></CompanionClickTracking>
                            <!-- other elements -->
                        </Companion>
                    </CompanionAds>
                </Creative>
                <!-- Other creatives --> 
            </Creatives>
            <!-- other elements -->
        </InLine>
    </Ad>
    <!-- Other ads -->
</DAAST>


Wrapper Ads

<?xml version="1.0" encoding="UTF-8"?>
<DAAST version="1.0">
    <Ad id="229">
        <Wrapper>
            <!-- other elements -->
            <Impression><![CDATA[%TRACKURL%]]></Impression>
            <Creatives>
                <Creative sequence="1" AdID="2135373">
                    <CompanionAds>
                        <Companion width="300" height="60">
                            <!-- other elements -->
                            <CompanionClickTracking><![CDATA[%CLICKTRACKURL%]]></CompanionClickTracking>
                            <!-- other elements -->
                        </Companion>
                    </CompanionAds>
                </Creative>
                <!-- Other creatives --> 
            </Creatives>
            <!-- other elements -->
        </Wrapper>
    </Ad>
    <!-- Other ads -->
</DAAST>

NOTE: You may save an audio creative without these MACROs, but impressions and clicks won't be reflected in the statistics data.

Tag Based Network Placeholders

When you create an ad for the Tag Based Network, you can use the following MACROs in the script tag.

Placeholders Description
%WIDTH% Replaced with MMA max image width based on the size parameter sent in ad request, zone settings or UA passed in the ad call.
%HEIGHT% Replaced with MMA max image height based on the size parameter sent in ad request, zone settings or UA passed in the ad call.
%DEVICEWIDTH% Replaced with the device screen width.
%DEVICEHEIGHT% Replaced with the device screen height.
%TRACKURL% Replaced with a wrapped impression tracking URL.
NOTE: When using the %TRACKURL% macro, make sure the "Enable Pixel Tracking" option is enabled for the related line item.
%CLICKTRACKURL% Replaced with a wrapped URL for tracking the click.
%ECLICKTRACKURL% Replaced with an encoded URL for tracking the click.
%TRACKPIXEL% Replaced with the 1x1 image pixel tracker.
NOTE: When using the %TRACKPIXEL% macro, make sure the "Enable Pixel Tracking" option is enabled for the related line item.
%IP% * Replaced with ip detected by a carrier gateway which the user device is connecting over (either passed directly in the ad call).
%USERAGENT% Replaced with user agent of the mobile device (either passed in the ad call as the ‘ua’ parameter).
%COUNTRYCODE% Replaced with a country code extracted from ad call or auto detected by IP.
%REGIONCODE% Replaced with a region code (a state code in case of US) or auto detected by IP.
%LATITUDE% ** Replaced with the latitude value of the user device (either passed in the call or auto detected by IP).
%LONGITUDE% ** Replaced with the longitude value of the user device (either passed in the call or auto detected by IP).
%LOCSOURCE% Replaced with an integer value reflecting the source the user location is defined by:
  • “1” - latitude/longitude are obtained from the ad request,
  • “2” - user location is defined by IP.
%ZIP% Replaced with zip code as entered in the ad call.
%DMA% Replaced with dma (metro) code as entered in the ad call using ‘dma’ parameter.
%VAR_param% Replaced with the custom parameter (‘param’) value passed in the ad request. NOTE: You may use any number of custom parameters and name them as you wish.
If you opted out from collecting information via cookies about your Internet visits, the macro is sent only if the custom parameter value does not contain Device ID.


To get more information about Tag Based Network ads, please refer to Ad Feed Settings.

Comprehensive MACROs List

The table bellow shows where every MACRO can be used.

MACRO Click URL Rich Media Video Tag Based Network Audio
 %DID% +
 %SITEURL% +
 %ADVID% +
 %ADVNAME% +
 %CPID% +
 %LPID% +
 %OPID% +
 %SID% +
 %UID% +
 %RANDOM% +
 %TIMESTAMP% +
 %REFURL% +
 %PHONE_BRAND% +
 %PHONE_MODEL% +
 %LINK% +
 %ELINK% +
 %ASSETURL1% +
 %WIDTH% + +
 %HEIGHT% + +
 %DEVICEWIDTH% + +
 %DEVICEHEIGHT% + +
 %TRACKURL% + + + +
 %TRACKPIXEL% + +
 %IMPTRACKURLS% +
 %IMPTRACKPIXELS% +
 %IP% + + +
 %USERAGENT% + + +
 %COUNTRYCODE% + + +
 %REGIONCODE% + + +
 %LATITUDE% + + +
 %LONGITUDE% + + +
 %LOCSOURCE% + + +
 %ZIP% + + +
 %DMA% + + +
 %VAR_param% + + +
 %CLICKTRACKURL% + + +
 %ECLICKTRACKURL% +
 %VASTERROR% +
 %VASTEVENT% +
Personal tools