Moments API Android Integration Playbook

overview the moments api enables you to present personalized offers to users within your android application this guide outlines the integration process, from initial setup to offer display and event tracking, to help you deliver engaging user experiences with minimal development effort prerequisites before you begin, ensure the following requirements are met api key obtain a unique api key for your account get your api key here https //docs momentscience com/apis documentation#xbu86 android version target android sdk 26 or higher add permission add internet permission in your androidmanifest xml \<uses permission android\ name="android permission internet" /> integration steps 1\ fetch offers the moments api provides offer data based on query parameters and payload inputs use below function to call the api and retrieve offers for your users fun fetchoffers( apikey string, loyaltyboost string = "0", creative string = "0", isdevelopment boolean = false, payload map\<string, string> = emptymap() ) { val baseurl = "https //api adspostx com/native/v4/offers json" val fullurl = "$baseurl?api key=$apikey\&loyaltyboost=$loyaltyboost\&creative=$creative" val url = url(fullurl) val connection = url openconnection() as httpurlconnection try { connection requestmethod = "post" connection setrequestproperty("content type", "application/json") connection dooutput = true // flatten payload and add dev flag if needed val bodyjson = jsonobject(payload) if (isdevelopment) { bodyjson put("dev", true) } outputstreamwriter(connection outputstream) use { writer > writer write(bodyjson tostring()) writer flush() } val responsecode = connection responsecode val responsemessage = connection inputstream bufferedreader() use { it readtext() } println("response code $responsecode") println("response $responsemessage") } catch (e exception) { e printstacktrace() } finally { connection disconnect() } } implementation note use the fetchoffers function to retrieve offers from the moments api you can adapt this logic for retrofit or other http clients as needed request parameters parameter type description required default api key string the api key associated with your momentscience account yes – loyaltyboost string sets the loyalty boost level for the offers accepts "0", "1", or "2" no "0" creative string determines the creative mode for the offers accepts "0" or "1" no "0" dev string enables development mode set to "1" for testing environments no – payload map\<string, string> pass any extra data required for offer targeting or tracking as a map of string key value pairs no – response a successful response returns a json object containing the available offers and related metadata for detailed response structure and field descriptions, refer to the official moments api documentation https //docs momentscience com/moments api refer offersapi kt and offersresponse kt for demo app implementation 2\ build the offer ui after retrieving offer data, design the user interface to display offers and enable user navigation offer container ui the offer container ui displays multiple offers in sequence and manages user navigation, loading, and error states below is a concise example using a composable function offercontainerview( offers = apioffers, styles = apistyles, currentofferindex = 0, onclose = { viewmodel dismissoffers() }, onpositiveclick = { offer > viewmodel handlepositiveaction(offer) }, onnegativeclick = { offer > viewmodel handlenegativeaction(offer) }, onpreviousclick = { viewmodel showpreviousoffer() }, onnextclick = { viewmodel shownextoffer() } ) this implementation demonstrates how to handle loading and error states display offers in a modal or embedded container track user actions (close, accept, decline) navigate between multiple offers for more details, see offercontainerview\ kt and offersviewmodel kt individual offer ui each offer is displayed using the offerview composable, which presents offer details such as title, image, description, and call to action buttons with dynamic styling the business logic and state for the offer presentation are managed by the offersviewmodel class, following the mvvm pattern example usage offerview( offer = offer( title = "special offer", description = "limited time discount!", image = "https //example com/image jpg", ctayes = "claim now", ctano = "maybe later" ), styles = apistyles, onpositiveclick = { handlepositiveaction() }, onnegativeclick = { handlenegativeaction() } ) for advanced usage and dynamic styling, refer to offerview\ kt 3\ track user interactions to monitor user engagement, fire event beacons at key interaction points the sendgetrequest function is responsible for sending these tracking requests example sending beacon requests import java net httpurlconnection import java net url fun sendgetrequest(fullurl string) { val url = url(fullurl) val connection = url openconnection() as httpurlconnection try { connection requestmethod = "get" val response = connection inputstream bufferedreader() use { it readtext() } println("response body $response") } catch (e exception) { e printstacktrace() } finally { connection disconnect() } } you can use this function to send https requests to predefined beacon urls when the offer container is closed ( beacons close ) an offer is displayed ( pixel ) the negative cta is tapped ( beacons no thanks click ) firing close beacon when a user closes the offer container fun onclose(offer offer) { offer beacons? close? let { url > sendgetrequest(url) } // existing code for closing event } firing “no thanks” beacon when a user taps the negative cta fun onnegativeclick(offer offer) { offer beacons? nothanksclick? let { url > sendgetrequest(url) } // existing code for navigation or closing } firing pixel events when an offer is displayed fun onofferdisplayed(offer offer) { offer pixel? let { url > sendgetrequest(url) } } reference for more details, see offersviewmodel kt explore the momentscience example on github to see a working demo next steps we recommend that you go through the moments api implementation checklist to verify your integration completing this checklist ensures that all best practices and requirements are met for a successful moments api deployment 📢 if you're running into any issues while going through the integration process, feel free to contact us at help\@momentscience com