XmobiTea Ads

Unity package with two separate runtime systems. Start by choosing the system that matches your task.

Choose Your Track

AdsManager

AdsManager is the ad-display side of the package. It does not ship a real ad SDK. Instead, it forwards reward, interstitial, and banner requests to the first ready controller from your assigned AdsControllerBase subclasses.

Use AdsManager when the task is about showing ads or integrating a concrete ad network controller.

Read deeper:

• AdsManager setup
• AdsManager runtime usage
• AdsManager API
• AdsControllerBase API
• AdsManager runtime behavior
• AdsControllerBase behavior

MiniAds

MiniAds is the cross-promo side of the package. It fetches a remote app list, restores the last cached JSON payload, caches icons on disk, and exposes GameItem entries that can be opened or checked for install state.

Use MiniAds when the task is about promoted app data, JSON feeds, icon hydration, or cross-promo UI.

Read deeper:

• MiniAds setup
• MiniAds runtime usage
• MiniAds API
• GameItem API
• MiniAds initialization
• Fetch and icon cache behavior

AI Entry Points

Use the smallest file for the task.

| Need | Use | | --- | --- | | Choose the correct system and fast rules | AI_USAGE.md | | Choose the correct setup guide | AI_SETUP.md | | Setup AdsManager and controller subclasses | AI_SETUP_ADS_MANAGER.md | | Setup MiniAds, AdsSettings, and the JSON feed | AI_SETUP_MINIADS.md | | Generate reward/interstitial/banner code | AI_USE_ADS_MANAGER.md | | Generate cross-promo fetch/open/install/icon code | AI_USE_MINIADS.md | | Exact public signatures, return values, fields, editor menus | AI_API_REFERENCE.md | | Lifecycle, cache, controller priority, platform behavior, hazards | AI_BEHAVIOR.md | | Package-level hard rules and maintenance checklist | AGENTS.md | | Missing or conflicting detail | runtime/editor source code |

Shared Contract

• Namespace: XmobiTea.MiniAds
• Package name: com.xmobitea.changx.mini-ads
• Unity: 2022.3+
• AdsManager and MiniAds inherit from Singleton<T>.
• Neither manager auto-creates a scene object.
• AdsManager controller initialization happens in Start(), not in Awake().
• AdsManager uses the first configured controller that reports readiness for the requested ad type.
• AdsManager does not null-check _adsControllers or individual controller entries.
• MiniAds.OnInit() restores cached JSON immediately and may start icon downloads during initialization.
• MiniAds uses GlobalCoroutine for remote fetches and uncached icon downloads.
• MiniAds loads AdsSettings from Assets/Resources/XmobiTea AdsSettings.asset.
• MiniAds.Fetch(...) returns the current cached list while the stored absolute expiry timestamp is still in the future.
• GameItem.IsInstall() and GameItem.Open() are platform-specific.
• On Apple-family builds, Open() uses appleId as an App Store id, but the current native install check uses the same string as URL-scheme input.
• The package does not include a production ad SDK integration.

What This Package Provides

| Type | Role | | --- | --- | | AdsManager | Reward/interstitial/banner facade over assigned controllers | | AdsControllerBase | Base class for concrete ad SDK adapters | | MiniAds | Remote cross-promo fetch, JSON cache, icon cache | | GameItem | Cross-promo app item model with open/install helpers and raw JObject metadata | | AdsSettings | Resources settings asset containing _adsJsonUrl | | Implement | Platform-specific app open/install implementation |

Minimum Setup By System

AdsManager

1. Add AdsManager to a loaded scene.
2. Add one or more concrete AdsControllerBase subclasses.
3. Assign those controllers to AdsManager._adsControllers in priority order.
4. Keep the array assigned and every entry non-null.
5. Call static ad APIs only after the manager has reached Start() if controller Init() work matters.

Example:

using XmobiTea.MiniAds;

bool shown = AdsManager.ShowRewardAds(success =>
{
    UnityEngine.Debug.Log("Reward result: " + success);
});

Deep links:

• AdsManager setup details
• AdsManager runtime usage
• AdsManager behavior details

MiniAds

1. Add MiniAds to a loaded scene.
2. Add GlobalCoroutine before using remote fetches or any icon download path.
3. Run XmobiTea Tools/Ads/Open Settings.
4. Set AdsSettings._adsJsonUrl to a JSON endpoint shaped like AdsJson.json.
5. Call MiniAds.Fetch(...) or MiniAds.ForceFetch(...) only after the singleton cache has been established.

Example:

using XmobiTea.MiniAds;

MiniAds.Fetch(items =>
{
    UnityEngine.Debug.Log("Fetched items: " + items.Count);
});

Deep links:

• MiniAds setup details
• MiniAds runtime usage
• MiniAds API details
• MiniAds behavior details

Dependencies

Declared in package.json:

• com.xmobitea.changx.app
• com.xmobitea.changx.mini-singleton
• com.xmobitea.changx.mini-global-coroutine
• com.xmobitea.changx.mini-helper
• com.xmobitea.changx.mini-storeprefs

Runtime code also imports Newtonsoft.Json.Linq in MiniAds.cs. Keep com.unity.nuget.newtonsoft-json installed in the host project because the current package manifest does not declare it.

License

Apache-2.0