Adicionar o PostHog e o Clerk a um novo aplicativo envolve configurar dois sistemas separados que resolvem problemas diferentes. O Clerk gerencia o login do usuário no seu aplicativo, enquanto o PostHog rastreia o que os usuários fazem depois de entrarem. Você pode configurá-los manualmente por meio dos seus dashboards e kits de desenvolvimento de software (SDKs), ou provisioná-los com o Stripe Projects, que extrai as credenciais de ambos os provedores diretamente para o arquivo .env do seu projeto sem que você precise alternar entre dashboards.
O PostHog é usado por mais de 500.000 equipes e quase 250.000 engenheiros. Muitas equipes acabarão combinando o PostHog a um provedor de autenticação, como o Clerk. O Stripe Projects simplifica essa configuração provisionando ambos os serviços em um único fluxo de trabalho.
Abaixo, discutiremos o que cada provedor faz, por que conectar a identidade autenticada a eventos de análise ajuda você a entender mais do que apenas o tráfego e como adicionar o PostHog e o Clerk rapidamente usando o Stripe Projects.
Principais conclusões
Conectar os identificadores de usuário (IDs) autenticados do Clerk ao método
identify()do PostHog transforma dados de sessões anônimas em perfis de usuários identificados sem perder o histórico de eventos anterior ao login.O Stripe Projects pode provisionar o PostHog e o Clerk por meio de comandos da interface de linha de comando (CLI) que processam a autorização da conta e gravam credenciais diretamente no arquivo
.envdo seu projeto.As práticas recomendadas para o PostHog e o Clerk incluem separar os ambientes de forma limpa e minimizar dados pessoais em propriedades de eventos.
O que são o PostHog e o Clerk?
O PostHog é uma plataforma de análise de produtos. Ele rastreia eventos, visualizações de página e o comportamento do usuário dentro de um aplicativo e, em seguida, transforma esses dados em funis, gravações de sessões, sinalizadores de recursos e análises de coorte. O Clerk é um provedor de autenticação e gestão de usuários. Ele processa inscrições, logins, tokens de sessão, autenticação multifator e dados do perfil do usuário.
Por que você deve combinar as análises do PostHog com a autenticação do Clerk?
Combinar o PostHog com o Clerk fornece a você análises sobre o tráfego do topo de funil, como previsão de churn, análise de onboarding ou adoção de recursos, divididas por nível de conta. O PostHog rastreia os usuários por meio de um ID distinto, que começa como um identificador anônimo, gerado aleatoriamente e vinculado a um navegador ou dispositivo. Quando um usuário faz login pelo Clerk, você pode chamar o método identify() do PostHog e passar o ID de usuário do Clerk como o novo ID distinto. O PostHog então mescla o histórico da sessão anônima com o perfil identificado, vinculando eventos rastreados antes do login (como visualizações de página, cliques em botões e interações com recursos) a esse usuário.
Preste muita atenção a estas especificidades:
Consistência na nomenclatura de eventos: decida cedo se os eventos serão em snake case (por exemplo, sem espaços) ou em title case e se eles descrevem ações como
signed\_upou objetos comosignup\_completed. Misturar convenções torna seus dashboards do PostHog ilegíveis.Usuários anônimos versus identificados: se você chamar
identify()em cada carregamento de página, acumulará eventos de mesclagem duplicados no log de atividades do PostHog. Chame-o uma vez, logo após o Clerk confirmar uma sessão. Você também pode condicionar a chamada a uma verificação de que o usuário já foi identificado na sessão atual.Privacidade e consentimento: em jurisdições com requisitos de consentimento para rastreamento, como sob o GDPR na UE, capture o consentimento antes de identificar um usuário ou anexar dados pessoais às propriedades do evento. Um e-mail ou nome em cada evento de análise raramente é necessário e amplia sua superfície de conformidade.
Quando conectar os dois: se o seu aplicativo consiste principalmente em páginas de marketing antes do registro, o rastreamento anônimo será suficiente. Conecte os eventos do Clerk e do PostHog quando tiver fluxos autenticados que valham a pena medir, como a conversão de teste para pago.
Como configurar o PostHog e o Clerk manualmente?
Você configurará manualmente os dois provedores em quatro sistemas: dois dashboards e dois SDKs.
Veja como funciona:
1. Crie um projeto no PostHog
Registre-se no PostHog e crie um projeto. Isso fornecerá a você uma chave de interface de programação de aplicações (API) do projeto e um URL de host. Você precisará de ambos os valores para o SDK.
2. Crie um aplicativo no Clerk
No dashboard do Clerk, crie um aplicativo e escolha seus métodos de login, como e-mail, Google OAuth ou chaves de acesso.
3. Instale os SDKs
Execute npm install posthog-js e npm install @clerk/nextjs para um aplicativo Next.js. O PostHog é inicializado do lado do cliente por meio de posthog.init(), enquanto o Clerk encapsula seu aplicativo em um \<ClerkProvider\> e exige um middleware para processar a proteção de rotas.
4. Defina variáveis de ambiente
Adicione de quatro a seis valores ao seu arquivo .env.local.
5. Teste a configuração
Confirme se o fluxo de login do Clerk produz uma sessão e, em seguida, verifique a visualização de eventos em tempo real do PostHog para confirmar que os eventos estão chegando. Verifique se identify() é acionado exatamente uma vez por sessão, logo após a autenticação ser resolvida.
Como pesquisar provedores de análises com o Stripe Projects?
O Stripe Projects é um recurso da Stripe CLI para provisionar serviços de infraestrutura de terceiros, incluindo bancos de dados, análises e provedores de IA, diretamente na linha de comando. Em vez de abrir dashboards separados para cada serviço, você os pesquisa e os provisiona de uma interface vinculada ao seu projeto.
Use o Stripe Projects para pesquisar opções de provedores de análise executando-o a partir do diretório do seu projeto para listar os provedores disponíveis, organizados por categoria e nível de serviço. Você pode refiná-los com stripe projects catalog \<provider\> ou stripe projects catalog \<category\>, ou pesquisar diretamente com stripe projects search \<keyword\>. Se estiver procurando por análises especificamente, verá o PostHog junto com outros provedores compatíveis, o que elimina a necessidade de sair do seu terminal ou mudar para um navegador.
Como adicionar o PostHog e o Clerk com o Stripe Projects?
Depois de escolher o PostHog e o Clerk, serão necessários dois comandos para provisionar ambos de um projeto já inicializado com a Stripe CLI. Para adicionar o PostHog, execute stripe projects add posthog/analytics para iniciar o fluxo de provisionamento. O Stripe Projects gerencia a etapa de autorização da conta que normalmente exigiria que você fizesse login diretamente no PostHog e copiasse as chaves manualmente. Em seguida, ele grava a chave de API e o URL de host resultantes no arquivo .env do seu projeto. Executar stripe projects add clerk/auth faz o mesmo com o Clerk: ele gerencia o fluxo de autorização e recupera as chaves publicáveis e secretas. Elas são gravadas em .env junto com o que o PostHog acabou de adicionar.
A diferença prática entre a configuração com o Stripe Projects e a configuração manual é a origem das credenciais. Em vez de copiar as chaves de dois dashboards e colá-las em .env.local, o Stripe Projects as recupera e as grava diretamente, embora você (ou seu agente de codificação) ainda precise escrever o código de inicialização do SDK e conectar a lógica do seu aplicativo por conta própria.
Você também deve manter suas chaves sincronizadas. Se estiver configurando o projeto em uma nova máquina pela primeira vez, stripe projects pull \<projectID\> clona o projeto existente para um diretório vazio e grava o arquivo .env, que se conecta aos serviços existentes do projeto em vez de provisionar novos. Se você já estiver no diretório do projeto e precisar atualizar seu .env local após um colega de equipe adicionar ou alternar um provedor, execute stripe projects pull env \--pull.
Quais são as práticas recomendadas para o PostHog e o Clerk?
Vale a pena acertar algumas coisas antes de lançar essa integração.
Aqui está o que você deve ter em mente:
Separe os ambientes de forma limpa: use projetos diferentes do PostHog e aplicativos do Clerk para desenvolvimento e produção. Misturar inscrições de teste com dados de usuários reais torna suas análises não confiáveis e sobrecarrega sua lista de usuários do Clerk com contas descartáveis.
Nunca exponha a chave secreta do Clerk do lado do cliente: ela pertence apenas às variáveis de ambiente do lado do servidor. A chave publicável é segura para o navegador; a chave secreta não.
Minimize dados pessoais nas propriedades de eventos: envie um ID de usuário em vez de um endereço de e-mail, pois somente o ID permite que você una os dados de volta à tabela de usuários do Clerk mais tarde, se precisar.
Respeite o consentimento antes de identificar usuários: se a sua jurisdição exigir consentimento de rastreamento, condicione a chamada
identify()a esse consentimento.Teste explicitamente o comportamento de mesclagem: inscreva-se como um usuário anônimo, gere alguns eventos e, em seguida, faça login e confirme que o PostHog mescla esse histórico no perfil identificado em vez de iniciar um novo desconectado.
Documente o esquema dos seus eventos: uma referência compartilhada para os nomes e as propriedades dos eventos impede que diferentes partes da sua equipe rastreiem a mesma ação sob três nomes diferentes.
Como o Stripe Projects pode ajudar
O Stripe Projects permite que desenvolvedores e seus agentes de IA adicionem serviços, gerem credenciais e gerenciem o faturamento a partir da interface de linha de comando (CLI).
O Stripe Projects ajuda você a:
Provisionar serviços de terceiros na linha de comando: use um fluxo de trabalho para adicionar serviços, gerenciar credenciais e fazer o upgrade de planos, em vez de ferramentas e fluxos de trabalho diferentes para cada provedor. Gerencie hospedagem, bancos de dados, autenticação, IA e muito mais sem precisar de dashboards, arquivos de configuração ou código de infraestrutura.
Sincronizar credenciais automaticamente: mantenha as variáveis de ambiente portáteis em diferentes configurações locais, máquinas, colegas de equipe e agentes, sem copiar e colar chaves de interface de programação de aplicações (API).
Gerenciar o faturamento na CLI ou com seu agente de codificação: configure os dados de faturamento uma vez e compartilhe-os de forma segura com serviços de terceiros. Faça upgrade e downgrade de níveis, monitore o uso e gerencie assinaturas pela CLI.
Saiba mais sobre como o Stripe Projects ajuda a simplificar o provisionamento de aplicativos ou copie e cole este comando em seu terminal para começar hoje mesmo:
O conteúdo deste artigo é apenas para fins gerais de informação e educação e não deve ser interpretado como aconselhamento jurídico ou tributário. A Stripe não garante a exatidão, integridade, adequação ou atualidade das informações contidas no artigo. Você deve procurar a ajuda de um advogado competente ou contador licenciado para atuar em sua jurisdição para aconselhamento sobre sua situação particular.