React Native
This guide explains how to integrate the Moments API into your React Native application. It covers setup, fetching offers, implementing the UI, and tracking user interactions. Follow these steps to integrate MomentScience offers into your app with minimal overhead.
Before diving into the integration process, there are a few preliminary steps you need to take
- Obtain an API key Before you start the integration, you must acquire a unique API key. Follow the instructions provided here to obtain your key.
- Check Version Requirements
- Ensure your project is using React 18.0.0 or higher and React Native 0.73 or higher.
- Verify that all dependencies are compatible with these versions.
- Plan Your Implementation:
- Identify Offer Display Areas: Decide whether offers will appear as part of a screen or as full-screen modal overlays.
- Frequency of Display: Determine if offers should be shown once per session or every time a specific section is accessed.
To enable API communication and device information retrieval, install the following dependencies:
Add the following intent filter to your AndroidManifest.xml to open offer links in an external browser:
The Moments API provides offer data based on query parameters and payload inputs. To retrieve offers, implement a function that calls the Moments API with the necessary parameters.
For complete details on Moments API, refer to the Moments API documentation.
The function below acts as a wrapper for the Moments API, handling query parameters and headers. Once implemented, you can call the fetchData function anywhere in your app to retrieve offer data.
Refer to this complete sample source code for an API call demonstration.
After retrieving the offer data, the next step is to develop the user interface (UI) and integrate event beacons to track user interactions. This section covers:
- Designing the offer display UI
- Implementing navigation between offers
- Tracking user engagement with event beacons
The offer UI can be embedded using an iframe. The following example sets the iframe height to adjust automatically:
This example features a modal, but you can implement any UI format that fits your application.
Build the Offer Container UI
The Offer Container UI is responsible for displaying multiple offers in a sequence. It includes:
- Navigation Buttons: Allow users to move between offers.
- Close Button: Closes the offer container.
- Offer Display Area: Renders the current offer.
This component maintains the state of the current offer and handles user interactions such as button clicks and event beacon tracking.
Define the OfferContainerView Component
The OfferContainerViewcomponent manages the state of offers and user interactions.
Prop | Description |
---|---|
offers | An array of offer objects containing title, description, image, and CTA buttons. |
OnCloseOfferCTA | Callback function triggered when the OfferContainerview is closed. It receives: - currentOfferIndex: Index of the displayed offer. - shouldFirePixel: A boolean indicating whether to call firePixel(). (See Supporting Functions for details.) |
Handle the Close Event
The OnCloseOfferCTAfunction is triggered when:
- The user closes the OfferContainerView.
- The user taps the negative CTA on the last offer.
It sends a request to the URL defined in beacons?.close before closing the view.
For more details on event tracking, refer to the "Supporting Functions" section.
View the full OfferContainerView.js source code on GitHub from here. ο»Ώ
Each individual offer is displayed using the OfferViewcomponent. This component includes an image, title, description, and two CTA buttons.
Define the OfferView Component
Prop | Description |
---|---|
title | The offer title. |
imageURL | The URL of the offer image. |
description | A detailed description of the offer. |
clickURL | The URL to open when either the offer image or the positive CTA is tapped. |
positiveCTA | Text for the positive CTA button. |
onImageCTA | A callback function triggered when the offer image is tapped. This function fetches the clickURL and opens it in an external browser using the openURLfunction. |
onPositiveCTA | A callback function invoked when the positive CTA is tapped. It performs two actions: β’ Opens the URL stored in .click_urlin an external browser. β’ Advances to the next offer by invoking goToNextOffer(). |
negativeCTA | The text label for the negative call-to-action button, |
onNegativeCTA | A callback function executed when the negative CTA is tapped. It sends a request using the URL specified in .beacons?.no_thanks_click and then advances to the next offer by calling goToNextOffer(). |
View the full OfferView.js. source code on GitHub from here. ο»Ώ
When calling our API, it's important to include the User-Agent parameter. Here's how you can retrieve its value for the device using thereact-native-device-info package.
To ensure effective tracking and offer management, the API requires a unique identifier for each user. This identifier is passed as the adpx_fpparameter in the Fetch Offers API request.
MomentScience uses adpx_fpto:
- Control the frequency of offer displays for a user.
- Prevent the same offer from appearing again when a user opts out.
The following function retrieves a device-specific unique identifier using the react-native-device-info package:
- For iOS: Uses getUniqueId(), which returns the Identifier for Vendors (IDFV).
- For Android: Uses getAndroidId(), which retrieves the Android ID.
- For other platforms: Returns "unknown" as a fallback.
This unique ID should be passed as the adpx_fp parameter in the Fetch Offers API request to maintain consistent tracking across sessions.
- Purpose: The firePixel function is responsible for sending tracking requests (pixels) under specific conditions to log user interactions. It sends HTTP requests to predefined beacon URLs when:
- OfferContainerView is closed: Sends a request to beacons.close.
- An offer is displayed: Sends a request to .pixel
- Negative CTA is tapped: Sends a request to beacons.no_thanks_click.
- Purpose: Opens a specified URL in an external browser. This is used when the user taps the offer image or a positive CTA.
- Usage: Call openURL(url) with the target URL. The function first checks if the URL can be opened and then launches it in the deviceβs browser.
Once the user closes the Offer Container UI, the next time you want to show offers, you need to reload them. You can reset the offer state and fetch new data to reload offers.
Explore the MomentScience Example on GitHub. Download and run it locally to see it in action.
π’ If you're running into any issues while going through the integration process, feel free to contact us at [email protected].