adwhale_sdk_flutter #

ADwhale Android 네이티브 광고 미디에이션 SDK를 Flutter 환경에서 사용할 수 있도록 제공하는 공식 SDK입니다.

• Android 네이티브 SDK 기반
• 배너, 전면, 보상형, 네이티브 광고 지원

Installation #

flutter pub add adwhale_sdk_flutter

Version Policy #

본 SDK는 Android 네이티브 SDK 버전과의 대응 관계를 명확히 유지하기 위해 다음과 같은 버전 규칙을 사용합니다.

• 앞 세 자릿수(Major.Minor.Patch) 는 Android SDK 버전과 동일
• Flutter 전용 수정 사항은 Patch 값을 확장하여 관리

Version Mapping Example #

Version Usage Guide #

프로젝트 상황에 따라 아래 방식을 권장합니다.

Android SDK 버전에 고정하여 사용하는 경우 (권장) #

운영 안정성을 중시하는 경우

{
  adwhale_sdk_flutter: ~2.7.2+7
}

• Android SDK 2.7.2 기반 유지
• Flutter 핫픽스만 자동 반영

• =2.7.2+7 <2.8.0 범위

특정 버전을 완전히 고정하여 사용하는 경우 #

{
  adwhale_sdk_flutter: 2.7.2+7
}

• 버전 변경 없음
• 재현성, 장애 분석에 최적
• QA / 장애 재현 환경
• 장기 유지 브랜치

Example Project #

SDK 동작을 바로 확인할 수 있는 example 프로젝트를 제공합니다.

• Flutter 샘플

flutter pub add adwhale_sdk_flutter

Supported Features #

• SDK 초기화
• 배너 광고
• 전면 광고
• 보상형 광고
• 네이티브 광고 (Template / Custom)
• 광고 이벤트 리스너 제공

iOS 실기기 실행 / App Store 배포 #

실기기에서 "Development team" 오류가 나는 이유 #

• 시뮬레이터: 코드 서명이 필요 없어 Development team 없이 실행됩니다.
• 실제 기기(USB): iOS는 기기 설치 시 Apple 개발자 팀(Development team) 서명을 요구합니다.

해결: Xcode에서 example/ios/Runner.xcworkspace 열기 → Runner 타깃 → Signing & Capabilities → Team에서 본인 Apple ID(팀) 선택. (무료 Apple ID로도 실기기 테스트 가능)

실기기에서 "신뢰하지 않는 개발자" / Runner가 실행되지 않을 때 #

무료 Apple ID로 서명한 앱을 처음 실기기에 설치한 경우, iOS가 개발자를 "신뢰하지 않음"으로 두어 앱 실행을 막습니다.
이때 Xcode에서는 "Runner failed to launch or exited before the debugger could attach" 같은 메시지가 나올 수 있습니다.

해결 (iPhone에서 한 번만 하면 됨)

1. iPhone 설정 → 일반 → VPN 및 기기 관리 (또는 기기 관리 / 프로필 및 기기 관리)
2. 개발자 앱 아래에서 본인 Apple ID(예: junhojohn@gmail.com) 항목 선택
3. "[Apple ID]을(를) 신뢰" 탭 → 신뢰 확인
4. 이후부터는 해당 기기에서 같은 Apple ID로 서명한 앱이 정상 실행됩니다.

App Store 배포 #

이 플러그인을 사용한 앱을 App Store에 제출·배포하는 데 문제 없습니다.
실기기 테스트·스토어 제출 시에는 위와 같이 서명(Development team, 프로비저닝 프로필)을 설정하고, iOS 앱 필수 설정(Info.plist, GADApplicationIdentifier 등)만 준수하면 됩니다.

Troubleshooting #

Android 빌드 오류 #

cd android
./gradlew clean

iOS: "PhaseScriptExecution failed with a nonzero exit code" #

Xcode 빌드 시 Run Script 단계 중 하나가 실패할 때 나옵니다. 어떤 스크립트에서 실패했는지부터 확인하세요.

1) 실패한 스크립트 확인

• Xcode에서 Product → Build 후 왼쪽 Report navigator (⌘9) → 최근 빌드 선택
• 빌드 로그에서 PhaseScriptExecution 또는 Run Script 근처의 빨간 에러 메시지 확인
• 실패한 스크립트 이름(예: "Run Script", "Embed Pods Frameworks")과 그 아래 출력 내용 확인

2) 자주 쓰는 해결 방법

# example 기준
cd example
flutter clean
flutter pub get
cd ios
rm -rf Pods Podfile.lock
pod install
cd ..
flutter build ios

• Podfile.lock 불일치라면: example/ios에서 pod install 한 번 더 실행.
• Flutter 스크립트 실패라면: 터미널에서 flutter build ios로 빌드해 보기 (Xcode만 쓸 때는 FLUTTER_ROOT 등이 없어서 실패할 수 있음)
• 실기기/서명 관련이라면: Development team·신뢰 설정 확인

환경 점검 #

flutter doctor

Changelog #

Learn More #

• ADwhale Flutter 가이드
• Flutter Documentation