Skip to main content
The Cello custom launcher allows you to open the Referral Component from any element that you want to use. It can be a button, a menu item, a link and you can use multiple places that open Cello Referral Component. Additionally, you can choose to open it either in a popup or modal view. Custom launcher integration showing referral component embedded in application menu
Critical Requirements for Custom Launchers:
  • The custom launcher element MUST exist in the DOM before Cello initializes
  • The element MUST have position: relative styling
  • You MUST configure the selector in Cello Portal to match your element
  • Cello does NOT automatically rescan the DOM for new elements after initialization
If your launcher can’t be in the DOM before Cello initializes, or you want the badge and announcement to match your own design, you can draw them in your own components. See Build your own badge and announcement.

Implementation Guide

Step 1: Create your launcher element

Create an HTML element that will trigger the Referral Component. The element must:
  1. Exist in the DOM before cello.boot() is called
  2. Have position: relative CSS styling
  3. Use a unique identifier (ID, class, or attribute)

Step 2: Configure Cello Portal

  1. Navigate to User experience → Widget in Cello Portal
  2. Set the Custom Launcher Selector to match your element:
    • For ID: #cello-launcher
    • For class: .cello-launcher
    • For attribute: [cello-launcher]
Cello Portal configuration for custom launcher selector settings

Step 3: Initialize Cello

After the custom launcher element exists in the DOM, initialize Cello:

Common Issues and Solutions

Custom launcher not working

Problem: The custom launcher element is created after Cello has already initialized.Solution: Ensure the element exists in the DOM before calling cello.boot(). In React/Vue, render the element with display: none initially, then show it after initialization.Alternative: Open the Referral Component from your own click handler, so the element doesn’t need to exist when Cello initializes. See Open the Referral Component from your own launcher.
Problem: The element doesn’t have position: relative styling.Solution: Add style="position: relative" to your launcher element. This is required for Cello to properly attach event handlers.
Problem: The selector in Cello Portal doesn’t match your element, or matches several elements where only one is visible.Solution: Verify the exact selector format:
  • ID selectors need # prefix: #my-launcher
  • Class selectors need . prefix: .my-launcher
  • Attribute selectors need brackets: [my-attribute]
Also verify uniqueness - Cello uses document.querySelector and picks the first match in DOM order. Run document.querySelectorAll("<your selector>") in the browser console: it should return exactly one visible element with a non-zero bounding box. If multiple elements match (for example, a wrapper <li> and an inner <span> share the same class), Cello will use the first one, which may be invisible. Either narrow the selector with a parent prefix or use an id. See Troubleshooting: announcement not showing for the same diagnostic flow applied to announcements.
Problem: In single-page applications, elements are dynamically added/removed.Solution: Keep the launcher element persistent in the DOM, use CSS to control visibility instead of conditional rendering.Alternative: Open the Referral Component from your own click handler, so the element can mount and unmount freely. See Open the Referral Component from your own launcher.

Add reward in launcher

1.5x activation rate 3.5x sharing rate Increase the sharing activity of your users by highlighting the reward directly in the referral launcher inside your menu item. Custom launcher displaying reward amount directly in menu item You can get the text for the menu launcher from cello.js. Text will be localized to the referrer’s language and the reward amount is based on the referrer’s campaign.

Disable Cello button

Cello button is a floating action button or bookmark style button provided as a default Referral Component launcher. When integrating a Customer Launcher, you may choose to disable the Cello button or keep it as an additional launcher. Default Cello floating action button launcher You can choose to disable the default launcher, the Cello button. Go to User experience → Widget settings in Cello Portal and uncheck “Show Cello Button”. Configuration to disable default Cello button and use custom launcher

Configure notification badge

Notification badge attached to custom launcher showing unread updates You can control the behaviour of the notification badge, which is attached to your Custom Launcher Selector by default:

Default behavior (clickable with badge)

This is the default behavior - the element opens the Referral Component on click and shows notification badges.
Add data-cello-badge="false" to hide the notification badge while keeping the element clickable. Use this when you have multiple launchers but only want badges on some of them.
Add data-cello-click="false" to show the notification badge but prevent clicks from opening the panel. Use this to show badge notifications on parent menu items for better visibility.
Draw the badge in your own component instead, as a dot or with the number of unread rewards. Cello’s own badge is always a dot. If Cello still opens the Referral Component from this element, add data-cello-badge="false" to hide Cello’s badge. See Show your own badge.
The data-cello-badge and data-cello-click attributes are optional modifiers. If you want the default behavior (clickable with badge), you don’t need these attributes at all.
Testing notification badge positionTo trigger a notification badge to be shown on your Custom Launcher simply visit the referral link, of the same user you are testing with, e.g. moonly.cello.so/pNRB1aYqArN . A link visit will trigger a view notification and a badge will be displayed.

Add announcement selector

Announcement callout anchored to custom launcher element Announcement are callout style notifications used to communicate important information to the user if we need to grab their attention and direct them to the Referral Component.
To show announcements in your own component instead of Cello’s callout, skip the Announcement Selector and see Show your own announcement.
If the Cello button is disabled, the announcement needs to be anchored to one of your Custom Launchers.
Depending on the implementation, the Announcement Selector can be the same as for Custom Launcher, i.e. you can use exactly the same class ID, attribute selector or element ID. Add this identifier as Announcement Selector under User experience → Widget in Cello Portal.
Critical requirements for Announcement Selector:
  • The selector MUST resolve to exactly one element when passed to document.querySelector. Cello uses the first match in DOM order and does not fall back to siblings.
  • The matched element MUST be visible and have a non-zero bounding box at announcement time. display: none, visibility: hidden, or width: 0 / height: 0 will cause the announcement to render against an invisible anchor.
  • If multiple elements share the same class or attribute (e.g. a wrapper <li> and an inner <span> both have .my-launcher), narrow the selector with a parent prefix or use an id.
  • Verify in the browser console: document.querySelectorAll("<your selector>") should return exactly one element with non-zero size. See Troubleshooting: announcement not showing.
Cello Portal configuration for announcement selector and positioning Here you can also configure where you want announcement to be shown relative to the Announcement Selector by specifying Announcement position and Announcement position offset.
Testing Announcement positionWhile choosing Announcement Selector and choosing its position, you will want to see how it looks and make necessary adjustments. You can trigger an announcement using Cello JS showAnnouncement(announcement) method.Example below will trigger the default welcome announcement:
A fulfilled promise from showAnnouncement only means the SDK accepted the request. It does not mean the announcement is visible. If you see Promise {<fulfilled>: undefined} in the console but no announcement on the page, see Troubleshooting: announcement not showing.

Build your own badge and announcement

By default, Cello draws the notification badge and announcements on your launcher, using the selectors you set in Cello Portal. You can draw them in your own components instead. cello.js tells you when the unread counts or the active announcement change, and you decide how they look. This is useful when:
  • Your launcher can’t be in the DOM before Cello initializes, for example in a single-page app.
  • You want the badge and announcement to match your own design system.
  • You want to show the number of unread rewards. Cello’s own badge is always a dot.
Each part below works on its own, so you can replace only the badge, only the announcement, or the whole launcher.

Open the Referral Component from your own launcher

Call open() from your launcher’s click handler. Without a destination, the Referral Component opens on the invite tab. Pass "rewards" to open it on the rewards tab instead, for example when your badge shows unread rewards.
Cello doesn’t need to find this element, so it doesn’t have to exist before Cello initializes, and it doesn’t need position: relative or a Custom Launcher Selector. If you don’t want the Cello button as an extra launcher, turn it off. To show the reward in your launcher text, use getLabels().

Show your own badge

Add onUnreadCountChanged to the options of your cello.boot() call from Step 3. It receives two values you can draw your badge from:
  • badgeCount: the number of unread rewards, otherwise 1 for another unread notification such as an unseen alert, otherwise 0. It’s at most 99. Cello’s own badge doesn’t show a number, so this is only available through cello.js.
  • counts.shouldShowBadge: true whenever Cello’s own badge would show. Unlike badgeCount, it also covers new referral link views.
Show a dot, or a number:
Cello calls onUnreadCountChanged right at boot with every count at 0, again once notifications have loaded, and then every time a count changes. It can also be called again with the same values. Both examples handle this, because they only set the badge from the values they get. Start with the badge hidden, so the first call with 0 doesn’t change anything. When the user opens the Referral Component, Cello clears the counts and calls onUnreadCountChanged again, so your badge hides without extra code. If your badge mounts after boot, read the current counts with getUnreadEventCounts(). It returns the same values as counts, including badgeCount, so you can draw the dot or the number right away. If Cello still opens the Referral Component from this element through the Custom Launcher Selector, add data-cello-badge="false" to the element, so Cello doesn’t draw its own badge as well. See Configure notification badge.

Show your own announcement

In User experience → Widget in Cello Portal, leave the Announcement Selector empty and turn off the Cello button, so Cello has nowhere to draw its own announcement. Then add onAnnouncementChanged to the options of your cello.boot() call. Cello calls it with the active announcement, or with null when there’s nothing to show:
  • The call-to-action opens the Referral Component on the page in ctaDestination. That marks the announcement as read, and Cello calls onAnnouncementChanged with null.
  • The close button calls dismissAnnouncement(), which marks the announcement as read without opening the Referral Component. Cello then calls onAnnouncementChanged with null.
  • icon is an optional icon name, Heart, Success or Gift, that you can map to your own icons.
Cello calls onAnnouncementChanged with null right at boot, then with the announcement once it has loaded, if there is one. It’s called again when a new announcement arrives and when its text changes, for example after changeLanguage. If your announcement component mounts after boot, read the active announcement with getActiveAnnouncement():
text can contain <strong> tags. The example above shows it as plain text. To keep the bold parts, sanitize text first, then insert it as HTML.
You place the announcement yourself, so the Announcement Selector requirements and Troubleshooting: announcement not showing don’t apply.

Full example

Both versions connect the launcher, a numbered badge and the announcement to one cello.boot() call. The React version keeps the latest values from Cello in a small store, so components that mount after boot show the current badge and announcement straight away.

Test your components

Testing your badge and announcement
  • Badge: visit the referral link of the user you’re testing with, e.g. moonly.cello.so/pNRB1aYqArN. The view sets shouldShowBadge to true, so a dot badge shows. Views don’t add to badgeCount, so a numbered badge stays hidden until the user has an unread reward or alert.
  • Announcement: run window.Cello("showAnnouncement", { "type": "welcome-announcement-1" }) in your browser console. Cello calls onAnnouncementChanged with the welcome announcement.
  • Clearing: open the Referral Component from your launcher. Cello clears the counts and the announcement, so both disappear.

Troubleshooting: announcement not showing

Short answer: The most common cause is that your Announcement Selector matches more than one element, and the first match in DOM order is invisible (zero-sized, hidden, or off-screen). Cello uses document.querySelector, which always picks the first match. Narrow the selector until document.querySelectorAll(<your selector>) returns exactly one visible element. If you’d rather not depend on a selector at all, show announcements in your own component instead. Cello doesn’t position those, so none of this section applies.

How announcement positioning works

  • Cello calls document.querySelector(<your Announcement Selector>) once when an announcement is rendered.
  • document.querySelector returns the first matching element in DOM order, not the most visible one.
  • The matched element must be present in the DOM, have non-zero width and height, and not be display: none or visibility: hidden at the moment the announcement renders.
  • A fulfilled showAnnouncement promise means the SDK accepted the request. It does not mean the announcement is visible to the user.
  • Cello does not retry, fall back to siblings, or rescan the DOM if the matched element is invisible.

Symptom: showAnnouncement returns a fulfilled promise but nothing appears

If your browser console shows:
…this only means the SDK accepted the call. The announcement may still be invisible because of the selector resolving to a hidden or zero-sized element.

Symptom map

  • Why does showAnnouncement resolve but no announcement appears?
  • Why is my Cello announcement invisible?
  • Why does my Cello announcement render at the top-left of the screen?
  • How do I fix “announcement selector matches multiple elements”?
  • Why does Cello pick the wrong element for my announcement?
  • Cello announcement not working / not showing / not appearing