SmartFeed API Guide

4097 views 2019-08-12 Ofer Garnett 0

Introduction

YouAppi’s SmartFeed API is a campaign recommendation API used to access YouAppi’s demand portfolio in real time. Publishers using this API are able to display ads that are the most suitable for their users. YouAppi’s SmartFeed API is compatible with both client-to-server & server-to-server integrations.

General Flow

Using YouAppi’s SmartFeed API is easy:

(1) Request is made to YouAppi’s servers

(2) Taking into consideration the information in the request, YouAppi’s recommendation engine selects the best campaign(s) for the user and returns a response

(3) The publisher processes YouAppi’s response and displays the ad to the user

API Request

Request Format

  • Request endpoint:https://onlineapi.youappi.com/online
  • Request method:POST
  • HTTP header:Content-Type = application/json.

Request Body

All requests should be made in JSON format; consider the following example.

{
  "access_token": "720dc669-cfe7-45d2-a85b-accda8419a1d",
  "request_origin": "server",
  "publisher_info": {
    "app_id": "greedygame.com",
    "publisher_token": "greedygame.com"
  },
  "user_info": {
    "ip": "82.81.135.50",
    "user_agent": "Mozilla/5.0 (Linux; Android 6.0.1; Redmi 4A Build/MMB29M; wv) AppleWebKit/537.36 (KHTML, like Gecko) Version/4.0 Chrome/57.0.2987.132 Mobile Safari/537.36",
    "user_id": {
      "gaid": "63fbbae8-ee20-4445-900b-c5a4ccc2728d",
      "idfa": "",
      "custom_user_token": "11263"
    },
    "gender": "m",
    "year_of_birth": 1985,
    "gdpr": 0,
    "consent": "1"
    "coppa": "0"
  },
  "device_info": {
    "device_lang": "en"
  },
  "ad_units": [
    {
      "ad_unit_id": "landscape",
      "ad_unit_type": "video",
      "ad_properties": {
        "min_duration": 5,
        "max_duration": 30,
        "min_bitrate": 100,
        "max_bitrate": 3500,
        "start_delay": 5,
        "playback_method": 1,
        "skippable": 1,
        "player_width": 320,
        "player_height": 480,
        "instl": 1
      }
    }
  ]
}

 

Request Parameters

The table below includes all of the fields that are available on the request.

Please avoid unnecessary space characters and note that request parameters are case sensitive.

ParameterDescriptionMandatoryData TypePossible Values
access_tokenThe partner’s key used to access the API; provided by YouAppiYesString82jfa77-3127-42b5-9e6b-0afzecf77c
request_originThe origin of the request: client or server.YesStringclient
server
publisher_info app_idThe publisher’s package name/bundle ID/native ID.YesString284809790
publisher_token
A custom ID of the sub-publisher in the publisher’s systemYesStringcom.awesomegame
publisher_nameThe name of the sub-publisherNoStringAwesome Game
user_infoip
The client’s IP addressOnly when origin = serverString77.234.46.185
user_agentThe client’s user agent stringOnly when origin = serverStringMozilla/5.0 (iPhone; CPU OS 11_0 like Mac OS X) AppleWebKit/604.1.25 (KHTML, like Gecko) Version/11.0 Mobile/15A372 Safari/604.1
genderThe user’s genderNoString
year_of_birthThe user’s year of birthNoInteger
user_idgaidThe client’s Google Advertising ID, when OS is Android. YesString
idfaThe client’s iOS IDFA, when OS is iOS. YesString
custom_user_tokenA custom ID of the user in the publisher’s systemNoString1256
gdprIndicate if the impression is GDPR regulated or not.Yes (Only for European users)Integer0 (no), 1 (yes)
consentGDPR user’s consent signals the permission to process and store user’s personal information Yes (only for European users)String0 (no), 1 (yes), or Full consent string
coppaIndicate if the impression is COPPA regulated or not. Yes (only for age restricted users)Integer0 (no), 1 (yes)
device_langThe device language in ISO-639-1-alpha-2 typeNoString
ad_unitsad_unit_idID or description of the ad unit or placementYesStringtest_ad_unit
ad_unit_typeThe type of ad unit that will be displayed to the user.YesStringimage
video
ad_unit_numThe number of recommendations wanted. Max is 10.No (default is 1)Integer
ad_propertiesimage_dimensionswidth X height (in pixels) of the requested creative.
See “Possible Values”.
Yes, when ad_unit_type = imageString[Please make sure that the x char is a legal x char when copy-pasting these values to your code]
300x50
320x50
300x250
320x480
480x320
768x1024
1024x768
1200x627
1200x628
728x90
600x314
648x340
640x200
640x100
600x500
468x60
480x855
1136x640
1200x800
1024x728
1280x720
min_durationMinimum duration of video accepted, in seconds.No, only available when ad_unit_type = videoInteger
max_durationMaximum duration of video accepted, in seconds.No, only available when ad_unit_type = videoInteger
min_bitrateMinimum Bitrate of encoded videoNo, only available when ad_unit_type = videoInteger
max_bitrateMaximum Bitrate of encoded videoNo, only available when ad_unit_type = videoInteger
start_delayTime in seconds for the video start delay

(If the start delay value is greater than 0, then the position is mid-roll and the value indicates the start delay.)
No, only available when ad_unit_type = videoInteger
playback_methodPlayback methods that may be in use

Only one method is typically used in practice
No, only available when ad_unit_type = videoInteger1 for Autoplay Sound on

2 for Autoplay sound off

3 for Click to play
skippableIs the video is skippable or notNo, only available when ad_unit_type = videoString1 or true

0 or false
player_widthThe video player’s width in pixelNo, only available when ad_unit_type = videoInteger320/480/768/1024
player_heightThe video player’s height in pixel No, only available when ad_unit_type = videoInteger320/480/768/1024
instlAll placements are interstitialsYesInteger1
companion_img_sizesAdditional companion banners of the same app, added to the video ad using the following format: widthxheight, separated by comma. This parameter is required in order to get companion ads.NoString320×480

API Response

Response Format

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

{
   "response_id":"48f6f7bc-0e7f-42bd-a1ef-a3b03310adb5",
   "ad_units":[
      {
         "ad_unit_id":"landscape",
         "ad_unit_type":"video",
         "ads":[
            {
               "ad_id":"48f6f7bc-0e7f-42bd-a1ef-a3b03310adb5.landscape.1",
               "app_info":{
                  "app_name":"The Rats",
                  "app_developer":"INTENIUM GmbH",
                  "app_native_id":"air.de.intenium.rats",
                  "app_rating":4.3,
                  "app_category":"GAMES",
                  "app_description":"*** Attention! Rat-tastic Action Game! ***\n\nPlay with 8 million players on Facebook, on your mobile or your tablet. The prizewinning “The Rats” is unique and well known from television.\n\nWhat are you waiting for!?\n\nOnly “The Rats” is a crazy mix of puzzle, simulation and casual games. Marry your rats and found a fluffy rat family to loot your neighbors! Lead your rat pack out of their subterranean prison into cheese paradise! Steal cheese, gather souls and loot your friends. Or celebrate a rat wedding and raise new baby rats in familial harmony with your clan members. Are you smart enough to puzzle your way out of the caves? This game is different from anything you’ve ever seen before! Only here will you find and fight your true (rat) love\n\nCASUAL\nSomewhere between Match-3 and Puzzle games: with the right tactics you will survive the battle within the prison’s caves. But beware, only the smartest cheese thieves will survive! Grab your mobile and look after your plushy rat clan all day long.\n\nWEDDING\nFind and fight the love of your life! Rats are not just thieves – they have feelings and a strong yearning for family affairs. Every bride is looking for a groom. Every husband loves his desperate house-rat. Raise your own rat family and celebrate your rats’ wedding. And merge your baby rats to level up your family business.\n\nPUZZLE\nDo you have the superior reflexes and skills needed to lead your cheese thieves through the puzzle-ridden caves of their subterranean prison?\n\nCLAN\nYou’ll only be strong if you have friends. Found your own fluffy rat clan and form a dangerous army of joker and vampire rats. Loot your neighbors and become the master of cheese thieves. Or join your friend’s rat family in harmony and tend to your own family affairs. Celebrate rat weddings and populate the caves with tiny cute baby rats.\n\nSIMULATION\nGrow your rat family and be the wise leader of your devilish and angel-like rat pack. Do so by collecting cheese, souls and skill points to improve your clan. Lead your tribe of saint and sinner rats and become top of the notch!\n\nCAVES\nLeveling up provides you with new caves full of loot. Here you‘ll get souls and cheese as well as important skill items. Your devil and angel rats are mad about those!\n\nCOMPETITIONS\nWin valuable in-game prizes in worldwide competitions and reach the top of the cheese pyramid. Every competition lasts for 72 hours. The right appetite for cheese and souls will lead you out of your subterranean prison into rat heaven. You decide whether you want to go down this road alone or in a clan with your friends.\n\nSKILLS\nCollect skill points, upgrade your angel and devil rats and crossbreed them to get even more sneaky super rats! Your rat party will soon include vampire and joker rats. Train them to become master thieves! \n\nPvP\nPlay solo against the world and loot your enemies or join ranks with your friends and celebrate your family affairs. Play on Facebook and form alliances with your plushy baby rats. Or simply outperform your neighbor’s angel and devil rats.\n\nTAMAGOTCHI\nGive your rats individual skills, crossbreed them and raise your own vampire and joker rats! But be careful: if you don’t care enough for your rats, you’ll lose them forever.\n\nCOLLECT CHEESE AND SOULS\nBe it cheese, souls or item sets – rats are hardworking gatherers and thieves and progress can only be made with the right loot. Steal cheese and souls from your neighbors or master gruesome caves and you’ll be rewarded. Every successful attack grants you the required skill points or cheese for your storage.\n\n\"The Rats\" is a free-to-play multiplatform game. Play with your friends on Facebook or on your mobile, or Android device. You’ll only survive the contest for cheese, souls and love with the right strategy and by mastering the unique mix of puzzle and simulation. Play now for free!\n\nAlready a fan?\n\nGive \"The Rats\" a like on Facebook and stay up to date with all the latest tips and tricks:\nfacebook.com/TheRatsOnline",
                  "app_cta":"Download Now!",
                  "app_store_page":"https://play.google.com/store/apps/details?id=air.de.intenium.rats",
                  "app_icon":"https://static.youappi.com/icons/android_air.de.intenium.rats_190.png"
               },
               "tracking_urls":{
                  "impression_url":"https://onlineapi.youappi.com/impressions?device_id=xiaomi_redmi_4a_ver1&ip=82.81.135.50&params=NGNG48f6f7bc-0e7f-42bd-a1ef-a3b03310adb5.landscape.1_64894_2018-01-29_63fbbae8-ee20-4445-900b-c5a4ccc2728d_10&ad_unit_id=landscape&ad_unit_type=Video&rec_time=1517221304638&publisher_token=greedygame.com&user_id=63fbbae8-ee20-4445-900b-c5a4ccc2728d&ad_group_id=0&rp=YgbZKpYdHdY&hash=k9eE9g9CLKVOxwkhS-3XsdRLlIJc13Y4&user_id_type=GAID&origin=Server&request_id=48f6f7bc-0e7f-42bd-a1ef-a3b03310adb5&ad_id=48f6f7bc-0e7f-42bd-a1ef-a3b03310adb5.landscape.1&cp=SQe4RNAUfww&partner_token=720dc669-cfe7-45d2-a85b-accda8419a1d&campaign_id=10117840",
                  "click_url":"https://onlineapi.youappi.com/clicks?device_id=xiaomi_redmi_4a_ver1&ip=82.81.135.50&ad_unit_id=landscape&ad_unit_type=Video&rec_time=1517221304638&redirect_url=http%3A%2F%2Fsevengames.go2cloud.org%2Faff_c%3Foffer_id%3D7422%26aff_id%3D1545%26aff_sub2%3DNGNG48f6f7bc-0e7f-42bd-a1ef-a3b03310adb5.landscape.1_64894_2018-01-29_63fbbae8-ee20-4445-900b-c5a4ccc2728d_10%26aff_sub%3D10232231%26google_aid%3D63fbbae8-ee20-4445-900b-c5a4ccc2728d&publisher_token=greedygame.com&user_id=63fbbae8-ee20-4445-900b-c5a4ccc2728d&ad_group_id=0&rp=YgbZKpYdHdY&hash=k9eE9g9CLKVOxwkhS-3XsdRLlIJc13Y4&user_id_type=GAID&origin=Server&request_id=48f6f7bc-0e7f-42bd-a1ef-a3b03310adb5&ad_id=48f6f7bc-0e7f-42bd-a1ef-a3b03310adb5.landscape.1&cp=SQe4RNAUfww&partner_token=720dc669-cfe7-45d2-a85b-accda8419a1d&campaign_id=10117840"
               },
               "creatives":{
                  "video_vast":"<VAST version=\"2.0\">  <Ad id=\"48f6f7bc-0e7f-42bd-a1ef-a3b03310adb5\">    <InLine>      <AdSystem>Youappi</AdSystem>      <AdTitle></AdTitle>      <Impression>        <![CDATA[https://onlineapi.youappi.com/impressions?device_id=xiaomi_redmi_4a_ver1&ip=82.81.135.50&params=NGNG48f6f7bc-0e7f-42bd-a1ef-a3b03310adb5.landscape.1_64894_2018-01-29_63fbbae8-ee20-4445-900b-c5a4ccc2728d_10&ad_unit_id=landscape&ad_unit_type=Video&rec_time=1517221304638&publisher_token=greedygame.com&user_id=63fbbae8-ee20-4445-900b-c5a4ccc2728d&ad_group_id=0&rp=YgbZKpYdHdY&hash=k9eE9g9CLKVOxwkhS-3XsdRLlIJc13Y4&user_id_type=GAID&origin=Server&request_id=48f6f7bc-0e7f-42bd-a1ef-a3b03310adb5&ad_id=48f6f7bc-0e7f-42bd-a1ef-a3b03310adb5.landscape.1&cp=SQe4RNAUfww&partner_token=720dc669-cfe7-45d2-a85b-accda8419a1d&campaign_id=10117840]]>      </Impression>      <Creatives>        <Creative id=\"48f6f7bc-0e7f-42bd-a1ef-a3b03310adb5.landscape.1\">          <Linear>            <Duration>0:00:18</Duration>            <VideoClicks>              <ClickThrough>                <![CDATA[http://sevengames.go2cloud.org/aff_c?offer_id=7422&aff_id=1545&aff_sub2=NGNG48f6f7bc-0e7f-42bd-a1ef-a3b03310adb5.landscape.1_64894_2018-01-29_63fbbae8-ee20-4445-900b-c5a4ccc2728d_10&aff_sub=10232231&google_aid=63fbbae8-ee20-4445-900b-c5a4ccc2728d]]>              </ClickThrough>              <ClickTracking>                <![CDATA[https://onlineapi.youappi.com/clicks?device_id=xiaomi_redmi_4a_ver1&ip=82.81.135.50&ad_unit_id=landscape&ad_unit_type=Video&rec_time=1517221304638&publisher_token=greedygame.com&user_id=63fbbae8-ee20-4445-900b-c5a4ccc2728d&ad_group_id=0&rp=YgbZKpYdHdY&hash=k9eE9g9CLKVOxwkhS-3XsdRLlIJc13Y4&user_id_type=GAID&origin=Server&request_id=48f6f7bc-0e7f-42bd-a1ef-a3b03310adb5&ad_id=48f6f7bc-0e7f-42bd-a1ef-a3b03310adb5.landscape.1&cp=SQe4RNAUfww&partner_token=720dc669-cfe7-45d2-a85b-accda8419a1d&campaign_id=10117840]]>              </ClickTracking>            </VideoClicks>            <TrackingEvents>              <Tracking event=\"start\"><![CDATA[https://onlineapi.youappi.com/v/track/start?adid=48f6f7bc-0e7f-42bd-a1ef-a3b03310adb5.landscape.1]]></Tracking>              <Tracking event=\"midpoint\"><![CDATA[https://onlineapi.youappi.com/v/track/mid?adid=48f6f7bc-0e7f-42bd-a1ef-a3b03310adb5.landscape.1]]></Tracking>              <Tracking event=\"complete\"><![CDATA[https://onlineapi.youappi.com/v/track/end?adid=48f6f7bc-0e7f-42bd-a1ef-a3b03310adb5.landscape.1]]></Tracking>            </TrackingEvents>            <MediaFiles>              <MediaFile id=\"573120\" delivery=\"progressive\" type=\"video/mp4\" width=\"1280\" height=\"720\"><![CDATA[https://static.youappi.com/creatives/Apps/64894/default/d88632274783fa24c474918e0f38078e.mp4]]></MediaFile>            </MediaFiles>          </Linear>        </Creative>      </Creatives>    </InLine>  </Ad></VAST>",
               }
            }
         ]
      }
   ]
}

Response Parameters

Below is a comprehensive list of the parameters available in the API response.

 

 

Parameter Description Mandatory Data Type
response_id YouAppi’s internal response ID Yes String
ad_units ad_unit_id The ad_unit_id that the publisher sent in the request Yes String
ad_unit_type The ad_unit_type that the publisher sent in the request Yes String
ads ad_id A unique ID that identifies the ad Yes String
app_info* app_name The official name of the app as the store Yes String
app_developer The name of the app developer Yes String
app_native_id The package/bundle ID of the app in the store Yes String
app_rating The rating of the app in the store (1-5) Yes Integer
app_cta The call to action text, used in native ad units Yes String
app_category The category of the app in the store Yes String
app_description The official description of the app in the store Yes String
app_store_page The app’s page in the relevant store Yes String
app_icon Link to the app icon
(Size: 190×190)
Yes String
tracking_urls impression_url YouAppi’s impression tracking URL. This URL must be fired whenever an impression of the ad took place. Yes String
click_url YouAppi’s click URL. This URL must be fired whenever a click took place. Yes String
creatives image_dimensions The dimensions of the image (in pixels): width x height Yes String
image_url Link to the image creative Yes String
image_file_weight The size of the image file in KB Yes Integer
      video_vast VAST 2.0 XML Yes String

*if the campaign’s promoted item is “brand”, then the entire “app_info” section would be absent.

No Ads

If there are no ads available, the ads array will be empty. Like so:

{
    "response_id": "9db2913b-bbf0-433c-89d7-dbbe01181bae",
    "ad_units": [
        {
            "ad_unit_id": "in-feed",
            "ad_unit_type": "image",
            "ads": []
        }
    ]
}

Error Messages

The following is a list of potential errors you may encounter in the response.

  • 500: Internal Server Error

This error may indicate a number of unexpected server errors, and can usually be resolved by re-submitting the request.

  • 4xx: Client Error; may include the following:

o Invalid access token

o User ID is missing from request

o Invalid user ID type

o Invalid request origin

o Invalid ad unit type

o Invalid ad unit num value

o Unsupported device OS/model

The cause for these errors must be corrected before resubmitting the request.

Best Practices

Reporting impressions and clicks

  • Please note thattracking_urls (i.e., for impressions and clicks) are unique per ad.
  • Clicks must be reported every time a user has clicked on thead, and only then.
  • Impressions must be reported each time a user is exposed to thead, and only then.
  • Please note that revenue is calculated for unique impressions (i.e., impression perad).

General

  • Please note that our recommendation engine is set to work under the assumption that calls are made in real-time or close to real-time. Caching – if performed – should be short-term for the duration of one active session per user.
  • Calls can be originated from either the server or the client. If the request is sent from a server, therequest_origin field must say “server” and the ip and user_agent fields must be populated with the details of the client.
  • On the request, the maximum value forad_unit_num is 10.
  • To get the best results, please allow 30,000-60,000 impressions for YouAppi’s algorithm to learn your inventory’s DNA.

 

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