fluent_adflow_widget 2.0.2

Fluent AdFlow Widget

Flutter SDK Integration Guide

Introduction

This comprehensive guide provides a step-by-step outline for our Flutter mobile app publishers to integrate the adflow experience via the adflow Flutter SDK seamlessly into their mobile app.

Overview

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

Getting Started

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

E-Commerce Integration

Enhance your app’s user experience by integrating the AdFlow Flutter SDK. This powerful tool allows seamless incorporation of e-commerce features, enabling you to showcase high-quality third-party offers that fit naturally within your app’s design.

Key benefits include:

• Flexible Placement: AdFlow placements can be integrated organically into existing app layouts, ensuring a cohesive user journey.

• Brand Customization: Style the AdFlow experience to align with your brand’s aesthetic.

• Data Control: Maintain full ownership of customer and transaction data while delivering a personalized and native experience for your users.

Integrating the Fluent AdFlow Flutter SDK

Add as a dependency

Install the Flutter adflow SDK into your Flutter project with the following command:

flutter pub add fluent_adflow_widget

This will add a line like this to your package's pubspec.yaml (and run an implicit flutter pub get):

dependencies:
  fluent_adflow_widget: ^[latest_version]

Alternatively, your editor might support flutter pub get. Check the docs for your editor to learn more.

Import it

Now in your Dart code, you can use:

import 'package:fluent_adflow_widget/FluentAdFlowWidget.dart';

Setting Up for iOS Integration

If you do not have an iosfolder in your project please see the troubleshooting steps below.

Set Minimum iOS Version

The Fluent AdFlow SDK requires iOS 14.0 or higher. 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 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

The Android SDK requires minSdkVersion 24 or greater. You may need to change: app/build.gradle:

...
android {
    ...
    defaultConfig {
        ...
        multiDexEnabled true,
        minSdkVersion 24
    }
    ...
}
...

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 dependencies, and permissions for the AdFlow SDK.

SDK Initialization

The SDK exposes a component that you can add to your application code.

Importing the Component

To import the component, add the following statement:

import 'package:flutter/material.dart';
import 'package:fluent_adflow_widget/FluentAdFlowWidget.dart';

The SDK provides an init method to initialize the SDK, which requires an API key and a referrer. Once initialized, you can use the FluentAdFlowWidgetView component in your application.

Initializing the SDK

To initialize the SDK, use the init method:

FluentAdFlowWidget.init("api-key", "referrer");

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 personalize the ad experience, you can pass user-specific parameters to the SDK. These parameters help tailor ad flows for each customer. Below is an example of how to set up and pass user data to the FluentAdFlowWidgetView.

Example Implementation

First, initialize the ad widget using a GlobalKey:

final GlobalKey<FluentAdFlowWidget> _adWidgetKey = GlobalKey();
late FluentAdFlowWidgetView _adWidget;

Then, instantiate the widget inside the initState method and define event listeners for ad interactions:

@override
void initState() {
  super.initState();

  _adWidget = FluentAdFlowWidgetView(
    key: _adWidgetKey,
    onAdShow: (isAdShown) {
      // Ad visibility event triggered
      if (isAdShown) {
        // Perform actions when the ad is shown, such as displaying overlays
      } else {
        // Perform actions when the ad is hidden, such as hiding overlays
      }
    },
    onInternalAdLaunched: (isAdLaunch) {
      // Internal ad launch event triggered of Earn Loyalty Solution
      // Update UI based on ad launch state
    },
    isScrollingEnabled: true, // Enable internal scrolling for the ad
  );
}

Handling Ad Visibility with onAdShow Event Callback

The onAdShow event callback is an optional handler triggered whenever an ad is displayed or hidden. It provides a boolean flag, isAdShown, to indicate the visibility state of the ad.

How It Works

• When the ad is displayed, isAdShown is true.

• When the ad is hidden, isAdShown is false.

You can use this event to manage UI elements that depend on the ad's visibility, such as showing or hiding overlays, modals, or additional UI components.

Example Implementation

void onAdShowHandler(bool isAdShown) {
  debugPrint('**** Ad Show Event Triggered **** $isAdShown');
  if (isAdShown) {
    // Show UI elements that depend on ad visibility
  } else {
    // Hide UI elements when ad is not visible
  }
}

In this example, the event logs the ad's visibility state whenever it changes. You can extend this logic to modify the UI based on whether the ad is visible or hidden.

Enabling Internal Scrolling (Only for Earn Loyalty Solution)

By default, the SDK does not support scrolling because its internal scrolling behavior can interfere with the app's scrolling, preventing users from scrolling through the page when the ad is placed inline with other components.

However, there are scenarios where enabling scrolling within the ad component itself is beneficial, such as:

The ad is displayed on a dedicated page or in its own tab.

The app layout requires fixed top components while allowing the ad to scroll independently.

To address this, the FluentAdFlowWidgetView component includes the isScrollingEnabled property, which allows internal scrolling within the ad.

Usage Example

To enable internal scrolling, set isScrollingEnabled to true in the component:

FluentAdFlowWidgetView(
  key: _adWidgetKey,
  isScrollingEnabled: true,
  onAdShow: (isAdShown) {
    // Handle ad show event
  },
  onInternalAdLaunched: (isAdLaunch) {
    // Handle internal ad launch event
  },
);

Handling Internal Ad Launch Events (Only for Earn Loyalty Solution)

Some applications require blocking interactions with other UI components when users claim earned points. To facilitate this, the SDK provides the onInternalAdLaunched callback event.

Behavior

This event is triggered when the user clicks to claim earned points or closes the popup ad window.

A boolean flag is passed into the callback method:

true → The popup is shown.

false → The popup is closed.

Usage Example

The following implementation listens for ad launch events and updates the application state accordingly:

FluentAdFlowWidgetView(
  key: _adWidgetKey,
  isScrollingEnabled: true,
  onAdShow: (isAdShown) {
    // Handle ad visibility changes
  },
  onInternalAdLaunched: (isAdLaunch) {
    _isAdLaunch = isAdLaunch;
    // Perform UI updates when ad is launched or closed
  },
);

Passing User Data

Next, define the user data you want to pass:

var userDetails = {
    "email": "[e-mail]",
    "firstname": "John",
    "lastname": "Smith",
    "orderId": "123abc456def",
    "transactionValue": "99.99",
    "zip": "11211",
};

Finally, pass the user details to the ad widget when it is mounted:

final adState = _adWidgetKey.currentState;
if (adState != null) {
  adState.setParams(userDetails);
} else {
  debugPrint("🚨 Ad Widget not mounted yet!");
}

This ensures the ad widget receives the necessary user data to provide a more personalized experience.

Building the UI

The UI consists only of the ad widget. Below is the implementation:

@override
Widget build(BuildContext context) {
  return Scaffold(
    backgroundColor: Colors.black,
    body: SafeArea(
      child: Column(
        crossAxisAlignment: CrossAxisAlignment.start,
        children: [
          _adWidget,
        ],
      ),
    ),
  );
}

IMPORTANT NOTES:

SDK Initialization

The SDK should be initialized when the app starts. To do this, call:

FluentAdFlowWidget.init("<your-api-key>", "<referrer>")

Provide your API key and referrer as parameters.

Using the Widget

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

Loading the Ad

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:

• true: The ad is currently being shown.
• false: The ad has ended.

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