ตั้งค่าโฆษณาเปิดแอป

โฆษณาเปิดแอปจะปรากฏขึ้นเมื่อผู้ใช้เปิดหรือกลับมาที่แอปของคุณ โดยผู้ใช้จะปิดโฆษณาเปิดแอปได้ทุกเมื่อ หากต้องการสร้างรายได้จากหน้าจอโหลดแอป ให้ใช้โฆษณาเปิดแอป ดูรายละเอียดได้ที่คำแนะนำและแนวทางปฏิบัติแนะนำสำหรับโฆษณาเปิดแอป

คู่มือนี้อธิบายวิธีผสานรวมโฆษณาเปิดแอปเข้ากับแอป React Native

ข้อกำหนดเบื้องต้น

โปรดทำสิ่งต่อไปนี้ก่อนดำเนินการต่อ

Android 

ca-app-pub-3940256099942544/9257395921

iOS 

ca-app-pub-3940256099942544/5575463023

ทำความเข้าใจการโหลดโฆษณาล่วงหน้า

การโหลดโฆษณาล่วงหน้าใน Google Mobile Ads SDK for React Native จะโหลดและแคชโฆษณาโดยอัตโนมัติ

การโหลดโฆษณาล่วงหน้ามีประโยชน์ดังนี้

  • การจัดการข้อมูลอ้างอิง: เก็บข้อมูลอ้างอิงไว้จนกว่าโฆษณาจะแสดง
  • การโหลดซ้ำอัตโนมัติ: โหลดโฆษณาใหม่เมื่อดึงโฆษณาจากแคช
  • การลองใหม่ที่มีการจัดการ: โหลดโฆษณาใหม่เมื่อโหลดโฆษณาไม่สำเร็จ
  • การจัดการการหมดอายุ: รีเฟรชโฆษณาก่อนหมดอายุ
  • การเพิ่มประสิทธิภาพแคช: เพิ่มประสิทธิภาพลำดับแคชเพื่อแสดงโฆษณาที่มีลำดับความสำคัญสูงสุด

หากต้องการโหลดโฆษณาด้วยตนเอง โปรดดูคู่มือโหลดโฆษณาเปิดแอปรายการเดียว

เริ่มโหลดล่วงหน้า

หากต้องการเริ่มโหลดโฆษณาล่วงหน้า ให้เรียกใช้เมธอด AppOpenAdPreloader.start และส่งค่า preloadId, การตั้งค่า และ Callback ของเหตุการณ์เพื่อตรวจสอบการเปลี่ยนแปลงสถานะบัฟเฟอร์ ดังนี้

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 สำหรับการกำหนดค่าการโหลดล่วงหน้าเพียงรายการเดียวในแอป คุณสามารถใช้รหัสหน่วยโฆษณานั้นเป็นรหัสการโหลดล่วงหน้าได้ หากแอปของคุณต้องใช้ตัวโหลดล่วงหน้าหลายตัวสำหรับรหัสหน่วยโฆษณาเดียวกัน ให้ส่งสตริงที่แตกต่างกันสำหรับรหัสการโหลดล่วงหน้าแต่ละรหัส

เมื่อแอปของคุณดึงโฆษณาที่โหลดไว้ล่วงหน้าจากบัฟเฟอร์ Google Mobile Ads SDK for React Native จะขอโฆษณาทดแทนในเบื้องหลังเพื่อเติมบัฟเฟอร์อีกครั้ง หากไม่มีโฆษณาที่โหลดไว้ล่วงหน้าเหลืออยู่ในบัฟเฟอร์ Google Mobile Ads SDK for React Native จะเรียกใช้ Callback onAdsExhausted

ขีดจำกัดแคชที่โหลดล่วงหน้า

Google Mobile Ads SDK for React Native บังคับใช้ขีดจำกัดทั่วทั้งแอปสำหรับจำนวนโฆษณาที่โหลดไว้ล่วงหน้าทั้งหมด ดังนี้

  • ขีดจำกัดเริ่มต้น: Google จะเก็บโฆษณาที่โหลดไว้ล่วงหน้าไว้ในหน่วยความจำได้สูงสุด 6 รายการ
  • เราขอแนะนำให้ใช้ขนาดบัฟเฟอร์เป็น 2 สำหรับรหัสการโหลดล่วงหน้าแต่ละรหัส

หากแอปถึงขีดจำกัดทั่วทั้งแอป คำขอในเบื้องหลังสำหรับโฆษณาที่โหลดไว้ล่วงหน้าจะหยุดชั่วคราวจนกว่าโฆษณาที่มีอยู่จะได้รับการสำรวจและแสดงหรือทำลาย

สำรวจและแสดงโฆษณา

หากต้องการตรวจสอบโฆษณาที่โหลดไว้ล่วงหน้าซึ่งพร้อมใช้งานและดึงข้อมูลอินสแตนซ์โฆษณา ให้เรียกใช้เมธอด AppOpenAdPreloader.pollAd

หากต้องการฟังเหตุการณ์การนำเสนอแบบเต็มหน้าจอ ให้ลงทะเบียน Callback ในพร็อพเพอร์ตี้ adEventCallback ของอินสแตนซ์ AppOpenAd ที่แสดงผลก่อนเรียกใช้เมธอด show ดังนี้

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();
}

หากต้องการปล่อยหน่วยความจำและทรัพยากร ให้เรียกใช้เมธอด ad.destroy ใน Callback onAdDismissedFullScreenContent และ onAdFailedToShowFullScreenContent เมื่อผู้ใช้ปิดโฆษณาหรือโฆษณาไม่แสดง

อ่านข้อมูลการตอบกลับ

หากต้องการตรวจสอบรายละเอียดของโฆษณาที่โหลดไว้ล่วงหน้าถัดไปโดยไม่นำโฆษณาออกจากแคช ให้เรียกใช้เมธอด 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;
}

จัดการโฆษณาเปิดแอปด้วยเครื่องมือจัดการระดับแอป

เนื่องจากโฆษณาเปิดแอปจะแสดงทั่วโลกในระหว่างการเปิดแอปและการเปลี่ยนไปใช้แอปที่ทำงานอยู่เบื้องหน้า เราขอแนะนำให้จัดการสถานะวงจรของ Preloader ในเครื่องมือจัดการระดับแอปนอกแผนผังคอมโพเนนต์ React

การใช้เครื่องมือจัดการระดับแอปมีข้อดีหลักๆ หลายประการดังนี้

  • ทำให้สถานะของตัวโหลดล่วงหน้าเป็นอิสระจากการนำทางหน้าจอและวงจรของคอมโพเนนต์แต่ละรายการ
  • รวมศูนย์ Callback ของเหตุการณ์โฆษณา การติดตามสถานะ และการล้างข้อมูลไว้ในอินสแตนซ์ที่ใช้ร่วมกันรายการเดียวในแอป
  • ควบคุมเวลาที่ระบบจะฟังเหตุการณ์การนำแอปไปไว้เบื้องหน้า เพื่อป้องกันไม่ให้มีการนำเสนอซ้ำเมื่อปิดโฆษณา

ตัวอย่างต่อไปนี้ใช้เครื่องมือจัดการระดับแอปโดยใช้ออบเจ็กต์ 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();
  }
}

รอเหตุการณ์การนำแอปไปไว้เบื้องหน้า

หากต้องการแสดงโฆษณาเมื่อแอปกลับมาทำงานอยู่เบื้องหน้า ให้ลงทะเบียน Listener change ในโมดูล AppState ในคอมโพเนนต์รูทของแอป เช่น App.tsx ตรวจสอบเมื่อสถานะเปลี่ยนเป็น active เช่น เรียกใช้เมธอด start ในอินสแตนซ์ตัวจัดการโฆษณาในคอมโพเนนต์ App.tsx

การแสดงหน้าต่างซ้อนทับโฆษณาหรือหน้า Landing Page เช่น การแสดงโฆษณาแบบเต็มหน้าจอหรือการแตะโฆษณาแบนเนอร์ จะทำให้แอปพลิเคชันของคุณทำงานอยู่เบื้องหลัง เมื่อผู้ใช้กลับมาที่แอปพลิเคชัน แอปจะได้รับเหตุการณ์สถานะ active ใหม่ เพื่อป้องกันการนำเสนอโฆษณาหรือการวนซ้ำโดยไม่ตั้งใจ ซึ่งการกลับมาจากโฆษณาจะแสดงโฆษณาเปิดแอปจากแคช ให้ทำดังนี้

  1. นำ Listener เหตุการณ์ AppState ออกก่อนแสดงโฆษณาแบบเต็มหน้าจอ
  2. หากต้องการให้แน่ใจว่าการฟังจะกลับมาทำงานอีกครั้งไม่ว่าผู้ใช้จะปิดโฆษณาหรือโฆษณาไม่แสดง ให้เพิ่ม Listener เหตุการณ์ AppState อีกครั้งใน Callback onAdDismissedFullScreenContent และ onAdFailedToShowFullScreenContent

ดูตัวอย่างที่สมบูรณ์ของการควบคุมเวลาที่หยุดชั่วคราวและกลับมาทำงานต่อของ Listener เหตุการณ์ที่ทำงานอยู่เบื้องหน้าได้ที่การติดตั้งใช้งาน AppOpenAdManager

ดูข้อมูลเกี่ยวกับ Cold Start และหน้าจอการโหลด

Cold Start เกิดขึ้นเมื่อแอปของคุณเปิดขึ้นใหม่ตั้งแต่ต้น เช่น เมื่อผู้ใช้เปิดแอปเป็นครั้งแรกหรือหลังจากที่อุปกรณ์ปิดแอปเพื่อเพิ่มหน่วยความจำ ในระหว่างการเริ่มแอปแบบ Cold Start คุณจะไม่มีโฆษณาเปิดแอปที่โหลดไว้ก่อนหน้านี้เพื่อแสดงในครั้งถัดไป

เนื่องจากความล่าช้าของคำขอโฆษณา ผู้ใช้อาจโต้ตอบกับแอปก่อนที่โฆษณาจะปรากฏ แสดงโฆษณาเปิดแอปใน Cold Start จากหน้าจอการโหลดเท่านั้นขณะที่โหลดชิ้นงานของแอป หากชิ้นงานโหลดเสร็จและผู้ใช้เข้าถึงเนื้อหาหลักก่อนที่การโหลดโฆษณาจะเสร็จสิ้น ก็ไม่ต้องแสดงโฆษณา

ล้างทรัพยากร

เมื่อไม่จำเป็นต้องโหลดล่วงหน้าสำหรับหน้าจอหรือรหัสหน่วยโฆษณาอีกต่อไป เช่น เมื่อออกจากหน้าจอที่โหลดโฆษณาล่วงหน้า ให้เรียกใช้เมธอด 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 ด้วยรหัสหน่วยโฆษณา
  • PRELOAD_ID ด้วยรหัส Preloader

ขั้นตอนถัดไป

หลังจากผสานรวมโฆษณาเปิดแอปแล้ว ให้สำรวจหัวข้อต่อไปนี้