OMNIBOX Flutter SDK Dart · iOS · Android

Обзор

Руководство для партнёров по подключению IABox Prebid Flutter SDK (iOS + Android).

SDK — обёртка над Prebid Mobile SDK (iOS 3.3.0 / Android 3.3.1). Поддерживаются баннерная, interstitial и outstream-видео реклама в Standalone-режиме.

Dart API одинаковый на обеих платформах. Настройка нативного слоя отличается — см. разделы ниже.

Порядок интеграции

1. Получить архив iabox_prebid-flutter-sdk-1.0.0.zip от iaBox
2. Установка — добавить плагин в pubspec.yaml, flutter pub get
3. Настройка Android / iOS — manifest, Info.plist, pod install
4. Инициализация SDK — IABoxPrebid.initialize() при запуске
5. Баннер или outstream — IABoxBanner / IABoxOutstreamVideo после инициализации

На iOS перед инициализацией желательно запросить ATT-разрешение (см. Настройка iOS).

Что вы получаете

Архив iabox_prebid-flutter-sdk-1.0.0.zip. Внутри — папка iabox_prebid/ с плагином, инструкцией и демо.

Отдельно от менеджера iaBox: configId, accountId, при необходимости serverUrl (https://ia.box/ads/prebid).

iabox_prebid/
├── INTEGRATION.md
├── pubspec.yaml
├── lib/
├── android/
├── ios/
└── example/

import 'package:iabox_prebid/iabox_prebid.dart';

Требования

Установка

1. Распакуйте архив

Скопируйте папку iabox_prebid в проект, например в packages/iabox_prebid/.

2. Подключите зависимость

Вариант A — локальная папка (архив от iaBox):

3. Установите зависимости

Выполните flutter pub get. На iOS: cd ios && pod install.

4. Импортируйте

Доступны IABoxPrebid, IABoxBanner, IABoxOutstreamVideo.

5. Настройте платформу

См. разделы Android и iOS ниже.

dependencies:
  flutter:
    sdk: flutter
  iabox_prebid:
    path: packages/iabox_prebid

dependencies:
  iabox_prebid:
    git:
      url: URL_FROM_IABOX
      ref: v1.0.0

cd packages/iabox_prebid/example
flutter pub get
cd ios && pod install && cd ..
flutter run

Настройка Android

Добавьте разрешения, queries для Android 11+ и AdBrowserActivity в AndroidManifest.xml. Установите minSdk 23 в build.gradle.

android {
    defaultConfig {
        minSdk 23
        targetSdk 34
    }
}

android.useAndroidX=true
android.enableJetifier=true

Настройка iOS

После flutter pub get выполните pod install. Добавьте ATT и ATS в Info.plist. Запрашивайте ATT после появления UI.

На iOS баннерные креативы с adboxsdk.new.js рендерятся через WKWebView внутри плагина — дополнительный нативный код не нужен.

cd ios
pod install
cd ..

NSUserTrackingUsageDescription
This identifier will be used to deliver personalized ads to you.
NSAppTransportSecurity

    NSAllowsArbitraryLoads
    

import 'package:app_tracking_transparency/app_tracking_transparency.dart';

Future requestATT() async {
  final status = await AppTrackingTransparency.trackingAuthorizationStatus;
  if (status == TrackingStatus.notDetermined) {
    await AppTrackingTransparency.requestTrackingAuthorization();
  }
}

Инициализация SDK

Вызывается один раз при запуске, до показа рекламы. Возвращает Future<bool>.

SDK инициализируется один раз. Ошибка /status не критична — bid requests идут на /openrtb2/auction.

await IABoxPrebid.initialize(
  accountId: 'YOUR_ACCOUNT_ID',
  serverUrl: 'https://ia.box/ads/prebid',
  timeoutMs: 10000,
  shareGeoLocation: true,
);

Future _initAds() async {
  final success = await IABoxPrebid.initialize(
    accountId: 'YOUR_ACCOUNT_ID',
    serverUrl: 'https://ia.box/ads/prebid',
    timeoutMs: 10000,
    shareGeoLocation: true,
  );
  setState(() => _isAdReady = success);
}

Баннерная реклама

Используйте виджет IABoxBanner. Размеры: 320×50, 300×250, 728×90, 320×100. Нативный баннер уничтожается при dispose виджета.

IABoxBanner(
  configId: 'YOUR_BANNER_CONFIG_ID',
  width: 300,
  height: 250,
  onAdLoaded: () {},
  onAdFailed: () {},
  onAdClicked: () {},
)

Outstream-видео

Outstream проигрывается внутри контента. Используйте IABoxOutstreamVideo — видео рендерит Prebid, отдельный плеер не нужен.

Android: добавьте AdBrowserActivity в манифест; поддерживаются onVideoCompleted и hideOnComplete.

iOS: onVideoCompleted / hideOnComplete не поддерживаются — уберите виджет вручную.

Не прячьте outstream в Offstage или контейнер с нулевой высотой при первом показе (Android).

IABoxOutstreamVideo(
  configId: 'YOUR_VIDEO_CONFIG_ID',
  width: 300,
  height: 250,
  protocols: const [2, 3, 4, 5],
  hideOnComplete: true,
  onAdLoaded: () {},
  onAdFailed: () {},
  onAdClicked: () {},
  onVideoCompleted: () {},
)

Privacy / GDPR

Вызывайте setPrivacyConfig до загрузки рекламы. Поддержка IAB TCF v2 и GPP.

await IABoxPrebid.setPrivacyConfig(
  tcfString: 'CPxxxxxxxxxxxxxxxxx',
  gppString: 'DBABMA~CPxxxx',
  gppSid: [7],
);

События и колбэки

Колбэки виджета: onAdLoaded, onAdFailed, onAdClicked, onVideoCompleted (только Android).

Глобальный поток: IABoxPrebid.events.listen(...) — onBannerLoaded, onBannerFailed, onVideoLoaded и др.

final sub = IABoxPrebid.events.listen((event) {
  switch (event['method']) {
    case 'onBannerLoaded':
      break;
    case 'onBannerFailed':
      break;
    case 'onVideoCompleted':
      break;
  }
});

Решение проблем

Демо-приложение

Полный пример — каталог example/ в комплекте SDK.