StageUp
모바일 SDK프로모션

Flutter

Flutter 애플리케이션에서 NBase AdStage SDK를 사용한 프로모션 관리 가이드입니다.

1. 개요

  • 프로모션(배너/팝업/네이티브)을 조회하고 열어 사용자에게 표시하며, 노출/클릭을 추적합니다.
  • 배너 타입, 타겟, 노출 제한 등 조건을 지정해 원하는 프로모션만 선택적으로 노출할 수 있습니다.

2. 빠른 시작

2.1 SDK 설치

# pubspec.yaml
dependencies:
	nbase_ad_flutter_sdk: ^1.0.1
flutter pub get

2.2 기본 설정

Android 설정

android/app/src/main/kotlin/.../MainActivity.kt:

import android.os.Bundle
import io.flutter.embedding.android.FlutterActivity
import io.nbase.adapter.adstage.AdStageSDK
 
class MainActivity : FlutterActivity() {
		override fun onCreate(savedInstanceState: Bundle?) {
				super.onCreate(savedInstanceState)
 
				// API 키 설정
				AdStageSDK.setApiKey("YOUR_API_KEY")
		}
}

iOS 설정

iOS는 별도 네이티브 설정 없이 Flutter에서 SDK 초기화만 하면 됩니다.

3. Flutter 구현

3.1 SDK 초기화

import 'package:flutter/material.dart';
import 'package:nbase_ad_flutter_sdk/nbase_ad_flutter_sdk.dart';
 
class MyApp extends StatefulWidget {
	@override
	State<MyApp> createState() => _MyAppState();
}
 
class _MyAppState extends State<MyApp> {
	@override
	void initState() {
		super.initState();
		_initializeSDK();
	}
 
	Future<void> _initializeSDK() async {
		try {
			await NbaseAdFlutterSdk.initializeAdStageSDK({
				'apiKey': 'YOUR_API_KEY',
			});
		} catch (e) {
			debugPrint('SDK 초기화 실패: $e');
		}
	}
 
	@override
	Widget build(BuildContext context) {
		return MaterialApp(home: Scaffold(body: Container()));
	}
}

4. 프로모션 기능

4.1 프로모션 열기

특정 조건에 맞는 프로모션을 열어 사용자에게 표시합니다.

Future<void> showPromotion(BuildContext context) async {
	try {
		final result = await NbaseAdFlutterSdk.openPromotion(
			bannerType: 'NATIVE',        // 배너 타입 (BANNER | POPUP | NATIVE 등)
			targetAudience: 'new_user',  // 타겟 오디언스 (선택)
			showTodayButton: true,       // "오늘 하루 보지 않기" 버튼 표시 여부 (선택)
		);
 
		if (result.success && result.url.isNotEmpty) {
			debugPrint('프로모션 URL: ${result.url}');
 
			// WebView 또는 브라우저로 프로모션 페이지 열기
			await _openPromotionPage(context, result.url);
		} else {
			debugPrint('표시할 프로모션이 없습니다.');
		}
	} catch (e) {
		debugPrint('프로모션 열기 실패: $e');
	}
}
 
Future<void> _openPromotionPage(BuildContext context, String url) async {
	// 예: webview_flutter 패키지로 WebView 화면으로 이동
	Navigator.push(
		context,
		MaterialPageRoute(
			builder: (context) => PromotionWebView(url: url),
		),
	);
}

4.2 프로모션 목록 조회

사용 가능한 프로모션 목록을 조회하여 앱 내 리스트/캐러셀 등에 노출합니다.

List<Map<String, dynamic>> _promotions = [];
 
Future<void> loadPromotionList() async {
	try {
		final result = await NbaseAdFlutterSdk.getPromotionList(
			bannerType: 'BANNER',  // 배너 타입 필터
			limit: 10,             // 최대 조회 개수
		);
 
		debugPrint('총 ${result.promotions.length}개의 프로모션 발견');
 
		for (final promotion in result.promotions) {
			debugPrint('프로모션 ID: ${promotion['id']}');
			debugPrint('제목: ${promotion['title']}');
			debugPrint('설명: ${promotion['description']}');
			debugPrint('이미지 URL: ${promotion['imageUrl']}');
			debugPrint('링크 URL: ${promotion['linkUrl']}');
			debugPrint('시작일: ${promotion['startDate']}');
			debugPrint('종료일: ${promotion['endDate']}');
			debugPrint('---');
		}
 
		// UI에 바인딩
		_promotions = List<Map<String, dynamic>>.from(result.promotions);
	} catch (e) {
		debugPrint('프로모션 목록 로드 실패: $e');
	}
}

5. 고급 설정

5.1 다양한 배너 타입 사용

// 팝업 형태 프로모션 열기
Future<void> showPopupPromotion() async {
	final result = await NbaseAdFlutterSdk.openPromotion(
		bannerType: 'POPUP',
		targetAudience: 'all',
		showTodayButton: true,
	);
	if (result.success && result.url.isNotEmpty) {
		debugPrint('팝업 프로모션 URL: ${result.url}');
	}
}
 
// 배너 형태 프로모션 목록
Future<void> getBannerPromotions() async {
	final result = await NbaseAdFlutterSdk.getPromotionList(
		bannerType: 'BANNER',
		limit: 5,
	);
	debugPrint('배너 프로모션 ${result.promotions.length}개');
}
 
// 네이티브 형태 프로모션 목록
Future<void> getNativePromotions() async {
	final result = await NbaseAdFlutterSdk.getPromotionList(
		bannerType: 'NATIVE',
		limit: 10,
	);
	debugPrint('네이티브 프로모션 ${result.promotions.length}개');
}

6. 문제 해결

  • 프로모션이 표시되지 않음: API 키와 SDK 초기화 완료 여부 확인, 네트워크 연결 확인
  • Android 빌드 오류: flutter clean && flutter pub get 실행 후 재빌드, Manifest/의존성 확인
  • iOS 빌드 오류: cd ios && pod install 실행 후 재빌드, 권한/설정 확인

참고: 지원 버전 예시 — Flutter 3.10.0+, iOS 12.0+, Android API 21+

목차