nestads_sdk_flutter_plugin 0.2.0-dev.2
nestads_sdk_flutter_plugin: ^0.2.0-dev.2 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'),
// 랜딩 정보가 필요하면 — CUSTOMLINK 는 SDK 가 랜딩을 열지 않으니 앱이 url 을 직접 엽니다
onAdClickedWithLandingInfo: (isLogSent, landingInfo) {
final url = landingInfo?.url; // 소재에 랜딩 URL 이 없으면 null
if (landingInfo?.type == NestAdsLandingUrlType.customLink && url != null) {
openMyLanding(url);
}
},
// 실패 종류는 코드로 구분한다 (양 OS 같음). 예: 3000 광고 없음, 5001 시간 초과
onAdFailedToLoadWithError: (error) => print('실패 ${error.code} ${error.message}'),
// 파트너 광고(Criteo · Appier 등)는 위 콜백이 아니라 onPartnerAd* 로 온다.
onPartnerAdLoaded: () => print('파트너 로드 완료'),
onPartnerAdImpression: (isLogSent) => print('파트너 노출 $isLogSent'),
);
// 위젯을 재빌드하지 않고 다시 로드
controller.loadAd();
// 파트너 동영상 광고(COVI 등) 재생 제어 — 재생 제어가 없는 광고면 false
// replay 는 iOS, stop 은 Android 에만 있습니다
final sent = await controller.controlPartnerPlayback(
NestAdsPartnerPlaybackCommand.pause,
);
로드블록 #
같은 화면의 광고가 같은 블록으로 묶이도록, 화면에 들어올 때마다 번호표(block ID)를 새로 받습니다.
@override
void initState() {
super.initState();
// 화면 진입마다 한 번, 이 화면의 어떤 광고 요청보다 먼저. 광고 뷰마다 부르지 않습니다.
NestAdsService.refreshBlockId();
}
Future<void> _onPullToRefresh() async {
// 새로고침도 새 번호표 — 광고를 다시 요청하기 전에 부릅니다.
// 연계형 서브 화면은 제외 — 두 번째 호출이 메인 화면과의 연계를 끊습니다.
await NestAdsService.refreshBlockId();
_bannerController.loadAd();
}
- 전면형 자리만 있는 화면은
refreshBlockId(screenType: NestAdsRoadBlockScreenType.singleOnly)— 선언하지 않으면 연계형 메인 화면 다음에 올 때 직전 화면의 연계 상태가 남아 이 화면의 전면형 광고가 안 나옵니다 - 연계형 메인 · 서브 화면과 서브 · 전면형이 섞인 화면, 로드블록 자리가 없는 화면은
screenType을 넘기지 않습니다 — 연계형 화면에 넘기면 연계가 끊겨 연계형 광고가 안 나갑니다 - 지금 번호표는
NestAdsService.getBlockId()(발급 전이거나 로드블록 구성을 받지 못했으면 null)
팝업 (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,
// 와이드 비디오 응답에만 쓰입니다. 생략하면 SDK 기본값 (auto)
videoQuality: NestAdsVideoQuality.auto,
),
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면 명시 크기 — 단 파트너 광고가 나가면 크기가 바뀌므로 높이를 그 값으로 묶지 마세요) 유용합니다.
adSize를 생략하면 FLUID입니다. 0.1.6-dev.3까지는 FIXED 320×50이었습니다. 예전 슬롯을 그대로 쓰려면adSize: NestAdsAdSize(320, 50)을 넘기세요. 배너의 FLUID / FILL은 부모 너비에 맞춥니다 —Row· 가로ListView처럼 너비 제약이 없는 부모 안에서는Expanded나SizedBox로 너비를 주세요 (debug 빌드에서는 assert로 알려줍니다). 배너의 FLUID 높이는 소재 크기를 받기 전까지initialHeight(기본 100)이고, 로드되면 소재 비율 높이로 바뀌어 아래 콘텐츠가 밀립니다. 부모 높이에 상한이 없는 FILL(예: 세로 스크롤 안)도 같습니다. 부모 높이에 상한이 있는 FILL은 슬롯이 부모 높이가 되고 크리에이티브는 너비 × 비율 높이로 그려집니다 — 남는 위아래 자리는 각 OS 네이티브와 같습니다 (Android 위쪽 · iOS 가운데 정렬). 밀림이 싫으면 지면 소재 높이를initialHeight로 주거나 (아래 예), 고정 크기NestAdsAdSize(width, height)를 쓰세요 — 단 파트너 광고가 나가면 고정 크기 슬롯도 바뀔 수 있습니다 (다음 줄). 로드에 실패하면 높이가 0이 됩니다 (collapseOnFailure와 상관없이). 고정 크기(FIXED) 슬롯에 파트너 광고(미디에이션 · Criteo 네이티브)가 나가면 슬롯은 각 OS SDK가 그 광고에 정한 크기를 따릅니다 — 미디에이션 광고는 파트너 광고에 따라 지정 크기와 달라질 수 있고 (예: iOS의 AdFit 네이티브 카드는 더 높음), Criteo 네이티브는 지정 너비(화면 너비까지) × 내용 높이입니다. 파트너 RTB 배너와 자사 광고는 지정 크기 그대로입니다.
// 320×50 소재만 나가는 지면 — 시작 높이를 소재 높이에 맞추면 로드 때 밀리지 않습니다
NestAdsBanner(
placementCode: 'SAMPLE_IMAGE_BANNER/320/50',
adSize: NestAdsAdSize.fluid,
initialHeight: 50,
);
initialHeight는 1 이상이어야 합니다. Android는 높이가 0인 슬롯에 네이티브 뷰를 만들지 않아 광고를 요청하지 않습니다 (debug 빌드는 assert로 알려주고, release 빌드는 1로 올려 씁니다).
네이티브 factory가 자체적으로
FLUID→ 네이티브 SDK 내부FLUID_CONTAIN(Android 2.13.1+ / iOSNestAdsSizeType.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안내를 참고하세요.
Flutter 의 release 빌드는 R8 을 기본으로 켭니다. Moloco SDK 는 Unity LevelPlay 가 있을 때만 쓰는 클래스를 참조하므로, LevelPlay 가 없는 앱은 R8 이 Missing class com.unity3d.mediation.LevelPlay 로 release 빌드를 멈춥니다. android/app/proguard-rules.pro 에 아래 두 줄을 추가합니다 (파일이 없으면 만듭니다 — Flutter 가 이 파일을 자동으로 읽습니다):
-dontwarn com.unity3d.mediation.LevelPlay
-dontwarn com.unity3d.mediation.impression.LevelPlayImpressionDataListener
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.1 으로 추가한 뒤, NestAdsPartnerMoloco 를 Runner 타깃에 넣습니다. 파트너 패키지는 Swift Package Manager 로만 제공됩니다 — CocoaPods 로 플러그인을 쓰는 앱도 이렇게 추가합니다. 플러그인이 쓰는 iOS SDK 2.20.1 은 NestAdsPartnerMoloco 1.0.1 이상에서만 Moloco 광고를 그립니다 (1.0.0 이면 Moloco 광고를 건너뜁니다).
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.content.Intent
import android.os.Bundle
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 {
private lateinit var flutterFragment: FlutterFragment
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
// Activity 가 다시 만들어지면 FragmentManager 가 복원한 fragment 를 그대로 씁니다.
val restoredFragment = supportFragmentManager.findFragmentByTag(FLUTTER_FRAGMENT_TAG) as FlutterFragment?
flutterFragment = restoredFragment
?: FlutterFragment.withNewEngine()
// 시스템 뒤로 가기를 Flutter Navigator 로 보냅니다.
.shouldAutomaticallyHandleOnBackPressed(true)
.build<FlutterFragment>()
.also { fragment ->
supportFragmentManager.beginTransaction()
.add(android.R.id.content, fragment, FLUTTER_FRAGMENT_TAG)
.commit()
}
}
// FlutterFragment 는 플러그인을 직접 등록하지 않으므로 여기서 등록합니다.
override fun configureFlutterEngine(flutterEngine: FlutterEngine) {
GeneratedPluginRegister.registerGeneratedPlugins(flutterEngine)
}
override fun cleanUpFlutterEngine(flutterEngine: FlutterEngine) {}
// 아래는 FlutterActivity 가 하던 일을 FlutterFragment 로 넘깁니다.
override fun onPostResume() {
super.onPostResume()
flutterFragment.onPostResume()
}
override fun onNewIntent(intent: Intent) {
super.onNewIntent(intent)
flutterFragment.onNewIntent(intent)
}
override fun onRequestPermissionsResult(
requestCode: Int,
permissions: Array<String>,
grantResults: IntArray,
) {
super.onRequestPermissionsResult(requestCode, permissions, grantResults)
flutterFragment.onRequestPermissionsResult(requestCode, permissions, grantResults)
}
override fun onUserLeaveHint() {
super.onUserLeaveHint()
flutterFragment.onUserLeaveHint()
}
override fun onTrimMemory(level: Int) {
super.onTrimMemory(level)
flutterFragment.onTrimMemory(level)
}
private companion object {
const val FLUTTER_FRAGMENT_TAG = "flutter"
}
}
res/values/styles.xml의LaunchTheme·NormalTheme은Theme.AppCompat계열을 부모로 둡니다 (AppCompatActivity의 요구 사항).FlutterEngineConfigurator의 두 메서드를 모두 구현합니다 —cleanUpFlutterEngine이 없으면 컴파일되지 않습니다.shouldAutomaticallyHandleOnBackPressed(true)가 없으면 시스템 뒤로 가기가 Flutter 화면 스택을 거치지 않아, 하위 화면에서 뒤로 가기를 눌러도 앱이 닫힙니다.onNewIntent를 넘기지 않으면 앱이 떠 있을 때 들어온 딥링크 (예: 로그인 콜백) 가 Flutter 에 전달되지 않습니다. 나머지 메서드도FlutterActivity가 Flutter 에 넘기던 이벤트입니다 (Flutter add-to-app 문서의FlutterFragment호스트 요구 사항).
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.0 – 0.1.1 | 2.11.0 | 2.11.0 |
| 0.1.2 – 0.1.5 | 2.13.x | 2.13.x |
| 0.1.6-dev.1 – 0.1.6-dev.3 | 2.18.0 | 2.18.1 |
| 0.2.0-dev.1 – 0.2.0-dev.2 | 2.20.1 | 2.20.1 |
라이선스 #
MIT