النماذج الأصلية في Dart
تنظيم صفحاتك في مجموعات
يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.
اختيار النظام الأساسي:
Android
iOS
Flutter
نماذج الإعلانات المدمجة مع المحتوى هي طرق عرض كاملة التعليمات البرمجية للإعلانات المدمجة مع المحتوى، وهي مصمَّمة لتنفيذ الإعلانات بسرعة وتعديلها بسهولة. باستخدام النماذج المدمجة مع المحتوى، يوفّر لك المكوّن الإضافي تنسيقات Android وiOS مُعدّة مسبقًا، ويمكنك تخصيص نمط مواد العرض المدمجة مع المحتوى باستخدام واجهة برمجة تطبيقات Dart.
يوضّح هذا الدليل كيفية استخدام Dart API لتصميم طرق العرض الأساسية على المنصّة وعرض الإعلان.
المتطلبات الأساسية
- الإصدار 2.4.0 من Flutter أو إصدار أحدث
اختبار الإعلانات دائمًا باستخدام الإعلانات الاختبارية
عند إنشاء تطبيقاتك واختبارها، احرص على استخدام إعلانات اختبارية بدلاً من الإعلانات المباشرة في مرحلة الإنتاج. أسهل طريقة لتحميل الإعلانات الاختبارية هي استخدام رقم تعريف وحدة الإعلانات الاختبارية المخصّص للإعلانات المدمجة مع المحتوى:
/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()
.
إنّ محتوى هذه الصفحة مرخّص بموجب ترخيص Creative Commons Attribution 4.0 ما لم يُنصّ على خلاف ذلك، ونماذج الرموز مرخّصة بموجب ترخيص Apache 2.0. للاطّلاع على التفاصيل، يُرجى مراجعة سياسات موقع Google Developers. إنّ Java هي علامة تجارية مسجَّلة لشركة Oracle و/أو شركائها التابعين.
تاريخ التعديل الأخير: 2025-09-06 (حسب التوقيت العالمي المتفَّق عليه)
[[["يسهُل فهم المحتوى.","easyToUnderstand","thumb-up"],["ساعَدني المحتوى في حلّ مشكلتي.","solvedMyProblem","thumb-up"],["غير ذلك","otherUp","thumb-up"]],[["لا يحتوي على المعلومات التي أحتاج إليها.","missingTheInformationINeed","thumb-down"],["الخطوات معقدة للغاية / كثيرة جدًا.","tooComplicatedTooManySteps","thumb-down"],["المحتوى قديم.","outOfDate","thumb-down"],["ثمة مشكلة في الترجمة.","translationIssue","thumb-down"],["مشكلة في العيّنات / التعليمات البرمجية","samplesCodeIssue","thumb-down"],["غير ذلك","otherDown","thumb-down"]],["تاريخ التعديل الأخير: 2025-09-06 (حسب التوقيت العالمي المتفَّق عليه)"],[[["\u003cp\u003eNative Templates offer pre-built layouts for Android and iOS, customizable through a Dart API, streamlining native ad implementation.\u003c/p\u003e\n"],["\u003cp\u003eFlutter provides two native ad template sizes, \u003ccode\u003esmall\u003c/code\u003e and \u003ccode\u003emedium\u003c/code\u003e, suitable for various ad placements, such as in-feed or landing pages.\u003c/p\u003e\n"],["\u003cp\u003eNative ad styling can be achieved using the \u003ccode\u003eNativeTemplateStyle\u003c/code\u003e and \u003ccode\u003eNativeTemplateTextStyle\u003c/code\u003e classes in Dart, offering granular control over visual elements.\u003c/p\u003e\n"],["\u003cp\u003eTo display the native ad, instantiate an \u003ccode\u003eAdWidget\u003c/code\u003e with the loaded \u003ccode\u003eNativeAd\u003c/code\u003e and place it within a \u003ccode\u003eConstrainedBox\u003c/code\u003e to define its dimensions.\u003c/p\u003e\n"],["\u003cp\u003eEnsure to dispose of the \u003ccode\u003eNativeAd\u003c/code\u003e using the \u003ccode\u003edispose()\u003c/code\u003e method when it's no longer needed, such as after removing the associated \u003ccode\u003eAdWidget\u003c/code\u003e from the widget tree.\u003c/p\u003e\n"]]],["Native templates provide prebuilt Android and iOS layouts for native ads, customizable via a Dart API. To use, load an ad with `NativeAd`, specifying an ad unit ID and listener for events. Customize the ad's appearance through `NativeTemplateStyle`, choosing from `small` or `medium` template sizes. Display the ad using an `AdWidget` within a `ConstrainedBox`. Ensure ads are tested with provided test ad unit IDs and disposed of properly after use to free up resources.\n"],null,["Select platform: [Android](/ad-manager/mobile-ads-sdk/android/native/templates \"View this page for the Android platform docs.\") [iOS](/ad-manager/mobile-ads-sdk/ios/native/templates \"View this page for the iOS platform docs.\") [Flutter](/ad-manager/mobile-ads-sdk/flutter/native/templates \"View this page for the Flutter platform docs.\")\n\n\u003cbr /\u003e\n\nNative templates are code-complete views for your native ads, designed for fast\nimplementation and easy modification. With native templates, the plugin provides\nprebuilt Android and iOS layouts for you, and you can customize the style of the\nnative assets using a Dart API.\n\nThis guide demonstrates how to use the Dart API to stylize the underlying\nplatform views and to render the ad.\n\nPrerequisites\n\n- Flutter 2.4.0 or higher.\n\n\u003c!-- --\u003e\n\n- Complete the [Get started guide](/ad-manager/mobile-ads-sdk/flutter/quick-start).\n- Familiarize yourself with the [native ads options](/ad-manager/mobile-ads-sdk/flutter/native).\n\nAlways test with test ads\n\nWhen building and testing your apps, make sure you use test ads rather than\nlive, production ads. The easiest way to load test ads is to use our dedicated\ntest ad unit ID for native ads:\n\n- `/21775744923/example/native`\n\nThe test ad units are configured to return test ads for every request, so\nyou can use them in your own apps while coding, testing, and\ndebugging---just make sure you replace them with your own ad unit IDs before\npublishing your app.\n\nLoad ad\n\nThe following example loads a native ad using the `medium` sized native\ntemplate: \n\n class NativeExampleState extends State\u003cNativeExample\u003e {\n NativeAd? nativeAd;\n bool _nativeAdIsLoaded = false;\n\n // TODO: replace this test ad unit with your own ad unit.\n final _adUnitId = '/21775744923/example/native';\n\n /// Loads a native ad.\n void loadAd() {\n _nativeAd = NativeAd(\n adUnitId: _adUnitId,\n listener: NativeAdListener(\n onAdLoaded: (ad) {\n debugPrint('$NativeAd loaded.');\n setState(() {\n _nativeAdIsLoaded = true;\n });\n },\n onAdFailedToLoad: (ad, error) {\n // Dispose the ad here to free resources.\n debugPrint('$NativeAd failed to load: $error');\n ad.dispose();\n },\n ),\n request: const AdManagerAdRequest(),\n // Styling\n nativeTemplateStyle: NativeTemplateStyle(\n // Required: Choose a template.\n templateType: TemplateType.medium,\n // Optional: Customize the ad's style.\n mainBackgroundColor: Colors.purple,\n cornerRadius: 10.0,\n callToActionTextStyle: NativeTemplateTextStyle(\n textColor: Colors.cyan,\n backgroundColor: Colors.red,\n style: NativeTemplateFontStyle.monospace,\n size: 16.0),\n primaryTextStyle: NativeTemplateTextStyle(\n textColor: Colors.red,\n backgroundColor: Colors.cyan,\n style: NativeTemplateFontStyle.italic,\n size: 16.0),\n secondaryTextStyle: NativeTemplateTextStyle(\n textColor: Colors.green,\n backgroundColor: Colors.black,\n style: NativeTemplateFontStyle.bold,\n size: 16.0),\n tertiaryTextStyle: NativeTemplateTextStyle(\n textColor: Colors.brown,\n backgroundColor: Colors.amber,\n style: NativeTemplateFontStyle.normal,\n size: 16.0)))\n ..load();\n }\n }\n\nSee\n[`NativeTemplateStyle`](//pub.dev/documentation/google_mobile_ads/latest/google_mobile_ads/NativeTemplateStyle-class.html)\nand\n[`NativeTemplateTextStyle`](//pub.dev/documentation/google_mobile_ads/latest/google_mobile_ads/NativeTemplateTextStyle-class.html)\nfor available styling options.\n\nCustomize ad\n\nWhen customizing a native ad using native templates, your ad's UI configuration\nwill live in the `NativeTemplateStyle` class, enabling you to style an entire\nnative ad in Dart code.\n\nTemplate sizes\n\nFlutter native ad templates come in two types: `TemplateType.small` and\n`TemplateType.medium`. The small template is ideal for a `TableView` or\n`GridView`, for in-feed ads or anywhere you need a thin rectangular ad view. The\nmedium template is meant to be a half to three-quarters page view, which is\nideal for landing or splash pages.\n\n| Small |\n|-------------|---------|\n| **Android** | **iOS** |\n| **Android** | **iOS** |\n\nNative ad events\n\nTo be notified of events related to the native ad interactions, use the\n[`listener`](//pub.dev/documentation/google_mobile_ads/latest/google_mobile_ads/NativeAd/listener.html)\nproperty of the ad. Then, implement\n[`NativeAdListener`](//pub.dev/documentation/google_mobile_ads/latest/google_mobile_ads/NativeAdListener-class.html)\nto receive ad event callbacks. \n\n class NativeExampleState extends State\u003cNativeExample\u003e {\n NativeAd? _nativeAd;\n bool _nativeAdIsLoaded = false;\n\n // TODO: replace this test ad unit with your own ad unit.\n final _adUnitId = '/21775744923/example/native';\n\n /// Loads a native ad.\n void loadAd() {\n _nativeAd = NativeAd(\n adUnitId: _adUnitId,\n listener: NativeAdListener(\n onAdLoaded: (ad) {\n print('$NativeAd loaded.');\n setState(() {\n _nativeAdIsLoaded = true;\n });\n },\n onAdFailedToLoad: (ad, error) {\n // Dispose the ad here to free resources.\n print('$NativeAd failedToLoad: $error');\n ad.dispose();\n },\n // Called when a click is recorded for a NativeAd.\n onAdClicked: (ad) {},\n // Called when an impression occurs on the ad.\n onAdImpression: (ad) {},\n // Called when an ad removes an overlay that covers the screen.\n onAdClosed: (ad) {},\n // Called when an ad opens an overlay that covers the screen.\n onAdOpened: (ad) {},\n // For iOS only. Called before dismissing a full screen view\n onAdWillDismissScreen: (ad) {},\n // Called when an ad receives revenue value.\n onPaidEvent: (ad, valueMicros, precision, currencyCode) {},\n ),\n request: const AdManagerAdRequest(),\n // Styling\n nativeTemplateStyle: NativeTemplateStyle(\n // Required: Choose a template.\n templateType: TemplateType.medium,\n // Optional: Customize the ad's style.\n mainBackgroundColor: Colors.purple,\n cornerRadius: 10.0,\n callToActionTextStyle: NativeTemplateTextStyle(\n textColor: Colors.cyan,\n backgroundColor: Colors.red,\n style: NativeTemplateFontStyle.monospace,\n size: 16.0),\n primaryTextStyle: NativeTemplateTextStyle(\n textColor: Colors.red,\n backgroundColor: Colors.cyan,\n style: NativeTemplateFontStyle.italic,\n size: 16.0),\n secondaryTextStyle: NativeTemplateTextStyle(\n textColor: Colors.green,\n backgroundColor: Colors.black,\n style: NativeTemplateFontStyle.bold,\n size: 16.0),\n tertiaryTextStyle: NativeTemplateTextStyle(\n textColor: Colors.brown,\n backgroundColor: Colors.amber,\n style: NativeTemplateFontStyle.normal,\n size: 16.0)))\n ..load();\n }\n }\n\nDisplay ad\n\nTo display a `NativeAd` as a widget, you must instantiate an\n[`AdWidget`](//pub.dev/documentation/google_mobile_ads/latest/google_mobile_ads/AdWidget-class.html)\nwith a supported ad after calling `load()`. You can create the widget before\ncalling `load()`, but `load()` must be called before adding it to the widget\ntree.\n\n`AdWidget` inherits from Flutter's `Widget` class and can be used like any other\nwidget. On iOS, make sure you place the widget in a container with a specified\nwidth and height. Otherwise, your ad may not be displayed. \n\n // Small template\n final adContainer = ConstrainedBox(\n constraints: const BoxConstraints(\n minWidth: 320, // minimum recommended width\n minHeight: 90, // minimum recommended height\n maxWidth: 400,\n maxHeight: 200,\n ),\n child: AdWidget(ad: _nativeAd!),\n );\n\n // Medium template\n final adContainer = ConstrainedBox(\n constraints: const BoxConstraints(\n minWidth: 320, // minimum recommended width\n minHeight: 320, // minimum recommended height\n maxWidth: 400,\n maxHeight: 400,\n ),\n child: AdWidget(ad: _nativeAd!),\n );\n\nDispose ad\n\nA\n[`NativeAd`](//pub.dev/documentation/google_mobile_ads/latest/google_mobile_ads/NativeAd-class.html)\nmust be disposed of when access to it is no longer needed. The best practice for\nwhen to call `dispose()` is after the `AdWidget` associated with the native ad\nis removed from the widget tree and in the `AdListener.onAdFailedToLoad()`\ncallback."]]