Using merchenta.io for real-time bidding
Using merchenta.io for real-time bidding
There are a vast array of campaign options available. The common settings are explained in more detail below.
|code||Y||String||The campaign code.
Must be unique and consist only of letters, numbers and hyphens. Once created, the campaign code will not change - it may be used as a primary key for further operations. Campaign codes must be prefixed with an advertiser code followed by hyphen (“-“).
|advertiserDomain||N||String||This is the URL of the advertiser (useful if the advertiser is different than the api user’s organization, ie agencies). It needs to be a valid URL preceded with http:// or https:// .|
|status||N||String||This is a read-only field that indicates the status of the campaign:
ACTIVE: Approved to run. Running.
INACTIVE: Approved to run. Paused.
PENDING: Campaign is under review.
REJECTED: Campaign was not accepted.
|creatives[n]||Y||Object||The creative object.|
|creatives[n] / code||Y||String||The creative code.
Creative codes can be a maximum of 32 characters long and may only contain characters A to Z, a to z, 0 to 9 and hyphen (“-“). Creative codes must be prefixed with a campaign code followed by hyphen (“-“).
|creatives[n] / status||Y||String||An indicator of creative status.
It may be one of the following:
ACTIVE : Approved to run on one or more exchanges/publishers - reach may vary in accordance with publisher policies. Running.
INACTIVE : Approved to run on one or more exchanges/publishers - reach may vary in accordance with publisher policies. Paused.
PENDING : creative is under review.
REJECTED : creative was not accepted in accordance with creative standards or contains content prohibited by policy.
|creatives[n] / type||Y||String||This determines the type of creative.
It may be one of the following:
IMAGE : for static creative (eg JPEG/GIF/PNG)
FLASH : for Flash Player v8+ ads
FB_SIDEBAR : for Facebook sidebar ads
HTML-URL : for 3rd party hosted ad creative
HTML-SCRIPT : for Merchenta hosted HTML ad creative
INTELLIAD : for Merchenta Intelliads
All creative must comply with our supported ad formats.
|creatives[n] / creativeId||Y||String||(IMAGE, FLASH, FB_SIDEBAR, HTML-SCRIPT, VAST, VPAID)
The identifier for the creative previously uploaded.
URL of 3rd party hosted ad creative.
|creatives[n] / alternateCreativeId||N||String||The creative identifier for the alternate creative file.
This file will be used to render an ad in case the user’s browser does not support Flash and the primary creative is SWF/Flash. If no alternate creative is defined this field should not be set.
|creatives[n] / dimensions||Y||Object||Ad dimensions.
This should match the ad creative uploaded - for example “728x90” for an IAB standard leaderboard. All dimensions must comply with our supported ad formats.
|creatives[n] / dimensions / width||Y||Number||Ad dimensions - width|
|creatives[n] / dimensions / height||Y||Number||Ad dimensions - height|
|creatives[n] / dimensions / expansion||N||Object||Ad expansion settings|
|creatives[n] / dimensions / expansion / width||Y||Number||Expanded ad width.|
|creatives[n] / dimensions / expansion / height||Y||Number||Expanded ad height.|
|creatives[n] / dimensions / expansion / direction||Y||String||Expanding direction.
Allowed values are:
|creatives[n] / clickthroughUrl||Y||String||This is the URL (http or https) that the browser is redirected to when a consumer clicks an ad. For Flash-based creative, remember to ensure that a valid ClickTag handler is embedded within the ad creative. Clickthrough URLs must be at least 13 characters excluding transport prefix.|
|creatives[n] / postImpressionUrl||N||String||This is the URL (http or https) that will be fired when an ad is displayed to consumer. If this is not specified, delivering an ad results in no impression tracking.|
|creatives[n] / facebook||N||Object||Facebook creative metadata. Required only for FB_SIDEBAR type.|
|creatives[n] / facebook / title||N||String||Facebook ad title|
|creatives[n] / facebook / body||N||String||Facebook ad body|
|creatives[n] / intelliad||N||Object||IntelliAd creative metadata. Required only for INTELLIAD type.|
|creatives[n] / intelliad / xml||N||String||IntelliAd XML.|
|creatives[n] / webmCreativeId||N||String||Required for VAST and VPAID creatives|
|creatives[n] / videoDuration||N||String||Required for VAST and VPAID creatives in format “00:01:15”|
|creatives[n] / videoBitrate||N||String||Required for VAST and VPAID creatives in kbps|
|creatives[n] / vpaidJsLocation||N||String||Required for VPAID creatives|
|creatives[n] / vpaidJsParameters||N||String||Required for VPAID creatives|
|biddingSettings / biddingStrategy||Y||Object||One of bidding strategies|
|biddingSettings / pacingType||Y||String||Pacing determines how quickly the campaign impressions are delivered within the constraints of the campaign settings themselves.
There are two options:
ACCELERATED - bid on all available impressions
PROPORTIONAL - bid evenly throughout the day on available impressions in proportion to the impressions available at that moment in time.
|biddingSettings / maxBidsPerSecond||N||Number||Numeric value describing how many bids can be made in one second. Since Merchenta has such a vast array of available inventory, this can be useful for low budget (< $10 per day) campaigns to prevent over-bidding. The setting is optional, in which case the default platform value (5 bps) will be used.|
|biddingSettings / budget||Y||Object||The budget settings|
|biddingSettings / budget / daily||Y*||Number||The budget for the campaign on a daily basis. Either a daily budget or a lifetime budget must be given..
Do not set if you want to specify a lifetime budget instead.
|biddingSettings / budget / lifetime||Y*||Number||The total budget for the campaign across its flight dates. Either a daily budget or a lifetime budget must be given..
Do not set if you want to specify a daily budget instead.
For example, if you set a lifetime budget of $14k for a campaign with flight dates spanning 7 days, the platform will deliver budget evenly at the rate of (lifetime budget / number of days in flight) - in this case, $2k per day.
|biddingSettings / budget / currency||N||String||The budget currency. If not set defaults to USD. Currency codes follow the ISO standard - for example US Dollar is USD, Euro is EUR.|
|biddingSettings / frequencyCap||N||Number||Each campaign may have its own frequency cap (maximum number of impressions per consumer per 24 hour period). Merchenta operates universal frequency capping across all inventory sources. Where campaign-level settings are not provided (or are null), the advertiser level frequency cap associated with your account is used instead.|
|.. / biddingStrategy / strategy||Y||String||Strategy name.
Possible values are:
For details of additional bidding strategies that may apply to your account, please contact your Account Manager.
|.. / biddingStrategy / strategy||Y||String||CTROptimisingBiddingStrategy. This bidding algorithm uses advanced machine learning techniques to automatically optimise campaigns to inventory that delivers a higher clickthrough rate. It encompasses over 800 features to select the best performing inventory for a given campaign, focussed upon providing CTR lift.|
|.. / biddingStrategy / defaultBid||Y||Number||A based bid value that will be varied by bidding algorithm to hit the goal CTR.|
|.. / biddingStrategy / strategy||Y||String||CPCTargetBiddingStrategy|
|.. / biddingStrategy / goal||Y||Number||CPC goal expressed as a cost-per-click in campaign currency. For example, if campaign currency was USD and we sought a 60 cent cost-per-click-target, this would be set to “0.60”.|
|.. / biddingStrategy / strategy||Y||String||CPMCappedBiddingStrategy|
|.. / biddingStrategy / maxBid||Y||Number||Max CPM bid value expressed in campaign currency. This strategy will bid up to the CPM value specified but no higher. On a second price auction basis, generally the winning bid price is lower than this CPM so it can be seen as a CPM ceiling.|
|.. / biddingStrategy / strategy||Y||String||CPMVariableBiddingStrategy|
|.. / biddingStrategy / defaultBid||Y||Number||Default CPM bid value expressed in campaign currency (eg “2.0” for $2/cpm). This strategy will vary bids around the default bid specified by +/- 10%.|
|.. / biddingStrategy / strategy||Y||String||CPMFixedCPMBiddingStrategy|
|.. / biddingStrategy / goal||Y||Number||The target fixed CPM bid value expressed in campaign currency. Real-time media markets work on an auction basis, which makes it difficult to deliver a fixed-price CPM for campaigns, as the clearing CPM will move around considerably in response to bid density, win rates and other factors within the second price auction environment. This bidding strategy interacts with the auction dynamics to tune bidding automatically to deliver campaign impressions as close to the target fixed CPM as possible.|
|.. / biddingStrategy / strategy||Y||String||CPMFixedCPMPIDBiddingStrategy|
|.. / biddingStrategy / goal||Y||Number||The target fixed CPM bid value expressed in campaign currency. Real-time media markets work on an auction basis, which makes it difficult to deliver a fixed-price CPM for campaigns, as the clearing CPM will move around considerably in response to bid density, win rates and other factors within the second price auction environment. This bidding strategy uses a proportional, integrative and derivative function (hence the name “PID”) to dynamically adjust bids within the auction environment to target the fixed CPM specified. The approach is analagous to a heating thermostat where the temperature (in this case fixed CPM) is set and the device adjusts temperature around that value (in our case to deliver the fixed CPM target).|
|.. / biddingStrategy / strategy||Y||String||CPMZeroBiddingStrategy. This strategy is useful for testing purposes as it will consistently bid 0 price in campaign currency - no media will be bought.|
|.. / biddingStrategy / strategy||Y||String||CPMOneCentBiddingStrategy. This strategy is useful for testing purposes as it will consistently bid 0.01 (one cent) price in campaign currency - some media may be bought at these levels but on a second price auction basis winning bids are 1 cent lower than the highest bid so any cleared bids will be at 0 cost.|
|timeSettings / start||N||String||A datetime in YYYY-MM-DDThh:mm:ss format indicating the start date/time for the campaign. All platform times are in UTC (universal timezone).|
|timeSettings / end||N||String||A datetime in YYYY-MM-DDThh:mm:ss format indicating the end date/time for the campaign. All platform times are in UTC (universal timezone).|
|timeSettings / activeWindow||N||Array||Each campaign may have one or more windows of activity which govern the days and times of day when the campaign is active. This works in conjunction with the flights dates (start/end datetime). If not set the campaign is active 24 hours Monday to Sunday.|
|timeSettings / activeWindow[n]||Y||Object||Window object|
|timeSettings / activeWindow[n] / start||Y||String||Window start time in hh:mm format|
|timeSettings / activeWindow[n] / end||Y||String||Window end time in hh:mm format|
|timeSettings / activeWindow[n] / days||N||Array||Window active days array.
If not set window will be active Monday to Sunday
|timeSettings / activeWindow[n] / days[n]||N||String||Window active day.
Valid values are:
|targetingSettings / geoSettings||N||Object||Geo targeting options.
A vast array of geography related targeting options, including country, city/town, zipcode/postcode, latitude/longitude, DMA and place/radius targeting.
|targetingSettings / contextualSettings||N||Object||Contextual targeting.
Target publisher sites & content by contextual category.
|targetingSettings / thirdPartySegments||N||Array||DMP (3rd party) targeting.
Third-party data segments (eg demographic, behavioural data sourced from other websites) you wish to buy for use in the campaign.
|targetingSettings / retargetingSettings||N||Object||Retargeting.
A full range of retargeting options.
|targetingSettings / deviceTargetingSettings||N||Object||Device targeting.
For device targeting, including device family (tablet, desktop, mobile) plus browser, operating system and physical device.
|targetingSettings / mobileOperators||N||Array||Mobile operators targeting settings.|
|targetingSettings / ipWhitelists||N||Array||Ip whitelists targeting settings.|
|.. / geoSettings / countries||N||Array||Array of strings containing the 2 character ISO country codes where the campaign should run. For example, [“GB”,”FR”,”US”] would run the campaign in United Kingdom, France & USA.|
|.. / geoSettings / countries[n]||Y||String||2 character ISO country code|
|.. / geoSettings / coordinates||N||Array||Each campaign may have defined a set of geo coordinates along with radiuses (expressed in miles) to target inventory only from defined areas.|
|.. / geoSettings / coordinates[n]||N||Object||Geo-coordinates targeting object|
|.. / geoSettings / coordinates[n] / latitude||Y||Number||Latitude|
|.. / geoSettings / coordinates[n] / longitude||Y||Number||Longitude|
|.. / geoSettings / coordinates[n] / radius||Y||Number||Targeting radius in miles. Care should be taken to ensure that the radius is sufficiently large to capture a reasonable number of online consumers.|
|.. / geoSettings / cities||N||Array||Each campaign may have defined a set of towns/cities (and country codes) coordinates along with radiuses (expressed in miles) to target inventory only from defined areas in and around those conurbations.|
|.. / geoSettings / cities[n]||Y||Object||City targeting object.|
|.. / geoSettings / cities[n] / city||Y||String||City/town name.|
|.. / geoSettings / cities[n] / countryCode||Y||String||Since there are many towns/cities worldwide with the same name (eg Manchester, USA and Manchester,UK) the town or city should also be specified with the ISO country code. For instance, the UK country code is “GB”.|
|.. / geoSettings / cities[n] / radius||N||Number||Targeting radius in miles. Care should be taken to ensure that the radius is sufficiently large to capture a reasonable number of online consumers.|
|.. / geoSettings / states||N||Array||Array of USA state codes specifying the USA state codes for targeting for the campaign. Used only if countries contains “US”.|
|.. / geoSettings / states[n]||Y||String||USA state code|
|.. / geoSettings / zipCodes||N||Array||Array of USA zip codes specifying the USA zip codes for targeting for the campaign. Used only if countries contains “US”.|
|.. / geoSettings / zipCodes[n]||Y||String||USA zip code|
|.. / geoSettings / dmaCodes||N||Array||Array of DMA codes specifying the USA DMA codes for targeting for the campaign. Used only if countries contains “US”.|
|.. / geoSettings / dmaCodes[n]||Y||String||USA DMA code|
|.. / contextualSettings / iabCategories||N||Array||Contextual categories are defined as a series of identifiers (each of which maps to a category). Several categories may be specified.|
|.. / contextualSettings / iabCategories[n]||Y||Number||Contextual category ID|
|.. / thirdPartySegments[n]||Y||Object||Segments may be used to target online consumers using third party data sources. To use a segment, specify the segment type and the associated segment identifiers.|
|.. / thirdPartySegments[n] / segmentType||Y||String||Segment type. Presently, one segment type (third-party source) is supported - VISUALDNA.|
|.. / thirdPartySegments[n] / ids||Y||Array||The segment identifiers are the VisualDNA “internal” segment identifiers.|
|.. / thirdPartySegments[n] / ids[n]||Y||String||VisualDNA “internal” segment identifier.|
Before configuring a campaign to use first-party audience segments for retargeting, one or more segments must be deployed. When these segments are triggered, the consumer is placed in the corresponding audience segment. Once the segment is populated with a reasonable number of people (eg >1000 people), it’s possible to use the segment in a campaign for (re)targeting purposes.
There are several types of segment available and we provide a segmentling API to create & manage audience segments.
|.. / retargetingSettings / startAfterVisitsInHour||Y||Number||This setting determines the number of hours after a site visit that a consumer falls within a retargeting segment.|
|.. / retargetingSettings / lookBackWindowInDays||Y||Number||This setting determines which consumers fall within the retargeting segment by including those website visitors who have visited the website within NN days of now. This option is expressed in whole days. If set, the campaign will retarget users who visited the advertiser’s site previously. Note that before enabling this option you should check with your Account Manager the segmentling/tagging procedure and correct instructions prior to use.|
|.. / retargetingSettings / firstPartySegments||Y||String||This is the expression used for audience targeting - if an expression is set, Merchenta will use it for audience targeting/retargeting.|
Creating Custom Audience Targeting Rules
A wide range of expressions are supported using a BOOLEAN-type notation. These enable simple targeting strategies (eg “target people who have opened email X”) through to more sophisticated approaches (eg “target people who opened email X AND clicked on a link AND who viewed one or more products in past 7 days AND who have NOT purchased anything within 2 days”). Note : Segmnets expressions are case sensitive.
User belongs to segment “segment123” - the date the user joined the segment is irrelevant
User joined segment “segment123” within the past 7 days
segment123 AND segment456
User joined segment “segment123” within the past 7 days and they also joined segment “segment456” within the past 3 days
segment123 AND segment456 AND segment789 AND segment000
User joined three segments within the past 3 days - segment “segment123”, segment “segment456” and “segment1000”.
segment123 OR segment456
User joined segment “segment123” in the last 7 days or segment “segment456” in the last 3 days
User is not a member of segment “segment123”.
NOT segment123 AND (segment465 OR segment789)
User does not belong to segment “segment123” and joined segment “segment465” or “segment789” within the last 7 days
segment123 AND segment465 OR segment789
This is not valid expression, as it would confuse people - you have to use parentheses when combining AND and OR! The preferred format is to have one OR condition at the start of expression, then those segments which the user should have joined and finally, those segments which user isn’t a member of eg
(segment1 OR segment2) AND segment3 AND segment4 NOT segment5
|.. / deviceTargetingSettings / languages||N||Array||Language targeting can be performed with reference to the languages supported by the consumer’s browser. This is more effective that targeting the language of the page hosting the ad placement.|
|.. / deviceTargetingSettings / languages[n]||N||String||Language code in ISO 639-1 format.|
|.. / deviceTargetingSettings / devices||N||Array||Array specifying the types of device to run the campaign across.|
|.. / deviceTargetingSettings / devices[n]||N||String||Device type.
Valid values are :
|.. / deviceTargetingSettings / userAgentTargets||N||Array||It’s also possible to target devices at a more granular level - using operating system (OS), browser or device type targeting.|
|.. / deviceTargetingSettings / userAgentTargets[n]||N||Object||User agent target object.|
|.. / deviceTargetingSettings / userAgentTargets[n] / os||N||String||Operating system family name|
|.. / deviceTargetingSettings / userAgentTargets[n] / osMajorVersion||N||String||Operating system major version|
|.. / deviceTargetingSettings / userAgentTargets[n] / osMinorVersion||N||String||Operating system minor version|
|.. / deviceTargetingSettings / userAgentTargets[n] / device||N||String||Device family name|
|.. / deviceTargetingSettings / userAgentTargets[n] / userAgentFamily||N||String||Browser family name|
|.. / deviceTargetingSettings / userAgentTargets[n] / userAgentMajorVersion||N||String||Browser major version|
|.. / deviceTargetingSettings / userAgentTargets[n] / userAgentMinorVersion||N||String||Browser minor version|
|.. / mobileOperators[n]||Y||String||Mobile operator|
|.. / ipWhitelists[n]||Y||String||The item could be a single IP address (e.g. 127.132.43.30) or a range of IP addresses (e.g. 127.132.0.0-127.132.255.255).|
|inventorySettings / exchangeBlockList||N||Array||Array of exchange codes to be blocked. This allows selection of exchanges on a per campaign basis - setting the value to null will ensure that campaigns run across all exchanges subject to the other campaign criteria.
Exchange inventory availability can vary by region, so for the widest reach, set this value to null. If you encounter error messages relating to “sensitive content”, be sure to check that that you are blocking GD and BS exchanges. Alternatively, contact your Account Manager to arrange a review of your account to enable this restriction to be lifted.
Exchange codes are set as follows :
AD - Adscale
AM - Admeta
AN - AppNexus
BS - BidSwitch
CL - Casale Media
CT - Pulsepoint
AE - Aerserv Exchange
FB - Facebook Exchange (FBX)
GD - Google Doubleclick
IM - Improve Digital
NX - Nexage
OX - OpenX
RB - Rubicon Project
TS - TapSense
SM - Smaato
To enquire about additional exchanges available - please contact your Account Manager.
|inventorySettings / exchangeBlockList[n]||Y||String||Exchange code to be blocked.|
|inventorySettings / placementType||N||Array||Determines whether the campaign is run on placements above-the-fold (ATF), below-the-fold (BTF) or other placements (UNKNOWN). Settings can be combined, so to run above & below the fold select ATF and BTF.|
|inventorySettings / placementType[n]||Y||String||Placement type.
Valid values are :
ATF - bid on above-fold placements
BTF - bid on below-fold placements
UNKNOWN - bid on placements where fold positioning is unclear or where a unit spans ATF & BTF
|inventorySettings / inventoryType||Y||Array||Determines whether the campaign is run on all available media or only pre-bid known sites.|
|inventorySettings / inventoryType[n]||Y||String||Valid values are :
TRANSPARENT - bid on pre-bid identified sites
BLIND - bid on all media including transparent sites and sites where the site URL is unknown pre-bid
|inventorySettings / publisherWhiteList||N||Array||Array of site domains specifying the site list for the campaign. This can form the basis of a pre-targeting strategy.|
|inventorySettings / publisherWhiteList[n]||Y||String||Valid domain.|
|inventorySettings / trafficType||N||Array||Determines type of targeting traffic types. Currently, we support three type of traffic: Desktop web (WEB), mobile app (MOBILE_APP) and mobile web (MOBILE_WEB). Leaving this property empty if you want to target all traffic types.|
|inventorySettings / trafficType[n]||Y||String||Valid traffic type (WEB, MOBILE_WEB or MOBILE_APP).|
Settings to help auto-optimise campaigns.
|optimisationSettings / optimisationStrategy||Y||String||An optimisation strategy can be used to influence the selection of campaigns within a campaign group (ie which ad creative is selected out of many associated with a campaign). This is an advanced setting and should be used with care.
It will only take effect if the campaign has more than 1 ad creative. By default, the platform will use a ROUND_ROBIN approach, which allocates impressions more-or-less evenly to creatives in line with incoming, matching bid request placements.
The possible options are :
ROUND_ROBIN : the default
CTR : allocate greater weight to creatives with the highest clickthrough rate
ETR : allocate greater weight to creatives with the highest engagement rate (note : IntelliAds only)
WIN_RATE : allocate greater weight to creatives with the highest win rate
CPM : allocate greater weight to creatives with the highest eCPM
If you specify and optimisationStrategy, you must also set the commenceOptimisationAfter setting.
|optimisationSettings / commenceOptimisationAfter||Y||Number||This setting determines the trigger point for the optimisationStrategy. To prevent premature optimisation, specify the number of impressions that must be served by the campaign before the optimisationStrategy kicks in.
If you specify an commenceOptimisationAfter, you must also set the optimisationStrategy setting.
|productSettings / recommendationStrategy||Y||String||Products recommendation strategy. This must be set if creative type is INTELLIAD.
Valid values are:
Copyright 2015 Merchenta