Serving MomentPerks in Mobile Apps
๏ปฟ
Overview
This playbook provides a high-level guide for implementing Moments in your mobile application using the MomentScience Moments API๏ปฟ.
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๏ปฟ, 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๏ปฟ. 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 Authorizationheader 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 documentation.๏ปฟ
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 Reference.๏ปฟ
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๏ปฟ 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 GETrequest to offers[].pixel when the offer is displayed.
- (If available) Trigger Advertiser Beacon: Fire a GETrequest 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 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 API 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@momentscience.com๏ปฟ