Analytics (nube.api.getAnalytics())

The Analytics API lets your app send analytics events to the store's configured analytics provider without touching the DOM or knowing which provider is installed. The host decides which underlying provider receives each event, so your app stays provider-agnostic.

In this initial release, GA4 is the only supported provider. The API is intentionally provider-agnostic, so additional providers may be added in the future without requiring changes to your app code.

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

export function App(nube: NubeSDK) {
  const analytics = nube.api.getAnalytics();
}

getAnalytics() returns a cached AnalyticsCommands instance — repeated calls return the same object. See the API overview for how the namespace is materialized and how errors are surfaced.

event

Sends a single analytics event.

event(
  name: string,
  data: AnalyticsEventData,
  options?: AnalyticsEventOptions,
): Promise<void>;

Parameter	Type	Required	Description
name	string	Yes	The event name — a GA4 recommended name (e.g. purchase, add_to_cart) or a custom app event.
data	AnalyticsEventData	Yes	The event payload, forwarded as-is to the host provider.
options	AnalyticsEventOptions	No	Extra dispatch options (see target below).

The types are:

type AnalyticsEventData = Record<string, unknown>;

type AnalyticsEventOptions = {
  target?: string;
};

AnalyticsEventData is a free-form object forwarded straight through to the provider — it maps to the params slot of gtag('event', name, params). Standard GA4 recommended fields (currency, value, items, …) live here.

Examples

Sending a standard event

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

export function App(nube: NubeSDK) {
  const analytics = nube.api.getAnalytics();

  analytics.event("add_to_cart", {
    currency: "BRL",
    value: 49.9,
    items: [{ item_id: "SKU_123", item_name: "T-Shirt", quantity: 1 }],
  });
}

Sending a custom event

Event names aren't limited to GA4's recommended set — use any name for app-specific tracking:

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

export function App(nube: NubeSDK) {
  const analytics = nube.api.getAnalytics();

  analytics.event("app_custom_event", {
    banner_id: "summer-sale",
    position: "home-hero",
  });
}

Reacting to state and awaiting the result

Because event returns a Promise, you can await it or handle failures:

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

export function App(nube: NubeSDK) {
  const analytics = nube.api.getAnalytics();

  nube.on("cart:add:success", async (state: Readonly<NubeSDKState>) => {
    try {
      await analytics.event("add_to_cart", {
        currency: state.store.currency,
        value: state.cart.total,
      });
    } catch (error) {
      console.error("Failed to send event:", error.message);
    }
  });
}

Targeting a specific provider

When a store has more than one analytics account configured (e.g. two GA4 properties), pass options.target with a measurement id to send the event to that destination only. The host forwards it as GA4's send_to.

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

export function App(nube: NubeSDK) {
  const analytics = nube.api.getAnalytics();

  analytics.event(
    "purchase",
    { transaction_id: "T_12345", currency: "BRL", value: 199.9 },
    { target: "G-XXXXXXXXXX" },
  );
}

Omit target for the host's default fan-out — one event per configured measurement id.

Notes

• The API is provider-agnostic. The store's host configuration decides which provider receives the event; your app only names the event and its payload.
• event resolves once the host has dispatched the event. On failure the promise rejects with an Error in the form "<code>: <message>" — see Return values and errors .
• The payload in data is sent as-is; use the field names your analytics provider expects (for GA4, its recommended events and parameters ).