Skip to main content

nestads_sdk_flutter_plugin 0.1.6-dev.3 copy "nestads_sdk_flutter_plugin: ^0.1.6-dev.3" to clipboard
nestads_sdk_flutter_plugin: ^0.1.6-dev.3 copied to clipboard

Official NestAds SDK for Flutter. Banner, popup, and splash ads with native Android and iOS integration.

nestads_sdk_flutter_plugin #

NestAds SDK의 공식 Flutter 플러그인. 네이티브 Android/iOS SDK를 기반으로 배너, 팝업, 스플래시 광고를 지원합니다.

주요 기능 #

  • 배너(Banner) — FLUID / FILL / 고정 크기(FIXED) 이미지 배너 광고
  • 팝업(Popup) — 단일 / 복수(캐러셀 + 모아보기 AdList) 팝업 광고, 좌/우 버튼 커스터마이징
  • 스플래시(Splash) — 1~5초 노출 스플래시 광고. 단일 응답(이미지)과 와이드 응답(Wide 이미지 / Wide 비디오)을 단일 위젯에서 모두 처리
  • Imperative 컨트롤러 — 네이티브 뷰를 재생성하지 않고도 광고를 다시 로드 / 표시 / 닫기
  • 타입 안전한 옵션 — 포맷별 전용 옵션 클래스 (NestAdsBannerOptions, NestAdsPopupOptions, NestAdsSplashOptions)
  • 자동 에러 리포팅 — Dart 측 예외를 NestAds 에러 로그 엔드포인트로 자동 전송 (JS/네이티브 SDK와 동일한 페이로드 / AES 인코딩)

요구 사항 #

플랫폼 버전
iOS 12.0 이상 (Xcode 16+, Swift 5.9+)
Android minSdkVersion 21, compileSdkVersion 33+, Kotlin 1.9+
Flutter 3.3.0 이상

설치 #

dependencies:
  nestads_sdk_flutter_plugin: ^0.1.4

Android 설정 #

프로젝트 레벨 android/settings.gradle에 NestAds Maven 저장소를 추가하세요. 일반적으로는 releases만 추가하면 충분하며, 플러그인의 -dev 사전 배포본을 사용하는 경우 snapshots도 함께 등록합니다:

dependencyResolutionManagement {
    repositories {
        google()
        mavenCentral()
        // Stable releases
        maven { url 'https://nexus.wisebirds.ai/repository/releases/' }
        // Pre-release / -dev builds (플러그인 -dev.* 버전 사용 시 필요)
        maven { url 'https://nexus.wisebirds.ai/repository/snapshots/' }
    }
}

iOS 설정 #

ios/Runner/Info.plist에 ATT 권한을 추가하세요:

<key>NSUserTrackingUsageDescription</key>
<string>사용자 트래킹 사용 목적을 기재해주세요.</string>

앱 실행 시 트래킹 권한을 요청합니다:

import AppTrackingTransparency

ATTrackingManager.requestTrackingAuthorization { _ in }

빠른 시작 #

초기화 #

호스트 앱은 광고 위젯이 마운트되기 전에 SDK를 한 번 초기화해야 합니다 — 일반적으로 main()의 runApp() 직전.

import 'package:flutter/widgets.dart';
import 'package:nestads_sdk_flutter_plugin/nestads_sdk_flutter_plugin.dart';

void main() async {
  WidgetsFlutterBinding.ensureInitialized();

  // 운영 앱: 채널 문제 (예: 플러그인 미등록) 를 직접 처리
  try {
    await NestAdsService.initialize();
  } catch (e) {
    // 폴백 / 로깅
  }

  // 데모 / 비핵심 환경: 실패를 무시 (내부 try/catch + debugPrint)
  // await NestAdsService.initializeIgnoringErrors();

  runApp(const MyApp());
}

⚠ initialize()를 호출하지 않으면 네이티브 SDK가 준비되지 않아 광고 위젯이 정상적으로 로드되지 않습니다. ⚠ 양 OS SDK는 초기화 실패(예: 키를 찾지 못함)를 알리지 않습니다 — initialize()는 그래도 정상 완료되고, 실패는 이후 광고마다 "SDK is not initialized" 로드 실패(코드 1000)로 나타납니다. ⚠ initialize()가 던지는 것은 채널 문제(예: 플러그인 미등록 시 MissingPluginException)뿐입니다 — try/catch 없이 await하면 unhandled async error로 잡혀 runApp()이 호출되지 않아 UI가 뜨지 않을 수 있습니다.

배너 (Banner) #

import 'package:nestads_sdk_flutter_plugin/nestads_sdk_flutter_plugin.dart';

final controller = NestAdsBannerController();

NestAdsBanner(
  placementCode: 'SAMPLE_IMAGE_BANNER/320/50',
  adSize: NestAdsAdSize(320, 50),
  options: const NestAdsBannerOptions(
    backgroundColor: '#FFFFFF',
    radius: 4,
    backgroundOpacity: 1.0,
  ),
  // 타겟팅 — appVersion(iOS only)/country/language/gender/age/
  // publisherProvidedId/customTargeting/audienceParameters/
  // httpTimeoutMillis/rtbPartners
  targeting: const NestAdsTargeting(
    country: 'KR',
    age: 25,
  ),
  controller: controller,
  onAdLoaded: () => print('로드 완료'),
  onAdImpression: (isLogSent) => print('노출 $isLogSent'),
  onAdClicked: (isLogSent) => print('클릭 $isLogSent'),
  // 실패 종류는 코드로 구분한다 (양 OS 같음). 예: 3000 광고 없음, 5001 시간 초과
  onAdFailedToLoadWithError: (error) => print('실패 ${error.code} ${error.message}'),
  // 파트너 광고(Criteo · Appier 등)는 위 콜백이 아니라 onPartnerAd* 로 온다.
  onPartnerAdLoaded: () => print('파트너 로드 완료'),
  onPartnerAdImpression: (isLogSent) => print('파트너 노출 $isLogSent'),
);

// 위젯을 재빌드하지 않고 다시 로드
controller.loadAd();

팝업 (Popup) #

단일 / 복수(캐러셀) 팝업 모두 같은 위젯으로 처리합니다 — maxNumberOfAds로 구분.

final controller = NestAdsPopupController();

// 팝업은 SDK가 시스템 오버레이로 띄웁니다. 위젯이 레이아웃에 320×320
// 빈 자리를 차지하지 않도록 Offstage로 감쌉니다.
Offstage(
  child: NestAdsPopup(
    placementCode: 'SAMPLE_POPUP_BANNER_APP',
    controller: controller,
    options: const NestAdsPopupOptions(
      maxNumberOfAds: 5,
      popupCornerRadius: 12,
      leftButton: NestAdsPopupButtonOptions(
        fontColor: '#999999',
        color: '#FFFFFF',
      ),
      rightButton: NestAdsPopupButtonOptions(
        fontColor: '#FFFFFF',
        color: '#FF6B00',
      ),
    ),
    onAdLoaded: () => controller.showPopup(),
    onLeftButtonClicked: () => controller.dismissPopup(),
    onRightButtonClicked: () => controller.dismissPopup(),
  ),
);

스플래시 (Splash) #

단일 응답(SAMPLE_SPLASH)과 와이드 응답(SAMPLE_SPLASH_WIDE_IMAGE / SAMPLE_SPLASH_WIDE_VIDEO)을 같은 위젯으로 처리합니다 — 네이티브가 응답 타입에 따라 알맞은 콜백을 발화합니다.

NestAdsSplash(
  placementCode: 'SAMPLE_SPLASH',
  duration: 3,
  adSize: NestAdsAdSize.fill,
  options: const NestAdsSplashOptions(
    backgroundDurationPolicy: BackgroundBehaviorPolicy.continue_,
    videoPlayCondition: VideoPlayCondition.autoStart,
  ),
  onAdReachedDuration: () => Navigator.pushReplacement(
    context, MaterialPageRoute(builder: (_) => HomePage()),
  ),
  onVideoStarted: (isLogSent) => print('비디오 시작 $isLogSent'),
  onVideoEnded: (isLogSent) => print('비디오 종료 $isLogSent'),
);

광고 크기 지정 #

NestAdsAdSize(320, 50)  // FIXED — 지정한 width × height로 고정
NestAdsAdSize.fluid     // FLUID — 부모 너비에 맞추고 높이는 크리에이티브 비율로 자동 (원본보다 커지지 않음)
NestAdsAdSize.fill      // FILL  — 부모 너비를 채우고 높이는 너비 × 크리에이티브 비율 (원본보다 커질 수 있음)

런타임에 어떤 종류의 사이즈인지 구분하려면 isFluid / isFill / isFixed getter를 사용하세요. 호스트 위젯이 슬롯 레이아웃을 직접 잡을 때(예: NestAdsAdSize.fill이면 화면 전체, fixed면 명시 크기) 유용합니다.

배너의 FLUID / FILL은 부모 너비에 맞춥니다 — Row · 가로 ListView처럼 너비 제약이 없는 부모 안에서는 Expanded나 SizedBox로 너비를 주세요 (debug 빌드에서는 assert로 알려줍니다). 배너의 FLUID 높이는 소재 크기를 받기 전까지 100이고, 로드되면 소재 비율 높이로 바뀌어 아래 콘텐츠가 밀립니다. 부모 높이에 상한이 없는 FILL(예: 세로 스크롤 안)도 같습니다. 부모 높이에 상한이 있는 FILL은 슬롯이 부모 높이가 되고 크리에이티브는 너비 × 비율 높이로 그려집니다 — 남는 위아래 자리는 각 OS 네이티브와 같습니다 (Android 위쪽 · iOS 가운데 정렬). 밀림이 싫으면 고정 크기 NestAdsAdSize(width, height)를 쓰세요. 로드에 실패하면 높이가 0이 됩니다 (collapseOnFailure와 상관없이).

네이티브 factory가 자체적으로 FLUID → 네이티브 SDK 내부 FLUID_CONTAIN (Android 2.13.1+ / iOS NestAdsSizeType.fluidContain)으로 라우팅합니다 — Dart 측에서는 fluid 한 값만 알면 됩니다.

파트너 광고 (Moloco RTB) #

Moloco 광고는 파트너 SDK 가 그립니다. 파트너 SDK 는 플러그인에 들어 있지 않으므로 앱이 OS 별로 직접 추가합니다 (네이티브 SDK 와 같음). Criteo · Appier 는 추가 작업이 필요 없습니다.

1. 파트너 SDK 추가 #

Android — android/app/build.gradle:

dependencies {
    implementation 'com.nestads:nestads-partner-sdk-android-moloco:1.0.0'
}

android/app/src/main/AndroidManifest.xml 의 <application> 아래에 앱 키를 등록합니다. Android SDK 는 이 값으로 Moloco 를 초기화합니다:

<meta-data
    android:name="com.nestads.sdk.partner.moloco.APP_KEY"
    android:value="YOUR_MOLOCO_APP_KEY" />

앱의 Kotlin 버전이 2.1 미만이면 Kotlin metadata 버전 오류가 날 수 있습니다 — 네이티브 Android 가이드의 -Xskip-metadata-version-check 안내를 참고하세요.

iOS — Xcode 에서 ios/Runner.xcworkspace 를 열고 File → Add Package Dependencies... 로 https://github.com/wisebirds/nestads-partner-ios-sdk-moloco 를 Up to Next Major Version 1.0.0 으로 추가한 뒤, NestAdsPartnerMoloco 를 Runner 타깃에 넣습니다. 파트너 패키지는 Swift Package Manager 로만 제공됩니다 — CocoaPods 로 플러그인을 쓰는 앱도 이렇게 추가합니다.

2. 초기화 시 파트너 선언 #

await NestAdsService.initialize(
  partners: [NestAdsPartnerConfig.moloco(appKey: 'YOUR_MOLOCO_APP_KEY')],
);
  • appKey 는 iOS 에만 쓰입니다. Android 는 AndroidManifest 의 값을 씁니다.
  • iOS 는 여기서 선언하지 않으면 bid token 을 보내지 않고, Moloco 광고가 내려와도 그리지 못합니다 (9001).

3. 요청마다 RTB 참여 파트너 지정 #

NestAdsBanner(
  placementCode: 'SAMPLE_RAW_PARTNER_RTB', // Moloco RTB 테스트 게재위치
  adSize: NestAdsAdSize.fluid,
  targeting: const NestAdsTargeting(rtbPartners: {NestAdsPartner.moloco}),
  onPartnerAdLoaded: () => print('Moloco 로드'),
  onPartnerAdFailedToLoadWithError: (error) => print('실패 ${error.code}'),
);
  • 결과는 onPartnerAd* 콜백으로 옵니다. 낙찰 실패는 3000, Moloco SDK 오류는 9001.
  • 소재는 320×50 고정 크기입니다. 확대하지 않고 가운데 정렬합니다 (네이티브와 같음).

COVI 미디에이션 (Android 추가 설정) #

COVI 광고도 파트너 SDK 가 그립니다. iOS 는 Moloco 와 같은 방법으로 https://github.com/wisebirds/nestads-partner-ios-sdk-covi 패키지의 NestAdsPartnerCovi 를 Runner 에 추가하면 됩니다. Android 는 아래가 더 필요합니다.

1. 저장소와 의존성 — android/build.gradle 의 allprojects.repositories 에 COVI 저장소를 추가하고, android/app/build.gradle 에 파트너 SDK 와 AppCompat 을 추가합니다:

// android/build.gradle
allprojects {
    repositories {
        maven { url 'https://maven.covi.co.kr/public/' }
    }
}

// android/app/build.gradle
dependencies {
    implementation 'com.nestads:nestads-partner-sdk-android-covi:1.0.0'
    implementation 'androidx.appcompat:appcompat:1.7.0'
}

2. AppCompatActivity 호스트 — COVI SDK 는 AppCompatActivity 안에서만 광고를 그립니다. Flutter 기본 FlutterActivity 에서는 9000 (Covi SDK requires AppCompatActivity) 으로 실패합니다. MainActivity 를 AppCompatActivity 로 바꾸고 Flutter 화면은 FlutterFragment 로 띄웁니다:

import android.os.Bundle
import android.view.View
import android.widget.FrameLayout
import androidx.appcompat.app.AppCompatActivity
import io.flutter.embedding.android.FlutterEngineConfigurator
import io.flutter.embedding.android.FlutterFragment
import io.flutter.embedding.engine.FlutterEngine
import io.flutter.embedding.engine.plugins.util.GeneratedPluginRegister

class MainActivity : AppCompatActivity(), FlutterEngineConfigurator {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        val container = FrameLayout(this).apply { id = View.generateViewId() }
        setContentView(container)
        supportFragmentManager.beginTransaction()
            .add(container.id, FlutterFragment.createDefault(), "flutter")
            .commit()
    }

    // FlutterFragment 는 플러그인을 직접 등록하지 않으므로 여기서 등록합니다.
    override fun configureFlutterEngine(flutterEngine: FlutterEngine) {
        GeneratedPluginRegister.registerGeneratedPlugins(flutterEngine)
    }
}
  • res/values/styles.xml 의 LaunchTheme · NormalTheme 은 Theme.AppCompat 계열을 부모로 둡니다 (AppCompatActivity 의 요구 사항).

3. Moloco 와 함께 쓸 때 — COVI 를 Moloco 보다 먼저 선언합니다. 두 SDK 가 가져오는 동영상 라이브러리 (Moloco 는 ExoPlayer 2, COVI 는 Media3) 에 같은 이름의 레이아웃이 있어 먼저 선언한 쪽이 쓰입니다. Moloco 를 먼저 선언하면 COVI 광고를 그릴 때 앱이 비정상 종료될 수 있습니다.

dependencies {
    implementation 'com.nestads:nestads-partner-sdk-android-covi:1.0.0'
    implementation 'com.nestads:nestads-partner-sdk-android-moloco:1.0.0'
}

AdFit 미디에이션 #

AdFit 광고도 파트너 SDK 가 그립니다. 추가 설정은 없습니다 — 파트너 SDK 만 추가합니다.

  • Android — android/build.gradle 의 allprojects.repositories 에 Kakao 저장소를, android/app/build.gradle 에 파트너 SDK 를 추가합니다:
// android/build.gradle
allprojects {
    repositories {
        maven { url 'https://devrepo.kakao.com/nexus/content/groups/public/' }
    }
}

// android/app/build.gradle
dependencies {
    implementation 'com.nestads:nestads-partner-sdk-android-adfit:1.1.0'
}
  • iOS — Moloco 와 같은 방법으로 https://github.com/wisebirds/nestads-partner-ios-sdk-adfit 패키지의 NestAdsPartnerAdFit 을 Runner 에 추가합니다.

에러 로깅 #

위젯 콜백 디스패치에서 발생한 Dart 예외를 자동으로 잡아 NestAds 에러 로그 엔드포인트로 PUT 합니다 — 네이티브 SDK / JS SDK와 동일한 페이로드 / AES 인코딩.

호스트 코드의 try/catch 사이트에서도 직접 호출할 수 있습니다:

try {
  // ...
} catch (error, stackTrace) {
  NestAdsErrorReporter.report(
    error,
    stackTrace: stackTrace,
    viewName: '[MyHostWidget._handleSomething]',
    placementCode: 'SAMPLE_BANNER',
  );
}

환경(서버 URL / 시크릿 키)을 전환하려면 NestAdsEnvironments.set(...)을 호출합니다. 기본은 NestAdsEnvironment.prod — 개발 · 테스트 앱만 바꿉니다:

NestAdsEnvironments.set(NestAdsEnvironment.dev);

지원 환경: dev / prod / pg1 / pg2 / pg3.

호환성 매트릭스 #

Plugin Android SDK iOS SDK
0.1.x 2.13.x 2.13.x

라이선스 #

MIT

0
likes
0
points
964
downloads

Publisher

unverified uploader

Weekly Downloads

Official NestAds SDK for Flutter. Banner, popup, and splash ads with native Android and iOS integration.

Homepage
Repository
View/report issues

License

unknown (license)

Dependencies

crypto, encrypt, flutter, http, visibility_detector

More

Packages that depend on nestads_sdk_flutter_plugin

Packages that implement nestads_sdk_flutter_plugin