Getting Started - Ad Control Help Center

Overview

Adrop Flutter SDK allows you to easily integrate various ad formats into your Flutter app.

Supported Ad Formats

Format	Description
Banner Ad	Rectangular ads displayed in a portion of the screen
Native Ad	Ads that naturally blend with your app content
Interstitial Ad	Full-screen ads
Rewarded Ad	Full-screen ads that provide rewards
Popup Ad	Ads displayed in popup format
Splash Ad	Ads displayed with your logo when the app starts

Requirements

Flutter

Flutter SDK 3.3.0 or higher
Dart SDK 2.18.0 or higher

Android

API level 23 (Android 6.0) or higher
compileSdkVersion 34
Kotlin 2.1.0 or higher
Gradle 8.7 or higher
Using Jetpack (AndroidX)

iOS

iOS 13.0 or higher
Swift 5.0 or higher

Installation

1. Install Package

Run the following command in your project directory.

flutter pub add adrop_ads_flutter

2. Android Setup

Add the backfill ad repository to android/settings.gradle.kts.

android/settings.gradle.kts

dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        mavenCentral()
        maven { url = uri("https://artifact.bytedance.com/repository/pangle") }
    }
}

Add the backfill dependency to android/app/build.gradle.

android/app/build.gradle

dependencies {
    implementation 'io.adrop:adrop-ads-backfill:1.8.0'
}

Add the backfill App ID to android/app/src/main/AndroidManifest.xml.

android/app/src/main/AndroidManifest.xml

<manifest>
    <application>
        <!-- Backfill App ID -->
        <meta-data
            android:name="com.google.android.gms.ads.APPLICATION_ID"
            android:value="ca-app-pub-xxxxxxxxxxxxxxxx~yyyyyyyyyy"/>
    </application>
</manifest>

Please contact Adrop to get your App ID.

3. iOS Setup

Modify ios/Podfile.

ios/Podfile

use_frameworks!

target 'Runner' do
  # Other dependencies...

  # Backfill ad SDK
  pod 'adrop-ads-backfill'
end

Install pods.

cd ios && pod install --repo-update && cd ..

4. Info.plist Configuration

Add the following settings to ios/Runner/Info.plist for backfill ads.

GADApplicationIdentifier: App ID for backfill ads
SKAdNetworkItems: Required for ad conversion tracking on iOS 14+

View Info.plist Configuration

Info.plist

<key>GADApplicationIdentifier</key>
<string>ca-app-pub-xxxxxxxxxxxxxxxx~yyyyyyyyyy</string>

<key>SKAdNetworkItems</key>
<array>
    <dict>
        <key>SKAdNetworkIdentifier</key>
        <string>cstr6suwn9.skadnetwork</string>
    </dict>
    <dict>
        <key>SKAdNetworkIdentifier</key>
        <string>4fzdc2evr5.skadnetwork</string>
    </dict>
    <dict>
        <key>SKAdNetworkIdentifier</key>
        <string>4pfyvq9l8r.skadnetwork</string>
    </dict>
    <dict>
        <key>SKAdNetworkIdentifier</key>
        <string>2fnua5tdw4.skadnetwork</string>
    </dict>
    <dict>
        <key>SKAdNetworkIdentifier</key>
        <string>ydx93a7ass.skadnetwork</string>
    </dict>
    <dict>
        <key>SKAdNetworkIdentifier</key>
        <string>5a6flpkh64.skadnetwork</string>
    </dict>
    <dict>
        <key>SKAdNetworkIdentifier</key>
        <string>p78axxw29g.skadnetwork</string>
    </dict>
    <dict>
        <key>SKAdNetworkIdentifier</key>
        <string>v72qych5uu.skadnetwork</string>
    </dict>
    <dict>
        <key>SKAdNetworkIdentifier</key>
        <string>ludvb6z3bs.skadnetwork</string>
    </dict>
    <dict>
        <key>SKAdNetworkIdentifier</key>
        <string>cp8zw746q7.skadnetwork</string>
    </dict>
</array>

Please contact Adrop for the full SKAdNetworkItems list and App ID.

5. Add Configuration File

Android

Download the adrop_service.json file from the Ad Control Console.
Copy the file to the android/app/src/main/assets/ directory.

android/app/src/main/assets/adrop_service.json

iOS

Download the adrop_service.json file from the Ad Control Console.
Add the file to the project root in Xcode.
Make sure to add the file to all targets.

Initialization

Initialize the SDK at app startup. Typically called in main.dart.

main.dart

import 'package:adrop_ads_flutter/adrop_ads_flutter.dart';

void main() {
  runApp(const MyApp());
}

class MyApp extends StatefulWidget {
  const MyApp({super.key});

  @override
  State<MyApp> createState() => _MyAppState();
}

class _MyAppState extends State<MyApp> {
  @override
  void initState() {
    super.initState();
    _initializeAdrop();
  }

  Future<void> _initializeAdrop() async {
    // false: test mode, true: production mode
    await Adrop.initialize(false);
  }

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      home: HomeScreen(),
    );
  }
}

Initialization Options

await Adrop.initialize(
  production,        // bool: production mode flag
  targetCountries: targetCountries,   // List<String>?: target country codes (optional)
  useInAppBrowser: useInAppBrowser    // bool?: iOS in-app browser usage (optional)
);

Parameters

Parameter	Type	Required	Description
`production`	`bool`	Y	`true`: production mode, `false`: test mode
`targetCountries`	`List<String>`	N	Country codes to show ads (e.g., `['KR', 'US']`)
`useInAppBrowser`	`bool`	N	iOS in-app browser usage (default: `false`)

Examples

// Basic initialization (test mode)
await Adrop.initialize(false);

// Production mode + specific country targeting
await Adrop.initialize(true, targetCountries: ['KR', 'JP', 'US']);

// Production mode + iOS in-app browser
await Adrop.initialize(true, useInAppBrowser: true);

Theme Settings

Set the ad UI theme.

import 'package:adrop_ads_flutter/adrop_ads_flutter.dart';

// Set theme
await Adrop.setTheme(AdropTheme.auto);  // Follow system settings
await Adrop.setTheme(AdropTheme.light); // Light mode
await Adrop.setTheme(AdropTheme.dark);  // Dark mode

Theme	Description
`AdropTheme.auto`	Automatically switches based on system settings
`AdropTheme.light`	Light mode
`AdropTheme.dark`	Dark mode

Set User Identifier

Set a user identifier (UID) for targeted advertising.

import 'package:adrop_ads_flutter/adrop_ads_flutter.dart';

// After user login
await Adrop.setUID('user_123');

// On logout
await Adrop.setUID('');

UID is hashed with SHA-256 before transmission. Do not pass personally identifiable information such as email or phone number directly.

Test Unit IDs

Use the following test unit IDs during development and testing.

Format	Test Unit ID
Banner (320x50)	`PUBLIC_TEST_UNIT_ID_320_50`
Banner (320x100)	`PUBLIC_TEST_UNIT_ID_320_100`
Native	`PUBLIC_TEST_UNIT_ID_NATIVE`
Interstitial	`PUBLIC_TEST_UNIT_ID_INTERSTITIAL`
Rewarded	`PUBLIC_TEST_UNIT_ID_REWARDED`
Popup (Bottom)	`PUBLIC_TEST_UNIT_ID_POPUP_BOTTOM`
Popup (Center)	`PUBLIC_TEST_UNIT_ID_POPUP_CENTER`
Splash	`PUBLIC_TEST_UNIT_ID_SPLASH`

Be sure to replace with actual unit IDs before production deployment.

Error Codes

Error codes that can occur in the SDK.

Error Code	Description
`network`	Network error
`internal`	Internal error
`initialize`	SDK initialization error
`invalidUnit`	Invalid unit ID
`notTargetCountry`	Not a target country
`inactive`	Inactive ad
`adNoFill`	No ads to display
`adLoadDuplicate`	Duplicate load request
`adLoading`	Loading in progress
`adEmpty`	Empty ad
`adShown`	Ad already shown
`adHideForToday`	Hidden for today
`accountUsageLimitExceeded`	Account usage limit exceeded
`adLandscapeUnsupported`	Landscape mode not supported
`backfillNoFill`	No backfill ads

import 'package:adrop_ads_flutter/adrop_ads_flutter.dart';

// Error handling example
if (errorCode == AdropErrorCode.adNoFill) {
  debugPrint('No ads available to display.');
}

Deprecated Class Migration

The following classes are deprecated and will be removed in a future version. Please migrate to the new classes.

AdropBanner → AdropBannerView

The AdropBanner widget is deprecated. Migrate to AdropBannerView.

// ❌ Deprecated
AdropBanner(
  unitId: 'YOUR_UNIT_ID',
  onAdropBannerCreated: (controller) {
    controller.load();
  },
  onAdReceived: (banner) { },
);

// ✅ Recommended (AdropBannerView)
final bannerView = AdropBannerView(
  unitId: 'YOUR_UNIT_ID',
  listener: AdropBannerListener(
    onAdReceived: (unitId, metadata) { },
    onAdFailedToReceive: (unitId, errorCode) { },
  ),
);
bannerView.load();

AdropNavigatorObserver (Deprecated)

AdropNavigatorObserver is deprecated and will be removed in a future version. This class no longer provides any functionality and can be safely removed from your code.

// ❌ Deprecated — can be removed
MaterialApp(
  navigatorObservers: [AdropNavigatorObserver()],
);

// ✅ Remove AdropNavigatorObserver
MaterialApp(
  // Remove AdropNavigatorObserver from navigatorObservers
);

Troubleshooting

iOS Build Errors

If you encounter Swift version compatibility issues, add the following to the post_install block in ios/Podfile.

ios/Podfile

post_install do |installer|
  installer.pods_project.targets.each do |target|
    target.build_configurations.each do |config|
      config.build_settings['BUILD_LIBRARY_FOR_DISTRIBUTION'] = 'YES'
    end
  end
end

Android Build Errors

If the Kotlin version doesn’t match, check the Kotlin version in android/build.gradle.

android/build.gradle

buildscript {
    ext.kotlin_version = '2.1.0'
}

Next Steps

Banner Ads

Implement banner ads

Native Ads

Implement native ads

Interstitial Ads

Implement interstitial ads

Rewarded Ads

Implement rewarded ads

WebView Guide

Display web ads in WebView

UMP Integration

GDPR/CCPA consent management

SDK Guide

AI

Android

iOS

React Native

Flutter

Web

REST API

​Overview

​Supported Ad Formats

​Requirements

​Flutter

​Android

​iOS

​Installation

​1. Install Package

​2. Android Setup

​3. iOS Setup

​4. Info.plist Configuration

​5. Add Configuration File

​Android

​iOS

​Initialization

​Initialization Options

​Theme Settings

​Set User Identifier

​Test Unit IDs

​Error Codes

​Deprecated Class Migration

​AdropBanner → AdropBannerView

​AdropNavigatorObserver (Deprecated)

​Troubleshooting

​iOS Build Errors

​Android Build Errors

​Next Steps

Banner Ads

Native Ads

Interstitial Ads

Rewarded Ads

WebView Guide

UMP Integration

Overview

Supported Ad Formats

Requirements

Flutter

Android

iOS

Installation

1. Install Package

2. Android Setup

3. iOS Setup

4. Info.plist Configuration

5. Add Configuration File

Android

iOS

Initialization

Initialization Options

Theme Settings

Set User Identifier

Test Unit IDs

Error Codes

Deprecated Class Migration

AdropBanner → AdropBannerView

AdropNavigatorObserver (Deprecated)

Troubleshooting

iOS Build Errors

Android Build Errors

Next Steps