SmartFeed API Guide

664 views 14/05/2018 Shay Karpeles 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",
      "language":"Bahasa",
      "timezone":"UTC+7",
      "user_id":{
         "gaid":"63fbbae8-ee20-4445-900b-c5a4ccc2728d",
         "idfa":"",
         "custom_user_token":"11263"
      }
   },
   "ad_units":[
      {
         "ad_unit_id":"landscape",
         "ad_unit_type":"video",
         "ad_properties":{
            "max_video_duration":30
         }
      }
   ]
}

 

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.

 

Parameter Description Mandatory Data Type Possible Values
access_token The partner’s key used to access the API; provided by YouAppi Yes String
request_origin The origin of the request: client or server. Yes String

client

server

publisher_info app_id The publisher’s package name/bundle ID/native ID. Yes String 284809790
publisher_token A custom ID of the sub-publisher in the publisher’s system Yes String 4568
publisher_name The name of the sub-publisher No String Yellow Pages
user_info ip The client’s IP address Only when origin = server String
user_agent The client’s user agent string Only when origin = server String
gender The user’s gender No String
year_of_birth The user’s year of birth No Integer
language The system language of the device No String
user_id gaid The client’s Google Advertising ID, when OS is Android. The value must not be encoded. Yes String
idfa The client’s iOS IDFA, when OS is iOS. The value must not be encoded. Yes String
custom_user_token A custom ID of the user in the publisher’s system No String 1256
ad_units ad_unit_id ID or description of the ad unit or placement Yes String home
ad_unit_type The type of ad unit that will be displayed to the user. See “Possible Values”. Yes String

image

 

video

ad_unit_num The number of recommendations wanted. Max is 10.

No

[default is 1]

Integer
ad_properties image_dimensions

widthxheight (in pixels) of the requested creative.

See “Possible Values”.

Yes, when ad_unit_type = image String

[Please replace the x char with a legal x char when copy-pasting these values to your code]

300×50

320×50

300×250

320×480

480×320

768×1024

1024×768

1200×627

1200×628

728×90

600×314

648×340

640×200

640×100

600×500

468×60

480×855

1136×640

1200×800 1024×728

1280×720

max_video_duration Duration of the video in seconds No, only available when ad_unit_type = video Integer 30
companion_img_sizes Additional 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. No String 320×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>",
                  "video_url":"https://onlineapi.youappi.com/v/cache/48f6f7bc-0e7f-42bd-a1ef-a3b03310adb5.landscape.1"
               }
            }
         ]
      }
   ]
}

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 Integer
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 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_url URL which points to a VAST 2.0 tag. This URL expires after 10 minutes. Yes String
video_vast VAST 2.0 XML Yes String

 

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.