Usage

Below is the full list of commands to call the Cello JS SDK with.

cello.boot(options)

Initializes Cello Referral Component in your product.

Returns a promise that is resolved once the whole initialization process is finished or rejected if the boot command failed.

window.cello = window.cello || { cmd: [] };

window.cello.cmd.push(async (cello) => {
  try {
    await cello.boot(options);
  } catch (error) {
    // Handle the error appropriately
  }
});

The solution above is designed so that you don’t have to wait for the library to finish loading before you call the command - follow it and use the window.cello object to avoid that particular race condition. For any other commands, or when you are sure that the command is called after the library has finished loading, you can opt to use the regular command syntax:

await window.Cello("boot", options);

Accepts

options · object · required

The initialization options object:

Show properties

productId · string · required

Identifier of the product your users will refer. You can obtain this in your Cello Portal.

token · string · required

Access token generated for the given user. More in User Authentication.

productUserDetails · object · required

Product user details object. Required for select features

Show properties

email · string · required

Email of the product user. This data is used in the personalization of the referral experience, e.g. email notifications. Required for select features

firstName · string · required

First name of the product user. This data is used in the personalization of the referral experience, e.g. email notifications and the personalized message to referees. Required for select features

lastName · string

Last name of the product user

fullName · string

Full name of the product user. Use this option if you do not have first name and last name separately.

productUserCountryCode · string

Product user country, if known. ISO 3166 Alpha-2 standard e.g. DE. If the user is from an unsupported country, the Cello Referral Component will not be booted for this user and an error will be returned. If no country is passed, Cello will still be booted.

language · string

The language, in which the Referral Component will be loaded in ISO 639-1. Default: undefined. If undefined, we use default language set for your product.

themeMode · string

Set light or dark theme to match your app’s interface. Accepts light and dark. Default: light.

hideDefaultLauncher · boolean

Show or hide the Cello button, launching the Referral Component when it’s first initialized. Default: false

onOpen · function

Callback event for when Referral Component widget is opened.

onClose · function

Callback event for when Referral Component widget is closed.

onUserInteraction · function

Callback handler for user interactions within the Referral Component. Receives two parameters: action (string) and payload (any). Currently supports linkCopied action which provides the copied URL as payload.

Example

window.cello = window.cello || { cmd: [] };

window.cello.cmd.push(async (cello) => {
  try {
    const options = {
      productId: "REPLACE_WITH_PRODUCT_ID",
      token: "REPLACE_WITH_TOKEN",
      language: "en",
      productUserDetails: {
        firstName: "Bob",
        lastName: "Bobsky",
        fullName: "Bob B Bobsky",
        email: "[e-mail]",
      },
      onUserInteraction: (action, payload) => {
        console.log('user interaction', action, payload)
        if (action === 'linkCopied') {
          const urlThatWasCopied = payload
          // Handle the copied link (e.g., track analytics, show notification)
        }
      }
    };

    await cello.boot(options);
    // Call other Cello commands, if necessary
  } catch (error) {
    console.error("Failed to boot cello:", error);
  }
});

---

changeLanguage(language)

Changes the Referral Component language at runtime without re-initializing it.

window.Cello("changeLanguage", "de");

Accepts

language · string · required

The language string in ISO 639-1

setThemeMode(theme)

Changes the Referral Component theme at runtime without re-initializing it.

window.Cello("setThemeMode", "dark");

Accepts

theme · string

The theme mode to apply. Accepted values are light or dark.

close()

Closes Referral Component.

window.Cello.close();

---

getActiveUcc()

Returns active ucc and invite link for the currently logged-in user.

const { ucc, link } = await window.Cello("getActiveUcc");

Returns

activeUcc · object

The active ucc object:

Show properties

ucc · string

Active unique campaign code or referral code for the current logged-in user

link · string

Personal invite link for the current logged-in user

getCampaignConfig()

Returns campaign config values for the currently logged-in user.

const campaignConfig = await window.Cello("getCampaignConfig");

Returns

campaignConfig · object

The campaign config object:

Show properties

primaryCurrency · string

Primary currency code

revenuePercentage · number

Percentage of attributed new revenue that will be paid as a reward

rewardCap · number

Maximum reward that can be earned per referral

newSignupBonus · number

Additional reward for signups to encourage more sharing

newPurchaseBonus · number

Additional reward for purchases to encourage more sharing

newUserDiscountMonth · number

How long new users get a discount

newUserDiscountPercentage · number

The discount new users get

getLabels()

Returns select labels used in our Referral Component.

const labels = await window.Cello("getLabels");

Returns

labels · object

The labels object:

Show properties

customLauncher · string

A welcome text useful for building custom launchers

hide()

Hides the Cello button or bookmark that launches the Referral Component.

window.Cello("hide");

---

open(destination)

Opens Referral Component.

window.Cello("open", destination);

Accepts

destination · string

Optional destination string to open Referral Component on a specific tab or page:

• "rewards" - open Referral Component on the rewards tab
• "edit-payments" - open Referral Component on the payment details page

show()

Shows the Cello button or bookmark that launches the Referral Component.

window.Cello("show");

---

showAnnouncement(announcement)

Triggers an announcement.

window.Cello("showAnnouncement", announcement);

Accepts

announcement · string · required

Example

Example below triggers a default welcome announcement:

const announcement = { type: "welcome-announcement-1" };
window.Cello("showAnnouncement", announcement);

shutdown()

Shuts down connection to Cello and unmounts the Referral Component.

window.Cello("shutdown");

---

updateProductUserDetails(productUserDetails)

Updates user details at runtime without re-initializing the Referral Component.

window.Cello("updateProductUserDetails", productUserDetails);

Accepts

productUserDetails · object · required

The product user details object

Show properties

email · string · required

Email of the product user. This data is used in the personalization of the referral experience, e.g. email notifications. Required for select features

firstName · string · required

First name of the product user. This data is used in the personalization of the referral experience, e.g. email notifications and the personalized message to referees. Required for select features

lastName · string

Last name of the product user

fullName · string

Full name of the product user. Use this option if you do not have first name and last name separately.

Example

const productUserDetails = {
  email: "[e-mail]",
  firstName: "Bob",
  lastName: "Bobsky",
  fullName: "Bob Bobsky",
};
window.Cello("updateProductUserDetails", productUserDetails);