راه‌اندازی آگهی‌های باز کردن برنامه

آگهی‌های باز شدن برنامه زمانی ظاهر می‌شوند که کاربران برنامه شما را باز می‌کنند یا به آن برمی‌گردند. کاربران شما می‌توانند آگهی‌های باز شدن برنامه را هرزمان که بخواهند ببندند. برای درآمدزایی از صفحه بار کردن برنامه، از آگهی‌های باز شدن برنامه استفاده کنید. برای جزئیات، به راهنمایی و روال‌های مطلوب آگهی در صفحه باز شدن برنامه مراجعه کنید.

این راهنما نحوه ادغام آگهی‌های باز شدن برنامه را در برنامه 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 فقط برای یک پیکربندی پیش‌بارگیری در برنامه‌تان استفاده می‌شود، می‌توانید از آن شناسه واحد آگهی به‌عنوان شناسه پیش‌بارگیری استفاده کنید. اگر برنامه‌تان به چند پیش‌بارگذار برای یک شناسه واحد آگهی نیاز دارد، رشته‌های متمایزی برای هر شناسه پیش‌بارگذاری ارسال کنید.

وقتی برنامه‌تان آگهی پیش‌بارشده‌ای را از میان‌گیر نظرسنجی می‌کند، Google Mobile Ads SDK for React Native درخواست آگهی جایگزین در پس‌زمینه می‌کند تا میان‌گیر را دوباره پر کند. اگر هیچ آگهی پیش‌بارشده‌ای در میان‌گیر باقی نمانده باشد، Google Mobile Ads SDK for React Native فراخوان برگشتی onAdsExhausted را فراخوانی می‌کند.

حدود حافظه نهان پیش‌بارکردن

Google Mobile Ads SDK for React Native محدودیتی را در سطح برنامه برای تعداد کل آگهی‌های پیش‌بارشده اعمال می‌کند:

  • محدودیت پیش‌فرض: Google حداکثر شش آگهی پیش‌بارشده را در حافظه نگه می‌دارد.
  • توصیه می‌کنیم برای هر شناسه پیش‌بارگیری، اندازه میان‌گیر را روی دو نگه دارید.

اگر برنامه شما به حد مجاز سراسری برنامه برسد، درخواست‌های پس‌زمینه برای آگهی‌های پیش‌بارشده موقتاً متوقف می‌شود تا زمانی که آگهی‌های موجود نظرسنجی و نمایش داده شوند یا ازبین بروند.

نظرسنجی و نمایش آگهی

برای بررسی آگهی‌های پیش‌بارشده دردسترس و بازیابی نمونه آگهی، روش AppOpenAdPreloader.pollAd را فراخوانی کنید.

برای گوش دادن به رویدادهای ارائه تمام‌صفحه، قبل‌از فراخوانی روش show، فراخوان‌های برگشتی را در ویژگی adEventCallback نمونه AppOpenAd برگردانده‌شده ثبت کنید:

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 را در فراخوانی‌های برگشتی 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;
}

مدیریت آگهی‌های باز شدن برنامه با مدیر سطح برنامه

Because app open ads are presented globally during app launch and foreground transitions, we recommend managing preloader lifecycle state in an app-level manager outside the React component tree.

استفاده از مدیر سطح برنامه چندین مزیت کلیدی دارد:

  • وضعیت پیش‌بارگذار را مستقل از پیمایش صفحه تکی و چرخه حیات مؤلفه نگه می‌دارد.
  • فراخوانی‌های برگشتی رویداد آگهی، ردگیری وضعیت، و پاک‌سازی را در یک نمونه مشترک واحد در سراسر برنامه‌تان متمرکز می‌کند.
  • کنترل می‌کند که چه زمانی رویدادهای پیش‌زمینه شنیده شوند، و از ارائه تکراری هنگام رد کردن آگهی جلوگیری می‌کند.

مثال زیر مدیر سطح برنامه را بااستفاده از شیء 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();
  }
}

گوش دادن به رویدادهای پیش‌زمینه برنامه

برای نمایش آگهی‌ها هنگام بازگشت برنامه به پیش‌زمینه، یک شنونده change را در ماژول AppState در مؤلفه ریشه برنامه خود ثبت کنید، مانند App.tsx. بررسی کنید که وضعیت چه زمانی به active تغییر می‌کند. برای مثال، روش start را در نمونه مدیر آگهی‌تان در مؤلفه App.tsx فراخوانی کنید.

ارائه هم‌پوشانی‌های آگهی یا صفحه‌های مقصد، مانند نمایش آگهی‌های تمام‌صفحه یا تک‌ضرب زدن روی آگهی برنما، برنامه‌تان را به پس‌زمینه می‌برد. وقتی کاربر به برنامه‌تان برمی‌گردد، برنامه شما رویداد حالت active جدیدی دریافت می‌کند. برای جلوگیری از ارائه یا حلقه آگهی ناخواسته که در آن بازگشت از آگهی، آگهی در صفحه باز شدن برنامه را از حافظه نهان ارائه می‌دهد، کارهای زیر را انجام دهید:

  1. قبل‌از ارائه آگهی تمام‌صفحه، شنونده رویداد AppState را بردارید.
  2. برای اطمینان از اینکه گوش دادن ازسر گرفته می‌شود، چه کاربر آگهی را ببندد یا آگهی نمایش داده نشود، شنونده رویداد AppState را دوباره در فراخوانی‌های برگشتی onAdDismissedFullScreenContent و onAdFailedToShowFullScreenContent اضافه کنید.

برای مشاهده نمونه کاملی از کنترل کردن زمان توقف موقت و ازسرگیری شنوندگان رویداد پیش‌زمینه، پیاده‌سازی AppOpenAdManager را ببینید.

با شروع سرد و صفحه‌های بار کردن آشنا شوید

راه‌اندازی سرد زمانی اتفاق می‌افتد که برنامه شما از ابتدا راه‌اندازی می‌شود، برای مثال، وقتی کاربر برای اولین‌بار برنامه شما را باز می‌کند یا پس‌از اینکه دستگاه برنامه را برای آزاد کردن حافظه می‌بندد. درطول راه‌اندازی سرد، آگهی در صفحه باز شدن برنامه که قبلاً بار شده باشد ندارید تا بعداً نشان دهید.

به‌دلیل تأخیر در درخواست آگهی، ممکن است کاربران شما قبل‌از ظاهر شدن آگهی با برنامه‌تان تعامل داشته باشند. آگهی‌های در صفحه باز شدن برنامه را در راه‌اندازی سرد فقط از صفحه بار کردن نشان دهید، درحالی‌که دارایی‌های برنامه بار می‌شود. اگر بار کردن دارایی‌ها تمام شود و کاربر قبل‌از بار شدن آگهی به محتوای اصلی برسد، آگهی را نشان ندهید.

پاک‌سازی منابع

وقتی پیش‌بارگیری دیگر برای شناسه واحد آگهی یا صفحه لازم نیست، مثلاً وقتی از صفحه‌ای که آگهی‌ها را پیش‌بارگیری می‌کند خارج می‌شوید، روش 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 با شناسه پیش‌بارگذار شما.

مراحل بعدی

پس‌از ادغام آگهی‌های باز شدن برنامه، موضوعات زیر را کاوش کنید: