یکپارچه‌سازی AdMob

1ایجاد حساب AdMob#

برای یک حساب Google AdMob ثبت‌نام کنید. برای شروع به یک حساب Google نیاز دارید. AdMob پلتفرم تبلیغات موبایلی Google است.

رفتن به AdMob ←

2اپلیکیشن خود را اضافه کنید#

در داشبورد AdMob:

• در نوار کناری روی «Apps» کلیک کنید
• روی «Add App» کلیک کنید
• برای «Is your app listed on a supported app store?» گزینه «No» را انتخاب کنید
• نام اپلیکیشن خود را وارد کنید
• «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، مرحله ۳:

1. «AdMob Ads» را روشن کنید و App ID مربوط به AdMob خود را جای‌گذاری کنید (همان که ~ دارد)
2. Ad Control: روی «Automatic» بماند - اپلیکیشن تبلیغات را برای شما قرار می‌دهد
3. «Banner Ad» را روشن کنید، موقعیت تبلیغ (پایین یا بالا) را انتخاب کنید و Banner Ad Unit ID خود را جای‌گذاری کنید (همان که / دارد)
4. با بقیه تنظیمات ادامه دهید و اپلیکیشن خود را بسازید

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

6آزمایش تبلیغات در اپلیکیشن شما#

در زمان توسعه، برای پرهیز از نقض سیاست‌ها از شناسه‌های آزمایشی رسمی Google استفاده کنید. این‌ها را در ابزار ساخت کپی و جای‌گذاری کنید:

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

📋 Banner Ad Unit ID:
ca-app-pub-3940256099942544/6300978111

📋 Interstitial Ad Unit ID:
ca-app-pub-3940256099942544/1033173712

📋 Rewarded Ad Unit ID:
ca-app-pub-3940256099942544/5224354917

📋 Publisher ID:
pub-3940256099942544

📋 Developer Website:
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تبلیغات تمام‌صفحه‌ای (Interstitial)#

تبلیغات تمام‌صفحه‌ای (Interstitial) کل رابط اپلیکیشن را می‌پوشانند. کاربران می‌توانند آن‌ها را ببندند و به اپلیکیشن برگردند.

📺 نحوه فعال‌سازی (مرحله ۳، Ad Control «Automatic»):

1. «Full Screen Ad» را روشن کنید
2. نوع تبلیغ: «Interstitial Ad» را انتخاب کنید
3. Interstitial Ad Unit ID خود را وارد کنید (یا برای تبلیغات آزمایشی خالی بگذارید)
4. حالت راه‌اندازی را انتخاب کنید:

🔄 پس از ناوبری‌ها (پیش‌فرض):
تبلیغ پس از هر N بار ناوبری صفحه نمایش داده می‌شود. مثلاً اگر روی ۴ تنظیم شود، تبلیغ پس از بارگذاری چهارم، هشتم، دوازدهم صفحه و همین‌طور ادامه نشان داده می‌شود.

📱 App Open:
تبلیغ یک بار بلافاصله پس از صفحه شروع، هنگام اولین باز شدن اپلیکیشن، نمایش داده می‌شود.

👆 بر اساس درخواست:
تبلیغ خودکار وجود ندارد - صفحه شما با یک ضربه و با WebToApk.showInterstitialAd() یک تبلیغ نشان می‌دهد.

⚠️ نوع تبلیغ یک انتخاب است: تمام‌صفحه‌ای (Interstitial) یا پاداشی، نه هر دو.

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تبلیغات پاداشی#

تبلیغات پاداشی، تبلیغات ویدیویی تمام‌صفحه‌ای هستند که کاربران در ازای دریافت پاداش تماشا می‌کنند. درآمد آن‌ها از تبلیغات بنری یا تمام‌صفحه‌ای بیشتر است.

🎁 نحوه فعال‌سازی (مرحله ۳، Ad Control «Automatic»):

1. «Full Screen Ad» را روشن کنید
2. نوع تبلیغ: «Rewarded Ad» را انتخاب کنید
3. Rewarded Ad Unit ID خود را وارد کنید (یا برای تبلیغات آزمایشی خالی بگذارید)
4. حالت راه‌اندازی را انتخاب کنید:

🔄 پس از ناوبری‌ها (پیش‌فرض):
مشابه تبلیغ تمام‌صفحه‌ای - تبلیغ پس از هر N بار بارگذاری صفحه نمایش داده می‌شود. «Show ad after every N page navigations» مقدار N را تعیین می‌کند. پیش‌فرض ۴ است.

📱 App Open:
ویدیوی پاداشی یک بار، هنگام اولین باز شدن اپلیکیشن پس از صفحه شروع، نمایش داده می‌شود.

👆 بر اساس درخواست:
تبلیغ خودکار وجود ندارد - دکمه «تماشای تبلیغ برای دریافت پاداش» خود صفحه شما WebToApk.showRewardedAd() را فراخوانی می‌کند.

💡 چند ناوبری؟
کمتر = تبلیغ بیشتر (درآمد بیشتر ولی تجربه بدتر). بیشتر = تبلیغ کمتر (تجربه بهتر ولی درآمد کمتر). پیشنهاد: ۳ تا ۵.

⚠️ سیاست Google: تبلیغات پاداشی به موافقت کاربر نیاز دارند. در حالت‌های «پس از ناوبری‌ها» و App Open، اپلیکیشن شما ابتدا پیام «تبلیغ ببینید؟» را با دکمه «نه، ممنون» نشان می‌دهد؛ تبلیغ فقط در صورت پذیرش پخش می‌شود.

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 برای کاربران در EEA، بریتانیا، سوئیس و ایالت‌های آمریکا به سازوکار رضایت نیاز دارد.

این کار به‌طور خودکار توسط اپلیکیشن ساخته‌شده و با استفاده از Google's User Messaging Platform (UMP) انجام می‌شود. اپلیکیشن:

• پیش از نمایش تبلیغات، یک پنجره رضایت را به کاربران EEA/بریتانیا/سوئیس نشان دهد
• یک پنجره انصراف را به کاربران ایالت‌های مربوطه در آمریکا نشان دهد
• فقط پس از دریافت رضایت تبلیغ درخواست کند

کاری که شما باید انجام دهید:

1. در کنسول AdMob ← Privacy & messaging ← Create a European regulations message
2. در کنسول AdMob ← Privacy & messaging ← Create a US state regulations message
3. نشانی URL سیاست حفظ حریم خصوصی خود را در ابزار ساخت تنظیم کنید (مرحله ۳ یا مرحله ۴)
4. مطمئن شوید سیاست حفظ حریم خصوصی شما به تبلیغات AdMob اشاره می‌کند

⚠️ بدون این تنظیم، ممکن است AdMob یک هشدار سیاستی نشان دهد: «Consent requirement: No CMP»

باز کردن AdMob Privacy & messaging ←

10فرایند بررسی تبلیغ#

پس از انتشار اپلیکیشن:

• AdMob اپلیکیشن شما را بررسی می‌کند (معمولاً ۲۴ تا ۴۸ ساعت طول می‌کشد)
• در ابتدا تبلیغات آزمایشی خواهید دید
• پس از تأیید، تبلیغات واقعی شروع به نمایش می‌کنند
• محتوای اپلیکیشن خود را مطابق سیاست‌ها نگه دارید

11فعال‌سازی پرداخت‌ها#

برای دریافت درآمد تبلیغات:

• در داشبورد AdMob به «Payments» بروید
• روش پرداخت را اضافه کنید (حساب بانکی یا گزینه‌های دیگر)
• نشانی خود را تأیید کنید
• اطلاعات مالیاتی را تنظیم کنید
• پرداخت‌ها ماهانه و پس از رسیدن به آستانه ۱۰۰ دلار انجام می‌شوند

12بهترین روش‌ها#

✅ جایگاه بنر: بنر پایین مزاحمت کمتری دارد و تجربه کاربری بهتری می‌دهد

✅ تمام‌صفحه‌ای/پاداشی: یکی را انتخاب کنید، نه هر دو. تبلیغات پاداشی درآمد بیشتری دارند اما به تعامل کاربر نیاز دارند

✅ تعداد اقدام: با ۴ تا ۵ ناوبری بین تبلیغات شروع کنید. زیاد بودن = نظرات بد

✅ اول آزمایش کنید: همیشه در زمان توسعه با واحدهای تبلیغاتی آزمایشی تست کنید

✅ عملکرد را زیر نظر بگیرید: داشبورد AdMob را برای درآمد و آمار مرتب بررسی کنید

⚠️ کلیک نکنید: هرگز روی تبلیغات خودتان کلیک نکنید - این کار سیاست AdMob را نقض می‌کند

⚠️ محتوای باکیفیت: مطمئن شوید اپلیکیشن شما ارزش ایجاد می‌کند و از سیاست‌های AdMob پیروی می‌کند

💡 نکته حرفه‌ای: برای بیشترین درآمد، بنر (همیشه نمایان) را با تمام‌صفحه‌ای یا پاداشی (دوره‌ای) ترکیب کنید

13عیب‌یابی#

مشکلات رایج و راه‌حل‌ها:

• تبلیغی نمایش داده نمی‌شود: بررسی کنید که از Ad Unit ID درست استفاده می‌کنید (نه App ID)
• تبلیغات آزمایشی کار می‌کنند اما تبلیغات واقعی نه: صبر کنید تا بررسی AdMob کامل شود
• درخواست تبلیغ ناموفق بود: اتصال اینترنت و وضعیت حساب AdMob را بررسی کنید
• حساب تعلیق شد: سیاست‌های AdMob را مرور کنید و در صورت لزوم درخواست تجدیدنظر بدهید

مرکز راهنمای AdMob ←

14تبلیغات تحت کنترل توسعه‌دهنده: هر تبلیغ را خودتان قرار دهید#

صفحه نمونه کامل را از پایین دانلود کنید (Coin Runner): یک بنر داخل چیدمان، یک تبلیغ تمام‌صفحه‌ای بین مراحل، یک دکمه «تماشای تبلیغ برای ۵۰ سکه»، یک مستطیل ۳۰۰×۲۵۰، کلید app-open و یک گزارش زنده از هر نتیجه. آن را ZIP کنید، به‌عنوان Offline ZIP بارگذاری کنید، Developer-controlled را با شناسه‌های آزمایشی از پیش پرشده انتخاب کنید و بسازید - هر دکمه خودش را توضیح می‌دهد.

گزینه‌های بالا حالت خودکار هستند: اپلیکیشن بنر و تبلیغ تمام‌صفحه یا پاداشی را برای شما نشان می‌دهد. اگر همه قالب‌های AdMob را می‌خواهید و می‌خواهید هر کدام را دقیقاً جایی که صفحه‌تان لازم دارد بگذارید، در عوض در مرحله ۳ گزینه «Ad Control ← Developer-controlled» را انتخاب کنید.

در این حالت هیچ‌چیز خودکار نیست. برای هر قالبی که استفاده می‌کنید یک شناسه واحد تبلیغاتی وارد کنید - بنر، مستطیل متوسط (300×250)، تمام‌صفحه‌ای، پاداشی، تمام‌صفحه‌ای پاداشی، app-open - و بقیه را خالی بگذارید. سپس صفحه شما همه‌چیز را از طریق 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) - تبلیغ app-open را وقتی کاربر وسط کاری است متوقف کنید

AppMintAds فقط داخل اپلیکیشن نصب‌شده وجود دارد - همیشه وجود آن را بررسی کنید (if (window.AppMintAds) …) تا صفحه در مرورگر هم کار کند. قوانین Google همچنان برقرارند و اپلیکیشن آن‌ها را اعمال می‌کند: تبلیغ پاداشی فقط با ضربه خود کاربر پخش می‌شود (دکمه «تماشای تبلیغ» شما همان موافقت اوست)، تبلیغات تمام‌صفحه‌ای ۶۰ ثانیه فاصله دارند و هرگز تبلیغی را روی یک عمل اصلی قرار ندهید.

// 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, plus rewarded (a reward was earned) and show_failed
• code (on failed): no_fill | network | invalid_unit | internal - adCode is AdMob's own number, message its text
• slot: کدام جایگاه بنر، برای banner/mrec

Promiseها برای هر فراخوانی همان پاسخ را می‌دهند؛ رویداد همه‌چیز را به شما می‌دهد، از جمله تبلیغاتی که برایشان show() را فراخوانی نکرده‌اید (تبلیغ app-open، تازه‌سازی بنر). در حالت خودکار 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, ... } }