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

​
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)
// ❌ WRONG: Element created after Cello initialization
function MyComponent() {
  const [celloReady, setCelloReady] = useState(false);
  
  useEffect(() => {
    initializeCello(); // Initializes Cello
    setCelloReady(true);
  }, []);
  
  return (
    <>
      {celloReady && (
        <button id="cello-launcher">Invite</button> // Too late!
      )}
    </>
  );
}

// ✅ CORRECT: Element exists before Cello initialization
function MyComponent() {
  const [celloReady, setCelloReady] = useState(false);
  
  useEffect(() => {
    // Element already exists in DOM
    initializeCello(); // Now initialize Cello
    setCelloReady(true);
  }, []);
  
  return (
    <>
      <button 
        id="cello-launcher"
        style={{ 
          position: 'relative',
          display: celloReady ? 'block' : 'none' 
        }}
      >
        Invite Friends
      </button>
    </>
  );
}

​
Step 2: Configure Cello Portal

  1. Navigate to Referrer Experience 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: 
window.cello = window.cello || { cmd: [] };

window.cello.cmd.push(async (cello) => {
  try {
    await cello.boot({
      productId: "YOUR_PRODUCT_ID",
      token: "USER_JWT_TOKEN",
      // ... other configuration
    });
    
    console.log("Cello initialized successfully");
    // Custom launcher is now active
  } catch (error) {
    console.error("Failed to initialize Cello:", error);
  }
});

​
Common Issues and Solutions

​
Custom launcher not working

​
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. 
const labels = await window.Cello("getLabels")
const myCustomLauncherLabel = labels.customLauncher

​
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 Referrer experience 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)

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.
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 Referrer Experience in Cello Portal. 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:
window.Cello("showAnnouncement", { "type": "welcome-announcement-1" })