Aggiungere PostHog e Clerk a una nuova app comporta la configurazione di due sistemi separati che risolvono problemi diversi. Clerk gestisce l'accesso degli utenti alla tua app, mentre PostHog tiene traccia di ciò che gli utenti fanno una volta all'interno. Puoi configurarli manualmente tramite le rispettive Dashboard e i software development kit (SDK), oppure effettuarne il provisioning con Stripe Projects, che estrae le credenziali di entrambi i fornitori direttamente nel file .env del tuo progetto, senza dover passare da una Dashboard all'altra.
PostHog è utilizzato da oltre 500.000 team e quasi 250.000 ingegneri. Molti team alla fine associano PostHog a un fornitore di autenticazione, come Clerk. Stripe Projects semplifica questa configurazione effettuando il provisioning di entrambi i servizi in un singolo flusso di lavoro.
Di seguito, spiegheremo le funzioni di ciascun fornitore, perché collegare l'identità autenticata agli eventi di analisi ti aiuta a comprendere molto più del solo traffico, e come aggiungere PostHog e Clerk in modo rapido tramite Stripe Projects.
In sintesi:
Collegare gli identificatori utente (ID) autenticati di Clerk al metodo
identify()di PostHog trasforma i dati anonimi delle sessioni in profili utente identificati, senza perdere la cronologia degli eventi precedente all'accesso.Stripe Projects può effettuare il provisioning di PostHog e Clerk tramite i comandi dell'interfaccia della riga di comando (CLI), i quali gestiscono l'autorizzazione dell'account e scrivono le credenziali direttamente nel file
.envdel tuo progetto.Le best practice per PostHog e Clerk includono la netta separazione degli ambienti e la riduzione al minimo dei dati personali nelle proprietà degli eventi.
Cosa sono PostHog e Clerk?
PostHog è una piattaforma di analisi dei prodotti. Monitora gli eventi, le visualizzazioni di pagina e il comportamento degli utenti all'interno di un'app, quindi trasforma quei dati in canalizzazioni, registrazioni delle sessioni, flag di funzioni e analisi di coorte. Clerk è un fornitore di autenticazione e gestione degli utenti. Gestisce la registrazione, l'accesso, i token di sessione, l'autenticazione a più fattori e i dati dei profili utente.
Perché combinare l'analisi di PostHog con l'autenticazione di Clerk?
Combinare PostHog con Clerk ti fornisce analisi sul traffico nella parte alta della canalizzazione, come la previsione dell'abbandono, l'analisi dell'attivazione o l'adozione delle funzioni, suddivise per livello di account. PostHog monitora gli utenti tramite un ID distinto, che inizia come identificatore anonimo generato casualmente e legato a un browser o dispositivo. Quando un utente accede tramite Clerk, puoi richiamare il metodo identify() di PostHog e passare l'ID utente di Clerk come nuovo ID distinto. PostHog unisce quindi la cronologia della sessione anonima con il profilo identificato, collegando gli eventi monitorati prima dell'accesso, come visualizzazioni di pagina, clic sui pulsanti e interazioni con le funzioni, a quell'utente.
Presta molta attenzione a questi dettagli:
Coerenza nella denominazione degli eventi: decidi fin da subito se gli eventi seguono lo snake case (ad es., senza spazi) o il title case, e se descrivono azioni come
signed\_upo oggetti comesignup\_completed. Mescolare le convenzioni rende le tue Dashboard di PostHog illeggibili.Utenti anonimi rispetto a utenti identificati: se richiami
identify()a ogni caricamento della pagina, accumulerai eventi di unione duplicati nel log delle attività di PostHog. Richiamalo una sola volta, subito dopo che Clerk ha confermato una sessione. Puoi anche vincolare la chiamata a un controllo che verifichi se l'utente è già stato identificato nella sessione in corso.Privacy e consenso: nelle giurisdizioni con requisiti di consenso per il monitoraggio, come previsto dal GDPR nell'UE, acquisisci il consenso prima di identificare un utente o di allegare dati personali alle proprietà dell'evento. L'inserimento di un'email o di un nome in ogni evento di analisi è raramente necessario e amplia la tua superficie di conformità.
Quando collegare i due sistemi: se la tua app è composta principalmente da pagine di marketing precedenti alla registrazione, il monitoraggio anonimo è sufficiente. Collega gli eventi di Clerk e PostHog quando disponi di flussi autenticati che vale la pena misurare, come la conversione da prova a pagamento.
Come si configurano manualmente PostHog e Clerk?
Configurerai manualmente entrambi i provider su quattro sistemi: due dashboard e due SDK.
Ecco come funziona:
1. Crea un progetto PostHog
Registrati su PostHog e crea un progetto. Questo ti fornisce una chiave per l'application programming interface (API) e un URL host del progetto. Avrai bisogno di entrambi i valori per l'SDK.
2. Crea un'applicazione Clerk
Nella Dashboard di Clerk, crea un'applicazione e scegli i tuoi metodi di accesso, come email, Google OAuth o passkey.
3. Installa gli SDK
Esegui npm install posthog-js e npm install @clerk/nextjs per un'app Next.js. PostHog si inizializza lato client tramite posthog.init(), mentre Clerk avvolge la tua app in un componente \<ClerkProvider\> e richiede un middleware per gestire la protezione del percorso.
4. Imposta le variabili d'ambiente
Aggiungi da quattro a sei valori al tuo file .env.local.
5. Testa la configurazione
Conferma che il flusso di accesso di Clerk produca una sessione, quindi controlla la visualizzazione degli eventi in tempo reale di PostHog per confermare che gli eventi vengano ricevuti. Verifica che identify() venga attivato esattamente una volta per sessione, subito dopo la risoluzione dell'autenticazione.
Come si esplorano i fornitori di analisi con Stripe Projects?
Stripe Projects è una funzione della Stripe CLI per il provisioning di servizi di infrastruttura di terze parti, inclusi database, strumenti di analisi e fornitori di intelligenza artificiale, direttamente dalla riga di comando. Invece di aprire Dashboard separate per ogni servizio, puoi esplorarli ed effettuarne il provisioning da un'unica interfaccia legata al tuo progetto.
Usa Stripe Projects per esplorare le opzioni dei fornitori per l'analisi eseguendolo dalla directory del tuo progetto per elencare i fornitori disponibili, organizzati per categoria e livello di servizio. Puoi restringere la ricerca con stripe projects catalog \<provider\> o stripe projects catalog \<category\>, oppure cercare direttamente con stripe projects search \<keyword\>. Se stai cercando in modo specifico gli strumenti di analisi, vedrai PostHog accanto ad altri fornitori supportati, eliminando la necessità di uscire dal terminale o passare a un browser.
Come si aggiungono PostHog e Clerk con Stripe Projects?
Dopo aver scelto PostHog e Clerk, sono necessari due comandi per effettuare il provisioning di entrambi da un progetto già inizializzato con la Stripe CLI. Per aggiungere PostHog, esegui stripe projects add posthog/analytics per avviare il flusso di provisioning. Stripe Projects gestisce il passaggio di autorizzazione dell'account che normalmente richiederebbe di accedere direttamente a PostHog e copiare le chiavi manualmente. Quindi scrive la chiave API e l'URL host risultanti nel file .env del tuo progetto. L'esecuzione di stripe projects add clerk/auth fa lo stesso per Clerk: gestisce il flusso di autorizzazione e recupera le chiavi pubblicabili e segrete. Queste vengono scritte in .env insieme a tutto ciò che PostHog ha appena aggiunto.
La differenza pratica tra la configurazione con Stripe Projects e quella manuale consiste nella provenienza delle credenziali. Invece di copiare le chiavi da due Dashboard e incollarle in .env.local, Stripe Projects le recupera e le scrive direttamente, anche se tu (o il tuo agente di programmazione) dovrete comunque scrivere il codice di inizializzazione dell'SDK e collegare la logica dell'app.
Inoltre, vorrai mantenere sincronizzate le tue chiavi. Se configuri il progetto su una nuova macchina per la prima volta, stripe projects pull \<projectID\> clona il progetto esistente in una directory vuota e scrive il tuo file .env, che si connette ai servizi esistenti del progetto anziché effettuarne il provisioning di nuovi. Se sei già nella directory del progetto e hai bisogno di aggiornare il tuo .env locale dopo che un membro del team ha aggiunto o ruotato un fornitore, esegui invece stripe projects pull env \--pull.
Quali sono le best practice per PostHog e Clerk?
Vale la pena configurare correttamente alcune cose prima di implementare questa integrazione.
Ecco gli aspetti da tenere presenti:
Separa in modo netto gli ambienti: utilizza progetti PostHog e applicazioni Clerk diversi per lo sviluppo e la produzione. Mescolare le registrazioni di prova con i dati degli utenti reali rende le tue analisi inaffidabili e riempie l'elenco utenti di Clerk con account usa e getta.
Non esporre mai la chiave segreta di Clerk lato client: deve trovarsi solo nelle variabili d'ambiente lato server. La chiave pubblicabile è sicura per il browser; la chiave segreta no.
Riduci al minimo i dati personali nelle proprietà degli eventi: invia un ID utente anziché un indirizzo email, poiché il solo ID ti consente di ricongiungere i dati alla tabella utenti di Clerk in un secondo momento, se necessario.
Rispetta il consenso prima di identificare gli utenti: se la tua giurisdizione richiede il consenso per il monitoraggio, vincola la chiamata
identify()a tale consenso.Testa esplicitamente il comportamento di unione: registrati come utente anonimo, genera alcuni eventi, quindi accedi e conferma che PostHog unisca tale cronologia sotto il profilo identificato anziché avviarne uno nuovo disconnesso.
Documenta lo schema degli eventi: un riferimento condiviso per i nomi e le proprietà degli eventi impedisce a parti diverse del tuo team di monitorare la stessa azione con tre nomi diversi.
In che modo Stripe Projects può essere d'aiuto
Stripe Projects consente agli sviluppatori e ai loro agenti IA di aggiungere servizi, generare credenziali e gestire la fatturazione dall'interfaccia a riga di comando (CLI).
Stripe Projects ti aiuta a:
Effettua il provisioning di servizi di terze parti dalla riga di comando: utilizza un unico flusso di lavoro per aggiungere servizi, gestire credenziali e aggiornare i piani, anziché strumenti e flussi di lavoro diversi per ogni fornitore. Gestisci hosting, database, autenticazione, intelligenza artificiale e altro ancora senza bisogno di Dashboard, file di configurazione o codice dell'infrastruttura.
Sincronizza le credenziali automaticamente: mantieni le variabili d'ambiente trasferibili tra configurazioni locali, macchine, membri del team e agenti, evitando di copiare e incollare le chiavi per l'application programming interface (API).
Gestisci la fatturazione dalla CLI o dal tuo agente di programmazione: imposta i dettagli di fatturazione una volta e condividili in modo sicuro con servizi di terze parti. Esegui l'upgrade e il downgrade dei livelli, monitora l'utilizzo e gestisci gli abbonamenti dalla CLI.
Scopri di più su come Stripe Projects ti aiuta a semplificare il provisioning delle app, oppure copia e incolla questo comando nel tuo terminale per iniziare oggi stesso:
I contenuti di questo articolo hanno uno scopo puramente informativo e formativo e non devono essere intesi come consulenza legale o fiscale. Stripe non garantisce l'accuratezza, la completezza, l'adeguatezza o l'attualità delle informazioni contenute nell'articolo. Per assistenza sulla tua situazione specifica, rivolgiti a un avvocato o a un commercialista competente e abilitato all'esercizio della professione nella tua giurisdizione.