@reviewo/tracker

SDK de tracking da Reviewo. O envio de eventos tem dois canais, espelhando a arquitetura do backend:

| Canal | Método | Endpoint | Onde rodar | Auth | | --- | --- | --- | --- | --- | | Público | reviewo.track.* | POST /api/v1/public/track | navegador ou backend | publishable key (metadata.siteKey) | | Sensível | reviewo.events.* | POST /api/v1/integration/events | somente backend | secret API key (x-api-key) |

⚠️ Compra, estorno e cancelamento são eventos sensíveis e sempre vão server-to-server, autenticados pela secret API key. Mesmo instalando o tracking via JavaScript/GTM, esses eventos nunca saem do navegador. O canal público recusa-os com um SensitiveEventError.

Instalação

npm install @reviewo/tracker
# ou: yarn add @reviewo/tracker

Canal público — navegação, carrinho e checkout

import { reviewo } from '@reviewo/tracker'

reviewo.configure({
  baseURL: 'https://www.api.reviewo.com.br',
  publishableKey: 'pk_rv_...', // vira metadata.siteKey
})

await reviewo.track.event({
  eventType: 'product_view',
  eventData: { productId: 'SKU-1', productName: 'Produto', price: 199.9 },
})

Eventos aceitos: page_view, product_view, add_to_cart, checkout_start, checkout_profile, checkout_shipping, checkout_payment, abandoned_cart, form_submit, custom_event.

Exemplos prontos em reviewo.track.examples.

Canal sensível — compra, estorno e cancelamento (backend)

import { reviewo } from '@reviewo/tracker'

reviewo.configure({
  baseURL: 'https://www.api.reviewo.com.br',
  apiKey: process.env.REVIEWO_SECRET_KEY!, // x-api-key — NUNCA no navegador
  accessKey: process.env.REVIEWO_ACCESS_KEY, // x-api-organization (opcional)
})

// Compra (atribuída pelo clickId do afiliado)
await reviewo.events.purchase({
  orderId: 'ORD-123',
  totalValue: 199.9,
  currency: 'BRL',
  clickId: 'CLICK_DO_AFILIADO',
  items: [{ sku: 'SKU-1', name: 'Produto', price: 199.9, quantity: 1 }],
})

// Estorno parcial (total quando sem refundValue)
await reviewo.events.refund({ orderId: 'ORD-123', refundValue: 50, reason: 'Estorno parcial' })

// Cancelamento
await reviewo.events.cancel({ orderId: 'ORD-123', reason: 'Cancelado pelo cliente' })

Idempotência

Cada evento é idempotente por idempotencyKey (header x-idempotency-key). Quando você não informa uma, o SDK deriva ${eventType}:${orderId} — igual ao backend. Reenvios do mesmo evento respondem { idempotent: true } sem reaplicar.

Resposta

const res = await reviewo.events.purchase({ orderId, totalValue, clickId })
// res.applied  → true quando o efeito foi aplicado (status 'processed')
// res.status   → 'processed' | 'ignored'
// res.reason   → 'no_attribution' | 'order_not_found' | 'order_already_exists' | ...

Configuração

reviewo.configure(options) (campos ausentes preservam o valor atual):

| Opção | Header / uso | Default | | --- | --- | --- | | baseURL | base das URLs | https://www.api.reviewo.com.br | | publishableKey | metadata.siteKey (público) | — | | apiKey | x-api-key (sensível) | — | | accessKey | x-api-organization (sensível, opcional) | — |