تنظیم ویژگی‌های بومی پیشرفته

آگهی‌های بومی ویژگی‌های پیشرفته زیر را ارائه می‌دهند که به شما امکان می‌دهند ادغام آگهی‌تان را سفارشی‌سازی کنید:

  • کنترل‌های بازپخش ویدیو: سفارشی‌سازی رفتار بازپخش ویدیو و گوش دادن به رویدادهای چرخه حیات ویدیو.
  • جای نماد AdChoices: جای نماد AdChoices را سفارشی‌سازی کنید.
  • اشاره‌های کلیک سفارشی: اشاره‌های تند کشیدن را به‌عنوان کنش‌های کلیک پیکربندی کنید.

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

پیش‌نیازها

پیش‌از ادامه دادن، کارهای زیر را انجام دهید:

مدیریت کردن بازپخش ویدیو و رویدادها

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

پیکربندی گزینه‌های درخواست ویدیو

برای سفارشی‌سازی کردن رفتار اولیه ویدیو، ویژگی videoOptions را در شیء NativeAdRequest بااستفاده از شیء VideoOptions تنظیم کنید.

مثال زیر ویدیو را طوری تنظیم می‌کند که هنگام شروع بازپخش، بی‌صدا شروع شود:

export async function loadNativeVideoAd(
  adUnitId: string,
): Promise<NativeAd | null> {
  try {
    const ad = await NativeAd.load({
      adUnitId,
      videoOptions: {
        // Autoplay video with sound muted.
        startMuted: true,
      },
    });

    // Inspect video metadata if the ad contains video content.
    if (ad.mediaContent.hasVideoContent) {
      console.log('Video duration in seconds:', ad.mediaContent.duration);
      console.log('Video aspect ratio:', ad.mediaContent.aspectRatio);
    }

    return ad;
  } catch (error) {
    const loadError = error as LoadAdError;
    console.error('Failed to load native video ad:', loadError.message);
    return null;
  }
}

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

برای اطلاعات بیشتر درباره ویژگی‌های فراداده ویدیو، مانند نسبت ابعادی، زمان فعلی، و مدت، به MediaContent مراجعه کنید.

گوش دادن به رویدادهای ویدیویی

برای گوش دادن به رویدادهای چرخه حیات ویدیو، مثلاً وقتی ویدیو شروع یا تمام می‌شود، فراخوان‌های برگشتی رویداد را از میانای VideoControllerEventProps به مؤلفه NativeAdMediaView ارسال کنید.

مثال زیر فراخوان‌های برگشتی را برای ثبت رویدادهای چرخه حیات ویدیو ارسال می‌کند و دکمه‌های سفارشی را برای کنترل بازپخش ویدیو ارائه می‌دهد:

export function NativeAdWithVideoControls({ad}: {ad: NativeAd}) {
  const mediaViewRef = useRef<NativeAdMediaViewMethods>(null);

  return (
    <NativeAdView ad={ad}>
      {/* Video lifecycle callbacks */}
      <NativeAdMediaView
        ref={mediaViewRef}
        // Called when video playback starts.
        onVideoStart={() => {
          console.log('Video playback started.');
        }}
        // Called when video playback resumes or plays.
        onVideoPlay={() => {
          console.log('Video is playing.');
        }}
        // Called when video playback pauses.
        onVideoPause={() => {
          console.log('Video playback paused.');
        }}
        // Called when video playback completes.
        onVideoEnd={() => {
          console.log('Video playback finished.');
        }}
        // Called when the video mute state changes.
        onVideoMute={(isMuted: boolean) => {
          console.log(`Video mute state changed: ${isMuted}`);
        }}
      />

      {/* Custom playback controls (Ad Manager customControlsRequested only) */}
      <View>
        {/* Plays or resumes the video. */}
        <Button
          title="Play"
          onPress={() => mediaViewRef.current?.playVideo()}
        />
        {/* Pauses video playback. */}
        <Button
          title="Pause"
          onPress={() => mediaViewRef.current?.pauseVideo()}
        />
        {/* Stops video playback and resets the playback position to the beginning. */}
        <Button
          title="Stop"
          onPress={() => mediaViewRef.current?.stopVideo()}
        />
        {/* Mutes or unmutes audio. */}
        <Button
          title="Mute"
          onPress={() => mediaViewRef.current?.setVideoMuted(true)}
        />
        <Button
          title="Unmute"
          onPress={() => mediaViewRef.current?.setVideoMuted(false)}
        />
      </View>
    </NativeAdView>
  );
}

وقتی کنترل‌های سفارشی را فعال می‌کنید، بازپخش ویدیو را با پیوست کردن ویژگی ref از نوع NativeAdMediaViewMethods به مؤلفه NativeAdMediaView کنترل کنید. نوع NativeAdMediaViewMethods نام مستعار میانای VideoControllerMethods است که روش‌های playVideo، pauseVideo، stopVideo، و setVideoMuted را در شیء ref نشان می‌دهد.

پیکربندی جای آگهی AdChoices

برای سفارشی‌سازی کردن جای نماد AdChoices، ویژگی adChoicesPlacement را در شیء NativeAdRequest بااستفاده از شیء AdChoicesPlacement مشخص کنید.

مثال زیر جای نماد AdChoices را در گوشه بالا سمت چپ درخواست آگهی پیکربندی می‌کند:

export async function loadNativeAdWithAdChoicesPlacement(
  adUnitId: string,
): Promise<NativeAd | null> {
  try {
    const ad = await NativeAd.load({
      adUnitId,
      // Render the AdChoices icon in the top-left corner.
      adChoicesPlacement: AdChoicesPlacement.TOP_LEFT,
    });
    return ad;
  } catch (error) {
    const loadError = error as LoadAdError;
    console.error('Failed to load native ad:', loadError.message);
    return null;
  }
}

این نمونه همچنین آگهی بارشده را درصورت موفقیت برمی‌گرداند و پیام خطایی را درصورت عدم موفقیت ثبت می‌کند.

پیکربندی کردن اشاره‌های کلیک سفارشی

اشاره‌های تند کشیدن را به‌عنوان کنش‌های کلیک در آگهی‌های بومی بااستفاده از ویژگی‌های customClickGestureDirection و customClickGestureAllowTaps در شیء NativeAdRequest پیکربندی کنید.

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

export async function loadNativeAdWithCustomClick(
  adUnitId: string,
): Promise<NativeAd | null> {
  try {
    const ad = await NativeAd.load({
      adUnitId,
      // Require a right swipe gesture for clicks while allowing standard taps.
      customClickGestureDirection: SwipeGestureDirection.RIGHT,
      customClickGestureAllowTaps: true,
    });

    if (ad.isCustomClickGestureEnabled) {
      console.log('Custom click gestures are enabled for this ad.');
    }

    return ad;
  } catch (error) {
    const loadError = error as LoadAdError;
    console.error('Failed to load native ad:', loadError.message);
    return null;
  }
}

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

پس‌از بار کردن آگهی، ویژگی ad.isCustomClickGestureEnabled را بررسی کنید تا مطمئن شوید اشاره‌های کلیک سفارشی برای آن آگهی فعال است.

مراحل بعدی

پس‌از پیکربندی ویژگی‌های پیشرفته آگهی‌های بومی، می‌توانید درباره موارد زیر اطلاعات کسب کنید: