Skip to content

Advertising ​

Game Developer Quick Start ​

Game scripts use the sud ad APIs. The host app provides the ad dependencies, OP initialization, and privacy configuration. Start with game developer examples to connect ad loading, display triggers, and scene cleanup.

FormatGame flowAPI
BannerDisplay in a scene; hide temporarily and clean up on exitsud.createBannerAd
InterstitialPrepare during a level and display at a natural breaksud.createInterstitialAd
Rewarded videoPrepare in advance; display after the user's choicesud.createRewardedVideoAd

Ad Error Codes ​

errCodeDescriptionRecommended action
-21001Invalid parameters, call order, or ad object state, such as an empty adUnitId, frequent requests, an ad not ready, or a destroyed instanceCheck parameters and call order, and wait for onLoad before showing. Do not call show() after loading fails; create a new ad object after destruction. Avoid immediate retry loops when the frequency limit is reached
-22001Ad module initialization, configuration, or integration failure, or no eligible ad candidates; this code alone does not prove that backend ad configuration is missingThe CP must first enable advertising for the game in the OpenPaaS console and verify the ad unit ID and format. Use errMsg to check the integration, initialization, and configuration of the host ad module and ad-source adapters. For Banner ads, also compare the maximum container dimensions with the ad size; this code may occur when no candidate fits
-22005The ad configuration request failed, for example due to a network error or server rejection caused by invalid application or game configuration; refer to errMsg for the specific reasonCheck network connectivity first. If errMsg contains a server-side failure, verify the application ID, game ID, application-to-game association, and platform configuration in the current environment; correct the configuration according to the returned reason instead of repeatedly retrying
-23001Ad load or display failure, possibly involving a timeout, an ad-source error, or an unusable auction result; this code alone does not establish a no-fill resultAddress the specific reason in errMsg and avoid ineffective retries. Load again and wait for onLoad before showing
-29001Unclassified internal errorRecord the complete errCode and errMsg, platform, app/SDK versions, ad format, ad unit ID, and reproduction steps, then contact technical support

Creation-stage troubleshooting: If errMsg indicates that no matching ad placement was found (for example, No ad placement matches this adUnitId), first check whether advertising is enabled for the game in the console and whether the ad unit ID and format are correct. A successful ad/init response may still contain an empty ad unit list. Enable advertising and verify the configuration first; repeatedly calling load() or show() cannot resolve missing configuration.

Keep both the error code and the complete error message when investigating a failure:

  • errCode is the unified error category exposed to the game. A raw_code in errMsg is an original error code from the corresponding layer, such as a server, ad SDK, or ad source; do not use it as a unified error code.
  • Diagnostic details such as stage, format, sources, and raw_message, when present, can help identify the failure stage, ad format, and ad-source cause. Their content may vary by platform, version, and failure path, and they are not guaranteed to appear. Avoid parsing these text details to control application logic.
  • One error code can have multiple causes. Preserve the complete errMsg instead of extracting only the error code.