يوضِّح لك هذا الدليل كيفية استخدام "SDK لإعلانات Google على الأجهزة الجوّالة" من أجل تحميل إعلانات من Unity Ads وعرضها باستخدام التوسّط، بما في ذلك عمليات دمج العرض الإعلاني بدون انقطاع. كما تتناول كيفية إضافة Unity Ads إلى إعدادات التوسّط لإحدى الوحدات الإعلانية، وكيفية دمج محوّل وحزمة Unity Ads في Flutter أحد التطبيقات.
عمليات الدمج وأشكال الإعلانات المتوافقة
يتميّز AdMob محوّل التوسّط لبرنامج Unity Ads بالإمكانات التالية:
| الدمج | |
|---|---|
| عروض الأسعار | |
| شلال | |
| التنسيقات | |
| بانر | |
| إعلان بيني | |
| تم منح المكافأة | |
المتطلّبات
- أحدث حزمة SDK لإعلانات Google على الأجهزة الجوّالة
- Flutter 3.7.0 أو إصدار أحدث
- للنشر على Android:
- المستوى 21 من واجهة برمجة تطبيقات Android أو أعلى
- للنشر على iOS:
- هدف نشر iOS هو 12.0 أو إصدار أحدث
- مشروع Flutter يعمل باستخدام حزمة SDK لإعلانات Google على الأجهزة الجوّالة. يمكنك الاطّلاع على البدء للحصول على مزيد من التفاصيل.
- إكمال عملية التوسّط دليل البدء
الخطوة 1: ضبط الإعدادات في واجهة مستخدم Unity Ads
اشترِك أو سجِّل الدخول في Unity Ads.
إنشاء مشروع
في لوحة بيانات Unity Ads، انتقِل إلى المشاريع وانقر على إنشاء مشروع.
املأ النموذج وانقر على إنشاء مشروع لإضافة مشروعك.
انتقِل إلى تحقيق الربح > البدء، ثمّ انقر على البدء.
في النافذة المشروطة إعداد المشروع، اختر أخطط لاستخدام التوسّط وGoogle Admob لشريك التوسّط، ثم انقر على التالي.
اختَر إعدادات الإعلانات، ثمّ انقر على التالي.
املأ النموذج، ثم انقر على إضافة مشروع.
دوِّن رقم تعريف اللعبة.
إنشاء وحدة إعلانية
انتقِل إلى تحقيق الربح > الوحدات الإعلانية، ثمّ انقر على إضافة وحدة إعلانية.
أدخِل اسم الوحدة الإعلانية، ثم اختَر النظام الأساسي وشكل الإعلان.
Android
iOS
أخيرًا، انقر على إنشاء لحفظ وحدتك الإعلانية.
إضافة موضع إعلان
بعد إنشاء المشروع، انتقِل إلى تحقيق الربح > مواضع الإعلانات. لإنشاء موضع إعلان جديد، انقر على إضافة موضع إعلان لوحدتك الإعلانية.
املأ التفاصيل اللازمة، ثم انقر على إضافة موضع إعلان.
دوِّن رقم تعريف موضع الإعلان.
Android
iOS
استرداد بيانات الاعتماد
بالإضافة إلى معرّف اللعبة ومعرّف موضع الإعلان، ستحتاج أيضًا إلى مفتاح واجهة برمجة التطبيقات لإعلانات Unity ورقم التعريف الأساسي للمؤسسة لإعداد AdMob معرّف الوحدة الإعلانية.
انتقِل إلى تحقيق الربح > الإعداد > إدارة واجهة برمجة التطبيقات ودوِّن ملاحظاتك بشأن مفتاح الوصول إلى واجهة برمجة التطبيقات لإحصاءات تحقيق الربح.
بعد ذلك، انتقِل إلى تحقيق الربح > إعدادات المؤسسة ودوِّن المعرّف الأساسي للمؤسسة.
تفعيل وضع الاختبار
يمكن تفعيل وضع الاختبار من لوحة بيانات Unity Ads. ضمن إعدادات مشروعك، اختر علامة التبويب الاختبار.
يمكنك فرض وضع الاختبار لتطبيقك من خلال النقر على زر التعديل في كل نظام أساسي ووضع علامة في المربّع إلغاء وضع اختبار العميل واختيار فرض تفعيل وضع الاختبار (أي استخدام إعلانات تجريبية) لجميع الأجهزة.
Android
iOS
ويمكنك بدلاً من ذلك تفعيل "وضع الاختبار" لأجهزة محدّدة من خلال النقر على زر إضافة جهاز اختباري.
املأ النموذج وانقر على حفظ.
الخطوة 2: إعداد طلب Unity Ads في AdMob واجهة المستخدم
ضبط إعدادات التوسّط لوحدتك الإعلانية
Android
للحصول على التعليمات، اطّلِع على الخطوة 2 في دليل Android.
iOS
للحصول على التعليمات، يُرجى الاطّلاع على الخطوة 2 في دليل iOS.
إضافة Unity Ads إلى قائمة شركاء الإعلانات الذين يخضعون للّائحة العامة لحماية البيانات (GDPR) ولوائح الولايات الأمريكية
اتّبِع الخطوات الواردة في إعدادات اللائحة العامة لحماية البيانات و إعدادات اللوائح السارية في الولايات الأمريكية لإضافة Unity Ads إلى اللائحة العامة لحماية البيانات (GDPR) وقائمة شركاء الإعلانات للوائح الولايات الأمريكية في AdMob واجهة المستخدم.
الخطوة 3: استيراد محوّل وحزمة تطوير البرامج (SDK) الخاصة بخدمة Unity Ads
الدمج من خلال pub.dev
أضِف التبعية التالية مع أحدث إصدارات
Unity Ads حزمة تطوير البرامج (SDK) والمحوِّل في ملف
pubspec.yaml الخاص بالحزمة:
dependencies:
gma_mediation_unity: ^1.0.0
الدمج اليدوي
نزِّل أحدث إصدار من المكوّن الإضافي لتوسّط "إعلانات Google على الأجهزة الجوّالة" من أجل
Unity Ads،
واستخرج الملف الذي تم تنزيله وأضِف مجلد المكوّن الإضافي المُستخرَج (ومحتواه) إلى مشروع Flutter. بعد ذلك، أشِر إلى المكوّن الإضافي في ملف
pubspec.yaml عن طريق إضافة التبعية التالية:
dependencies:
gma_mediation_unity:
path: path/to/local/package
الخطوة 4: تنفيذ إعدادات الخصوصية في حزمة تطوير البرامج (SDK) الخاصة بـ Unity Ads
موافقة الاتحاد الأوروبي واللائحة العامة لحماية البيانات
بموجب سياسة موافقة المستخدم في الاتحاد الأوروبي التي تتّبعها Google، عليك التأكّد من الإفصاح عن معلومات محدّدة للمستخدمين في المنطقة الاقتصادية الأوروبية والحصول على موافقات منهم بشأن استخدام معرّفات الأجهزة والبيانات الشخصية. تعكس هذه السياسة متطلبات "التوجيه الأوروبي بشأن الخصوصية الإلكترونية" و"اللائحة العامة لحماية البيانات" (GDPR) في الاتّحاد الأوروبي. عند طلب الحصول على موافقة، يجب عليك تحديد كل شبكة إعلانات في سلسلة التوسط قد تجمع البيانات الشخصية أو تتلقاها أو تستخدمها، وتقدم معلومات عن استخدام كل شبكة. ولا يمكن لشركة Google حاليًا تمرير خيار موافقة المستخدم إلى هذه الشبكات تلقائيًا.
يحتوي المكوّن الإضافي لتوسّط "إعلانات Google على الأجهزة الجوّالة" مع Unity Ads
على
GmaMediationUnity.setGDPRConsent()
الطريقة. يعرض الرمز النموذجي التالي كيفية تمرير معلومات الموافقة إلى حزمة تطوير البرامج (SDK) الخاصة بخدمة Unity Ads. وإذا اخترت استدعاء هذه الطريقة، ننصحك بفعل ذلك
قبل طلب الإعلانات من خلال "SDK لإعلانات Google على الأجهزة الجوّالة".
import 'package:gma_mediation_unity/gma_mediation_unity.dart';
// ...
GmaMediationUnity.setGDPRConsent(true);
يُرجى الاطّلاع على أدلة الموافقة على الخصوصية وواجهات برمجة التطبيقات للبيانات في Unity Ads، ودليلَي الامتثال للائحة العامة لحماية البيانات (GDPR) للحصول على مزيد من التفاصيل والقيم التي يمكن تقديمها في كل طريقة.
قوانين الخصوصية في الولايات الأمريكية
قوانين الخصوصية في الولايات الأمريكية تتطلب من المستخدمين منح المستخدمين الحق في إيقاف "بيع" "معلوماتهم الشخصية" (وفقًا لما يحدّده القانون) لهذه المصطلحات)، وذلك من خلال رابط بارز يتضمّن العبارة "عدم بيع معلوماتي الشخصية" على الصفحة الرئيسية للطرف "البيع". إنّ دليل الامتثال لقوانين الخصوصية في الولايات الأمريكية يوفّر إمكانية تفعيل المعالجة المحدودة للبيانات لعرض الإعلانات على Google، ولكن يتعذّر على Google تطبيق هذا الإعداد على كل شبكة إعلانات في سلسلة التوسّط. وبالتالي، عليك تحديد كل شبكة إعلانات في سلسلة التوسّط قد تشارك في بيع المعلومات الشخصية واتّباع الإرشادات من كل شبكة من هذه الشبكات لضمان الامتثال لها.
يحتوي المكوّن الإضافي لتوسّط "إعلانات Google على الأجهزة الجوّالة" مع Unity Ads
على
GmaMediationUnity.setCCPAConsent()
الطريقة. يعرض الرمز النموذجي التالي كيفية تمرير معلومات الموافقة إلى حزمة تطوير البرامج (SDK) الخاصة بخدمة Unity Ads. وإذا اخترت استدعاء هذه الطريقة، ننصحك بفعل ذلك
قبل طلب الإعلانات من خلال "SDK لإعلانات Google على الأجهزة الجوّالة".
import 'package:gma_mediation_unity/gma_mediation_unity.dart';
// ...
GmaMediationUnity.setCCPAConsent(true);
الخطوة 5: إضافة الرمز المطلوب
Android
ما مِن رمز إضافي مطلوب لعمليات دمج Unity Ads مع Android.
iOS
دمج SKAdNetwork
اتّبِع مستندات Unity Ads
لإضافة معرّفات SKAdNetwork إلى ملف Info.plist الخاص بمشروعك.
الخطوة 6: اختبار عملية التنفيذ
تفعيل الإعلانات التجريبية
احرص على تسجيل جهاز الاختبار من أجل AdMob وتفعيل وضع الاختبار في واجهة المستخدم Unity Ads .
التحقّق من الإعلانات الاختبارية
للتأكّد من أنّك تتلقّى إعلانات اختبارية من Unity Ads، فعِّل اختبار مصدر إعلان فردي في "أداة فحص الإعلانات" باستخدام Unity Ads (Waterfall) مصادر الإعلانات.
رموز الخطأ
إذا تعذّر على المحوّل تلقّي إعلان من Unity Ads، يمكن للناشرين التحقق من الخطأ الأساسي في استجابة الإعلان باستخدام ResponseInfo ضمن الفئات التالية:
Android
com.google.ads.mediation.unity.UnityAdapter
com.google.ads.mediation.unity.UnityMediationAdapter
iOS
GADMAdapterUnity
GADMediationAdapterUnity
في ما يلي الرموز والرسائل المصاحبة التي يعرضها محوّل UnityAds عند تعذُّر تحميل الإعلان:
Android
| رمز الخطأ | السبب |
|---|---|
| 0-10 | حدث خطأ في حزمة تطوير البرامج (SDK) في UnityAds. اطّلِع على الرمز البرمجي لمزيد من التفاصيل. |
| 101 | مَعلمات خادم UnityAds التي تم ضبطها في واجهة مستخدم Admob غير متوفّرة/غير صالحة |
| 102 | عرضت UnityAds موضع إعلان بحالة NO_FILL. |
| 103 | عرضت UnityAds موضع إعلان بالحالة "متوقّفة". |
| 104 | حاولت UnityAds عرض إعلان بسياق فارغ. |
| 105 | إنّ السياق المستخدَم لإعداد الإعلانات و/أو تحميلها و/أو عرضها من Unity Ads ليس من أمثلة النشاط. |
| 106 | حاولت UnityAds عرض إعلان غير جاهز للعرض. |
| 107 | لا يمكن استخدام UnityAds على الجهاز. |
| 108 | بإمكان UnityAds تحميل إعلان واحد فقط لكل موضع في المرة الواحدة. |
| 109 | انتهت UnityAds بحالة "خطأ". |
| 200-204 | حدث خطأ معيّن في بانر UnityAds. اطّلِع على الرمز البرمجي لمزيد من التفاصيل. |
iOS
| 0-9 | حدث خطأ في حزمة تطوير البرامج (SDK) في UnityAds. راجِع مستندات Unity لمزيد من التفاصيل. |
| 101 | مَعلمات خادم UnityAds التي تم ضبطها في واجهة مستخدم Admob غير متوفّرة/غير صالحة |
| 102 | الجهاز غير متوافق مع UnityAds. |
| 103 | انتهت صلاحية عرض الوحدة الإعلانية UnityAds مع ظهور حالة الخطأ kUnityAdsFinishStateError. |
| 104 | يكون عنصر إعلان Unity معدومًا بعد استدعاء أداة الإعداد. |
| 105 | تعذّر عرض إعلانات Unity لأنّ الإعلان غير جاهز. |
| 106 | غيَّرت UnityAds موضع الإعلان معاودة الاتصال بحالة الموضع kUnityAdsPositionStateNoFill. |
| 107 | غيَّرت UnityAds موضع الإعلان معاودة الاتصال بحالة الموضع kUnityAdsPositionStateDisabled. |
| 108 | سبق أن تم تحميل إعلان لهذا الموضع. لا تتيح حزمة تطوير البرامج (SDK) في UnityAds تحميل إعلانات متعددة لموضع معيّن. |
سجلّ تغييرات مهايئ محوّل Flutter Mediation في Unity Ads
الإصدار 1.0.0
- الإصدار الأولي.
- تم التحقّق من التوافق مع الإصدار 4.10.0.0 من محوّل Unity Android
- تم التحقّق من التوافق مع الإصدار 4.10.0.0 من محوّل Unity iOS