docs: phase 2 Android notes and emulator results; CHANGELOG for the Android bridge

This commit is contained in:
CRTkafa 2026-10-10 04:31:07 +08:00
parent 213b17b5c6
commit 4bd01013c2
2 changed files with 63 additions and 3 deletions

View file

@ -16,6 +16,17 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
- `AdInfo` gains optional `ab`, `segmentName`, `encryptedCPM`, `creativeId`, `conversionValue` (iOS) and `adSize`. - `AdInfo` gains optional `ab`, `segmentName`, `encryptedCPM`, `creativeId`, `conversionValue` (iOS) and `adSize`.
- Web stubs for every new method. - Web stubs for every new method.
### Added (Android bridge for 0.3.0)
- Banners in a pass-through overlay above the WebView: presets, `ADAPTIVE` (width in dp = CSS px, recreated on
rotation), `CUSTOM` sizes, top / bottom / center with offsets, safe area from the WebView's on-screen rect and the
window insets, several banners by id, every `banner*` event.
- Native ads with the plugin's `small` and `medium` templates (colours, corner radius, fonts) and `nativeAd*` events.
- `impressionData` from per-ad listeners, queued (max 100) until the first JS listener; `adInfoChanged`;
`getCapabilities`, `setSegment`, `setDynamicUserId`, `isPlacementCapped`, `getReward`.
- `AdInfo` fields `ab`, `segmentName`, `encryptedCPM`, `creativeId`, `adSize` on Android.
- JVM unit tests for the overlay geometry and argument validation (`bun run verify:android`).
- `BannerSize` `CUSTOM` with `customSize`, `NativeAdTemplateStyle` fonts, banner ids in `LEVELPLAY_DEMO`.
## [0.2.1] - 2026-10-10 ## [0.2.1] - 2026-10-10
### Changed ### Changed

View file

@ -98,7 +98,9 @@ explicitly makes that deterministic on both platforms.
Adaptive width units: the plugin passes CSS px. On Android 1 CSS px = 1 dp in a Capacitor WebView at default zoom, Adaptive width units: the plugin passes CSS px. On Android 1 CSS px = 1 dp in a Capacitor WebView at default zoom,
and the `Integer` width **is dp** (§14 Q3): in the bytecode, `createAdaptiveAdSize` (`com.ironsource.g1.a`) compares and the `Integer` width **is dp** (§14 Q3): in the bytecode, `createAdaptiveAdSize` (`com.ironsource.g1.a`) compares
the width with the preset widths (320 / 728) and, for a `null` or negative width, falls back to the width with the preset widths (320 / 728) and, for a `null` or negative width, falls back to
`DisplayMetrics.widthPixels / density` rounded (`com.ironsource.e5`), i.e. the screen width in dp. On iOS 1 CSS px = 1 pt. `DisplayMetrics.widthPixels / density` rounded (`com.ironsource.e5`), i.e. the screen width in dp. Checked on the emulator (Pixel 9 Pro, density 3): an
`ADAPTIVE` banner for 426 CSS px reports `adSize` 426 x 50 and its `LevelPlayBannerAdView` measures 1278 x 150 px.
On iOS 1 CSS px = 1 pt.
Both factories need a finished init (iOS returns `nil` before init, documented in LPMAdSize.h), so `createBanner` Both factories need a finished init (iOS returns `nil` before init, documented in LPMAdSize.h), so `createBanner`
rejects `NOT_INITIALIZED` before `initialize()` resolved. Unity's docs also say to create banners only after init rejects `NOT_INITIALIZED` before `initialize()` resolved. Unity's docs also say to create banners only after init
succeeded. succeeded.
@ -216,7 +218,9 @@ asset views from the getters, call the `set*View` setters (Android) / assign the
`IMPRESSION_DATA_KEY_*` constants (auctionId, adFormat, mediationAdUnitName, mediationAdUnitId, country, ab, `IMPRESSION_DATA_KEY_*` constants (auctionId, adFormat, mediationAdUnitName, mediationAdUnitId, country, ab,
segmentName, placement, adNetwork, instanceName, instanceId, revenue, precision, encryptedCPM, creativeId), and the segmentName, placement, adNetwork, instanceName, instanceId, revenue, precision, encryptedCPM, creativeId), and the
string does not occur in the iOS binary. Apps that need lifetime revenue sum `revenue` themselves. If the server string does not occur in the iOS binary. Apps that need lifetime revenue sum `revenue` themselves. If the server
sends it anyway it shows up in `allData`. sends it anyway it shows up in `allData`. Observed in phase 2 (Android, demo app key): the server does send
`allData.lifetimeRevenue` (per ad unit, cumulative in the session), so it is readable there; it stays out of the
typed fields because the SDK classes do not promise it.
### 5.2 Registration ### 5.2 Registration
@ -449,7 +453,7 @@ iOS 15 / 18 / 26, phone and tablet, portrait and landscape:
used. used.
- **Q2 Retain impressions. Decided:** yes, with a plugin-owned queue capped at 100 impressions (oldest dropped), - **Q2 Retain impressions. Decided:** yes, with a plugin-owned queue capped at 100 impressions (oldest dropped),
flushed in order on the first `addListener('impressionData')`. See §5.2. flushed in order on the first `addListener('impressionData')`. See §5.2.
- **Q3 Android adaptive width unit. Decided / verified:** dp, from the SDK bytecode (§3.2); checked on the emulator in phase 2. - **Q3 Android adaptive width unit. Decided / verified:** dp, from the SDK bytecode (§3.2); confirmed on the emulator (view measured 3 px per CSS px at density 3).
CSS px are passed through unchanged. CSS px are passed through unchanged.
- **Q4 Adaptive banners and rotation. Decided:** automatic. Adaptive banners without a fixed `adaptiveWidth` are - **Q4 Adaptive banners and rotation. Decided:** automatic. Adaptive banners without a fixed `adaptiveWidth` are
recreated and reloaded on a safe-area width change, keeping position, offsets, visibility and id. See §6.4. recreated and reloaded on a safe-area width change, keeping position, offsets, visibility and id. See §6.4.
@ -461,3 +465,48 @@ iOS 15 / 18 / 26, phone and tablet, portrait and landscape:
until then the native code only uses APIs present in both Capacitor 7 and 8 (Android: `Plugin.addListener`, until then the native code only uses APIs present in both Capacitor 7 and 8 (Android: `Plugin.addListener`,
`notifyListeners`, `hasListeners`, `handleOnDestroy`, `handleOnConfigurationChanged`, `bridge.getWebView()`, all `notifyListeners`, `hasListeners`, `handleOnDestroy`, `handleOnConfigurationChanged`, `bridge.getWebView()`, all
identical in 7.6.9 and 8.5.3). identical in 7.6.9 and 8.5.3).
## 15. Phase 2 notes (Android implementation)
Files (`android/src/main/java/fyi/crt/capacitor/levelplay/`): `LevelPlayPlugin` (bridge, impression queue, lifecycle),
`OverlayHost` (§6.2), `BannerManager` (§3), `NativeAdManager` + `NativeAdTemplate` + `NativeAdStyle` (§4),
`Mappers` (SDK objects to JSON), `OverlayMath` (pure geometry and validation, JVM unit tests in `android/src/test`),
`CallError` (reject codes). `res/values/strings.xml` holds the two template texts (`levelplay_native_ad_badge` "Ad",
`levelplay_native_ad_cta_fallback` "Open"), overridable by the app's own resources.
Implementation details that the sections above leave open:
- Every bridge call hops to the main thread; SDK listeners re-post to it. Unexpected runtime exceptions reject with
code `ERROR`.
- `createBanner` validates its arguments first (`INVALID_ARGUMENT`), then `NOT_INITIALIZED`, `ALREADY_EXISTS`,
`NO_ACTIVITY` (also when the WebView has no parent view yet).
- Overlay children are positioned with FrameLayout margins from the WebView's offset in the host
(`getLocationInWindow` of both), so the host simply fills the WebView's parent. Relayouts are posted, never run
inside a layout pass.
- A hidden banner is `View.GONE` + `pauseAutoRefresh()`; `showBanner` is `VISIBLE` + `bringToFront()` +
`resumeAutoRefresh()`.
- Banner and native listeners are per view / per ad object; callbacks from a replaced (rotation) or destroyed
object are dropped.
- A native ad template consumes touches inside its bounds (taps between asset views do not reach the page).
- Native template font files are read with `Typeface.createFromAsset(assets, "public/" + path)` and cached; a missing
file logs a warning (tag `LevelPlay`) and uses the system font.
Emulator results (Pixel 9 Pro AVD, API 36, Capacitor 8.5.3 test app, Unity demo app key + Unity Ads adapter 5.14 /
Unity Ads 4.21 in the app):
- Seen: init, `getCapabilities`, `setSegment` (valid, and `INVALID_ARGUMENT` for 6 pairs, a `-` in a key and a
non-integer level), `setDynamicUserId` (`valid: true`), `isPlacementCapped`, `getReward` (`Virtual Item` x 1);
adaptive / preset / `MEDIUM_RECTANGLE` / `CUSTOM` banners at top / bottom / center with offsets; hide / show /
destroy (view visibility checked with `dumpsys activity top`); `ALREADY_EXISTS`, `NOT_FOUND`; touches beside a
banner reach the page; safe area with Capacitor's default insets handling and with `insetsHandling: 'disable'`
(edge to edge: top banner at y 52 = status bar, bottom banner ends 24 px above the WebView bottom = navigation
bar; `respectSafeArea: false` gives y 0); rotation recreates a width-following adaptive banner (426 x 50 to
900 x 50, reloaded); rewarded load / show / reward / close; queued `impressionData` (banner, rewarded) flushed on
the first listener; native ad error paths (`UNSUPPORTED`, `INVALID_ARGUMENT`, `NOT_LOADED`, `NOT_FOUND`,
`nativeAdLoadFailed` 508).
- Not seen with the public demo ids: a filled native ad (the demo app key has no native configuration: 508 "No Native
Ad configurations found"), so `nativeAdLoaded` / `nativeAdImpression` / `nativeAdClicked` and the synthesised
native `impressionData` are untested; the templates were rendered with sample assets through
`NativeAdTemplate.create` / `fill` instead. `adInfoChanged` never fired. An interstitial show (it loaded, then
Unity Ads timed out on the overloaded emulator, later loads had no fill). `segmentName` stayed empty in `adInfo`
(no segments on the demo dashboard). Banner click / expand / collapse / left-application events.