הגדרה של תכונות מותאמות מתקדמות

מודעות מותאמות כוללות את התכונות המתקדמות הבאות, שמאפשרות לכם להתאים אישית את שילוב המודעות:

  • רכיבי UI להפעלת סרטונים: התאמה אישית של אופן ההפעלה של הסרטונים והאזנה לאירועים במחזור החיים של הסרטונים.
  • מיקום הסמל של 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.

האזנה לאירועי וידאו

כדי להאזין לאירועים במחזור החיים של הסרטון, למשל כשהסרטון מתחיל או מסתיים, מעבירים קריאות חוזרות (callbacks) של אירועים מהממשק VideoControllerEventProps לרכיב NativeAdMediaView.

בדוגמה הבאה, קריאות חוזרות (callbacks) מועברות כדי לתעד אירועים במחזור החיים של הסרטון, ומוצגים כפתורים בהתאמה אישית לשליטה בהפעלת הסרטון:

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 כדי לוודא שתנועות הקליק בהתאמה אישית פעילות במודעה הזו.

השלבים הבאים

אחרי שמגדירים את התכונות המתקדמות של המודעות המותאמות, אפשר לקרוא מידע נוסף על הנושאים הבאים: