--- title: Serving MomentPerks in Mobile Apps slug: serving-momentperks-in-mobile-apps icon: 📲 docTags: createdAt: 2025-07-25T19:52:30.925Z --- # Overview This playbook provides a high-level guide for implementing Moments in your mobile application using the MomentScience [MomentPerks API](docId\:zpOL4DX0Bohl2AOoyZrLQ). ## 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 [MomentPerks API](docId\:zpOL4DX0Bohl2AOoyZrLQ) , 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 [MomentPerks API](docId\:zpOL4DX0Bohl2AOoyZrLQ) . 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:** 1. **Log In**: Sign in to your MomentScience account. 2. **Go to Profile**: Navigate to the **Profile** section in the dashboard. 3. **Generate API Key**: Click the **Generate API Key** button. 4. **Name the Key**: Enter a descriptive name (for example, "Test API Key" or "Production API Key"). 5. **Set Scopes**: Select the appropriate access scopes. Make sure the **Ads/Offers** scope is selected. 6. **Generate**: Click **Generate** to create the API key. Include this key in the `Authorization`header of all Moments API requests. :::hint{type="warning"} 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). ::: :::CtaButton{label="Learn more about how to obtain your API key." docId="CD0hKzWhbqxqwKYfO_cZG" openInNewTab="true"} ::: ## 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. :::Iframe{iframeHeight="0" code=""} ::: :::CtaButton{label="Learn more about MomentPerks API" docId="zpOL4DX0Bohl2AOoyZrLQ" openInNewTab="true"} ::: ## 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. :::hint{type="success"} For more information about each parameter, please refer to the [MomentPerks API](docId\:zpOL4DX0Bohl2AOoyZrLQ) ::: ### 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: :::hint{type="success"} For a full explanation of all response fields and display guidance, refer to the [Offer Anatomy Reference](docId\:CcqwdfiSARHryXivsNF38) ::: | **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. | :::hint{type="info"} 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 [MomentPerks API](docId\:zpOL4DX0Bohl2AOoyZrLQ) 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 [MomentPerks Integration Checklist](docId\:X6WKO1QqSk1o53zhCku_Z) . - `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. :::hint{type="success"} For more information about the required parameters when calling the Moments API, please refer to the [MomentPerks Integration Checklist](docId\:X6WKO1QqSk1o53zhCku_Z) ::: *** # 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:** 1. Go to Settings -> [Configuration](https://app.momentscience.com/account/settings/behavior/). 2. Locate the "Number of Offers" setting. 3. Set your desired value. 4. 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). :::CtaButton{label="Learn more about Handling Postback Events" docId="U6s7GlbRWPW4hb3zP9xJm" openInNewTab="true"} ::: *** 📢 If you're running into any issues while going through the integration process, feel free to contact us at [help@momentscience.com](mailto\:help@Momentscience.com)