@npm_fluentco/adflow-react-native-sdk

Fluent AdFlow Widget SDK for React Native

This detailed guide provides step-by-step instructions for seamlessly integrating the AdFlow experience using the AdFlow React Native SDK in a React Native mobile app.

Getting Started

If you haven't yet connected with a Fluent representative to explore partnership opportunities, reach out at sales@fluentco.com to begin. Once all required contractual agreements are finalized, a unique Partner ID will be assigned to your account.

Integrating the Fluent AdFlow React Native SDK

Seamlessly integrate the Fluent AdFlow SDK into your React Native project to elevate your app’s functionality. Begin by installing the SDK using the following command:

npm install @npm_fluentco/adflow-react-native-sdk

Setting Up for iOS Integration

If your project does not include an ios folder, follow the troubleshooting steps outlined below.

Set Minimum iOS Version

The Fluent AdFlow SDK requires iOS 14.0 or higher. To ensure compatibility:

Open your project's Podfile, typically found in the root of the ios directory.
Verify or update the iOS deployment target to at least version 14.0.

Example update:

platform :ios, '14.0'

This step ensures your project is configured correctly to support the required SDK version.

Install iOS Dependencies

After installing the npm package, navigate to the ios directory and install the iOS dependencies by running:

cd ios && pod install

Note: For Mac M1 architecture issues, use the following commands:

sudo arch -x86_64 gem install ffi
arch -x86_64 pod install

Update Info.plist

Add the following entry to Info.plist to ensure compliance for accessing the Advertising Identifier (IDFA):

<key>NSUserTrackingUsageDescription</key>
<string>This identifier will be used to serve personalized ads based on your activity.</string>

This configuration ensures that the iOS SDK is correctly set up and compliant with privacy requirements.

Configure the SDK for Android

Set Up Repositories

To use the SDK in your Android application, add the AdFlow repository to your build.gradle file:

allprojects {
    repositories {
        mavenCentral()
        google()
        maven {
            url = uri("https://mobile-sdk.adflow-prod.minionplatform.com/android")
        }
    }
}

Add GAID Permission

To collect the Google Advertising ID (GAID), include the following permission in your AndroidManifest.xml file:

<uses-permission android:name="com.google.android.gms.permission.AD_ID" />

This configuration ensures your Android app has the necessary repositories, dependencies, and permissions for the AdFlow SDK.

OPTIONAL (only if plugin autoloading isn’t working)

Update your ReactApplication (typically located in the MainApplication.javaclass file) with the following. This will add the SDK to the Android project within your react-native application.

import com.fluentadflowreactnativesdk.FluentAdFlowWidgetPackage;
@Override
protected List<ReactPackage> getPackages() {
    List<ReactPackage> packages = new PackageList(this).getPackages();
    packages.add(new FluentAdFlowWidgetPackage());
    return packages;
}

SDK Initialization

The Fluent AdFlow React Native SDK provides components that can be integrated directly into your application code.

Importing the Component

Add the following import statement to your code to access the SDK components:

import {  
  FluentAdFlowWidgetView,  
  FluentAdFlowWidget,  
} from '@npm_fluentco/adflow-react-native-sdk';

Initializing the SDK

To initialize the SDK, use the init method, which requires your API key and referer:

FluentAdFlowWidget.init('<your-api-key>', '<your-referer>')
  .then(() => {
    console.log('SDK initialized successfully');
  })
  .catch(([errorCode, message]: [number, string]) => {
    console.error(`SDK initialization failed with code ${errorCode}: ${message}`);
  });

We recommend initializing the SDK during your app's startup process rather than at the point of use.

Displaying the Ad and Passing User Data

To display the ad and pass user data for a personalized experience, use useRef to access the component and pass the necessary parameters:

import React, { useState, useRef } from 'react';
.
.
.
const adRef = useRef(null);
.
.
.
<FluentAdFlowWidgetView
  ref={adRef}
  style={styles.adContainer}
  onAdShow={onAdShowHandler}
/>

Handling Ad Visibility with the optional onAdShow event callback

The onAdShow callback handler is triggered when the ad is shown or hidden. It includes an isAdShown flag to indicate the ad's visibility. You can use this event to control the display of a wrapper view (e.g., an overlay or slide-up drawer) around the FluentAdFlowWidgetView. Here's an example of the handler:

const onAdShowHandler = (isAdShown) => {
  console.log('**** Ad Show Event Triggered ****', isAdShown); // Log the event
};

⚠️ Important Warning: Do Not Use FluentAdFlowWidgetView Inside a Modal

FluentAdFlowWidgetView should not be used inside a Modal component to function properly. The reason is that Modal components in React Native are loaded later in the component lifecycle, which can prevent useRef from referencing the FluentAdFlowWidgetView correctly.

To ensure proper functionality, wrap FluentAdFlowWidgetView inside a regular View container. If you want the ad to appear as an overlay or a popup, you can style this View to behave like a modal or sliding drawer.

Here’s an example of how to implement this:

<View style={[styles.drawer]}>
  <View style={styles.drawerHeader}>
    <Text style={styles.headerText}>Ad Title</Text>
    <TouchableOpacity onPress={togglePopup}>
      <Text style={styles.closeButton}>X</Text>
    </TouchableOpacity>
  </View>

  <FluentAdFlowWidgetView
    ref={adRef}
    style={styles.adContainer}
    onAdShow={onAdShowHandler}
  />
</View>

Sample Styles:

drawer: {
    position: 'absolute',
    left: 0,
    right: 0,
    bottom: 0,
    backgroundColor: '#ffffff', // Solid white background
    padding: 0,
    borderTopLeftRadius: 0, // More prominent corner rounding
    borderTopRightRadius: 0,
    shadowColor: '#000',
    shadowOffset: { width: 0, height: -2 },
    shadowOpacity: 0.2,
    shadowRadius: 5,
    elevation: 5, // Shadow for Android
    border: 1,
    borderColor: `#ff0000`,
  },
  drawerHeader: {
    flexDirection: 'row',
    backgroundColor: '#FF0000', // Bright red background
    justifyContent: 'space-between',
    alignItems: 'center',
    padding: 15,
    borderTopLeftRadius: 0,
    borderTopRightRadius: 0,
  },
  headerText: {
    color: '#ffffff',
    fontSize: 18,
    fontWeight: 'bold',
  },
  closeButton: {
    color: '#ffffff',
    fontSize: 18,
    fontWeight: 'bold',
    paddingHorizontal: 10,
  },
  adContainer: {
    width: '100%',
    backgroundColor: '#f2f2f2', // Neutral background to frame the ad content
    borderRadius: 8,
    marginTop: 0,
  },

Passing User Data to the SDK

You can pass user data into the FluentAdFlowWidgetView like this:

const params = {
  email: 'default@example.com',
  firstname: 'John',
  lastname: 'Smith',
  gender: 'male',
  address1: '37 Willow Street',
  address2: 'Apt 2',
  city: 'Wichita',
  state: 'Kansas',
  telephone: '1234567890',
};

if (adRef.current?.setParams) {
  adRef.current.setParams(params);
} else {
  console.log('setParams method is not available on the adRef');
}

Important Notes:

SDK Initialization:

The SDK should be initialized when the app starts. To do this, call FluentAdFlowWidget.init("<your-api-key>", withReferrer: "<referrer>"), providing your API key and referrer.

Using the Widget:

To display the ad widget in your app, add the FluentAdFlowWidgetView component.

Loading the Ad:

You can load ads into the widget by calling setParams() on the FluentAdFlowWidgetView object. Pass user data such as email, transaction details, etc., to personalize the ad content.

Handling Ad Events:

To track when the ad is shown or ends, listen for the onAdShow event. The isAdShown flag will indicate whether the ad is currently being shown (true) or has ended (false).

By following these simple steps, you can integrate the Fluent AdFlow Widget SDK into your iOS app and start displaying personalized ads!