🚀 Start Here

See SDK for installation instructions

The purpose of this attribution tool is to acquire more users at lower customer acquisition cost. And retain those users so that the average lifetime revenue per user increases as your company grows and scales.

In order to do this, you will need an attribution system. This documentation server is written both for advanced users who have used attribution and retargetting systems before, and also new startup founders or CMO's or Sales Executives that want a step by step walkthrough.

How businesses interface with our product

The businesses we serve typically sell products, technology products. They are typically B2C. Examples include

• Exchanges

• L1's

• L2's

• DeFi

• SocialFi

• GameFi and Traditional Web 2 Gaming

• AI companies and SaaS

• Media Companies such as CoinDesk

If you are a business, any business really, your goal is to sell a product, and monetize your users. You spend money on marketing. This can be in the form of paid ads or social and/or organic. However, at the end of the day there is no free lunch.

Even if you are posting organic content and doing social media, you are still paying for it.

In summary what we do

We give businesses the decision making accuracy to get the best ROI on any type of marketing spend. Specifically we serve web3 customers, but we serve all businesses no matter what their domain as long as they are generating revenue and have a good product to sell.

🙋‍♀️ Frequently Asked Questions

If there are any questions that haven't been answered yet, please ask them in our Telegram Group

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

1. Install the Lucia-Browser-SDK:

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

2. 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

Wallet Login Tracking

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

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

Troubleshooting

If you encounter issues:

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

Check our open source codebase on Github

React + JavaScript

If your stack is React + JavaScript, follow these steps in the guide which explains how to integrate Lucia's SDK.

1. Install the SDK
2. See this code example

Prerequisites

• A React [Redux] 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

You have a react redux app

Initialize

import LuciaSDK from 'lucia-sdk';

LuciaSDK.init({
  apiKey: process.env.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: process.env.CLICKINSIGHTS_API_KEY,
  debugURL: process.env.CLICKINSIGHTS_DEBUG_URL
});

See Github reference on our sandbox here

Data Driven Marketing

Why all startups need this product

Consider these 2 scenarios

One startup founded by Alice collects all sorts of customer data at scale. The types of link they click on. The IP address of its users, Even things like timezone, locale, language.

She uses machine learning to automate a lot of her marketing campaigns. These can include

• Emails

• In App Push Notifications

• Messages from Telegram or Discord

• X Paid Ads

Another startup founded by Bob is a crypto exchange. He likes to play things by gut feeling. When its a bull market, he does crazy marketing stunts, helicopters, Superbowl ads, and tries to hit a home run. The only problem...? Bob is ridiculously inconsistent. Over time, he loses accountability and each marketing dollar being spent does not result in more than a dollar back into the business. Ultimately his business folds.

Illustration

You can imagine why its important to collect data on your users.

By understanding when users are most impressionable, you get their attention with your ad, they are focused on your offer, have time to think about your product. And may make a purchasing decision later.

But if you are like Bob, shooting from the hips, you're never going to get your customer's attention because you don't realize you are advertising or marketing to him at the worst possible time ever (when he is the most busiest).

Apply this logic not just to 2 customers but to 2 million customers. The companies that figure out Peformance Marketing are the ones that take their companeis to over 100 million dollars in valuation.

Links

A Lucia Link is a way for you to collect attribution data across all customers.

Overview

The underlying theory is that in order to track the ROI of a campaign, you must know the canonical source of the visitor. It's critical to track their customer journey as they transition from visitor to user. When they register for your DApp, you would collect their wallet address and link it to their lucia_user_id or essentially, what we call a unique person.

Content

4.1 Read about how to create a link and how to use it to maximize the ROI of your marketing campaign.

4.2 Read about using campaigns to track the performance of your marketing campaigns.

How to Create a Link on Lucia

And how to use it to maximize the ROI of your marketing campaign

Pre-reqs

• You've signed up for an account on our Lucia Attribution Dashboard: https://ads.clickinsights.xyz

Basic Usage

1. Make sure you've registered for an account on our Lucia Attribution Dashboard: https://ads.clickinsights.xyz

2. After you login go to the left panel of the dashboard and click Links

3. In the top right of your dashboard click on the New Link orange button

4. This will pop up a modal which will ask you to ask you where to redirect the user to.

Now, in order to make most of the links - again you'll want to have the SDK installed on all websites that the links redirect to. That way you can track the full journey of the user from the first click to the last conversion.

After you press enter you are done. For more on links, scroll down and go to Use Case Examples.

Advanced Usage

To learn more about advanced usage, go to the section about Campaigns

Theory

Links are the lifeblood of the Lucia Attribution system. With them, you're able to see the analytics involved in the relationships between each of your assets. For a web3 company, we would define your assets as

• Your DApp page or CEX page

• Your landing page which may feature a blog

• Your YouTube Channel and the X accounts your KOL's manage

• Your Socials: Telegram/Discord/X/Farcaster/Medium

Now the problem with most marketing tools out there is that once the user visits the page, they tend to forget about your website for a couple of days.

If they are interested in your product, they may google your name instead of clicking on the affiliate link that they first clicked on from the original KOL or X post that told them about your project.

Cookies

Cookies are tiny bits of data that are stored in the user's browser. However, they do not span devices. If your visitor ends up using a device, which is common because we are on our mobile phones a lot, but then when we sit down and do research on a product we typically do that on a computer - then typical tracking tools lose track of who this user is.

Unique Differences that Lucia provides

Lucia creates this concept of a "supercookie". It can track the user on any device.

That means, when you are measuring KPI's for your marketing campaign, you're able to measure the full journey of the user from the first click to the last conversion.

This is made possible by integrating Lucia SDK in your website. When you do that, it conencts their current cookie to the supercookie.

Main Use Case of Links

1. Integrating Link tracking with your KOL

Assumptions

• First you'll need to work with a KOL, or Influencer as they are sometimes called.
• They have an account on linktr.ee or beacons.ai - if not have them create one

They will usually have an X account, or IG or TikTok. Each one of these platforms support a link in bio.

Have them put their linktr.ee link or beacons.ai link in their bio.

You generate a link from the dashboard and give it to them. Next you'll want to have them to create links to your DApp or CEX page or any page you want to track.

2. Integrating Link tracking with your X campaign

See this video tutorial

How to create a campaign on Lucia

Click on the New Campaign button in the center

OR

Click on the New Campaign button on the top right corner to start creating a new Campaign

1) ✏️ Enter Campaign Details

• Click on the Campaign tab on the top to create a new Link.

• Enter the Target Url you want your users to redirect to.

  Example : https://google.com

• Choose a Platform you want to use this campaign for.

  Example : Facebook

• You can also add some Description to give more details about this campaign

• Click on Generate Link button

2) 🎉 Congrats. Your Campaign has now been created

Copy the link to share for your business or social media platforms.

Click on the Go to link dashboard button to view all your links and campaigns created.

3) 💻 Dashboard

All your links and campaigns created can be found in the dashboard

Installation and initialization for a browser environment using a Javascript SDK

For Single-Page Applications (React, Angular, Vue, Svelte, etc).

Install our sdk using

npm

npm install lucia-sdk 

OR

yarn

yarn add lucia-sdk

page.js

import LuciaSDK from 'lucia-sdk';

LuciaSDK.init({

  // Get your API Key from https://ads.clickinsights.xyz
  api_key: 'bb10bb08-a7298818-3265d018-e9a648ae-95371b44-d25e6c77-38069b79-1e4bd263', 

});

For Multi-Page Application

include the script

<script src="https://cdn.luciaprotocol.com/lucia-sdk-latest.min.js"></script>
<script>
  LuciaSDK.init({
    
    // API Key from https://ads.clickinsights.xyz
    api_key: 'bb10bb08-a7298818-3265d018-e9a648ae-95371b44-d25e6c77-38069b79-1e4bd263', 
  
  });

</script>

Track Specific Events

• Page View

• Track Conversion

• User Information

• Button Click

• Wallet Information

Page View

For Single-Page Applications (React, Angular, Vue, Svelte, etc).

import LuciaSDK from 'lucia-sdk';

LuciaSDK.pageView('PAGE-NAME');

Example

import LuciaSDK from 'lucia-sdk';

LuciaSDK.pageView('home');

For Multi-Page Application

<script src="https://cdn.luciaprotocol.com/lucia-sdk-latest.min.js"></script>
<script>
  LuciaSDK.init({

    // API Key from https://ads.clickinsights.xyz
    api_key: 'bb10bb08-a7298818-3265d018-e9a648ae-95371b44-d25e6c77-38069b79-1e4bd263', 
  
  });

  LuciaSDK.pageView('PAGE-NAME');

</script>

Example

<script src="https://cdn.luciaprotocol.com/lucia-sdk-latest.min.js"></script>
<script>
  LuciaSDK.init({

    // API Key from https://ads.clickinsights.xyz
    api_key: 'bb10bb08-a7298818-3265d018-e9a648ae-95371b44-d25e6c77-38069b79-1e4bd263', 
  
  });

  LuciaSDK.pageView('home');
  
</script>

Track Conversion

For Single-Page Applications (React, Angular, Vue, Svelte, etc).

import LuciaSDK from 'lucia-sdk';

LuciaSDK.trackConversion(
  event_tag, 
  amount, 
  event_details
);

Example

import LuciaSDK from 'lucia-sdk';

LuciaSDK.trackConversion(
  "purchase", //event_tag
  500, //amount
  { 
    //event_details
    product_id: 'bag_123', 
    quantity: 1, 
    brand: 'Nike'
  }
);
 

For Multi-Page Application

<script src="https://cdn.luciaprotocol.com/lucia-sdk-latest.min.js"></script>
<script>
  LuciaSDK.init({

    // API Key from https://ads.clickinsights.xyz
    api_key: 'bb10bb08-a7298818-3265d018-e9a648ae-95371b44-d25e6c77-38069b79-1e4bd263', 
  
  });
  
  LuciaSDK.trackConversion(
  event_tag, 
  amount, 
  event_details
);

</script>

Example

<script src="https://cdn.luciaprotocol.com/lucia-sdk-latest.min.js"></script>
<script>
  LuciaSDK.init({

    // API Key from https://ads.clickinsights.xyz
    api_key: 'bb10bb08-a7298818-3265d018-e9a648ae-95371b44-d25e6c77-38069b79-1e4bd263', 
  
  });
  
  LuciaSDK.trackConversion(
  "purchase", //event_tag
  500, //amount
  { 
    //event_details
    product_id: 'bag_123', 
    quantity: 1, 
    brand: 'Nike'
  }
);

</script>

User Information

For Single-Page Applications (React, Angular, Vue, Svelte, etc).

import LuciaSDK from 'lucia-sdk';

LuciaSDK.userInfo(
  user, 
  userInfo
);

Example

import LuciaSDK from 'lucia-sdk';

LuciaSDK.userInfo(
  "johndoe@email.com", 
  { 
    first_name : "John", 
    last_name: "Doe", 
    contact: "1234456722" 
  }
);

For Mutli-Page Application

<script src="https://cdn.luciaprotocol.com/lucia-sdk-latest.min.js"></script>
<script>
  LuciaSDK.init({

    // API Key from https://ads.clickinsights.xyz
    api_key: 'bb10bb08-a7298818-3265d018-e9a648ae-95371b44-d25e6c77-38069b79-1e4bd263', 
  
  });

  LuciaSDK.userInfo(
  user, 
  userInfo
);

</script>

Example

<script src="https://cdn.luciaprotocol.com/lucia-sdk-latest.min.js"></script>
<script>
  LuciaSDK.init({

    // API Key from https://ads.clickinsights.xyz
    api_key: 'bb10bb08-a7298818-3265d018-e9a648ae-95371b44-d25e6c77-38069b79-1e4bd263', 
  
  });

  LuciaSDK.userInfo(
  "johndoe@email.com", 
  { 
    first_name : "John", 
    last_name: "Doe", 
    contact: "1234456722" 
  }
);

</script>

Button Click

For Single-Page Applications (React, Angular, Vue, Svelte, etc).

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

import LuciaSDK from 'lucia-sdk';

LuciaSDK.init({
  debugURL: process.env.LUCIA_BASE_URL,
  apiKey: process.env.LUCIA_API_KEY,
});

For Vite + TypeScript projects, see our TypeScript Integration Guide

Example

import LuciaSDK from 'lucia-sdk';

LuciaSDK.buttonClick('add_to_cart');

For Multi-Page Application

<script src="https://cdn.luciaprotocol.com/lucia-sdk-latest.min.js"></script>
<script>
  LuciaSDK.init({

    // API Key from https://ads.clickinsights.xyz
    api_key: 'bb10bb08-a7298818-3265d018-e9a648ae-95371b44-d25e6c77-38069b79-1e4bd263', 
  
  });

LuciaSDK.buttonClick('BUTTON-NAME');

</script>

Example

<script src="https://cdn.luciaprotocol.com/lucia-sdk-latest.min.js"></script>
<script>
  LuciaSDK.init({

    // API Key from https://ads.clickinsights.xyz
    api_key: 'bb10bb08-a7298818-3265d018-e9a648ae-95371b44-d25e6c77-38069b79-1e4bd263', 
  
  });

LuciaSDK.buttonClick('add_to_cart');
  
</script>

Wallet Information

For Single-Page Applications (React, Angular, Vue, Svelte, etc).

import LuciaSDK from 'lucia-sdk';

LuciaSDK.sendWalletInfo('WALLET-ADDRESS', 'CHAIN-ID')

Example

import LuciaSDK from 'lucia-sdk';

LuciaSDK.sendWalletInfo('0x21342HHJJHJHJhjh87812', 59141)

For Multi-Page Application

<script src="https://cdn.luciaprotocol.com/lucia-sdk-latest.min.js"></script>
<script>
  LuciaSDK.init({

    // API Key from https://ads.clickinsights.xyz
    api_key: 'bb10bb08-a7298818-3265d018-e9a648ae-95371b44-d25e6c77-38069b79-1e4bd263', 
  
  });

LuciaSDK.sendWalletInfo('WALLET-ADDRESS', 'CHAIN-ID')

</script>

Example

<script src="https://cdn.luciaprotocol.com/lucia-sdk-latest.min.js"></script>
<script>
  LuciaSDK.init({

    // API Key from https://ads.clickinsights.xyz
    api_key: 'bb10bb08-a7298818-3265d018-e9a648ae-95371b44-d25e6c77-38069b79-1e4bd263', 
  
  });

LuciaSDK.sendWalletInfo('0x21342HHJJHJHJhjh87812', 59141)
  
</script>

Return on Marketing Investment

A common problem we see is startups may be making revenue, but they aren't growing quickly. They aren't generating enough revenue to continue to scale their teams.

At the same time, having a limited budget means they are apprehensive on spending money on marketing whether that's non-paid (organic/social) or paid advertising.

Our Dashboard Main Page for Customers

The top right panel is a graph showing Revenue vs Ad Spend

The area under the curve outlined with the Orange line represents revenue. The area under the curve outlined with the Blue line represents ad spend.

Organic Campaigns

Organic Campaigns usually stem from social media apps.

First after you login you'll see this page. If you're like most startups, you'll want to grow a strong organic community using Telegram, Discord, WhatsApp. In this section of the doc server we'll talk primarily about Telegram but the same concept applies for other chat platforms.

Case Studies

You can follow our Lucia Ad Attribution Case Studies for better insights

Tokenomics

You can look at our tokenomics here