Release 0.3.0: version, README (banners, native ads, impression data, segments, limitations, example app, Capacitor 7), CHANGELOG

This commit is contained in:
CRTkafa 2026-10-10 05:43:29 +08:00
parent 8dde08bcd9
commit 390bf03e63
3 changed files with 216 additions and 27 deletions

View file

@ -6,7 +6,12 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
## [Unreleased] ## [Unreleased]
### Added (API design for 0.3.0) ## [0.3.0] - 2026-10-10
Banners, native ads, impression-level revenue, segments, dynamic user id, placement capping and Capacitor 7 support.
Fully backwards compatible with 0.2.x.
### Added (API)
- `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`,
@ -16,7 +21,7 @@ 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) ### Added (Android)
- Banners in a pass-through overlay above the WebView: presets, `ADAPTIVE` (width in dp = CSS px, recreated on - 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 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. window insets, several banners by id, every `banner*` event.
@ -27,7 +32,7 @@ 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) ### Added (iOS)
- Banners in a pass-through overlay inside the WebView: presets, `ADAPTIVE` (width in pt = CSS px, recreated when the - 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 safe-area width changes), `CUSTOM` sizes, top / bottom / center with offsets, safe area, several banners by id, every
`banner*` event. `banner*` event.
@ -38,6 +43,19 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
`isPlacementCapped`, `getReward`; cleanup of banners and native ads when the plugin is released. `isPlacementCapped`, `getReward`; cleanup of banners and native ads when the plugin is released.
- `AdInfo` fields `ab`, `segmentName`, `encryptedCPM`, `creativeId`, `conversionValue`, `adSize` on iOS. - `AdInfo` fields `ab`, `segmentName`, `encryptedCPM`, `creativeId`, `conversionValue`, `adSize` on iOS.
### Added (tooling and docs)
- `bun run test`: `bun test` for the web stub (unimplemented rejections vs no-ops), `LEVELPLAY_DEMO` and the exports,
plus a compile-only check of the public API (`tsc -p test`); `verify` runs it.
- `example-app/`: a minimal Capacitor 8 app (HTML + TypeScript, esbuild) with the demo ids and buttons for every
format, segments and an impression log; Android and iOS (SPM) platforms committed. Not part of the npm package.
- README: banners, native ads (style options), impression data, segments / user id / placements, error codes,
limitations, example app, Capacitor 7.
### Changed
- Capacitor 7 support: `peerDependencies` `@capacitor/core >=7.0.0`; `Package.swift` depends on `capacitor-swift-pm`
`"7.0.0"..<"9.0.0"`; iOS deployment target 14.0 in `Package.swift` and the podspec (was 15.0); Android
`minSdkVersion` fallback 23 (was 24). Checked by building a Capacitor 7.6.9 app for Android and the iOS simulator.
## [0.2.1] - 2026-10-10 ## [0.2.1] - 2026-10-10
### Changed ### Changed
@ -79,7 +97,8 @@ First public release on npm. No behaviour changes to the native bridges since 0.
`closed` `rewarded`. Show calls resolve after close with `{ shown, rewarded, reward?, error? }`. `closed` `rewarded`. Show calls resolve after close with `{ shown, rewarded, reward?, error? }`.
- `LEVELPLAY_DEMO`: Unity's public demo app keys and ad unit ids. - `LEVELPLAY_DEMO`: Unity's public demo app keys and ad unit ids.
[Unreleased]: https://git.crt.fyi/CRT/capacitor-levelplay/compare/v0.2.1...main [Unreleased]: https://git.crt.fyi/CRT/capacitor-levelplay/compare/v0.3.0...main
[0.3.0]: https://git.crt.fyi/CRT/capacitor-levelplay/compare/v0.2.1...v0.3.0
[0.2.1]: https://git.crt.fyi/CRT/capacitor-levelplay/compare/v0.2.0...v0.2.1 [0.2.1]: https://git.crt.fyi/CRT/capacitor-levelplay/compare/v0.2.0...v0.2.1
[0.2.0]: https://git.crt.fyi/CRT/capacitor-levelplay/compare/v0.1.0...v0.2.0 [0.2.0]: https://git.crt.fyi/CRT/capacitor-levelplay/compare/v0.1.0...v0.2.0
[0.1.0]: https://git.crt.fyi/CRT/capacitor-levelplay/releases/tag/v0.1.0 [0.1.0]: https://git.crt.fyi/CRT/capacitor-levelplay/releases/tag/v0.1.0

207
README.md
View file

@ -2,12 +2,13 @@
[![npm version](https://img.shields.io/npm/v/capacitor-levelplay.svg)](https://www.npmjs.com/package/capacitor-levelplay) [![npm version](https://img.shields.io/npm/v/capacitor-levelplay.svg)](https://www.npmjs.com/package/capacitor-levelplay)
[![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE) [![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
[![Capacitor 8](https://img.shields.io/badge/Capacitor-8-119eff.svg)](https://capacitorjs.com) [![Capacitor 7 | 8](https://img.shields.io/badge/Capacitor-7%20%7C%208-119eff.svg)](https://capacitorjs.com)
[![LevelPlay SDK 9.6.1](https://img.shields.io/badge/LevelPlay%20SDK-9.6.1-222.svg)](https://docs.unity.com/en-us/grow/levelplay) [![LevelPlay SDK 9.6.1](https://img.shields.io/badge/LevelPlay%20SDK-9.6.1-222.svg)](https://docs.unity.com/en-us/grow/levelplay)
Capacitor 8 plugin for [Unity LevelPlay](https://docs.unity.com/en-us/grow/levelplay) (formerly ironSource) mediation: Capacitor 7 and 8 plugin for [Unity LevelPlay](https://docs.unity.com/en-us/grow/levelplay) (formerly ironSource)
**rewarded** and **interstitial** ads on Android and iOS, built on LevelPlay's current **ad-unit API** mediation: **rewarded**, **interstitial**, **banner** and **native** ads on Android and iOS, plus impression-level
(`LevelPlay.init`, `LevelPlayRewardedAd` / `LPMRewardedAd`, `LevelPlayInterstitialAd` / `LPMInterstitialAd`). revenue data, built on LevelPlay's current **ad-unit API** (`LevelPlay.init`, `LevelPlayRewardedAd` / `LPMRewardedAd`,
`LevelPlayInterstitialAd` / `LPMInterstitialAd`, `LevelPlayBannerAdView` / `LPMBannerAdView`, `LevelPlayNativeAd`).
```ts ```ts
import { LevelPlay } from 'capacitor-levelplay'; import { LevelPlay } from 'capacitor-levelplay';
@ -28,8 +29,10 @@ if (result.rewarded) grantCoins(result.reward!.amount);
- [Android setup](#android-setup) - [Android setup](#android-setup)
- [Quick start](#quick-start) - [Quick start](#quick-start)
- [Usage guide](#usage-guide) - [Usage guide](#usage-guide)
- [Example app](#example-app)
- [Mediation adapters](#mediation-adapters) - [Mediation adapters](#mediation-adapters)
- [Privacy and consent](#privacy-and-consent) - [Privacy and consent](#privacy-and-consent)
- [Limitations](#limitations)
- [Troubleshooting](#troubleshooting) - [Troubleshooting](#troubleshooting)
- [FAQ](#faq) - [FAQ](#faq)
- [API reference](#api) - [API reference](#api)
@ -52,26 +55,35 @@ if (result.rewarded) grantCoins(result.reward!.amount);
adapters during development. adapters during development.
- **Typed events** (`loaded`, `loadFailed`, `displayed`, `displayFailed`, `clicked`, `closed`, `rewarded`) with ad - **Typed events** (`loaded`, `loadFailed`, `displayed`, `displayFailed`, `clicked`, `closed`, `rewarded`) with ad
info including impression revenue. info including impression revenue.
- **Banners** (0.3.0): standard sizes, adaptive (follows the safe-area width and rotation), and custom sizes; placed at
the top, bottom or centre with offsets, inside the safe area, in a pass-through overlay above the WebView (touches
beside a banner reach the page). Several banners at once, addressed by `bannerId`.
- **Native ads** (0.3.0): the plugin's `small` and `medium` templates, styled from JS (colours, corner radius, fonts)
and placed over any rectangle of the page, typically a placeholder element's `getBoundingClientRect()`.
- **Impression-level revenue** (0.3.0): `impressionData` for rewarded, interstitial, banner and native ads, queued
(up to 100) until the first listener so early impressions are not lost; `adInfoChanged` for full-screen ads.
- **Segments, dynamic user id, placement capping and rewards** (0.3.0): `setSegment`, `setDynamicUserId`,
`isPlacementCapped`, `getReward`.
- **Capabilities** (0.3.0): `getCapabilities()` tells what the current platform supports.
- **Demo ids** (`LEVELPLAY_DEMO`) from Unity's public sample apps for test ads during development. - **Demo ids** (`LEVELPLAY_DEMO`) from Unity's public sample apps for test ads during development.
- Web stub: on the web nothing is ever ready and shows resolve `{ shown: false }`, so the same game code runs in a - Web stub: on the web nothing is ever ready and shows resolve `{ shown: false }`, so the same game code runs in a
browser. browser.
Banners and native ads are not supported.
## Compatibility ## Compatibility
| | Version | | | Version |
|---|---| |---|---|
| Capacitor | 8 (`@capacitor/core` >= 8.0.0) | | Capacitor | 7 and 8 (`@capacitor/core` >= 7.0.0) |
| Unity LevelPlay SDK | 9.6.1 (Android `com.unity3d.ads-mediation:mediation-sdk:9.6.1`; iOS `LevelPlay-Swift-Package` 9.6.1 up to < 10, or the `IronSourceSDK ~> 9.6.1` pod) | | Unity LevelPlay SDK | 9.6.1 (Android `com.unity3d.ads-mediation:mediation-sdk:9.6.1`; iOS `LevelPlay-Swift-Package` 9.6.1 up to < 10, or the `IronSourceSDK ~> 9.6.1` pod) |
| iOS | 15.0+ deployment target | | iOS | 14.0+ deployment target (Capacitor 7 default; Capacitor 8 apps use 15.0) |
| Xcode | 26+ (Capacitor 8 requirement); tested with Xcode 27 | | Xcode | 16+ for Capacitor 7, 26+ for Capacitor 8; tested with Xcode 27 (which needs an app target of iOS 15.0+) |
| Android | minSdk 24, compileSdk / targetSdk 36 (Capacitor 8 defaults, overridable from `variables.gradle`) | | Android | minSdk 23+, compileSdk / targetSdk 35 (Capacitor 7) or 36 (Capacitor 8), taken from the app's `variables.gradle` |
| Java | JDK 21 for Gradle builds | | Java | JDK 21 for Gradle builds |
| Node.js | 22+ (Capacitor 8 CLI) | | Node.js | 20+ (Capacitor 7 CLI), 22+ (Capacitor 8 CLI) |
| Plugin | Capacitor | LevelPlay SDK | | Plugin | Capacitor | LevelPlay SDK |
|---|---|---| |---|---|---|
| 0.3.x | 7, 8 | 9.6.1 |
| 0.2.x | 8 | 9.6.1 | | 0.2.x | 8 | 9.6.1 |
| 0.1.x | 8 | 9.6.1 | | 0.1.x | 8 | 9.6.1 |
@ -92,7 +104,7 @@ pnpm add capacitor-levelplay && pnpm cap sync
### Swift Package Manager (default) ### Swift Package Manager (default)
Capacitor 8 projects created with SPM need nothing extra: `npx cap sync` adds the plugin to `CapApp-SPM/Package.swift` Capacitor 8 projects (and Capacitor 7 projects created with `--packagemanager SPM`) need nothing extra: `npx cap sync` adds the plugin to `CapApp-SPM/Package.swift`
and Xcode resolves the LevelPlay package (a binary xcframework, roughly 27 MB) on the next build. and Xcode resolves the LevelPlay package (a binary xcframework, roughly 27 MB) on the next build.
### CocoaPods (alternative) ### CocoaPods (alternative)
@ -167,7 +179,7 @@ ext {
} }
``` ```
Gradle in Capacitor 8 projects needs **JDK 21** (see [Troubleshooting](#android-build-fails-with-unsupported-class-file-major-version)). Gradle in Capacitor 7 and 8 projects needs **JDK 21** (see [Troubleshooting](#android-build-fails-with-unsupported-class-file-major-version)).
## Quick start ## Quick start
@ -294,6 +306,128 @@ Every event carries `{ format: 'rewarded' | 'interstitial', adUnitId, adInfo? }`
`isReady({ format, adUnitId })` returns the native `isAdReady()` for that ad unit. It is `false` for an ad unit that was `isReady({ format, adUnitId })` returns the native `isAdReady()` for that ad unit. It is `false` for an ad unit that was
never loaded. Use it to enable or disable a "watch video" button. never loaded. Use it to enable or disable a "watch video" button.
### Banners
A banner is created hidden, then loaded and shown. `createBanner` resolves the banner's size and on-screen frame (CSS
px, relative to the WebView viewport), so the page can leave room for it.
```ts
const banner = await LevelPlay.createBanner({
adUnitId: ids.banner,
bannerId: 'main', // optional; defaults to adUnitId
size: 'ADAPTIVE', // BANNER 320x50, LARGE 320x90, MEDIUM_RECTANGLE 300x250, LEADERBOARD 728x90, ADAPTIVE, CUSTOM
position: 'bottom', // 'top' | 'bottom' | 'center'
offsetY: 0, // CSS px, away from the edge
respectSafeArea: true, // default: stays clear of notches, status bar, navigation bar and home indicator
});
document.body.style.paddingBottom = `${banner.frame.height}px`;
await LevelPlay.addListener('bannerLoaded', (e) => console.log('banner', e.bannerId, e.frame));
await LevelPlay.addListener('bannerLoadFailed', (e) => console.warn('banner failed', e.error.code));
await LevelPlay.loadBanner({ bannerId: 'main' }); // once per banner object; the SDK refreshes and retries by itself
await LevelPlay.showBanner({ bannerId: 'main' });
await LevelPlay.setBannerLayout({ bannerId: 'main', position: 'top' }); // move it
await LevelPlay.hideBanner({ bannerId: 'main' }); // hidden banners pause auto refresh
await LevelPlay.destroyBanner({ bannerId: 'main' });
```
- `ADAPTIVE` uses the safe-area width (or `adaptiveWidth` in CSS px) and is recreated and reloaded automatically when
that width changes, for example on rotation, keeping its id, position and visibility.
- `CUSTOM` takes `customSize: { width, height }` in CSS px.
- Banner events: `bannerLoaded`, `bannerLoadFailed`, `bannerDisplayed`, `bannerDisplayFailed`, `bannerClicked`,
`bannerExpanded`, `bannerCollapsed`, `bannerLeftApplication`, all with `{ bannerId, adUnitId, adInfo?, frame? }`.
| Top and bottom (Android) | Rotated, adaptive (Android) |
|---|---|
| ![Adaptive banners at the top and bottom](docs/images/android/banners-top-bottom.png) | ![Adaptive banner recreated after rotation](docs/images/android/banners-landscape-rotated.png) |
### Native ads
Native ads are drawn by the plugin's templates (`small`: a row at least 90 px tall, no media; `medium`: with a media
view, about 300 x 350) and placed over a
rectangle of the page, usually a placeholder element. Check `getCapabilities()` first.
```ts
const caps = await LevelPlay.getCapabilities();
if (caps.nativeAd && caps.nativeAdTemplates.includes('small')) {
const slot = document.getElementById('native-slot')!; // e.g. a 90 px tall div
await LevelPlay.addListener('nativeAdLoaded', async (e) => {
const r = slot.getBoundingClientRect();
await LevelPlay.showNativeAd({ nativeAdId: e.nativeAdId, rect: { x: r.left, y: r.top, width: r.width, height: r.height } });
});
await LevelPlay.addListener('nativeAdLoadFailed', (e) => console.warn('native failed', e.error.code));
await LevelPlay.loadNativeAd({
nativeAdId: 'feed-1',
template: 'small',
placementName: 'Feed', // optional
style: {
backgroundColor: '#ffffff',
titleColor: '#111111',
bodyColor: '#555555',
callToActionBackgroundColor: '#2f6fed',
callToActionTextColor: '#ffffff',
cornerRadius: 8,
titleFont: { family: 'fonts/Inter-SemiBold.ttf', size: 15 }, // a web asset path or a system family
bodyFont: { size: 13 },
callToActionFont: { family: 'Helvetica', size: 14 },
},
});
}
// keep it on the placeholder while the page scrolls or resizes
await LevelPlay.setNativeAdRect({ nativeAdId: 'feed-1', rect: { x: 16, y: 420, width: 343, height: 90 } });
await LevelPlay.hideNativeAd({ nativeAdId: 'feed-1' });
await LevelPlay.destroyNativeAd({ nativeAdId: 'feed-1' });
```
Style options (`NativeAdTemplateStyle`): `backgroundColor`, `titleColor`, `bodyColor`, `callToActionBackgroundColor`,
`callToActionTextColor` (`#RRGGBB` or `#RRGGBBAA`), `cornerRadius` (CSS px), and `titleFont`, `bodyFont`, `callToActionFont`
(`{ family?, size? }`; a `.ttf` / `.otf` path is read from the app's web assets, anything else is a system font family;
a missing font falls back to the system font). The template texts "Ad" and "Open" can be localised with the app
resources `levelplay_native_ad_badge` and `levelplay_native_ad_cta_fallback` (Android `strings.xml`, iOS
`Localizable.strings`).
Native events: `nativeAdLoaded`, `nativeAdLoadFailed`, `nativeAdImpression`, `nativeAdClicked`, all with
`{ nativeAdId, placementName?, adInfo? }`.
### Impression-level revenue
```ts
await LevelPlay.addListener('impressionData', (d) => {
// d.adFormat as the SDK reports it ('Rewarded Video', 'Interstitial', 'Banner', 'nativead' ...); d.revenue in USD
analytics.logAdImpression({ network: d.adNetwork, format: d.adFormat, revenue: d.revenue ?? 0, currency: 'USD' });
});
```
Impressions that happen before the first listener (for example a banner shown during app start) are queued, up to 100,
and delivered in order when the first `impressionData` listener is added. `d.allData` carries every raw field of the
SDK's impression object. `adInfoChanged` fires when the ad info of a loaded rewarded or interstitial ad changes.
### Segments, user id, placements
```ts
await LevelPlay.setSegment({ segmentName: 'whales', level: 12, isPaying: true, iapTotal: 49.99, customParameters: { cohort: 'b' } });
await LevelPlay.setDynamicUserId({ userId: 'player-123' }); // { valid } ; used for server-to-server rewards
const { capped } = await LevelPlay.isPlacementCapped({ format: 'rewarded', placementName: 'Shop' });
const reward = await LevelPlay.getReward({ adUnitId: ids.rewarded, placementName: 'Shop' }); // { name, amount }
await LevelPlay.showRewarded({ adUnitId: ids.rewarded, placementName: 'Shop' });
```
`setSegment` takes at most 5 custom parameters, keys and values 1-32 letters and digits (SDK limits); invalid input
rejects with `INVALID_ARGUMENT` instead of being dropped silently by the SDK.
### Error codes
Calls reject with a `code`: `INVALID_ARGUMENT`, `NOT_INITIALIZED` (banner / native before `initialize()`),
`ALREADY_EXISTS` (banner id in use), `NOT_FOUND` (unknown banner or native id), `NOT_LOADED` (`showNativeAd` before
`nativeAdLoaded`), `UNSUPPORTED`, `NO_ACTIVITY` (Android) / `NO_VIEW_CONTROLLER` (iOS), `UNIMPLEMENTED` (web).
`hideBanner` and the `destroy*` calls resolve for unknown ids. Ad load and show errors arrive in events as
`{ code, message }` with the SDK's code (509 is "no fill").
### Integration Test Suite ### Integration Test Suite
The [Integration Test Suite](https://docs.unity.com/en-us/grow/levelplay/sdk/android/integration-test-suite) shows every The [Integration Test Suite](https://docs.unity.com/en-us/grow/levelplay/sdk/android/integration-test-suite) shows every
@ -331,15 +465,26 @@ await LevelPlay.setMetaData({ key: 'is_deviceid_optout', value: 'true' });
([Mediation-Demo-Apps](https://github.com/ironsource-mobile/Mediation-Demo-Apps)). They serve test ads; never ship ([Mediation-Demo-Apps](https://github.com/ironsource-mobile/Mediation-Demo-Apps)). They serve test ads; never ship
them. them.
| Platform | App key | Rewarded | Interstitial | | Platform | App key | Rewarded | Interstitial | Banner |
|---|---|---|---| |---|---|---|---|---|
| Android | `25b63cf85` | `syz3d8ekts22q0or` | `h3xw38h9214adgxo` | | Android | `25b63cf85` | `syz3d8ekts22q0or` | `h3xw38h9214adgxo` | `4fpetq4lhe5lsw3e` |
| iOS | `8545d445` | `qwouvdrkuwivay5q` | `wmgt0712uuux8ju4` | | iOS | `8545d445` | `qwouvdrkuwivay5q` | `wmgt0712uuux8ju4` | `iep3rxsyp9na3rw8` |
The sample apps have no native ad unit; native ads load with the app key's default placement.
### Web ### Web
LevelPlay has no web SDK. On the web `initialize` and `launchTestSuite` reject as unimplemented, `isReady` is always LevelPlay has no web SDK. On the web `initialize` and `launchTestSuite` reject as unimplemented, `isReady` is always
`false` and shows resolve `{ shown: false, rewarded: false, error: { code: -1, ... } }`. `false` and shows resolve `{ shown: false, rewarded: false, error: { code: -1, ... } }`. `getCapabilities()` reports
nothing supported; `createBanner`, `showBanner`, `setBannerLayout`, `loadNativeAd` and `showNativeAd` reject as
unimplemented; `setSegment`, `loadBanner`, hide and destroy calls are no-ops; `setDynamicUserId` resolves
`{ valid: false }`, `isPlacementCapped` `{ capped: false }` and `getReward` `{ name: '', amount: 0 }`.
## Example app
[`example-app/`](example-app/) is a minimal Capacitor 8 app (HTML + TypeScript) that uses the plugin from this
repository with the demo ids: initialize, rewarded, interstitial, banner top / bottom / hide / destroy, native small /
medium, segment and an impression log. See its [README](example-app/README.md) for the steps.
## Mediation adapters ## Mediation adapters
@ -452,6 +597,21 @@ if (status === 'notDetermined') await LevelPlay.requestTrackingAuthorization();
await LevelPlay.initialize({ appKey }); await LevelPlay.initialize({ appKey });
``` ```
## Limitations
- **Native ads need per-network setup.** Only networks that serve native ads through LevelPlay fill them, and each
needs its adapter and a native ad configuration in the dashboard. The public demo app key has no native
configuration on Android (508 "No Native Ad configurations found"); on iOS it filled from ironSource Ads in testing.
- **Native ads use the plugin's templates.** Custom native layouts in HTML are not possible: the SDK requires its own
native views (and the network's privacy icon) to record impressions and clicks.
- **`loadBanner` is one-shot** per banner object (an SDK rule in 9.6.1): a second call is ignored and the SDK retries
on its refresh interval. To retry right away, `destroyBanner` + `createBanner` + `loadBanner`.
- **`-ObjC` is required on iOS**, also for the new APIs: without it `setSegment` crashes with an unrecognized selector.
- **No `adInfoChanged` for banners and native ads**: the SDK only reports it for rewarded and interstitial ads.
- **`lifetimeRevenue` is not typed** in `ImpressionData`; read it from `allData.lifetimeRevenue` when present.
- **Overlay ads**: banners and native ads are native views above the WebView, so CSS cannot clip, transform or
animate them; move them with `setBannerLayout` / `setNativeAdRect` and hide them under your own modals.
## Troubleshooting ## Troubleshooting
### Loads fail with 509 "No fill" ### Loads fail with 509 "No fill"
@ -504,16 +664,21 @@ legacy `IronSource.*` placement API is not used.
Yes. Every call takes an `adUnitId`, and the plugin keeps one native ad object per id. Yes. Every call takes an `adUnitId`, and the plugin keeps one native ad object per id.
**Does it support banners or native ads?** **Does it support banners or native ads?**
No. It focuses on full-screen formats. Yes, since 0.3.0: banners in every LevelPlay size (including adaptive and custom sizes) and native ads in two
templates. See [Banners](#banners) and [Native ads](#native-ads).
**Does it work with Capacitor 7?**
Yes, since 0.3.0 (`@capacitor/core` >= 7.0.0). Android and iOS (Swift Package Manager) builds were checked with a
Capacitor 7.6.9 app.
**How is this different from `capacitor-levelplay-ads`?** **How is this different from `capacitor-levelplay-ads`?**
Both are Capacitor 8 plugins for LevelPlay and both use the ad-unit API. The differences, as of `capacitor-levelplay-ads` Both are Capacitor plugins for LevelPlay and both use the ad-unit API. The differences, as of `capacitor-levelplay-ads`
0.1.42: 0.1.42:
| | `capacitor-levelplay` | `capacitor-levelplay-ads` | | | `capacitor-levelplay` | `capacitor-levelplay-ads` |
|---|---|---| |---|---|---|
| iOS integration | SPM first: `Package.swift` depends on `LevelPlay-Swift-Package`; podspec as alternative | CocoaPods first; its `Package.swift` does not depend on the SDK (SDK code is compiled out unless you add a package yourself) | | iOS integration | SPM first: `Package.swift` depends on `LevelPlay-Swift-Package`; podspec as alternative | CocoaPods first; its `Package.swift` does not depend on the SDK (SDK code is compiled out unless you add a package yourself) |
| Formats | rewarded, interstitial | banner, rewarded, interstitial | | Formats | rewarded, interstitial, banner, native (templates) | banner, rewarded, interstitial |
| Ad units | any number per format side by side, addressed by `adUnitId` | one ad object per format at a time | | Ad units | any number per format side by side, addressed by `adUnitId` | one ad object per format at a time |
| Show result | promise resolves after close with `{ shown, rewarded, reward }` | outcome via events | | Show result | promise resolves after close with `{ shown, rewarded, reward }` | outcome via events |
| Consent | GDPR / CCPA / COPPA flags; bring your own CMP | built-in consent flows (own consent modal, optional Usercentrics / InMobi CMP) | | Consent | GDPR / CCPA / COPPA flags; bring your own CMP | built-in consent flows (own consent modal, optional Usercentrics / InMobi CMP) |

View file

@ -1,7 +1,7 @@
{ {
"name": "capacitor-levelplay", "name": "capacitor-levelplay",
"version": "0.2.1", "version": "0.3.0",
"description": "Capacitor 8 plugin for Unity LevelPlay (ironSource) rewarded and interstitial ads on Android and iOS: ad-unit API, Swift Package Manager first, ATT and GDPR / CCPA / COPPA consent.", "description": "Capacitor 7 and 8 plugin for Unity LevelPlay (ironSource) ads on Android and iOS: rewarded, interstitial, banner and native ads, impression-level revenue, segments, ad-unit API, Swift Package Manager first, ATT and GDPR / CCPA / COPPA consent.",
"main": "dist/plugin.cjs.js", "main": "dist/plugin.cjs.js",
"module": "dist/esm/index.js", "module": "dist/esm/index.js",
"types": "dist/esm/index.d.ts", "types": "dist/esm/index.d.ts",
@ -29,6 +29,7 @@
"keywords": [ "keywords": [
"capacitor", "capacitor",
"capacitor-plugin", "capacitor-plugin",
"capacitor7",
"capacitor8", "capacitor8",
"plugin", "plugin",
"native", "native",
@ -42,6 +43,10 @@
"rewarded", "rewarded",
"rewarded-video", "rewarded-video",
"interstitial", "interstitial",
"banner",
"native-ads",
"impression-data",
"ilrd",
"ios", "ios",
"android", "android",
"swift-package-manager" "swift-package-manager"