Editor DocUI Widgets - Ads Button
It takes about 15 minutes to read this article
This article outlines the properties and instructions for UI widgets—Ads buttons.
What is the Ads button?
Ads buttons have Ads playback encapsulated inside, most Ads buttons are fixed and unmodifiable in style, and can only be clicked to play Ads if they are not obscured and displayed in their entirety within screen range. - Transform/align/generic/render properties see UI widget base properties - See UI widget-text for text properties 
Functional description of Ads button
- Player clicks Ads button in the experience to trigger Play Ads, and contains two events onClose/onShow is able to provide callbacks before Ads are about to play and when play is complete, providing information on whether there are currently Ads to play/whether Player successfully finished watching Ads.
- Ads buttons are not allowed to be modified for most properties related to the performance level (including widget size, button style and color, various rendering properties), only the overall position, align, visibility, usability, Z coefficient, and Ads text section are allowed to be modified, and in order to maintain a fixed size, Ads buttons aligning options align up/down/fully-justified/adaptive will not take effect.
- When making a UI, please note that the interface should be designed as uniformly as possible in combination with the fixed style of the Ads button. The colorless version of the button has an asset ID of 142733 in the asset library. Other buttons making the interface can use this asset.
- Please note: Ads buttons as a whole should not be obscured anywhere by any actually visible UI widget (including UI widgets such as visible non-interactive/modified rendering properties) or out of screen visibility. Non-compliant Ads buttons will not play Ads and will not trigger any events (but will trigger an error report).
- Scanning the code from the developer background into the test experience does not show real Ads, but a test Ads.
- Note that you must actually get the Ads button in the TS script (e.g. execute onClose or onShow at least once) to play Ads successfully, simply creating an Ads button without executing any TS logic cannot trigger Ads.
How to use the Ads button?
- onShow is triggered after requesting results from the client on whether Ads are playable (i.e., the value of isReady). If Ads are playable, onShow is triggered before pulling Ads; if no results are requested within 5 seconds, it is automatically triggered after another 5 seconds, and the parameter value of isReady is false.
- If there are no Ads to play after the Player clicks the Ads button, the Player is shown a 2-second prompt (mobile only).
- onClose is triggered when the user closes Ads, but note that onClose is also triggered when the user skips Ads, and the parameter value of isSuccess is also referenced as to whether rewards should be awarded.
- If you want to achieve ad playback using Ads buttons you can refer to the following:
ts
// Create Ad button, note that it cannot play Ads when obscured by any UI whose visibility is not hidden/collapsed
let adsbutton1=AdsButton.newObject(canvas)
// Trigger onShow after Player clicks Ads button, i.e. before playing Ads
adsbutton1.onShow.add((isReady: boolean)=>{
// Different logic can be executed depending on the value of isReady, such as pop-up prompt when no Ads are available, pause monster attacks when Ads are available and playing
if (isReady) {
this.onShowReady();
}else{
this.onShowUnready();
}
})
// Trigger onClose after Player closes Ads
adsbutton1.onClose.add((isSuccess: boolean)=>{
// Different logic can be executed based on the value of isSuccess, such as whether to award a reward to the Player
if (isSuccess) {
this.onCloseSuccess();
}else{
this.onCloseFailure();
}
})// Create Ad button, note that it cannot play Ads when obscured by any UI whose visibility is not hidden/collapsed
let adsbutton1=AdsButton.newObject(canvas)
// Trigger onShow after Player clicks Ads button, i.e. before playing Ads
adsbutton1.onShow.add((isReady: boolean)=>{
// Different logic can be executed depending on the value of isReady, such as pop-up prompt when no Ads are available, pause monster attacks when Ads are available and playing
if (isReady) {
this.onShowReady();
}else{
this.onShowUnready();
}
})
// Trigger onClose after Player closes Ads
adsbutton1.onClose.add((isSuccess: boolean)=>{
// Different logic can be executed based on the value of isSuccess, such as whether to award a reward to the Player
if (isSuccess) {
this.onCloseSuccess();
}else{
this.onCloseFailure();
}
})- If you want to query if there are currently playable Ads without creating an Ad button, you can do so using AdsService.isReady. For example, if you want to achieve the logic of creating an Ad button with Ads playable, you can refer to the following:
- Note that querying for Ads to play using AdsService.isReady is not a necessary pre-step. It can be done without writing. You can get Ads to play directly in the callback of AdsButton.onShow.
ts
// Can detect if there are currently Ads to play before creating ad button, can not write this step if not need to detect before creating ad button
AdsService.isReady( (isReady) => {
if (!isReady) {
// Execute logic here that no Ads can play
this.onShowUnready();
}else{
// here executes logic that Ads can play, such as create ad button
// Create Ad button, note that it cannot play Ads when obscured by any UI whose visibility is not hidden/collapsed
let adsbutton1=AdsButton.newObject(canvas)
// Trigger onShow after Player clicks Ads button, i.e. before playing Ads
adsbutton1.onShow.add((isReady: boolean)=>{
// Different logic can be executed depending on the value of isReady, such as pop-up prompt when no Ads are available, pause monster attacks when Ads are available and playing
if (isReady) {
this.onShowReady();
}else{
this.onShowUnready();
}
})
// Trigger onClose after Player closes Ads
adsbutton1.onClose.add((isSuccess: boolean)=>{
// Different logic can be executed based on the value of isSuccess, such as whether to award a reward to the Player
if (isSuccess) {
this.onCloseSuccess();
}else{
this.onCloseFailure();
}
})
}
})// Can detect if there are currently Ads to play before creating ad button, can not write this step if not need to detect before creating ad button
AdsService.isReady( (isReady) => {
if (!isReady) {
// Execute logic here that no Ads can play
this.onShowUnready();
}else{
// here executes logic that Ads can play, such as create ad button
// Create Ad button, note that it cannot play Ads when obscured by any UI whose visibility is not hidden/collapsed
let adsbutton1=AdsButton.newObject(canvas)
// Trigger onShow after Player clicks Ads button, i.e. before playing Ads
adsbutton1.onShow.add((isReady: boolean)=>{
// Different logic can be executed depending on the value of isReady, such as pop-up prompt when no Ads are available, pause monster attacks when Ads are available and playing
if (isReady) {
this.onShowReady();
}else{
this.onShowUnready();
}
})
// Trigger onClose after Player closes Ads
adsbutton1.onClose.add((isSuccess: boolean)=>{
// Different logic can be executed based on the value of isSuccess, such as whether to award a reward to the Player
if (isSuccess) {
this.onCloseSuccess();
}else{
this.onCloseFailure();
}
})
}
})