Skip to main content

JavaScript widget overview

The Cheggout Rewards Widget puts scratch cards and reward banners on a website with one script tag. You call a function when the user does something worth rewarding; the widget draws the banner, runs the scratch interaction, and talks to Cheggout's APIs on its own.

It is the lowest-effort way to add rewards to a web property, and the right answer for publishers whose engagement moments are page-level — an article finished, a scroll milestone, a transaction confirmed.

The widget is distributed from a UAT host today

Beta The only published script URL is a UAT blob host. There is no production distribution URL yet. Build against UAT, and confirm the production URL with Cheggout before you plan a launch date — this is a hard blocker for going live, not a detail to settle later. Tracked in Open items.

What it is​

A single lightweight browser script, cheggout-widget.iife.js, built with React and Vite. It bundles all widget components, assets, styles and business logic into a self-contained package — there is nothing else to install, no framework requirement on your page, and no build step on your side.

Being an IIFE bundle matters practically: it does not require a module loader, it does not register itself in your dependency graph, and it exposes exactly one thing on the page, window.CheggoutRewards.

What it renders​

Two surfaces, designed to reward users after they read a certain number of articles or perform key actions:

ComponentWhat it isHow it appears
Reward bannerAn interactive banner promoting an available rewardInjected into a container <div> you place on the page
Scratch card overlayThe scratch interaction and the revealed rewardOpened over your page when the user engages with the banner

The journey inside the widget runs from the reward banner, to the scratch card overlay, to a reward claimed state. You do not build any of those screens.

Architecture​

Four layers, from your page down to Cheggout's campaign data:

The UI flow inside layer 2 is linear: Reward Banner → Scratch Card Overlay → Reward Claimed.

You call functions, not endpoints

The widget's internal API paths are an implementation detail and are deliberately not published as endpoint contracts. Your integration surface is window.CheggoutRewards — the trigger event functions — plus the server-side token call your backend makes. Do not reverse-engineer the widget's network traffic into your own client; it will change.

The one exception is the token API, which your backend calls directly because it requires a signed envelope. See User states and tokens.

When to use it​

The widget is the right choice when all of these hold:

  • Your engagement moment happens in a browser, on a page you control.
  • You are happy with Cheggout's banner and scratch card visuals. You place the container; you do not restyle the contents.
  • You can serve the page over HTTPS and can add a script tag to your template.
  • You have a backend that can hold an RSA private key and mint user tokens.

Choose something else when:

SituationBetter surface
You want to design the card and reveal yourselfHeadless API
The moment happens in a native appAndroid or iOS SDK
You want the full 600-retailer marketplace, not just rewardsHosted PWA or the native SDKs
You need coupons and deals with your own coin economyDeals Store API
You cannot run a backend that signs requestsReconsider — no surface works without one

What you are responsible for​

The widget draws and decides nothing. You own:

  • Placing the container with the exact id the widget looks for.
  • Deciding when to trigger. The widget does not watch your page. You call bannerTriggerEvent when your own milestone logic says the user earned a look.
  • Identity. You pass virtualId. "guest" has a specific meaning — see User states.
  • Tokens. Minted server-side, valid one hour, refreshed by you.
  • De-duplication. Preventing the same article from triggering repeatedly. The widget writes localStorage keys you can read for exactly this; see Interaction data.

Try it first​

A sample demo app demonstrating the scratch card functionality is available at:

https://cheggoutsampleapp.z29.web.core.windows.net/news

Open it before writing any code. Seeing the banner appear and the overlay open takes five minutes and settles most design questions about where to put the container on your own page.

Next​