TypeScript API: typed LevelPlay definitions, web stub, demo ids

This commit is contained in:
CRTkafa 2026-10-09 23:02:07 +08:00
parent 06f8096623
commit ca046c01bd
4 changed files with 295 additions and 0 deletions

189
src/definitions.ts Normal file
View file

@ -0,0 +1,189 @@
import type { PluginListenerHandle } from '@capacitor/core';
/** Full-screen ad formats supported by this plugin. Banners and native ads are intentionally not exposed. */
export type AdFormat = 'rewarded' | 'interstitial';
export interface InitOptions {
/** LevelPlay app key from the LevelPlay dashboard (one per platform). */
appKey: string;
/** Optional user id, needed for server-to-server reward callbacks and the Ad Quality user journey. */
userId?: string;
/**
* Enable the LevelPlay Integration Test Suite (sets the `is_test_suite=enable` meta data before init).
* Call {@link LevelPlayPlugin.launchTestSuite} after init resolves. Never ship this enabled.
*/
testSuite?: boolean;
/** Turn on mediated ad network debug logs (`setAdaptersDebug`). Development only. */
adaptersDebug?: boolean;
/**
* Privacy flags applied right before init (LevelPlay recommends setting them before the SDK starts).
* Same as calling {@link LevelPlayPlugin.setConsent} first.
*/
consent?: ConsentOptions;
}
export interface InitResult {
/** Native LevelPlay SDK version, for example `9.6.1`. */
sdkVersion: string;
}
/**
* Privacy signals forwarded to LevelPlay (`LevelPlayPrivacySettings` on Android, `LPMPrivacySettings` on iOS).
* Omitted fields are left untouched.
*/
export interface ConsentOptions {
/** GDPR: `true` when the user consented to personalised ads / data processing. */
gdprConsent?: boolean;
/** CCPA / US state privacy: `true` when the user opted OUT of the sale or sharing of personal data. */
ccpaDoNotSell?: boolean;
/** COPPA: `true` when the user must be treated as a child (child-directed treatment). */
coppa?: boolean;
}
export interface MetaDataOptions {
key: string;
value: string;
}
export interface AdUnitOptions {
/** Ad unit id from the LevelPlay dashboard. */
adUnitId: string;
}
export interface ShowOptions extends AdUnitOptions {
/** Optional placement name configured in the LevelPlay dashboard (capping / pacing / reward per placement). */
placementName?: string;
}
export interface IsReadyOptions extends AdUnitOptions {
format: AdFormat;
}
export interface IsReadyResult {
ready: boolean;
}
export interface Reward {
name: string;
amount: number;
}
export interface AdError {
code: number;
message: string;
}
/** Subset of the native `LevelPlayAdInfo` / `LPMAdInfo` that is useful in JavaScript. */
export interface AdInfo {
adId?: string;
adUnitId: string;
adUnitName?: string;
adFormat?: string;
placementName?: string;
adNetwork?: string;
instanceName?: string;
instanceId?: string;
country?: string;
auctionId?: string;
/** Impression revenue in USD as reported by the SDK (may be absent before display). */
revenue?: number;
precision?: string;
}
export interface ShowResult {
/** The ad was displayed (`displayed` fired). */
shown: boolean;
/** Rewarded only: the reward callback fired for this show. Grant the reward only when this is true. */
rewarded: boolean;
reward?: Reward;
/** Present when the ad was not ready or failed to display. */
error?: AdError;
adInfo?: AdInfo;
}
export interface AdEvent {
format: AdFormat;
adUnitId: string;
adInfo?: AdInfo;
}
export interface AdErrorEvent extends AdEvent {
error: AdError;
}
export interface AdRewardEvent extends AdEvent {
reward: Reward;
}
export type TrackingStatus = 'authorized' | 'denied' | 'restricted' | 'notDetermined' | 'unavailable';
export interface TrackingResult {
/** iOS App Tracking Transparency status. Always `unavailable` on Android and web. */
status: TrackingStatus;
}
export interface LevelPlayPlugin {
/**
* Initialise the LevelPlay SDK. Resolves on `onInitSuccess`, rejects with the init error otherwise.
* Calling it again after a successful init resolves immediately. Load ads only after this resolves.
*/
initialize(options: InitOptions): Promise<InitResult>;
/** Native SDK version (available before init). */
getSdkVersion(): Promise<InitResult>;
/** Forward GDPR / CCPA / COPPA signals. Call before {@link initialize} when you can. */
setConsent(options: ConsentOptions): Promise<void>;
/** Raw `LevelPlay.setMetaData(key, value)` for network-specific flags. Call before init. */
setMetaData(options: MetaDataOptions): Promise<void>;
/**
* iOS: show the App Tracking Transparency prompt (needs `NSUserTrackingUsageDescription` in Info.plist) and resolve
* with the resulting status. Call it before {@link initialize}. Android / web: resolves `unavailable`.
*/
requestTrackingAuthorization(): Promise<TrackingResult>;
/** Current ATT status without prompting (iOS). Android / web: `unavailable`. */
getTrackingAuthorizationStatus(): Promise<TrackingResult>;
/**
* Start loading a rewarded ad for the ad unit (the ad object is created on first use and reused).
* Resolves once the request is issued; the outcome arrives as `loaded` / `loadFailed` events.
*/
loadRewarded(options: AdUnitOptions): Promise<void>;
/**
* Show a loaded rewarded ad. Resolves after the ad closes (or failed to display) with what happened.
* Never rejects for "not ready": resolves `{ shown: false, error }` instead.
*/
showRewarded(options: ShowOptions): Promise<ShowResult>;
/** Start loading an interstitial ad (see {@link loadRewarded}). */
loadInterstitial(options: AdUnitOptions): Promise<void>;
/** Show a loaded interstitial. Resolves after it closes (or failed to display). */
showInterstitial(options: ShowOptions): Promise<ShowResult>;
/** `isAdReady()` of the ad object for this ad unit (`false` when it was never loaded). */
isReady(options: IsReadyOptions): Promise<IsReadyResult>;
/** Open the LevelPlay Integration Test Suite. Requires `initialize({ testSuite: true })` first. */
launchTestSuite(): Promise<void>;
/** Log the LevelPlay integration helper report to the native console (development only). */
validateIntegration(): Promise<void>;
addListener(eventName: 'loaded', listenerFunc: (event: AdEvent) => void): Promise<PluginListenerHandle>;
addListener(eventName: 'loadFailed', listenerFunc: (event: AdErrorEvent) => void): Promise<PluginListenerHandle>;
addListener(eventName: 'displayed', listenerFunc: (event: AdEvent) => void): Promise<PluginListenerHandle>;
addListener(eventName: 'displayFailed', listenerFunc: (event: AdErrorEvent) => void): Promise<PluginListenerHandle>;
addListener(eventName: 'clicked', listenerFunc: (event: AdEvent) => void): Promise<PluginListenerHandle>;
addListener(eventName: 'closed', listenerFunc: (event: AdEvent) => void): Promise<PluginListenerHandle>;
addListener(eventName: 'rewarded', listenerFunc: (event: AdRewardEvent) => void): Promise<PluginListenerHandle>;
removeAllListeners(): Promise<void>;
}
/** Event names emitted by the plugin. */
export type LevelPlayEventName = 'loaded' | 'loadFailed' | 'displayed' | 'displayFailed' | 'clicked' | 'closed' | 'rewarded';

18
src/demo.ts Normal file
View file

@ -0,0 +1,18 @@
/**
* Public demo app keys and ad unit ids from Unity's official LevelPlay sample apps
* (https://github.com/ironsource-mobile/Mediation-Demo-Apps: `Android/Kotlin/.../DemoActivity.kt` and
* `iOS/Swift SPM/LevelPlayDemo/DemoViewController.swift`). They serve test ads and are safe for development only.
* Replace them with your own ids from the LevelPlay dashboard before release.
*/
export const LEVELPLAY_DEMO = {
android: {
appKey: '25b63cf85',
rewarded: 'syz3d8ekts22q0or',
interstitial: 'h3xw38h9214adgxo',
},
ios: {
appKey: '8545d445',
rewarded: 'qwouvdrkuwivay5q',
interstitial: 'wmgt0712uuux8ju4',
},
} as const;

11
src/index.ts Normal file
View file

@ -0,0 +1,11 @@
import { registerPlugin } from '@capacitor/core';
import type { LevelPlayPlugin } from './definitions';
const LevelPlay = registerPlugin<LevelPlayPlugin>('LevelPlay', {
web: () => import('./web').then((m) => new m.LevelPlayWeb()),
});
export * from './definitions';
export { LEVELPLAY_DEMO } from './demo';
export { LevelPlay };

77
src/web.ts Normal file
View file

@ -0,0 +1,77 @@
import { WebPlugin } from '@capacitor/core';
import type {
AdUnitOptions,
ConsentOptions,
InitOptions,
InitResult,
IsReadyResult,
LevelPlayPlugin,
MetaDataOptions,
ShowResult,
TrackingResult,
} from './definitions';
/**
* Web stub. LevelPlay has no web SDK: init rejects with `unimplemented`, ads are never ready and every show resolves
* as "not shown" so callers can treat the web like a no-fill platform without special casing.
*/
export class LevelPlayWeb extends WebPlugin implements LevelPlayPlugin {
private static readonly NO_FILL: ShowResult = {
shown: false,
rewarded: false,
error: { code: -1, message: 'LevelPlay is not available on the web' },
};
async initialize(_options: InitOptions): Promise<InitResult> {
throw this.unimplemented('LevelPlay is not available on the web.');
}
async getSdkVersion(): Promise<InitResult> {
return { sdkVersion: 'web' };
}
async setConsent(_options: ConsentOptions): Promise<void> {
/* nothing to forward */
}
async setMetaData(_options: MetaDataOptions): Promise<void> {
/* nothing to forward */
}
async requestTrackingAuthorization(): Promise<TrackingResult> {
return { status: 'unavailable' };
}
async getTrackingAuthorizationStatus(): Promise<TrackingResult> {
return { status: 'unavailable' };
}
async loadRewarded(_options: AdUnitOptions): Promise<void> {
/* never fills */
}
async showRewarded(_options: AdUnitOptions): Promise<ShowResult> {
return { ...LevelPlayWeb.NO_FILL };
}
async loadInterstitial(_options: AdUnitOptions): Promise<void> {
/* never fills */
}
async showInterstitial(_options: AdUnitOptions): Promise<ShowResult> {
return { ...LevelPlayWeb.NO_FILL };
}
async isReady(): Promise<IsReadyResult> {
return { ready: false };
}
async launchTestSuite(): Promise<void> {
throw this.unimplemented('LevelPlay is not available on the web.');
}
async validateIntegration(): Promise<void> {
/* nothing to validate */
}
}