dApp: PostHog integration (#871)

Closes: #747
Closes: AENG-30

### Overview
This PR integrates dApp with PostHog service to track users activities
and analyze it. The PostHog project was created. All dApp activity is
now accessible through [the
dashboard](https://us.posthog.com/project/104474).
The API key and endpoint are available in the project settings.

### Features
- dApp integration using [PostHog's official React
SDK](https://www.npmjs.com/package/posthog-js)
- Autocapture: all user interactions are tracked, any button click, any
form fill
- Manually triggered `$pageview` capture event: autocapture for page
view event was disabled to prevent false positive captures. It is
triggered manually as user visits the dApp.
- User identification via wallet address
- Added custom events with additional payload information: 
  - `deposit_success` - payload: `{ transactionHash }`
  - `deposit_failure` - payload: `{ cause }`
- `withdrawal_success` - wasn't able to easily get any reasonable
payload here, can be done later
  - `withdrawal_failure` - payload: `{ cause }`
  - `points_claim_success` - payload: `{ claimedAmount, totalAmount }`
  - `points_claim_failure` - payload: `{ cause }`
- Defined feature flag to toggle PostHog integration

### Changes
- Added new env variables to define API key and endpoint and a feature
flag
- Defined preconfigured `PostHogProvider` to inject the service into
application
- Defined hooks: `usePostHogCapture`, `usePostHogIdentity`,
`usePostHogPageViewCapture`
- Integrated key actions to capture PostHog custom events (see above)

### Caveats
To ensure the `$pageview` event is captured properly it's needed to call
it as a side effect as the `location` value changes. To access this
value (via `useLocation` hook) the router's context needs to be in scope
of PostHog's context.
The only way to achieve it was to do it in the `Layout` component where
both contexts are available.

### Note
It's impossible to exclude captures for development environment. To keep
data logs clean and ensure it contains only user's data I suggest to
**keep the feature flag disabled** while using development environment.

dapp/.env

@@ -18,6 +18,10 @@ VITE_GELATO_RELAY_API_KEY="htaJCy_XHj8WsE3w53WBMurfySDtjLP_TrNPPa6IPIc_"  # this
 # Get the API key from: https://thegraph.com/studio/apikeys/.
 VITE_SUBGRAPH_API_KEY=""
 
+# Posthog
+VITE_POSTHOG_API_HOST="https://us.i.posthog.com"
+VITE_POSTHOG_API_KEY=""
+
 # Feature flags
 VITE_FEATURE_FLAG_GAMIFICATION_ENABLED="false"
 VITE_FEATURE_FLAG_WITHDRAWALS_ENABLED="false"
@@ -26,5 +30,6 @@ VITE_FEATURE_FLAG_XVERSE_WALLET_ENABLED="false"
 VITE_FEATURE_FLAG_ACRE_POINTS_ENABLED="true"
 VITE_FEATURE_FLAG_TVL_ENABLED="true"
 VITE_FEATURE_GATING_DAPP_ENABLED="true"
+VITE_FEATURE_POSTHOG_ENABLED="true"
 VITE_FEATURE_MOBILE_MODE_ENABLED="true"
 

dapp/package.json

@@ -40,6 +40,7 @@
     "framer-motion": "^10.16.5",
     "luxon": "^3.5.0",
     "mustache": "^4.2.0",
+    "posthog-js": "^1.186.1",
     "react": "^18.2.0",
     "react-confetti-explosion": "^2.1.2",
     "react-dom": "^18.2.0",

dapp/src/DApp.tsx

@@ -19,6 +19,7 @@ import getWagmiConfig from "./wagmiConfig"
 import queryClient from "./queryClient"
 import { delay, logPromiseFailure } from "./utils"
 import { AcreLogo } from "./assets/icons"
+import PostHogProvider from "./posthog/PostHogProvider"
 
 function SplashPage() {
   return (
@@ -69,7 +70,9 @@ function DAppProviders() {
               <SidebarContextProvider>
                 <WalletConnectionAlertContextProvider>
                   <ReduxProvider store={store}>
-                    <DApp />
+                    <PostHogProvider>
+                      <DApp />
+                    </PostHogProvider>
                   </ReduxProvider>
                 </WalletConnectionAlertContextProvider>
               </SidebarContextProvider>

dapp/src/components/ConnectWalletModal/ConnectWalletButton.tsx

@@ -24,6 +24,7 @@ import {
 } from "@chakra-ui/react"
 import { IconArrowNarrowRight } from "@tabler/icons-react"
 import { AnimatePresence, Variants, motion } from "framer-motion"
+import { usePostHogIdentity } from "#/hooks/posthog"
 import ArrivingSoonTooltip from "../ArrivingSoonTooltip"
 import { TextLg, TextMd } from "../shared/Typography"
 import ConnectWalletStatusLabel from "./ConnectWalletStatusLabel"
@@ -72,6 +73,7 @@ export default function ConnectWalletButton({
   const { closeModal } = useModal()
   const dispatch = useAppDispatch()
   const isMounted = useRef(false)
+  const { handleIdentification } = usePostHogIdentity()
 
   const [isLoading, setIsLoading] = useState<boolean>(false)
 
@@ -118,8 +120,11 @@ export default function ConnectWalletButton({
       if (!btcAddress) return
 
       await handleSignMessageAndCreateSession(connector, btcAddress)
+      handleIdentification(btcAddress, {
+        connector: connectedConnector.id,
+      })
     },
-    [connector, handleSignMessageAndCreateSession],
+    [connector, handleSignMessageAndCreateSession, handleIdentification],
   )
 
   const handleConnection = useCallback(() => {

dapp/src/components/Header/ConnectWallet.tsx

@@ -29,6 +29,7 @@ import {
   IconChevronUp,
 } from "@tabler/icons-react"
 import { useMatch } from "react-router-dom"
+import { usePostHogIdentity } from "#/hooks/posthog"
 import Tooltip from "../shared/Tooltip"
 
 function isChangeAccountFeatureSupported(embeddedApp: string | undefined) {
@@ -45,12 +46,18 @@ export default function ConnectWallet() {
     size: "lg",
   })
   const isDashboardPage = useMatch("/dashboard")
+  const { resetIdentity } = usePostHogIdentity()
   const isMobile = useMobileMode()
 
   const handleConnectWallet = (isReconnecting: boolean = false) => {
     openModal(MODAL_TYPES.CONNECT_WALLET, { isReconnecting })
   }
 
+  const handleDisconnectWallet = () => {
+    onDisconnect()
+    resetIdentity()
+  }
+
   if (!address) {
     return (
       <Button
@@ -184,6 +191,17 @@ export default function ConnectWallet() {
                 </Tooltip>
               ),
           )}
+
+          <Tooltip size="xs" label="Disconnect">
+            <IconButton
+              variant="ghost"
+              aria-label="Disconnect"
+              icon={<Icon as={IconLogout} boxSize={5} />}
+              px={2}
+              boxSize={5}
+              onClick={handleDisconnectWallet}
+            />
+          </Tooltip>
         </HStack>
       </Flex>
     </HStack>

dapp/src/components/Layout.tsx

@@ -3,6 +3,7 @@ import { Outlet } from "react-router-dom"
 import { Flex, VStack } from "@chakra-ui/react"
 import { useIsEmbed, useMobileMode } from "#/hooks"
 import { DappMode } from "#/types"
+import { usePostHogPageViewCapture } from "#/hooks/posthog"
 import DocsDrawer from "./DocsDrawer"
 import Header from "./Header"
 import ModalRoot from "./ModalRoot"
@@ -24,6 +25,10 @@ function Layout() {
   const isMobileMode = useMobileMode()
   const { isEmbed, embeddedApp } = useIsEmbed()
 
+  // It needs to be called here because the scope of `RouterProvider` is
+  // required to get `location` from `useLocation` hook.
+  usePostHogPageViewCapture()
+
   if (!isEmbed && isMobileMode) return <MobileModeBanner forceOpen />
 
   const maxWidth = embeddedApp

dapp/src/components/TransactionModal/ActiveStakingStep/DepositBTCModal.tsx

@@ -1,4 +1,5 @@
 import React, { useCallback, useRef } from "react"
+import { ONE_SEC_IN_MILLISECONDS, queryKeysFactory } from "#/constants"
 import {
   useActionFlowPause,
   useActionFlowTokenAmount,
@@ -9,10 +10,11 @@ import {
   useStakeFlowContext,
   useVerifyDepositAddress,
 } from "#/hooks"
-import { eip1193, logPromiseFailure } from "#/utils"
-import { PROCESS_STATUSES } from "#/types"
+import { usePostHogCapture } from "#/hooks/posthog/usePostHogCapture"
+import { PostHogEvent } from "#/posthog/events"
 import { setStatus, setTxHash } from "#/store/action-flow"
-import { ONE_SEC_IN_MILLISECONDS, queryKeysFactory } from "#/constants"
+import { PROCESS_STATUSES } from "#/types"
+import { eip1193, logPromiseFailure } from "#/utils"
 import { useTimeout } from "@chakra-ui/react"
 import { useMutation } from "@tanstack/react-query"
 import WalletInteractionModal from "../WalletInteractionModal"
@@ -28,6 +30,7 @@ export default function DepositBTCModal() {
   const handleBitcoinBalanceInvalidation = useInvalidateQueries({
     queryKey: userKeys.balance(),
   })
+  const { handleCapture, handleCaptureWithCause } = usePostHogCapture()
 
   const sessionId = useRef(Math.random())
   const { cancel, resolve, sessionIdToPromise } = useCancelPromise(
@@ -59,8 +62,11 @@ export default function DepositBTCModal() {
     (transactionHash: string) => {
       dispatch(setTxHash(transactionHash))
       handleStake()
+      handleCapture(PostHogEvent.DepositSuccess, {
+        transactionHash,
+      })
     },
-    [dispatch, handleStake],
+    [dispatch, handleStake, handleCapture],
   )
 
   const onDepositBTCError = useCallback(
@@ -72,8 +78,10 @@ export default function DepositBTCModal() {
       } else {
         onError(error)
       }
+
+      handleCaptureWithCause(error, PostHogEvent.DepositFailure)
     },
-    [sessionIdToPromise, handlePause, onError],
+    [sessionIdToPromise, handlePause, onError, handleCaptureWithCause],
   )
 
   const { mutate: sendBitcoinTransaction, status } = useDepositBTCTransaction({

dapp/src/components/TransactionModal/ActiveUnstakingStep/SignMessageModal.tsx

@@ -16,6 +16,8 @@ import { useInitializeWithdraw } from "#/acre-react/hooks"
 import { ONE_SEC_IN_MILLISECONDS, queryKeysFactory } from "#/constants"
 import { activityInitialized } from "#/store/wallet"
 import { useMutation } from "@tanstack/react-query"
+import { PostHogEvent } from "#/posthog/events"
+import { usePostHogCapture } from "#/hooks/posthog/usePostHogCapture"
 import BuildTransactionModal from "./BuildTransactionModal"
 import WalletInteractionModal from "../WalletInteractionModal"
 
@@ -44,6 +46,7 @@ export default function SignMessageModal() {
     amount,
     ACTION_FLOW_TYPES.UNSTAKE,
   )
+  const { handleCapture, handleCaptureWithCause } = usePostHogCapture()
 
   const dataBuiltStepCallback = useCallback(() => {
     setWaitingStatus("built-data")
@@ -58,7 +61,8 @@ export default function SignMessageModal() {
   const onSignMessageSuccess = useCallback(() => {
     handleBitcoinPositionInvalidation()
     dispatch(setStatus(PROCESS_STATUSES.SUCCEEDED))
-  }, [dispatch, handleBitcoinPositionInvalidation])
+    handleCapture(PostHogEvent.WithdrawalSuccess)
+  }, [dispatch, handleBitcoinPositionInvalidation, handleCapture])
 
   const onSignMessageError = useCallback(
     (error: unknown) => {
@@ -77,8 +81,15 @@ export default function SignMessageModal() {
       } else {
         onSignMessageError(error)
       }
+
+      handleCaptureWithCause(error, PostHogEvent.WithdrawalFailure)
     },
-    [sessionIdToPromise, handlePause, onSignMessageError],
+    [
+      sessionIdToPromise,
+      handlePause,
+      onSignMessageError,
+      handleCaptureWithCause,
+    ],
   )
 
   const { mutate: handleSignMessage } = useMutation({

dapp/src/constants/env.ts

@@ -22,6 +22,10 @@ const LATEST_COMMIT_HASH = import.meta.env.VITE_LATEST_COMMIT_HASH
 
 const ACRE_API_ENDPOINT = import.meta.env.VITE_ACRE_API_ENDPOINT
 
+const POSTHOG_API_HOST = import.meta.env.VITE_POSTHOG_API_HOST
+
+const POSTHOG_API_KEY = import.meta.env.VITE_POSTHOG_API_KEY
+
 export default {
   PROD,
   USE_TESTNET,
@@ -35,4 +39,6 @@ export default {
   NETWORK_TYPE,
   LATEST_COMMIT_HASH,
   ACRE_API_ENDPOINT,
+  POSTHOG_API_HOST,
+  POSTHOG_API_KEY,
 }

dapp/src/constants/featureFlags.ts

@@ -18,6 +18,8 @@ const TVL_ENABLED = import.meta.env.VITE_FEATURE_FLAG_TVL_ENABLED === "true"
 const GATING_DAPP_ENABLED =
   import.meta.env.VITE_FEATURE_GATING_DAPP_ENABLED === "true"
 
+const POSTHOG_ENABLED = import.meta.env.VITE_FEATURE_POSTHOG_ENABLED === "true"
+
 const MOBILE_MODE_ENABLED =
   import.meta.env.VITE_FEATURE_MOBILE_MODE_ENABLED === "true"
 
@@ -29,6 +31,7 @@ const featureFlags = {
   ACRE_POINTS_ENABLED,
   TVL_ENABLED,
   GATING_DAPP_ENABLED,
+  POSTHOG_ENABLED,
   MOBILE_MODE_ENABLED,
 }
 

dapp/src/hooks/posthog/index.ts

@@ -0,0 +1,3 @@
+export * from "./usePostHogIdentity"
+export * from "./usePostHogCapture"
+export * from "./usePostHogPageViewCapture"

dapp/src/hooks/posthog/usePostHogCapture.ts

@@ -0,0 +1,40 @@
+import { PostHogEvent } from "#/posthog/events"
+import { PostHog, usePostHog } from "posthog-js/react"
+import { useCallback } from "react"
+
+type CaptureArgs = [
+  eventName: PostHogEvent,
+  ...rest: Parameters<PostHog["capture"]> extends [unknown, ...infer R]
+    ? R
+    : never,
+]
+
+export const usePostHogCapture = () => {
+  const posthog = usePostHog()
+
+  const handleCapture = useCallback(
+    (...captureArgs: CaptureArgs) => {
+      posthog.capture(...captureArgs)
+    },
+    [posthog],
+  )
+
+  const handleCaptureWithCause = useCallback(
+    (error: unknown, ...captureArgs: CaptureArgs) => {
+      const [eventName, parameters, ...rest] = captureArgs
+
+      const captureParameters =
+        error instanceof Error
+          ? {
+              ...parameters,
+              cause: error.message,
+            }
+          : undefined
+
+      handleCapture(eventName, captureParameters, ...rest)
+    },
+    [handleCapture],
+  )
+
+  return { handleCapture, handleCaptureWithCause }
+}

dapp/src/hooks/posthog/usePostHogIdentity.ts

@@ -0,0 +1,27 @@
+import { PostHog, usePostHog } from "posthog-js/react"
+import { useCallback } from "react"
+import { sha256, toUtf8Bytes } from "ethers"
+
+type IdentifyArgs = Parameters<PostHog["identify"]>
+
+export const usePostHogIdentity = () => {
+  const posthog = usePostHog()
+
+  const handleIdentification = useCallback(
+    (...identifyArgs: IdentifyArgs) => {
+      const [id, ...rest] = identifyArgs
+      if (!id) return
+
+      const hashedId = sha256(toUtf8Bytes(id.toLowerCase())).slice(2, 12)
+
+      posthog.identify(hashedId, ...rest)
+    },
+    [posthog],
+  )
+
+  const resetIdentity = useCallback(() => {
+    posthog.reset()
+  }, [posthog])
+
+  return { handleIdentification, resetIdentity }
+}

dapp/src/hooks/posthog/usePostHogPageViewCapture.ts

@@ -0,0 +1,15 @@
+import { PostHogEvent } from "#/posthog/events"
+import { useEffect } from "react"
+import { useLocation } from "react-router-dom"
+import { usePostHogCapture } from "./usePostHogCapture"
+
+export const usePostHogPageViewCapture = () => {
+  const { handleCapture } = usePostHogCapture()
+  const location = useLocation()
+
+  useEffect(() => {
+    handleCapture(PostHogEvent.PageView)
+  }, [location, handleCapture])
+
+  return handleCapture
+}

dapp/src/hooks/useAcrePoints.ts

@@ -2,8 +2,10 @@ import { useMutation, useQuery } from "@tanstack/react-query"
 import { acreApi } from "#/utils"
 import { queryKeysFactory, REFETCH_INTERVAL_IN_MILLISECONDS } from "#/constants"
 import { MODAL_TYPES } from "#/types"
+import { PostHogEvent } from "#/posthog/events"
 import { useWallet } from "./useWallet"
 import { useModal } from "./useModal"
+import { usePostHogCapture } from "./posthog/usePostHogCapture"
 
 const { userKeys, acreKeys } = queryKeysFactory
 
@@ -21,6 +23,7 @@ type UseAcrePointsReturnType = {
 export default function useAcrePoints(): UseAcrePointsReturnType {
   const { ethAddress = "" } = useWallet()
   const { openModal } = useModal()
+  const { handleCapture, handleCaptureWithCause } = usePostHogCapture()
 
   const userPointsDataQuery = useQuery({
     queryKey: [...userKeys.pointsData(), ethAddress],
@@ -47,9 +50,15 @@ export default function useAcrePoints(): UseAcrePointsReturnType {
         claimedAmount,
         totalAmount,
       })
+
+      handleCapture(PostHogEvent.PointsClaimSuccess, {
+        claimedAmount,
+        totalAmount,
+      })
+    },
+    onError: (error) => {
+      handleCaptureWithCause(error, PostHogEvent.PointsClaimFailure)
     },
-    // TODO: Add the case when something goes wrong
-    // onError: (error) => {},
   })
 
   return {