Recursos do Tracking

Nesta seção, você encontrará uma visão detalhada de cada recurso disponível.

Para cada domínio, apresentamos:

O objetivo do recurso
O que ele retorna
Um exemplo de uso prático

🧩 Padrão de uso

Todos os recursos seguem o mesmo padrão de consumo:

1import { Tracking } from '@uappi/public-sdk';
2
3// Exemplo genérico
4const response = await Tracking.<dominio>.<metodo>(params);
import { Tracking } from '@uappi/public-sdk';
// Exemplo genérico
const response = await Tracking.<dominio>.<metodo>(params);

ℹ️ Informação

Para mais informações sobre cada endpoint, consulte:
API Pública: Árvore de Categoria

Facebook Pixel

Além do GA4, vários recursos disparam eventos no Facebook Pixel. Cada evento é registrado antes no servidor (API de Conversões) e o eventID retornado é repassado ao fbq, para que o Facebook deduplique os dois envios.

Os eventos do Facebook só são disparados quando o window.fbq existe na página. O SDK não carrega o Pixel.

Recurso	GA4	Facebook
`view.*`	`view_home`, `view_shipping`, `view_payment`, `view_other`, `view_not_found`	`PageView`
`product.getUrl`	`view_item` (produto) / `view_item_list` (categoria e marca)	`PageView` + `ViewContent` (produto)
`product.getSearch`	`view_item_list`	`PageView` + `Search`
`cart.addProduct`	`add_to_cart`	`AddToCart`
`cart.upsertProduct`	`add_to_cart` / `remove_from_cart`	`AddToCart` (apenas em adições)
`cart.beginCheckout`	`begin_checkout`	`InitiateCheckout`
`cart.addPaymentInfo`	`add_payment_info`	`AddPaymentInfo`
`cart.buy`	`purchase`	—
Componente `PaymentHosted`	`purchase`	`Purchase`

View

Responsável por emitir eventos referente a visualização de página, como: view_home, view_not_found, e mais. Todos os métodos deste domínio também disparam o PageView do Facebook.

`viewHome`

Emite o evento view_home usado para mensurar acesso a home da loja.

1await Tracking.view.viewHome();
await Tracking.view.viewHome();

`viewShipping`

Emite o evento view_shipping usado para mensurar acesso a página de frete.

1await Tracking.view.viewShipping();
await Tracking.view.viewShipping();

`viewPayment`

Emite o evento view_payment usado para mensurar acesso a página de pagamento.

1await Tracking.view.viewPayment();
await Tracking.view.viewPayment();

`viewOther`

Emite o evento view_other usado para mensurar acesso a páginas genéricas, como: institucionais.

1await Tracking.view.viewOther();
await Tracking.view.viewOther();

`viewNotFound`

Emite o evento view_not_found usado para mensurar acesso a páginas de erro 404.

1await Tracking.view.viewNotFound();
await Tracking.view.viewNotFound();

🎨 Customization

Responsável pelos eventos relacionados à exibição de conteúdo dinâmico, como banners e vitrines.

`listBanners`

Emite o evento view_promotion e retorna grupos de banner.

ℹ️ Informação

O método baixo possui um Genérico opcional em sua assinatura.
Caso o banner esteja configurado para trabalhar com parametros adicionais no painel, você deve tipar o Genérico "AdditionalParameters"
Ex: interface AdditionalParameters { title: string; description: string; }

1// Retorna uma lista de grupos de banners
2await Tracking.customization.listBanners<AdditionalParameters>(codes: Array<string>): Array<Banners<AdditionalParameters>>;
3
4// Retorna apenas um grupo de banner em especifico
5await Tracking.customization.listBanners<AdditionalParameters>(code: string): Banners<AdditionalParameters>;
// Retorna uma lista de grupos de banners
await Tracking.customization.listBanners<AdditionalParameters>(codes: Array<string>): Array<Banners<AdditionalParameters>>;
// Retorna apenas um grupo de banner em especifico
await Tracking.customization.listBanners<AdditionalParameters>(code: string): Banners<AdditionalParameters>;

`listShowcase`

Emite o evento view_item_list e retorna vitrines de produtos.

1// Retorna uma lista de vitrine
2await Tracking.customization.listShowcase(codes: Array<string>): Array<Showcase>;
3
4// Retorna apenas uma vitrine em especifico
5await Tracking.customization.listShowcase(code: string): Showcase;
// Retorna uma lista de vitrine
await Tracking.customization.listShowcase(codes: Array<string>): Array<Showcase>;
// Retorna apenas uma vitrine em especifico
await Tracking.customization.listShowcase(code: string): Showcase;

`selectPromotion`

Emite o evento select_promotion. Usado para mensurar cliques do cliente em banners.

ℹ️ Informação

1await Tracking.customization.selectPromotion<AdditionalParameters>(
2  banner: Banner<AdditionalParameters>, // item de Banners.banners, retornado por listBanners
3  index: number,                        // posição do banner no grupo
4): void;
await Tracking.customization.selectPromotion<AdditionalParameters>(
  banner: Banner<AdditionalParameters>, // item de Banners.banners, retornado por listBanners
  index: number,                        // posição do banner no grupo
): void;

👤 Customer

Responsável pelos eventos relacionados ao cliente.

`addNewsletter`

Emite o evento generate_lead e inscreve o cliente na newsletter da loja.

1await Tracking.customer.addNewsletter({
2  email: string;
3  name: string;
4  phone: string;
5});
await Tracking.customer.addNewsletter({
  email: string;
  name: string;
  phone: string;
});

`detail`

Emite o evento customer_profile e retorna os detalhes do cliente logado

1await Tracking.customer.detail(
2  options?: Pick<
3    ApiParams<TrackingCustomerFields, CustomerSortFields, CustomerConditionFields>,
4    'condition' | 'fields' | 'order'
5  >,
6);
await Tracking.customer.detail(
  options?: Pick<
    ApiParams<TrackingCustomerFields, CustomerSortFields, CustomerConditionFields>,
    'condition' | 'fields' | 'order'
  >,
);

`signinByDocument`

Emite o evento login e realiza o login por documento

1await Tracking.customer.signinByDocument({
2  document: string;
3  password: string;
4});
await Tracking.customer.signinByDocument({
  document: string;
  password: string;
});

`signinByEmail`

Emite o evento login e realiza o login por e-mail

1await Tracking.customer.signinByEmail({
2  email: string;
3  password: string;
4});
await Tracking.customer.signinByEmail({
  email: string;
  password: string;
});

`signup`

Emite o evento sign_up e realiza o cadastro de novo cliente

1await Tracking.customer.signup({
2  email: string;
3  nameCorporateName: string;
4  isCorporate: boolean;
5  gender: 'male' | 'female' | 'undefined';
6  birthdate: string;
7  phone: string;
8  nationality: string;
9  origin: 'frontend' | 'api' | 'admin';
10  password: string;
11  documents?: Array<{
12    type: 'cpf' | 'rg' | 'cnpj' | 'ie' | 'document1' | 'document2' | 'document3';
13    document: string;
14  }>;
15});
await Tracking.customer.signup({
  email: string;
  nameCorporateName: string;
  isCorporate: boolean;
  gender: 'male' | 'female' | 'undefined';
  birthdate: string;
  phone: string;
  nationality: string;
  origin: 'frontend' | 'api' | 'admin';
  password: string;
  documents?: Array<{
    type: 'cpf' | 'rg' | 'cnpj' | 'ie' | 'document1' | 'document2' | 'document3';
    document: string;
  }>;
});

🛍️ Product

Responsável pelos eventos de interação com produtos.

`search`

Emite o evento search.

1await Tracking.product.search(term: string);
await Tracking.product.search(term: string);

`selectItem`

Emite o evento select_item. Usado para mensurar cliques do cliente em links.

1await Tracking.product.selectItem(
2  page: UrlBrand | UrlListing | Showcase | Search,
3  productIndex: number,
4): void;
await Tracking.product.selectItem(
  page: UrlBrand | UrlListing | Showcase | Search,
  productIndex: number,
): void;

`getUrl`

Realiza a request com dados da página (categoria, detalhe de produto, institucional, marca, etc) e emite os eventos conforme o tipo da página:

Produto: view_item no GA4 e PageView + ViewContent no Facebook
Categoria e marca: view_item_list no GA4 e PageView no Facebook
Demais páginas: PageView no Facebook

ℹ️ Informação

Os campos price, brand, variation e mainCategory são adicionados automaticamente a fields, pois são necessários para montar os eventos. Por isso não podem ser informados em options.fields.

ℹ️ Informação

O método baixo possui um Genérico obrigatório em sua assinatura.
Genérico usado para definir o tipo de página que será retornado
tipos de páginas UrlProduct | UrlPage | UrlBrand | UrlListing

1await Tracking.product.getUrl<UrlType>(
2	path: string,
3	options?: Pick<
4		ApiParams<TrackingProductFields, ProductSortFields, ProductConditionFields>,
5		'condition' | 'fields' | 'limit' | 'offset' | 'meta' | 'order'
6	>
7): Promise<UrlType>;
await Tracking.product.getUrl<UrlType>(
	path: string,
	options?: Pick<
		ApiParams<TrackingProductFields, ProductSortFields, ProductConditionFields>,
		'condition' | 'fields' | 'limit' | 'offset' | 'meta' | 'order'
	>
): Promise<UrlType>;

`getSearch`

Emite o evento view_item_list no GA4, PageView e Search no Facebook, e retorna uma listagem de produtos com base no termo de pesquisa. Pode ser usado para criar uma sugestão no header do site e também para criar uma listagem paginada de busca de produto

1await Tracking.product.getSearch(
2	term: string,
3  options?: Pick<
4    ApiParams<TrackingProductFields, ProductSortFields, ProductConditionFields>,
5    'condition' | 'fields' | 'limit' | 'meta' | 'offset' | 'order'
6  >
7): Search;
await Tracking.product.getSearch(
	term: string,
  options?: Pick<
    ApiParams<TrackingProductFields, ProductSortFields, ProductConditionFields>,
    'condition' | 'fields' | 'limit' | 'meta' | 'offset' | 'order'
  >
): Search;

`listShipmentQuoteProduct`

Emite o evento item_view_shipping_calculation e realiza cotação de frete no contexto do produto informado na requisição. Não considera produtos persistidos no carrinho, apenas o frete considerando um produto em específico.

1await Tracking.product.listShipmentQuoteProduct(
2	payload: Pick<ApiParams, 'targetCountryCode' | 'targetZipCode' | 'items'>,
3): ShipmentQuoteProductResponse;
await Tracking.product.listShipmentQuoteProduct(
	payload: Pick<ApiParams, 'targetCountryCode' | 'targetZipCode' | 'items'>,
): ShipmentQuoteProductResponse;

🛒 Cart

Responsável pelos eventos relacionados ao carrinho.

`addProduct`

Emite o evento add_to_cart no GA4 e AddToCart no Facebook, e adiciona um ou mais produtos ao carrinho

1await Tracking.cart.addProduct({
2  items: Array<{
3    productId: number;
4    quantity: number;
5    code?: string | null;
6    upsellId?: number | null;
7    productPairOfferId?: number | null;
8  }>;
9}): CartResponse;
await Tracking.cart.addProduct({
  items: Array<{
    productId: number;
    quantity: number;
    code?: string | null;
    upsellId?: number | null;
    productPairOfferId?: number | null;
  }>;
}): CartResponse;

`deleteProduct`

Emite o evento remove_from_cart e remove um ou varios produtos do carrinho.

O segundo parâmetro é o carrinho antes da remoção. Ele é usado para montar o evento com os dados dos itens removidos, que não estão mais na resposta.

1await Tracking.cart.deleteProduct(
2  payload: {
3    items: Array<{ productId: number; upsellId?: number | null }>;
4  },
5  oldCartResponse: CartResponse,
6): CartResponse;
await Tracking.cart.deleteProduct(
  payload: {
    items: Array<{ productId: number; upsellId?: number | null }>;
  },
  oldCartResponse: CartResponse,
): CartResponse;

`listDetail`

Retorna todos os detalhes de um carrinho: produtos, descontos, frete selecionado, e mais

1await Tracking.cart.listDetail(): CartResponse;
await Tracking.cart.listDetail(): CartResponse;

`shipmentQuote`

Emite o evento item_view_shipping_calculation e retorna opções de frete no contexto do carrinho

1await Tracking.cart.shipmentQuote({
2  targetCountryCode: CountryAlpha3;
3  targetZipCode: string;
4}): CartResponse;
await Tracking.cart.shipmentQuote({
  targetCountryCode: CountryAlpha3;
  targetZipCode: string;
}): CartResponse;

`upsertProduct`

Emite eventos conforme a ação do cliente: remove_from_cart para remoções e add_to_cart para adições, atualizando a quantidade do produto no carrinho de acordo com a operação realizada. Nas adições, também emite AddToCart no Facebook.

Informe oldQuantity com a quantidade atual do item: o SDK compara com quantity para decidir se é adição ou remoção.

1await Tracking.cart.upsertProduct({
2  items: Array<{
3    productId: number;
4    quantity?: number;
5    oldQuantity?: number;
6    code?: string | null;
7    upsellId?: number | null;
8    productPairOfferId?: number | null;
9  }>;
10}): CartResponse;
await Tracking.cart.upsertProduct({
  items: Array<{
    productId: number;
    quantity?: number;
    oldQuantity?: number;
    code?: string | null;
    upsellId?: number | null;
    productPairOfferId?: number | null;
  }>;
}): CartResponse;

`selectShipment`

Emite o evento add_shipping_info e seleciona uma opção de frete no contexto do carrinho.

1await Tracking.cart.selectShipment({
2  orders: Array<{
3    cartOrderId: number;
4    shippingTableId: number;
5    shippingPickupPointId?: number;
6  }>;
7}): CartResponse;
await Tracking.cart.selectShipment({
  orders: Array<{
    cartOrderId: number;
    shippingTableId: number;
    shippingPickupPointId?: number;
  }>;
}): CartResponse;

`buy`

Emite o evento purchase e faz o processo de finalização de uma compra. O código do pedido criado é enviado como transaction_id.

O carrinho precisa ser informado porque, após a compra, ele já foi consumido e não reflete mais os itens comprados.

1await Tracking.cart.buy(
2  payload: {
3    payments: Array<{
4      paymentOptionId: number;
5      value?: number;
6      selectedInstallment?: number;
7      card?: {
8        token?: string;
9        number: string;
10        cvv: string;
11        month: number;
12        year: number;
13        name: string;
14      };
15    }>;
16  },
17  paymentMethod: string,      // código do tipo de pagamento, enviado como payment_type
18  cartResponse: CartResponse, // carrinho antes da compra
19);
await Tracking.cart.buy(
  payload: {
    payments: Array<{
      paymentOptionId: number;
      value?: number;
      selectedInstallment?: number;
      card?: {
        token?: string;
        number: string;
        cvv: string;
        month: number;
        year: number;
        name: string;
      };
    }>;
  },
  paymentMethod: string,      // código do tipo de pagamento, enviado como payment_type
  cartResponse: CartResponse, // carrinho antes da compra
);

ℹ️ Informação

Ao usar o componente PaymentHosted, o purchase (GA4) e o Purchase (Facebook) são disparados pelo próprio componente. Não chame Tracking.cart.buy nesse fluxo.

`beginCheckout`

Emite o evento begin_checkout no GA4 e InitiateCheckout no Facebook. Recebe o carrinho atual, retornado por listDetail.

1await Tracking.cart.beginCheckout(cartPayload: CartResponse): void;
await Tracking.cart.beginCheckout(cartPayload: CartResponse): void;

`addPaymentInfo`

Emite o evento add_payment_info no GA4 e AddPaymentInfo no Facebook.

1await Tracking.cart.addPaymentInfo(
2  paymentMethod: string,
3  cartPayload: CartResponse
4): void;
await Tracking.cart.addPaymentInfo(
  paymentMethod: string,
  cartPayload: CartResponse
): void;

publicApiTracking

`install`

Instala o Google Tag Manager em ambiente de desenvolvimento, para testar os eventos localmente. Busca o ID do GTM configurado no app google-tag-manager da loja, via listTemplateSettings(import.meta.env.VITE_BASE).

Em produção (import.meta.env.PROD) não faz nada.

1import { Tracking } from '@uappi/public-sdk';
2
3await Tracking.publicApiTracking.install();
import { Tracking } from '@uappi/public-sdk';
await Tracking.publicApiTracking.install();

🏁 Próximo passo

Agora que você conhece tudo sobre Tracking do public-sdk, veja também:

SDK Público - Api: Introdução

Para o desenvolvimento de interfaces, veja:

Store Theme: introdução Área Restrita: introdução Checkout: introdução

Começando

Store Theme

Customização de Interface

Consumo de Dados

Tracking e SEO

Checkout

Consumo de Dados

Tracking e SEO

Ambiente de Pagamento

Área Restrita (Minha Conta)

Consumo de Dados

Tracking e SEO

SDK Público (public-sdk)

Modules

Api

Tracking

API Pública

Área Restrita (Minha Conta)

Carrinho de Compras

API Privada

Apps

Configurações Gerais

Clientes

Template

Avaliações

Notificações

ERPs

Filas

Grupo de Pedidos

Pedidos

Carrinhos

Pagamentos

Anti-Fraude

Produtos

Inteligência Artificial

Marcas

Categorias

Filtros

Atributos

Url

Relatórios

Render

Fretes

Usuários

Promocionais

Marketplace

Third Party

Datalogic

Busca

MCP

Recursos do Tracking

🧩 Padrão de uso

Facebook Pixel

View

viewHome

viewShipping

viewPayment

viewOther

viewNotFound

🎨 Customization

listBanners

listShowcase

selectPromotion

👤 Customer

addNewsletter

detail

signinByDocument

signinByEmail

signup

🛍️ Product

search

selectItem

getUrl

getSearch

listShipmentQuoteProduct

🛒 Cart

addProduct

deleteProduct

listDetail

shipmentQuote

`viewHome`

`viewShipping`

`viewPayment`

`viewOther`

`viewNotFound`

`listBanners`

`listShowcase`

`selectPromotion`

`addNewsletter`

`detail`

`signinByDocument`

`signinByEmail`

`signup`

`search`

`selectItem`

`getUrl`

`getSearch`

`listShipmentQuoteProduct`

`addProduct`

`deleteProduct`

`listDetail`

`shipmentQuote`

`upsertProduct`

`selectShipment`

`buy`

`beginCheckout`

`addPaymentInfo`

`install`