docs: phase 3 iOS notes and simulator results; CHANGELOG for the iOS bridge
This commit is contained in:
parent
c6dd670f34
commit
cd4147f719
2 changed files with 73 additions and 7 deletions
13
CHANGELOG.md
13
CHANGELOG.md
|
|
@ -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
|
||||||
|
|
|
||||||
|
|
@ -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.
|
||||||
|
|
|
||||||
Loading…
Add table
Add a link
Reference in a new issue