Pre-launch Testbook

This testbook walks you through testing your Cello integration on your own, from first event to launch. By the end you should have:

• The referral widget and attribution library connected
• Signups and purchases tracked, with events validated as correct
• The manual front-end checks done that the portal can’t see for you
• Everything ready to launch your program

This is the full testbook behind the View full test book link in the launch checklist and on the Technical integration page.

​

Integrate, test, and launch

You integrate, test, and launch all from your main account. While you build and test, the account stays in pre-launch (testing) mode, so everything in this testbook runs safely against your real product - nothing reaches your referrers until you go live. When you launch your program, payouts begin, notifications start reaching real referrers, the payout delay applies, and all new events and data are treated as live. You don’t need a sandbox to run this testbook - testing happens directly in pre-launch. A sandbox is an optional, fully isolated environment with its own credentials (My account → Create sandbox). It’s how you test changes once you’re live, because launching is not reversible.

​

What this testbook covers

Six areas, each testing one part of your integration. Read this table first to see which ones apply to you, then work through them in order. Then check Alternative scenarios for anything else that describes your setup - a partners-only program, a mobile app, organization-level rewards, Auto Attribution, or report-based attribution.

​

Before you start

• You can sign in to the Cello Portal, and your main account is in pre-launch (testing) mode
• The referral component, attribution library, and your signup and purchase events are implemented (see the Setup Overview)
• You have test accounts for every signup method you support (email/password, Google SSO, Microsoft SSO, and so on) - you’ll need a fresh user per signup test
• You have access to your payment gateway’s test mode, for example Stripe test cards or the Chargebee test gateway

Definition of done: all four components report Connected when you ask your coding tool for your integration status, your events validate as OK under Developers → Events, and the manual checks in each area pass. That’s everything the launch checklist asks for - then you can launch your program.

​

Where to check things

Two places do most of the work:

​

When each surface updates

Cello’s surfaces refresh at different speeds, so give each one time before assuming something is broken. These intervals are the same in pre-launch as they are once you’re live.

​

Test by area

Each area below follows the same shape: what it needs before you start, what to do, and what you should see when it works.

​

Referral component

The referral widget (cello.js) booting in your app, plus the referrer-facing experience around it. Prerequisite: the referral component is implemented and boots at login - not lazily when the launcher is first clicked. Booting at login is what makes notifications and rewards ready the moment a referrer signs in, and it’s what produces the booted events Cello tracks. Do this: log in as a new user without opening the widget, so the component has to boot on its own. Open dev tools → Network, filter for cello, and reload. Then ask your coding tool for your integration status, and open the widget as a referrer. You should see If it’s not working

• If only cello.js loads and no v2?... request follows, Cello is loaded but not booted. Boot it on login.
• A JWT token error means the widget token is missing, malformed, or expired. Regenerate it on your backend - see User Authentication.

​

Notifications

The badge, in-app announcements, and emails that keep referrers engaged. See Referral notifications and emails. Prerequisites

• The referral component is integrated and booting, so the badge and announcements can anchor to the launcher. If you use a custom launcher, it’s anchored to a unique selector.
• The boot command sends productUserDetails with at least email, and firstName for personalization. Both are required for emails - see the boot command.
• Notifications send on their own in pre-launch, so they reach your test users when the activity that triggers them happens.

Do this: review the email and announcement previews in the Portal, then run the activity behind each notification - have a referral link viewed, and let a referred signup and a reward come through - so the badge, announcement and email reach your test user. To check an announcement’s placement without waiting for a trigger, render one on demand from your browser dev console with window.Cello("showAnnouncement", ...), for example { type: "welcome-announcement-1" }. You should see If it’s not working: if the announcement doesn’t show, check your Announcement Selector matches exactly one visible element.

​

Capturing the referral code

The attribution library (cello-attribution.js) on your landing pages, capturing the referral code (ucc) when someone clicks a referral link. Prerequisite: the attribution library is embedded on every page reachable from a referral link, and your signup URL is set in User Experience → Settings. See Web attribution setup. Do this: open one of your referral links in a fresh incognito window to land on your page, then ask your coding tool for your integration status. You should see If it’s not working: “no signup URL” means you need to set your signup URL in User Experience → Settings. If it stays Not connected, confirm cello-attribution.js is embedded on the landing pages reachable from your referral links.

​

Signup tracking

Referred signups reaching Cello and being attributed to the referrer. Prerequisite: your signup source is set (self-serve in pre-launch) and signups are implemented for that source. Do this: complete a referred signup by following a referral link and signing up, then check your integration status and open Developers → Events. Repeat for every signup method you support, testing both a direct signup (open the link, go straight to signup) and an indirect one (open the link, browse around your site, then sign up). You should see If it’s not working: “events received, none attributed” means your events are arriving without a referral code. Open Developers → Events to see which ucc is missing or malformed.

​

Applying discounts

The new-user discount your referred users get at checkout. Applies if you offer a discount, typically freemium or trial. Prerequisite: a new-user discount is configured for your campaign. See Apply discounts and New user discounts. Do this: as the referred user from Signup tracking, go to your upgrade or checkout page. You should see

​

Purchase tracking

Referred purchases reaching Cello with the right fields, so rewards can be calculated. Prerequisite: your purchase source is set (self-serve in pre-launch) and purchases are implemented for that source. Do this: with the referred user from Signup tracking, complete a test purchase using your gateway’s test card, then check your integration status and open Developers → Events. You should see

​

Alternative scenarios

Only work through the ones that describe your setup.

​

Partners only

You run a partner or affiliate program with no in-app referral widget. Partners get their sharing link and see their performance in the Cello-hosted Partner Portal, so cello.js is never deployed in your product. What still applies: Capturing the referral code, Signup tracking and Purchase tracking, exactly as written above. A partner’s referral link is attributed the same way any referral link is. What doesn’t apply: Referral component and Notifications. Both test the in-app widget, which you don’t have. Prerequisites

• A partner campaign exists. You can’t invite partners without one.
• You’ve invited yourself as a test partner from Partner Users. See Manage partners.

Do this: register from the invite email, then run a full referral through your own partner link - land on your site, sign up as a new user, and complete a test purchase. You should see For how the program is set up end to end, see the Partner program overview.

​

Mobile app

Users can sign up directly inside your mobile app, so attribution has to work there too. See the Mobile SDKs.

​

Organization-level attribution

Rewards attach to an organization or team rather than an individual user.

​

Auto Attribution

You opted into Auto Attribution instead of sending your own events. See the Auto Attribution guide.

​

Report-based attribution

Only if you can’t send events automatically. This is less reliable and higher-maintenance - prefer a webhook or the Cello API where possible. See Report-based attribution.

​

Launch your program

When the checks above pass, you’re ready to go live. Do one last thing to your payment provider first, then launch from the Home page.

​

Switch your payment provider to live credentials

You tested against your gateway’s test mode, so the webhook forwarding events to Cello is a test-mode endpoint with a test-mode signing secret. Stripe and Chargebee keep test and live as separate environments, so that webhook never fires for a real purchase - signups and purchases would silently stop being attributed the moment you go live. Add the same webhook in live mode, update the signing secret under Developers → Webhooks, and re-check your integration status once a real event has come through. This is about your payment provider’s environment, not Cello’s. Your Cello account is already production - launching only takes it out of pre-launch mode.

​

Confirm the pre-launch checklist

On the Home page, open the Go live card. A short pre-launch checklist appears confirming the essentials this testbook covers - one item per area above:

• Referral widget loads and opens for signed-in users
• Notifications work: badge, announcement, email
• New users land on the correct page from a referral link
• Signups are attributed to the referrer
• The new-user discount shows correctly at checkout, if your offer includes one
• Purchases are attributed to the referrer

The four event-based items also report Connected in your integration status. Confirm them, then Launch program.

​

After you launch

Re-check your integration status periodically. It flags when an upstream change - a redeployed script, a rotated webhook secret - silently breaks a component.