النماذج الأصلية في Dart

النماذج المدمجة مع المحتوى هي طرق عرض كاملة للرموز البرمجية لإعلاناتك المدمجة مع المحتوى، وهي مصمّمة للتنفيذ السريع والتعديل بسهولة. باستخدام النماذج الأصلية، يوفر المكوّن الإضافي لك تنسيقات Android وiOS المصممة مسبقًا، ويمكنك تخصيص نمط مواد العرض الأصلية باستخدام واجهة برمجة تطبيقات Dart.

يوضّح هذا الدليل كيفية استخدام Dart API لتصميم طرق عرض المنصّة الأساسية وعرض الإعلان.

المتطلبات الأساسية

  • Flutter 2.4.0 أو إصدار أحدث

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

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

Android

ca-app-pub-3940256099942544/2247696110

iOS

ca-app-pub-3940256099942544/3986624511

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

تحميل الإعلان

يحمّل المثال التالي إعلانًا مدمجًا مع المحتوى باستخدام نموذج مدمج مع المحتوى بحجم medium:

class NativeExampleState extends State<NativeExample> {
  NativeAd? nativeAd;
  bool _nativeAdIsLoaded = false;

 // TODO: replace this test ad unit with your own ad unit.
 final String _adUnitId = Platform.isAndroid
      ? 'ca-app-pub-3940256099942544/2247696110'
      : 'ca-app-pub-3940256099942544/3986624511';

  /// Loads a native ad.
  void loadAd() {
    _nativeAd = NativeAd(
        adUnitId: _adUnitId,
        listener: NativeAdListener(
          onAdLoaded: (ad) {
            debugPrint('$NativeAd loaded.');
            setState(() {
              _nativeAdIsLoaded = true;
            });
          },
          onAdFailedToLoad: (ad, error) {
            // Dispose the ad here to free resources.
            debugPrint('$NativeAd failed to load: $error');
            ad.dispose();
          },
        ),
        request: const AdRequest(),
        // Styling
        nativeTemplateStyle: NativeTemplateStyle(
            // Required: Choose a template.
            templateType: TemplateType.medium,
            // Optional: Customize the ad's style.
            mainBackgroundColor: Colors.purple,
            cornerRadius: 10.0,
            callToActionTextStyle: NativeTemplateTextStyle(
                textColor: Colors.cyan,
                backgroundColor: Colors.red,
                style: NativeTemplateFontStyle.monospace,
                size: 16.0),
            primaryTextStyle: NativeTemplateTextStyle(
                textColor: Colors.red,
                backgroundColor: Colors.cyan,
                style: NativeTemplateFontStyle.italic,
                size: 16.0),
            secondaryTextStyle: NativeTemplateTextStyle(
                textColor: Colors.green,
                backgroundColor: Colors.black,
                style: NativeTemplateFontStyle.bold,
                size: 16.0),
            tertiaryTextStyle: NativeTemplateTextStyle(
                textColor: Colors.brown,
                backgroundColor: Colors.amber,
                style: NativeTemplateFontStyle.normal,
                size: 16.0)))
      ..load();
  }
}

يمكنك الانتقال إلى NativeTemplateStyle وNativeTemplateTextStyle للاطّلاع على خيارات التصميم المتاحة.

تخصيص الإعلان

عند تخصيص إعلان مدمج مع المحتوى باستخدام نماذج مدمجة مع المحتوى، ستكون تهيئة واجهة مستخدم إعلانك مباشرة في الفئة NativeTemplateStyle، ما يتيح لك تصميم إعلان مدمج مع المحتوى بالكامل باستخدام رمز Dart.

أحجام النماذج

يتوفّر نوعان من نماذج الإعلانات المدمجة مع المحتوى من Flutter: TemplateType.small وTemplateType.medium. يُعد هذا النموذج الصغير مثاليًا لكلٍّ من TableView أو GridView، للإعلانات ضمن الخلاصة أو في أي مكان تحتاج فيه إلى عرض إعلان رفيع مستطيل. ويتمثل نموذج الوسيط في عرض الصفحة من نصف إلى ثلاثة أرباع، وهو مثالي للصفحات المقصودة أو صفحات البداية.

صغير

Android
iOS
الوسيط

Android
iOS

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

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

class NativeExampleState extends State<NativeExample> {
  NativeAd? _nativeAd;
  bool _nativeAdIsLoaded = false;

 // TODO: replace this test ad unit with your own ad unit.
 final String _adUnitId = Platform.isAndroid
      ? 'ca-app-pub-3940256099942544/2247696110'
      : 'ca-app-pub-3940256099942544/3986624511';

  /// Loads a native ad.
  void loadAd() {
    _nativeAd = NativeAd(
        adUnitId: _adUnitId,
        listener: NativeAdListener(
          onAdLoaded: (ad) {
            print('$NativeAd loaded.');
            setState(() {
              _nativeAdIsLoaded = true;
            });
          },
          onAdFailedToLoad: (ad, error) {
            // Dispose the ad here to free resources.
            print('$NativeAd failedToLoad: $error');
            ad.dispose();
          },
          // Called when a click is recorded for a NativeAd.
          onAdClicked: (ad) {},
          // Called when an impression occurs on the ad.
          onAdImpression: (ad) {},
          // Called when an ad removes an overlay that covers the screen.
          onAdClosed: (ad) {},
          // Called when an ad opens an overlay that covers the screen.
          onAdOpened: (ad) {},
          // For iOS only. Called before dismissing a full screen view
          onAdWillDismissScreen: (ad) {},
          // Called when an ad receives revenue value.
          onPaidEvent: (ad, valueMicros, precision, currencyCode) {},
        ),
        request: const AdRequest(),
        // Styling
        nativeTemplateStyle: NativeTemplateStyle(
            // Required: Choose a template.
            templateType: TemplateType.medium,
            // Optional: Customize the ad's style.
            mainBackgroundColor: Colors.purple,
            cornerRadius: 10.0,
            callToActionTextStyle: NativeTemplateTextStyle(
                textColor: Colors.cyan,
                backgroundColor: Colors.red,
                style: NativeTemplateFontStyle.monospace,
                size: 16.0),
            primaryTextStyle: NativeTemplateTextStyle(
                textColor: Colors.red,
                backgroundColor: Colors.cyan,
                style: NativeTemplateFontStyle.italic,
                size: 16.0),
            secondaryTextStyle: NativeTemplateTextStyle(
                textColor: Colors.green,
                backgroundColor: Colors.black,
                style: NativeTemplateFontStyle.bold,
                size: 16.0),
            tertiaryTextStyle: NativeTemplateTextStyle(
                textColor: Colors.brown,
                backgroundColor: Colors.amber,
                style: NativeTemplateFontStyle.normal,
                size: 16.0)))
      ..load();
  }
}

إعلان صوري

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

يكتسِب AdWidget من فئة Widget في Flutter ويمكن استخدامها مثل أي تطبيق مصغّر آخر. على نظام التشغيل iOS، تأكد من وضع الأداة في حاوية ذات عرض وارتفاع محددين. وإلا فقد لا يتم عرض إعلانك.

// Small template
final adContainer = ConstrainedBox(
  constraints: const BoxConstraints(
    minWidth: 320, // minimum recommended width
    minHeight: 90, // minimum recommended height
    maxWidth: 400,
    maxHeight: 200,
  ),
  child: AdWidget(ad: _nativeAd!),
);

// Medium template
final adContainer = ConstrainedBox(
  constraints: const BoxConstraints(
    minWidth: 320, // minimum recommended width
    minHeight: 320, // minimum recommended height
    maxWidth: 400,
    maxHeight: 400,
  ),
  child: AdWidget(ad: _nativeAd!),
);

التخلص من الإعلان

يجب التخلص من NativeAd عندما لا تكون هناك حاجة إليه. أفضل ممارسة لوقت طلب dispose() هي بعد إزالة AdWidget المرتبط بالإعلان المدمج مع المحتوى من شجرة الأدوات ومن معاودة الاتصال في AdListener.onAdFailedToLoad().

الخطوات التالية

مثال كامل على GitHub

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