capacitor-levelplay/dist/esm/definitions.d.ts
CRT 9e3b1abb74 API docs: JSDoc with @since for every method, option, event and type
Drop the explicit tsconfig lib (same defaults for target es2017) so
@capacitor/docgen resolves Promise return types.
2026-10-10 02:16:06 +08:00

546 lines
14 KiB
TypeScript

import type { PluginListenerHandle } from '@capacitor/core';
/**
* Full-screen ad formats supported by this plugin. Banners and native ads are intentionally not exposed.
*
* @since 0.1.0
*/
export type AdFormat = 'rewarded' | 'interstitial';
/**
* Options for `initialize()`.
*
* @since 0.1.0
*/
export interface InitOptions {
/**
* LevelPlay app key from the LevelPlay dashboard. Android and iOS apps have different keys.
*
* @since 0.1.0
*/
appKey: string;
/**
* Optional user id. Needed for server-to-server reward callbacks and the Ad Quality user journey.
*
* @since 0.1.0
*/
userId?: string;
/**
* Enable the LevelPlay Integration Test Suite: sets the `is_test_suite=enable` meta data before init.
* Call `launchTestSuite()` after `initialize` resolves. Never ship this enabled.
*
* @default false
* @since 0.1.0
*/
testSuite?: boolean;
/**
* Turn on debug logs of the mediated ad network adapters (`LevelPlay.setAdaptersDebug(true)`). Development only.
*
* @default false
* @since 0.1.0
*/
adaptersDebug?: boolean;
/**
* Privacy signals applied right before init (LevelPlay recommends setting them before the SDK starts).
* Same as calling `setConsent()` first.
*
* @since 0.1.0
*/
consent?: ConsentOptions;
}
/**
* Result of `initialize()` and `getSdkVersion()`.
*
* @since 0.1.0
*/
export interface InitResult {
/**
* Native LevelPlay SDK version, for example `9.6.1`. `web` on the web.
*
* @since 0.1.0
*/
sdkVersion: string;
}
/**
* Privacy signals forwarded to LevelPlay (`LevelPlayPrivacySettings` on Android, `LPMPrivacySettings` on iOS).
* Omitted fields are left untouched.
*
* @since 0.1.0
*/
export interface ConsentOptions {
/**
* GDPR: `true` when the user consented to personalised ads and data processing, `false` when they did not.
* For users in the EEA, UK and Switzerland pass `false` until a consent management platform (CMP) says otherwise.
*
* @since 0.1.0
*/
gdprConsent?: boolean;
/**
* CCPA and other US state privacy laws: `true` when the user opted OUT of the sale or sharing of personal data
* ("do not sell"), `false` otherwise.
*
* @since 0.1.0
*/
ccpaDoNotSell?: boolean;
/**
* COPPA: `true` when the user must be treated as a child (child-directed treatment).
*
* @since 0.1.0
*/
coppa?: boolean;
}
/**
* Options for `setMetaData()`.
*
* @since 0.1.0
*/
export interface MetaDataOptions {
/**
* Meta data key, for example `is_deviceid_optout` or a network-specific flag from Unity's docs.
*
* @since 0.1.0
*/
key: string;
/**
* Meta data value, always a string (for example `"true"`).
*
* @since 0.1.0
*/
value: string;
}
/**
* Identifies one ad unit.
*
* @since 0.1.0
*/
export interface AdUnitOptions {
/**
* Ad unit id from the LevelPlay dashboard (Ad units page). Android and iOS ad units have different ids.
*
* @since 0.1.0
*/
adUnitId: string;
}
/**
* Options for `showRewarded()` and `showInterstitial()`: `adUnitId` (see AdUnitOptions) plus an optional placement.
*
* @since 0.1.0
*/
export interface ShowOptions extends AdUnitOptions {
/**
* Optional placement name configured in the LevelPlay dashboard (capping, pacing and reward per placement).
* Omit it to use the default placement.
*
* @since 0.1.0
*/
placementName?: string;
}
/**
* Options for `isReady()`: `adUnitId` (see AdUnitOptions) plus the format.
*
* @since 0.1.0
*/
export interface IsReadyOptions extends AdUnitOptions {
/**
* Format of the ad unit.
*
* @since 0.1.0
*/
format: AdFormat;
}
/**
* Result of `isReady()`.
*
* @since 0.1.0
*/
export interface IsReadyResult {
/**
* `true` when a loaded ad can be shown right now.
*
* @since 0.1.0
*/
ready: boolean;
}
/**
* The reward of a rewarded ad, as configured in the LevelPlay dashboard (per ad unit or placement).
*
* @since 0.1.0
*/
export interface Reward {
/**
* Name of the reward, for example `Coins`.
*
* @since 0.1.0
*/
name: string;
/**
* Amount of the reward.
*
* @since 0.1.0
*/
amount: number;
}
/**
* Error reported by the SDK (load / display failures) or by the plugin.
*
* @since 0.1.0
*/
export interface AdError {
/**
* LevelPlay error code, for example `509` (no fill). `-1` is used by the plugin for "Ad not ready" and for the web
* stub.
*
* @since 0.1.0
*/
code: number;
/**
* Human readable message.
*
* @since 0.1.0
*/
message: string;
}
/**
* Subset of the native `LevelPlayAdInfo` (Android) / `LPMAdInfo` (iOS) that is useful in JavaScript.
* Fields the SDK does not report are omitted.
*
* @since 0.1.0
*/
export interface AdInfo {
/**
* Unique id of this ad.
*
* @since 0.1.0
*/
adId?: string;
/**
* Ad unit id.
*
* @since 0.1.0
*/
adUnitId: string;
/**
* Ad unit name from the dashboard.
*
* @since 0.1.0
*/
adUnitName?: string;
/**
* Ad format as reported by the SDK.
*
* @since 0.1.0
*/
adFormat?: string;
/**
* Placement name of the show call, when one was used.
*
* @since 0.1.0
*/
placementName?: string;
/**
* Name of the mediated network that served the ad.
*
* @since 0.1.0
*/
adNetwork?: string;
/**
* Mediation instance name.
*
* @since 0.1.0
*/
instanceName?: string;
/**
* Mediation instance id.
*
* @since 0.1.0
*/
instanceId?: string;
/**
* Country code of the impression.
*
* @since 0.1.0
*/
country?: string;
/**
* Auction id.
*
* @since 0.1.0
*/
auctionId?: string;
/**
* Impression revenue in USD as reported by the SDK (may be absent or 0 before display).
*
* @since 0.1.0
*/
revenue?: number;
/**
* Revenue precision as reported by the SDK.
*
* @since 0.1.0
*/
precision?: string;
}
/**
* Result of `showRewarded()` and `showInterstitial()`, resolved after the ad
* closed or failed to display.
*
* @since 0.1.0
*/
export interface ShowResult {
/**
* The ad was displayed (the `displayed` event fired).
*
* @since 0.1.0
*/
shown: boolean;
/**
* Rewarded only: the reward callback fired for this show. Grant the reward only when this is `true`.
* Always `false` for interstitials.
*
* @since 0.1.0
*/
rewarded: boolean;
/**
* The reward, present when `rewarded` is `true`.
*
* @since 0.1.0
*/
reward?: Reward;
/**
* Present when the ad was not ready (`code: -1`) or failed to display.
*
* @since 0.1.0
*/
error?: AdError;
/**
* Info of the displayed ad.
*
* @since 0.1.0
*/
adInfo?: AdInfo;
}
/**
* Payload of the `loaded`, `displayed`, `clicked` and `closed` events.
*
* @since 0.1.0
*/
export interface AdEvent {
/**
* Format of the ad unit that fired the event.
*
* @since 0.1.0
*/
format: AdFormat;
/**
* Ad unit that fired the event.
*
* @since 0.1.0
*/
adUnitId: string;
/**
* Ad info, when the SDK provides it (not on `loadFailed`).
*
* @since 0.1.0
*/
adInfo?: AdInfo;
}
/**
* Payload of the `loadFailed` and `displayFailed` events: the AdEvent fields plus `error`.
*
* @since 0.1.0
*/
export interface AdErrorEvent extends AdEvent {
/**
* What went wrong.
*
* @since 0.1.0
*/
error: AdError;
}
/**
* Payload of the `rewarded` event: the AdEvent fields plus `reward`.
*
* @since 0.1.0
*/
export interface AdRewardEvent extends AdEvent {
/**
* The reward earned.
*
* @since 0.1.0
*/
reward: Reward;
}
/**
* iOS App Tracking Transparency status. `unavailable` on Android, on the web and on unknown future iOS values.
*
* @since 0.1.0
*/
export type TrackingStatus = 'authorized' | 'denied' | 'restricted' | 'notDetermined' | 'unavailable';
/**
* Result of `requestTrackingAuthorization()` and
* `getTrackingAuthorizationStatus()`.
*
* @since 0.1.0
*/
export interface TrackingResult {
/**
* iOS App Tracking Transparency status. Always `unavailable` on Android and web.
*
* @since 0.1.0
*/
status: TrackingStatus;
}
/**
* Event names emitted by the plugin.
*
* @since 0.1.0
*/
export type LevelPlayEventName = 'loaded' | 'loadFailed' | 'displayed' | 'displayFailed' | 'clicked' | 'closed' | 'rewarded';
/**
* Unity LevelPlay rewarded and interstitial ads (ad-unit API).
*
* @since 0.1.0
*/
export interface LevelPlayPlugin {
/**
* Initialise the LevelPlay SDK (`LevelPlay.init`). Resolves on init success, rejects with the init error
* (code and message from the SDK) otherwise. Calling it again after a successful init resolves immediately;
* concurrent calls share one init. Load ads only after this resolves.
*
* Set consent (and on iOS ask for ATT) before calling it.
*
* On the web it rejects as unimplemented.
*
* @since 0.1.0
*/
initialize(options: InitOptions): Promise<InitResult>;
/**
* Native LevelPlay SDK version. Works before init.
*
* @since 0.1.0
*/
getSdkVersion(): Promise<InitResult>;
/**
* Forward GDPR / CCPA / COPPA signals to LevelPlay. Call it before `initialize()` when you
* can, and again whenever the user changes their choice.
*
* @since 0.1.0
*/
setConsent(options: ConsentOptions): Promise<void>;
/**
* Raw `LevelPlay.setMetaData(key, value)` for SDK or network-specific flags. Call it before init.
*
* @since 0.1.0
*/
setMetaData(options: MetaDataOptions): Promise<void>;
/**
* iOS: show the App Tracking Transparency prompt and resolve with the resulting status. Needs
* `NSUserTrackingUsageDescription` in `Info.plist`. iOS only shows the prompt once; later calls resolve the stored
* status. Call it before `initialize()`, while the app is active.
*
* Android and web: resolves `unavailable`.
*
* @since 0.1.0
*/
requestTrackingAuthorization(): Promise<TrackingResult>;
/**
* Current App Tracking Transparency status without prompting (iOS). Android and web: `unavailable`.
*
* @since 0.1.0
*/
getTrackingAuthorizationStatus(): Promise<TrackingResult>;
/**
* Start loading a rewarded ad for the ad unit. The native ad object is created on first use and reused for the
* ad unit. Resolves once the request is issued; the outcome arrives as a `loaded` or `loadFailed` event.
* Load the next ad after each show.
*
* @since 0.1.0
*/
loadRewarded(options: AdUnitOptions): Promise<void>;
/**
* Show a loaded rewarded ad. Resolves after the ad closed (or failed to display) with what happened. The reward
* and close callbacks can arrive in either order on some networks, so the plugin waits up to 1 second after the close
* for a late reward. Never rejects for "not ready": resolves `{ shown: false, rewarded: false, error }` instead.
*
* @since 0.1.0
*/
showRewarded(options: ShowOptions): Promise<ShowResult>;
/**
* Start loading an interstitial ad for the ad unit. Works like `loadRewarded()`.
*
* @since 0.1.0
*/
loadInterstitial(options: AdUnitOptions): Promise<void>;
/**
* Show a loaded interstitial. Resolves after it closed (or failed to display). Never rejects for "not ready".
*
* @since 0.1.0
*/
showInterstitial(options: ShowOptions): Promise<ShowResult>;
/**
* `isAdReady()` of the native ad object for this ad unit. `false` when the ad unit was never loaded.
*
* @since 0.1.0
*/
isReady(options: IsReadyOptions): Promise<IsReadyResult>;
/**
* Open the LevelPlay Integration Test Suite. Requires `initialize({ testSuite: true })` first.
* Development builds only. Rejects on the web.
*
* @since 0.1.0
*/
launchTestSuite(): Promise<void>;
/**
* Write the LevelPlay integration helper report to the native log (Xcode console; Android logcat tag
* `IntegrationHelper`): SDK, adapter and network SDK versions, each `VERIFIED` or not. Development only.
*
* @since 0.1.0
*/
validateIntegration(): Promise<void>;
/**
* An ad finished loading for the ad unit and can be shown.
*
* @since 0.1.0
*/
addListener(eventName: 'loaded', listenerFunc: (event: AdEvent) => void): Promise<PluginListenerHandle>;
/**
* Loading failed, for example `509` (no fill). Retry later with a backoff.
*
* @since 0.1.0
*/
addListener(eventName: 'loadFailed', listenerFunc: (event: AdErrorEvent) => void): Promise<PluginListenerHandle>;
/**
* The ad was displayed (impression). `adInfo.revenue` is available here.
*
* @since 0.1.0
*/
addListener(eventName: 'displayed', listenerFunc: (event: AdEvent) => void): Promise<PluginListenerHandle>;
/**
* The ad failed to display. The pending show call resolves with the same error.
*
* @since 0.1.0
*/
addListener(eventName: 'displayFailed', listenerFunc: (event: AdErrorEvent) => void): Promise<PluginListenerHandle>;
/**
* The user clicked the ad.
*
* @since 0.1.0
*/
addListener(eventName: 'clicked', listenerFunc: (event: AdEvent) => void): Promise<PluginListenerHandle>;
/**
* The ad was closed and the app is back in front.
*
* @since 0.1.0
*/
addListener(eventName: 'closed', listenerFunc: (event: AdEvent) => void): Promise<PluginListenerHandle>;
/**
* Rewarded only: the user earned the reward. Can fire before or after `closed`.
*
* @since 0.1.0
*/
addListener(eventName: 'rewarded', listenerFunc: (event: AdRewardEvent) => void): Promise<PluginListenerHandle>;
/**
* Remove every listener of this plugin.
*
* @since 0.1.0
*/
removeAllListeners(): Promise<void>;
}