Adrop Flutter SDK를 사용하면 Flutter 앱에서 다양한 광고 포맷을 쉽게 연동할 수 있습니다.
지원 광고 포맷
| 포맷 | 설명 |
|---|
| 배너 광고 | 화면 일부에 표시되는 직사각형 광고 |
| 네이티브 광고 | 앱 콘텐츠와 자연스럽게 어우러지는 광고 |
| 전면 광고 | 전체 화면을 덮는 광고 |
| 리워드 광고 | 보상을 제공하는 전체 화면 광고 |
| 팝업 광고 | 팝업 형태로 표시되는 광고 |
요구 사항
Flutter
- Flutter SDK 3.3.0 이상
- Dart SDK 2.18.0 이상
Android
- API 레벨 23 (Android 6.0) 이상
compileSdkVersion 34- Kotlin 2.1.0 이상
- Gradle 7.6.3 이상
- Jetpack (AndroidX) 사용
iOS
1. 패키지 설치
프로젝트 디렉토리에서 다음 명령어를 실행합니다.
flutter pub add adrop_ads_flutter
2. iOS 설정
ios/Podfile을 수정합니다.
Pod을 설치합니다.
cd ios && pod install --repo-update && cd ..
3. 설정 파일 추가
Android
- 애드컨트롤 콘솔에서 adrop_service.json 파일을 다운로드합니다.
- 파일을
android/app/src/main/assets/ 디렉토리에 복사합니다.
android/app/src/main/assets/adrop_service.json
iOS
- 애드컨트롤 콘솔에서 adrop_service.json 파일을 다운로드합니다.
- Xcode에서 프로젝트 루트에 파일을 추가합니다.
- 모든 타겟에 파일을 추가하도록 선택합니다.
초기화
앱 시작 시 SDK를 초기화합니다. 일반적으로 main.dart에서 호출합니다.
import 'package:adrop_ads_flutter/adrop_ads_flutter.dart';
void main() {
runApp(const MyApp());
}
class MyApp extends StatefulWidget {
const MyApp({super.key});
@override
State<MyApp> createState() => _MyAppState();
}
class _MyAppState extends State<MyApp> {
@override
void initState() {
super.initState();
_initializeAdrop();
}
Future<void> _initializeAdrop() async {
// false: 테스트 모드, true: 프로덕션 모드
await Adrop.initialize(false);
}
@override
Widget build(BuildContext context) {
return MaterialApp(
home: HomeScreen(),
);
}
}
초기화 옵션
await Adrop.initialize(
production, // bool: 프로덕션 모드 여부
targetCountries: targetCountries, // List<String>?: 타겟 국가 코드 배열 (선택)
useInAppBrowser: useInAppBrowser // bool?: iOS 인앱 브라우저 사용 여부 (선택)
);
| 파라미터 | 타입 | 필수 | 설명 |
|---|
production | bool | Y | true: 프로덕션 모드, false: 테스트 모드 |
targetCountries | List<String> | N | 광고를 표시할 국가 코드 (예: ['KR', 'US']) |
useInAppBrowser | bool | N | iOS에서 인앱 브라우저 사용 여부 (기본값: false) |
// 기본 초기화 (테스트 모드)
await Adrop.initialize(false);
// 프로덕션 모드 + 특정 국가 타겟팅
await Adrop.initialize(true, targetCountries: ['KR', 'JP', 'US']);
// 프로덕션 모드 + iOS 인앱 브라우저 사용
await Adrop.initialize(true, useInAppBrowser: true);
테마 설정
광고 UI 테마를 설정합니다.
import 'package:adrop_ads_flutter/adrop_ads_flutter.dart';
// 테마 설정
await Adrop.setTheme(AdropTheme.auto); // 시스템 설정 따름
await Adrop.setTheme(AdropTheme.light); // 라이트 모드
await Adrop.setTheme(AdropTheme.dark); // 다크 모드
| 테마 | 설명 |
|---|
AdropTheme.auto | 시스템 설정에 따라 자동 전환 |
AdropTheme.light | 라이트 모드 |
AdropTheme.dark | 다크 모드 |
사용자 식별자 설정
타겟팅 광고를 위해 사용자 식별자(UID)를 설정합니다.
import 'package:adrop_ads_flutter/adrop_ads_flutter.dart';
// 사용자 로그인 후
await Adrop.setUID('user_123');
// 로그아웃 시
await Adrop.setUID('');
UID는 SHA-256으로 해시되어 전송됩니다. 이메일, 전화번호 등 개인정보를 직접 전달하지 마세요.
테스트 유닛 ID
개발 및 테스트 시 다음 테스트 유닛 ID를 사용하세요.
| 포맷 | 테스트 유닛 ID |
|---|
| 배너 (320x50) | PUBLIC_TEST_UNIT_ID_320_50 |
| 배너 (320x100) | PUBLIC_TEST_UNIT_ID_320_100 |
| 네이티브 | PUBLIC_TEST_UNIT_ID_NATIVE |
| 전면 광고 | PUBLIC_TEST_UNIT_ID_INTERSTITIAL |
| 리워드 광고 | PUBLIC_TEST_UNIT_ID_REWARDED |
| 팝업 광고 (하단) | PUBLIC_TEST_UNIT_ID_POPUP_BOTTOM |
| 팝업 광고 (중앙) | PUBLIC_TEST_UNIT_ID_POPUP_CENTER |
| 스플래시 광고 | PUBLIC_TEST_UNIT_ID_SPLASH |
프로덕션 배포 전에 반드시 실제 유닛 ID로 교체하세요.
에러 코드
SDK에서 발생할 수 있는 에러 코드입니다.
| 에러 코드 | 설명 |
|---|
network | 네트워크 오류 |
internal | 내부 오류 |
initialize | SDK 초기화 오류 |
invalidUnit | 유효하지 않은 유닛 ID |
notTargetCountry | 타겟 국가가 아님 |
inactive | 비활성화된 광고 |
adNoFill | 노출할 광고 없음 |
adLoadDuplicate | 중복 로드 요청 |
adLoading | 로드 진행 중 |
adEmpty | 빈 광고 |
adShown | 이미 표시된 광고 |
adHideForToday | 오늘 숨김 처리된 광고 |
adLandscapeUnsupported | 가로 모드 미지원 |
backfillNoFill | 백필 광고 없음 |
import 'package:adrop_ads_flutter/adrop_ads_flutter.dart';
// 에러 처리 예시
if (errorCode == AdropErrorCode.adNoFill) {
debugPrint('노출할 광고가 없습니다.');
}
문제 해결
iOS 빌드 오류
Swift 버전 호환성 문제가 발생할 경우, ios/Podfile의 post_install 블록에 다음을 추가하세요.
post_install do |installer|
installer.pods_project.targets.each do |target|
target.build_configurations.each do |config|
config.build_settings['BUILD_LIBRARY_FOR_DISTRIBUTION'] = 'YES'
end
end
end
Android 빌드 오류
Kotlin 버전이 맞지 않는 경우, android/build.gradle에서 Kotlin 버전을 확인하세요.
buildscript {
ext.kotlin_version = '2.1.0'
}
다음 단계
