Campaign Feed Product Manual Please note that your account manager would be happy to explain you how the campaign feed works. Please do not hesitate to contact your dedicated account manager. © Cheetah Media Link 2015 – All rights reserved help@cmcm.com Revision History Version 1.0 Date 19/09/2012 Owner/Contributer Comments Cheetah Media Link Technical Team First release Cheetah Media Link Technical Team Creatives packs replace promotions, add target’s payouts to feed, list campaigns categories, list campaigns platforms 1.1 31/10/2012 1.2 30/03/2013 Cheetah Media Link Technical Team Campaign type added 1.3 11/08/2015 Cheetah Media Link Technical Team Capping added 1.4 04/12/2015 Cheetah Media Link Technical Team Campaign GEO areas and capping config added © Cheetah Media Link 2015 – All rights reserved help@cmcm.com Content Revision History ...................................................................................................... 2 1 2 3 Introduction ....................................................................................................... 4 1.1 What is Cheetah Media Link Campaign Feed ............................................................. 4 1.2 Prerequisite .................................................................................................................. 4 How to request our Campaign Feed................................................................. 5 2.1 Campaign feed request url ........................................................................................... 5 2.2 Output parameter ......................................................................................................... 6 2.3 Optional info ................................................................................................................. 6 2.4 Filter ............................................................................................................................. 7 2.5 Examples...................................................................................................................... 8 Structure of the Campaign Feed response ...................................................... 8 3.1 Service ......................................................................................................................... 8 3.2 Campaign ..................................................................................................................... 8 3.3 Category ....................................................................................................................... 9 3.4 Platform ...................................................................................................................... 10 3.5 Screenshot ..................................................................................................................11 3.6 Capping (campaign level) ...........................................................................................11 3.7 Action ..........................................................................................................................11 3.8 Application .................................................................................................................. 12 3.9 Language ................................................................................................................... 13 3.10 Capping (action level) .............................................................................................. 13 3.11 Target ....................................................................................................................... 14 3.12 Payout ...................................................................................................................... 15 3.13 Creative Pack ........................................................................................................... 15 3.14 Creative .................................................................................................................... 16 3.15 Exclude ..................................................................................................................... 16 3.16 Global view of the campaign feed response ............................................................ 17 © Cheetah Media Link 2015 – All rights reserved help@cmcm.com 1 Introduction 1.1 What is Cheetah Media Link Campaign Feed If you want to promote our campaigns on your platform, you can use our feed to easily retrieve the data of the campaigns you’re subscribed to. The campaign feed is updated automatically and will only provide the available campaign in your traffic source or in a specific pool. The campaign feed has to be used in a Server-to-server connection: your server calls our feed to retrieve and store the campaigns info. Your clients can then use the campaign info from your server. The feed is updated once every hour, so you should not call it more often than every 60 minutes. Due to that limitation, you should not use our campaign feed directly from your client, as it would result in excessive and inefficient calls to our servers. You can get more accurate information on the campaigns thanks to the parameters available and filter the content thanks to our filter parameter. You can access our generator page at: http://dashboard.cheetahmedialink.com/en/admin/campaign/feed/generator 1.2 Prerequisite The first thing you need to do, as a Cheetah Media Link affiliate, is to get a valid TRAFFIC SOURCE id or POOL id from the Cheetah Media Link dashboard. It will be required for every request you will send using the Cheetah Media Link Campaign Feed. A TRAFFIC SOURCE is a general term to describe your app or site. In other words, you need to create a traffic source for each application, mobile site or adnetwork where you have traffic. A POOL is basically a collection of campaigns you wish to promote on your mobile site and/or application. To create one, go to the Cheetah Media Link Publisher backoffice, go to Traffic sources tab and then click on Create a new Pool. © Cheetah Media Link 2015 – All rights reserved help@cmcm.com Detailed steps to create a traffic source and a pool please refer to following FAQ articles: What is a traffic source? How can I declare/add a traffic source? http://support.cheetahmedialink.com//hc/en-us/articles/202500791-What-is-a-traffic-sour ce-How-can-I-declare-add-a-traffic-source- What is a pool? When should I use pools? http://support.cheetahmedialink.com/hc/en-us/articles/202500811-What-is-a-pool-Whenshould-I-use-pools- You’ll have to choose a name and configure your POOL before filling it with campaigns. Your POOL id or TRAFFIC SOURCE id is the number just after the # next to the POOL or TRAFFIC SOURCE name. Should you need any help selecting campaigns or configuring the TRAFFIC SOURCE or POOL to match your needs, please feel free to contact your dedicated account manager and/or Cheetah Media Link technical support. 2 How to request our Campaign Feed 2.1 Campaign feed request url 2.1.1 Key parameter In order to use our Campaigns Feed, you must first retrieve your key from your Cheetah Media Link Dashboard. Without the key, it is impossible to access the campaign feed. You’ll find yours on this page, when logged in: http://dashboard.cheetahmedialink.com/en/admin/campaign/feed/generator This key is the same for all your services or your pools created on your Cheetah Media Link account. 2.1.2 Campaign Feed URL To use our Campaign Feed, you have to call one of those two URLs, depending on whether you want to get the data of a complete TRAFFIC SOURCE or of a specific POOL: TRAFFIC SOURCE http://dashboard.cheetahmedialink.com/en/admin/service/[YOUR_TRAFFIC_SOURCE_ ID]/feed?key=[YOUR_KEY] POOL http://dashboard.cheetahmedialink.com/en/admin/service/pool/[YOUR_POOL_ID]/feed? key=[YOUR_KEY] © Cheetah Media Link 2015 – All rights reserved help@cmcm.com 2.1.3 Examples Here are two examples of campaign feel request url. In the sample urls, “1234” is the sample traffic source ID, and “123456” is the sample pool ID. The sample key value is the same in two urls: TRAFFIC SOURCE http://www.cheetahmedialink.com/en/admin/service/1234/feed?key=1225f834d7f0436ca e829cf3c998b5qa POOL http://www.cheetahmedialink.com/en/admin/service/pool/123456/feed?key=1225f834d7f 0436cae829cf3c998b5qa 2.2 Output parameter The campaign feed can produce either an XML or a JSON result. To choose between those two types of data, just add the parameter &output= with the value xml or json in campaign feed request url. Xml is the default value. Available values Description xml (Default) You will get a XML format data json You will get a JSON format data Examples: To get XML result: http://www.cheetahmedialink.com/en/admin/service/1234/feed?key=1225f834d7f0436ca e829cf3c998b5qa&output=xml To get JSON result: http://www.cheetahmedialink.com/en/admin/service/1234/feed?key=1225f834d7f0436ca e829cf3c998b5qa&output=json 2.3 Optional info To get more accurate information in the campaign feed response, you can use the following parameters. Every one of those parameters accepts the value 0 or 1. 0 is the default value, 1 activates the option and displays the requested data. Parameter Description displayCategory Display the ID of the categories of the campaigns. displayPlatform Display the ID of the platforms of the campaigns. displayScreenshot Display the screenshots of the campaign. © Cheetah Media Link 2015 – All rights reserved help@cmcm.com displayAction Display the different actions of the campaign. Please refer to the campaign description to know more about each action. displayApplication If the campaign is CPI, this will display information about the application promoted by the campaign. displayTarget Display the different targets of the campaign for you to know what traffic is allowed by the campaign. displayExclude Display information about what traffic is not allowed by the campaign. displayPayout Display payout information at campaign target level. displayCreativesPack Display creative packs information. displayCreative Display detailed information about each creative of each creative pack. displayIncent Display if incent traffic is allowed or not. 0: not allowed; 1: allowed. displayCapping Display if cap is reached or not. 0: cap not reached; 1: cap reached. displayCappingConfig Display cap configurations on campaign or campaign action level. By default campaign level cap configuration is displayed. To display action level cap configuration, displayAction parameter should be used. Some attribute information (e.g. categories, OS, OS version, and carrier information) is displayed as ID. To get the name corresponding to the IDs, please refer to following FAQ article: http://support.cheetahmedialink.com/hc/en-us/articles/204812261-Attribute-IDs-in-campaign-f eed-response-and-corresponding-names 2.4 Filter To filter the content in the campaign feed response, you can use the following filter parameters. Every one of those parameters accepts specific values, as shown below: Parameter filterCountry filterApplicationLan guage filterPayoutType Description Values Display only the campaign open for a specific list of countries. The ISO 3166-1-alpha-2 code is used. You can put one value, or several separated by a hyphen. You can get the full country list here. Examples: FR FR-ES Display only the description of the application for a specific language. The ISO 639-1 code is used. You can put one value, or several separated by a hyphen. You can get the full country list here. Examples: FR FR-ES Display only the targets with specific payout type. 1 (only Fix payouts) 2 (only Percent from Cheetah Media Link part payouts) 3 (only Percent from Advertiser part payouts) © Cheetah Media Link 2015 – All rights reserved help@cmcm.com filterCreativeType Display only the targets with specific creative type. 1 (only text creative) 2 (only image creative) By default, all filter parameters have an empty value. 2.5 Examples Displays the campaigns of the pool open for the USA, with their actions, targets, and payouts: http://dashboard.cheetahmedialink.com/en/admin/service/pool/4192/feed?key=1235183 7d780236c9e829c93c99ab5ea&filterCountry=US&displayPayout=1 Displays the campaign of the pool with the information in French of the application if the campaign is CPI: http://dashboard.cheetahmedialink.com/en/admin/service/pool/4192/feed?key=1235183 7d780236c9e829c93c99ab5ea&filterApplicationLanguage=FR&displayApplication=1 Displays the campaigns of the pool with their categories, their targets and excluded targets: http://dashboard.cheetahmedialink.com/en/admin/service/pool/4192/feed?key=1235183 7d780236c9e829c93c99ab5ea&displayTarget=1&displayExclude=1&displayCategory=1 3 Structure of the Campaign Feed response 3.1 Service root > service Service represents your mobile site, mobile application… Attribute Name Description Values Can be empty? ID Your service ID Integer No Name Your service name String No 3.2 Campaign root > service > campaigns > campaign Your Service or Pool can be linked to several campaigns, so “campaign” elements are contained in a “campaigns” element. A campaign is a product to promote, like a game or a group of applications. © Cheetah Media Link 2015 – All rights reserved help@cmcm.com Attribute Name Description Values Can be empty? id The campaign identifier Integer No name The campaign name String No click The campaign click url (Redirect to random url among matching children target) Url No banner The campaign banner url (Redirect to random banner url from random matching children target) (Auto detect device width) Url No text The campaign text creative (Fixed to “Click here” for now) String No incentAllo wed Display if incent traffic is allowed or not (This attribute is displayed when parameter “&displayIncent=1” is added in the campaign feed request url) 0 (not allowed) 1 (allowed) No cappingRe ached Display if cap is reached or not (This attribute is displayed when parameter “&displayCapping=1” is added in the campaign feed request url) 0 (not reached) 1 (reached) No 3.3 Category root > service > campaigns > campaign > categories > category A campaign can be linked to several categories, so “category” elements are contained in a “categories” element. Categories allow us to target public for campaigns with value like Entertainment, Banking, Adult, Sport … This part is displayed when parameter “&displayCategory=1” is added in the campaign feed request url. Attribute Name Description Values Can be empty? id The campaign category identifier Get full list here. 1 (Mobile Content) 2 (Social Networks) 3 (Applications) 4 (Entertainment) 5 (Banking, Financial) 6 (Casino, Gambling) 7 (Adult) 8 (iPhone Applications) 9 (Fashion) 10 (Education) No © Cheetah Media Link 2015 – All rights reserved help@cmcm.com 11 (M-Commerce) 12 (Coupon) 13 (Insurance) 14 (Healthcare) 15 (Sport) 16 (Auto) 17 (Food, Beverage) 18 (Media) 19 (Telecom) 20 (Services) 21 (B2B) 22 (Games) 23 (Sexy) 26 (Musics) 27 (Ringtones) 28 (Hightech) 29 (Video) 30 (Software) 31 (Travel) 32 (Dating) 33 (Astrology) 3.4 Platform root > service > campaigns > campaign > platforms > platform A campaign can be linked to several platforms, so “platform” elements are contained in a “platforms” element. Platforms allow us to target device for campaigns with value like iPhone App, Android App, JAVA, WAP … This part is displayed when parameter “&displayPlatform=1” is added in the campaign feed request url. Attribute Name Description Values Can be empty? id The campaign platform identifier Get full list here. 1 (WAP) 2 (JAVA) 4 (iPhone) 5 (iPad) 6 (Android) 7 (BlackBerry) 8 (Windows Phone) 9 (Bada) No © Cheetah Media Link 2015 – All rights reserved help@cmcm.com 3.5 Screenshot root > service > campaigns > campaign > screenshots > screenshot A campaign can have several screenshots, so “screenshot” elements are contained in a “screenshots” element. Screenshots are pictures that represent the advertised application. This part is displayed when parameter “&displayScreenshot=1” is added in the campaign feed request url. Attribute Name Description Values Can be empty? id The campaign screenshot identifier Integer No thumbnail The campaign screenshot thumbnail url Url No File The campaign screenshot url Url No 3.6 Capping (campaign level) root > service > campaigns > campaign > cappings > capping A campaign can have several cappings, so “capping” elements are contained in a “cappings” element. Cappings are capping configuration information at campaign level for publisher who requested the campaign feed. This part is displayed when parameter “&displayCappingConfig=1” is added in the campaign feed request url. Attribute Name Description Values Can be empty? period The campaign level capping period Daily Weekly Month No country The campaign level capping targeting country String Yes device The campaign level capping targeting device String Yes payout The campaign level capping payout value Number No 3.7 Action root > service > campaigns > campaign > actions > action A campaign can contains several actions, so “action” elements are contained in an “actions” © Cheetah Media Link 2015 – All rights reserved help@cmcm.com element. An action is a way to monetize a campaign like subscription, purchase, CPC … This part is displayed when parameter “&displayAction=1” is added in the campaign feed request url. Attribute Name Description Values Can be empty? id The action identifier Integer No name The action name String No type The action type (CPS, CPI, CPL…) String No click The action click url (Redirect to random url among matching children target) Url No banner The action banner url (Redirect to random banner url from random matching children target) (Auto detect device width) Url No text The action text creative (Fixed to “Click here” for now) String No applicatio nId Identifier on official store (AppStore) String Yes 3.8 Application root > service > campaigns > campaign > actions > action > application Application related data retrieved from Google Play (for Android CPI campaigns) or Apple App store (for iOS CPI campaigns). This part is displayed when parameter “&displayApplication=1” is added in the campaign feed request url and the campaign is CPI at the same time. Attribute Name Description Values Can be empty? id Identifier on official store (AppStore) String No osName The application OS name String No url The application url on official store Url No thumbnail The application thumbnail url Url No companyN ame The application company name String No rating The application rating on official store. A number between 0 and 5 (e.g. “4.3”) Number Yes © Cheetah Media Link 2015 – All rights reserved help@cmcm.com 3.9 Language … > campaign > actions > action > application > languages > language Application information in different languages retrieved from Google Play (for Android CPI campaigns) or Apple App store (for iOS CPI campaigns). This part is displayed when parameter “&displayApplication=1” is added in the campaign feed request url and the campaign is CPI at the same time. Attribute Name Description Values Can be empty? iso The language country iso String No name The application name in this language String No baseline The application description in this language String No price The application price Number No priceCurren cyCode The price currency code String No priceCurren cySymbol The price currency symbol String No 3.10 Capping (action level) … > campaign > actions > action > cappings > capping An action can have several cappings, so “capping” elements are contained in a “cappings” element. Cappings at action level are displayed when parameters “&displayCappingConfig=1” and “&displayAction=1” are both added in the campaign feed request url. Attribute Name Description Values Can be empty? period The action level capping period Daily Weekly Month No country The action level capping targeting country String Yes device The action level capping targeting device String Yes payout The action level capping payout value Number No © Cheetah Media Link 2015 – All rights reserved help@cmcm.com 3.11 Target … > campaign > actions > action > targets > target An action can be composed of several targets, so “target” elements are contained in a “targets” element. A target represents an allowed mobile phone filter on which we can define a destination url, a payout, creatives packs … Target can filter mobile phone by country, operator, brand, model, os, osVersion and proxy. This part is displayed when parameter “&displayTarget=1” is added in the campaign feed request url. Attribute Name Description Values Can be empty? id The target id Integer No click The target click url Url No banner The target banner url (Redirect to random banner url from this target) (Auto detect device width) Url No text The target text creative (Fixed to “Click here” for now) String No country Traffic allowed limited to one country ISO codes (ISO 3166) Yes operator Traffic allowed limited to one operator Integer (get full list here) Yes brand Traffic allowed limited to one phone brand Integer (get full list here) Yes model Traffic allowed limited to one phone model Integer (get full list here) Yes os Traffic allowed limited to one os Integer (get full list here) Yes osVersion Traffic allowed limited to one os version Integer (get full list here) Yes proxyAllo wed Is proxy traffic allowed? 0 (No) 1 (Yes) No geoarea The target geoarea name String Yes © Cheetah Media Link 2015 – All rights reserved help@cmcm.com 3.12 Payout … > actions > action > targets > target > payout A payout represents the part paid to you for a specific target when a transaction happens. It can be in US Dollars or in percent. This part is displayed when parameter “&displayPayout=1” is added in the campaign feed request url. Attribute Name Description Values Can be empty? type The payout type 1 (Fix) 2 (Percent from Cheetah Media Link part) 3 (Percent from Advertiser part) No value Fix type: Part paid to you in US Dollars Percent type: Part paid to you in percent Number No currency (Only for Fix type) USD/EUR/GBP No 3.13 Creative Pack … > action > targets > target > creativesPacks > creativesPack A target can have several creatives packs, so “creativesPack” elements are contained in a “creativesPacks” element. A creatives pack is a set of creatives with different type and size (See next section) Ex: two texts, a 300x50 image and a 320x50 image... This part is displayed when parameter “&displayCreativesPack=1” is added in the campaign feed request url. Attribute Name Description Values Can be empty? id The creatives pack idendifier Integer No name The creatives pack name String No click The creatives pack click url Url No banner The creatives pack banner url (Redirect to random banner url from this creative pack) (Auto detect device width) Url No text The creatives pack text (Fixed to “Click here” for now) String No © Cheetah Media Link 2015 – All rights reserved help@cmcm.com 3.14 Creative … > target > creativesPacks > creativesPack > creatives > creative A creative pack can be composed of several creatives, so “creative” elements are contained in a “creatives” element. A creative is a displayed item on which the user will click to access the promoted product. It can be a text or an image. This part is displayed when parameter “&displayCreative=1” is added in the campaign feed request url. Attribute Name Description Values Can be empty? id The creatives idendifier Integer No type The creative type 1 (Text) 2 (Image) No width The image width in pixels (Only for Image type) Integer No height The image height in pixels (Only for Image type) Integer No file The image final url (Only for Image type) String No click The creatives click url Url No banner The creatives banner url (Only for Image type) Url No text The creatives text (Only for Text type) String No 3.15 Exclude … > action > targets > target > excludes > exclude An exclude is displayed when there is excluding item for this target. This part is displayed when parameter “&displayExclude=1” is added in the campaign feed request url. Attribute Name Description Values Can be empty? country Traffic excluding one country ISO codes (ISO 3166) Yes operator Traffic excluding one operator Integer (get full list here) Yes brand Traffic excluding one brand Integer (get full list here) Yes model Traffic excluding one model Integer (get full list here) Yes os Traffic excluding one os Integer (get full list here) Yes osVersion Traffic excluding one os version Integer (get full list here) Yes © Cheetah Media Link 2015 – All rights reserved help@cmcm.com 3.16 Global view of the campaign feed response 3.16.1 XML <root> <service id="" name=""> <campaigns> <campaign id="" name="" click="" banner="" text="" incentAllowed="" cappingReached=""> <categories> <category id=""/> </categories> <platforms> <platform id=""/> <platform id=""/> </platforms> <screenshots> <screenshot id="" thumbnail="" file=""/> </screenshots> <actions> <action id="" name="" type="" click="" banner="" text="" applicationId=""> <application id="" osName="" url="" thumbnail="" companyName="" rating=""> <languages> <language iso="" name="" baseline="" price="" priceCurrencyCode="" priceCurrencySymbol=""/> </languages> </application> <targets> <target id="" click="" banner="" text="" country="" operator="" brand="" model="" os="" osVersion="" proxyAllowed="" geoarea=""> <payout type="" value="" group="" currency=""/> <creativesPacks> <creativesPack id="" name="" click="" banner="" text=""> <creatives> <creative id="" type="" width="" height="" file="" click="" banner="" text=""/> </creatives> </creativesPack> </creativesPacks> <excludes> <exclude country="" operator="" brand="" model="" os="" osVersion=""/> </excludes> <cappings > <capping period="" country="" device="" payout=""/> </cappings > </target> </targets> </action> </actions> <cappings> <capping period="" country="" device="" payout=""/> </cappings> </campaign> </campaigns> </service> </root> © Cheetah Media Link 2015 – All rights reserved help@cmcm.com 3.16.2 JSON { "service": { "id": "", "name": "", "campaigns": { "campaign": [ { "id": "", "name": "", "click": "", "banner": "", "text": "", "incentAllowed": "", "categories": { "category": [ { "id": "" } ] }, "platforms": { "platform": [ { "id": "" } ] }, "screenshots": { "screenshot": [ { "id": "", "thumbnail": "", "file": "" } ] }, "actions": { "action": [ { "id": "", "name": "", "type": "", "click": "", "banner": "", "text": "", "applicationId": "", "application": { "id": "", "osName": "", "url": "", "thumbnail": "", "companyName": "", "rating": "", "languages": { "language": [ { "iso": "", "name": "", "baseline": "", "price": "", "priceCurrencyCode": "", "priceCurrencySymbol": "" } © Cheetah Media Link 2015 – All rights reserved help@cmcm.com ] } }, "targets": { "target": [ { "id": "", "click": "", "banner": "", "text": "", "country": "", "operator": "", "brand": "", "model": "", "os": "", "osVersion": "", "proxyAllowed": "", "payout": { "type": "", "value": "", "group": "", "currency": "" }, "geoarea":"" "creativesPacks": { "creativesPack": [ { "id": "", "name": "", "click": "", "banner": "", "text": "", "creatives": { "creative": [ { "id": "", "type": "", "width": "", "height": "", "file": "", "click": "", "banner": "", "text": "" } ] } } ] }, "excludes": { "exclude": [ { "country": "", "operator": "", "brand": "", "model": "", "os": "", "osVersion": "" } ] } "cappings": { "capping": [ { "period": "", "country": "", "device": "", © Cheetah Media Link 2015 – All rights reserved help@cmcm.com "payout": "" } ] } } ] } } ] }, "cappingReached": "", "cappings": { "capping": [ { "period": "", "country": "", "device": "", "payout": "" } ] } } ] } } } © Cheetah Media Link 2015 – All rights reserved help@cmcm.com