DirectRun API Guide

305 views 28/01/2018 Shay Karpeles 0

1. Objective

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

2. API Request

2.1 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 10 minutes to 1 hour in order to retrieve the most updated campaigns available.

2.2 Mandatory Parameters

accesstoken is a unique access token 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 with the token provided. Please note that the value for this parameter should be hardcoded into the link once.

3. API Response

3.1 Response Format

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

{  
   "status":200,
   "statusMessage":"OK ",
   "data":{  
      "402":{  
         "campaign_id":10012345,
         "platform":"iphone",
         "cpc":"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=",
         "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
}

 

3.2 Available Parameters

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

Field Name Description Optional Value Type Values
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
target_ecpi The target eCPI (in USD) according to which the publisher is expected to optimize the campaign. Only available when the cost model is CPC. 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
countries The countries 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 unique identifier of an 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 or banner files relevant to the campaign. Creatives aren’t available for every campaign. Yes Map string-to-string
whitelist_publisherTokens Channels (publisher tokens or site IDs) that are whitelisted by the advertiser. Yes String
blacklist_publisherTokens Channels (publisher tokens or site IDs) that are blacklisted by the advertiser. Yes String
adid_required An indication whether the campaign requires AdID. Yes Boolean

true

false

idfa_required An indication whether the campaign requires IDFA. Yes Boolean

true

false

minOS The minimum OS version required for the campaign No Integer
deviceType The type of the device that is required for the campaign No String

SMART PHONE

TABLET

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

 

4. Using the Campaign Redirect URL

4.1 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.

4.2 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
publishertoken Site ID String
publishername Site name String
usertoken A unique user ID (i.e. device identifier or customer ID) String
deviceAndroidId Google advertising ID String
deviceIfa IDFA, iOS advertising ID String
age The user’s age Integer
gender The user’s gender String

male

female

publisher_type The publisher’s media type String

app

web

format The type of ad placement inside the publisher’s content String

banner

fullscreen

app_wall

in_content

For additional information and support please contact support@youappi.com.