Drop the explicit tsconfig lib (same defaults for target es2017) so @capacitor/docgen resolves Promise return types.
546 lines
14 KiB
TypeScript
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>;
|
|
}
|