fluent-adflow-widget 2.0.0

.NET MAUI SDK 2.0 Integration Guide

This guide will help you integrate the fluent-adflow-widget NuGet package into your .NET MAUI application. The fluent-adflow-widget allows you to easily display ads within your app.

Prerequisites

Ensure you have the following prerequisites:

• .NET 8.0 or higher
• .NET MAUI
• Access to the Fluent AdFlow Widget API (API key and referer)

Installation

Install the fluent-adflow-widget NuGet package in your .NET MAUI project:

dotnet add package fluent-adflow-widget

iOS Integration Guide

Prerequisites

• Ensure your MAUI project includes an iOS target
• Fluent AdFlow SDK requires iOS 14.0 or higher

Setup Instructions

1. Verify iOS Project Structure

If your project doesn't contain an iOS folder:

1. Right-click on your solution in Visual Studio
2. Select Add > New Project
3. Choose .NET MAUI iOS Application
4. Follow the project creation wizard

2. Set Minimum iOS Version

Update your project to target iOS 14.0 or higher:

1. Open your Platforms/iOS/Info.plist file
2. Set the MinimumOSVersion to 14.0
3. Alternatively, set this in your project properties:
   • Right-click iOS project > Properties
   • Under Application > Target iOS version, select 14.0 or higher

3. Update Info.plist for Advertising Identifier

Add the following entry to your Platforms/iOS/Info.plist file to ensure IDFA compliance:

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

You can add this by:

1. Opening Info.plist
2. Switching to Source view
3. Adding the XML snippet within the <dict> section

Verification

Build your iOS project to ensure there are no configuration errors. The project should compile successfully with these settings.

Android Integration Guide

Prerequisites

Before integrating the fluent-adflow-widget, ensure the following requirements are met:

• Android API Level 21 (Android 5.0 Lollipop) or higher
• AndroidX compatibility is enabled in your project
• Google Play Services must be available (required if using GAID)

Required NuGet Packages

Install the following NuGet packages in your Android project:

dotnet add package Square.Retrofit2 --version 2.11.0.1
dotnet add package Square.Retrofit2.ConverterGson --version 2.11.0.1
dotnet add package Xamarin.GooglePlayServices.Ads.Identifier --version 118.0.1

These libraries are used for networking (Retrofit) and retrieving the Google Advertising ID (GAID).

Configuration Steps

1. Add GAID Permission

To collect the Google Advertising ID (GAID), add this permission to your AndroidManifest.xml:

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

2. Update AndroidManifest.xml

• Locate the file at: Platforms/Android/AndroidManifest.xml
• Add the permission within the <manifest> tag but outside the <application> tag

Verification

After configuration:

• Clean and rebuild your Android project
• Verify the build completes successfully
• Confirm the permission appears in your merged manifest:
• Check: obj/Debug/{target}/android/AndroidManifest.xml

Notes

This permission is required for ad personalization and tracking

Integration Steps

1. Update MauiProgram.cs

In your MauiProgram.cs file, add the following code to configure the FluentAdFlowWidgetControl handler:

using Microsoft.Extensions.Logging;
using Fluent.Maui.AdFlow;

namespace YourNamespace;

public static class MauiProgram
{
    public static MauiApp CreateMauiApp()
    {
        var builder = MauiApp.CreateBuilder();
        builder
            .UseMauiApp<App>()
            .ConfigureFonts(fonts =>
            {
                fonts.AddFont("OpenSans-Regular.ttf", "OpenSansRegular");
                fonts.AddFont("OpenSans-Semibold.ttf", "OpenSansSemibold");
            })
            .ConfigureMauiHandlers(handlers =>
            {
                handlers.AddHandler(typeof(FluentAdFlowWidgetControl), typeof(FluentAdFlowWidgetHandler));
            });

#if DEBUG
        builder.Logging.AddDebug();
#endif

        return builder.Build();
    }
}

2. Initializing the SDK (.NET MAUI)

To initialize the SDK in a .NET MAUI application, you need to use the FluentAdFlowWidgetHandler.InitializeSdk(...) method. This method requires two parameters: your API key and referer. It also accepts two callbacks to handle success and failure events.

We recommend calling this method during your app's startup or page load process to ensure the SDK is ready before usage.

Method Signature

void InitializeSdk(
    string apiKey,
    string referer,
    Action onInitializedSucceed,
    Action<int, string> onInitializedFailure
)

Parameters

Error Codes

Example Usage

private FluentAdFlowWidgetHandler _widgetHandler;

public MainPage()
{
    InitializeComponent();
    _widgetHandler = new FluentAdFlowWidgetHandler();
}

private void InitializeWidget(string apiKeyValue, string refererValue)
{
    _widgetHandler.InitializeSdk(
        apiKeyValue,
        refererValue,
        onInitializedSucceed: () => 
        {
            Console.WriteLine("✅ SDK initialized successfully");
        },
        onInitializedFailure: (errorCode, errorMessage) => 
        {
            Console.WriteLine($"❌ SDK initialization failed (Code: {errorCode}) - {errorMessage}");
        }
    );
}

3. Displaying the Ad and Passing User Data

To display the ad and pass user data, use the FluentAdFlowWidgetControl in your XAML layout. In code-behind, you can set parameters via the Params property.

XAML Implementation

<fluentAdFlowWidget:FluentAdFlowWidgetControl 
    x:Name="Ad1"/>

C# Code-Behind Implementation

Ad1.Params = new Dictionary<string, object>
{
    ["email"] = "user@example.com",
    ["emailmd5"] = "md5hash",
    ["emailsha256"] = "sha256hash",
    ["firstname"] = "John",
    ["lastname"] = "Smith",
    ["gender"] = "male",
    ["address1"] = "123 Main St",
    ["address2"] = "Apt 4B",
    ["city"] = "New York",
    ["state"] = "NY",
    ["telephone"] = "555-123-4567",
    ["transactionId"] = "TRX12345",
    ["currency"] = "USD",
    ["primaryCategory"] = "Electronics",
    ["subCategory"] = "Smartphones",
    ["subaff1"] = "Affiliate1",
    ["orderId"] = "ORD67890",
    ["transactionValue"] = "599.99",
    ["zip"] = "10001"
};

4. Handling Ad Visibility with OnAdShow Callback

The OnAdShow delegate is triggered when the ad appears or is hidden. This is useful for displaying or hiding container views like slide-up drawers.

Ad1.OnAdShow = OnAd1ShowHandler;

private void OnAd1ShowHandler(bool isShown)
{
    SlideUpDrawer.IsVisible = isShown;
    Console.WriteLine("**** Ad 1 Show Event Triggered **** " + isShown);
}

5. (Optional) Dynamically Resize Popup Wrapper Based on Ad Content Height

If you’re using the FluentAdFlowWidgetControl inside a popup-style container (such as a slide-up drawer), you may want to dynamically adjust the popup’s height to fit the ad content.

To do this, handle the SizeChanged event from the widget and update the popup container’s HeightRequest and layout bounds accordingly.

Note: This step is not required when using the widget as an inline ad inside a scrollable layout or page.

Example:

XAML Implementation

<Frame
    x:Name="PopupContainer"
    IsVisible="False"
    CornerRadius="10"
    Padding="10"
    HasShadow="True"
    BackgroundColor="White"
    AbsoluteLayout.LayoutFlags="PositionProportional"
    AbsoluteLayout.LayoutBounds="0.5, 0.5, 0.9, AutoSize">
    
    <Grid Padding="0">
        <fluentAdFlowWidget:FluentAdFlowWidgetControl
            x:Name="PopupAdFlowWidget"
            HorizontalOptions="FillAndExpand"
            VerticalOptions="FillAndExpand" />
    </Grid>
</Frame>

C# Code-Behind Implementation

PopupAdFlowWidget.SizeChanged += OnPopupAdFlowWidgetSizeChanged;
.
.
.
private bool _isUpdatingHeight = false;
private double _previousHeight = -1;

private void OnPopupAdFlowWidgetSizeChanged(object sender, EventArgs e)
{
    if (_isUpdatingHeight) return;
    
    _isUpdatingHeight = true;
    
    double height = PopupAdFlowWidget.HeightRequest;
    
    if (!double.IsNaN(height) && height > 0 && height != _previousHeight)
    {
        _previousHeight = height;
        PopupContainer.HeightRequest = height + 25; // Add 25px padding
    }
    
    _isUpdatingHeight = false;
}

Important Notes

SDK Initialization:

The SDK should be initialized when the app starts. Use the InitializeSdk method on the FluentAdFlowWidgetHandler, passing your API key and referer. You can also provide callbacks for success and failure to handle the initialization result appropriately.

Using the Widget:

To display the ad widget in your app, add the FluentAdFlowWidgetControl to your layout. The widget will render inline within your page and automatically handle ad display once initialized.

Loading the Ad:

You can load personalized ads into the widget by setting the Params property with relevant user data such as email or transaction details. This data helps tailor the ad content for each user.

Handling Ad Events:

To detect when an ad is shown or closed, use the OnAdShow event. It provides a flag indicating whether the ad is currently being displayed (true) or has been closed (false).

Popup Height Adjustment (Optional):

If the widget is used inside a popup or a dynamic container, you can listen to the SizeChanged event to update the container height based on the ad content. This step is only required when the widget is wrapped inside such a layout and is not needed when used inline.