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();

  // 운영 앱: 실패 시 PlatformException을 직접 처리
  try {
    await NestAdsService.initialize();
  } on PlatformException catch (e) {
    // 폴백 / 로깅
  }

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

  runApp(const MyApp());
}

⚠ initialize()를 호출하지 않으면 네이티브 SDK가 준비되지 않아 광고 위젯이 정상적으로 로드되지 않습니다. ⚠ initialize()는 실패 시 PlatformException을 그대로 던집니다 — 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(Android only)
  targeting: const {
    'country': 'KR',
    'age': 25,
  },
  controller: controller,
  onAdLoaded: () => print('로드 완료'),
  onAdImpression: (isLogSent) => print('노출 $isLogSent'),
  onAdClicked: (isLogSent) => print('클릭 $isLogSent'),
);

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

팝업 (Popup)

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

final controller = NestAdsPopupController();

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면 명시 크기) 유용합니다.

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

에러 로깅

위젯 콜백 디스패치에서 발생한 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.dev:

NestAdsEnvironments.set(NestAdsEnvironment.prod);

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

호환성 매트릭스

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

라이선스

MIT

Libraries

nestads_sdk_flutter_plugin