Documentação

Se você usa o app do Provedly para Shopify, não precisa instalar nada: o app embed do tema carrega tudo. O Plugin para WordPress continua funcionando normalmente.

O snippet do site cobre quase todos os casos. Cada widget e cada barra também tem sua própria tag, em Advanced na aba Embed, para duas situações: uma barra embutida que precisa aparecer num ponto exato da página (ela aparece onde a tag for colada) e construtores de páginas que só aceitam código por bloco. Uma página com os dois tipos de tag nunca carrega um item duas vezes.

O endpoint de configuração só responde aos domínios cadastrados no site. Subdomínios estão incluídos, então example.com cobre shop.example.com. Adicione os hosts de homologação explicitamente. Deixar a lista vazia libera qualquer domínio, o que não recomendamos.

1. O snippet do site faz uma única requisição, GET https://provedly.app/api/s/{site key}/manifest, que retorna cada widget e barra ativos com suas configurações e até 30 registros recentes por widget, além da versão atual do código.
2. Depois ele carrega o código do widget e o da barra, só se a página precisar deles. Os dois são arquivos versionados que o navegador mantém em cache até a próxima versão.
3. O ciclo de notificações começa depois do atraso inicial que você definiu. Cada exibição envia uma impressão para /track.
4. Enquanto a aba está aberta, um heartbeat chama /presence a cada 30 segundos para o contador ao vivo.

Adicione um elemento onde a contagem deve aparecer, por exemplo abaixo do título do produto ou do botão Adicionar ao carrinho. Na Shopify, use um bloco Custom liquid no editor de tema. O snippet do site preenche esse elemento com a mesma contagem real da notificação (visitantes vistos nos últimos 90 segundos) e o mantém oculto abaixo do seu mínimo.

<div data-provedly-live data-template="{n} people are viewing this product right now"></div>

Adicione data-style="card" para uma versão em cartão com o número grande e um link Verify para sua página de verificação, ou data-dot="off" para remover o ponto. Com vários widgets na mesma página, coloque o token de um widget no atributo (data-provedly-live="pp_…") para escolher qual.

Vídeos passo a passo: qualquer site ou WordPress e Shopify.

• As chaves começam com provedly_ e pertencem ao espaço de trabalho, não a um widget específico.
• A chave aparece uma única vez, quando você a cria. Guardamos só um hash, então copie-a na hora.
• Revogue uma chave quando quiser, na mesma página. Requisições com uma chave revogada recebem 401.

Widgets e barras aceitam o id (um UUID) ou o token. Sites aceitam o id ou o domínio.

Barras novas são criadas pausadas. Ative uma com PATCH /bars/{bar} {"status": "active"}.

As leituras retornam os mesmos campos, então você pode ler um widget ou uma barra, mudar um valor e enviar de volta. As regras de URL aceitam uma lista de caminhos ou um caminho por linha. Se a alteração colocar dois itens ativos no mesmo lugar das mesmas páginas, a resposta traz uma entrada warnings.

A marca, a página pública de verificação, os registros de exemplo e o design detalhado ficam no painel.

Impressões e cliques de widgets e barras, pedidos e receita verificados, pedidos e receita assistidos pela prova, e um detalhamento por widget para o número de dias escolhido.

{ "error": "...", "message": "..." }

401  missing or invalid key
403  read-only key used for a change
404  not in this workspace
422  refused: validation, plan limit, or an ended or archived bar

Cada chave pode fazer 120 requisições por minuto.

get_account, list_sites, list_widgets, list_bars, get_stats, set_widget_status, update_widget, set_bar_status, create_bar, update_bar, add_record, get_install_snippet.

• Valem os mesmos limites de plano do painel.
• Barras criadas por um assistente começam pausadas até você pedir para ativá-las.
• Uma chave somente leitura não pode alterar nada.
• Registros adicionados pela API ou MCP nunca são marcados como verificados. Só os webhooks assinados da Stripe, Shopify e WooCommerce são.

• “Quantas impressões e pedidos verificados meus widgets tiveram nos últimos 7 dias?”
• “Crie uma barra de contagem regressiva em example.com para a liquidação de inverno que termina em 1º de dezembro às 9h, horário de Nova York.”
• “Pause todos os widgets do meu site de homologação.”
• “Me passe o código de instalação da minha loja.”

Apenas os números desse espaço de trabalho. O parâmetro tz é opcional.

Os campos de série trazem today, yesterday, change_pct, last_7d, last_30d, total, trend_24h, trend_7d, trend_30d.

Os números são recalculados no máximo uma vez por minuto. Cada chave pode fazer 60 requisições por minuto.

201 Created
{ "id": 812, "hash": "9c1e0b7a…", "verified": false, "occurred_at": "2026-10-15T14:03:00+00:00" }

401 Unauthorized   wrong or missing bearer key
422 Unprocessable  validation errors, including a duplicate external_id

O widget exibe os registros da API, mas nunca os marca como verificados. A marca de verificado é reservada aos webhooks assinados. Veja Webhooks.

• Linha de cabeçalho obrigatória, colunas em qualquer ordem, colunas extras ignoradas.
• Datas em ISO 8601. Datas ausentes usam o horário da importação.
• "Skip duplicates" ignora linhas cujo nome e cidade coincidem com um registro existente dentro de uma hora.
• As linhas importadas têm a origem csv e não são verificadas. Linhas mais antigas que a sua janela de exibição são salvas, mas não aparecem.

1. Na aba Data do widget, adicione uma fonte Stripe. Copie a URL do endpoint:

https://provedly.app/api/hooks/stripe/pp_your_widget_token

2. Na Stripe, vá em Developers, Webhooks, Add endpoint. Cole a URL e selecione os eventos que o seu checkout envia: checkout.session.completed para pagamentos únicos via Checkout, invoice.paid para assinaturas e payment_intent.succeeded somente se você cobra com Payment Intents sem Checkout. Uma compra é registrada uma única vez, mesmo que vários deles disparem.
3. Copie o segredo de assinatura (whsec_…) para o campo de segredo da fonte no Provedly.
4. Envie um evento de teste pela Stripe. A fonte mostra "last event" em poucos segundos.

Lemos o nome do cliente, o país e a cidade de entrega ou cobrança quando existirem, o primeiro item do pedido como produto e o total formatado como preço.

1. Instale o Provedly pela Shopify App Store (listagem em breve).
2. Na página inicial do app, clique em "Open theme editor", confira se o app embed do Provedly está ativado e salve. Sem código, sem tag script.
3. Os pedidos viram registros verificados automaticamente: os últimos 60 dias são importados na instalação e cada novo pedido chega por um webhook assinado.

O app roda dentro do seu admin da Shopify com as mesmas ferramentas de design, dados e análise deste painel. Os planos são cobrados pela Shopify na sua fatura normal; o plano Free não exige forma de pagamento. Nomes e cidades dos compradores só aparecem depois que a Shopify aprova o acesso do app aos dados de clientes; até lá, as notificações dizem "Someone just purchased…".

1. Adicione uma fonte Shopify na aba Data e copie a URL:

https://provedly.app/api/hooks/shopify/pp_your_widget_token

2. No admin da Shopify, em Settings, Notifications, Webhooks, crie um webhook para Order payment (orders/paid), formato JSON, com essa URL. Order creation também funciona se você quiser incluir pedidos não pagos; o mesmo pedido nunca é registrado duas vezes.
3. Copie o segredo compartilhado exibido abaixo da lista de webhooks para o campo de segredo da fonte.

Os payloads são verificados pelo cabeçalho HMAC-SHA256. Uma verificação que falha é registrada e descartada. Sem segredo, os eventos são aceitos, mas aparecem como "No signing secret set" no seu painel e não são marcados como verificados.

1. Adicione uma fonte WooCommerce na aba Data, copie a URL e escolha um segredo de assinatura (qualquer texto com 8 ou mais caracteres):

https://provedly.app/api/hooks/woocommerce/pp_your_widget_token

2. Com o plugin: instale o Provedly pelo WordPress.org (Plugins, Add New, busque "Provedly"), abra o Provedly no menu do admin, cole o token do widget, a URL e o segredo, e salve. O plugin insere as tags script, cria o webhook do WooCommerce e envia o id do visitante em cada pedido para a atribuição.
3. Manualmente: WooCommerce, Settings, Advanced, Webhooks, Add webhook. Tópico Order updated, a URL de entrega acima, o mesmo segredo, versão da API WP REST API v3.

O WooCommerce assina cada envio com HMAC-SHA256 em X-WC-Webhook-Signature. Só pedidos em Processing ou Completed viram registros, uma vez cada, então pedidos pendentes, com falha ou cancelados nunca aparecem.

O painel conta um pedido como assistido pela prova só quando o comprador tinha um id de visitante que viu uma notificação do mesmo widget nos 30 dias antes da compra. Nada é estimado. Em lojas Shopify que usam o app isso é automático: o widget grava o id de visitante no carrinho como o atributo provedly_visitor e o webhook do pedido o lê de volta.

Nos demais casos, repasse você mesmo o id de visitante. O widget o guarda no cookie próprio pv_vid e o expõe como window.Provedly.visitorId().

• Stripe: defina metadata.provedly_visitor na Checkout Session ou no PaymentIntent.
• API de registros: envie no campo opcional visitor.

// at checkout time, on your site
const visitor = window.Provedly?.visitorId();
// Stripe: pass it as metadata.provedly_visitor
// Records API: POST { ..., "visitor": visitor }

Contagens de compras verificadas em 24 horas, 7 dias e desde o início; a janela e o mínimo do contador ao vivo; se exemplos são exibidos; se só compras verificadas são exibidas; cada fonte com suas contagens e o último registro; os provedores conectados; as compras verificadas recentes como hashes; e as raízes SHA-256 noturnas do registro. Nomes e cidades nunca aparecem. Leia a página de confiança para entender o motivo.

O hash de cada registro é retornado quando você o cria pela API. A raiz de um dia é o SHA-256 da lista ordenada dos hashes dos registros daquele dia. Guarde seus hashes e você pode recalcular a raiz por conta própria.

Se "Verified purchases only" estiver ativado e o widget ainda não tiver registros verificados, não há nada para mostrar. A página do widget avisa sobre isso. Desative a configuração ou conecte uma loja.

Espere cerca de um minuto e recarregue a página. Com os snippets por item, novas versões do código podem levar alguns minutos.

• Abra o console do navegador. Um 403 em /api/w/…/config significa que o domínio da página não está nos domínios permitidos do site.
• O widget precisa de pelo menos um registro dentro da janela de exibição. Adicione um registro de exemplo para testar.
• Confira se o status do widget é "active" e se o espaço de trabalho ainda tem impressões neste mês.
• Segmentação por caminho: uma lista de inclusão que não corresponde ao caminho atual deixa o widget em silêncio.

Ele fica oculto abaixo do mínimo que você definiu (padrão 2). Abra a página em dois navegadores, ou numa janela anônima, e espere o primeiro heartbeat. Também é preciso ativar "Enable live counter".

O segredo de assinatura está faltando ou errado. O cartão da fonte mostra "No signing secret set" ou a contagem de eventos para de subir. Cole o segredo de novo e reenvie um evento de teste.

Aumente o z-index na seção Look do widget. O padrão é 9999.