Skip to main content

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.
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:

Accepts

object
required
The initialization options object:

Example


changeLanguage(language)

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

Accepts

string
required
The language string in ISO 639-1

setThemeMode(theme)

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

Accepts

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

close()

Closes Referral Component.

dismissAnnouncement()

Dismisses the active announcement without opening the Referral Component. Use it for the close button when you show announcements in your own UI. The announcement is marked as read, and onAnnouncementChanged is called with null. Does nothing if there is no active announcement.

getActiveAnnouncement()

Returns the active announcement for the currently logged-in user, or null if there is none. Heading and text are translated and personalized the same way as in the Referral Component’s own announcement bubble, including your label overrides. Use it when your page loads after the announcement arrived. To be notified when the announcement changes, use the onAnnouncementChanged boot option.

Returns

object | null
The active announcement object:

Example

Example below shows the announcement in your own UI. The call-to-action opens the Referral Component on the right page, which also marks the announcement as read:
text can contain <strong> tags. If you insert it as HTML, sanitize it first. Otherwise, strip the tags and show it as plain text.

getActiveUcc()

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

Returns

object
The active ucc object:

getCampaignConfig()

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

Returns

object
The campaign config object:

getLabels()

Returns select labels used in our Referral Component.

Returns

object
The labels object:

getUnreadEventCounts()

Returns the unread counts for the currently logged-in user, the same counts that drive the Cello notification badge. Use it to read the counts once, e.g. when your launcher renders. To be notified when they change, use the onUnreadCountChanged boot option.

Returns

object
The unread counts:

Example

Example below shows a dot badge on your own launcher. To show a number instead, see Show your own badge.

hide()

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

open(destination)

Opens Referral Component.

Accepts

string
Optional destination string to open Referral Component on a specific tab or page. Without it, Referral Component opens on the invite tab:
  • "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.

showAnnouncement(announcement)

Triggers an announcement.

Accepts

string
required

Example

Example below triggers a default welcome 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.

updateProductUserDetails(productUserDetails)

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

Accepts

object
required
The product user details object

Example


Content Security Policy (CSP)

Most applications don’t need any changes here. This section only applies if your site enforces a Content Security Policy - if you don’t set CSP headers, or your policy is permissive, you can skip it. The Cello Referral Component loads its script and assets from Cello domains at runtime. If your policy is restrictive, extend it with the following sources so the Referral Component can load and run:
  • These directives extend your existing policy; if you use a restrictive default-src, keep all of the above explicit.
  • Sandbox environments use the equivalent *.sandbox.cello.so domains (for example https://assets.sandbox.cello.so and https://share.sandbox.cello.so).
If the Referral Component fails to load and your browser console shows errors like Refused to connect because it violates the document's Content Security Policy, see Troubleshooting in the Referral Component quickstart.

Nonce-based policies

If your style-src or script-src contains a 'nonce-...' source, browsers ignore 'unsafe-inline'. The Referral Component then cannot apply its styles and renders without them. Pass the nonce of the current response to boot instead, and put it on the two script tags as well:
The Referral Component puts the nonce on every style it creates and on the font stylesheet it loads. 'unsafe-inline' is no longer needed in style-src; keep the Cello and Typekit hosts listed above. Pass a fresh nonce on every page load. A nonce reused across responses defeats the policy.