README and changelog for 0.1.0

This commit is contained in:
CRTkafa 2026-10-09 23:02:07 +08:00
parent f960ee3d3b
commit 700c2e4719
2 changed files with 181 additions and 0 deletions

11
CHANGELOG.md Normal file
View file

@ -0,0 +1,11 @@
# Changelog
## 0.1.0 (2026-10-09)
- First release: Capacitor 8 plugin for Unity LevelPlay rewarded and interstitial ads (ad-unit API).
- iOS: Swift Package Manager with the official LevelPlay-Swift-Package (SDK 9.6.1); podspec on `IronSourceSDK ~> 9.6.1`.
- Android: `com.unity3d.ads-mediation:mediation-sdk:9.6.1` from Maven Central, Play services ids, consumer ProGuard rules.
- API: `initialize`, `setConsent` (GDPR / CCPA / COPPA), `setMetaData`, iOS ATT, load / show / isReady per ad unit,
`launchTestSuite`, `validateIntegration`, events `loaded` `loadFailed` `displayed` `displayFailed` `clicked`
`closed` `rewarded`. Show calls resolve after close with `{ shown, rewarded, reward?, error? }`.
- `LEVELPLAY_DEMO`: Unity's public demo app keys and ad unit ids.

170
README.md Normal file
View file

@ -0,0 +1,170 @@
# capacitor-levelplay
Capacitor 8 plugin for [Unity LevelPlay](https://docs.unity.com/en-us/grow/levelplay) (formerly ironSource) mediation:
**rewarded** and **interstitial** ads on Android and iOS, using LevelPlay's current ad-unit API
(`LevelPlay.init`, `LevelPlayRewardedAd` / `LPMRewardedAd`, `LevelPlayInterstitialAd` / `LPMInterstitialAd`).
No banners, no native ads.
| | |
|---|---|
| Capacitor | 8 |
| LevelPlay SDK | Android `com.unity3d.ads-mediation:mediation-sdk:9.6.1` (Maven Central) · iOS `9.6.1` via the official [LevelPlay-Swift-Package](https://github.com/ironsource-mobile/LevelPlay-Swift-Package) (`IronSourceSDK` pod for CocoaPods) |
| iOS | 15+, Swift Package Manager first (the plugin's `Package.swift` really pulls the SDK); a podspec is included for CocoaPods projects |
| Android | minSdk 24, Java 21 |
Why another LevelPlay plugin: the existing `capacitor-levelplay-ads` package targets CocoaPods first and its
`Package.swift` does not depend on the LevelPlay SDK; this one is SPM-first, pulls the SDK under SPM, and exposes only
the ad-unit API.
## Install
```sh
npm install capacitor-levelplay # or: bun add capacitor-levelplay
npx cap sync
```
### iOS setup
1. **`-ObjC` linker flag** (required by LevelPlay): App target > Build Settings > *Other Linker Flags* > add `-ObjC`.
2. **Info.plist**:
```xml
<!-- ironSource / LevelPlay SKAdNetwork id. Add the ids of every mediated network you enable
(https://docs.unity.com/en-us/grow/levelplay/sdk/ios/skadnetwork-id-manager). -->
<key>SKAdNetworkItems</key>
<array>
<dict>
<key>SKAdNetworkIdentifier</key>
<string>su67r6k2v3.skadnetwork</string>
</dict>
</array>
<!-- Shown by the App Tracking Transparency prompt (requestTrackingAuthorization). -->
<key>NSUserTrackingUsageDescription</key>
<string>Your data will be used to deliver ads that are more relevant to you.</string>
<!-- Optional, recommended: copies of SKAN install-validation postbacks. -->
<key>NSAdvertisingAttributionReportEndpoint</key>
<string>https://postbacks-is.com/</string>
<!-- LevelPlay's integration guide asks for arbitrary loads (some ad creatives are served over http). -->
<key>NSAppTransportSecurity</key>
<dict>
<key>NSAllowsArbitraryLoads</key>
<true/>
</dict>
```
With SPM, `npx cap sync` adds the plugin to `CapApp-SPM/Package.swift`; Xcode resolves the LevelPlay package
(binary xcframework, about 27 MB download) on the next build.
### Android setup
Nothing beyond `npx cap sync`: the plugin module declares `mediation-sdk` (Maven Central) plus the Play services
`ads-identifier`, `appset` and `basement` artifacts, and the SDK's manifest brings its activities, providers and the
`INTERNET` / `ACCESS_NETWORK_STATE` permissions. The plugin adds `com.google.android.gms.permission.AD_ID`
(remove it with `tools:node="remove"` in a child-directed app).
Optional overrides in the app's `android/variables.gradle`:
```gradle
ext {
levelPlayVersion = '9.6.1'
}
```
Mediation adapters (Unity Ads, AdMob, AppLovin, ...) go into the app module, e.g.
`implementation 'com.unity3d.ads-mediation:unityads-adapter:5.+'`; see Unity's
[mediation networks](https://docs.unity.com/en-us/grow/levelplay/sdk/android/mediation-networks) page.
If you minify, the core keep rules ship as consumer ProGuard rules; add the per-network rules yourself.
## Usage
```ts
import { LevelPlay, LEVELPLAY_DEMO } from 'capacitor-levelplay';
import { Capacitor } from '@capacitor/core';
const ids = Capacitor.getPlatform() === 'ios' ? LEVELPLAY_DEMO.ios : LEVELPLAY_DEMO.android;
await LevelPlay.requestTrackingAuthorization(); // iOS ATT prompt; no-op elsewhere
await LevelPlay.setConsent({ gdprConsent: true, ccpaDoNotSell: false }); // from your CMP
await LevelPlay.initialize({ appKey: ids.appKey });
await LevelPlay.addListener('loaded', (e) => console.log('loaded', e.format, e.adUnitId));
await LevelPlay.loadRewarded({ adUnitId: ids.rewarded });
// later, when the user taps "watch video":
const { ready } = await LevelPlay.isReady({ format: 'rewarded', adUnitId: ids.rewarded });
if (ready) {
const r = await LevelPlay.showRewarded({ adUnitId: ids.rewarded });
if (r.rewarded) grantReward(r.reward);
await LevelPlay.loadRewarded({ adUnitId: ids.rewarded }); // preload the next one
}
```
`showRewarded` / `showInterstitial` resolve **after the ad closes** (or failed to display) with
`{ shown, rewarded, reward?, error?, adInfo? }`. They never reject because an ad is not ready; they resolve
`{ shown: false, error: { code: -1, message: 'Ad not ready' } }`. Reward and close callbacks can arrive in either order
on some networks; the plugin waits up to 1 s after the close for a late reward before resolving. Grant rewards only
when `rewarded` is `true` (or on the `rewarded` event).
### Demo ids
`LEVELPLAY_DEMO` holds the public app keys and ad unit ids from Unity's official sample apps
([Mediation-Demo-Apps](https://github.com/ironsource-mobile/Mediation-Demo-Apps)). They serve test ads; never ship
them.
| platform | app key | rewarded | interstitial |
|---|---|---|---|
| Android | `25b63cf85` | `syz3d8ekts22q0or` | `h3xw38h9214adgxo` |
| iOS | `8545d445` | `qwouvdrkuwivay5q` | `wmgt0712uuux8ju4` |
### Integration Test Suite
```ts
await LevelPlay.initialize({ appKey, testSuite: true }); // sets is_test_suite=enable before init
await LevelPlay.launchTestSuite();
```
Development builds only. The suite is portrait only.
### Privacy
`setConsent({ gdprConsent?, ccpaDoNotSell?, coppa? })` maps to `LevelPlayPrivacySettings` (Android) /
`LPMPrivacySettings` (iOS): `setGDPRConsent`, `setCCPA`, `setCOPPA` (SDK 9.5+ APIs). Call it before `initialize`
(or pass `consent` to `initialize`). LevelPlay also reads a Google UMP / IAB TCF CMP's consent string by itself.
Raw meta data flags (for example `is_deviceid_optout`) go through `setMetaData({ key, value })`.
## API
| method | description |
|---|---|
| `initialize({ appKey, userId?, testSuite?, adaptersDebug?, consent? })` | `LevelPlay.init`; resolves `{ sdkVersion }` on success, rejects with the init error. Idempotent. |
| `getSdkVersion()` | `{ sdkVersion }` |
| `setConsent({ gdprConsent?, ccpaDoNotSell?, coppa? })` | privacy signals |
| `setMetaData({ key, value })` | `LevelPlay.setMetaData` |
| `requestTrackingAuthorization()` / `getTrackingAuthorizationStatus()` | iOS ATT, `{ status }`; `unavailable` on Android / web |
| `loadRewarded({ adUnitId })` / `loadInterstitial({ adUnitId })` | start a load; outcome via `loaded` / `loadFailed` |
| `showRewarded({ adUnitId, placementName? })` / `showInterstitial(...)` | show; resolves after close with the result |
| `isReady({ format, adUnitId })` | `{ ready }` |
| `launchTestSuite()` | LevelPlay Integration Test Suite |
| `validateIntegration()` | integration helper report in the native log |
Events (`addListener`): `loaded`, `loadFailed`, `displayed`, `displayFailed`, `clicked`, `closed`, `rewarded`.
Every event carries `{ format: 'rewarded' | 'interstitial', adUnitId, adInfo? }`, plus `error` (failures) or `reward`.
Full types with JSDoc: [`src/definitions.ts`](src/definitions.ts).
On the web the plugin is a stub: `initialize` rejects as unimplemented, nothing is ever ready and shows resolve
`{ shown: false }`.
## Development
```sh
bun install
bun run build # dist/ (esm + cjs + iife)
bun run verify:ios # xcodebuild the Swift package
```
`dist/` is committed so the package can be installed straight from git.
## License
MIT (see [LICENSE](LICENSE)). The Unity LevelPlay SDK itself is proprietary and governed by Unity's terms; this
plugin only declares it as a dependency and does not redistribute it.