Direct Campaign API

Direct Campaign API Guide

4684 views 2019-09-22 Ofer Garnett 0

Objective

This document provides directions on how to access YouAppi’s offline (server to server) campaign API and use YouAppi’s campaign URLs.

API Request

Request URL Format

Access to the YouAppi campaign API is via http GET, using the following URL:

https://service.youappi.com/cmp/campaigninfo?accesstoken=XXX

Please be sure to check in every 5-10 minutes in order to retrieve the most updated campaigns available.

Mandatory Parameters

accesstoken is a unique API key that will be provided to the publisher by YouAppi and will look similar to this: 888777666-987-4268-b99c-e24f9b286bc5. The publisher must replace the XXX placeholder in the example above with the token provided. Please note that the value for this parameter should be hardcoded into the link once.

Optional Parameters

You can filter the OS targeting of the campaigns by appending the os parameter, which can be set to either of the following:

“android” – integration will get android campaigns only
“ios” – integration will get ios campaigns only

Examples:

https://service.youappi.com/cmp/campaigninfo?accesstoken=XXX&os=ios
Will provide only ios campaigns.

https://service.youappi.com/cmp/campaigninfo?accesstoken=XXX&os=android
Will provide only Android campaigns.

API Response

Response Format

The response of the API is in JSON format. YouAppi’s response looks like this:

{  
   "status":200,
   "statusMessage":"OK ",
   "data":{  
      "402":{  
         "offer_id":952771,
         "campaign_id":10012345,
         "platform":"iphone",
         "cpi":"0.80",
         "target_ecpi":"2.60",
         "app_url":"https://itunes.apple.com/app/id282614216?mt=8&ls=1",
         "redirect_url":"https://service.youappi.com/app/directlink?accesstoken=exmpl123_abc123&appid=1234&campaignpartnerid=1836&subid=&publishertoken=&publishername=&usertoken=&deviceAndroidId=&deviceIfa=&age=&gender=&publisher_type=&format=&consent=",
         "countries":[  
            "gb"
         ],
         "cities":[  
            "Manchester"
         ],
         "max_daily":100,
         "max_total":10000,
         "capping_type":"installs",
         "app_details":{  
            "app_id":"449655162",
            "app_icon":"http://d2ym6yrl197shi.cloudfront.net/icons/iphone_449655162_190.png",
            "app_description":"Available in 24 cities including New York, London, Moscow, St Petersburg",
            "app_name":"Gett - Taxi, Cab, Limo & Black Car Service",
            "app_os":"iphone"
         },
         "creatives":{  
            "320x50":"https://static.youappi.com/creatives/Apps/60116/118/50/320x50/ES.jpg",
            "300x250":"https://static.youappi.com/creatives/Apps/60116/118/50/300x250/ENG.gif"
         },
         "blacklist_publisherTokens":[  
            "1234",
            "abc123"
         ],
         "adid_required":false,
         "idfa_required":false,
         "minOS":"4.1",
         "deviceType":"SMART PHONE"
      }
   },
   "totalNumberOfEntries":1
}

Available Parameters

The table below contains information about the parameters that are available through the API.

Field Name Description Optional Value Type Values
offer_id A unique ID assigned to the campaign for a specific publisher by the YouAPPi system. No Integer
campaign_id A unique ID assigned to the campaign by the YouAPPi system. No Integer
platform The platform of the campaign No String

iphone

ipad

android
cpi The cost (in USD) the publisher will receive from YouAPPi for every valid installation. Depends on the cost model. Yes Double
cpc The cost (in USD) the publisher will receive from YouAPPi for every valid click. Depends on the cost model. Yes Double
app_url The URL of the app’s page in the relevant app store. No String
redirect_url The click URL of the campaign. See section 4 for more information. No String
impression_url The impression URL of the campaign. Yes String
countries The countries relevant to the campaign. No Array of strings
regions The regions relevant to the campaign. No Array of strings
zip_codes The zip codes relevant to the campaign. No Array of strings
day_parts The day parts relevant to the campaign. No Array of strings
cities The cities relevant to the campaign. Yes Array of strings
max_daily The maximum amount of clicks/installs/USD the campaign is allowed to reach in a day. Yes Double
max_total The maximum amount of clicks/installs/dollars the campaign is allowed to reach in its lifetime. Yes Double
capping_type The event by which capping is enforced. Yes String

installs

clicks

USD
app_id The bundle ID or package name of the promoted app in the relevant app store. No String
app_icon A direct link to the app’s icon. No String
app_description The description of the app, as stored in the relevant app store. No String
app_name The full name of the app, as stored in the relevant app store. No String
app_os The operating system relevant to the campaign’s app. No String

iphone

ipad

android
creatives The link to the creative files relevant to the campaign. Yes Map string-to-string
whitelist_publisherTokens Channels (publisher tokens or site IDs) that are whitelisted by the advertiser. Yes Array of strings
blacklist_publisherTokens Channels (publisher tokens or site IDs) that are blacklisted by the advertiser. Yes Array of strings
adid_required An indication whether the campaign requires Google Advertising ID. Yes Boolean

true

false
idfa_required An indication whether the campaign requires IDFA. Yes Boolean

true

false
bundle_id_required An indication whether the campaign requires the publisher bundle ID. Yes Boolean

true

false
whitelist_supply_bundle_id An indication whether the campaign has a supply bundle IDs Whitelist Yes Array of strings
blacklist_supply_bundle_id An indication whether the campaign has a supply bundle IDs Blacklist Yes Array of strings
minOS The minimum OS version required for the campaign No Integer
maxOS The maximum OS version required for the campaign No Integer
carrierNames List of carriers to target Yes Array of strings
deviceType The type of the device that is required for the campaign No String

SMART PHONE

TABLET
deviceModels The device models that are required for the campaign No Array of strings

 

 
totalNumberOfEntries The number of offers currently available through the API No Integer

 

Using the Campaign Redirect URL

Campaign URL Format

The campaign redirect URL contains a number of parameters that must be populated by the publisher (marked in orange below):

https://service.youappi.com/app/directlink?accesstoken=exmpl123_abc123&appid=1234&campaignpartnerid=1836&subid=&publishertoken=&publishername=&usertoken=&deviceAndroidId=&deviceIfa=&age=&gender=&publisher_type=&format=

The publisher must populate each parameter with the relevant parameter, macro or value from his end, and only then implement the redirect URL on his side. Information about these parameters can be found in the following section.

Redirect URL Parameters

The table below contains detailed information about the parameters that are appended to the redirect URL. Please note that the parameters are case sensitive!

Field Name Description Value Type Expected Values
* subid Sub ID for install postback setup String
subid2 / subid3 / subid4 / subid5 Placeholders for additional parameters that the publisher wants to pass on the click in order to have them passed back by us on the postback. String
* publishertoken Site ID String
publishername Site name String
deviceAndroidId Google advertising ID String
deviceIfa IDFA, iOS advertising ID String
bundle_id The bundle ID of the app String
consent The consent of the user according to the GDPR.
If not populated will automatically default to consent=false		 String

true / 1

false / 0

* Mandatory parameters

For additional information and support please contact [email protected].

Related Articles