← Blog

앱인토스 광고 연동 주의사항 — 광고 그룹 순차 로드와 dismissed 이벤트 누락 대응

JunGyu Kim · · 19분 읽기앱인토스광고광고SDKWebView
목차

1. 문제 상황: 광고 코드가 dismissed를 믿고 있었습니다

저는 토스 앱 안에서 돌아가는 앱인토스 웹뷰 미니앱 세 개를 운영합니다. 주식 차트의 다음 봉을 맞히는 차트예측게임, 나를 성분표처럼 풀어 주는 나의 성분 분석기, 손바닥 사진으로 손금 보고서를 만드는 AI 손금 감정 보고서입니다. 세 앱 모두 하단 배너와 화면 전체를 덮는 전면형 광고를 씁니다. 전면형은 보상을 주는 보상형과 보상 없는 전면 광고로 나뉘는데, 손금 감정 보고서는 보상형만 씁니다. 광고 SDK를 처음 붙인 과정은 앱인토스 배포기 5편에 정리했는데, 그때 세운 전략은 앱이 시작되면 광고를 미리 불러 두고, 광고를 보여 준 뒤 다음 광고를 다시 불러오는 것이었습니다.

2026년 3월 24일 빌드부터 서비스하던 차트예측게임의 광고 매니저 일부입니다.

// 차트예측게임 src/utils/adManager.ts (커밋 778a225, 일부 생략)
 
// 앱 시작 시 한 번 호출
export async function preloadAllAds(): Promise<void> {
  await Promise.all([loadAd('interstitial'), loadAd('rewarded')]);
}
 
// showAd() 안의 이벤트 처리
switch (event.type) {
  case 'userEarnedReward':
    rewarded = true;
    break;
  case 'dismissed':
    // 광고 종료 시 다음 광고 미리 로드
    loadAd(adType);
    resolve({ success: true, rewarded });
    break;
  case 'failedToShow':
    resolve({ success: false });
    break;
}

전면과 보상형을 Promise.all로 한꺼번에 불러오고, 같은 시점에 게임 화면에는 하단 배너도 붙습니다. 보상은 userEarnedReward에서 표시만 해 두고, 실제로 생명을 돌려주는 것은 dismissed가 와서 Promise가 풀릴 때입니다. 다음 광고를 불러오는 일도 dismissed에 묶여 있습니다.

나의 성분 분석기도 결과 화면에서 보상형, 전면, 배너를 한꺼번에 불러왔고, "다시 분석하기"는 전면 광고의 dismissed를 기다린 뒤에야 첫 화면으로 돌아갔습니다. 배너는 TossAds.initialize 없이 attachBanner만 불러서 아예 그려지지 않고 있었습니다. 두 앱 모두 이벤트를 기다리는 코드에 시간 제한이 없었습니다.

제 광고 코드는 두 가지 가정 위에 서 있었던 셈입니다. 광고는 동시에 불러와도 된다, 그리고 dismissed는 반드시 온다. 2026년 10월 14일, 두 가정이 모두 틀렸다는 것을 공식 문서에서 확인했습니다.

2. 연동 코드에는 없고 공식 FAQ에는 있던 규칙

제가 따르던 연동 방식은 보상 안내와 다음 광고 준비를 모두 dismissed에 걸어 두는 구조였고, 광고를 불러오는 순서나 토스 앱 버전별 이벤트 누락은 고려하지 않았습니다.

10월 14일, 세 앱의 광고 코드를 손보던 날 개발자 센터 문서를 직접 열어 봤습니다. 인앱 광고 문서 중 전면형·보상형 광고 페이지의 FAQ에 이런 문장이 있었습니다.

광고 그룹 ID는 반드시 1개씩 순차적으로 로드해 주세요. 미니앱에서 여러 광고 그룹 ID를 동시에 로드하면 정상적으로 처리되지 않아요.

같은 FAQ의 내용을 묶으면 이렇습니다.

  • 순차 로드 규칙은 보상형, 전면, 배너를 가리지 않습니다. 배너도 광고 그룹 하나입니다.
  • Android 토스 앱 5.266.0 이상에서 전면형 광고를 배너와 동시에 불러오면 전면형 광고의 이벤트가 오지 않습니다. 확인 당시 수정은 "5.268.0 예정"이었습니다.
  • Android 토스 앱 5.255.0에서는 dismissed가 아예 오지 않습니다.
  • 광고 그룹마다 미리 불러 둔 광고 하나는 괜찮습니다. 보상은 userEarnedReward에서만 주고, 흐름은 로드 → 노출 → 다시 로드입니다.

FAQ에 비춰 보니 문제가 구조로 보였습니다. 차트예측게임은 앱이 시작되자마자 세 광고 그룹을 동시에 불러오므로, 5.266.0 이상에서 전면형 광고의 이벤트가 빠지면 그 이벤트를 기다리는 코드는 그대로 멈춥니다. dismissed가 오지 않는 5.255.0이라면, 보상이 dismissed에서 풀리는 구조라 광고를 끝까지 보고도 생명을 받지 못하고 다음 광고도 불러오지 않습니다. 나의 성분 분석기의 "다시 분석하기"는 광고를 닫아도 첫 화면으로 넘어가지 못합니다.

다만 이 증상을 해당 버전 기기에서 재현해 본 것은 아닙니다. FAQ의 조건을 코드에 대입한 결과라, 고칠 때 그 조건을 흉내 내는 가짜 SDK 테스트를 함께 만들었습니다.

3. 해결 1: 배너까지 모든 광고 로드를 큐 하나로

첫 번째 규칙은 한 곳에서 지킵니다. 광고를 불러오는 모든 코드가 같은 큐를 거치게 했습니다. AI 손금 감정 보고서의 큐 핵심부입니다.

// AI 손금 감정 보고서 src/lib/adLoadQueue.ts (일부 생략)
 
// 앱인토스 광고는 광고 그룹을 한 번에 하나씩 불러와야 해요.
// 보상형 광고와 배너를 동시에 불러오면 일부 Android 버전에서 보상형 광고 이벤트가 오지 않아요.
// 그래서 모든 광고 로드를 이 큐에서 하나씩 실행해요.
 
// 숫자가 작을수록 먼저 실행해요.
export const AD_LOAD_PRIORITY = {
  rewarded: 0,
  banner: 1,
} as const;
 
// 한 화면의 effect들이 같은 틱에 넣은 작업은 넣은 순서가 아니라 우선순위대로 시작하도록 한 박자 미뤄요.
function schedulePump() {
  if (isPumpScheduled) return;
  isPumpScheduled = true;
  queueMicrotask(() => {
    isPumpScheduled = false;
    pump();
  });
}
 
function pump() {
  if (isRunning) return;
  waiting.sort((a, b) => a.priority - b.priority || a.order - b.order);
  const job = waiting.shift();
  if (!job) return;
 
  isRunning = true;
  job.started = true;
  let timeoutId: ReturnType<typeof setTimeout> | undefined;
  const timedOut = new Promise<void>((resolve) => {
    timeoutId = setTimeout(() => {
      job.controller.abort();
      resolve();
    }, job.timeoutMs);
  });
  // 예외를 던진 작업도 큐를 비워 줘야 해요.
  const ran = Promise.resolve()
    .then(() => job.run(job.controller.signal))
    .catch(() => {});
 
  void Promise.race([ran, timedOut]).then(() => {
    clearTimeout(timeoutId);
    job.finished = true;
    isRunning = false;
    schedulePump();
  });
}

신경 쓴 점은 세 가지입니다. 첫째, 한 번에 한 작업만 돌고, 작업은 로드 결과를 받는 순간 큐를 놓아줍니다. 전면형 광고는 loaded나 에러를, 배너는 렌더링 완료(onAdRendered), 노필(onNoFill), 렌더링 실패(onAdFailedToRender) 중 먼저 오는 콜백을 결과로 봅니다.

둘째, 모든 작업에 시간 제한이 있습니다. 이벤트가 빠질 수 있는 환경에서 큐가 끝없이 기다리면 광고 하나가 앱의 모든 광고를 막습니다. 시간이 지나면 AbortSignal로 작업을 끊고 넘어가며, 작업은 브리지를 부르기 직전에 signal을 다시 확인해서 늦게 출발한 로드가 다음 작업과 겹치지 않게 합니다. 전면형 광고 로드는 30초, 배너는 10초입니다.

셋째, 우선순위입니다. 한 화면의 effect들이 여러 광고 요청을 같은 틱에 넣어도, 마이크로태스크로 한 박자 미뤄 정렬하면 마운트 순서가 아니라 정해 둔 순서로 출발합니다. 나의 성분 분석기는 보상형 0, 배너 1, 전면 2, 방금 보여 준 광고를 다시 채우는 refill 3 순서입니다.

TossAds.initialize는 광고 SDK 스크립트를 준비하는 단계라 광고 로드가 아닙니다. 그래서 손금 감정 보고서와 성분 분석기는 초기화를 큐 밖에서 먼저 끝내고 attachBanner만 줄을 세워서, 스크립트가 늦게 떠도 큐를 붙잡거나 배너의 10초를 깎아 먹지 않게 했습니다.

// AI 손금 감정 보고서 src/hooks/useBannerAd.ts (일부 생략)
 
// 이 시간 안에 표시·실패 소식이 없으면 다음 광고 로드에 큐를 넘겨요.
const BANNER_LOAD_TIMEOUT_MS = 10_000;
 
// 광고 SDK 초기화는 광고 로드가 아니라서 바로 하고, 배너 로드만 큐에서 보상형 광고 다음 차례를 기다려요.
initializeTossAds().then((ready) => {
  // ... 초기화 실패나 미지원이면 배너 자리를 접고 끝
  ticket = enqueueAdLoad({
    priority: AD_LOAD_PRIORITY.banner,
    timeoutMs: BANNER_LOAD_TIMEOUT_MS,
    run: (signal) => new Promise<void>((release) => {
      if (signal.aborted || disposed) {
        release();
        return;
      }
      // 시간 안에 소식이 없으면 배너 로드를 접어서, 다음 광고 로드와 겹치지 않게 해요.
      signal.addEventListener('abort', () => {
        destroy?.();
        destroy = undefined;
        if (!disposed) setIsVisible(false);
        release();
      }, { once: true });
      destroy = TossAds.attachBanner('<AD_GROUP_ID>', container, {
        theme: 'light',
        tone: 'grey',
        variant: 'expanded',
        callbacks: {
          onAdFailedToRender: () => { setIsVisible(false); release(); },
          onNoFill: () => { setIsVisible(false); release(); },
          onAdRendered: () => { setIsVisible(true); release(); },
        },
      }).destroy;
    }),
  });
});

차트예측게임은 우선순위 없이 Promise 체인 하나로 같은 규칙을 지킵니다. 보상형 다음에 전면을 await로 이어 붙이고, 배너의 첫 부착도 같은 슬롯을 거칩니다.

// 차트예측게임 src/utils/adSdk.ts
 
// A single queue also covers initial banner attachment: affected Android versions
// can drop callbacks when different ad groups start loading concurrently.
let loadQueue: Promise<unknown> = Promise.resolve();
export function withAdLoadSlot<T>(load: () => Promise<T>): Promise<T> {
  const next = loadQueue.then(load, load);
  loadQueue = next.catch(() => undefined);
  return next;
}

손금 감정 보고서는 보상형 광고를 보여 주는 동안에도 큐를 잡아 배너 로드가 끼어들지 못하게 하고, 끝을 알 수 없을 때를 대비해 최대 90초로 묶었습니다. 큐에서 기다리는 시간도 사용자에게는 로딩이라, 성분 분석기는 차례를 기다리는 동안 버튼에 "광고 준비 중이에요..."를 띄웁니다.

4. 해결 2: dismissed 없이도 끝나는 노출 흐름

두 번째 규칙의 원칙은 하나입니다. dismissed는 오면 반갑지만, 오지 않아도 흐름은 끝나야 합니다. 나의 성분 분석기와 AI 손금 감정 보고서의 처리는 이렇습니다.

이벤트처리
노출 요청 후 아무 이벤트 없음10초 뒤 실패로 끝냄
requested30초 안에 화면에 뜨지 않으면 실패로 끝냄
show 또는 impression표시된 것으로 기록하고, 이때부터 우리 화면의 탭을 감시
userEarnedReward그 자리에서 보상 지급. 30초 안에 닫힘 소식이 없으면 끝난 것으로 봄
dismissed 또는 화면 탭끝냄. 손금 감정 보고서는 늦게 오는 보상을 1초 기다림
failedToShow, 브리지 에러실패로 끝냄. 이미 받은 보상은 유지

핵심은 화면 탭입니다. 광고가 화면을 덮고 있는 동안에는 우리 페이지를 누를 수 없으니, 광고가 표시된 뒤 페이지에서 pointerdown이 잡혔다면 광고는 이미 닫힌 것입니다. 손금 감정 보고서의 노출 코드 일부입니다.

// AI 손금 감정 보고서 src/hooks/useRewardedAd.ts (일부 생략)
 
// 닫힘 이벤트와 화면 탭을 같은 길로 처리해요. 보상 이벤트가 닫힘보다 늦게 올 수 있어 잠시 기다려요.
const markClosed = () => {
  if (dismissed) return;
  dismissed = true;
  if (earned) finish('rewarded');
  else lateRewardTimer = window.setTimeout(() => finish(earned ? 'rewarded' : 'dismissed'), LATE_REWARD_GRACE_MS);
};
// 광고가 뜬 뒤 우리 화면을 누를 수 있다면 광고는 이미 닫힌 거예요. 닫힘 이벤트가 오지 않아도 버튼이 멈추지 않게 해요.
const onPageTap = () => markClosed();
const markDisplayed = () => {
  if (displayed) return;
  displayed = true;
  window.clearTimeout(displayTimer);
  document.addEventListener('pointerdown', onPageTap, true);
};
 
handle.cleanup = showFullScreenAd({
  options: { adGroupId: '<AD_GROUP_ID>' },
  onEvent: (event) => {
    if (done) return;
    window.clearTimeout(startTimer);
    switch (event.type) {
      case 'requested':
        if (!displayed && displayTimer === undefined) {
          displayTimer = window.setTimeout(() => finish('failed'), SHOW_DISPLAY_TIMEOUT_MS);
        }
        break;
      case 'show':
      case 'impression':
        markDisplayed();
        break;
      case 'userEarnedReward':
        markDisplayed();
        if (earned) break;
        earned = true;
        onRewarded();
        if (dismissed) finish('rewarded');
        else closeGraceTimer = window.setTimeout(() => finish('rewarded'), REWARD_CLOSE_GRACE_MS);
        break;
      case 'dismissed':
        markClosed();
        break;
      case 'failedToShow':
        finish(earned ? 'rewarded' : 'failed');
        break;
    }
  },
  onError: () => finish(earned ? 'rewarded' : 'failed'),
});

보상은 userEarnedReward를 받는 즉시 줍니다. 3월 버전 차트예측게임처럼 dismissed에서 보상을 풀면 닫힘 이벤트 하나를 잃는 순간 보상까지 잃습니다. 닫힘 신호와 시간 제한은 버튼을 풀어 주는 데만 씁니다. 성분 분석기의 테스트 이름 keeps an earned reward when `dismissed` never arrives가 이 의도를 그대로 말해 줍니다.

전면 광고는 더 단순합니다. "다시 분석하기"는 광고가 닫히기를 기다리지 않고, 광고가 화면에 뜨는 순간 다음으로 넘어갑니다. 사용자가 광고를 닫으면 이미 첫 화면이 기다리고 있습니다.

// 나의 성분 분석기 src/lib/resultActions.ts (커밋 592e2f3 기준)
export async function restartAfterInterstitial(result: AnalysisResult, deps: RestartDeps): Promise<void> {
  const ad = deps.getAdState();
  if (ad.isSupported === true && ad.isPreloaded) {
    // Moves on once the ad is on screen (or failed), not on `dismissed`, which some app
    // versions never send: the user closes the ad onto the onboarding screen
    await deps.showUntilDisplayed();
    // A newer session may have started meanwhile: never reset that one
    if (deps.getResult() !== result) return;
  }
  deps.resetApp();
}

광고가 떠 있는 사이 사용자가 뒤로 가기로 새 분석을 시작했을 수 있어서, 처음 받은 결과와 지금 결과가 같을 때만 초기화합니다. 광고를 쓸 수 없거나 미리 불러 두지 못했다면 기다리지 않고 바로 넘어갑니다.

차트예측게임은 다른 길을 골랐습니다. 토스 앱이 알려 주는 환경 정보로 문제 버전을 직접 걸러 냅니다.

// 차트예측게임 src/utils/adSdk.ts
export function hasBrokenDismissEvent(sdk: AdSdk): boolean {
  try { return sdk.Device.os === 'android' && sdk.Environment.tossAppVersion === '5.255.0'; }
  catch { return false; }
}

이 함수가 참이면 전면형 광고를 지원하지 않는 환경으로 보고 아예 불러오지 않습니다. 결과 화면의 "광고 보고 이어하기" 버튼은 비활성화되고 "지금 환경에서는 광고를 볼 수 없어요"라는 안내가 뜹니다. 광고가 끝난 시점을 알 수 없는 버전에는 처음부터 광고를 내밀지 않는 쪽을 택한 것입니다.

그 밖의 이유로 닫힘 이벤트가 빠질 때는 사용자에게 직접 묻습니다. 광고를 띄운 지 30초가 지났는데 게임 화면이 보이고 있으면 "광고 화면을 닫았는데 돌아오지 않았나요?"라는 안내와 "광고 화면을 닫았어요 · 계속하기" 버튼이 나타납니다. 이 버튼은 멈춘 상태만 풀 뿐, 네이티브 광고를 닫거나 없던 보상을 만들어 내지 않습니다.

5. 적용한 미니앱과 날짜, 그리고 남은 문제

세 앱 모두 2026년 10월 14일 하루에 바꿨고, 모두 @apps-in-toss/web-framework 3.8.0 기준입니다.

  • 나의 성분 분석기: 커밋 b971d1c에서 로드 큐와 dismissed에 기대지 않는 노출 처리를, 커밋 592e2f3에서 배너 상시 노출을 넣었습니다. 같은 날 폰에서 확인한 뒤 출시했습니다.
  • AI 손금 감정 보고서: 커밋 f4cd1dd에서 보상형 → 배너 순서의 큐와 노출 안전장치를 넣고, 배너 상시 노출(커밋 151c3d4)까지 묶어 그날 밤 검토를 요청했습니다.
  • 차트예측게임: 순차 로드, 5.255.0 감지, 30초 복구 버튼을 넣은 번들로 같은 날 검토를 요청했습니다.

키보드 위에 배너와 하단 버튼을 차례로 쌓는 배치 문제는 따로 정리합니다. 남은 문제도 적어 둡니다.

  • 실기기 검증이 부족합니다. 5.255.0이나 5.266.0 이상 Android 기기에서 이벤트 흐름을 직접 확인하지 못했고, 가짜 SDK 시나리오 테스트로만 확인했습니다.
  • 같은 규칙을 세 가지 코드로 지킵니다. 큐는 Promise 체인과 우선순위 큐로, 5.255.0 대응은 광고를 끄는 쪽과 화면 탭·시간 제한으로 버티는 쪽으로 갈립니다. 공용 모듈로 합치는 일이 남았습니다.
  • 시간 제한 값이 앱마다 다릅니다. 차트예측게임은 광고 로드가 최대 60초까지 걸릴 수 있다는 FAQ 내용을 주석으로 남기고 65초를 잡았지만, 다른 두 앱은 30초입니다. 60초 가까이 걸리는 로드는 30초 제한에서 실패로 끝납니다.
  • 5.266.0 이상의 이벤트 누락이 고쳐졌는지는 아직 확인하지 않았습니다. 다만 순차 로드는 버전과 상관없는 규칙이라, 버그가 고쳐져도 큐를 걷어 낼 이유는 없습니다.
  • 차트예측게임은 5.255.0 사용자에게 이어하기를 주지 못합니다. 멈추지 않는 대신 기능 하나를 포기한 셈입니다.

6. 앱인토스 광고 연동 체크리스트

  • 배너를 포함한 모든 광고 로드가 큐 하나를 거쳐 한 번에 하나씩, 정해 둔 우선순위대로 출발하는가.
  • 큐의 각 작업에 시간 제한이 있고, 시간이 지난 작업은 브리지를 부르지 않고 다음으로 넘기는가.
  • attachBanner 전에 TossAds.initialize를 한 번 부르는가. 초기화는 광고 로드가 아니니 큐 밖에서 끝낸다.
  • 보상은 userEarnedReward에서 즉시 주는가. dismissed에서 보상을 풀고 있지 않은가.
  • dismissed가 오지 않아도 버튼과 화면 전환이 풀리는가. 화면 탭이나 시간 제한 같은 다른 출구가 있는가.
  • 한 번 보여 준 광고는 소진된 것으로 보고 다시 불러오는가(로드 → 노출 → 다시 로드).
  • 광고를 쓸 수 없거나 반복해서 실패할 때 버튼과 화면이 멈춘 채 남지 않는가.
  • FAQ에 적힌 버전(Android 5.255.0, 5.266.0 이상)의 증상을 가짜 SDK 테스트로라도 재현해 두었는가.

돌아보면 규칙 두 줄을 몰랐던 것보다, 이벤트가 반드시 온다는 가정을 세 앱에 똑같이 깔아 둔 것이 더 큰 문제였습니다. 이벤트를 기다리는 코드에는 기다림을 끝낼 출구가 하나 더 있어야 합니다. 보상형 광고로 콘텐츠를 여는 설계는 Flutter 앱에서 같은 고민을 했던 NeonBoard 수익화 글에 정리해 두었고, 차트 게임 아이디어는 iOS 앱 차트 예측 게임으로도 이어졌습니다.

광고

관련 글