Attribution Library

Cello's Attribution library simplifies the process of tracking users and personalizing messages on your landing and signup pages. You can add this library to your the page where your customers sign up and where the referrer link forwards them to. By integrating this JavaScript library, you can store and attach unique campaign codes (ucc) to your forms to be later used by your application, enabling seamless tracking of referrals and delivering personalized messages to new users.

Integrating the Cello Attribution Library

To add the Cello Attribution library to your site, insert the following code snippet into the <head> tag of each page on your website

Javascript
    
 
<script type="module" src="https://assets.cello.so/attribution/latest/cello-attribution.js" async></script>
Copy

Environment based URL

Choose the correct CDN URL for the for the Cello Attribution library based on the environment you are integrating.

CDN URL	Environment
https://assets.sandbox.cello.so/attribution/latest/cello-attribution.js	Sandbox
https://assets.cello.so/attribution/latest/cello-attribution.js	Production

Attribution library API

To avoid race condition of our script loading and your application trying to communicate to it, you should add the following javascript code before any of the calls to the library.

Javascript
    
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}
Copy

Here is an example setup:

Javascript
    
​x
    
<html>  <head>    <script type="module" src="https://assets.cello.so/attribution/latest/cello-attribution.js" async></script>  </head>​  <body>    <script>      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}    </script>​    <script>      window.CelloAttribution('getUcc').then(referral => {        console.log('Incoming Referral:', referral);      });    </script>​    <form data-cello>      <input type="text" name="test-name" value="TEST-VALUE" />      <input type="submit" value="Submit" />    </form>  </body></html>
Copy

Methods

All methods are asynchronous and return a promise. This guarantees that developer does not have to implement their own blocking mechanism and the promise resolves once the action or data is available. Developer can use either the straight up cookie handling with .then methods or with async/await .

CelloAttribution('getUcc')

Retrieves the referral code (ucc) from the link URL or the cookie (if cookies are enabled).

Javascript
    
 
// if in async functionconst ucc = await window.CelloAttribution('getUcc');​// otherwise​window.CelloAttribution('getUcc').then((result) => {  const ucc = result;})
Copy

CelloAttribution('getReferrerName')

Returns the referrer's name, if it was provided in the referral link, so you can use it in your UI, like adding it to the greeting page.

Javascript
    
 
const name = await window.CelloAttribution('getReferrerName');
Copy

CelloAttribution('attachAll')

This method is deprecated. It now auto-detects forms and injects the hidden ucc input without manual calls. Rely on the new automatic behaviour or, for targeted cases, use attachTo() instead.

CelloAttribution('attachTo')

Attaches hidden input to passed HTMLFormElement node, or array of nodes.

Javascript
    
 
window.CelloAttribution('attachTo', document.querySelector('form'));
Copy

CelloAttribution('getCampaignConfig')

Returns campaign config pertaining a new user

Javascript
    
 
const campaignConfig = await window.CelloAttribution('getCampaignConfig');
Copy

Returns

newUserDiscountMonth - how long new users get a discount
newUserDiscountPercentage - the discount new users get

CelloAttribution('getReferral')

This method is deprecated. It will be supported for some time. Switch to using getUcc method instead, which has also asynchronous support.

Retrieves the referral code (ucc) from the link URL or the cookie (if cookies are enabled).

Javascript
    
 
const ucc = window.CelloAttribution('getReferral');
Copy

When a new user (referred user) visits your product page via the shared landing page link, the referrer's referral code is saved in the referee's browser as a first-party cookie. The referral code is injected as a regular parameter to your product landing page URL (unlike a tracking parameter, such as a UTM parameter). If our attribution library is installed on your product landing page, it will extract this parameter from the URL and save it as a first-party cookie. This allows you to attribute the referee to a specific referrer, even if the referee does not sign up during their initial visit and returns later without using the referral link.

For example, a product landing page URL might include the ucc as a parameter, where the ucc is the unique campaign code (i.e., referral code) saved in the cookie. The stored cookie will be labeled cello-referral . Learn more about our cookies managing options here.

Attaching the Referral Code to Forms

Attribution library automatically observes the DOM and attaches the hidden ucc input to both forms that exist on first paint and forms that are added later by your JavaScript framework (React, Vue, Angular, etc.). No extra code is required.

By default, any element matching the selector form[data-cello] will be used.

Once the attribution script is incorporated into your HTML website, it automatically identifies forms. After collecting all the forms, it retrieves the ucc from the URL search parameters, injects it into the cookie, and then creates a hidden input in all the forms with the ucc value.

This process operates automatically for server-side generated and static websites. For dynamic forms, use Attribution library API.

This function allows you to attach a referral code to any registration form, such as "Sign up for demo" or "Sign up for a free trial," to your CRM. Consequently, you can attribute this signup to a specific referrer, who can then be rewarded according to your Rewards setup.

The steps you need to perform are:

Add the data-cello attribute to all forms you wish to pass the referral code with
Call Attribution API attachAll or attachTo commands if the forms appear dynamically and not at first load
Include ucc in the attribution sent to Cello

Below is an example of a form with the data-cello attribute:

Javascript
    
 
<form action="/signup" method="post" data-cello="true">  <input type="text" name="name">  <input type="email" name="email">  <button>Request demo</button>    <!-- Inserted automatically by Cello: -->  <input type="hidden" name="referral" value="UPobYBDuu0N"></form>
Copy

Last updated on

Was this page helpful?