مدمجة مع المحتوى

تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.

الإعلانات المدمجة مع المحتوى هي مواد عرض الإعلانات يتم تقديمها للمستخدمين من خلال مكوّنات واجهة المستخدم التي يتم استخدامها في النظام الأساسي. ويتم عرضها باستخدام أنواع المشاهدات نفسها التي تستخدمها لإنشاء تنسيقاتك، ويمكن تنسيقها لتتوافق مع التصميم المرئي لتجربة المستخدم في المكان الذي يعيش فيه. وهذا يعني أنه عند تحميل إعلان مدمج مع المحتوى، يتلقى تطبيقك كائن إعلان مدمج مع المحتوى يحتوي على مواد العرض، ويكون التطبيق (بدلاً من حزمة تطوير البرامج (SDK) لإعلانات Google على الأجهزة الجوّالة) مسؤولاً عن عرضه.

بصورة عامة، هناك جزءان لتنفيذ الإعلانات المدمجة مع المحتوى بنجاح: تحميل إعلان عبر حزمة تطوير البرامج (SDK) وعرض محتوى الإعلان في تطبيقك. يتناول هذا الدليل استخدام حزمة تطوير البرامج (SDK) لتحميل الإعلانات المدمجة مع المحتوى.

إعداد النظام الأساسي

يتم عرض الإعلانات المدمجة مع المحتوى للمستخدمين من خلال مكوّنات واجهة المستخدم التي يتم إعدادها على المنصة (على سبيل المثال، View على نظام التشغيل Android أو UIView على نظام التشغيل iOS).

نظرًا لأن الإعلانات المدمجة مع المحتوى تتطلب مكونات واجهة مستخدم مدمجة في نظام أساسي، تتطلب هذه الميزة إعدادًا إضافيًا لنظامي التشغيل Android وiOS:

نظام التشغيل Android

يتطلب تنفيذ المكوّن الإضافي لإعلانات Google للأجهزة الجوّالة التي تعمل بنظام التشغيل Android فئة تستخدم NativeAdFactory. للإشارة إلى واجهة برمجة التطبيقات هذه من مشروع Android، أضِف الأسطر التالية إلى settings.gradle:

def flutterProjectRoot = rootProject.projectDir.parentFile.toPath()
def plugins = new Properties()
def pluginsFile = new File(flutterProjectRoot.toFile(), '.flutter-plugins')
if (pluginsFile.exists()) {
    pluginsFile.withInputStream { stream -> plugins.load(stream) }
}

plugins.each { name, path ->
    def pluginDirectory = flutterProjectRoot.resolve(path).resolve('android').toFile()
    include ":$name"
    project(":$name").projectDir = pluginDirectory
}

تحتوي NativeAdFactory على طريقة تقبل NativeAd وخيارات مخصّصة، وتعرض NativeAdView. تظهر السمة NativeAdView في تطبيقك.

يمكنك تنفيذ هذا الإجراء في MainActivity.java أو إنشاء صف منفصل في الدليل نفسه المُستخدَم في MainActivity.java:

package my.app.path;

import com.google.android.gms.ads.nativead.NativeAd;
import com.google.android.gms.ads.nativead.NativeAdView;
import io.flutter.plugins.googlemobileads.GoogleMobileAdsPlugin.NativeAdFactory;
import java.util.Map;

class NativeAdFactoryExample implements NativeAdFactory {
  @Override
  public NativeAdView createNativeAd(
      NativeAd nativeAd, Map<String, Object> customOptions) {
    // Create NativeAdView
  }
}

يجب تسجيل كل NativeAdFactory باستخدام معرّف String فريد. فيMainActivity.configureFlutterEngine(FlutterEngine) يمكن تنفيذ NativeAdFactory وتسجيله لكل تنسيق إعلان مدمج مع المحتوى فريد يستخدمه تطبيقك، أو يمكن لمنصّة واحدة معالجة كل التنسيقات.

يجب أيضًا إلغاء تسجيل NativeAdFactory في cleanUpFlutterEngine(engine) عند إنشاؤه باستخدام إضافة إلى تطبيق.

من المفترض أن يبدو MainActivity.java مشابهًا لما يلي:

package my.app.path;

import io.flutter.embedding.android.FlutterActivity;
import io.flutter.embedding.engine.FlutterEngine;
import io.flutter.plugins.googlemobileads.GoogleMobileAdsPlugin;

public class MainActivity extends FlutterActivity {
  @Override
  public void configureFlutterEngine(FlutterEngine flutterEngine) {
    flutterEngine.getPlugins().add(new GoogleMobileAdsPlugin());
   super.configureFlutterEngine(flutterEngine);

    GoogleMobileAdsPlugin.registerNativeAdFactory(flutterEngine, "adFactoryExample", NativeAdFactoryExample());
  }

  @Override
  public void cleanUpFlutterEngine(FlutterEngine flutterEngine) {
    GoogleMobileAdsPlugin.unregisterNativeAdFactory(flutterEngine, "adFactoryExample");
  }
}

عند إنشاء NativeAd في الأسهم، يجب أن تتطابق السمة factoryId مع الفلتر المستخدَم لإضافة المصنع إلى GoogleMobileAdsPlugin. في مقتطف الرمز أعلاه، adFactoryExample هو اسم factoryId. إليك مثال على NativeAdFactory:

package io.flutter.plugins.googlemobileadsexample;

import android.graphics.Color;
import android.view.LayoutInflater;
import android.widget.TextView;
import com.google.android.gms.ads.nativead.NativeAd;
import com.google.android.gms.ads.nativead.NativeAdView;
import io.flutter.plugins.googlemobileads.GoogleMobileAdsPlugin.NativeAdFactory;
import java.util.Map;

/**
 * my_native_ad.xml can be found at
 * //github.com/googleads/googleads-mobile-flutter/tree/master/packages/google_mobile_ads/example/android/app/src/main/res/layout
 */
class NativeAdFactoryExample implements NativeAdFactory {
  private final LayoutInflater layoutInflater;

  NativeAdFactoryExample(LayoutInflater layoutInflater) {
    this.layoutInflater = layoutInflater;
  }

  @Override
  public NativeAdView createNativeAd(
      NativeAd nativeAd, Map<String, Object> customOptions) {
    final NativeAdView adView =
        (NativeAdView) layoutInflater.inflate(R.layout.my_native_ad, null);
    final TextView headlineView = adView.findViewById(R.id.ad_headline);
    final TextView bodyView = adView.findViewById(R.id.ad_body);

    headlineView.setText(nativeAd.getHeadline());
    bodyView.setText(nativeAd.getBody());

    adView.setBackgroundColor(Color.YELLOW);

    adView.setNativeAd(nativeAd);
    adView.setBodyView(bodyView);
    adView.setHeadlineView(headlineView);
    return adView;
  }
}

iOS

يتطلب تنفيذ المكوّن الإضافي لإعلانات Google على الأجهزة الجوّالة في نظام التشغيل iOS فئة تُنفِّذ FLTNativeAdFactory. تحتوي الخاصية FLTNativeAdFactory على طريقة تأخذ GADNativeAd وخيارات مخصّصة وتعرض القيمة GADNativeAdView. تعرض GADNativeAdView البيانات في تطبيقك.

يمكن تنفيذ البروتوكول FLTNativeAdFactory من خلال AppDelegate أو يمكن إنشاء فئة منفصلة:

/* AppDelegate.m */
#import "FLTGoogleMobileAdsPlugin.h"
@interface NativeAdFactoryExample : NSObject<FLTNativeAdFactory>
@end

@implementation NativeAdFactoryExample
- (GADNativeAdView *)createNativeAd:(GADNativeAd *)nativeAd
                             customOptions:(NSDictionary *)customOptions {
  // Create GADNativeAdView
}
@end

يجب تسجيل كلّ FLTNativeAdFactory باستخدام factoryId (معرّف String فريد) في registerNativeAdFactory:factoryId:nativeAdFactory:.

يمكن تنفيذ FLTNativeAdFactory وتسجيله لكل تنسيق إعلان فريد مدمج مع المحتوى يستخدمه تطبيقك، أو يمكن لتصميم واحد التعامل مع جميع التنسيقات. ويتم ذلك من خلال استيراد FLTGoogleMobileAdsPlugin.h والطلب registerNativeAdFactory:factoryId:nativeAdFactory: باستخدام FlutterPluginRegistry (معرّف فريد للمصنع) و المصنع نفسه. ويجب أيضًا إضافة المصنع بعد استدعاءGeneratedPluginRegistrant registerWithRegistry:self];.

إذا تم إنجاز ذلك في AppDelegate.m، من المفترض أن يبدو مشابهًا لما يلي:

#import "FLTGoogleMobileAdsPlugin.h"

@implementation AppDelegate
- (BOOL)application:(UIApplication *)application
    didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
  [GeneratedPluginRegistrant registerWithRegistry:self];

  NativeAdFactoryExample *nativeAdFactory = [[NativeAdFactoryExample alloc] init];
  [FLTGoogleMobileAdsPlugin registerNativeAdFactory:self
                                          factoryId:@"adFactoryExample"
                                    nativeAdFactory:nativeAdFactory];

  return [super application:application didFinishLaunchingWithOptions:launchOptions];
}
@end

عند إنشاء NativeAd في الأسهم، يجب أن تتطابق السمة factoryID مع الفلتر المستخدَم لإضافة المصنع إلى FLTGoogleMobileAdsPlugin. في مقتطف الرمز أعلاه، adFactoryExample هو اسم factoryID. في ما يلي مثال على FLTNativeAdFactory:

/**
 * The example NativeAdView.xib can be found at
 * //github.com/googleads/googleads-mobile-flutter/blob/master/packages/google_mobile_ads/example/ios/Runner/NativeAdView.xib
 */
@interface NativeAdFactoryExample : NSObject <FLTNativeAdFactory>
@end

@implementation NativeAdFactoryExample
- (GADNativeAdView *)createNativeAd:(GADNativeAd *)nativeAd
                             customOptions:(NSDictionary *)customOptions {
  // Create and place ad in view hierarchy.
  GADNativeAdView *adView =
      [[NSBundle mainBundle] loadNibNamed:@"NativeAdView" owner:nil options:nil].firstObject;

  // Associate the native ad view with the native ad object. This is
  // required to make the ad clickable.
  adView.nativeAd = nativeAd;

  // Populate the native ad view with the native ad assets.
  // The headline is guaranteed to be present in every native ad.
  ((UILabel *)adView.headlineView).text = nativeAd.headline;

  // These assets are not guaranteed to be present. Check that they are before
  // showing or hiding them.
  ((UILabel *)adView.bodyView).text = nativeAd.body;
  adView.bodyView.hidden = nativeAd.body ? NO : YES;

  [((UIButton *)adView.callToActionView) setTitle:nativeAd.callToAction
                                         forState:UIControlStateNormal];
  adView.callToActionView.hidden = nativeAd.callToAction ? NO : YES;

  ((UIImageView *)adView.iconView).image = nativeAd.icon.image;
  adView.iconView.hidden = nativeAd.icon ? NO : YES;

  ((UILabel *)adView.storeView).text = nativeAd.store;
  adView.storeView.hidden = nativeAd.store ? NO : YES;

  ((UILabel *)adView.priceView).text = nativeAd.price;
  adView.priceView.hidden = nativeAd.price ? NO : YES;

  ((UILabel *)adView.advertiserView).text = nativeAd.advertiser;
  adView.advertiserView.hidden = nativeAd.advertiser ? NO : YES;

  // In order for the SDK to process touch events properly, user interaction
  // should be disabled.
  adView.callToActionView.userInteractionEnabled = NO;

  return adView;
}
@end

الاختبار دائمًا باستخدام الإعلانات التجريبية

عند إنشاء تطبيقاتك واختبارها، احرص على استخدام إعلانات تجريبية بدلاً من إعلانات الإنتاج المباشر. ويمكن أن يؤدي عدم الالتزام بذلك إلى تعليق حسابك.

أسهل طريقة لتحميل الإعلانات الاختبارية هي استخدام رقم تعريف الوحدة الإعلانية الاختبارية المخصصة للإعلانات المدمجة مع المحتوى:

يتم إعداد الوحدات الإعلانية الاختبارية لعرض إعلانات اختبارية لكل طلب، ويمكنك استخدام هذه التطبيقات في تطبيقاتك أثناء الترميز والاختبار وتصحيح الأخطاء. ما عليك سوى التأكّد من استبدالها بأرقام تعريف وحداتك الإعلانية قبل نشر تطبيقك.

إنشاء إعلان فوري

يتطلب NativeAd adUnitId وfactoryId وAdRequest وNativeAdListener.يؤدي المثال التالي إلى إنشاء مثيل لإعلان مدمج مع المحتوى:

final NativeAd myNative = NativeAd(
  adUnitId: '<ad unit id>',
  factoryId: 'adFactoryExample',
  request: AdRequest(),
  listener: NativeAdListener(),
);

رقم تعريف المصنع

يجب أن تتطابق السمة factoryId مع المستودع المستخدَم لإضافة المصنع إلى GoogleMobileAdsPlugin على Android و/أو FLTGoogleMobileAdsPlugin على أجهزة iOS. ويمكن استخدام نظام التشغيل factoryId نفسه من خلال النظامَين الأساسيَين، أو يمكن أن يكون لكل منهما نظام خاص به.

أحداث الإعلانات المدمجة مع المحتوى

وباستخدام NativeAdListener، يمكنك الاستماع إلى أحداث مراحل النشاط، مثلاً عند تحميل إعلان. ينفِّذ المثال التالي كل طريقة ويسجِّل رسالة في وحدة التحكُّم:

final NativeAdListener listener = NativeAdListener(
 // Called when an ad is successfully received.
 onAdLoaded: (Ad ad) => print('Ad loaded.'),
 // Called when an ad request failed.
 onAdFailedToLoad: (Ad ad, LoadAdError error) {
   // Dispose the ad here to free resources.
   ad.dispose();
   print('Ad failed to load: $error');
 },
 // Called when an ad opens an overlay that covers the screen.
 onAdOpened: (Ad ad) => print('Ad opened.'),
 // Called when an ad removes an overlay that covers the screen.
 onAdClosed: (Ad ad) => print('Ad closed.'),
 // Called when an impression occurs on the ad.
 onAdImpression: (Ad ad) => print('Ad impression.'),
 // Called when a click is recorded for a NativeAd.
 onNativeAdClicked: (NativeAd ad) => print('Ad clicked.'),
);

تحميل إعلان

بعد إنشاء مثيل NativeAd، يجب طلب load() قبل أن يتم عرضه على الشاشة.

myNative.load();

إعلان صوري

لعرض NativeAd كأداة، عليك إنشاء مثيل AdWidget بإعلان متوافق بعد طلب load(). يمكنك إنشاء الأداة قبل طلب load()، ولكن يجب طلب load() قبل إضافتها إلى شجرة الأدوات.

final AdWidget adWidget = AdWidget(ad: myBanner);

يرث AdWidget البيانات من فئة Widget في Flutter&#29 ويمكن استخدامه مثل أي أداة أخرى. على نظام التشغيل iOS، تأكد من وضع الأداة في حاوية بعرض وارتفاع محددَين. وإلا قد لا يتم عرض إعلانك.

final Container adContainer = Container(
  alignment: Alignment.center,
  child: adWidget,
  width: 500,
  height: 500,
);

بعد طلب "إعلان" من load()، يجب أن يتصل بـ dispose() عندما لا يكون هناك حاجة إلى الوصول إليه. إنّ أفضل ممارسة للاتصال بـ dispose() هي بعد إزالة السمة AdWidget من شجرة الأداة أو في استدعاء AdListener.onAdFailedToLoad.

أكملت هذه الخطوة. أصبح تطبيقك جاهزًا الآن لعرض الإعلانات المدمجة مع المحتوى.

الخطوات اللاحقة