Highfivve Advertising Flutter Plugin #

A Flutter plugin to integrate Highfivve GmbH's native advertising SDKs for both Android and iOS, enabling you to display various ad formats within your Flutter application.

⚠️ Disclaimer: Official Highfivve GmbH Advertising SDK #

This is the official Highfivve GmbH Advertising Software Development Kit (SDK) delivered as a Flutter Plugin. This plugin utilizes our native advertising_android(visit on github) and advertising_ios(visit on github) SDKs.

Important Usage Requirements:

• Customer Status: To utilize this SDK and the Highfivve advertising services, you or your organization must be an active and approved customer of Highfivve GmbH.
• Authorization: Access to and use of our advertising platform through this SDK require prior authorization and agreement with Highfivve GmbH's terms of service.
• Contact for Access: If you are not yet a customer or wish to inquire about using our advertising services, please contact us to discuss your needs and begin the onboarding process.

Contact Information:

For new customer inquiries, SDK support or any questions regarding the use of this SDK, please reach out to us at:

[team@highfivve.com]

Using this SDK without being an authorized customer of Highfivve GmbH is a violation of our terms and may result in a lack of service or functionality.

Supported Platforms:

• Android
• iOS

Supported Ad Formats:

• Banner Ads
• Interstitial Ads (Planned/In Development - Update as appropriate)

Table of Contents #

• Getting Started
  • Prerequisites
  • Installation
  • Platform Specific Setup
    • Android
    • iOS
• Usage
  • Initializing the SDK
  • Displaying a Banner Ad
  • Handling Ad Events
• API Reference
• Example
• License

Getting Started #

Prerequisites #

• Flutter SDK: Version >= 3.3.0
• Dart SDK: Version >= 3.4.3
• Active Customer Status with Highfivve GmbH (See disclaimer above).

Installation #

1. Add this to your package's pubspec.yaml file:

dependencies:
  highfivve_advertising: ^0.0.1+3

2. Install packages from the command line:

flutter pub get

Platform Specific Setup #

Android

1. Add Highfivve SDK Dependency: Add the Highfivve Advertising SDK dependency to your android/app/build.gradle file:

dependencies {
    implementation 'com.highfivve.sdk:advertising:0.0.4'// Make sure this line is inserted
}

2. Google AdMob Integration To enable Google AdMob ads, add your AdMob App ID to your AndroidManifest.xml as shown below. This is required for Google ad serving to work correctly. Add the following inside the <application> tag in your android/app/src/main/AndroidManifest.xml:

<meta-data
    android:name="com.google.android.gms.ads.APPLICATION_ID"
    android:value="ca-app-pub-****************~**********"/>

Replace ca-app-pub-****************~********** with your actual AdMob App ID.

• Finding your AdMob App ID: You can find your App ID in the AdMob UI.
  • **More Information: ** Google Mobile Ads SDK Android - Get Started

iOS

1. Permissions: Add necessary permission strings to your ios/Runner/Info.plist file. For example, for App Tracking Transparency:

<key>NSUserTrackingUsageDescription</key><string>This identifier will be used to deliverpersonalized
ads to you.
</string>

2. Add Google AdMob App ID:

To use Google AdMob with the Highfivve Advertising Flutter plugin on iOS, you must add your AdMob App ID to your app's Info.plist. Add the following inside the <dict> section of your ios/Runner/Info.plist:

<key>GADApplicationIdentifier</key><string>ca-app-pub-****************~**********</string>

Replace ca-app-pub-****************~********** with your actual AdMob App ID.

• Finding your AdMob App ID: You can find your App ID in the AdMob UI.
  • **More Information: ** Google Mobile Ads SDK iOS - Get Started

3. SKAdNetwork Identifiers: To support ad attribution for ad networks participating in Apple's SKAdNetwork framework, you need to include their SKAdNetwork identifiers in your ios/Runner/Info.plist. For Google, you will add an entry for Google's SKAdNetwork identifier.

   Add the SKAdNetworkItems key with an array of dictionaries, where each dictionary contains a SKAdNetworkIdentifier key.

<key>SKAdNetworkItems</key>
<array>
  <dict>
    <key>SKAdNetworkIdentifier</key>
    <string>cstr6suwn9.skadnetwork</string>
  </dict>
  <!-- Add more SKAdNetworkIdentifier entries as needed -->
</array>

This SKAdNetworkItems are needed for this sdk:

Google

<key>SKAdNetworkIdentifier</key><string>cstr6suwn9.skadnetwork</string>

• Google's SKAdNetwork ID:
  • **More Information from Apple: ** Configuring a Source App for SKAdNetwork
  • **More Information from Google: ** Google Mobile Ads SDK iOS - SKAdNetwork ( Often covered within the Get Started or advanced setup pages for iOS 14+)
  • Note: Highfivve GmbH may provide an updated or consolidated list of SKAdNetworkIdentifier values to include, especially if mediating multiple networks. Always refer to the latest guidance from Highfivve and the respective ad networks.

4. PrivacyInfo.xcprivacy: With upcoming Apple privacy requirements, you will need to declare the APIs your SDK (and any embedded third-party SDKs) use. Create a PrivacyInfo.xcprivacy file in your plugin's ios/Resources folder. Ensure your app complies with Apple's privacy manifest requirements. Our native iOS SDK includes necessary privacy declarations for its direct operations. If you integrate other ad networks through our SDK, consult their documentation for their privacy manifest details.

5. Platform Version: Ensure your Podfile in ios/Podfile targets a compatible iOS version ( e.g., platform :ios, '15.0'). This plugin requires iOS 15.0+.

6. Podfile Configuration: Ensure your Podfile is configured to use frameworks.

target 'Runner' do
  use_frameworks! :linkage => :static #<-- Ensure this line is present

  flutter_install_all_ios_pods File.dirname(File.realpath(__FILE__))
  target 'RunnerTests' do
    inherit! :search_paths
  end
end

Usage #

Initializing the SDK #

It's crucial to initialize the HighfivveAdManager at the start of your application, preferably in your main.dart.

import 'dart:io';
import 'package:flutter/material.dart';
import 'package:ahighfivve_advertising/highfivve_advertising.dart';

void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  try {
    await HighfivveAdManager.instance.initialize(
      // When the bundle name is the same for both platforms, you don´t need this differentiation. 
      bundleName: Platform.isAndroid
          ? 'com.example.your_bundle_name_android' // Replace with your actual Android app ID
          : 'com.example.your_bundle_name_ios', // Replace with your actual iOS app ID
      publisherCode: 'your-publisher-code', // Provided by Highfivve GmbH
    );
    print("HighfivveAdManager initialized successfully.");
  } catch (e) {
    print("Failed to initialize HighfivveAdManager: $e");
  }
  runApp(MyApp());
}

class MyApp extends StatelessWidget {

  @override Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Advertising SDK Example',
      home: Scaffold(
        appBar: AppBar(title: Text('Advertising Example')),
        body: Center(child: Text('Welcome to the app!')),
      ),
    );
  }
}

Displaying a Banner Ad (HighfivveBannerAdWidget) #

The HighfivveBannerAdWidget is a stateful widget used to display banner ads. It automatically adjusts its height based on the ad size received from the server.

import 'package:highfivve_advertising/highfivve_advertising.dart';

// Inside your widget's build method: 
HighfivveBannerAdWidget
(
position: 'content_1', // Unique identifier for this ad placement 
showWidget: true, // Optional: Control visibility - default is true
pageType: 'article_list', // Optional: context for the ad  
maxHeight: 300 //Optional: to allocate a fixed height of the widget 
onAdNotFound: () {print('Ad not found');} //Optional: this method is triggered when a ad for a specific position is not found
)

Parameters for HighfivveBannerAdWidget:

• position (required): String - A unique identifier for this ad slot position.
• showWidget (optional): bool - Controls if the widget attempts to load and show an ad. Defaults to true.
• pageType (optional): String - An optional string to specify the type or context of the page where the ad is displayed.
• maxHeight (optional): int - to allocate a fixed max height of the widget.
• onAdNotFound (optional): Function() - Callback for when an ad position is not found.

Handling Ad Events #

The SDK provides mechanisms to listen to global ad events or events specific to ad widgets. (This section might need more detail based on how your event handling is exposed. The original context mentions _AdEventListener and _AdEventHandler which sound internal. Clarify how developers can listen to events like ad clicked, ad closed for interstitials, etc., if not covered by widget callbacks.)

Example (if you have a global event stream):

 _adEventSubscription = HighfivveAdManager.instance.adEvents.listen
(
(event) {
print("Global Ad Event: ${event.type}, Data: ${event.data}");
if (event.type == AdEventType.clicked) {
// Handle ad click   
}
});

// Remember to cancel the subscription in dispose():
_adEventSubscription
?.
cancel
(
);

API Reference #

Full API documentation for this package is available here.

Example #

An example application demonstrating the plugin's features can be found in the /example directory of this package.

License #

This plugin is released under the Apache 2.0 License. See the LICENSE file for more details.