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.

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.

*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 [email protected].