Integrating Lucia SDK with Vite + TypeScript

This guide explains how to integrate Lucia SDK into your Vite + TypeScript application to track wallet interactions and user behavior.

Prerequisites

A Vite + TypeScript project
Lucia Attribution API key found in your dashboard: register at https://ads.clickinsights.xyz the domain for Lucia's app dashboard
Environment variables configured in your .env file

Installation and Setup

Install the Lucia-Browser-SDK:

npm install lucia-sdk
# or
yarn add lucia-sdk

Initialize the SDK in your application entry point (typically App.tsx):

import LuciaSDK from 'lucia-sdk';

LuciaSDK.init({
  apiKey: import.meta.env.VITE_CLICKINSIGHTS_API_KEY
});

OPTIONAL: You may put a debug URL in the instantiation parameters. This is typical only for internal purposes

import LuciaSDK from 'lucia-sdk';

LuciaSDK.init({
  apiKey: import.meta.env.VITE_CLICKINSIGHTS_API_KEY,
  debugURL: import.meta.env.VITE_CLICKINSIGHTS_DEBUG_URL
});

Tracking Wallet Interactions

The SDK provides methods to track wallet connections and user information. Here's how to implement wallet tracking in your login function:

interface WalletLoginParams {
  connectedAccount: string;
  walletName: "Metamask" | "Phantom";
}

async function handleWalletLogin({ connectedAccount, walletName }: WalletLoginParams) {
  try {
    // Track wallet connection
    await LuciaSDK.sendWalletInfo(connectedAccount, 101, walletName);

    // Handle wallet-specific logic
    switch (walletName) {
      case "Phantom": {
        const solBalance = await connection.getBalance(new PublicKey(connectedAccount));
        const tokenAccount = await fetchTokenAccounts();
        
        // Track user information including balances
        await LuciaSDK.userInfo(connectedAccount, {
          solBalance,
          tokenAccount,
        });
        break;
      }

      case "Metamask": {
        // Add Metamask-specific tracking here
        await LuciaSDK.userInfo(connectedAccount, {
          // Add relevant Ethereum wallet data
        });
        break;
      }
    }
  } catch (error) {
    console.error('Error during wallet login tracking:', error);
  }
}

These lines are the ones that specifically interact with our SDK

await LuciaSDK.sendWalletInfo(connectedAccount, 101, walletName);

await LuciaSDK.userInfo(connectedAccount, {
    solBalance,
    tokenAccount,
});

API Reference

sendWalletInfo

Tracks wallet connection events:

LuciaSDK.sendWalletInfo(
  walletAddress: string,  // The wallet address of the user
  chainId: number,        // Blockchain network ID
  walletProvider: string  // Wallet provider name
): Promise<void>

userInfo

Updates user-specific information:

LuciaSDK.userInfo(
  userId: string,     // The user's ID, e.g. email, wallet address, etc.
  userInfo: object    // Additional user information, e.g. name, contact details, etc.
): Promise<void>

Best Practices

Error Handling: Always implement proper error handling around SDK calls
Environment Variables: Keep API keys and URLs in environment variables

Troubleshooting

If you encounter issues:

Verify your API key and debug URL are correct
Check browser console for error messages
Ensure all required dependencies are installed

Check our open source codebase on Github

ClickInsights Documentation