> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cello.so/llms.txt
> Use this file to discover all available pages before exploring further.

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

```javascript theme={null}
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:

```javascript theme={null}
await window.Cello("boot", options);
```

### Accepts

<ParamField path="options" type="object" required>
  The initialization options object:

  <Expandable title="properties">
    <ParamField path="productId" type="string" required>
      Identifier of the product your users will refer.
      You can obtain this in your Cello Portal.
    </ParamField>

    <ParamField path="token" type="string" required>
      Access token generated for the given user.
      More in [User Authentication](/referral-component/user-authentication).
    </ParamField>

    <ParamField path="productUserDetails" type="object" required>
      Product user details object. Required for select features

      <Expandable title="properties">
        <ParamField path="email" type="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
        </ParamField>

        <ParamField path="firstName" type="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](/docs/add-personalized-message).
          Required for select features
        </ParamField>

        <ParamField path="lastName" type="string">
          Last name of the product user
        </ParamField>

        <ParamField path="fullName" type="string">
          Full name of the product user.
          Use this option if you do not have first name and last name separately.
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField path="productUserCountryCode" type="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](/guides/user-experience/overview#reward-countries-and-payout-methods), 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](/guides/user-experience/overview#reward-countries-and-payout-methods) for tradeoffs before using this to gate visibility.
    </ParamField>

    <ParamField path="language" type="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.
    </ParamField>

    <ParamField path="themeMode" type="string">
      Set light or dark theme to match your app’s interface. Accepts `light` and `dark`.
      Default: `light`.
    </ParamField>

    <ParamField path="hideDefaultLauncher" type="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](/referral-component/custom-launcher#configure-notification-badge). There is no `hideDefaultBadge` boot option.
    </ParamField>

    <ParamField path="onOpen" type="function">
      Callback event for when Referral Component widget is opened.
    </ParamField>

    <ParamField path="onClose" type="function">
      Callback event for when Referral Component widget is closed.
    </ParamField>

    <ParamField path="onUserInteraction" type="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.
    </ParamField>
  </Expandable>
</ParamField>

### Example

```javascript theme={null}
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.

```javascript theme={null}
window.Cello("changeLanguage", "de");
```

### Accepts

<ParamField path="language" type="string" required>
  The language string in ISO 639-1
</ParamField>

## `setThemeMode(theme)`

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

```javascript theme={null}
window.Cello("setThemeMode", "dark");
```

### Accepts

<ParamField path="theme" type="string"> The theme mode to apply. Accepted values are `light` or `dark`. </ParamField>

## `close()`

Closes Referral Component.

```javascript theme={null}
window.Cello.close();
```

***

## `getActiveUcc()`

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

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

### Returns

<ResponseField name="activeUcc" type="object">
  The active ucc object:

  <Expandable title="properties">
    <ResponseField name="ucc" type="string">
      Active unique campaign code or referral code for the current logged-in user
    </ResponseField>

    <ResponseField name="link" type="string">
      Personal invite link for the current logged-in user
    </ResponseField>
  </Expandable>
</ResponseField>

## `getCampaignConfig()`

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

```javascript theme={null}
const campaignConfig = await window.Cello("getCampaignConfig");
```

### Returns

<ResponseField name="campaignConfig" type="object">
  The campaign config object:

  <Expandable title="properties">
    <ResponseField name="primaryCurrency" type="string">
      Primary currency code
    </ResponseField>

    <ResponseField name="revenuePercentage" type="number">
      Percentage of attributed new revenue that will be paid as a reward
    </ResponseField>

    <ResponseField name="rewardCap" type="number">
      Maximum reward that can be earned per referral
    </ResponseField>

    <ResponseField name="newSignupBonus" type="number">
      Additional reward for signups to encourage more sharing
    </ResponseField>

    <ResponseField name="newPurchaseBonus" type="number">
      Additional reward for purchases to encourage more sharing
    </ResponseField>

    <ResponseField name="newUserDiscountMonth" type="number">
      How long new users get a discount
    </ResponseField>

    <ResponseField name="newUserDiscountPercentage" type="number">
      The discount new users get
    </ResponseField>
  </Expandable>
</ResponseField>

## `getLabels()`

Returns select labels used in our Referral Component.

```javascript theme={null}
const labels = await window.Cello("getLabels");
```

### Returns

<ResponseField name="labels" type="object">
  The labels object:

  <Expandable title="properties">
    <ResponseField name="customLauncher" type="string">
      A welcome text useful for building custom launchers
    </ResponseField>
  </Expandable>
</ResponseField>

## `hide()`

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

```javascript theme={null}
window.Cello("hide");
```

***

## `open(destination)`

Opens Referral Component.

```javascript theme={null}
window.Cello("open", destination);
```

### Accepts

<ParamField path="destination" type="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
</ParamField>

## `show()`

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

```javascript theme={null}
window.Cello("show");
```

***

## `showAnnouncement(announcement)`

Triggers an [announcement](/docs/notifications#announcement).

```javascript theme={null}
window.Cello("showAnnouncement", announcement);
```

### Accepts

<ParamField path="announcement" type="string" required />

### Example

Example below triggers a default welcome announcement:

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

<Warning>
  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](/referral-component/custom-launcher#troubleshooting-announcement-not-showing) for the full diagnostic flow.
</Warning>

## `shutdown()`

Shuts down connection to Cello and unmounts the Referral Component.

```javascript theme={null}
window.Cello("shutdown");
```

***

## `updateProductUserDetails(productUserDetails)`

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

```javascript theme={null}
window.Cello("updateProductUserDetails", productUserDetails);
```

### Accepts

<ParamField path="productUserDetails" type="object" required>
  The product user details object

  <Expandable title="properties">
    <ParamField path="email" type="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
    </ParamField>

    <ParamField path="firstName" type="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](/docs/add-personalized-message).
      Required for select features
    </ParamField>

    <ParamField path="lastName" type="string">
      Last name of the product user
    </ParamField>

    <ParamField path="fullName" type="string">
      Full name of the product user.
      Use this option if you do not have first name and last name separately.
    </ParamField>
  </Expandable>
</ParamField>

### Example

```javascript theme={null}
const productUserDetails = {
  email: "bob@gmail.com",
  firstName: "Bob",
  lastName: "Bobsky",
  fullName: "Bob Bobsky",
};
window.Cello("updateProductUserDetails", productUserDetails);
```