@adapty/capacitor/dist/esm/ui-builder/onboarding-view-controller.d.ts

Official Adapty SDK for Capacitor

import type { Adapty } from '../adapty';
import type { AdaptyOnboarding } from '../shared/types';
import type { OnboardingEventHandlers, AdaptyIOSPresentationStyle } from './types';
/**
 * Controller for managing onboarding views.
 *
 * @remarks
 * This class provides methods to present, dismiss, and handle events for onboarding views
 * created with the Onboarding Builder. Create instances using the {@link createOnboardingView} function
 * rather than directly constructing this class.
 *
 * @public
 */
export declare class OnboardingViewController {
    private id;
    private adaptyPlugin;
    private viewEmitter;
    /**
     * Intended way to create a OnboardingViewController instance.
     * It prepares a native controller to be presented
     * and creates reference between native controller and JS instance
     * @internal
     */
    static create(onboarding: AdaptyOnboarding, adaptyPlugin: Adapty): Promise<OnboardingViewController>;
    /**
     * Since constructors in JS cannot be async, it is not
     * preferred to create ViewControllers in direct way.
     * Consider using @link{OnboardingViewController.create} instead
     *
     * @internal
     */
    private constructor();
    /**
     * Presents the onboarding view as a modal screen.
     *
     * @remarks
     * Calling `present` on an already visible onboarding view will result in an error.
     * The onboarding will be displayed with the configured presentation style on iOS.
     * On Android, the onboarding is always presented as a full-screen activity.
     *
     * @param options - Optional presentation options
     * @param options.iosPresentationStyle - iOS presentation style. Available options: `'full_screen'` (default) or `'page_sheet'`. Only affects iOS platform.
     * @returns A promise that resolves when the onboarding is presented.
     * @throws {@link AdaptyError} if the view reference is invalid or the view is already presented.
     *
     * @example
     * Present with default full-screen style
     * ```typescript
     * import { adapty, createOnboardingView } from '@adapty/capacitor';
     *
     * const onboarding = await adapty.getOnboarding({ placementId: 'YOUR_PLACEMENT_ID' });
     * const view = await createOnboardingView(onboarding);
     * await view.present();
     * ```
     *
     * @example
     * Present with page sheet style on iOS
     * ```typescript
     * await view.present({ iosPresentationStyle: 'page_sheet' });
     * ```
     */
    present(options?: {
        iosPresentationStyle?: AdaptyIOSPresentationStyle;
    }): Promise<void>;
    /**
     * Dismisses the onboarding view.
     *
     * @remarks
     * This method closes the onboarding and cleans up associated resources.
     * After dismissing, the view controller instance cannot be reused.
     *
     * @returns A promise that resolves when the onboarding is dismissed.
     * @throws {@link AdaptyError} if the view reference is invalid.
     *
     * @example
     * ```typescript
     * import { createOnboardingView } from '@adapty/capacitor';
     *
     * const view = await createOnboardingView(onboarding);
     * await view.present();
     * // ... later
     * await view.dismiss();
     * ```
     */
    dismiss(): Promise<void>;
    private onRequestClose;
    /**
     * Registers event handlers for onboarding UI events.
     *
     * @remarks
     * Each event type can have only one handler — new handlers replace existing ones.
     * Default handlers are registered automatically in {@link createOnboardingView} and provide standard closing behavior:
     * - `onClose` - closes the onboarding when the close button is pressed or system back is used
     *
     * If you want to override the `onClose` listener, we strongly recommend returning `true`
     * from your custom listener to retain default closing behavior.
     *
     * Calling this method multiple times will replace previously registered handlers for provided events.
     *
     * @see {@link https://adapty.io/docs/capacitor-handling-onboarding-events | Handling Onboarding Events}
     *
     * @param eventHandlers - Set of event handling callbacks. Only provided handlers will be registered or updated.
     * @returns A promise that resolves to an unsubscribe function that removes all registered listeners.
     *
     * @example
     * Register custom event handlers
     * ```typescript
     * import { createOnboardingView } from '@adapty/capacitor';
     *
     * const view = await createOnboardingView(onboarding);
     *
     * const unsubscribe = await view.setEventHandlers({
     *   onClose: () => {
     *     console.log('Onboarding closed');
     *     // Return true to keep default closing behavior
     *     return true;
     *   },
     *   onActionPerformed: (action) => {
     *     console.log('Action performed:', action.name);
     *   },
     *   onProductSelected: (product) => {
     *     console.log('Product selected:', product.vendorProductId);
     *   }
     * });
     *
     * await view.present();
     *
     * // Later, unsubscribe all handlers
     * unsubscribe();
     * ```
     */
    setEventHandlers(eventHandlers?: Partial<OnboardingEventHandlers>): Promise<() => void>;
    /**
     * Clears all registered event handlers.
     *
     * @remarks
     * This method removes all previously registered event handlers.
     * After calling this method, no event handlers will be active
     * until you call {@link setEventHandlers} again.
     *
     * Use this after dismiss to remove all event handlers.
     *
     * @example
     * ```typescript
     * const view = await createOnboardingView(onboarding);
     * await view.setEventHandlers({ onClose: handleClose });
     *
     * // Later, clear all handlers
     * view.clearEventHandlers();
     * ```
     */
    clearEventHandlers(): void;
}