@npm_fluentco/adflow-react-native-sdk/README.md

Fluent Ad Flow Widget

# @npm_fluentco/adflow-react-native-sdk

## Fluent AdFlow Widget SDK for React Native
This package only supports the new React Native architecture, which includes Fabric and TurboModules.
Starting with React Native 0.76, the New Architecture is enabled by default, offering better performance and stability.

- For apps running React Native 0.76 or newer, you can use the latest version of this package directly.

- If your app is on a React Native version below 0.76 or still relies on the old architecture, please use version 2.0.11 instead.

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

<div style="border: 2px solid #FFC107; border-radius: 8px; padding: 16px; background-color: #FFF8E1; color: #000000">
Note: While the old architecture is still technically available in RN 0.76, it is now considered legacy and will eventually be removed in a future release. For long-term support and access to new features, we strongly recommend migrating to the New Architecture.
</div>

## Upgrading from the classic architecture of the React Native framework to the modern architecture
If you’re upgrading your application from the classic architecture to the modern architecture then be sure to see the breaking changes listed here and update your code accordingly.

<b>Breaking changes</b>

* Minimum Platform versions: iOS version: 15.1+, Android SDK: 24+

* AdRefs can no longer be set as \
`const adRef = useRef(null);`
They must now be set as \
`const adRef = useRef<FluentAdFlowWidgetViewRef>(null);`

* SDK 3.0+ is not backwards compatible with the classic architecture of React Native. The last stable version of the SDK that works with the classic architecture of React Native is version 2.0.11
## 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 enhance your app’s functionality.

<div style="border: 2px solid #FFC107; border-radius: 8px; padding: 16px; background-color: #FFF8E1; color: #000000">
Important: This package supports React Native 0.76+ with the New Architecture (Fabric and TurboModules).
Ensure you are using @npm_fluentco/adflow-react-native-sdk version 3.0 or above.
If you are on an older React Native version or still using the legacy architecture, use version 2.0.11 instead.
</div>

### Installation

Install the SDK using npm:

```sh
npm install @npm_fluentco/adflow-react-native-sdk@^3.0.0
```

## Setting Up for iOS Integration

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

### Set Minimum iOS Version and Enable New Architecture

The React Native framework requires iOS 15.1 or higher. 
```
If you’re using version 2.0.11 or below then the minimum iOS version supported is 14 (classic React Native architecture)
```

To ensure compatibility:
1. Open your project's Podfile, typically found in the root of the ios directory.

2. Verify or update the iOS deployment target to at least version 15.1 or min_ios_version_supported.

Example update:

```
platform :ios, min_ios_version_supported
```

3. Enable the New Architecture by adding the following line before the use_react_native! call:

```
ENV['RCT_NEW_ARCH_ENABLED'] = '1'
```

Example Podfile snippet:
```
ENV['RCT_NEW_ARCH_ENABLED'] = '1'

# Resolve react_native_pods.rb with node to allow for hoisting
require Pod::Executable.execute_command('node', ['-p',
  'require.resolve(
    "react-native/scripts/react_native_pods.rb",
    {paths: [process.argv[1]]},
  )', __dir__]).strip

platform :ios, min_ios_version_supported
prepare_react_native_project!

linkage = ENV['USE_FRAMEWORKS']
if linkage != nil
  Pod::UI.puts "Configuring Pod with #{linkage}ally linked Frameworks".green
  use_frameworks! :linkage => linkage.to_sym
end

target 'WebviewFabricExample' do
  config = use_native_modules!

  use_react_native!(
    :path => config[:reactNativePath],
    # An absolute path to your application root.
    :app_path => "#{Pod::Config.instance.installation_root}/.."
  )

  post_install do |installer|
    installer.pods_project.targets.each do |target|
      target.build_configurations.each do |config|
        config.build_settings['CLANG_ALLOW_NON_MODULAR_INCLUDES_IN_FRAMEWORK_MODULES'] = 'YES'
      end
    end
    
    # https://github.com/facebook/react-native/blob/main/packages/react-native/scripts/react_native_pods.rb#L197-L202
    react_native_post_install(
      installer,
      config[:reactNativePath],
      :mac_catalyst_enabled => false,
      # :ccache_enabled => true
    )
  end
end
```
This ensures your project is configured to support both the minimum iOS version and the New React Native Architecture, which is required by the Fluent AdFlow SDK.

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

```sh
cd ios && pod install
```

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

```sh
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):

```xml
<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
Minimum Android SDK Supported is SDK 24

```
If you’re using version 2.0.11 or below then the minimum Android SDK version is 23 (classic React Native architecture)
```

### 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:

```xml
<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.

### Enable New React Native Architecture
To enable Fabric and TurboModules on Android, add the following line to your gradle.properties file, located in the root of your Android project:

```
newArchEnabled=true
```

This ensures your Android project is configured to support the New React Native Architecture, which is required by the Fluent 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.

```java
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:

```js
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:

```js
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:

```js
import React, { useState, useRef } from 'react';
import { FluentAdFlowWidgetView } from '@npm_fluentco/adflow-react-native-sdk';
import type { FluentAdFlowWidgetViewRef } from '@npm_fluentco/adflow-react-native-sdk';
.
.
.
const adRef = useRef<FluentAdFlowWidgetViewRef>(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:

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

<div style="border: 2px solid #FFC107; border-radius: 8px; padding: 16px; background-color: #FFF8E1; color: #000000">

### **⚠️ 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:

```html
<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:
```css
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,
  },
```
</div>

### Passing User Data to the SDK

You can pass user data into the FluentAdFlowWidgetView like this:

```js
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');
}
```

<div style="border: 2px solid #FFC107; border-radius: 8px; padding: 16px; background-color: #FFF8E1; color: #000000">

### 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!

</div>

## License

© 2025 Fluent, LLC Licensed under the Fluent Software Development Kit (SDK) Terms of Use, Ver. 1.0 (the "Agreement"). Your use of this SDK is subject to the Agreement which you can access [here](https://fluentco.com/sdk-license/)