Playbooks
Serving Moments in Mobile Apps
17 min
overview this playbook provides a high level guide for implementing moments in your mobile application using the momentscience moments api docid\ duaxqa4vbbpvihg4cqaac what is a moment? a moment is a contextual experience that presents one or more personalized offers at meaningful points in a user's journey, such as after a purchase, upon completing a task, or during a key interaction these moments help you enhance user engagement with timely, relevant perks drive incremental revenue by surfacing claimable offers maintain full control over how and where offers appear in your app using the moments api docid\ duaxqa4vbbpvihg4cqaac , your app can fetch moments dynamically and render them with your own ui components integration steps the following steps outline the general integration flow for using the moments api docid\ duaxqa4vbbpvihg4cqaac these steps apply to all mobile platforms and should be followed before implementing a platform specific sdk (e g , flutter, ios, android, react native) step 1 create an api key before making api requests, you need to generate an api key from the momentscience dashboard to create an api key log in sign in to your momentscience account go to profile navigate to the profile section in the dashboard generate api key click the generate api key button name the key enter a descriptive name (for example, "test api key" or "production api key") set scopes select the appropriate access scopes make sure the ads/offers scope is selected generate click generate to create the api key include this key in the authorization header of all moments api requests never hardcode your api key directly in your app’s source code or commit it to version control store it securely using platform specific tools like environment variables, encrypted storage, or secrets managers (e g , android keystore, ios keychain, or dotenv for react native) step 2 call the moments api there are two common ways to call the moments api, depending on your app architecture option a direct call from the app make the http request from the client include all required headers option b proxy through your backend send a request from your app to your backend then, have your backend forward the request to the moments api and relay the response to your app 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 step 3 parse the api response the moments api returns a list of eligible offers in the data offers\[] array each offer contains all the data needed to render the unit, handle user interactions, and track performance at a minimum, your integration should extract and use the title, image, cta, click url, impression pixel, and optional beacons for more information about each parameter, please refer to the moments api understanding offer anatomy each offer object in data offers\[] contains reusable fields for rendering offer units (e g , single offer unit or multi offer unit) here's a quick reference to the most important ones for a full explanation of all response fields and display guidance, refer to the offer anatomy docid\ t8o0a 3bctma448n5pyhw field description offers\[] title main headline text use short headline for compact layouts offers\[] description primary offer copy use short description for limited space formats offers\[] image main image url for the offer offers\[] click url url to open when the user taps the positive cta (label from cta yes) offers\[] cta yes label for the primary action (e g , "claim now") offers\[] cta no label for the negative action (e g , "no thanks") offers\[] terms and conditions html formatted terms render as html if present offers\[] pixel impression tracking url fire once when the offer becomes visible offers\[] adv pixel url optional advertiser tracking pixel fire if provided offers\[] beacons close track when the user closes the offer unit offers\[] beacons no thanks click track when the user clicks the "no thanks" button creatives\[] optional array of additional creative assets, including dimensions and types settings offerwall url (optional) url to launch perkswall button label comes from settings offerwall cta you are not limited to a specific layout these fields support custom implementations, feel free to build the ui that best fits your app's experience step 4 trigger impression beacons each offer returned by the moments api docid\ duaxqa4vbbpvihg4cqaac includes impression and interaction tracking urls these must be implemented to ensure proper reporting, advertiser compliance, and offer optimization required actions trigger impression beacon fire a successful get request to offers\[] pixel when the offer is displayed (if available) trigger advertiser beacon fire a get request to offers\[] adv pixel url to satisfy advertiser tracking display terms and conditions render the offers\[] terms and conditions field as html to show offer specific rules if the field is empty, no terms apply additional tracking the following additional beacons and requirements are documented in the moments and perkswall api implementation checklist offers\[] beacons close trigger when the user closes an offer unit offers\[] beacons no thanks click trigger when the user opts out of an offer adpx fp attribute use to identify unique users for frequency control and reward tracking ip and user agent headers required when proxying requests to ensure valid targeting loyaltyboost support special implementation required for rewarded offers, including postbacks, loyalty identifiers, and payout handling for more information about the required parameters when calling the moments api, please refer to the moments and perkswall api implementation checklist further recommendations configure moments settings in the dashboard the number of offers returned in the moments api response can be configured in the momentscience dashboard to configure offer count go to settings > configuration locate the "number of offers" setting set your desired value press save configuration this setting limits how many offers the moments api returns in each response implement postbacks for conversion tracking postbacks let you receive real time notifications when a user converts on an offer these are sent to your designated endpoint and help track performance, optimize targeting, and power loyaltyboost rewards (if applicable) 📢 if you're running into any issues while going through the integration process, feel free to contact us at help\@m omentscience com