Moments
Mobile

React Native

25min

Overview

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.

Prerequisites

Before diving into the integration process, there are a few preliminary steps you need to take

  1. 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.
  2. Check Version Requirements
    1. Ensure your project is using React 18.0.0 or higher and React Native 0.73 or higher.
    2. Verify that all dependencies are compatible with these versions.
  3. Plan Your Implementation:
    1. Identify Offer Display Areas: Decide whether offers will appear as part of a screen or as full-screen modal overlays.
    2. Frequency of Display: Determine if offers should be shown once per session or every time a specific section is accessed.

Getting Started

Install Dependency Packages

To enable API communication and device information retrieval, install the following dependencies:

Installation Command
ο»Ώ

Implement Android Intent Filter

Add the following intent filter to your AndroidManifest.xml to open offer links in an external browser:

AndroidManifest.xml
ο»Ώ

Fetch Offers

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.

Fetch and Process Offers Data
Moments API Wrapper Function
ο»Ώ

Refer to this complete sample source code for an API call demonstration.

Implement UI and Event Beacons

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
ο»Ώ

Embed Offer UI

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.

Handling the Close Event Code Example
ο»Ώ

View the full OfferContainerView.js source code on GitHub from here. ο»Ώ

Implement Offer UI

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().

Handling Offer Interactions Code
ο»Ώ

View the full OfferView.js. source code on GitHub from here. ο»Ώ

Supporting Functions

Device Information Functions

Get Device User-Agent

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.

Fetching 'User-Agent' Parameter
ο»Ώ

Generating User Identifiers

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:

Generating User Identifiers
ο»Ώ
  • 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.

Event Tracking Functions

firePixel

  • 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.
firePixel Function
ο»Ώ

openURL

  • 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.
openURL Function
ο»Ώ

Reloading Offers

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.

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].

Updated 25 Feb 2025
Did this page help you?