Usage - Cello

`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

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 country is not on the supported payout countries list, the Referral Component will not be booted for this user. If no country is passed, Cello will still be booted. Note: this uses the country your product has on file, which may differ from the user’s actual PayPal payout country. See the unsupported countries guidance for tradeoffs before using this to gate visibility.

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. Note: the language must be enabled for your product by Cello - if the language is not enabled, this parameter has no effect and the component falls back to your product’s default language. Contact Cello support to enable additional languages.

themeMode

string

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

hideDefaultLauncher

boolean

Hides the entire default Cello launcher button. Use this when you want to provide your own launcher element via customLauncherSelector. Default: false. Note: this hides the button, not just the notification badge. To hide only the badge on a custom launcher element, add data-cello-badge="false" to your HTML element instead - see Configure notification badge. There is no hideDefaultBadge boot option.

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: "bob@gmail.com",
      },
      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

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);

A fulfilled promise from showAnnouncement only means the SDK accepted the request. It does not mean the announcement is visible to the user.The announcement is anchored to the element matched by your Announcement Selector using document.querySelector (first match in DOM order). If that element is hidden, zero-sized, or off-screen, the announcement renders but is invisible. If you see Promise {<fulfilled>: undefined} but no announcement, run document.querySelectorAll("<your selector>") in the console - the result must be exactly one visible element.See Troubleshooting: announcement not showing for the full diagnostic flow.

`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

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: "bob@gmail.com",
  firstName: "Bob",
  lastName: "Bobsky",
  fullName: "Bob Bobsky",
};
window.Cello("updateProductUserDetails", productUserDetails);

Documentation Index

​cello.boot(options)

​Accepts

​Example

​changeLanguage(language)

​Accepts

​setThemeMode(theme)

​Accepts

​close()

​getActiveUcc()

​Returns

​getCampaignConfig()

​Returns

​getLabels()

​Returns

​hide()

​open(destination)

​Accepts

​show()

​showAnnouncement(announcement)

​Accepts

​Example

​shutdown()

​updateProductUserDetails(productUserDetails)

​Accepts

​Example

`cello.boot(options)`

Accepts

Example

`changeLanguage(language)`

Accepts

`setThemeMode(theme)`

Accepts

`close()`

`getActiveUcc()`

Returns

`getCampaignConfig()`

Returns

`getLabels()`

Returns

`hide()`

`open(destination)`

Accepts

`show()`

`showAnnouncement(announcement)`

Accepts

Example

`shutdown()`

`updateProductUserDetails(productUserDetails)`

Accepts

Example