> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cello.so/llms.txt
> Use this file to discover all available pages before exploring further.

# Introduction

> JavaScript library for capturing and tracking referral codes throughout the conversion funnel

## What is Attribution JS?

Attribution JS is a lightweight JavaScript library that captures referral codes (`ucc`) from landing pages and maintains attribution throughout the user journey. When users click referral links and land on your website, this library ensures their referral source is properly tracked through signup and purchase events.

The library automatically:

* Detects referral code (`ucc`) query parameters from referral links
* Stores referral code (`ucc`) as first-party cookies for persistent tracking
* Attaches referral code (`ucc`) to signup forms
* Provides APIs to retrieve referrer information for personalization

## Installation Options

Choose your preferred installation method:

<CardGroup cols={2}>
  <Card title="Embedded Script Tag" icon="code" href="/sdk/client-side/embedded-script-tag">
    Add directly to your HTML pages with a script tag
  </Card>

  <Card title="Google Tag Manager" icon="google" href="/sdk/client-side/google-tag-manager">
    Deploy through GTM without code changes
  </Card>
</CardGroup>

## Key Capabilities

Attribution JS enables you to:

### Referral Tracking

* **Capture referral codes** - Automatically detect and store `ucc` parameters from referral links
* **Retrieve referral data** - Access referral codes programmatically with `getUcc()`. Returns data from URL parameters or stored cookies (persisted for 3 months)
* **Form integration** - Auto-inject hidden referral fields into signup forms for seamless attribution

### Personalization & Campaigns

* **Get referrer names** - Display personalized messages using `getReferrerName()` to retrieve the name of the person who sent the referral
* **Access campaign config** - Use `getCampaignConfig()` to retrieve discount percentages (in decimal format: 0.1 = 10%) and duration in months for referred users
* **Dynamic discount display** - Show referral incentives based on campaign parameters with proper percentage conversion for user display

### Cookie Management

* **Privacy compliance** - [Manage cookie consent](/landing-pages/manage-cookies) with built-in methods
* **Allow cookies** - Enable cookie storage after user consent
* **Delete cookies** - Remove stored data when consent is withdrawn
* **Custom handling** - Implement your own consent flow with full API control

## How It Works

1. **User clicks referral link** - Link contains referral code (`ucc`) parameter (e.g., `yoursite.com?ucc=ABC123`)
2. **Script captures code** - Attribution JS detects referral code (`ucc`) and makes it accessible via `window.CelloAttribution("getUcc")` method
3. **Code persists** - Stored as first-party cookie for 3 months to handle return visits and cross-session attribution
4. **Methods available** - All attribution methods (`getUcc`, `getReferrerName`, `getCampaignConfig`) become available asynchronously after script initialization
5. **Signup attribution** - Referral code (`ucc`) is automatically attached to forms or retrieved programmatically for user registration
6. **Referral conversion tracking** - Pass the referral code (`ucc`) to Cello when tracking signups and purchases for complete attribution

## Next Steps

<Steps>
  <Step title="Install the Library">
    Choose between [embedded script](/sdk/client-side/embedded-script-tag) or [GTM installation](/sdk/client-side/google-tag-manager)
  </Step>

  <Step title="Verify Installation">
    Test that referral codes are being captured correctly
  </Step>

  <Step title="Explore the API">
    Review all [available methods](/sdk/client-side/attribution-js-usage) for advanced functionality
  </Step>
</Steps>

## API Method Calls

All Cello Attribution methods use the unified `CelloAttribution` function syntax:

```javascript theme={null}
const ucc = await window.CelloAttribution("getUcc");
const referrerName = await window.CelloAttribution("getReferrerName");
const campaignConfig = await window.CelloAttribution("getCampaignConfig");
```

<Note>
  Attribution JS works alongside [Cello JS](/sdk/client-side/cello-js-introduction) for complete referral program functionality. While Attribution JS handles tracking and data retrieval, Cello JS provides the referral component interface.
</Note>