README and changelog for 0.1.0
This commit is contained in:
parent
f960ee3d3b
commit
700c2e4719
2 changed files with 181 additions and 0 deletions
11
CHANGELOG.md
Normal file
11
CHANGELOG.md
Normal 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
170
README.md
Normal 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.
|
||||||
Loading…
Add table
Add a link
Reference in a new issue