Skip to main content

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.

​
Script Initialization and Timing

The attribution script loads asynchronously. To avoid race conditions between script loading and your application calls, you have two options: Add this JavaScript code before any calls to the library to queue commands until the script loads: 
window.CelloAttribution=window.CelloAttribution||function(t,...o){if("getReferral"===t)throw new Error("getReferral is not supported in this context. Use getUcc instead.");let e,n;const i=new Promise((t,o)=>{e=t,n=o});return window.CelloAttributionCmd=window.CelloAttributionCmd||[],window.CelloAttributionCmd.push({command:t,args:o,resolve:e,reject:n}),i}

​
Option 2: Wait for Script Initialization

Alternatively, wait for the script to load before making calls: 
document.addEventListener('DOMContentLoaded', async function() {
    // Wait for script initialization
    await new Promise(resolve => setTimeout(resolve, 1000));
    
    if (typeof window.CelloAttribution === 'function') {
        // Now safe to call methods
        const ucc = await window.CelloAttribution("getUcc");
        console.log('UCC:', ucc);
    } else {
        console.error('Cello Attribution script failed to load');
    }
});

​
attachTo(formElement)

Attaches hidden input to the passed HTMLFormElement node, or array of nodes. 
window.CelloAttribution("attachTo", formElement);

​
Accepts

​
formElement
HTMLFormElement | HTMLFormElement[]
required
Form(s) to attach the hidden input to

​
Example

window.CelloAttribution("attachTo", document.querySelector("form"));

​
getCampaignConfig()

Returns campaign configuration for new users, including discount information. 
const campaignConfig = await window.CelloAttribution("getCampaignConfig");

​
Returns

​
campaignConfig
object
The campaign config object:

​
Complete Example

const config = await window.CelloAttribution("getCampaignConfig");
console.log(config);
// Output:
// {
//   newUserDiscountPercentage: 0.1,    // 10% discount
//   newUserDiscountMonth: 12           // For 12 months
// }

// Convert to display format:
const displayPercentage = config.newUserDiscountPercentage * 100; // 10
const message = `${displayPercentage}% off for ${config.newUserDiscountMonth} months`;
console.log(message); // "10% off for 12 months"

// Use in your UI:
document.getElementById('discount-banner').innerHTML = 
  `🎉 Special offer: ${displayPercentage}% off your first ${config.newUserDiscountMonth} months!`;

​
getReferrerName()

Returns the referrer’s name, if provided in the referral link. 
const name = await window.CelloAttribution("getReferrerName");

​
Returns

​
name
string | undefined
Referrer’s name or undefined

​
getUcc()

Retrieves the referral code ucc from the URL or the cookie (if cookies are enabled). 
const ucc = await window.CelloAttribution("getUcc");

​
Returns

​
ucc
string
Unique campaign code/referral code

​
attachAll()

⚠️ Deprecated: forms are now auto-detected and the hidden ucc input is injected automatically. Use attachTo(formElement) for targeted cases instead.

​
Troubleshooting

​
Attribution Script Not Loading

// Check if script loaded correctly
if (typeof window.CelloAttribution !== 'function') {
    console.error('Cello Attribution script failed to load');
    // Implement fallback logic
    // For example, proceed without attribution or show error message
}

​
Methods Returning undefined or null

Common causes:
  • Script not fully initialized - wait for DOM load or use the queue function
  • Incorrect method syntax - ensure you use window.CelloAttribution("methodName")
  • No referral data available - user didn’t come from a referral link
Solutions: 
// Always check return values
const ucc = await window.CelloAttribution("getUcc");
if (ucc) {
    console.log('Referral code found:', ucc);
} else {
    console.log('No referral code - user came directly');
}

// Handle missing referrer names gracefully
const referrerName = await window.CelloAttribution("getReferrerName");
const greeting = referrerName 
    ? `Welcome! ${referrerName} referred you` 
    : 'Welcome to our platform';

​
Testing Attribution Methods

Test all methods in your browser console: 
// Test UCC retrieval
await window.CelloAttribution("getUcc");
// Returns: string (referral code) or null

// Test referrer name
await window.CelloAttribution("getReferrerName");
// Returns: string (referrer name) or undefined

// Test campaign config
await window.CelloAttribution("getCampaignConfig");
// Returns: { newUserDiscountPercentage: number, newUserDiscountMonth: number }

​
Network and Loading Issues

// Check if attribution script is blocked
fetch('https://assets.cello.so/attribution/latest/cello-attribution.js')
  .then(response => {
    if (!response.ok) {
      console.error('Attribution script blocked or unavailable');
    }
  })
  .catch(error => {
    console.error('Network error loading attribution script:', error);
  });

​
Common Integration Patterns

// Safe attribution check with fallbacks
async function initializeWithAttribution() {
    try {
        // Wait for script if needed
        let retries = 0;
        while (typeof window.CelloAttribution !== 'function' && retries < 10) {
            await new Promise(resolve => setTimeout(resolve, 500));
            retries++;
        }
        
        if (typeof window.CelloAttribution === 'function') {
            const ucc = await window.CelloAttribution("getUcc");
            const referrerName = await window.CelloAttribution("getReferrerName");
            const campaignConfig = await window.CelloAttribution("getCampaignConfig");
            
            return { ucc, referrerName, campaignConfig };
        } else {
            throw new Error('Attribution script not available');
        }
    } catch (error) {
        console.warn('Attribution initialization failed:', error);
        return { ucc: null, referrerName: null, campaignConfig: null };
    }
}

// Use in your application
initializeWithAttribution().then(({ ucc, referrerName, campaignConfig }) => {
    // Proceed with or without attribution data
    if (ucc) {
        console.log('Referral detected:', { ucc, referrerName, campaignConfig });
    }
});

​
getReferral()

⚠️ Deprecated: use getUcc() instead.