docs: phase 3 iOS notes and simulator results; CHANGELOG for the iOS bridge

This commit is contained in:
CRTkafa 2026-10-10 05:29:59 +08:00
parent c6dd670f34
commit cd4147f719
2 changed files with 73 additions and 7 deletions

View file

@ -6,7 +6,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
## [Unreleased] ## [Unreleased]
### Added (API design for 0.3.0; Android and iOS bridges not implemented yet) ### Added (API design for 0.3.0)
- `docs/design-0.3.md`: banner, native ad, impression data, placement, segment and dynamic user id design with the - `docs/design-0.3.md`: banner, native ad, impression data, placement, segment and dynamic user id design with the
exact LevelPlay 9.6.1 Android / iOS mappings, overlay positioning, error codes, Capacitor 7 findings, test plan. exact LevelPlay 9.6.1 Android / iOS mappings, overlay positioning, error codes, Capacitor 7 findings, test plan.
- TypeScript API (`@since 0.3.0`): `getCapabilities`, `setSegment`, `setDynamicUserId`, `isPlacementCapped`, - TypeScript API (`@since 0.3.0`): `getCapabilities`, `setSegment`, `setDynamicUserId`, `isPlacementCapped`,
@ -27,6 +27,17 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
- JVM unit tests for the overlay geometry and argument validation (`bun run verify: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`. - `BannerSize` `CUSTOM` with `customSize`, `NativeAdTemplateStyle` fonts, banner ids in `LEVELPLAY_DEMO`.
### Added (iOS bridge for 0.3.0)
- Banners in a pass-through overlay inside the WebView: presets, `ADAPTIVE` (width in pt = CSS px, recreated when the
safe-area width changes), `CUSTOM` sizes, top / bottom / center with offsets, safe area, several banners by id, every
`banner*` event.
- Native ads with the plugin's `small` and `medium` templates built in code (`ISNativeAdView` binding; colours, corner
radius, system or web-asset fonts) and `nativeAd*` events.
- `impressionData` from per-ad delegates (with `conversionValue`), queued (max 100) until the first JS listener;
native impressions synthesised; `adInfoChanged`; `getCapabilities`, `setSegment`, `setDynamicUserId`,
`isPlacementCapped`, `getReward`; cleanup of banners and native ads when the plugin is released.
- `AdInfo` fields `ab`, `segmentName`, `encryptedCPM`, `creativeId`, `conversionValue`, `adSize` on iOS.
## [0.2.1] - 2026-10-10 ## [0.2.1] - 2026-10-10
### Changed ### Changed

View file

@ -1,8 +1,7 @@
# capacitor-levelplay 0.3.0 · API design # capacitor-levelplay 0.3.0 · API design
Status: phase 2. `src/definitions.ts` and `src/web.ts` carry the new API; the Android bridge implements all of it Status: phase 3. `src/definitions.ts` and `src/web.ts` carry the new API; the Android bridge (phase 2, §15) and the
(phase 2). The iOS bridge is not implemented yet (phase 3); until it is, calling a new method on iOS rejects with iOS bridge (phase 3, §16) implement all of it. The owner's answers to the open questions are recorded in §14.
Capacitor's `UNIMPLEMENTED`. The owner's answers to the open questions are recorded in §14.
Scope (owner approved): banners, native ads (template overlay), impression-level revenue, `adInfoChanged`, placement Scope (owner approved): banners, native ads (template overlay), impression-level revenue, `adInfoChanged`, placement
capping and reward lookup, segments, dynamic user id, full backwards compatibility with 0.2.x, and a Capacitor 7 capping and reward lookup, segments, dynamic user id, full backwards compatibility with 0.2.x, and a Capacitor 7
@ -258,9 +257,12 @@ non-scrolled page). Capacitor WebViews render at 1 CSS px = 1 dp (Android, defau
It is kept equal to the WebView's bounds with an `OnLayoutChangeListener` on the WebView. The host is not clickable It is kept equal to the WebView's bounds with an `OnLayoutChangeListener` on the WebView. The host is not clickable
and has no touch listener, so touches outside ad views fall through to the WebView below (Android dispatches to and has no touch listener, so touches outside ad views fall through to the WebView below (Android dispatches to
siblings in reverse z-order until one consumes). Ad views inside it consume their own touches. siblings in reverse z-order until one consumes). Ad views inside it consume their own touches.
- **iOS**: a plugin-owned `UIView` subclass added to `bridge.viewController.view` above `bridge.webView`, frame and - **iOS**: a plugin-owned `UIView` subclass added to `bridge.viewController.view` above the WebView's content, frame
`autoresizingMask` following the WebView. Its `hitTest(_:with:)` returns `nil` when the hit view is itself, so only and `autoresizingMask` following the WebView. In Capacitor `CAPBridgeViewController.loadView` sets
ad subviews receive touches. `view = webView`, so that view *is* the `WKWebView`: the overlay is its last subview, above `WKScrollView`, and does
not scroll. (The WebView's superview belongs to UIKit / the presentation and a full-screen modal can reinsert the
WebView above a sibling there, so it is not used.) Its `hitTest(_:with:)` returns `nil` when the hit view is
itself, so only ad subviews receive touches.
- Full-screen ads (rewarded / interstitial / expanded banners / test suite) are presented as Activities / modal view - Full-screen ads (rewarded / interstitial / expanded banners / test suite) are presented as Activities / modal view
controllers and therefore always cover the overlay. controllers and therefore always cover the overlay.
@ -516,3 +518,56 @@ Unity Ads 4.21 in the app):
The emulator ran on an overloaded host (load average 30-40): system apps and the test app showed ANR dialogs The emulator ran on an overloaded host (load average 30-40): system apps and the test app showed ANR dialogs
around SDK init and Unity full-screen ads; the overlay was idle at those times (no frames rendered while idle, around SDK init and Unity full-screen ads; the overlay was idle at those times (no frames rendered while idle,
app CPU 2 %). app CPU 2 %).
## 16. Phase 3 notes (iOS implementation)
Files (`ios/Sources/LevelPlayPlugin/`): `LevelPlayPlugin.swift` (bridge, holders, impression queue, overlay,
cleanup), `OverlayHost.swift` (§6.2), `BannerManager.swift` (§3), `NativeAdManager.swift` + `NativeAdTemplate.swift` +
`NativeAdStyle.swift` (§4), `Mappers.swift` (SDK objects to JSON), `OverlayMath.swift` (pure geometry and validation,
same rules as Android), `CallError.swift` (reject codes and typed option reads).
Swift names the SDK actually imports as (the ObjC importer renames several of the §3 / §4 names):
`LPMAdSize.banner()`, `.large()`, `.mediumRectangle()`, `.leaderBoard()`, `.customSize(withWidth:height:)`,
`.createAdaptiveAdSize(withWidth:)`, `.createAdaptive()`; `LPMBannerAdView.loadAd(with:)`;
`LevelPlayNativeAd.load()` / `.destroy()`; `LevelPlayNativeAdBuilder.build()` returns an optional. Delegate methods are
declared with explicit `@objc(selector)` names so the optional callbacks are found whatever their Swift spelling.
Behaviour matches the Android bridge (same validation order, messages, codes and payloads) except:
- `NO_VIEW_CONTROLLER` instead of `NO_ACTIVITY`.
- `loadBanner` passes `bridge.viewController` to `loadAdWithViewController:`; the native builder gets it via
`withViewController:`.
- Booleans and numbers are told apart (`CFBoolean`), so `isPaying: 1` or `offsetX: true` reject as on Android.
- `setSegment` custom parameters are applied in key order (JS object order is not kept by the bridge).
- Native template fonts: a `.ttf` / `.otf` path is resolved against `bridge.config.appLocation` (the app's `public`
folder), registered once per process with `CTFontManagerRegisterFontsForURL` (`.process`) and used by PostScript
name; a system family is looked up by name, then by family. Missing fonts log a warning (subsystem
`fyi.crt.capacitor.levelplay`) and use the system font. Template texts `levelplay_native_ad_badge` ("Ad") and
`levelplay_native_ad_cta_fallback` ("Open") come from the app's `Localizable.strings` when present.
- The overlay logs each banner's frame (and every `showBanner`) and each shown native ad's frame at `notice` level
(subsystem `fyi.crt.capacitor.levelplay`, category `LevelPlay`).
- Cleanup runs in the plugin's `deinit` (Capacitor iOS has no `handleOnDestroy`); managers are created on first use
so `deinit` never builds them.
- The app needs the `-ObjC` linker flag (already a README requirement): without it `LevelPlay.setSegment` crashes with
`+[ISSegment createFrom:]: unrecognized selector`, a category of the static SDK binary.
Simulator results (iPhone 17 simulator, iOS 26, Capacitor 8.5.2 Swift package, Unity demo app key, no extra
adapters, ironSource Ads filled):
- Seen: `getCapabilities`; `setSegment` valid and `INVALID_ARGUMENT` for 6 pairs, a `-` in a key and level 1.5;
`NOT_INITIALIZED` for `createBanner` before init; init; `setDynamicUserId` (`valid: true`); `isPlacementCapped`
(and `INVALID_ARGUMENT` for format `banner`); `getReward` (`Virtual Item` x 1); adaptive banner at the bottom:
`adSize` 402 x 50, frame `0,790 402x50` in a `402x874` WebView whose safe area is `0,62 402x778` (ends 34 pt above
the bottom = home indicator); `ALREADY_EXISTS`, `NOT_FOUND`, `INVALID_ARGUMENT` for size `HUGE`;
`bannerLoadFailed` 509 then `bannerLoaded` / `bannerDisplayed` on the SDK's retry; rewarded load / show /
`displayed` / `rewarded`; `impressionData` for banner, native and rewarded queued before the first listener and
flushed in order when it was added (`allData.lifetimeRevenue` present as on Android; `conversionValue` was `nil` in
`LPMImpressionData` and `0` in `ISAdInfo` / `LPMAdInfo` with the demo key); native ad error paths (`UNSUPPORTED`,
`NOT_LOADED`); a **filled** native ad (unlike Android's demo key): `nativeAdLoaded`, `showNativeAd` in the small
template at `20,460 300x90` (icon 48 x 48, title "Demo App", "Ad" badge, body, CTA "INSTALL" 79 x 36 on the right,
the network's privacy "i" at the bottom-left corner `0,69 21x21`), `nativeAdImpression` and the synthesised
`impressionData` (`adFormat: 'nativead'`). The native `ISAdInfo` fields were all empty strings with the demo key.
The medium template and a missing-advertiser / long-text case were checked with sample assets (view hierarchy
logged: title truncated, media view filling the rest, CTA right-aligned, web-asset font applied).
- Not seen: interstitial, close of the rewarded ad, rotation (adaptive recreation), `setBannerLayout`, banner
click / expand / collapse / left-application, `nativeAdClicked`, `adInfoChanged`, Capacitor 7. Compiled only.