Autenticação e limites entre contas
Os endpoints de leitura do painel exigem o cookie de sessão HttpOnly autenticado. Proprietários com e-mail verificado podem emitir tokens bearer somente leitura vinculados a projetos, mostrados uma única vez e armazenados como hashes, com expiração de até 90 dias. read:reports permite summary/trend/search; read:journeys também permite leituras de eventos brutos e jornadas. Tokens nunca autorizam acesso à conta ou alterações. Proprietários podem alterar seus próprios projetos; Viewers verificados e aceitos podem ler projetos compartilhados, mas não mudar configurações, cobrança ou conexões. IDs de projetos e IDs públicos de rastreadores são identificadores de roteamento, não autenticação. Não copie uma sessão do navegador para código público de cliente.
Gravações da API exigem JSON e verificações de mesma origem. Origens exatas de sites permitidos se aplicam à coleta pública. Cookies usam Secure em produção. Uma sessão ausente retorna 401; projetos inacessíveis retornam 404. Controles de consulta inválidos retornam 400.
Política de navegação automática
startPageviews({mode, routes, initial}) ativa explicitamente a automação de visualizações de páginas mapeadas. mode é history (padrão) ou hash; routes é um objeto obrigatório com 1–50 caminhos seguros exatos ou prefixos terminados em /* mapeados para rótulos estáticos seguros de páginas. initial tem true como padrão. stopPageviews() interrompe apenas a automação de navegação; consent(false) interrompe toda a coleta e apaga o pseudônimo armazenado.
pushState/replaceState e popstate do histórico são observados apenas com consentimento. O modo hash também trata mudanças em #/route. Strings de consulta são ignoradas na identidade da página; fragmentos comuns do histórico não se tornam páginas. Repetições de configurações equivalentes e sinais de navegação duplicados não adicionam eventos. track(pageview) manual é independente, portanto não o combine com visualizações automáticas para a mesma visita.
GPC=true bloqueia concessões de consentimento, visualizações de páginas, eventos nomeados e acesso ao ID do visitante. Um novo sinal GPC observado retira o rastreamento ativo e cancela solicitações pendentes quando possível. Desativar GPC não restaura o consentimento silenciosamente. Esse é um comportamento da implementação, não uma declaração de conformidade jurídica universal.
Coleta consentida no navegador
O rastreador nunca concede consentimento automaticamente. Conecte consentimento e retirada ao seu gerenciador de consentimento. Page é um rótulo explícito não pessoal de caminho; nenhuma URL completa, consulta de busca ou fragmento é coletado. Não coloque nomes, IDs de contas ou tokens em rótulos de caminho. Referrer, se fornecido, deve ser um hostname; device é uma categoria ampla declarada opcional, não fingerprinting. País não é inferido da entrada do navegador.
reylin.consent(true); // only after the visitor permits it
await reylin.track('pageview', {page:'/pricing', device:'desktop'});
await reylin.track('signup', {page:'/signup'});
// On withdrawal:
reylin.consent(false);Resumo e funil ordenado
GET /api/projects/:id/summary aceita days (1–366), currency (código ISO em maiúsculas), source, steps (nomes separados por vírgula) e conversionHours (1, 24 ou 168). Os dias terminam no horário UTC atual. Use page:/pricing para visualizações exatas de páginas declaradas ou page:/docs/* para um prefixo seguro de caminho declarado, combinados com metas nomeadas e $payment final. Um funil exige horários estritamente ordenados; qualquer entrada elegível pode iniciar um percurso e cada visitante pseudônimo é contado uma vez. Source se aplica à entrada. Consentimento ou vínculo de visitante ausentes não podem criar uma conversão de pagamento.
A etapa final reservada $payment lê apenas pagamentos bem-sucedidos dos registros financeiros. Um evento do navegador chamado purchase ou payment nunca é prova financeira. Reembolsos não apagam conversões de pagamentos bem-sucedidos. Os totais de receita usam unidades monetárias mínimas inteiras do provedor; moedas nunca são combinadas ou convertidas implicitamente.
Consultas por dimensão e paginação
GET /api/projects/:id/events aceita horários ISO from/to (intervalo máximo de 366 dias), limit (1–1000), cursor, groupBy e filters como JSON codificado para URL. Dimensões: source, type, page, referrer, country, device. Valores ausentes são Unknown, não presumidos. Operadores: is, is_not, contains, not_contains. Até dez filtros se combinam com AND; a comparação contains não diferencia maiúsculas de minúsculas.
Omita groupBy para eventos individuais cronológicos; defina-o para contagens de eventos e visitantes distintos. As respostas incluem os limites normalizados from/to e nextCursor. Reutilize exatamente esses limites e filtros nas solicitações seguintes, pois um horário final móvel muda a consulta. Cursores são vinculados à consulta, não são credenciais de acesso.
const query = new URLSearchParams({
from:'2026-10-01T00:00:00Z', to:'2026-10-31T23:59:59Z',
groupBy:'page', limit:'100',
filters:JSON.stringify([{dimension:'source',operator:'contains',value:'Google'}])
});
const response = await fetch('/api/projects/PROJECT_ID/events?' + query);Jornadas pseudônimas de visitantes
GET /api/projects/:id/journey aceita visitorId, from/to, limit e cursor. Retorna fatos de eventos consentidos, pagamentos bem-sucedidos vinculados e estados de reembolso desses pagamentos em ordem cronológica. Não identifica pessoa, e-mail, grafo de dispositivos ou identidade entre sites. Um visitante ausente retorna uma jornada vazia em vez de histórico fabricado. Valores de reembolso continuam específicos por moeda e os estados permanecem visíveis.
Semântica da conexão com o provedor e da importação
As análises de clientes Stripe e sua assinatura do Reylin têm limites de confiança separados. A configuração da conexão verifica a conta do provedor, cria um rascunho com um endpoint estável de webhook e depois ativa o segredo de assinatura criptografado. As assinaturas validam os bytes brutos da entrega; o dinheiro é conciliado a partir do objeto atual do provedor e deduplicado.
A importação histórica limitada de pagamentos de 7 ou 30 dias não reconstrói visitantes históricos, todos os reembolsos ou contestações. Avisos de cobertura continuam visíveis. Receita desconectada está indisponível; uma contagem zero de pagamentos armazenados não comprova zero vendas reais. O teste de aceitação real do provedor continua sendo um pré-requisito de implantação.
Dados de busca não são receita
A integração com Search Console é um relatório de busca somente leitura, autorizado separadamente. Cliques, impressões, CTR e posição são métricas de busca do Google, não pagamentos ou visitantes únicos do site. Os limites de datas do Google usam o horário do Pacífico, diferentemente da janela UTC dos relatórios de eventos. Os resultados da API podem omitir linhas e retornar as principais; uma paginação limitada nunca comprova uma exportação exaustiva. O provisionamento OAuth e a autorização real da conta exigem uma integração configurada separadamente.
Configurações salvas e relatórios por calendário
GET e POST /api/projects/:id/config/:kind suportam segment, funnel, goal, note e preferences. Atualizações usam /:id e exclusões usam POST {action: delete}. Somente proprietários alteram dados. Notas são exclusivas do proprietário; outras definições salvas podem ser lidas por Viewers compartilhados. Chaves de eventos de metas não podem mudar; rótulos de exibição nunca reescrevem o histórico de eventos. Preferências são salvas explicitamente e aplicadas ao relatório atual mediante solicitação.
GET /api/projects/:id/trend aceita from, to, timezone, bucket hour/day/week/month, currency e compare=true. Sua janela semiaberta [from,to) evita contagem dupla nos limites. Os agrupamentos seguem limites reais do calendário local, incluindo mudanças de horário de verão; semanas começam na segunda-feira. A comparação com o período anterior tem igual duração transcorrida, e uma base zero retorna null na variação percentual.
Assinaturas de clientes e contratos recorrentes
As análises de clientes podem conciliar eventos customer.subscription.created, customer.subscription.updated e customer.subscription.deleted. Somente IDs de assinaturas são retidos dos disparos de eventos assinados; o estado atual da assinatura é obtido pela conta verificada correspondente. Retratos de assinaturas nunca criam lançamentos de recebimentos em dinheiro.
GET /api/projects/:id/subscriptions retorna valores recorrentes mensais brutos contratados, separados por moeda, antes de descontos e impostos. Somente itens recorrentes fixos do tipo licensed: retratos pausados, medidos por consumo, por faixas, transformados, desconhecidos ou desatualizados são excluídos com avisos de cobertura. Equivalentes de períodos de teste são separados do MRR ativo. A agregação racional exata é arredondada por half-up uma vez por moeda. A normalização de mês/ano/semana/dia é informada explicitamente.
Assinaturas conhecidas são atualizadas em lotes limitados em segundo plano. Leituras malsucedidas excluem imediatamente aquela assinatura; retratos com mais de 24 horas não são apresentados como atuais. Proprietários podem iniciar uma varredura de descoberta retomável em Recurring contracts. Conclusão significa que as assinaturas atuais disponíveis foram paginadas, não que todo ciclo de vida histórico ou registro mutável do provedor foi reconstruído. A descoberta exige permissão de leitura para listar e obter assinaturas.
Metas declarativas e filas seguras
Após consentimento explícito, data-reylin-event em um elemento clicável dispara uma meta nomeada por clique. data-reylin-view-event dispara uma vez por concessão de consentimento quando pelo menos metade do elemento está visível. O atributo opcional data-reylin-page fornece um rótulo explícito de caminho seguro. Valores de formulários, destinos de links e texto do DOM nunca são coletados. A retirada do consentimento desconecta observadores e cancela solicitações pendentes quando há suporte.
Entradas de fila anteriores ao carregamento ou com consentimento negado são descartadas, não reproduzidas depois. Após o carregamento, reylinQueue.push([track, eventName, dimensions]) dispara apenas enquanto o consentimento atual é true. Não há adição de visualização automática de página ou consentimento automático.
Sessões observadas e busca privada de visitantes
GET /api/projects/:id/session-metrics informa uma coorte de entradas de sessão dentro de [from,to). As sessões agrupam eventos consentidos pelo ID pseudônimo do navegador e por um intervalo estritamente maior que 30 minutos. O histórico anterior armazenado evita criar uma nova sessão artificial apenas porque uma janela de relatório começou; retenção e exclusão ainda podem remover evidências de continuidade.
Uma rejeição é uma sessão encerrada por inatividade com exatamente uma visualização de página e nenhum evento que não seja visualização de página. Sessões abertas são excluídas do denominador de rejeição. O intervalo médio observado é a diferença entre o primeiro e o último evento registrado, não o tempo no site nem uma estimativa de atenção. A primeira visualização observada e os últimos rótulos de página observados não comprovam o comportamento real de entrada ou saída. Dados ausentes são Unknown, não geolocalização ou um perfil de navegador inventado.
GET /api/projects/:id/visitors é privado e exige uma sessão de projeto/Viewer ou token read:journeys. Ele suporta source, eventType, customerStatus all/paid/unpaid, busca por identificador, limit e cursor vinculado à consulta. Filtros de fonte e tipo de evento exigem o mesmo evento observado. As contagens descrevem os eventos observados daquele visitante na janela escolhida. Paid significa pagamentos vinculados nos registros financeiros naquela mesma janela; eventos purchase do navegador não o estabelecem. As contagens de pagamentos são separadas por moeda.
Métricas agregadas de sessão permitem tokens read:reports e nunca incluem IDs individuais de visitantes. Linhas de visitantes são observações pseudônimas, não pessoas verificadas, e-mails, correspondência de identidade ou perfis de CRM.
Dimensões de aquisição e receita congelada
Dimensões explícitas de eventos podem incluir campaign, medium, content e term como slugs não pessoais em minúsculas com até 64 caracteres, hostname como hostname DNS e categorias amplas de navegador/sistema operacional. São rótulos declarados: o Reylin não os infere de uma impressão digital nem captura automaticamente consultas brutas de busca. Dimensões ausentes continuam Unknown. Os campos existentes page, referrer e device continuam suportados.
Novos registros de pagamentos verificados congelam o retrato consentido das dimensões do primeiro contato dentro da janela de atribuição configurada. Um evento posterior, histórico de eventos excluído ou metadados alterados do provedor não podem reescrevê-lo. Pagamentos antigos sem retrato de dimensões continuam Unknown para essa dimensão; nenhuma atribuição histórica é fabricada.
GET /api/projects/:id/acquisition aceita dimension, metric, from, to e currency. É uma leitura agregada para sessões de projeto/Viewers e tokens read:reports. O relatório usa uma coorte de pagamentos: pagamentos dentro da janela semiaberta e seus reembolsos elegíveis no estado succeeded antes do fim dela, limitados por pagamento. Não é um relatório de movimentação de caixa de reembolsos. O dinheiro é mantido separado por moeda. A conversão exige um visitante consentido observado no mesmo grupo de dimensão e janela; proporções com denominador zero ficam indisponíveis, não viram zeros inventados.
Os relatórios retornam no máximo 100 grupos ordenados, além de contagens e totais explícitos dos grupos omitidos. Visitantes podem aparecer em vários grupos de dimensão, portanto a soma dos visitantes dos grupos não precisa ser igual ao total global de visitantes únicos. Segmentos salvos de consultas de eventos suportam as mesmas dimensões declaradas de aquisição e plataforma.
Propriedades categóricas de metas
Primeiro, os proprietários declaram esquemas apenas com enum em Goal properties, por exemplo signup → plan → starter ou growth. Chaves de esquemas de eventos e propriedades usam snake case em minúsculas com até 32 caracteres; no máximo 20 esquemas de eventos, 8 propriedades por esquema e 20 valores por propriedade. Rótulos são slugs curtos em minúsculas, nunca identificadores pessoais ou segredos. Pertencer a um enum não comprova anonimato: o proprietário do projeto é responsável por rótulos não pessoais. Chaves ou valores desconhecidos são rejeitados antes da persistência e do consumo da cota.
Envie propriedades como terceiro argumento do rastreador, por exemplo reylin.track("signup", {page:"/pricing"}, {plan:"starter"}). Consentimento é obrigatório. Nenhum texto do DOM ou valor de formulário é coletado automaticamente. O servidor valida com base no esquema atual daquele projeto. Edições do esquema afetam eventos futuros, não registros históricos.
GET /api/projects/:id/goal-properties aceita eventType, property, from e to (janela UTC semiaberta). Categorias configuradas e um grupo distinto para ausências contêm contagens de eventos e visitantes únicos, nunca IDs de visitantes. Categorias históricas removidas contam como excludedEvents/excludedVisitors sem repetir rótulos removidos. Proprietários, Viewers e tokens read:reports podem ler esse agregado; somente proprietários podem usar GET/POST /property-schemas. Propriedades brutas continuam fazendo parte de leituras de eventos com escopo de jornadas.
Trabalhos de limpeza de visitantes pelo proprietário
GET /api/projects/:id/visitor-erasure lista os estados sanitizados dos trabalhos daquele proprietário; acrescente o ID do trabalho para um único estado. POST à coleção inicia um trabalho com visitorId, um requestId aleatório estável e retainFinancialRecords:true. O pseudônimo bruto do visitante deve ficar no corpo JSON, nunca em uma URL. Somente sessões de proprietários verificados; Viewers e tokens bearer de API não podem iniciar nem examinar esses trabalhos.
O mesmo ID de solicitação e destino são idempotentes; um destino conflitante é rejeitado. O estado público omite resumos de supressão e tokens de workers. A conclusão preserva dinheiro e atribuição congelada enquanto desvincula o pseudônimo conhecido; não é uma garantia de apagamento jurídico, físico ou no provedor. Leia o guia de ciclo de vida dos dados e a confirmação dos dados retidos antes de usar.
A coleta e as gravações financeiras pausam no projeto afetado enquanto barreiras locais à transação e lotes retomáveis são executados. Trabalhos aguardando envios incertos continuam visivelmente pendentes. Retenção manual e exclusão de projeto ou conta não podem ocorrer em corrida com uma limpeza ativa. Os limites de escopo incluem recibos antigos sem índice, notas e rótulos escritos por usuários, cópias externas e backups.
Inventário de exportação de dados do proprietário
GET /api/account/data-export retorna as seções locais suportadas, projeções de campos, disponibilidade e exclusões. Adicione section, projectId opcional de um projeto do proprietário, limit (1–100) e cursor para ler uma página. O servidor determina o proprietário a partir da sessão autenticada, nunca de um ID de proprietário fornecido. Funções Viewer e tokens de API somente leitura não autorizam essa rota no nível da conta.
O cursor é vinculado à seção, ao proprietário e ao projeto. Linhas são selecionadas por SQL estático e listas de campos JSON permitidos; não existe parâmetro arbitrário de banco, tabela, caminho ou coluna. Armazenamento ausente ou com esquema incompatível retorna cobertura explicitamente indisponível. Hashes de credenciais, textos criptografados, tokens brutos e detalhes internos de workers são omitidos. O resultado não é um retrato atômico nem uma alegação universal de completude.
Relatórios e alertas do proprietário
Proprietários de projetos podem optar por um relatório semanal com dia da semana, hora UTC e moeda explícitos, ou por alertas de eventos nomeados. Mensagens vão somente para o e-mail verificado da conta; não há campo de destinatário arbitrário. Novos alertas de metas começam no ponto de controle de recebimento do servidor, portanto ativar uma regra nunca reproduz eventos anteriores. Um evento atrasado pode gerar alerta se chegar depois da ativação da regra. Metas do navegador não comprovam receita.
A entrega é desativada independentemente por padrão. Regras de simulação podem enfileirar relatórios, mas não enviam e-mail. Uma mensagem aceita significa que o provedor de e-mail a aceitou, não que chegou à caixa de entrada. Limites de fila pendente e de entrega diária do proprietário suprimem notificações excedentes; não são criadas cobranças por excesso. Disable all em Reports & alerts cancela mensagens na fila. Mensagens aceitas anteriormente não podem ser recolhidas.
Somente sessões de proprietários podem acessar /api/projects/:id/notifications. Tokens bearer somente leitura e Viewers não podem configurar relatórios nem ler a fila privada. As ações POST são weekly, goal, remove_goal e unsubscribe.
Links públicos de agregados e widgets
Proprietários criam explicitamente um compartilhamento nas configurações Sharing do projeto. Qualquer pessoa com sua URL bearer pode ler somente agregados de visitantes, eventos, pagamentos, recebimentos brutos/reembolsados/líquidos, moeda e período. Nenhuma fonte, visitante individual, nota ou registro subjacente é incluído. Links e incorporações de widgets não são publicados automaticamente. A rotação ou revogação invalida imediatamente a URL antiga, mas não apaga cópias que alguém já visualizou.
A página compartilhada e a incorporação são noindex e usam cabeçalhos no-referrer/no-store. O widget permite incorporação em frame por design somente após o proprietário criar essa capacidade. As rotas privadas do painel continuam impedindo frames. Uma contagem agregada zero nos registros financeiros não estabelece que um negócio real desconectado não teve vendas.
SDK e CLI somente leitura
reylin-client.mjs é um SDK de servidor sem dependências que expõe summary/events/journey/trend/search. reylin-cli.mjs expõe as mesmas operações de leitura e imprime JSON. Defina REYLIN_API_TOKEN no ambiente, nunca em argumentos de linha de comando ou pacotes do navegador. Tokens não podem alterar cobrança, configurações de provedores ou contas de usuários. Essas ferramentas de código-fonte são locais; nenhum pacote no registro npm ou conexão MCP de terceiros foi publicado.
node reylin-cli.mjs summary --origin https://YOUR_APPROVED_HOST --project PROJECT_ID --days 30 --currency USDErros e tratamento de dados
Nunca repita uma ação cobrável com uma nova chave de idempotência apenas porque sua resposta se perdeu. Não coloque segredos em strings de consulta, eventos personalizados ou capturas de tela para suporte. Exportações e jornadas pseudônimas são dados de projeto autenticados; restrinja seu acesso e respeite políticas de retenção e exclusão. Não há API pública de leitura de análises sem autenticação.
Referências
Esta documentação descreve o código e seus limites; não confirma uma conexão ativa. Os exemplos técnicos mantêm os identificadores originais.