klaviyo-react-native-sdk/lib/typescript/src/Forms.d.ts

Official Klaviyo React Native SDK

/**
 * Interface for the Klaviyo Forms API
 */
export interface KlaviyoFormsApi {
    /**
     * Load in-app forms data and display a form to the user if applicable based on the forms
     * configured in your Klaviyo account. Note [Klaviyo.initialize] must be called first
     * @param configuration Duration (in seconds) of the period of user inactivity after which
     * the user's app session is terminated and the forms session is ended. Defaults to 1 Hour.
     */
    registerForInAppForms(configuration?: FormConfiguration): void;
    /**
     * Unregisters app from receiving in-app forms.
     */
    unregisterFromInAppForms(): void;
    /**
     * Register a handler to receive form lifecycle events.
     * @param handler Function to be called when form lifecycle events occur
     * @returns A function to unsubscribe from lifecycle events
     */
    registerFormLifecycleHandler(handler: FormLifecycleHandler): () => void;
}
/**
 * Configuration for in-app forms
 */
export interface FormConfiguration {
    /**
     * Duration in seconds before the session times out
     */
    readonly sessionTimeoutDuration: number;
}
/**
 * String constants for form lifecycle event types.
 *
 * These values match the `type` discriminants emitted by the native bridge
 * and are safe to use when comparing {@link FormLifecycleEvent#type} or
 * building dispatch tables keyed by event type.
 */
export declare const FormLifecycleEventType: {
    /** Emitted when a form is shown to the user. */
    readonly Shown: "formShown";
    /** Emitted when the user dismisses a visible form. */
    readonly Dismissed: "formDismissed";
    /** Emitted when the user taps a CTA button with a configured deep link. */
    readonly CtaClicked: "formCtaClicked";
};
/** Union of valid {@link FormLifecycleEvent} type discriminants. */
export type FormLifecycleEventType = (typeof FormLifecycleEventType)[keyof typeof FormLifecycleEventType];
/**
 * Discriminated union representing a form lifecycle event.
 *
 * Each variant carries contextual data about the form, and the `type` field
 * serves as the discriminant. Use a `switch` on `event.type` to narrow the type
 * and access variant-specific fields like `buttonLabel` and `deepLinkUrl`.
 *
 * Example usage:
 * ```typescript
 * Klaviyo.registerFormLifecycleHandler((event) => {
 *   switch (event.type) {
 *     case FormLifecycleEventType.Shown:
 *       console.log(`Form shown: ${event.formId}`);
 *       break;
 *     case FormLifecycleEventType.Dismissed:
 *       console.log(`Form dismissed: ${event.formId}`);
 *       break;
 *     case FormLifecycleEventType.CtaClicked:
 *       console.log(`CTA clicked: ${event.buttonLabel}, deep link: ${event.deepLinkUrl}`);
 *       break;
 *   }
 * });
 * ```
 */
export type FormLifecycleEvent = 
/** Triggered when a form is shown to the user. Fired after the SDK has initiated form presentation. */
{
    type: typeof FormLifecycleEventType.Shown;
    formId: string;
    formName: string;
}
/**
 * Triggered when a form is dismissed by the user. Fired after the SDK has initiated form dismissal.
 * Fires for user-initiated dismissals (e.g. tapping outside, close button).
 * Does not fire when the SDK tears down the form internally (session timeouts, aborts).
 */
 | {
    type: typeof FormLifecycleEventType.Dismissed;
    formId: string;
    formName: string;
}
/**
 * Triggered when a user taps a call-to-action (CTA) button in a form that has a deep link URL configured.
 * Fired after the SDK has initiated deep link navigation.
 * Not emitted if no deep link URL is configured for the CTA.
 */
 | {
    type: typeof FormLifecycleEventType.CtaClicked;
    formId: string;
    formName: string;
    /**
     * Label of the tapped CTA button. May be an empty string when the
     * button has no visible label configured.
     */
    buttonLabel: string;
    /**
     * Deep link URL configured for the tapped CTA. Always present and
     * non-empty — this event is not emitted when no deep link is configured.
     */
    deepLinkUrl: string;
};
/**
 * Handler function type for form lifecycle events
 */
export type FormLifecycleHandler = (event: FormLifecycleEvent) => void;
/**
 * Parses a raw native event payload into a validated {@link FormLifecycleEvent}.
 *
 * Returns `null` and logs a warning if required fields are missing or empty.
 * Required fields vary by event type:
 * - All events: `type`, `formId`, `formName`
 * - `formCtaClicked`: additionally requires `deepLinkUrl`; `buttonLabel` defaults to empty string if absent
 *
 * @param data Raw event data from the native bridge
 * @returns A validated FormLifecycleEvent, or null if the payload is invalid
 */
export declare function parseFormLifecycleEvent(data: Record<string, unknown>): FormLifecycleEvent | null;
//# sourceMappingURL=Forms.d.ts.map