Page & Lifecycle Events

These events handle page initialization, checkout lifecycle, configuration, and navigation.

page:loaded

Dispatched by store when the page is loaded and the SDK is ready to use. Use this to run initialization logic.

Example

import type { NubeSDK } from "@tiendanube/nube-sdk-types";

export function App(nube: NubeSDK) {
  nube.on("page:loaded", (state) => {
    console.log("SDK ready", state.store?.name);
  });
}

checkout:ready

Dispatched by checkout every time a new checkout page is loaded and ready to use. This includes page transitions such as going from the start to the payment step, or from shipping to the success page.

Example

import type { NubeSDK } from "@tiendanube/nube-sdk-types";

export function App(nube: NubeSDK) {
  nube.on("checkout:ready", ({ location }) => {
    // Trigger logic every time the user navigates to a new checkout page
    const { page } = location;
    // You can inspect the current page using:
    console.log("Current page:", page);

    // Example: Only run logic on the success page
    if (page.type === "checkout" && page.data.step === "success") {
      // Your custom behavior here
    }
  });
}

For more details about the state.location object, see the Location state page .

checkout:success

Dispatched by checkout when the checkout completes successfully (success page). Use this for conversion tracking or post-purchase logic.

Example

import type { NubeSDK } from "@tiendanube/nube-sdk-types";

export function App(nube: NubeSDK) {
  nube.on("checkout:success", (state) => {
    console.log("Checkout completed", state.order);
  });
}

config:set

Dispatched by app to setup initial script configuration.

Example

import type { NubeSDK } from "@tiendanube/nube-sdk-types";

export function App(nube: NubeSDK) {
  nube.send("config:set", () => ({
    config: {
      has_cart_validation: true,
    },
  }));
}

Payload (AppConfig)

Property	Type	Required	Description
has_cart_validation	boolean	Yes	Enables cart validation feature.
disable_shipping_more_options	boolean	Yes	Determines whether the user can select a shipping option.

location:updated

Dispatched by store when the page changes (e.g., moving between product, cart, or category pages) or when visible content updates (e.g., products loaded via infinite scroll).

Example

import type { NubeSDK } from "@tiendanube/nube-sdk-types";

export function App(nube: NubeSDK) {
  nube.on("location:updated", ({ location }) => {
    // Trigger logic every time the user navigates to a new page
    const { page } = location;

    // Check the current page type
    if (page?.type === "home") {
      console.log("User is viewing the home page", page.data);
    } else if (page?.type === "product") {
      console.log("User is viewing a product page", page.data);
    } else if (page?.type === "category") {
      console.log("User is viewing a category page", page.data);
    }
  });
}

For more details about the state.location object, see the Location state page .

page:scroll

Storefront only. Dispatched by store when the reader crosses a new vertical scroll-depth bucket. The event fires once per 10% depth threshold reached (10, 20, …, 100), not on every scroll movement, so it is safe to use for scroll-depth tracking without throttling.

eventPayload

This event includes state.eventPayload describing the current scroll position:

Property	Type	Description
scrollY	number	Current vertical scroll position, in pixels.
scrollHeight	number	Total scrollable height of the document, in pixels.
viewportHeight	number	Height of the visible viewport, in pixels.
scrollPercentage	number	Scroll depth bucket that was just crossed (0, 10, 20, …, 100).

Example

import type { NubeSDK } from "@tiendanube/nube-sdk-types";

export function App(nube: NubeSDK) {
  nube.on("page:scroll", ({ eventPayload }) => {
    console.log(`User scrolled to ${eventPayload?.scrollPercentage}%`);

    if (eventPayload?.scrollPercentage === 100) {
      // The user reached the bottom of the page
    }
  });
}

page:exit_intent

Storefront only. Dispatched by store when the cursor leaves through the top edge of the viewport (moving toward the browser tab or address bar) — the classic desktop exit-intent signal. This only applies to pointer devices; on touch devices, use page:visibility_change instead.

eventPayload

This event includes state.eventPayload with context about the signal:

Property	Type	Description
deviceType	"desktop"	Detected device type. Exit intent only fires on "desktop".
source	string	Origin of the signal. Always "mouseout".

Example

import type { NubeSDK } from "@tiendanube/nube-sdk-types";

export function App(nube: NubeSDK) {
  nube.on("page:exit_intent", (state) => {
    // The user is about to leave — e.g. show a retention modal
    console.log("Exit intent detected");
  });
}

page:visibility_change

Storefront only. Dispatched by store when the store becomes hidden/backgrounded or the user switches tabs (based on the browser's visibilitychange event). This is the touch-friendly counterpart to page:exit_intent and works across desktop and mobile.

eventPayload

This event includes state.eventPayload with the current visibility state:

Property	Type	Description
deviceType	"desktop" | "touch"	Detected device type.
source	string	Origin of the signal. Always "visibilitychange".
visibilityState	"visible" | "hidden"	Current document visibility, mirroring document.visibilityState.

Example

import type { NubeSDK } from "@tiendanube/nube-sdk-types";

export function App(nube: NubeSDK) {
  nube.on("page:visibility_change", ({ eventPayload }) => {
    if (eventPayload?.visibilityState === "hidden") {
      console.log("👋 The user left the store (switched tabs or minimized)");
    } else {
      console.log("👀 The user came back to the store");
    }
  });
}