Google은 AI 기술을 사용하여 콘텐츠를 사용자의 기본 언어로 번역합니다. AI 번역에는 오류가 있을 수 있습니다.

앱 오프닝 광고 설정

앱 오프닝 광고는 사용자가 앱을 열거나 앱으로 돌아갈 때 표시됩니다. 사용자는 언제든지 앱 오프닝 광고를 닫을 수 있습니다. 앱 로드 화면에서 수익을 창출하려면 앱 오프닝 광고를 사용하세요. 자세한 내용은 앱 오프닝 광고 안내 및 권장사항을 참고하세요.

이 가이드에서는 앱 오프닝 광고를 React Native 앱에 통합하는 방법을 설명합니다.

기본 요건

계속하기 전에 다음을 수행하세요.

Google Mobile Ads SDK for React Native를 설정합니다.
테스트 광고를 사용 설정하고 다음 테스트 광고 단위를 사용합니다.

Android

ca-app-pub-3940256099942544/9257395921

iOS

ca-app-pub-3940256099942544/5575463023

광고 사전 로드 이해하기

Google Mobile Ads SDK for React Native의 광고 사전 로드는 광고 로드 및 캐싱을 자동화합니다.

광고 사전 로드의 이점은 다음과 같습니다.

참조 관리: 광고가 표시될 때까지 참조를 유지합니다.
자동 새로고침: 캐시에서 광고를 가져올 때 새 광고를 로드합니다.
관리형 재시도: 광고 로드에 실패하면 새 광고를 로드합니다.
만료 처리: 만료되기 전에 광고를 새로고침합니다.
캐시 최적화: 우선순위가 가장 높은 광고를 게재하도록 캐시 순서를 최적화합니다.

광고를 수동으로 로드하려면 단일 앱 오프닝 광고 로드 가이드를 참고하세요.

미리 로드 시작

광고 미리 로드를 시작하려면 AppOpenAdPreloader.start 메서드를 호출하고 preloadId 값, 구성 설정, 이벤트 콜백을 전달하여 버퍼 상태 변경을 모니터링합니다.

export function startAppOpenAdPreloader(
  adUnitId: string,
  preloadId: string,
  customPreloadCallback?: PreloadCallback,
): boolean {
  const started = AppOpenAdPreloader.start(
    preloadId,
    {
      request: {adUnitId},
      bufferSize: 2,
    },
    {
      // Called when an ad is preloaded into the buffer.
      onAdPreloaded: (event) => {
        console.log(`App open ad preloaded for ${event.preloadId}`);
        customPreloadCallback?.onAdPreloaded?.(event);
      },
      // Called when an ad fails to preload.
      onAdFailedToPreload: (error: LoadAdError) => {
        console.error('Failed to preload app open ad:', error.message);
        customPreloadCallback?.onAdFailedToPreload?.(error);
      },
      // Called when all preloaded ads in the buffer have been shown.
      onAdsExhausted: () => {
        console.log('App open ad buffer exhausted.');
        customPreloadCallback?.onAdsExhausted?.();
      },
    },
  );
  return started;
}

preloadId는 광고 사전 로드 구성을 고유하게 식별하는 문자열입니다. adUnitId가 앱에서 단일 미리 로드 구성에만 사용되는 경우 해당 광고 단위 ID를 미리 로드 ID로 사용할 수 있습니다. 앱에서 동일한 광고 단위 ID에 여러 미리 로드 도구가 필요한 경우 각 미리 로드 ID에 고유한 문자열을 전달하세요.

앱이 버퍼에서 미리 로드된 광고를 폴링하면 Google Mobile Ads SDK for React Native가 백그라운드에서 대체 광고를 요청하여 버퍼를 다시 채웁니다. 버퍼에 미리 로드된 광고가 남아 있지 않으면 Google Mobile Ads SDK for React Native에서 onAdsExhausted 콜백을 호출합니다.

미리 로드 캐시 한도

Google Mobile Ads SDK for React Native는 미리 로드된 광고의 총 개수에 앱 전체 한도를 적용합니다.

기본 한도: Google은 메모리에 최대 6개의 미리 로드된 광고를 보관합니다.
미리 로드 ID마다 버퍼 사이즈를 2로 유지하는 것이 좋습니다.

앱이 앱 전체 한도에 도달하면 기존 광고가 폴링되어 표시되거나 소멸될 때까지 미리 로드된 광고에 대한 백그라운드 요청이 일시중지됩니다.

폴링 및 광고 표시

사용 가능한 미리 로드된 광고를 확인하고 광고 인스턴스를 가져오려면 AppOpenAdPreloader.pollAd 메서드를 호출합니다.

전체 화면 표시 이벤트를 수신 대기하려면 show 메서드를 호출하기 전에 반환된 AppOpenAd 인스턴스의 adEventCallback 속성에 콜백을 등록하세요.

export function showPreloadedAppOpenAd(
  preloadId: string,
  customAdEventCallback?: FullScreenAdEventCallback,
) {
  if (!AppOpenAdPreloader.isAdAvailable(preloadId)) {
    console.log('No preloaded app open ad available right now.');
    return;
  }

  const ad = AppOpenAdPreloader.pollAd(preloadId);
  if (!ad) {
    return;
  }

  ad.adEventCallback = {
    // Called when the ad is presented on screen.
    onAdShowedFullScreenContent: () => {
      console.log('Preloaded app open ad showed full screen content.');
      customAdEventCallback?.onAdShowedFullScreenContent?.();
    },
    // Called when the ad is closed by the user.
    onAdDismissedFullScreenContent: () => {
      console.log('Preloaded app open ad dismissed full screen content.');
      customAdEventCallback?.onAdDismissedFullScreenContent?.();
      ad.destroy();
    },
    // Called when presentation fails.
    onAdFailedToShowFullScreenContent: (error) => {
      console.error('Failed to show preloaded app open ad:', error);
      customAdEventCallback?.onAdFailedToShowFullScreenContent?.(error);
      ad.destroy();
    },
    // Called when an impression is recorded.
    onAdImpression: () => {
      console.log('Preloaded app open ad recorded an impression.');
      customAdEventCallback?.onAdImpression?.();
    },
    // Called when the user taps the ad.
    onAdClicked: () => {
      console.log('Preloaded app open ad was clicked.');
      customAdEventCallback?.onAdClicked?.();
    },
    // Called when the ad is estimated to have earned money.
    onAdPaid: (adValue) => {
      console.log(
        `Preloaded app open ad paid: ${adValue.amountMicros}` +
          ` ${adValue.currencyCode}`,
      );
      customAdEventCallback?.onAdPaid?.(adValue);
    },
  };

  ad.show();
}

사용자가 광고를 닫거나 광고가 표시되지 않으면 onAdDismissedFullScreenContent 및 onAdFailedToShowFullScreenContent 콜백에서 ad.destroy 메서드를 호출하여 메모리와 리소스를 확보합니다.

대답 정보 읽기

캐시에서 광고를 삭제하지 않고 미리 로드된 다음 광고의 세부정보를 검사하려면 AppOpenAdPreloader.peekAdResponseInfo 메서드를 호출합니다.

export function peekAppOpenAdResponseInfo(
  preloadId: string,
): ResponseInfo | null {
  const responseInfo = AppOpenAdPreloader.peekAdResponseInfo(preloadId);
  if (responseInfo) {
    console.log('Next preloaded app open ad response info:', responseInfo);
  }
  return responseInfo;
}

앱 수준 관리자로 앱 오프닝 광고 관리하기

앱 오프닝 광고는 앱 실행 및 포그라운드 전환 중에 전역적으로 표시되므로 React 구성요소 트리 외부의 앱 수준 관리자에서 미리 로드 도구 수명 주기 상태를 관리하는 것이 좋습니다.

앱 수준 관리자를 사용하면 다음과 같은 주요 이점이 있습니다.

개별 화면 탐색 및 구성요소 수명 주기와 관계없이 미리 로드 상태를 유지합니다.
앱 전체에서 단일 공유 인스턴스에 광고 이벤트 콜백, 상태 추적, 삭제를 중앙 집중화합니다.
포그라운드 이벤트가 수신되는 시점을 제어하여 광고가 닫힐 때 중복 표시를 방지합니다.

다음 예에서는 AppOpenAdPreloader 객체를 사용하여 앱 수준 관리자를 구현합니다.

export class AppOpenAdManager {
  private adUnitId: string;
  private preloadId: string;
  private appStateSubscription?: NativeEventSubscription;
  private startTimeoutId?: ReturnType<typeof setTimeout>;

  constructor(adUnitId: string, preloadId: string) {
    this.adUnitId = adUnitId;
    this.preloadId = preloadId;
  }

  start(): boolean {
    if (!AppOpenAdPreloader.getConfiguration(this.preloadId)) {
      AppOpenAdPreloader.start(
        this.preloadId,
        {
          request: {adUnitId: this.adUnitId},
          bufferSize: 2,
        },
        {
          onAdPreloaded: (event) => {
            console.log(`App open ad preloaded for ${event.preloadId}`);
          },
          onAdFailedToPreload: (error: LoadAdError) => {
            console.error('Failed to preload app open ad:', error.message);
          },
          onAdsExhausted: () => {
            console.log('App open ad buffer exhausted.');
          },
        },
      );
    }

    if (!this.appStateSubscription && !this.startTimeoutId) {
      // Delay attaching the listener to ensure native dismissal transitions complete
      this.startTimeoutId = setTimeout(() => {
        this.startTimeoutId = undefined;
        if (!this.appStateSubscription) {
          this.appStateSubscription = AppState.addEventListener(
            'change',
            (nextAppState: AppStateStatus) => {
              if (nextAppState === 'active') {
                this.showAdIfAvailable();
              }
            },
          );
        }
      }, APP_STATE_LISTENER_DELAY_MS);
    }

    return true;
  }

  pause(): void {
    if (this.startTimeoutId) {
      clearTimeout(this.startTimeoutId);
      this.startTimeoutId = undefined;
    }
    this.appStateSubscription?.remove();
    this.appStateSubscription = undefined;
  }

  stop(): void {
    this.pause();
    AppOpenAdPreloader.destroy(this.preloadId);
  }

  showAdIfAvailable() {
    if (!AppOpenAdPreloader.isAdAvailable(this.preloadId)) {
      console.log('App open ad is not preloaded or available right now.');
      return;
    }

    const ad = AppOpenAdPreloader.pollAd(this.preloadId);
    if (!ad) {
      return;
    }

    // Pause listener while presenting the ad
    this.pause();

    ad.adEventCallback = {
      onAdShowedFullScreenContent: () => {
        console.log('Preloaded app open ad showed full screen content.');
      },
      onAdDismissedFullScreenContent: () => {
        console.log('Preloaded app open ad dismissed full screen content.');
        ad.destroy();
        this.start();
      },
      onAdFailedToShowFullScreenContent: (error) => {
        console.error('Failed to show preloaded app open ad:', error);
        ad.destroy();
        this.start();
      },
    };

    ad.show();
  }
}

앱 포그라운드 이벤트 수신

앱이 포그라운드로 돌아올 때 광고를 표시하려면 앱의 루트 구성요소(예: App.tsx)에 있는 AppState 모듈에 change 리스너를 등록하세요. 상태가 active로 전환되는 시점을 확인합니다. 예를 들어 App.tsx 구성요소의 광고 관리자 인스턴스에서 start 메서드를 호출합니다.

전체 화면 광고를 표시하거나 배너 광고를 탭하는 등 광고 오버레이 또는 방문 페이지를 표시하면 애플리케이션이 백그라운드로 푸시됩니다. 사용자가 애플리케이션으로 돌아오면 앱은 새로운 active 상태 이벤트를 수신합니다. 광고에서 돌아올 때 캐시에서 앱 오프닝 광고를 표시하는 의도하지 않은 광고 표시 또는 루프를 방지하려면 다음 단계를 따르세요.

전체 화면 광고를 표시하기 전에 AppState 이벤트 리스너를 삭제합니다.
사용자가 광고를 닫거나 광고가 표시되지 않는 경우에도 수신이 재개되도록 하려면 onAdDismissedFullScreenContent 및 onAdFailedToShowFullScreenContent 콜백에 AppState 이벤트 리스너를 다시 추가하세요.

포그라운드 이벤트 리스너가 일시중지되고 재개되는 시점을 제어하는 전체 예시는 AppOpenAdManager 구현을 참고하세요.

콜드 스타트 및 로드 화면 알아보기

콜드 스타트는 앱이 처음부터 실행될 때 발생합니다. 예를 들어 사용자가 앱을 처음으로 열거나 기기에서 메모리를 확보하기 위해 앱을 닫은 후에 발생합니다. 콜드 스타트 중에는 다음에 표시할 미리 로드된 앱 오프닝 광고가 없습니다.

광고 요청 지연으로 인해 광고가 표시되기 전에 사용자가 앱과 상호작용할 수 있습니다. 앱 애셋이 로드되는 동안 로드 화면에서만 콜드 스타트 시점에 앱 오프닝 광고를 표시합니다. 광고가 로드되기 전에 애셋 로드가 완료되고 사용자가 기본 콘텐츠에 도달하면 광고를 표시하지 않습니다.

리소스 삭제

광고를 미리 로드하는 화면에서 벗어나는 경우와 같이 화면 또는 광고 단위 ID에 더 이상 미리 로드가 필요하지 않은 경우 AppOpenAdPreloader.destroy 메서드를 호출하여 미리 로드 도구 리소스를 해제하고 사용하지 않는 광고 객체가 메모리에 보관되지 않도록 합니다.

export function destroyAppOpenAdPreloader(preloadId: string) {
  AppOpenAdPreloader.destroy(preloadId);
}

미리 로드 도구 큐를 소멸시키는 것 외에도 사용자가 광고를 닫거나 광고가 표시되지 않을 때 개별 폴링된 광고 인스턴스를 소멸시켜야 합니다. 자세한 내용은 광고 폴링 및 표시를 참고하세요.

전체 예시 보기

다음 예시 구성요소는 마운트 시 미리 로드를 시작하고, 사용 가능한 광고 수를 추적하며, 미리 로드된 앱 오프닝 광고를 표시하는 컨트롤을 제공합니다.

export function AppOpenScreen() {
  const [numAdsAvailable, setNumAdsAvailable] = useState<number>(0);
  const [status, setStatus] = useState<string>('Preloader idle.');

  const refreshAdCount = () => {
    const count = AppOpenAdPreloader.getNumAdsAvailable(PRELOAD_ID);
    setNumAdsAvailable(count);
  };

  useEffect(() => {
    // Start preloading ads on component mount
    const started = startAppOpenAdPreloader(APP_OPEN_AD_UNIT_ID, PRELOAD_ID, {
      onAdPreloaded: () => {
        refreshAdCount();
        setStatus('App open ad preloaded into buffer.');
      },
      onAdFailedToPreload: (error) => {
        setStatus(`Failed to preload app open ad: ${error.message}`);
      },
      onAdsExhausted: () => {
        refreshAdCount();
        setStatus('Preload buffer exhausted for app open ads.');
      },
    });
    if (started) {
      setStatus('Preloader started.');
    }

    // Clean up preloader resources on component unmount
    return () => {
      destroyAppOpenAdPreloader(PRELOAD_ID);
    };
  }, []);

  const handleShowAd = () => {
    setStatus('Showing preloaded ad...');
    showPreloadedAppOpenAd(PRELOAD_ID, {
      onAdDismissedFullScreenContent: () => {
        setStatus('Ad dismissed.');
      },
      onAdFailedToShowFullScreenContent: (error) => {
        setStatus(`Failed to show preloaded ad: ${error.message}`);
      },
    });
    refreshAdCount();
  };

  return (
    <View style={styles.container}>
      <Text style={styles.title}>Preload App Open Ads</Text>
      <Text style={styles.status}>Status: {status}</Text>
      <Text style={styles.status}>Ads Available: {numAdsAvailable}</Text>
      <View style={styles.buttonGroup}>
        <Button
          title="Show Preloaded Ad"
          onPress={handleShowAd}
          disabled={numAdsAvailable === 0}
        />
      </View>
    </View>
  );
}

다음을 바꿉니다.

APP_OPEN_AD_UNIT_ID를 광고 단위 ID로 교체
PRELOAD_ID를 미리 로드 도구 ID로 바꿉니다.

다음 단계

앱 오프닝 광고를 통합한 후 다음 주제를 살펴보세요.

앱 오프닝 광고 설정 컬렉션을 사용해 정리하기 내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.