docs: phase 2 Android notes and emulator results; CHANGELOG for the Android bridge
This commit is contained in:
parent
213b17b5c6
commit
4bd01013c2
2 changed files with 63 additions and 3 deletions
11
CHANGELOG.md
11
CHANGELOG.md
|
|
@ -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
|
||||||
|
|
|
||||||
|
|
@ -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.
|
||||||
|
|
|
||||||
Loading…
Add table
Add a link
Reference in a new issue