Release 0.3.0: version, README (banners, native ads, impression data, segments, limitations, example app, Capacitor 7), CHANGELOG
This commit is contained in:
parent
8dde08bcd9
commit
390bf03e63
3 changed files with 216 additions and 27 deletions
27
CHANGELOG.md
27
CHANGELOG.md
|
|
@ -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
207
README.md
|
|
@ -2,12 +2,13 @@
|
||||||
|
|
||||||
[](https://www.npmjs.com/package/capacitor-levelplay)
|
[](https://www.npmjs.com/package/capacitor-levelplay)
|
||||||
[](LICENSE)
|
[](LICENSE)
|
||||||
[](https://capacitorjs.com)
|
[](https://capacitorjs.com)
|
||||||
[](https://docs.unity.com/en-us/grow/levelplay)
|
[](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) |
|
||||||
|
|---|---|
|
||||||
|
|  |  |
|
||||||
|
|
||||||
|
### 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) |
|
||||||
|
|
|
||||||
|
|
@ -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"
|
||||||
|
|
|
||||||
Loading…
Add table
Add a link
Reference in a new issue