Android – MomentPerks Prefetch Integration Guide

overview this guide walks you through integrating the momentscience moments solution into your android app using kotlin and jetpack compose the sdk enables you to preload and display personalized offers during key checkout moments to drive revenue and user engagement momentscience offers two integration modes to suit your technical preferences integration modes sdk prefetch mode in sdk prefetch mode, the sdk handles offer fetching internally by initializing a hidden 0×0 webview in advance this allows offers to be prefetched and cached before the user reaches the offer display screen (e g checkout screen) as a result, offers appear instantly during checkout without requiring additional network requests simplest integration path, minimal setup required no need to manage https requests manually api prefetch mode this mode gives your app full control over when and how offers are fetched you initiate a native https request using your own logic and pass the response into the sdk at checkout time greater control over timing and payload enables server side optimizations and logging in both modes, offers are rendered in a webview at the checkout screen because offers are preloaded before checkout, the user experience remains fast and frictionless, even when no offers are found if no offers are returned, you can choose to skip showing the offer display part altogether check out the https //github com/adspostx/examples/tree/main/android native/mssdkdemoapp android to see the complete implementation, including offer fetching, webview rendering, event handling, and external link support requirements to integrate the momentscience sdk into your android app, ensure the following prerequisites are met a valid momentscience sdk id , which you can https //docs momentscience com/getting your sdk id environment kotlin version 1 6 0 or higher minimum android sdk version 26 target android sdk version 35 setup instructions step 1 add dependencies to enable the momentscience sdk in your android app, you'll need to add html assets copy the required html templates into your project these files are used by the sdk to render the offers in a webview\ you can place them in assets/templates folder required files adpx template html https //github com/adspostx/examples/blob/main/android native/mssdkdemoapp android/app/src/main/assets/templates/adpx template html checkout template html https //github com/adspostx/examples/blob/main/android native/mssdkdemoapp android/app/src/main/assets/templates/checkout template html add dependencies open your app/build gradle kts and add the following build gradle kts dependencies { // enables webview support for rendering the sdk implementation("androidx webkit\ webkit 1 6 0") // used for native api requests in api prefetch mode implementation("com squareup okhttp3\ okhttp 4 10 0") // used for parsing json offer payloads implementation("com google code gson\ gson 2 10") // optional used for async image loading implementation("io coil kt\ coil compose 2 5 0") } what these do library purpose androidx webkit enables webview rendering for the sdk okhttp3 required for making http requests in api prefetch mode gson parses json responses into kotlin data classes coil compose (optional) loads creative assets like logos and banners asynchronously add internet permission include the following permission in your androidmanifest xml , outside the \<application> tag \<uses permission android\ name="android permission internet" /> this allows the sdk to fetch offers and tracking beacons over the network step 2 prefetch offers (sdk or api) momentscience offers two modes for prefetching offers before rendering them on your ui sdk prefetch uses a hidden 0×0 webview to silently fetch and cache offers before checkout api prefetch uses a native api call to fetch offers, which are then injected into the sdk display template in both modes, you can skip showing the checkout screen if no offers are found option 1 sdk prefetch in this approach, a hidden webview preloads the sdk when offers are available, the sdk triggers an ads found callback event it’s the lightest touch integration, ideal when you want minimal native logic see https //github com/adspostx/examples/blob/main/android native/mssdkdemoapp android/app/src/main/java/com/momentscience/apiwebdemoapp/ui/offersview\ kt in the demo app for working implementation add javascript interface for sdk events on a screen that runs before the offer display screen (e g checkout screen), insert a hidden 0×0 webview to initiate sdk prefetching make sure to enable javascript enable dom storage enable js native communication to receive callbacks like ads found from the sdk, implement a javascriptinterface and attach it to the webview adpxjavascriptinterface // callback type typealias adpxcallbackhandler = (event string, payload string) > unit // javascript interface to receive events from the sdk class adpxjavascriptinterface( private val callbackhandler adpxcallbackhandler? = null ) { @javascriptinterface fun adpxcallback(event string, payload string) { log d("adpxjsinterface", "event $event, payload $payload") callbackhandler? invoke(event, payload) } } // attach to webview webview\ addjavascriptinterface( adpxjavascriptinterface { event, payload > viewmodel handleadpxcallback(event, payload) }, "android" ) handleadpxcallback private val offercount = mutablestateflow(0) val offercount stateflow\<int> = offercount asstateflow() private val showcheckout = mutablestateflow(false) val showcheckout stateflow\<boolean> = showcheckout asstateflow() private val jsonresponse = mutablestateflow\<jsonelement?>(null) val jsonresponse stateflow\<jsonelement?> = jsonresponse asstateflow() fun handleadpxcallback(event string, payload string) { when (event) { "ads found" > handleadsfound(payload) } } private fun handleadsfound(payload string) { try { val jsonobject = jsonobject(payload) if (jsonobject has("response")) { val responsestring = jsonobject get("response") tostring() val jsonelement = jsonparser parsestring(responsestring) // only set json response if this is from web prefetch if ( prefetchmode value == prefetchmode web) { setjsonresponse(jsonelement) } try { val dataobject = jsonelement asjsonobject get("data")? asjsonobject if (dataobject != null && !dataobject isjsonnull) { val offersarray = dataobject get("offers")? asjsonarray if (offersarray != null && !offersarray isjsonnull) { val count = offersarray size() updateofferscount(count) setshowcheckout(true) log d("adpxcallback", "found $count offers") } } } catch (e exception) { log e("adpxcallback", "error parsing offers from response", e) } log d("adpxcallback", "successfully updated viewmodel with response") } else { log e("adpxcallback", "payload does not contain 'response' key") } } catch (e exception) { log e("adpxcallback", "error parsing ads found payload", e) } } fun updateofferscount(count int) { offercount value = count } load prefetch template with user data load adpx template html from your assets and inject runtime values like sdkid , adpxuser , and sdk cdn url fun generate( sdkid string, context context, payload map\<string, string>? = null ) string { requirenotnull(context) { "context must not be null" } // load html template from assets val templatecontent = readassetfile(context, "templates/adpx template html") // create payload as json val gson = gson() val userpayloadjson = payload? let { gson tojson(it) } ? "{}" // replace placeholders in html return templatecontent replace("%%sdk id%%", sdkid) replace("%%sdk cdn url%%", appconfig sdk cdn url) replace("window\ adpxuser = {};", "window\ adpxuser = $userpayloadjson;") } createpayload private fun createpayload() map\<string, string> { return mapof( "adpx fp" to "\<unique value>", "pub user id" to "\<unique value>", "ua" to "\<user agent value>", "themeid" to "demo", // pass valid themeid here "placement" to "checkout" ) } see https //github com/adspostx/examples/blob/main/android native/mssdkdemoapp android/app/src/main/java/com/momentscience/apiwebdemoapp/templates/adpxhtmltemplate kt , https //github com/adspostx/examples/blob/main/android native/mssdkdemoapp android/app/src/main/java/com/momentscience/apiwebdemoapp/viewmodels/offersviewmodel kt and https //github com/adspostx/examples/blob/main/android native/mssdkdemoapp android/app/src/main/assets/templates/adpx template html in the demo app for more details option 2 api prefetch mode in this mode, your app fetches offers directly from the moments api using a native http post request the fetched response is then passed into the momentscience sdk for rendering at checkout for complete details on momentperks api, refer to the docid\ zpol4dx0bohl2aooyzrlq send a post request to the moments api moments api endpoint post https //api adspostx com/native/v4/offers json build the request parameters include the following api key as a query parameter a user payload in the request body custom user agent in the request headers validate optional parameters (if used) loyaltyboost must be " 0 ", " 1 ", or " 2 " creative must be " 0 " or " 1 " prepare and send the request use the following example code to construct and send the request fetchoffers override suspend fun fetchoffers( sdkid string, payload map\<string, string>? = null, loyaltyboost string?, creative string?, campaignid string? = null, isdevelopment boolean = false ) jsonelement = withcontext(dispatchers io) { try { validateparameters(loyaltyboost, creative) val urlbuilder = stringbuilder(baseurl) apply { append("?api key=$sdkid") loyaltyboost? let { append("\&loyaltyboost=$it") } creative? let { append("\&creative=$it") } campaignid? let { append("\&campaignid=$it") } } val requestjson = jsonobject() apply { payload? foreach { (key, value) > addproperty(key, value) } if (isdevelopment) addproperty("dev", "1") } val jsonbody = gson tojson(requestjson) val requestbody = jsonbody torequestbody("application/json" tomediatype()) val useragent = payload? get("ua")? takeif { it isnotblank() } ? useragentutil getuseragent() val request = request builder() url(urlbuilder tostring()) post(requestbody) header("user agent", useragent) build() val response = client newcall(request) execute() if (!response issuccessful) { val errorbody = response body? string() log e(tag, "error response $errorbody") throw networkerror servererror("server returned ${response code} $errorbody") } val responsebody = response body? string() ? throw networkerror servererror("empty response body") jsonparser parsestring(responsebody) } catch (e exception) { log e(tag, "network error", e) throw when (e) { is networkerror > e is ioexception > networkerror servererror(e message ? "unknown server error") else > networkerror decodingerror(e message ? "unknown error") } } } fetchoffers usage private val jsonresponse = mutablestateflow\<jsonelement?>(null) val jsonresponse stateflow\<jsonelement?> = jsonresponse asstateflow() val response = networkservice fetchoffers( sdkid = sdkid, payload = payload, isdevelopment = true ) createpayload private fun createpayload() map\<string, string> { return mapof( "adpx fp" to "\<unique value>", "pub user id" to "\<unique value>", "ua" to "\<user agent value>", "themeid" to "demo", // pass a valid themeid here "placement" to "checkout" ) } see https //github com/adspostx/examples/blob/main/android native/mssdkdemoapp android/app/src/main/java/com/momentscience/apiwebdemoapp/viewmodels/offersviewmodel kt and https //github com/adspostx/examples/blob/main/android native/mssdkdemoapp android/app/src/main/java/com/momentscience/apiwebdemoapp/services/networkserviceimpl kt in the demo app for more details step 3 show offers in fullscreen webview once the ads found callback confirms that offers are available, you can render them using a full screen webview on your checkout screen use the https //github com/adspostx/examples/blob/main/android native/mssdkdemoapp android/app/src/main/java/com/momentscience/apiwebdemoapp/ui/checkoutview\ kt composable pass the necessary parameters to the checkoutview component this loads the offer experience using a dynamic html template ( checkout template html) checkoutview( sdkid = sdkid, jsonresponse = jsonresponse, isfromapiprefetch = isfromapiprefetch, // // you may not need this parameter as you are going to use only one of the approach offercount = offercount, // optional, require only if you want to show no of offers in ui payload = payload, onbackpressed = { navcontroller popbackstack() } // handle back navigation ) html generation logic the offer experience is rendered by reading the checkout template html file, replacing predefined placeholders with actual offer data, and then loading the final html into the webview use the provided utility method to perform placeholder replacement and generate the complete html content for display fun generate( sdkid string, offerscount int, jsonresponse jsonelement?, isfromapiprefetch boolean = false, context context, payload map\<string, string>? = null ) string { requirenotnull(context) { "context must not be null to load html from assets" } val templatecontent = readassetfile(context, "templates/checkout template html") val autoloadconfig = if (isfromapiprefetch) { "autoload false" } else { "prefetch true, autoload true" } val userpayloadjson = payload? let { gson() tojson(it) } ? "{}" val responsehandling = if (isfromapiprefetch) { """ try { const responsedata = ${jsonresponse? tostring() ? "{}"}; if (responsedata && typeof responsedata === 'object') { settimeout(() => window\ adpx setapiresponse(responsedata), 100); } } catch (error) { console error('error parsing response ' + error message); } """ trimindent() } else { "console log('adpx initialized successfully');" } return templatecontent replace("%%sdk id%%", sdkid) replace("%%offers count%%", offerscount tostring()) replace("%%autoload config%%", autoloadconfig) replace("%%response handling%%", responsehandling) replace("window\ adpxuser = {};", "window\ adpxuser = $userpayloadjson;") replace("%%sdk cdn url%%", appconfig sdk cdn url) } behavior based on prefetch mode mode behavior sdk prefetch sdk fetches offers automatically from the cdn autoload true api prefetch you inject the pre fetched offer json via window\ adpx setapiresponse() use the same checkoutview regardless of the prefetch mode, only the generated html changes based on isfromapiprefetch refer https //github com/adspostx/examples/blob/main/android native/mssdkdemoapp android/app/src/main/java/com/momentscience/apiwebdemoapp/ui/checkoutview\ kt , https //github com/adspostx/examples/blob/main/android native/mssdkdemoapp android/app/src/main/java/com/momentscience/apiwebdemoapp/viewmodels/checkoutviewmodel kt , https //github com/adspostx/examples/blob/main/android native/mssdkdemoapp android/app/src/main/java/com/momentscience/apiwebdemoapp/templates/checkouthtmltemplate kt , https //github com/adspostx/examples/blob/main/android native/mssdkdemoapp android/app/src/main/assets/templates/checkout template html in the demo app for more details step 4 open clicks in external browser when a user taps on an offer, it’s recommended to open the offer url in the device’s default browser, rather than opening it inside same webview this avoids trapping the user inside the checkout view and ensures a more familiar, secure experience override shouldoverrideurlloading in the screen where offers are rendered (e g , checkoutview), override the webviewclient’s shouldoverrideurlloading() method override fun shouldoverrideurlloading(view webview?, url string?) boolean { url? let { val intent = intent(intent action view, uri parse(it)) context startactivity(intent) return true // url was handled externally } return false // let webview handle it if url is null } best practices use this override to handle external navigation for all outbound links in the sdk validate or sanitize urls if you plan to intercept them for custom redirect logic avoid deep linking back into your app unless you’re explicitly handling that behavior for a working example, see the implementation in https //github com/adspostx/examples/blob/main/android native/mssdkdemoapp android/app/src/main/java/com/momentscience/apiwebdemoapp/ui/checkoutview\ kt conclusion you’ve now successfully integrated the moments solutioninto your android app using kotlin and jetpack compose whether you’re using web sdk prefetch mode or api prefetch mode, your app is now equipped to deliver personalized offers that enhance the user experience and drive conversions 📢 if you're running into any issues while going through the integration process, feel free to contact us at mailto\ help\@momentscience com