Flutter β Moments Prefetch Integration Guide
Overview
This guide explains how to integrate the MomentScience Moments solution into your Flutter application to present personalized offers during the checkout experience.
This guide covers two integration modes, both designed to preload and display offers in a WebView:
- SDK Prefetch Mode
- API Prefetch Mode
Both options enable a high-performing native experience while keeping the integration lightweight and flexible.
Integration Modes
SDK Prefetch Mode
The SDK automatically preloads and caches offers using a 0Γ0 WebView placed in advance of checkout. Offers are displayed instantly when the user reaches the checkout step.
- Easiest integration path
- No need to make manual API calls
API Prefetch Mode
Your app uses a native HTTPS request to fetch offers from the Moments API and passes the response into the SDK during checkout.
- Full control over when and how offers are requested
- Ability to customize the request payload (e.g., user ID, cart value)
In both modes, the offers are rendered inside a WebView on the checkout screen. Offers are preloaded ahead of time, so user experience remains responsive, even when no offers are available. If no offers are returned, your app can skip rendering the offer section.
To see a full implementation, check out the MomentScience Flutter Demo on GitHub which includes examples for offer fetching, event handling, and WebView integration.
Requirements
To integrate the MomentScience SDK into your Flutter app, ensure the following prerequisites are met:
- Environment:
- Flutter: 3.0.0+
- Dart: 2.17.0+
- iOS minimum deployment target: iOS 12
- Android minimum SDK version: API level 21
Integration Steps
Step 1: Add Dependencies
Add HTML Assets
Add the required HTML templates to your project. These files are used by the SDK to render the offer experience in a WebView.
- Create a directory: assets/html/
- Place the following files in the assets/html/ directory:
- Register the asset path in your pubspec.yaml:
Install Dependencies
Update your pubspec.yaml file with the required packages:
dependencies:
http: ^1.1.0 # For making API requests
device_info_plus: ^9.1.0 # For retrieving user-agent information
flutter_inappwebview: ^6.1.5 # For rendering the offers in WebView
url_launcher: ^6.1.10 # For launching URLs externally
flutter_dotenv: ^5.0.2 # For managing environment variables (optional)After adding the dependencies, install them by running the following command from your project root:
flutter pub getAdd Internet Permission
To allow offer content to load, add the following permission in android/app/src/main/AndroidManifest.xmlinside <manifest> but before <application>:
<uses-permission android:name="android.permission.INTERNET" />This is required for the SDK to load offer content in both integration modes.
Step 2: Prefetch Offers (SDK or API)
You can prefetch offers using one of two modes:
- SDK Prefetch: Uses a hidden 0Γ0 WebView to preload offers.
- 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
This method uses a hidden 0Γ0 WebView to preload the Moments SDK in the background. When available offers are detected, the SDK triggers an ads_found event in your app. This is the most lightweight integration method and is ideal when you want to minimize native code involvement.
- Set up the WebView: Place a hidden 0Γ0 WebView on any screen before checkout. Make sure to enable the following WebView settings:
- JavaScript
- DOM storage
- Database support
- Register JavaScript Event Handler: The Web SDK communicates with your app through JavaScript events. You must handle these events in your app to react to SDK events. Use addJavaScriptHandler to listen for Web SDK events, and implement a handler like:
- Load WebView with the Prefetch HTML Template: Use the existing prefetch.html template from your local assets. Inject your SDK ID, SDK CDN URL, and AdpxUser configuration (payload) dynamically, then load the resulting HTML into the WebView.
- Handle ads_found Event: Once the WebView receives the ads_found event, extract the offer count. If offerCount == 0, you can skip rendering the offer UI entirely.
See prefetch_service.dart in the demo app for working implementation.
Option 2: Prefetch with API
This method allows your app to prefetch offers directly from the Moments API and pass them into the Web SDK via script injection.
For complete details on Moments API, refer to the Moments API documentation.
- Send a POSTrequest to the Moments API:
- Build the Request Parameters: Include the following:
- api_keyas 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:
- Save the API Response Locally: Store the JSON response from the API to use it when initializing the SDK
See prefetch_service.dart, network_service.dart and device_utils.dart in the demo app for a complete working implementation of this flow.
Step 3: Show Offers Using Fullscreen WebView
After confirming that offers are available, display them on your checkout screen using a fullscreen WebView. Pass the necessary parameters depending on the prefetch method.
- Navigate to the Checkout Screen: Use Navigator.push() to launch a CheckoutScreenand pass the required values
- Load the Offer Experience: Inside the CheckoutScreen, load the offer experience into the WebView using checkout.html. Follow these steps:
- Replace placeholders like %%SDK_ID%%, %%CONFIG%%, and %%AdpxUser%% with actual values (from the payload or API response).
- Load the final HTML into the WebView.
- Ensure JavaScript, DOM storage, and database settings are enabled in the WebView.
- Use _getAutoLoadConfig() (See example below) to determine whether auto-loading and prefetc should be enabled based on your prefetch method:
- Choose Logic Based on Prefetch Mode: Use different logic depending on whether you're using:
- Prefetch with SDK: Cached offers are automatically shown by the SDK.
- Prefetch with API: You need to pass the saved apiResponse and inject it via JavaScript.
String _getAutoLoadConfig(bool isPrefetchApi) {
if (isPrefetchApi) {
// For API prefetch: Disable auto features since we'll provide the response
return 'autoLoad: false, prefetch: false';
} else {
// For WebSDK prefetch: Enable auto features to use cached data
return 'autoLoad: true, prefetch: true';
}
}
See checkout_service.dart and checkout_screen.dart in the demo app for working implementation.
Step 4: Open Clicks in an External Browser
To ensure that offer clickouts open in the deviceβs default browser (rather than inside the WebView), listen for SDK callback events and handle the URL externally.
- Handle the url_clickedEvent in Your Service: Open external URLs manually and prevent the WebView from navigating to the same URL again.
See checkout_screen.dart in the demo app for working implementation.
Conclusion
Congratulations! You've now completed the integration of the Moments solutioninto your Flutter app.
Whether you're using SDK Prefetch Mode or API Prefetch Mode, your app is now ready to deliver personalized offers directly within the user journey, enhancing monetization while maintaining full control over offer timing and display.
π’ If you're running into any issues while going through the integration process, feel free to contact us at help@momentscience.comο»Ώ