از Ad Placement API استفاده کنید

Ad Placement API شامل دو تابع است: adBreak() و adConfig( adConfig() که در فضای نام جهانی زیر تعریف شده اند. بیشتر آرگومان‌ها توابعی هستند که شما ارائه می‌کنید و به شما امکان می‌دهند مراحل کلیدی آماده‌سازی و نمایش یک آگهی را انجام دهید:

adBreak({
   type: '<type>',                      // The type of this placement
   name: '<name>',                      // A descriptive name for this placement
   beforeAd: () => {},                  // Prepare for the ad. Mute and pause the game flow
   afterAd: () => {},                   // Resume the game and un-mute the sound
   beforeReward: (showAdFn) => {},      // Show reward prompt (call showAdFn() if clicked)
   adDismissed: () => {},               // Player dismissed the ad before completion
   adViewed: () => {},                  // Ad was viewed and closed
   adBreakDone: (placementInfo) => {},  // Always called (if provided) even if an ad didn't show
});

adConfig({
   preloadAdBreaks: 'on|auto',      // Should ads always be preloaded
   sound: 'on|off',                 // Is sound currently enabled within the game
});

این توابع برای قرار دادن و پیکربندی تبلیغات در بازی شما استفاده می شود. آرگومان های نشان داده شده در بالا تنها آرگومان های معتبری هستند که می توانند به این توابع ارسال شوند. انواع مختلف تبلیغات به زیرمجموعه های متفاوتی از این آرگومان ها نیاز دارند که در زیر توضیح داده شده است.

adBreak() تابع کلیدی برای قرار دادن تبلیغات در بازی شما است. این یک مکان تبلیغاتی را تعریف می کند و یک شی به نام پیکربندی مکان را می گیرد که همه چیز مورد نیاز برای نمایش یک تبلیغ را مشخص می کند.

adBreak() را تعریف می کند که در آن تبلیغ می تواند نشان داده شود. اینکه آیا یک تبلیغ واقعاً نشان داده می شود به عواملی مانند موارد زیر بستگی دارد:

• نوع درج آگهی که اعلام کردید
  • آیا این تبلیغ در ابتدای بازی است؟ بین سطوح؟ در لحظه ای که بازیکن بازی را متوقف کرده است؟
• آیا آگهی مناسب برای پخش کننده فعلی وجود دارد یا خیر
  • آیا این تبلیغ به آنها مربوط است؟
  • آیا با تنظیمات حریم خصوصی داده و رضایت آنها سازگار است؟
• تعداد تبلیغاتی که بازیکن اخیراً دیده است
• تنظیمات کنترل - به عنوان مثال، فرکانس تبلیغات، که شما برای این بازی پیکربندی کرده اید
  • یا به عنوان نکات در تگ، یا
  • در AdSense—توجه داشته باشید که کنترل‌های موجود در AdSense در طول زمان تغییر خواهند کرد.

نوع تبلیغی که نشان می دهد نیز به عوامل مشابهی بستگی دارد.

توجه داشته باشید که تماس با adBreak() ممکن است اصلاً تبلیغی را نشان ندهد. این به سادگی مکانی را که در آن تبلیغ می تواند نشان داده شود را اعلام می کند.

این برخلاف API های سنتی است که در آن کد شما همیشه می داند که آیا یک تبلیغ در دسترس است یا خیر، و شما در بازی تصمیم می گیرید که آیا آن را نشان دهید یا خیر. این رویکرد که به Ad Placement API اجازه می‌دهد تصمیم بگیرد که آیا یک تبلیغ در یک مکان خاص نشان داده می‌شود، الگویی است که گاهی اوقات به عنوان "وارونگی کنترل" نامیده می‌شود.

دلیل اینکه ما API بازی‌هایمان را به این مدل تغییر می‌دهیم این است که ابتدا کدی را که باید در بازی خود بنویسید کوتاه می‌کند. ثانیا، ارائه مکان‌های منطبق با خط‌مشی با تجربه کاربری عالی را آسان‌تر می‌کند، که به نوبه خود به ما اجازه می‌دهد تا برخی از فرمت‌های با بالاترین عملکرد خود را به ناشران بازی ارائه دهیم. در نهایت، فرآیند قرار دادن تبلیغات در بازی شما را از تصمیمات کسب درآمد در مورد نوع و تعداد تبلیغات برای نمایش جدا می کند.

ما می خواهیم که بتوانید تنظیمات کسب درآمد خود را تغییر دهید و تجربه کاربری را بدون نیاز به ویرایش و انتشار نسخه جدیدی از بازی خود، در ابتدا با مشخص کردن نکاتی در برچسب، کنترل کنید. اما در نسخه‌های بعدی، می‌توانیم کنترل‌هایی را مستقیماً در AdSense و AdMob ارائه کنیم.

بینابینی

یک تبلیغ بینابینی یک تبلیغ تمام صفحه است که می تواند در لحظات مختلف در بازی شما نمایش داده شود، مانند زمانی که بازیکن بازی را شروع می کند یا بعد از اینکه بازیکن یک سطح را کامل می کند. بازی را متوقف می‌کند، کل سند را پوشش می‌دهد، و بازیکن می‌تواند انتخاب کند که روی تبلیغ کلیک کند (در این صورت تبلیغ در برگه دیگری از مرورگر خود نشان داده می‌شود) یا آن را رد کند که به آنها اجازه می‌دهد بازی را ادامه دهند.

توجه: قبل از اینکه بازی شما رابط کاربری خود را بارگیری کند، می‌توان یک بینابینی نشان داد. به این نوع تبلیغات، پیش نمایش گفته می شود و باید با آن ها کمی متفاوت از تبلیغات معمولی رفتار شود. درباره پیش‌پرول‌ها بیشتر بدانید

برای قرار دادن یک تبلیغ بینابینی، فیلدهای زیر را در پیکربندی مکان پر کنید:

adBreak({
   type: 'start',           // The type of this placement
   name: 'game_started',    // A descriptive name for this placement
   beforeAd: beforeAd,      // Prepare for the ad. Mute and pause the game flow
   afterAd: afterAd,        // Resume the game and un-mute the sound
   adBreakDone: breakDone,  // Always called (if provided) even if an ad didn't show
});

آرگومان type مورد نیاز است، و توصیه می کنیم همیشه مکان های خود را نام ببرید . تماس های دیگر اختیاری هستند.

دنباله تماس

دنباله تماس را برای یک تبلیغ بینابینی مرور کنید.

شرح

بینابینی - دنباله تماس دقیق
بازی H5 شما	Ad Placement API
	راه اندازی و بارگذاری اولیه تبلیغات
اجرای بازی
فرصت خوبی برای نمایش آگهی... adBreak() →
	یک تبلیغ موجود است و اکنون زمان خوبی برای نمایش آن است... ← beforeAd()
بازی مکث می کند، صدا را قطع می کند و برای نمایش آگهی آماده می شود. return به API →
	Ad Placement API آگهی بینابینی را ارائه می کند. بازیکن می تواند روی تبلیغ (که در یک برگه جدید نمایش داده می شود) کلیک کند. آنها باید آگهی را رد کنند تا به بازی ادامه دهند.
	← afterAd() در صورتی فراخوانی می شود که تبلیغی نشان داده شده باشد
بازی صدا را از حالت مکث خارج می کند و قطع می کند.
	← adBreakDone() adBreakDone() همیشه فراخوانی می شود (حتی اگر تبلیغی نشان داده نشده باشد)
بازی تجزیه و تحلیل های مربوط به این مکان را ثبت می کند.

یادداشت

• adBreak() یک تابع ناهمزمان است که بلافاصله برمی گردد.
• اگر هیچ تبلیغی برای نمایش برای یک مکان وجود نداشته باشد، هیچ یک از callback ها فراخوانی نمی شوند - یعنی هیچ یک از beforeAd() BeforeAd، afterAd() فراخوانی نمی شوند.
• برای اطمینان از اینکه بازی شما در حین نمایش تبلیغ اجرا نمی شود، از beforeAd() برای قطع صدا و توقف بازی استفاده کنید.
• قبل از beforeAd() همزمان باشد، API Ad Placement تا زمانی که برنگردد تبلیغی را نشان نمی‌دهد.
• بازی خود را مجدداً راه اندازی کنید و هنگامی که تماس afterAd() را دریافت کردید، صدا را قطع کنید.
• در صورت ارائه، adBreakDone() همیشه فراخوانی می شود حتی اگر تبلیغی در این مکان نشان داده نشده باشد.
• فراخوانی adBreak() در حالی که تبلیغ دیگری نمایش داده می شود با شکست مواجه می شود و یک هشدار در کنسول جاوا اسکریپت نمایش داده می شود.

پیش نمایش ها

یک پیش‌پرول یک میان‌افزار است که قبل از بارگیری رابط کاربری بازی شما نمایش داده می‌شود. این اولین چیزی است که یک بازیکن هنگام رفتن به بازی شما می بیند. از آنجایی که یک پیش نمایش در اوایل بارگذاری صفحه اتفاق می‌افتد و بازی شما هنوز نمایش داده نمی‌شود، به تماس‌های معمول برای توقف موقت و بی‌صدا کردن بازی‌تان نیازی نیست. درعوض، از adBreakDone() استفاده می‌کنید تا شروع بازی خود را با تبلیغ ترتیب دهید—یعنی رابط کاربری را رندر کنید و شروع به پخش صدا کنید. برای هر بارگذاری صفحه فقط یک پیش‌پرول می‌تواند فعال شود.

دنباله تماس

فراخوان برای پیش نمایش خیلی زود در بارگذاری صفحه انجام می شود. از آنجایی که بازی شما در این مرحله رابط کاربری خود را رندر نکرده است، نباید از beforeAd() BeforeAd و afterAd() عبور کنید. درعوض، از adBreakDone() برای شروع بازی خود پس از قرار دادن استفاده کنید، زیرا تضمین می شود که حتی اگر هیچ تبلیغی وجود نداشته باشد، فراخوانی می شود.

با فراخوانی کد زیر، در اوایل منطق بازی شما یک تبلیغ قبل از پخش قرار می گیرد. رابط کاربری شما نباید قبل از فراخوانی این کد ارائه شود.

// Game must not be running.
// Nothing in the game area should be clickable
adBreak({
   type: ‘preroll',
   adBreakDone: startGame,
})

Preroll - دنباله تماس دقیق
بازی H5 شما	Ad Placement API
	راه اندازی API و پیش ذخیره سازی تبلیغات شروع می شود
در حال اجرا است اما شروع نشده است و رابط کاربری نمایش داده نشده است
adBreak(type:'preroll',…) →
	Ad Placement API مقداردهی اولیه و بارگذاری تبلیغات را به پایان می رساند. اگر تبلیغی وجود داشته باشد نشان داده می شود. بازیکن می تواند روی تبلیغ (که در یک برگه جدید نمایش داده می شود) کلیک کند. آنها باید آن را رد کنند تا بازی شروع شود.
	← adBreakDone() همیشه فراخوانی می شود (حتی اگر تبلیغی نشان داده نشده باشد)
رابط کاربری بازی روی صفحه نمایش داده می شود و بازیکن اکنون می تواند با آن تعامل داشته باشد. بازی می‌تواند در صورت نیاز از شی placementInfo ارسال شده به adBreakDone() استفاده کند (مثلاً برای ثبت تجزیه و تحلیل اضافی).

یادداشت

• یک پیش نمایش همیشه سعی می کند تبلیغات را از قبل بارگیری کند:
  • فراخوانی adConfig(preloadAds: 'on') با پیش‌پرول‌ها الزامی نیست.
• مانند سایر مکان‌های تبلیغاتی، پیش نمایش ممکن است تبلیغی را نشان دهد یا ندهد.
• beforeAd() BeforeAd و afterAd() نباید به یک preroll منتقل شوند.
  • از آنجایی که تبلیغات پیش از پخش قبل از شروع بازی شما اجرا می شود، نیازی به مکث یا بی صدا کردن صدای بازی نیست.
  • اگر قبل از beforeAd() Ad یا afterAd() را با یک پیش رول ارسال کنید، تماس با شکست مواجه می شود و یک خطا در کنسول جاوا اسکریپت ثبت می شود.
• یک پیش نمایش به طور خودکار منتظر می ماند تا Ad Placement API مقداردهی اولیه و بارگذاری اولیه تبلیغات را انجام دهد:
  • با این حال، یک بازه زمانی (2 ثانیه) وجود دارد که از تأخیر نامحدود تماس جلوگیری می کند. این تضمین می کند که adBreakDone() به موقع فراخوانی می شود و بازی شما شروع می شود.
  • adBreakDone() همیشه فراخوانی می شود حتی اگر هیچ تبلیغی وجود نداشته باشد.
• توصیه می کنیم قبل از شروع بازی از یک پیش نمایش برای قرار دادن تبلیغات استفاده کنید.
  • از طرف دیگر، می توانید از onReady() به ( adConfig() adConfig به عنوان مکانیزمی برای توالی منطق بازی خود با مقداردهی اولیه API و بارگذاری اولیه تبلیغات استفاده کنید.

تبلیغات با پاداش

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

برخلاف مطالب بینابینی، که در آن بازیکن می‌تواند در هر زمان تبلیغ را رد کند، برای دریافت جایزه، باید آگهی را برای حداقل زمان مشاهده کند (که بسته به خلاقیت تبلیغی که نشان داده می‌شود می‌تواند متفاوت باشد).

از آنجایی که تبلیغات پاداش برای بازیکن اختیاری است، نیاز به ادغام عمیق تری در جریان بازی شما دارد. شما باید عملکردهایی را برای ارائه یک درخواست پاداش در بازی خود ارائه دهید و در صورت تماشای تبلیغ، پاداش را به بازیکن اختصاص دهید.

جوایز نباید ارزشی خارج از برنامه شما داشته باشند، نباید ارزش پولی داشته باشند (یا به راحتی با آنها مبادله شوند)، و نباید قابل فروش یا مبادله با کالاها و خدمات باشند، و نباید بازیکنان را تشویق کنید که روی تبلیغات کلیک کنند. لطفاً برای جزئیات بیشتر به خط‌مشی پیش‌نویس برای مطالب بینابینی مراجعه کنید.

از آنجایی که جوایز برای بازیکن اختیاری است، می‌توانید آن‌ها را در هر جایی که در بازی‌تان منطقی است اضافه کنید و علاوه بر موارد بینابینی از آن‌ها استفاده کنید. مانند تبلیغات بینابینی، این مکان‌ها فرصت‌هایی برای نمایش تبلیغات با پاداش هستند. Ad Placement API تنها زمانی کد شما را فراخوانی می‌کند که واقعاً در نقطه خاصی از بازی شما یک تبلیغ پاداش ارائه شود.

بار دیگر هدف در اینجا این است که به شما اجازه دهیم یک بار بازی خود را با Ad Placement API ادغام کنید و سپس، به مرور زمان با استفاده از کنترل‌ها در تگ یا در AdSense، می‌توانید ترکیب دقیق تبلیغات فعال‌شده را بدون نیاز به تغییر دهید. بازی خود را مجدداً رمزگذاری کرده و مجدداً منتشر کنید.

نوع قرار دادن پاداش همیشه 'reward' و می توان از تمام فیلدهای موجود در پیکربندی قرارگیری استفاده کرد.

adBreak({
   type: 'reward',                      // The type of this placement
   name: '<name>',                      // A descriptive name for this placement
   beforeAd: () => {},                  // Prepare for the ad. Mute and pause the game flow
   afterAd: () => {},                   // Resume the game and re-enable sound
   beforeReward: (showAdFn) => {},      // Show reward prompt (call showAdFn() if clicked)
   adDismissed: () => {},               // Player dismissed the ad before it finished.
   adViewed: () => {},                  // Player watched the ad–give them the reward.
   adBreakDone: (placementInfo) => {},  // Always called (if provided) even if an ad didn't show
});

توابع جدید کلیدی عبارتند از beforeReward() که محرکی است که به شما سیگنال می دهد که باید اعلان پاداش را ارائه دهید و adViewed() که زمانی فراخوانی می شود که پخش کننده تبلیغ را با موفقیت مشاهده کرد، بنابراین می توانید پاداش خود را اختصاص دهید.

شما ممکن است یک مکان با پاداش را به صورت زیر تعریف کنید:

adBreak({
   type: 'reward',
   name: 'new_life_reward_1',
   beforeAd: pauseGame,
   afterAd: restartGame,
   beforeReward: showRewardPrompt,
   adDismissed: adDismissed,
   adViewed: adViewed,
   adBreakDone: breakDone,
});

تبلیغات پاداش با یک درخواست در بازی شما شروع می شود که در صورت مشاهده یک تبلیغ به بازیکن پاداش می دهد.

دنباله تماس برای تبلیغ پاداش

شرح

تبلیغ پاداش - دنباله تماس دقیق
بازی H5 شما	Ad Placement API
	راه اندازی و پیش ذخیره سازی تبلیغات
اجرای بازی
adBreak(type:'reward', ... ) →
	یک تبلیغ در دسترس است، بنابراین یک تبلیغ با پاداش را شروع کنید. beforeReward() به صورت همزمان فراخوانی می شود – بلافاصله پس از فراخوانی adBreak() ← beforeReward(showAdFn)
بازی اعلان پاداش را ارائه می دهد. این به بازیکن این فرصت را می دهد که با تماشای یک تبلیغ جایزه دریافت کند. بیش از یک نوع پاداش می تواند ارائه شود (به عنوان مثال، یک زندگی جدید یا یک سکه طلا). بازیکن می‌تواند روی یک درخواست پاداش کلیک کند، آنها را رد کند یا به سادگی آنها را نادیده بگیرد. اگر روی یک فرمان کلیک کنند، آنگاه بازی نوع پاداشی را که درخواست کرده اند ذخیره می کند و showAdFn()... در غیر این صورت، اگر درخواست پاداش نادیده گرفته شود یا نادیده گرفته شود، هیچ اتفاقی نمی‌افتد تا زمانی که تماس دیگری با adBreak() با نوع قرار دادن پاداش برقرار کنید، در این مرحله Ad Placement API تنظیم مجدد می‌شود و وضعیت را از این تماس پاک می‌کند. اگر برنامه showAdFn را از یک استراحت تبلیغاتی قبلی فراخوانی کند، تأثیری ندارد.
showAdFn() →
	← beforeAd()
بازی مکث می کند، صدا را قطع می کند و برای نمایش آگهی آماده می شود return به API →
	API آگهی را نشان می دهد. دارای دکمه رد کردن و شمارش معکوس برای مدت زمان باقی مانده در آگهی است.
اگر بازیکن تبلیغ را رد کند...
	← adDismissed()
بازیکن تبلیغ را رد کرد و بازی پاداش را صادر نمی کند.
در غیر این صورت بازیکن آگهی را تا پایان تماشا می کند...
	← adViewed()
بازیکن آگهی را تا پایان تماشا کرد و بازی پاداش را صادر کرد. (این معمولاً با تنظیم حالت بازی است که پس از شروع مجدد بازی با فراخوانی afterAd() در زیر انتخاب می شود).
بعد از تماشا یا رد شدن آگهی...
	← afterAd() در صورتی فراخوانی می شود که تبلیغی نشان داده شده باشد
بازی صدا را از حالت مکث خارج می کند و قطع می کند.
	← adBreakDone() adBreakDone() همیشه فراخوانی می شود (حتی اگر تبلیغی نشان داده نشده باشد)
بازی تجزیه و تحلیل های مربوط به این مکان را ثبت می کند.

یادداشت

• adBreak() یک تابع ناهمزمان است که بلافاصله برمی گردد.
• اگر هیچ تبلیغی برای نمایش دادن برای یک مکان وجود نداشته باشد، هیچ یک از callback ها فراخوانی نمی شوند - یعنی هیچ یک از beforeAd() beforeReward() ) BeforeReward فراخوانی نمی شوند.
• برای اطمینان از اینکه بازی شما در حین نمایش تبلیغ اجرا نمی شود، از beforeAd() برای قطع صدا و توقف بازی استفاده کنید.
• قبل از beforeAd() همزمان باشد، API Ad Placement تا زمانی که برنگردد تبلیغی را نشان نمی‌دهد.
• بازی خود را مجدداً راه اندازی کنید و هنگامی که تماس afterAd() را دریافت کردید، صدا را قطع کنید.
• در صورت ارائه، adBreakDone() همیشه فراخوانی می شود حتی اگر تبلیغی در این مکان نشان داده نشده باشد.
• فراخوانی adBreak() در حالی که تبلیغ دیگری نمایش داده می شود با شکست مواجه می شود و یک هشدار در کنسول جاوا اسکریپت نمایش داده می شود.