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

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

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

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

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

• أكمِل دليل البدء.
• اطّلِع على خيارات الإعلانات المدمجة مع المحتوى.

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

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

• /21775744923/example/native

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

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

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

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

 // TODO: replace this test ad unit with your own ad unit.
 final _adUnitId = '/21775744923/example/native';

  /// 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 AdManagerAdRequest(),
        // 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 _adUnitId = '/21775744923/example/native';

  /// 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 AdManagerAdRequest(),
        // 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() الاستدعاء.