@easy-smart-app-banner/core/dist/index.d.ts

An Easy Smart App Banner for promoting mobile app installs based on the Safari Apple Experience. Includes support for Safari too.

/**
 * @event Triggered when the user clicks the call to action button (aka. "View" button by default)
 */
declare class ClickedCallToAction extends SmartAppBannerEvent {
    static readonly type = "clicked-call-to-action";
}

/**
 * Default options
 * Options which are required are omitted for brevity.
 */
export declare const DEFAULT_OPTIONS: Required<Omit<ParsedSmartBannerOptions, 'title' | 'author'>>;

/**
 * @event Triggered once the smart app banner is destroyed.
 */
declare class DestroyedEvent extends SmartAppBannerEvent {
    static readonly type = "destroyed";
}

declare namespace events {
    export {
        SmartAppBannerEvents,
        SmartAppBannerEvent,
        ReadyEvent,
        DestroyedEvent,
        ClickedCallToAction,
        ToggledVisibility
    }
}
export { events }

export declare const OPTION_PARSERS: OptionParsers<SmartBannerOptions, ParsedSmartBannerOptions>;

/**
 * Declaration of option parsers, used by {@link geTParser}
 * Maps the provided options to their default.
 */
declare type OptionParsers<T, U extends T = T> = {
    [option in keyof Required<T>]: (val: T[option], opts: {
        defaultValue: U[option];
        rawOptions: T;
    }) => U[option];
};

declare type ParsedPlatform = 'android' | 'ios' | 'safari';

/**
 * Parsed Smart App Banner options
 */
export declare type ParsedSmartBannerOptions = {
    title: string;
    author: string;
    icon: string | null;
    platforms: SupportedPlatForm[];
    price: string | null;
    buttonLabel: string;
    verbose: boolean;
    dismissPath: string;
    googlePlayStoreUrl: URL | null;
    androidButtonLabel: string | null;
    androidIcon: string | null;
    androidPrice: string;
    appStoreUrl: URL | null;
    appleButtonLabel: string | null;
    appleIcon: string | null;
    applePrice: string;
};

/**
 * @event Triggered once the smart app banner is ready.
 */
declare class ReadyEvent extends SmartAppBannerEvent {
    static readonly type = "ready";
}

export declare class SmartAppBanner extends TypedEventTarget<SmartAppBannerEvents> {
    readonly options: ParsedSmartBannerOptions;
    /**
     * If the platform is undefined, then it is not a supported platform.
     * eg. a desktop environment (as this is intended for mobile)
     */
    readonly platform: ParsedPlatform | undefined;
    readonly bannerId = "smart-app-banner";
    private __bannerElement;
    constructor(options: SmartBannerOptions);
    mount(): void;
    destroy(): void;
    /**
     * Toggles the banner visibility programmatically.
     * This still respects the platform visibility!
     *
     * @param visible
     */
    setBannerVisibility(visible: boolean): void;
    onClickClose(event: Event): void;
    onClickCallToAction(event: Event): void;
    removeEventListeners(): void;
    get title(): string | undefined;
    get author(): string | undefined;
    get price(): string | undefined;
    get icon(): string | undefined;
    get buttonUrl(): URL | undefined;
    get buttonLabel(): string | undefined;
    get html(): string;
}

/**
 * Base class for all events dispatched by {@link SmartAppBanner}
 */
declare abstract class SmartAppBannerEvent extends TypedEvent<SmartAppBanner> {
}

/**
 * A list of all the events the component can emit.
 */
declare type SmartAppBannerEvents = ReadyEvent | DestroyedEvent | ClickedCallToAction | ToggledVisibility;

export declare type SmartBannerOptions = {
    title: string;
    author: string;
    /**
     * The main asset to show. This should is expected to be a URL that resolves an image.
     * This can be overriden on a per-platform basis as needed.
     */
    icon?: string;
    /**
     * Enabled platforms. If a platform is enabled here it must be configured.
     *
     * @see https://developer.apple.com/documentation/webkit/promoting-apps-with-smart-app-banners
     * @default ['android', 'ios']
     */
    platforms?: SupportedPlatForm[];
    /**
     * The price tagline of the app, this can be any string you prefer.
     * This can be overriden on a per-platform basis as needed. If not provided, then the platform
     * specific options will be preferred.
     *
     * @default undefined (prefer platform specific by default)
     */
    price?: string;
    /**
     * View button label. This can be overriden on a per-platform basis as needed.
     * @default View
     */
    buttonLabel?: string;
    /**
     * Enable verbose logging. Disabled by default.
     *
     * @default false
     */
    verbose?: boolean;
    /**
     * The path to hide the banner on once its dismissed. This allows conditionally rendering the banner
     * on specific paths.
     *
     * SPA's should set '/' to apply hide/show the banner as expected (default behaviour)
     *
     * @default /
     */
    dismissPath?: string;
    /**
     * The Google Play Store URL.
     *
     * @example https://play-store-application-url
     */
    googlePlayStoreUrl?: string;
    /**
     * Android specific button label. If not specified, falls back to buttonLabel.
     */
    androidButtonLabel?: string;
    /**
     * Android specific icon. This should is expected to be a URL that resolves an image.
     */
    androidIcon?: string;
    /**
     * Android specific price tagline.
     * @default GET - On the Google Play Store
     */
    androidPrice?: string;
    /**
     * The Apple app store URL.
     * @example https://app-store-application-url
     */
    appStoreUrl?: string;
    /**
     * Apple specific button label. If not specified, falls back to buttonLabel.
     */
    appleButtonLabel?: string;
    /**
     * Apple specific icon. This should is expected to be a URL that resolves an image.
     */
    appleIcon?: string;
    /**
     * Apple specific price tagline.
     * @default GET - On the App Store
     */
    applePrice?: string;
};

declare type SupportedPlatForm = 'android' | 'ios';

/**
 * @event Triggered when the user clicks the dismiss button or programmatically toggles visiblity, provide an event.
 */
declare class ToggledVisibility extends SmartAppBannerEvent {
    static readonly type = "toggled-visibility";
}

/**
 * Base class for events dispatched by {@link TypedEventTarget}
 * @template TTarget type of the event target
 */
declare abstract class TypedEvent<TTarget extends TypedEventTarget<any>> extends Event {
    static readonly type: string;
    target: TTarget;
    constructor(type: string, cancelable?: boolean);
}

/**
 * Decorator for EventTarget allowing to strongly type events and listeners
 * @see https://rjzaworski.com/2021/06/event-target-with-typescript
 * @template TEvents union of dispatched events
 */
declare class TypedEventTarget<TEvents extends TypedEvent<any>> extends EventTarget {
    dispatchEvent(e: TEvents): boolean;
    /**
     * @template T the name of event
     * @template E the class of the event
     */
    addEventListener<T extends TEvents['type'], E extends TEvents & {
        type: T;
    }>(type: T, callback: ((e: E) => void) | EventListenerObject | null, options?: AddEventListenerOptions | boolean): void;
    /**
     * @template T the name of event
     * @template E the class of the event
     */
    removeEventListener<T extends TEvents['type'], E extends TEvents & {
        type: T;
    }>(type: TEvents['type'], callback: ((e: E) => void) | EventListenerObject | null, options?: EventListenerOptions | boolean): void;
}

export { }