CustomerTrackActivity

Finalidade

O Storefront API expõe uma mutation para registrar eventos de rastreamento de atividade do cliente, usados na integração com o Meta CAPI:

Envio de eventos de conversão (ViewContent, AddToCart, Purchase, etc.) ao Meta
Enriquecimento automático do payload com contexto da requisição (URL, IP, User-Agent)
Associação opcional do evento a um cliente logado (via customerAccessToken)

O consumidor envia o evento pela Storefront API; o processamento e o encaminhamento para o Meta CAPI ficam a cargo da plataforma.

Mutation disponível

`customerTrackActivity`

Registra um evento de rastreamento de atividade do cliente (ex.: eventos Meta CAPI).

Aspecto	Descrição
Nome GraphQL	`customerTrackActivity`
Autenticação	Obrigatória. Token de acesso (loja/parceiro) no header da requisição GraphQL.
Descrição	"Registers a customer tracking activity."

Assinatura

customerTrackActivity(
  customerAccessToken: String
  input: CustomerTrackActivityInput!
): OperationResult!

customerAccessToken (opcional): token do cliente logado. Quando informado e válido, o evento pode ser associado ao usuário.
input (obrigatório): payload do evento no tipo CustomerTrackActivityInput.

Retorno

Tipo OperationResult:

Campo	Tipo	Descrição
`isSuccess`	`Boolean`	Indica se o registro do evento foi realizado com sucesso.

Tipos de entrada e campos

`CustomerTrackActivityInput`

Objeto de entrada da mutation customerTrackActivity.

Campo	Tipo GraphQL	Obrigatório	Descrição
`id`	`UUID` (Guid)	Sim	Identificador único do evento (UUID/GUID). Gerado pelo cliente para idempotência e rastreio.
`type`	`String`	Sim	Tipo do evento. Para Meta CAPI use os nomes padrão do Meta (ex.: `ViewContent`, `AddToCart`, `Purchase`).
`message`	`Any`	Sim	Payload do evento em objeto/JSON. Para Meta CAPI, seguir as recomendações do Meta para cada tipo de evento.

Comportamento do message: A API pode enriquecer o objeto message com dados da requisição HTTP (ex.: url, client_ip_address, client_user_agent). O cliente envia apenas os dados de negócio; o restante é preenchido pela API.

Tipos de evento (Meta CAPI)

Para integração com o Meta CAPI, o campo type deve usar os Standard Events do Meta. Exemplos:

Tipo do evento	Uso típico
`ViewContent`	Visualização de produto ou conteúdo
`AddToCart`	Adição de produto ao carrinho
`AddToWishlist`	Adição à lista de desejos
`InitiateCheckout`	Início do checkout
`AddPaymentInfo`	Inclusão de informação de pagamento
`Purchase`	Compra concluída
`Lead`	Geração de lead
`CompleteRegistration`	Conclusão de cadastro

Lista completa e recomendações de campos por evento: documentação oficial do Meta.

Exemplos de uso

Request GraphQL

mutation CustomerTrackActivity($customerAccessToken: String, $input: CustomerTrackActivityInput!) {
  customerTrackActivity(customerAccessToken: $customerAccessToken, input: $input) {
    isSuccess
  }
}

Variáveis de exemplo (ViewContent):

{
  "customerAccessToken": null,
  "input": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "type": "ViewContent",
    "message": {
      "content_name": "Camiseta Preta",
      "content_ids": ["150131"],
      "content_type": "product",
      "value": 109.99,
      "currency": "BRL",
      "content_category": "Masculino"
    }
  }
}

Cliente logado

Para associar o evento ao usuário logado, envie o customerAccessToken:

{
  "customerAccessToken": "seu-customer-access-token",
  "input": {
    "id": "550e8400-e29b-41d4-a716-446655440001",
    "type": "Purchase",
    "message": {
      "value": 299.90,
      "currency": "BRL",
      "num_items": 2,
      "content_ids": ["150131", "150132"]
    }
  }
}

SDK TypeScript (Storefront SDK)

O Storefront SDK (TypeScript) expõe o método track no repositório de customer:

const input: CustomerTrackActivityInput = {
  id: '550e8400-e29b-41d4-a716-446655440000',
  type: 'ViewContent',
  message: {
    content_name: 'Camiseta Preta',
    content_ids: ['150131'],
    value: 109.99,
    currency: 'BRL',
  },
};

const result = await client.customer.track(input, customerAccessTokenOptional);
// result.data?.isSuccess