تكامل AdMob

1إنشاء حساب AdMob#

سجّل للحصول على حساب Google AdMob. ستحتاج إلى حساب Google للبدء. AdMob هي منصة الإعلانات على الجوال من Google.

انتقل إلى AdMob ←

2أضف تطبيقك#

في لوحة تحكم AdMob:

• انقر على «Apps» في الشريط الجانبي
• انقر على «Add App»
• اختر «No» عند سؤال «Is your app listed on a supported app store?»
• أدخل اسم تطبيقك
• اختر «Android» كمنصة
• انقر على «Add»

3احصل على App ID#

بعد إنشاء تطبيقك:

• انسخ App ID المعروض (الصيغة: ca-app-pub-XXXXXXXXXXXXXXXX~XXXXXXXXXX)
• هذا يختلف عن معرّف وحدة الإعلان (Ad Unit ID)
• ستستخدم هذا في AndroidManifest.xml

App ID format:
ca-app-pub-1234567890123456~1234567890

4إنشاء وحدة إعلان (بانر)#

في تطبيق AdMob الخاص بك:

• انقر على تبويب «Ad units»
• انقر على «Add ad unit»
• اختر «Banner»
• أدخل اسم وحدة الإعلان (مثل: «Main Banner»)
• انقر على «Create ad unit»
• انسخ معرّف وحدة الإعلان (Ad Unit ID)

Banner Ad Unit ID format:
ca-app-pub-1234567890123456/1234567890

5الإعداد في AppMint#

في AppMint، الخطوة 3:

1. فعّل «AdMob Ads» والصق AdMob App ID (الذي يحتوي على ~)
2. Ad Control: أبقِ «Automatic» - يضع التطبيق الإعلانات نيابةً عنك
3. فعّل «Banner Ad»، واختر موضع الإعلان (Bottom أو Top) والصق معرّف وحدة إعلان البانر (الذي يحتوي على /)
4. تابع بقية الإعدادات وأنشئ تطبيقك

Ad Unit ID (not App ID):
ca-app-pub-XXXXXXXXXXXXXXXX/YYYYYYYYYY

6اختبر الإعلانات في تطبيقك#

أثناء التطوير، استخدم معرّفات الاختبار الرسمية من Google لتجنب مخالفة السياسات. انسخها والصقها في المولّد:

📋 AdMob App ID:
ca-app-pub-3940256099942544~3347511713

📋 معرّف وحدة إعلان البانر:
ca-app-pub-3940256099942544/6300978111

📋 معرّف وحدة الإعلان البيني:
ca-app-pub-3940256099942544/1033173712

📋 معرّف وحدة الإعلان المكافئ:
ca-app-pub-3940256099942544/5224354917

📋 معرّف الناشر:
pub-3940256099942544

📋 موقع المطوّر:
https://example.com

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

Test IDs for Generator:

AdMob App ID:       ca-app-pub-3940256099942544~3347511713
Banner Ad ID:       ca-app-pub-3940256099942544/6300978111
Interstitial ID:    ca-app-pub-3940256099942544/1033173712
Rewarded Ad ID:     ca-app-pub-3940256099942544/5224354917
Publisher ID:       pub-3940256099942544
Developer URL:      https://example.com

7الإعلانات البينية#

الإعلانات البينية هي إعلانات بملء الشاشة تغطي واجهة التطبيق كاملةً. يمكن للمستخدمين إغلاقها للعودة إلى التطبيق.

📺 كيفية التفعيل (الخطوة 3، Ad Control «Automatic»):

1. فعّل «Full Screen Ad»
2. نوع الإعلان: اختر «Interstitial Ad»
3. أدخل معرّف وحدة الإعلان البيني (أو اتركه فارغًا للإعلانات التجريبية)
4. اختر وضع التشغيل (Trigger Mode):

🔄 بعد التنقلات (الافتراضي):
يظهر الإعلان بعد كل N تنقل بين الصفحات. فمثلًا إذا ضُبط على 4، يظهر الإعلان بعد تحميل الصفحة الرابعة والثامنة والثانية عشرة، وهكذا.

📱 فتح التطبيق:
يظهر الإعلان مرة واحدة فور انتهاء شاشة البدء، عند فتح التطبيق لأول مرة.

👆 عند الطلب:
لا توجد إعلانات تلقائية - تعرض صفحتك إعلانًا عند النقر باستخدام WebToApk.showInterstitialAd().

⚠️ نوع الإعلان خيار واحد: بيني أو مكافئ، وليس كلاهما.

Example: every 4 page navigations

Page 1 → No ad
Page 2 → No ad
Page 3 → No ad
Page 4 → 📺 Interstitial Ad shown!
Page 5 → No ad
Page 6 → No ad
Page 7 → No ad
Page 8 → 📺 Interstitial Ad shown!
...

8الإعلانات المكافئة#

الإعلانات المكافئة هي إعلانات فيديو بملء الشاشة يشاهدها المستخدمون مقابل مكافأة. وتحقق إيرادات أعلى من إعلانات البانر أو الإعلانات البينية.

🎁 كيفية التفعيل (الخطوة 3، Ad Control «Automatic»):

1. فعّل «Full Screen Ad»
2. نوع الإعلان: اختر «Rewarded Ad»
3. أدخل معرّف وحدة الإعلان المكافئ (أو اتركه فارغًا للإعلانات التجريبية)
4. اختر وضع التشغيل (Trigger Mode):

🔄 بعد التنقلات (الافتراضي):
مشابه للإعلان البيني - يظهر الإعلان بعد كل N تحميل لصفحة. «Show ad after every N page navigations» يحدد قيمة N. والافتراضي 4.

📱 فتح التطبيق:
يظهر فيديو المكافأة مرة واحدة عند فتح التطبيق لأول مرة بعد شاشة البدء.

👆 عند الطلب:
لا توجد إعلانات تلقائية - يستدعي زر «شاهد إعلانًا لتربح» في صفحتك الدالة WebToApk.showRewardedAd().

💡 كم عدد التنقلات؟
أقل = إعلانات أكثر (إيرادات أكثر لكن تجربة أسوأ). أعلى = إعلانات أقل (تجربة أفضل لكن إيرادات أقل). الموصى به: 3-5.

⚠️ سياسة Google: تحتاج الإعلانات المكافئة إلى موافقة المستخدم. في وضعي «بعد التنقلات» و«فتح التطبيق» يعرض تطبيقك أولًا رسالة «هل تشاهد إعلانًا؟» مع زر «لا، شكرًا»؛ ولا يُعرض الإعلان إلا إذا قبل.

Revenue comparison (approximate):

Banner Ads:       $0.10 - $0.50 per 1000 views
Interstitial Ads: $1 - $5 per 1000 views
Rewarded Ads:     $5 - $15 per 1000 views

Recommended N (page navigations per ad):
Aggressive:  2-3 (more ads, more revenue)
Balanced:    4-5 (recommended)
Conservative: 6-10 (fewer ads, better UX)

9الموافقة وسياسة الخصوصية (مطلوبة)#

⚠️ يتطلب AdMob آلية موافقة للمستخدمين في المنطقة الاقتصادية الأوروبية والمملكة المتحدة وسويسرا والولايات الأمريكية.

يتولى التطبيق المُنشأ ذلك تلقائيًا باستخدام منصة رسائل المستخدم (UMP) من Google. سيقوم التطبيق بما يلي:

• اعرض نافذة موافقة للمستخدمين في المنطقة الاقتصادية الأوروبية/المملكة المتحدة/سويسرا قبل عرض الإعلانات
• اعرض نافذة لرفض الاشتراك للمستخدمين في الولايات الأمريكية المعنية
• اطلب الإعلانات فقط بعد الحصول على الموافقة

ما يجب عليك فعله:

1. في وحدة تحكم AdMob ← Privacy & messaging ← Create a European regulations message
2. في وحدة تحكم AdMob ← Privacy & messaging ← Create a US state regulations message
3. حدّد رابط سياسة الخصوصية في المولّد (الخطوة 3 أو الخطوة 4)
4. تأكد من أن سياسة الخصوصية تذكر إعلانات AdMob

⚠️ بدون هذا الإعداد، قد يعرض AdMob تحذيرًا بشأن السياسة: «Consent requirement: No CMP»

افتح AdMob Privacy & messaging ←

10عملية مراجعة الإعلانات#

بعد نشر تطبيقك:

• سيراجع AdMob تطبيقك (يستغرق عادةً 24-48 ساعة)
• في البداية سترى إعلانات تجريبية
• بعد الموافقة، ستبدأ الإعلانات الحقيقية بالظهور
• أبقِ محتوى تطبيقك متوافقًا مع السياسات

11تفعيل المدفوعات#

لتحصل على إيرادات الإعلانات:

• انتقل إلى «Payments» في لوحة تحكم AdMob
• أضف وسيلة دفع (حساب بنكي أو خيارات أخرى)
• تحقق من عنوانك
• أعدّ المعلومات الضريبية
• تُدفع المبالغ شهريًا بعد بلوغ حد 100 دولار

12أفضل الممارسات#

✅ موضع البانر: البانر السفلي أقل إزعاجًا ويوفر تجربة مستخدم أفضل

✅ بيني/مكافئ: اختر أحدهما وليس كليهما. الإعلانات المكافئة تربح أكثر لكنها تتطلب تفاعل المستخدم

✅ عدد الإجراءات: ابدأ بـ 4-5 تنقلات بين الإعلانات. الإفراط في الظهور = تقييمات سيئة

✅ اختبر أولًا: اختبر دائمًا بوحدات إعلان تجريبية أثناء التطوير

✅ راقب الأداء: تحقق من لوحة تحكم AdMob بانتظام لمعرفة الأرباح والمقاييس

⚠️ لا تنقر: لا تنقر على إعلاناتك أبدًا - فهذا يخالف سياسة AdMob

⚠️ محتوى عالي الجودة: تأكد من أن تطبيقك يقدّم قيمة ويلتزم بسياسات AdMob

💡 نصيحة: اجمع بين البانر (ظاهر دائمًا) والبيني أو المكافئ (دوري) لتحقيق أقصى إيراد

13استكشاف الأخطاء#

المشكلات الشائعة وحلولها:

• لا تظهر إعلانات: تحقق من استخدام معرّف وحدة الإعلان الصحيح (وليس App ID)
• الإعلانات التجريبية تعمل لكن الحقيقية لا تعمل: انتظر اكتمال مراجعة AdMob
• فشل طلب الإعلان: تحقق من اتصال الإنترنت وحالة حساب AdMob
• تعليق الحساب: راجع سياسات AdMob وقدّم استئنافًا إن لزم

مركز مساعدة AdMob ←

14إعلانات يتحكم بها المطوّر: ضع كل إعلان بنفسك#

نزّل صفحة العرض التوضيحي الكاملة أدناه (Coin Runner): بانر داخل التصميم، وإعلان بيني بين المراحل، وزر «شاهد إعلانًا لتربح 50 عملة»، ومستطيل 300×250، ومفتاح فتح التطبيق، وسجل مباشر لكل نتيجة. اضغطها في ZIP، وارفعها كـ Offline ZIP، واختر Developer-controlled مع المعرّفات التجريبية المعبأة مسبقًا، ثم أنشئ التطبيق - كل زر يشرح نفسه.

الخيارات أعلاه تخص الوضع التلقائي: يعرض التطبيق البانر والإعلان بملء الصفحة أو المكافئ نيابةً عنك. وإذا أردت جميع صيغ AdMob وحرية وضع كل منها حيث تحتاجه صفحتك، فاختر «Ad Control ← Developer-controlled» في الخطوة 3 بدلًا من ذلك.

في هذا الوضع لا شيء تلقائي. أدخل معرّف وحدة إعلان واحدًا لكل صيغة تستخدمها - بانر، مستطيل متوسط (300×250)، بيني، مكافئ، بيني مكافئ، فتح التطبيق - واترك الباقي فارغًا. بعدها تتحكم صفحتك في كل شيء عبر window.AppMintAds:

• AppMintAds.banner.attach('#slot', {size:'banner'|'medium_rectangle'}) - بانر يوضع فوق العنصر الذي تحدده، داخل بطاقة أو بين عناصر قائمة أو في أي مكان. يتبع العنصر عند التمرير؛ وdetach() يزيله. حتى اثنين في الوقت نفسه.
• await AppMintAds.load('interstitial') → {ok:true} or {ok:false, code:'no_fill'|'network'|'invalid_unit'|'consent'|'ad_free'|'disabled'}
• await AppMintAds.show('rewarded') → {shown:true, earned:true, reward:{type,amount}} or {shown:false, reason}
• AppMintAds.isReady('interstitial') - فعّل زرك اعتمادًا على هذا
• AppMintAds.appOpen.setEnabled(false) - أوقف إعلان فتح التطبيق مؤقتًا أثناء انشغال المستخدم بمهمة

يوجد AppMintAds داخل التطبيق المثبّت فقط - تحقق دائمًا من وجوده (if (window.AppMintAds) …) ليبقى عمل الصفحة سليمًا في المتصفح. وتبقى قواعد Google سارية ويفرضها التطبيق: لا يُعرض الإعلان المكافئ إلا بنقرة المستخدم نفسه (زر «شاهد إعلانًا» هو موافقته)، وتحافظ الإعلانات البينية على فاصل 60 ثانية، ولا تضع إعلانًا فوق إجراء أساسي أبدًا.

// Feature-detect: AppMintAds exists only in the installed app
const ads = window.AppMintAds;

// 1. A banner INSIDE your layout — <div id="ad-slot"></div> reserves the space
if (ads) {
  const r = await ads.banner.attach('#ad-slot', { size: 'banner' });
  console.log(r.ok ? 'banner ' + r.width + 'x' + r.height : 'no banner: ' + r.code);
}

// 2. A full-page ad at a natural break (between levels), never on every tap
async function levelFinished() {
  if (ads && ads.isReady('interstitial')) await ads.show('interstitial');
  showNextLevel();          // continues whether or not an ad was shown
}

// 3. A 'Watch ad to earn 50 coins' button — the tap is the user's opt-in
watchBtn.onclick = async () => {
  if (!ads) return;                                 // browser: no native ads
  // From a tap the ad plays. Without one (a timer, a route change) the app shows
  // AdMob's "Watch an ad? / No thanks" intro first and answers code 'declined'.
  const r = await ads.show('rewarded');
  if (r.earned) addCoins(r.reward.amount || 50);   // grant ONLY when earned
  else if (r.reason === 'ad_free') addCoins(50);    // premium user: grant without an ad
  else toast('No ad available right now');          // no popup, no Skip button
};

// 4. Preload and keep the button honest
ads?.load('rewarded').then(r => { watchBtn.disabled = !r.ok; });

15أحداث حالة الإعلان: اعرف ما حدث لكل طلب#

يُبلغ كل إعلان يتحكم به المطوّر عن دورة حياته الكاملة عبر حدث واحد، appmint:ad، لتتمكن من تسجيل نجاح التحميل والاستجابة للإخفاقات وتشغيل واجهتك الخاصة:

{ type, phase, slot?, code?, adCode?, message?, width?, height?, reward?, earned? }

• type: banner | mrec | interstitial | rewarded | rewarded_interstitial | app_open
• phase: loading → loaded | failed → opened → impression → clicked → closed، إضافةً إلى rewarded (تم كسب مكافأة) وshow_failed
• code (عند الفشل): no_fill | network | invalid_unit | internal - adCode هو رقم AdMob نفسه، وmessage نصه
• slot: أي موضع بانر، لإعلانات banner/mrec

تعطيك الـ promises الإجابة نفسها لكل استدعاء؛ أما الحدث فيعطيك كل شيء، بما في ذلك الإعلانات التي لم تستدعِ show() لها (إعلان فتح التطبيق، أو تحديث بانر). في الوضع التلقائي يبقى AppMintAds موجودًا لكنه يجيب بالرمز 'automatic_mode' - استخدم هناك استدعاءات WebToApk.showInterstitialAd()/showRewardedAd() والأحداث appmint:reward / appmint:ad-closed / appmint:ad-unavailable.

window.addEventListener('appmint:ad', e => {
  const a = e.detail;
  console.log(a.type, a.phase, a.code || '', a.message || '');
  if (a.phase === 'failed' && a.code === 'no_fill') analytics.track('ad_no_fill', a);
  if (a.type === 'rewarded' && a.phase === 'rewarded') console.log('earned', a.reward);
  if (a.type === 'banner' && a.phase === 'loaded') console.log('banner ' + a.width + 'x' + a.height + ' in ' + a.slot);
});

// What can this build serve? (guard it — in a browser AppMintAds is undefined)
if (window.AppMintAds) console.log(AppMintAds.config());
// → { control: 'developer', formats: { banner: true, mrec: false, interstitial: true, ... } }