MomentPerks API

overview the momentperks api offers a flexible, programmatic interface for integrating momentscience offers into your application or website it is compatible with any environment capable of making http requests and returns structured json responses for easy integration use cases display personalized offers at checkout to increase average order value present special deals during user idle time to boost engagement show targeted promotions after specific user actions (e g , article completion) monetize natural breaks in user experience with relevant offers integration architecture proxy connect (recommended) in this approach, your application or website communicates with your own proxy server the proxy server then securely forwards requests and responses to and from the momentperks api this architecture allows you to add custom business logic, logging, or caching at the proxy layer secure api credentials and control outbound traffic maintain better observability of requests direct connect in a direct integration, your app or website makes requests directly to the momentperks api to retrieve and render offers this method is simple to implement suitable for rapid prototyping or low risk environments however, it may expose api keys and is less suitable for production use without additional security measures try it out try our moments api live now and experience the response in real time! test it below to see how it works and explore the data it returns authentication all requests must include a valid api key with the "ads/offers" permission this key authorizes your application to retrieve and serve momentscience offers securely obtaining an api key log in to the https //app momentscience com navigate to https //app momentscience com/account/profile settings generate a new api key with the "ads/offers" permission for more details, see docid\ t1d2y6emug0lh0t bi6ao fetch offers endpoint method post url https //api adspostx com/native/v2/offers json request header true 170,100,100left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type query parameters true 127,68,89,100left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type body parameters true 120,66,129,100left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type the adpx fp parameter is strongly recommended for all integrations it is a persistent, anonymous user identifier that enables per user frequency capping prevents re serving offers after opt out improves overall offer targeting and performance this value should be a consistent, non pii, alphanumeric string generated for each user request example curl request example curl request post \\ \ url 'https //api adspostx com/native/v2/offers json?api key=replace with your api key' \\ \ header 'content type application/json' \\ \ data '{ "placement" "checkout confirmation page", // required identifier for where the offer is shown (e g , page, screen) "ua" "mozilla/5 0 (linux; android 10 )", // recommended end user user agent string for targeting "ip" "203 0 113 45", // recommended ip address of the end user for geo and device targeting "adpx fp" "1234abcd 5678 efgh 9101 ijklmnopqrst", // strongly recommended unique, persistent, non pii user fingerprint "pub user id" "1234abcd 5678 efgh 9101 ijklmnopqrst", // required for pwaas unique, anonymous user id consistent across sessions "creative" "1", // optional set to '1' to return offers with at least one creative "loyaltyboost" "1", // optional '1' to include loyaltyboost offers, '2' for loyaltyboost only "dev" "1" // optional '1' to return test offers (no tracking, ignores geo) }' javascript request example const fetch = require('node fetch'); // use native fetch in modern environments const url = 'https //api adspostx com/native/v2/offers json?api key=replace with your api key'; const headers = { 'content type' 'application/json' }; const body = { placement 'checkout confirmation page', // required ua navigator useragent, // recommended (use real user agent if proxying) ip '203 0 113 45', // recommended (if known) adpx fp '1234abcd 5678 efgh 9101 ijklmnopqrst', // strongly recommended pub user id '1234abcd 5678 efgh 9101 ijklmnopqrst', // required for pwaas creative '1', // optional loyaltyboost '1', // optional dev '1' // optional (test mode) }; fetch(url, { method 'post', headers, body json stringify(body) }) then(res => res json()) then(data => console log('offers ', data)) catch(err => console error('error fetching offers ', err)); kotlin request example import okhttp3 import org json jsonobject import java io ioexception val client = okhttpclient() val json = jsonobject() apply { put("placement", "checkout confirmation page") put("ua", "mozilla/5 0 (linux; android 11 )") put("ip", "203 0 113 45") put("adpx fp", "1234abcd 5678 efgh 9101 ijklmnopqrst") put("pub user id", "1234abcd 5678 efgh 9101 ijklmnopqrst") put("creative", "1") put("loyaltyboost", "1") put("dev", "1") } val body = requestbody create(mediatype parse("application/json"), json tostring()) val request = request builder() url("https //api adspostx com/native/v2/offers json?api key=replace with your api key") post(body) addheader("content type", "application/json") build() client newcall(request) enqueue(object callback { override fun onfailure(call call, e ioexception) { println("error ${e message}") } override fun onresponse(call call, response response) { response body()? string()? let { println("offers $it") } } }) swift request example import foundation let url = url(string "https //api adspostx com/native/v2/offers json?api key=replace with your api key")! var request = urlrequest(url url) request httpmethod = "post" request setvalue("application/json", forhttpheaderfield "content type") let body \[string any] = \[ "placement" "checkout confirmation page", "ua" "mozilla/5 0 (iphone; cpu iphone os 15 0 like mac os x)", "ip" "203 0 113 45", "adpx fp" "1234abcd 5678 efgh 9101 ijklmnopqrst", "pub user id" "1234abcd 5678 efgh 9101 ijklmnopqrst", "creative" "1", "loyaltyboost" "1", "dev" "1" ] request httpbody = try? jsonserialization data(withjsonobject body) let task = urlsession shared datatask(with request) { data, response, error in guard let data = data, error == nil else { print("error ", error ?? "unknown error") return } if let json = try? jsonserialization jsonobject(with data) { print("offers ", json) } } task resume() api response a successful response from the momentperks api returns a data object containing one or more offers each offer object includes all the metadata required to render and track a momentscience offer within your application true 128,100,100left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type you can easily manage how many offers are returned in the response from your dashboard navigate to the https //app momentscience com/account/settings/behavior locate the "number of offers" setting set your desired number of offers to be returned click "save configuration" to apply the changes sample response { "data" { "session id" "abc123 def456 ghi789", "offers" \[ { "id" 12345, "campaign id" 67890, "advertiser name" "premium sports store", "title" "get 25% off athletic wear + free shipping", "description" "save on top brand athletic wear, running shoes, and gym equipment free shipping on orders over $50 ", "short headline" "25% off athletic wear", "short description" "save on top brands + free shipping over $50", "mini text" "excludes sale items valid through 12/31/2024 ", "click url" "https //offers momentscience com/click/abc123", "cta yes" "shop now", "cta no" "no thanks", "image" "https //cdn momentscience com/creatives/sports banner jpg", "qr code img" "data\ image/png;base64,ivborw0kggoaaaansuheugaa ", "creatives" \[ { "id" 1001, "url" "https //cdn momentscience com/creatives/sports square jpg", "height" 400, "width" 400, "type" "jpg", "is primary" true, "aspect ratio" 1 0 }, { "id" 1002, "url" "https //cdn momentscience com/creatives/sports banner jpg", "height" 200, "width" 800, "type" "jpg", "is primary" false, "aspect ratio" 4 0 } ], "terms and conditions" "\<p>\<strong>offer valid through december 31, 2024 \</strong>\</p>\<ul>\<li>cannot be combined with other offers\</li>\<li>excludes sale items\</li>\<li>free shipping on orders $50+\</li>\</ul>", "pixel" "https //tracking momentscience com/impression/abc123", "adv pixel url" "https //advertiser com/track?id=xyz789", "beacons" { "close" "https //tracking momentscience com/close/abc123", "no thanks click" "https //tracking momentscience com/decline/abc123" }, "offerwall enabled" true, "perkswallet enabled" true, "save for later url" "https //api momentscience com/wallet/save", "offerwall url" "https //offers momentscience com/wall/user123", "is loyaltyboost" true, "loyaltyboost requirements" "complete purchase to earn 500 bonus points" "tags" \["security", "vpn", "privacy"], } ], "count" 1, "privacy url" "https //momentscience com/privacy", "styles" { "primary color" "#007bff", "background color" "#ffffff", "text color" "#333333" // more styles parameters }, "settings" { "max display time" 30, "auto close" false // more settings parameters } } } offer object properties each offer in the offers array contains the following properties identification & metadata true 196,73,100 unhandled content type unhandled content type unhandled content type unhandled content type unhandled content type unhandled content type unhandled content type unhandled content type unhandled content type unhandled content type unhandled content type unhandled content type offer text content true 235,67,100left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type use title and description for desktop/tablet layouts use short headline and short description for mobile/compact layouts reserve mini text for essential legal disclaimers only call to action elements true 173,78,100left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type images & creatives assets true 197,100,100left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type creatives object structure true 288,100,100 unhandled content type unhandled content type unhandled content type unhandled content type unhandled content type unhandled content type unhandled content type unhandled content type unhandled content type unhandled content type unhandled content type unhandled content type unhandled content type unhandled content type unhandled content type unhandled content type unhandled content type unhandled content type unhandled content type unhandled content type unhandled content type unhandled content type unhandled content type unhandled content type terms & conditions true 166,100,100 unhandled content type unhandled content type unhandled content type unhandled content type unhandled content type unhandled content type expected html tags (terms and conditions) , , , , , , , , , , , , , , , , do not display full terms by default within the initial view of the offer provide a clear, user friendly way to access the terms using one of the following ui mechanisms expanding or accordion style reveal flip card interaction modal or lightbox popup tooltip on hover link to a separate detail view tracking & analytics true 163,100,100left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type interaction beacons true 220,220,221 unhandled content type unhandled content type unhandled content type unhandled content type unhandled content type unhandled content type unhandled content type unhandled content type unhandled content type feature flags true 220,220,221left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type loyaltyboost attributes true 220,220,221 unhandled content type unhandled content type unhandled content type unhandled content type unhandled content type unhandled content type unhandled content type unhandled content type unhandled content type parsing the response and displaying offers once you receive a successful response from the momentperks endpoint, you can begin rendering offers using the structured data provided in the response each offer object contains all the necessary fragments (text, images, tracking urls, etc ) to generate and present an interactive, trackable offer unit in your app or website display sequence and tracking flow to ensure accurate performance tracking and seamless offer display, implement the following flow render the first offer using its content fragments ( title , description , image , click url , etc ) fire the impression beacon url ( pixel ) as soon as the first offer is visibly displayed to the user a successful get request to this url is required for momentscience to register the impression handle user interaction if the user clicks the positive cta, redirect them to the click url if the user clicks the negative cta, fire the no thanks click url from the beacons object render the next offer in sequence, and again display its visual and text content fire its corresponding pixel beacon for impression tracking continue this process until all offers are exhausted or the user exits the offer flow why impression beacons matter accurate impression tracking via the pixel url is critical because it enables momentscience to measure key performance metrics such as click through rate (ctr) effective cpm (ecpm) conversion rate optimize offer relevance and ranking based on real time engagement data maintain accurate billing and reporting data for both advertisers and publishers implementing event beacons beyond impression tracking, momentperks also supports tracking additional user interactions through the beacons object in each offer true 330,331 unhandled content type unhandled content type unhandled content type unhandled content type unhandled content type unhandled content type these urls should be triggered with simple get requests at the appropriate moments beacons help measure user intent and drop off behavior on the fly image resizing to optimize for different screen sizes and resolutions, you can dynamically resize image assets using query parameters ?width=xxx resize width to xxx pixels ?height=yyy resize height to yyy pixels ?aspect ratio=x\ y override aspect ratio example https //cdn momentscience com/creative jpg?width=300 these transformations are handled server side and ensure that images remain responsive across devices integration checklist we recommend you go through our docid\ nzqqzpx9czbn mzqypdxr to ensure that you have not missed any integration steps this will help you gain the full advantage of the features provided by momentscience if you're encountering problems rendering offers, triggering beacons, or receiving data, reach out to mailto\ help\@momentscience com