"النماذج المدمجة مع المحتوى" هي طرق عرض مكتملة الرموز لإعلاناتك المدمجة مع المحتوى، وهي مصمّمة للتنفيذ السريع والتعديل السهل. باستخدام النماذج المدمجة مع المحتوى، يوفّر المكوّن الإضافي تنسيقات Android وiOS مُعدّة مسبقًا، ويمكنك تخصيص نمط مواد العرض المدمجة مع المحتوى باستخدام واجهة برمجة تطبيقات Dart.
يوضّح هذا الدليل كيفية استخدام Dart API لتصميم طرق عرض النظام الأساسي الأساسية وعرض الإعلان.
المتطلبات الأساسية
قبل المتابعة، عليك تنفيذ ما يلي:
- الإصدار 2.4.0 من Flutter أو إصدار أحدث
اختبِر دائمًا باستخدام الإعلانات الاختبارية
عند إنشاء تطبيقاتك واختبارها، تأكَّد من استخدام الإعلانات الاختبارية بدلاً من الإعلانات المباشرة والإنتاجية. أسهل طريقة لتحميل الإعلانات الاختبارية هي استخدام معرّف الوحدة الإعلانية الاختبارية المخصّص للإعلانات المدمجة مع المحتوى:
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().
الخطوات التالية
- يمكنك الاطّلاع على مزيد من المعلومات عن "الإعلانات المدمجة مع المحتوى" في دليل "الإعلانات المدمجة مع المحتوى".
- يُرجى الاطّلاع على سياسات وإرشادات الإعلانات المدمجة مع المحتوى.
- يمكنك الاطّلاع على بعض قصص نجاح العملاء: دراسة الحالة 1، دراسة الحالة 2.
مثال كامل على GitHub
للاطّلاع على المثال الكامل، يُرجى مراجعة العرض التوضيحي لواجهة برمجة التطبيقات.



