배너 광고 - Ad Control Help Center

개요

배너 광고는 화면의 일부 영역에 표시되는 직사각형 광고입니다. AdropBannerView 위젯을 사용하여 손쉽게 구현할 수 있습니다.

주요 특징

화면 상단, 하단 또는 중간에 고정 배치 가능
이미지 및 동영상 광고 지원
콜백을 통한 광고 이벤트 처리
광고 메타데이터 제공 (크리에이티브 ID, 캠페인 ID 등)

개발 환경에서는 테스트 유닛 ID를 사용하세요: PUBLIC_TEST_UNIT_ID_320_100

AdropBannerView

생성자

AdropBannerView({
  required String unitId,
  String? contextId,
  AdropBannerListener? listener,
})

파라미터

파라미터	타입	필수	설명
`unitId`	`String`	Y	애드컨트롤 콘솔에서 생성한 유닛 ID
`contextId`	`String`	N	문맥 타겟팅에 사용할 컨텍스트 ID (1.17.0+)
`listener`	`AdropBannerListener`	N	광고 이벤트 리스너

속성

속성	타입	설명
`contextId`	`String?`	생성자에 전달한 컨텍스트 ID
`creativeSize`	`CreativeSize?`	광고 크리에이티브 크기
`adSize`	`Size?`	배너 뷰의 크기 설정

메서드

메서드	반환 타입	설명
`load()`	`Future<void>`	광고를 로드합니다
`dispose()`	`Future<void>`	리소스를 해제합니다

기본 사용법

import 'package:flutter/material.dart';
import 'package:adrop_ads_flutter/adrop_ads_flutter.dart';

class BannerExample extends StatefulWidget {
  const BannerExample({super.key});

  @override
  State<BannerExample> createState() => _BannerExampleState();
}

class _BannerExampleState extends State<BannerExample> {
  bool isLoaded = false;
  late AdropBannerView bannerView;

  @override
  void initState() {
    super.initState();

    bannerView = AdropBannerView(
      unitId: 'YOUR_UNIT_ID',
      listener: AdropBannerListener(
        onAdReceived: (unitId, metadata) {
          debugPrint('배너 광고 수신 성공: $unitId');
          setState(() {
            isLoaded = true;
          });
        },
        onAdClicked: (unitId, metadata) {
          debugPrint('배너 광고 클릭: $unitId');
        },
        onAdImpression: (unitId, metadata) {
          debugPrint('배너 광고 노출: $unitId');
        },
        onAdFailedToReceive: (unitId, errorCode) {
          debugPrint('배너 광고 수신 실패: $unitId, $errorCode');
          setState(() {
            isLoaded = false;
          });
        },
      ),
    );

    // 광고 로드
    bannerView.load();
  }

  @override
  void dispose() {
    bannerView.dispose();
    super.dispose();
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('배너 광고 예제')),
      body: Column(
        children: [
          // 메인 콘텐츠
          Expanded(
            child: Center(
              child: const Text('메인 콘텐츠'),
            ),
          ),
          // 배너 광고
          if (isLoaded)
            SizedBox(
              width: MediaQuery.of(context).size.width,
              height: 80,
              child: bannerView,
            ),
        ],
      ),
    );
  }
}

AdropBannerListener

배너 광고 이벤트를 처리하는 리스너입니다.

콜백 함수

AdropBannerListener(
  onAdReceived: (String unitId, Map<String, dynamic>? metadata) {
    // 광고 수신 성공
  },
  onAdClicked: (String unitId, Map<String, dynamic>? metadata) {
    // 광고 클릭
  },
  onAdImpression: (String unitId, Map<String, dynamic>? metadata) {
    // 광고 노출
  },
  onAdFailedToReceive: (String unitId, AdropErrorCode errorCode) {
    // 광고 수신 실패
  },
  onAdVideoStart: (String unitId) {
    // 동영상 광고 재생 시작
  },
  onAdVideoEnd: (String unitId) {
    // 동영상 광고 재생 종료
  },
)

콜백 설명

콜백	설명
`onAdReceived`	광고 수신 성공 시 호출
`onAdClicked`	광고 클릭 시 호출
`onAdImpression`	광고 노출 시 호출
`onAdFailedToReceive`	광고 수신 실패 시 호출
`onAdVideoStart`	동영상 광고 재생 시작 시 호출
`onAdVideoEnd`	동영상 광고 재생 종료 시 호출

메타데이터

onAdReceived, onAdClicked, onAdImpression 콜백에서 메타데이터를 받을 수 있습니다.

onAdReceived: (unitId, metadata) {
  debugPrint('크리에이티브 ID: ${metadata?['creativeId']}');
  debugPrint('트랜잭션 ID: ${metadata?['txId']}');
  debugPrint('캠페인 ID: ${metadata?['campaignId']}');
  debugPrint('목적지 URL: ${metadata?['destinationURL']}');
  debugPrint('브라우저 타겟: ${metadata?['browserTarget']}');
}

필드	타입	설명
`creativeId`	`String`	크리에이티브 ID
`txId`	`String`	트랜잭션 ID
`campaignId`	`String`	캠페인 ID
`destinationURL`	`String`	목적지 URL
`browserTarget`	`int?`	브라우저 타겟 (0: 외부 브라우저, 1: 인앱 브라우저)

크리에이티브 크기는 메타데이터가 아닌 bannerView.creativeSize?.width 및 bannerView.creativeSize?.height로 접근합니다.

광고 크기

배너 광고는 유닛에 설정한 크기에 맞춰 컨테이너 크기를 지정해야 합니다.

일반적인 배너 크기

크기	테스트 유닛 ID	용도
320 x 50	`PUBLIC_TEST_UNIT_ID_320_50`	소형 배너
320 x 100	`PUBLIC_TEST_UNIT_ID_320_100`	중형 배너

고정 크기 사용

SizedBox(
  width: 320,
  height: 100,
  child: bannerView,
)

화면 너비에 맞추기

SizedBox(
  width: MediaQuery.of(context).size.width,
  height: 80,
  child: bannerView,
)

크기 설정

adSize 속성을 사용하여 배너 뷰의 크기를 명시적으로 설정할 수 있습니다.

@override
void initState() {
  super.initState();

  bannerView = AdropBannerView(
    unitId: 'YOUR_UNIT_ID',
    listener: AdropBannerListener(
      onAdReceived: (unitId, metadata) {
        setState(() {
          isLoaded = true;
        });
      },
    ),
  );

  // 컨텍스트가 준비된 후 크기 설정
  WidgetsBinding.instance.addPostFrameCallback((_) {
    bannerView.adSize = Size(
      MediaQuery.of(context).size.width,
      80,
    );
  });
}

에러 처리

광고 로드 실패 시 적절한 에러 처리를 구현하세요.

class _BannerExampleState extends State<BannerExample> {
  bool isLoaded = false;
  AdropErrorCode? errorCode;
  late AdropBannerView bannerView;

  @override
  void initState() {
    super.initState();

    bannerView = AdropBannerView(
      unitId: 'YOUR_UNIT_ID',
      listener: AdropBannerListener(
        onAdReceived: (unitId, metadata) {
          setState(() {
            isLoaded = true;
            errorCode = null;
          });
        },
        onAdFailedToReceive: (unitId, error) {
          setState(() {
            isLoaded = false;
            errorCode = error;
          });
        },
      ),
    );

    bannerView.load();
  }

  @override
  Widget build(BuildContext context) {
    return Column(
      children: [
        if (isLoaded)
          SizedBox(
            width: MediaQuery.of(context).size.width,
            height: 80,
            child: bannerView,
          )
        else if (errorCode != null)
          Text('광고 로드 실패: ${errorCode?.code}'),
      ],
    );
  }

  @override
  void dispose() {
    bannerView.dispose();
    super.dispose();
  }
}

모범 사례

1. 리소스 해제

배너 뷰가 더 이상 필요하지 않을 때 반드시 dispose()를 호출하세요.

@override
void dispose() {
  bannerView.dispose();
  super.dispose();
}

2. 광고 새로고침

필요에 따라 광고를 새로고침할 수 있습니다.

void refreshAd() {
  setState(() {
    isLoaded = false;
  });
  bannerView.load();
}

3. 조건부 렌더링

광고가 로드될 때까지 배너 영역을 숨기거나 플레이스홀더를 표시하세요.

Widget buildBanner() {
  if (isLoaded) {
    return SizedBox(
      width: MediaQuery.of(context).size.width,
      height: 80,
      child: bannerView,
    );
  } else if (isLoading) {
    return const SizedBox(
      height: 80,
      child: Center(child: CircularProgressIndicator()),
    );
  } else {
    return const SizedBox.shrink();
  }
}

4. 여러 배너 관리

여러 배너를 사용할 때는 각각의 상태를 관리하세요.

class _MultiBannerState extends State<MultiBanner> {
  late AdropBannerView topBanner;
  late AdropBannerView bottomBanner;
  bool isTopLoaded = false;
  bool isBottomLoaded = false;

  @override
  void initState() {
    super.initState();

    topBanner = AdropBannerView(
      unitId: 'TOP_UNIT_ID',
      listener: AdropBannerListener(
        onAdReceived: (_, __) => setState(() => isTopLoaded = true),
      ),
    );

    bottomBanner = AdropBannerView(
      unitId: 'BOTTOM_UNIT_ID',
      listener: AdropBannerListener(
        onAdReceived: (_, __) => setState(() => isBottomLoaded = true),
      ),
    );

    topBanner.load();
    bottomBanner.load();
  }

  @override
  void dispose() {
    topBanner.dispose();
    bottomBanner.dispose();
    super.dispose();
  }

  // ...
}

전체 예제

import 'package:flutter/material.dart';
import 'package:adrop_ads_flutter/adrop_ads_flutter.dart';

class BannerAdPage extends StatefulWidget {
  const BannerAdPage({super.key});

  @override
  State<BannerAdPage> createState() => _BannerAdPageState();
}

class _BannerAdPageState extends State<BannerAdPage> {
  static const double bannerHeight = 80;
  bool isLoaded = false;
  bool isLoading = false;
  AdropErrorCode? errorCode;
  late AdropBannerView bannerView;

  @override
  void initState() {
    super.initState();

    bannerView = AdropBannerView(
      unitId: 'PUBLIC_TEST_UNIT_ID_320_100', // 테스트 유닛 ID
      listener: AdropBannerListener(
        onAdReceived: (unitId, metadata) {
          debugPrint('광고 수신 성공');
          debugPrint('크리에이티브 ID: ${metadata?['creativeId']}');
          debugPrint('캠페인 ID: ${metadata?['campaignId']}');
          debugPrint('크리에이티브 크기: ${bannerView.creativeSize?.width}x${bannerView.creativeSize?.height}');
          setState(() {
            isLoaded = true;
            isLoading = false;
            errorCode = null;
          });
        },
        onAdClicked: (unitId, metadata) {
          debugPrint('광고 클릭: ${metadata?['destinationURL']}');
        },
        onAdImpression: (unitId, metadata) {
          debugPrint('광고 노출: ${metadata?['creativeId']}');
        },
        onAdFailedToReceive: (unitId, error) {
          debugPrint('광고 수신 실패: $error');
          setState(() {
            isLoaded = false;
            isLoading = false;
            errorCode = error;
          });
        },
      ),
    );

    WidgetsBinding.instance.addPostFrameCallback((_) {
      bannerView.adSize = Size(
        MediaQuery.of(context).size.width,
        bannerHeight,
      );
    });
  }

  void loadAd() {
    setState(() {
      isLoading = true;
      errorCode = null;
    });
    bannerView.load();
  }

  @override
  void dispose() {
    bannerView.dispose();
    super.dispose();
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: const Text('배너 광고 예제'),
      ),
      body: SafeArea(
        child: Column(
          children: [
            // 로드 버튼
            Padding(
              padding: const EdgeInsets.all(16),
              child: ElevatedButton(
                onPressed: isLoading ? null : loadAd,
                child: Text(isLoading ? '로딩 중...' : '배너 광고 로드'),
              ),
            ),

            // 상태 표시
            if (errorCode != null)
              Padding(
                padding: const EdgeInsets.all(16),
                child: Text(
                  '에러: ${errorCode?.code}',
                  style: const TextStyle(color: Colors.red),
                ),
              ),

            // 메인 콘텐츠
            const Expanded(
              child: Center(
                child: Text('메인 콘텐츠 영역'),
              ),
            ),

            // 배너 광고
            Container(
              width: MediaQuery.of(context).size.width,
              height: bannerHeight,
              color: Colors.grey[200],
              child: isLoaded
                  ? bannerView
                  : isLoading
                      ? const Center(child: CircularProgressIndicator())
                      : const Center(child: Text('광고 영역')),
            ),
          ],
        ),
      ),
    );
  }
}

백필 광고

백필 광고가 활성화된 경우, 직광고가 없을 때 자동으로 백필 광고가 로드됩니다. 백필 광고 로드는 SDK에서 자동으로 처리됩니다. backfillNoFill 에러 코드를 사용하여 백필 관련 에러를 처리할 수 있습니다.

bannerView = AdropBannerView(
  unitId: 'YOUR_UNIT_ID',
  listener: AdropBannerListener(
    onAdReceived: (unitId, metadata) {
      debugPrint('광고 로드됨');
      setState(() {
        isLoaded = true;
      });
    },
    onAdFailedToReceive: (unitId, errorCode) {
      switch (errorCode) {
        case AdropErrorCode.adNoFill:
          debugPrint('직광고 없음');
          break;
        case AdropErrorCode.backfillNoFill:
          debugPrint('백필 광고도 없습니다');
          // 광고 영역 숨김 처리
          break;
        default:
          debugPrint('광고 로드 실패: ${errorCode.code}');
      }
    },
  ),
);

배너 광고 메타데이터에는 creativeId, txId, campaignId, destinationURL, browserTarget 필드만 포함됩니다. 백필 광고는 메타데이터로 구분할 수 없습니다. backfillNoFill 에러 코드를 사용하여 백필 광고 실패를 감지할 수 있습니다.

백필 광고를 사용하려면 네이티브 플랫폼에 백필 의존성을 추가해야 합니다. 시작하기를 참고하세요.

백필 광고 미리 로드 (preload)

SDK 1.17.0부터 AdropBannerView.preload()로 백필 배너 광고를 미리 받아 둘 수 있습니다. 같은 유닛 ID와 같은 크기로 load()한 배너가 직광고 없이 백필 광고로 넘어가면, 백필 광고를 다시 요청하지 않고 미리 받아 둔 광고를 바로 표시합니다. load()는 preload와 관계없이 직광고를 먼저 요청합니다. 직광고가 표시되면 미리 받아 둔 광고는 그대로 남습니다. preload를 호출하지 않으면 동작은 이전과 같습니다.

동작 조건

adrop_ads_flutter 1.17.0 이상과, 네이티브 플랫폼의 백필 의존성 1.17.0 이상이 필요합니다. 시작하기를 참고하세요.
서버가 앱에 지금 노출할 직광고가 없다고 알려 준 상태에서만 백필 광고를 받습니다. 그 밖에는 백필 광고를 요청하지 않고 ERROR_CODE_AD_PRELOAD_SKIPPED로 끝납니다. 직광고 캠페인이 있는 앱에서는 정상적인 결과입니다.
앱 설치 직후, 앱 키를 바꾼 직후, setUID로 다른 사용자로 바꾼 직후에는 서버 응답을 받기 전까지 ERROR_CODE_AD_PRELOAD_SKIPPED로 끝납니다.
테스트 유닛 ID로는 항상 ERROR_CODE_AD_PRELOAD_SKIPPED로 끝납니다.

사용 방법

배너가 있는 화면을 띄우기 직전에 호출하세요. 미리 받은 광고는 쓰이지 않으면 30분 뒤 폐기되므로 곧 표시할 배너에만 호출하세요. 결과를 기다렸다가 load()할 필요는 없습니다. 아직 받는 중이면 load()가 그 결과를 기다려 사용합니다. preload()는 미리 받기에 성공하면 완료되고, 그 밖의 결과(ERROR_CODE_AD_PRELOAD_SKIPPED 포함)는 code가 에러 코드 문자열인 PlatformException으로 전달됩니다. 처리하지 않으면 정상 결과인 SKIPPED도 처리되지 않은 비동기 오류로 보고되므로, try/catch로 감싸거나 .catchError를 붙이세요.

import 'package:adrop_ads_flutter/adrop_ads_flutter.dart';
import 'package:flutter/material.dart';
import 'package:flutter/services.dart';

// 배너가 있는 화면을 띄우기 직전에 호출합니다.
Future<void> preloadFeedBanner() async {
  try {
    await AdropBannerView.preload(
      unitId: 'YOUR_UNIT_ID',
      adSize: const Size(320, 50), // 생략하면 320x50
    );
    debugPrint('미리 로드 완료');
  } on PlatformException catch (e) {
    // ERROR_CODE_AD_PRELOAD_SKIPPED는 정상 결과입니다.
    // 여기서 preload를 바로 다시 호출하지 마세요.
    final errorCode = AdropErrorCode.getByCode(e.code);
    debugPrint('미리 로드 안 됨: ${errorCode.code}');
  }
}

결과가 필요 없으면 다음처럼 호출할 수 있습니다.

AdropBannerView.preload(unitId: 'YOUR_UNIT_ID', adSize: const Size(320, 50))
    .catchError((_) {});

미리 받아 둔 광고를 쓰려면 load()할 AdropBannerView의 adSize를 preload에 넘긴 크기와 같게 지정하세요.

final bannerView = AdropBannerView(unitId: 'YOUR_UNIT_ID');
bannerView.adSize = const Size(320, 50); // preload에 넘긴 크기
bannerView.load();

미리 받은 광고가 쓰이는 조건

같은 유닛 ID와 같은 크기: load()하는 AdropBannerView의 adSize가 preload에 넘긴 크기와 같아야 합니다. 크기가 다르면 미리 받은 광고는 그대로 남고, load()는 평소처럼 백필 광고를 요청합니다.
한 번만 사용: 미리 받은 광고는 load() 한 번에 쓰이면 없어집니다. 다시 미리 받으려면 preload를 다시 호출하세요.
유효 시간과 개수: 30분 안에 쓰이지 않은 광고는 폐기됩니다. 같은 유닛·크기에는 1개만 보관하고, 배너는 서로 다른 유닛·크기 조합을 최대 5개까지 보관합니다. 5개를 넘으면 가장 먼저 받은 광고부터 폐기합니다.
다시 호출할 때: 같은 유닛·크기로 다시 호출해도 새로 요청하지 않습니다. 받아 둔 광고가 있으면 새 요청 없이 완료되고, 받는 중이면 그 로드의 결과(성공 또는 실패)가 똑같이 전달됩니다. 광고를 새로 고치는 용도로는 쓸 수 없습니다. 단, 그 사이 사용자 동의 상태가 바뀌었으면 기존 광고를 버리고 새로 받습니다.
동의 상태 변경: 미리 받은 뒤 사용자 동의 상태가 바뀌면 그 광고는 load()에 쓰이지 않습니다.
완료의 의미: preload()가 완료되었다는 것은 미리 받기가 끝났다는 뜻입니다. 그 결과를 기다리던 load()가 이미 사용했을 수도 있습니다.

실패 코드

에러 코드	코드 문자열	설명
`preloadSkipped`	`ERROR_CODE_AD_PRELOAD_SKIPPED`	직광고가 노출될 수 있거나 아직 확인되지 않아 백필 광고를 요청하지 않았습니다. 정상 결과이므로 다음 화면을 띄우기 직전에 다시 호출하세요.
`adNoFill`	`ERROR_CODE_AD_NO_FILL`	1.17.0 이상의 백필 의존성이 없거나, 유닛에 백필이 설정되지 않았거나 SDK가 그 설정을 아직 받지 못했습니다. 잠시 뒤 다시 호출하세요. 백필 의존성이 없으면 계속 이 코드로 끝납니다. iOS에서는 기기가 대상 국가에 속하지 않을 때도 이 코드로 끝납니다.
`backfillNoFill`	`ERROR_CODE_AD_BACKFILL_NO_FILL`	백필 광고가 없습니다.
`internal`	`ERROR_CODE_INTERNAL`	요청이 중단되었거나(예: Android에서 받는 중에 Activity가 종료됨) 내부 오류가 발생했습니다. 나중에 다시 호출하세요.
`initialize`	`ERROR_CODE_INITIALIZE`	SDK가 초기화되지 않았습니다. Android에서는 기기가 대상 국가에 속하지 않을 때도 이 코드로 끝납니다.
`invalidUnit`	`ERROR_CODE_INVALID_UNIT`	유닛 ID가 비어 있습니다.

catch 안에서 preload를 바로 다시 호출하지 마세요. 백필 의존성이 없을 때처럼 결과가 바뀌지 않으면 호출이 끝없이 반복됩니다. 다음 화면을 띄우기 전처럼 나중에 다시 호출하세요.

다음 단계

네이티브 광고

UI에 맞게 커스터마이징 가능한 네이티브 광고 구현하기

전면 광고

화면 전체를 덮는 전면 광고 구현하기

팝업 광고

팝업 형태로 표시되는 광고 구현하기

레퍼런스

타입, 메서드, 에러 코드 참고하기