הצגת מודעות מותאמות

כאשר מודעה מותאמת נטענת, האפליקציה מקבלת אובייקט מודעה שמכיל נכסים שמצורפים למודעה, כמו תמונות, טקסט וסרטונים. האפליקציה אחראית להצגת הנכסים שמצורפים למודעה בפריסה של תצוגת המודעה המותאמת. כדי להציג מודעות מותאמות בהתאם למדיניות, Google Mobile Ads SDK for React Native מספק את הרכיבים הבאים:

פרטים על הצגת מודעות מותאמות בהתאם למדיניות זמינים במאמר מודעות מותאמות שמשתמשות בפורמט "מודעה מותאמת מסוג Advanced".

בדף הזה מוסבר איך לרנדר נכסים שמצורפים למודעות מותאמות, להגדיר תוכן מדיה ולטפל באירועים של מודעות באמצעות Google Mobile Ads SDK for React Native.

דרישות מוקדמות

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

הגדרת רכיב התצוגה של המודעה המותאמת

הרכיב NativeAdView הוא מאגר האב של הפריסה של המודעה המותאמת. הרכיב הזה כולל את כל התצוגות של הנכסים הנפרדים ומקשר את התצוגות של הנכסים למופע של NativeAd שנטען.

כשעוטפים את הנכסים ברכיב NativeAdView, קורים הדברים הבאים:

  • תיעוד חשיפות כשהמודעה מוצגת במסך.
  • לתעד קליקים ולטפל בניווט כשמשתמשים לוחצים על נכסים אינטראקטיביים.
  • להציג את שכבת-העל של AdChoices ולמקם אותה.

סימן למודעה ו-AdChoices

הסימן למודעה ושכבת העל של AdChoices הם דרישות מדיניות חובה בכל ההטמעות של מודעות מותאמות של Google.

כשעוטפים את הפריסה ב-NativeAdView, Google Mobile Ads SDK for React Native מעבד באופן אוטומטי את הסמל של AdChoices בפינה השמאלית העליונה של תצוגת המודעה כברירת מחדל. לא צריך להוסיף קוד בהתאמה אישית או תצוגות של נכסים כדי שהסמל יופיע.

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

אכלוס ורישום של תצוגות נכסים

כדי לרשום צפיות בנכסים באמצעות Google Mobile Ads SDK for React Native, צריך לעטוף כל רכיב של נכס ב-wrapper מסוג NativeAdView.Asset ולציין את סוג הנכס באמצעות האובייקט NativeAdAssetNames. כל wrapper מסוג NativeAdView.Asset חייב להכיל רכיב מארח יחיד של React Native, כמו Text,‏ Image או View, שמקבל את המאפיין nativeID. לפרטים על מאפייני הנכסים הזמינים, ראו Class NativeAd.

בטבלה הבאה מפורטים סוגי הנכסים הזמינים, מאפייני היעד ודוגמאות לרישום תצוגות הנכסים:

סוג הנכס תיאור ודוגמאות
ADVERTISER

נכס היעד: NativeAd.advertiser

{/* The advertiser or sponsor name (optional). */}
{ad.advertiser && (
  <NativeAdView.Asset type={NativeAdAssetNames.ADVERTISER}>
    <Text>{ad.advertiser}</Text>
  </NativeAdView.Asset>
)}
BODY

נכס היעד: NativeAd.body

{/* Detailed description text (optional). */}
{ad.body && (
  <NativeAdView.Asset type={NativeAdAssetNames.BODY}>
    <Text>{ad.body}</Text>
  </NativeAdView.Asset>
)}
CALL_TO_ACTION

נכס היעד: NativeAd.callToAction

{/* Action button text such as "Install" or "Shop Now" (optional). */}
{ad.callToAction && (
  <NativeAdView.Asset type={NativeAdAssetNames.CALL_TO_ACTION}>
    <View>
      <Text>{ad.callToAction}</Text>
    </View>
  </NativeAdView.Asset>
)}
HEADLINE

נכס היעד: NativeAd.headline

{/* The main title of the ad (required). */}
<NativeAdView.Asset type={NativeAdAssetNames.HEADLINE}>
  <Text>{ad.headline}</Text>
</NativeAdView.Asset>
ICON

נכס היעד: NativeAd.icon

{/* The advertiser logo or app icon (optional). */}
{ad.icon && (
  <NativeAdView.Asset type={NativeAdAssetNames.ICON}>
    <Image source={{uri: ad.icon.uri}} />
  </NativeAdView.Asset>
)}
PRICE

נכס היעד: NativeAd.price

{/* Price string for products or paid apps (optional). */}
{ad.price && (
  <NativeAdView.Asset type={NativeAdAssetNames.PRICE}>
    <Text>{ad.price}</Text>
  </NativeAdView.Asset>
)}
STAR_RATING

נכס היעד: NativeAd.starRating

{/* App rating score from 0 to 5 (optional). */}
{ad.starRating !== undefined && ad.starRating > 0 && (
  <NativeAdView.Asset type={NativeAdAssetNames.STAR_RATING}>
    <Text>★ {ad.starRating.toFixed(1)}</Text>
  </NativeAdView.Asset>
)}
STORE

נכס היעד: NativeAd.store

{/* App store source such as "Google Play" or "App Store" (optional). */}
{ad.store && (
  <NativeAdView.Asset type={NativeAdAssetNames.STORE}>
    <Text>{ad.store}</Text>
  </NativeAdView.Asset>
)}

תמיד להציג באופן מותנה את תצוגות הנכסים האופציונליות הבאות:

  • ad.icon
  • ad.body
  • ad.advertiser
  • ad.price
  • ad.store
  • ad.starRating

אם במודעה מסוימת אין נכסים אופציונליים, האפליקציה לא יכולה להציג רכיבים ריקים בממשק המשתמש.

הצגת תוכן מדיה

הרכיב NativeAdMediaView מעבד את הנכס החזותי של המודעה, כמו סרטונים ותמונות. אם המודעה מכילה קטע וידאו, תצוגת המדיה טוענת את הסרטון ומפעילה אותו. אם המודעה מכילה רק תוכן של תמונה, תצוגת המדיה מעבדת את התמונה הראשית במקום זאת.

החלת המצב של שינוי גודל המדיה

כדי לקבוע את קנה המידה של התמונות במאגר של תצוגת המדיה, צריך להחיל את המאפיין resizeMode על הרכיב NativeAdMediaView:

      {/* Video or image media asset (optional). */}
      <NativeAdMediaView resizeMode={ResizeMode.COVER} />

הערכים הזמינים של ResizeMode כוללים:

הגדרת יחס הגובה-רוחב של המדיה

כדי לבקש נכסי קריאייטיב של מודעות שתואמים ליחס הגובה-רוחב של פריסת תצוגת המדיה, צריך לציין את המאפיין aspectRatio במופע של NativeAdRequest.

בדוגמה הבאה, נשלחת בקשה למודעה מותאמת עם יחס גובה-רוחב של מדיה לרוחב, המודעה שנטענה מוחזרת אם הבקשה מצליחה, ונרשמת הודעת שגיאה אם הבקשה נכשלת:

export async function loadNativeAdWithAspectRatio(
  adUnitId: string,
): Promise<NativeAd | null> {
  try {
    const ad = await NativeAd.load({
      adUnitId,
      aspectRatio: NativeMediaAspectRatio.LANDSCAPE,
    });
    return ad;
  } catch (error) {
    const loadError = error as LoadAdError;
    console.error('Failed to load native ad:', loadError.message);
    return null;
  }
}

הערכים האפשריים של NativeMediaAspectRatio הם:

האזנה לאירועים של מודעות

כדי לקבל התראות על אירועים במחזור החיים של המודעה, כמו חשיפות או קליקים, צריך להעביר קריאות חוזרות (callbacks) של אירועים לרכיב NativeAdView. כאןAdEventCallback מפורטים כל ה-callbacks הזמינים ב-.

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

export function NativeAdWithEvents({ad}: {ad: NativeAd}) {
  return (
    <NativeAdView
      ad={ad}
      // Called when the user taps the ad.
      onAdClicked={() => {
        console.log('Native ad was clicked.');
      }}
      // Called when an impression is recorded.
      onAdImpression={() => {
        console.log('Native ad recorded an impression.');
      }}
      // Called when the ad presents full-screen content.
      onAdShowedFullScreenContent={() => {
        console.log('Native ad showed full screen content.');
      }}
      // Called when full-screen content is dismissed.
      onAdDismissedFullScreenContent={() => {
        console.log('Native ad dismissed full screen content.');
      }}
      // Called when the ad is estimated to have earned money.
      onAdPaid={(adValue: AdValue) => {
        console.log(
          `Native ad paid: ${adValue.amountMicros} ${adValue.currencyCode}`,
        );
      }}
    />
  );
}

לצפייה בדוגמה המלאה

בקטע הזה מופיעה דוגמה מלאה ליצירת רכיב של כרטיס מודעה מותאמת לשימוש חוזר.

בדוגמה הבאה מוגדר הרכיב NativeAdCard, שמציג תג סימון למודעה, מעבד ורושם באופן מותנה נכסים שמצורפים למודעה ספציפיים של מודעות מותאמות, ומעבד את תוכן המדיה באמצעות הרכיב NativeAdMediaView:

export function NativeAdCard({ad}: {ad: NativeAd}) {
  return (
    <NativeAdView ad={ad}>
      {/* 1. Ad Attribution Badge */}
      <View>
        <Text>Ad</Text>
      </View>

      {/* 2. Header: Icon, Headline, Advertiser, and Star Rating */}
      <View>
        {/* The advertiser logo or app icon (optional). */}
        {ad.icon && (
          <NativeAdView.Asset type={NativeAdAssetNames.ICON}>
            <Image source={{uri: ad.icon.uri}} />
          </NativeAdView.Asset>
        )}

        <View>
          {/* The main title of the ad (required). */}
          <NativeAdView.Asset type={NativeAdAssetNames.HEADLINE}>
            <Text>{ad.headline}</Text>
          </NativeAdView.Asset>

          {/* The advertiser or sponsor name (optional). */}
          {ad.advertiser && (
            <NativeAdView.Asset type={NativeAdAssetNames.ADVERTISER}>
              <Text>{ad.advertiser}</Text>
            </NativeAdView.Asset>
          )}

          {/* App rating score from 0 to 5 (optional). */}
          {ad.starRating !== undefined && ad.starRating > 0 && (
            <NativeAdView.Asset type={NativeAdAssetNames.STAR_RATING}>
              <Text>★ {ad.starRating.toFixed(1)}</Text>
            </NativeAdView.Asset>
          )}
        </View>
      </View>

      {/* 3. Media Content */}
      {/* Video or image media asset (optional). */}
      <NativeAdMediaView resizeMode={ResizeMode.COVER} />

      {/* 4. Body Text */}
      {/* Detailed description text (optional). */}
      {ad.body && (
        <NativeAdView.Asset type={NativeAdAssetNames.BODY}>
          <Text>{ad.body}</Text>
        </NativeAdView.Asset>
      )}

      {/* 5. Footer: Price, Store, and Call To Action */}
      <View>
        {/* Price string for products or paid apps (optional). */}
        {ad.price && (
          <NativeAdView.Asset type={NativeAdAssetNames.PRICE}>
            <Text>{ad.price}</Text>
          </NativeAdView.Asset>
        )}

        {/* App store source such as "Google Play" or "App Store" (optional). */}
        {ad.store && (
          <NativeAdView.Asset type={NativeAdAssetNames.STORE}>
            <Text>{ad.store}</Text>
          </NativeAdView.Asset>
        )}

        {/* Action button text such as "Install" or "Shop Now" (optional). */}
        {ad.callToAction && (
          <NativeAdView.Asset type={NativeAdAssetNames.CALL_TO_ACTION}>
            <View>
              <Text>{ad.callToAction}</Text>
            </View>
          </NativeAdView.Asset>
        )}
      </View>
    </NativeAdView>
  );
}