Perkswall API

adspostx is now momentscience! momentscience! 🎉 we have rebranded adspostx to momentscience all the latest documentation and updates can now be found at momentscience documentation https //docs momentscience com/ the adspostx perskwall api is a powerful platform that allows publishers to easily integrate a perks "gallery" within their app or website using any language that supports the ability to make restful calls perkswall offers returns all perkswall enabled offers available to the publisher these offers can be used by the publisher to construct their perkswall in a branded experience in order to use the perkswall api, contact your account manager to enable perkswall on your account quickstart the typical flow to generate and serve offers via a perkswall is as follows api docid\ fdwu3w abztbbfv5jhhqk make a fetch perkswall offers api call to adspostx to retrieve offers (see below for information) parse the response and display offers in the desired fashion ensure that beacon urls fire on sequence and offer impression loads fetch perkswall offers method post base url https //api adspostx com/ native/v2/perkswall json header parameters parameter description type example content type required required should be application/json s tring application/json query parameters parameter description type example api key required required your api key api docid\ fdwu3w abztbbfv5jhhqk required permission ads/offers s tring 4bbdefc2 b130 424d 8170 54bdcb98e64e loyaltyboost optional include loyaltyboost offers in response; values 0 = none 1 = true 2 = only string 0 | 1 | 2 creative optional returns offers with at least one creative (image) if set to true s tring 0 | 1 body parameters parameter description type example ua recommended recommended the user agent of the end user required for proper targeting if proxying requests via a server call, be sure to pass through the user agent of the end user string mozilla/5 0 (linux; android 10; k) applewebkit/537 36 (khtml, like gecko) chrome/120 0 6099 43 mobile safari/537 36 ip recommended recommended ip address of the end user to be passed through used for targeting string adpx fp recommended recommended a unique identifier for the end user; not required but highly recommended more information can be found below string dev optional returns a test response ignores geo restrictions no activity is recorded string 0 | 1 subid optional an id to identify various usages of the fetch perkswall offers api s tring mobile android app post transaction \<string> optional custom key value payload attributes you can add any number of custom key value payload attributes to the payload that you want to use to add additional details all payload attributes are passed back on conversion reports and can be reported on in relation to impression and clicks s tring membershipid "a45gre987343pkd" the adpx fp attribute in the body of the fetch perkswall offers calls is a special parameter that aids in overall offer performance it should be populated with a unique end user identifier as an alpha numeric string adspostx uses the adpx fp value to frequency cap offers on a unique user basis as well as exclude offers from showing again when a user opts out for a certain offer when 'dev' is set to '1', the sandbox environment is enabled for testing purposes only, with no activity recorded in production in this mode, geo targeting is ignored for publishers, ensuring that all offers are returned in ad responses for comprehensive testing the response body upon a successful response from the fetch perkswall offers api request, the body of the reponse will include a data object that contains an array of objects that can be used to construct your offers the following attributes are the relevant attributes to construct your offers with sample response response example { "data" { "offers" \[ { "id" 4586, "title" "you unlocked adspostx for 90 days free!", "description" "adspostx lets you capture revenue across your user's moments delight your users with relevant offers at the right time get 3 months free!", "click url" "https //trk pubtailer com/sdk/offer click?o id=4586\&c id=1879\&p id=1854\&sess id=0ccc9e7f69951c889ce962975e150d69e8a76f29", "image" "https //adpx b cdn net/campaigns/1879/d93fbd2662b784b655d430c9ce3789e4 png", "mini text" "", "pixel" "https //trk pubtailer com/sdk/v2/impression/p png?o id=4586\&c id=1879\&p id=1854\&sess id=0ccc9e7f69951c889ce962975e150d69e8a76f29\&cbuster=%7bcbuster%7d", "cta yes" "earn 150 points", "cta no" "no, thanks", "useraction cta" "", "useraction url" "", "adv pixel url" "", "beacons" { "close" "https //trk pubtailer com/event/record/close?oid=4586\&cid=1879\&pid=1854\&sess id=0ccc9e7f69951c889ce962975e150d69e8a76f29", "no thanks click" "https //trk pubtailer com/event/record/no thanks click?oid=4586\&cid=1879\&pid=1854\&sess id=0ccc9e7f69951c889ce962975e150d69e8a76f29" }, "creatives" \[ { "id" 1769, "url" "https //adpx b cdn net/campaigns/1879/d93fbd2662b784b655d430c9ce3789e4 png", "height" 1530, "width" 1530, "type" "png", "is primary" true, "aspect ratio" 1 } ], "offerwall enabled" true, "short description" "capture revenue across your user's moments get 3 months free!", "short headline" "3 free months of adspostx!", "advertiser name" "adspostx", "is loyaltyboost" true, "loyaltyboost requirements" "user must finish integrating adspostx to qualify you must click “allow” if tracking permission is requested within the app " }, { "id" 5043, "title" "click to unlock adspostx for 90 days free!", "description" "adspostx lets you capture revenue across your user's moments delight your users with relevant offers at the right time get 3 months free!", "click url" "https //trk pubtailer com/sdk/offer click?o id=5043\&c id=2338\&p id=1854\&sess id=0ccc9e7f69951c889ce962975e150d69e8a76f29", "image" "https //adpx b cdn net/campaigns/1649/62a98d93af4e12a3dbbcf247172fadce png", "mini text" "", "pixel" "https //trk pubtailer com/sdk/v2/impression/p png?o id=5043\&c id=2338\&p id=1854\&sess id=0ccc9e7f69951c889ce962975e150d69e8a76f29\&cbuster=%7bcbuster%7d", "cta yes" "try out adspostx!", "cta no" "no, thanks", "useraction cta" null, "useraction url" null, "adv pixel url" "", "beacons" { "close" "https //trk pubtailer com/event/record/close?oid=5043\&cid=2338\&pid=1854\&sess id=0ccc9e7f69951c889ce962975e150d69e8a76f29", "no thanks click" "https //trk pubtailer com/event/record/no thanks click?oid=5043\&cid=2338\&pid=1854\&sess id=0ccc9e7f69951c889ce962975e150d69e8a76f29" }, "creatives" \[ { "id" 2741, "url" "https //adpx b cdn net/campaigns/1649/62a98d93af4e12a3dbbcf247172fadce png", "height" 1530, "width" 1530, "type" "png", "is primary" true, "aspect ratio" 1 } ], "offerwall enabled" true, "short description" "capture revenue across your user's moments get 3 months free!", "short headline" "3 free months of adspostx! click to unlock", "advertiser name" "adspostx", "is loyaltyboost" false, "loyaltyboost requirements" "" }, { "id" 4359, "title" "you unlocked adspostx for 90 days free!", "description" "adspostx lets you capture revenue across your user's moments delight your users with relevant offers at the right time get 3 months free!", "click url" "https //trk pubtailer com/sdk/offer click?o id=4359\&c id=1649\&p id=1854\&sess id=0ccc9e7f69951c889ce962975e150d69e8a76f29", "image" "https //adpx b cdn net/campaigns/1649/62a98d93af4e12a3dbbcf247172fadce png", "mini text" "", "pixel" "https //trk pubtailer com/sdk/v2/impression/p png?o id=4359\&c id=1649\&p id=1854\&sess id=0ccc9e7f69951c889ce962975e150d69e8a76f29\&cbuster=%7bcbuster%7d", "cta yes" "try out adspostx!", "cta no" "no, thanks", "useraction cta" "", "useraction url" "", "adv pixel url" "", "beacons" { "close" "https //trk pubtailer com/event/record/close?oid=4359\&cid=1649\&pid=1854\&sess id=0ccc9e7f69951c889ce962975e150d69e8a76f29", "no thanks click" "https //trk pubtailer com/event/record/no thanks click?oid=4359\&cid=1649\&pid=1854\&sess id=0ccc9e7f69951c889ce962975e150d69e8a76f29" }, "creatives" \[ { "id" 1436, "url" "https //adpx b cdn net/campaigns/1649/62a98d93af4e12a3dbbcf247172fadce png", "height" 1530, "width" 1530, "type" "png", "is primary" true, "aspect ratio" 1 } ], "offerwall enabled" true, "short description" "capture revenue across your user's moments get 3 months free!", "short headline" "3 free months of adspostx!", "advertiser name" "adspostx", "is loyaltyboost" false, "loyaltyboost requirements" "" }, { "id" 4361, "title" "free initial consultation!", "description" "adspostx lets you capture revenue across your user's moments delight your users with relevant offers at the right time start now with a free consultation ", "click url" "https //trk pubtailer com/sdk/offer click?o id=4361\&c id=1651\&p id=1854\&sess id=0ccc9e7f69951c889ce962975e150d69e8a76f29", "image" "https //adpx b cdn net/campaigns/1651/63549ce925dd7372a0da4e35dfe3eeb0 png", "mini text" "", "pixel" "https //trk pubtailer com/sdk/v2/impression/p png?o id=4361\&c id=1651\&p id=1854\&sess id=0ccc9e7f69951c889ce962975e150d69e8a76f29\&cbuster=%7bcbuster%7d", "cta yes" "try out adspostx!", "cta no" "no, thanks", "useraction cta" "", "useraction url" "", "adv pixel url" "", "beacons" { "close" "https //trk pubtailer com/event/record/close?oid=4361\&cid=1651\&pid=1854\&sess id=0ccc9e7f69951c889ce962975e150d69e8a76f29", "no thanks click" "https //trk pubtailer com/event/record/no thanks click?oid=4361\&cid=1651\&pid=1854\&sess id=0ccc9e7f69951c889ce962975e150d69e8a76f29" }, "creatives" \[ { "id" 1438, "url" "https //adpx b cdn net/campaigns/1651/63549ce925dd7372a0da4e35dfe3eeb0 png", "height" 1530, "width" 1531, "type" "png", "is primary" true, "aspect ratio" 1 } ], "offerwall enabled" true, "short description" "capture revenue across your user's moments start now with a free consultation ", "short headline" "free initial consultation!", "advertiser name" "adspostx", "is loyaltyboost" false, "loyaltyboost requirements" "" }, { "id" 4360, "title" "100% revshare for the first month!", "description" "adspostx lets you capture revenue across your user's moments delight your users with relevant offers at the right time get 100% revshare for the first month!", "click url" "https //trk pubtailer com/sdk/offer click?o id=4360\&c id=1650\&p id=1854\&sess id=0ccc9e7f69951c889ce962975e150d69e8a76f29", "image" "https //adpx b cdn net/campaigns/1650/0e4dfbe0875fd1b4190bae4dc2032320 png", "mini text" "", "pixel" "https //trk pubtailer com/sdk/v2/impression/p png?o id=4360\&c id=1650\&p id=1854\&sess id=0ccc9e7f69951c889ce962975e150d69e8a76f29\&cbuster=%7bcbuster%7d", "cta yes" "try out adspostx!", "cta no" "no, thanks", "useraction cta" "", "useraction url" "", "adv pixel url" "", "beacons" { "close" "https //trk pubtailer com/event/record/close?oid=4360\&cid=1650\&pid=1854\&sess id=0ccc9e7f69951c889ce962975e150d69e8a76f29", "no thanks click" "https //trk pubtailer com/event/record/no thanks click?oid=4360\&cid=1650\&pid=1854\&sess id=0ccc9e7f69951c889ce962975e150d69e8a76f29" }, "creatives" \[ { "id" 1437, "url" "https //adpx b cdn net/campaigns/1650/0e4dfbe0875fd1b4190bae4dc2032320 png", "height" 1530, "width" 1531, "type" "png", "is primary" true, "aspect ratio" 1 } ], "offerwall enabled" true, "short description" "capture revenue across your user's moments get 100% revshare for the first month!", "short headline" "100% revshare for the first month!", "advertiser name" "adspostx", "is loyaltyboost" false, "loyaltyboost requirements" "" } ], "count" 5, "privacy url" "https //www adspostx com/privacy policy" } } response parameters upon making an api call, the following attributes are returned in the response to construct your perkswall offers with offers array of offer objects contains the copy, creatives, and resources to construct each offer each offer object has the following attributes offer attributes offers\[] title string recommended to implemen recommended to implemen t for larger formats t for larger formats the title of the offer to be used to construct the headline of the offer maximum length 90 characters offers\[] advertiser name string the name of the advertiser offering the offer offers\[] description string recommended to implemen recommended to implemen t for larger formats t for larger formats the description of the offer maximum length 220 characters offers\[] click url url required to implement required to implement url the offer should direct to offers\[] image url recommended to implement recommended to implement url for the offer's primary image offers\[] mini text string recommended to implement recommended to implement additional sub description for the offer used for disclaimers maximum length 160 characters offers\[] pixel url required to implement required to implement the impression beacon url to be fired when the offer is displayed to the user for impression tracking a successful get call to the pixel url is required to successfully record delivery on the adspostx dashboard offers\[] cta yes string recommended to implement recommended to implement suggested copy for implementing a postitive cta button for the user to accept the offer maximum length 25 characters offers\[] cta no string suggested copy for implementing a negative cta button for the user to reject an offer maximum length 25 characters offers\[] adv pixel url url required to implement if available required to implement if available advertiser may provide their own impression tracking url, fire this along with the pixel impression beacon url a successful get call to adv pixel url is required offers\[] beacons object contains beacon urls for a variety of actions the beacons object contains the following attributes attribute type description offers\[] beacons close url to be fired when closer closes the offer container or when the user has browsed through all available offers for reporting purposes a successful get call to beacons close is required if implemented recommended to implement recommended to implement if perkswall offers are presented in a dismissable container if perkswall offers are presented in a dismissable container offers\[] beacons no thanks click url to be fired when user clicks the negative cta element for reporting purposes a successful get call to beacons no thanks clicks is required if implemented recommended to implement recommended to implement if a negative cta is implemented for each offer on the perkswall if a negative cta is implemented for each offer on the perkswall offers\[] creatives array of creative objects contains additional creative images that can be used to construct the offers unit each creative object contains the following attributes attribute type description offers\[] creatives\[] url url url location for the creative offers\[] creatives\[] height double height of the image in pixels offers\[] creatives\[] width double width of the image in pixels offers\[] creatives\[] type string file type of the image offers\[] creatives\[] is primary boolean indicates whether the image is primary or not offers\[] creatives\[] aspect ratio number the aspect ratio of the image a value of 1 = square image a value < 1 signifies generally portrait a value > 1 signifies generally landscape offers\[] short description string recommended to implemen recommended to implemen t for smaller formats t for smaller formats alternative shorter text to use for the offer's description if the context of the offer is in a smaller format like on mobile or if you're implementing the offer in a smaller element maximum length 140 characters offers\[] short headline string recommended to implemen recommended to implemen t for smaller formats t for smaller formats alternative shorter text to use for the offer's headline if the context of the offer is in a smaller format like on mobile or if you're implementing the offer in a smaller element maximum length 60 characters offers\[] is loyaltyboost boolean indicates if an offer is eligible to be used in an incentive manner offers\[] loyaltyboost requirements string specifies the requirements for a loyaltyboost offer it outlines the actions for which rewards will be granted to users these requirements define the criteria that the user must meet to qualify for rewards associated with the loyaltyboost offer maximum length 160 characters count integer number of offers returned from the call privacy url url recommended to implement recommended to implement url to adspostx's current end user privacy policy page parsing the response and displaying offers upon a successful response from the fetch perkswall offer's api request, generate offers using the offer fragments provided for each returned offer remember to implement impression tracking using the pixel attribute for each displayed offer a successful get call to the pixel url is required to successfully record delivery on the adspostx dashboard this allows adspostx to accurately calculate and present performance statistics such as click through rate (ctr), ecpm and other metrics use performance data to optimize ad delivery on future traffic generate and display first offer using the fragments of the offer returned in the response implement the impression beacon url ( pixel ) for the first offer r ender the second offer (and implement the impression beacon url for this offer ) continue through all the other offers to construct your perkswall experience using creatives when retrieving offer , we provide a creatives attribute with each returned offer , which lists creatives available for use in your offers included with each creative is an is primary boolean attribute you can use any of the creatives available depending on the platform you are rendering or default to the primary creative if you are unsure the moments api also supports on the fly image transformations by simply adding the query parameter "width=xxx" into the image url (replace xxx with a suitable integer value for width, depending on the device resolution) the query parameters "height=xxx" or "?aspect ratio=x\ y" are also available as on the fly image processing directives on images we also provide an aspect ratio attribute for each creative which can be helpful in selecting an image for the offer an aspect ratio with a value of 1 = square image a value < 1 signifies generally portrait a value > 1 signifies generally landscape