Skip to main content

Widget trigger events

Once the script is loaded, your page drives the widget by calling functions on window.CheggoutRewards. You decide the moment; the widget handles the rendering and the API calls.

bannerTriggerEvent​

Injects an interactive reward banner into your container when the customer completes a predefined milestone — reaching 100% reading progress, completing a scroll action, or any other qualifying event you define.

window.CheggoutRewards.bannerTriggerEvent(
  virtualId,
  authToken,
  eventType,
  deviceType,
  additionalParams
);
ParameterTypeRequiredDescription
virtualIdstringYesYour unique identifier for the customer
authTokenstringYes for logged-in usersBearer token for the user session
eventTypestringYesThe event identifier, for example "article_read"
deviceTypestringYesClient device type, for example "web" or "mobile"
additionalParamsobjectOptionalExtra metadata — see below

additionalParams​

An object, not a string, on this surface.

{ bannerURL: "https://assets.example.com/your-banner.png" }

bannerURL is optional. Supply it and that image is displayed; omit it and the widget renders its default static banner. When you have nothing to send, pass an empty object rather than omitting the argument.

A typical call​

const virtualId = sessionStorage.getItem('vid');
const authToken = getCheggoutToken();   // from your backend

window.CheggoutRewards.bannerTriggerEvent(
  virtualId,
  authToken,
  'article_read',
  'web',
  {}
);
Pick a meaningful milestone

The banner performs best when it appears as a reward for something the customer just completed — finishing an article, reaching the end of a scroll — rather than on page load. Trigger it at the moment of completion.

checkPendingRewardEvent​

Checks whether the customer has any unclaimed rewards. Call it on landing and home pages, immediately after login.

window.CheggoutRewards.checkPendingRewardEvent(
  virtualId,
  authToken,
  eventType,
  additionalParams
);
ParameterTypeRequiredDescription
virtualIdstringYesYour unique identifier for the customer
authTokenstringYesBearer authentication token
eventTypestringOptionalTarget event type, for example "article_read"
additionalParamsobjectOptionalExtra configuration

This is what closes the loop for a customer who earned a reward as a guest and then signed in. See User states.

// Immediately after your login flow completes
window.CheggoutRewards.checkPendingRewardEvent(
  newVirtualId,
  authToken,
  'article_read',
  {}
);

fetchScratchCard — legacy​

TBD Treat fetchScratchCard as legacy. An earlier integration exposed a simpler call:

window.CheggoutRewards.fetchScratchCard('NULL', virtualId, 'CAMPAIGN_ARTICLEREAD');

with static event types such as CAMPAIGN_ARTICLEREAD, documented as triggering after five events, and CAMPAIGN_ADREAD after four. Additional event types could be added.

The TypeScript declaration published with it:

declare global {
  interface Window {
    CheggoutRewards?: {
      fetchScratchCard: (category: string, virtualId: string, trackerEvent: any) => void;
    };
  }
}
Prefer the current API for new integrations

fetchScratchCard takes no auth token, so it cannot establish a session for a logged-in customer, and its first argument is not used by current builds. CAMPAIGN_ADREAD availability is TBD.

Use bannerTriggerEvent and checkPendingRewardEvent instead. If you already integrated fetchScratchCard, it is not broken — but plan to migrate, and confirm the deprecation timeline with Cheggout.

TBD An articleTriggerEvent variant also exists in current builds but has no published specification. Do not build against it until Cheggout documents it.

Event types​

Event typeWhere it appears
"article_read"The documented example for bannerTriggerEvent and checkPendingRewardEvent
CAMPAIGN_ARTICLEREADLegacy fetchScratchCard
CAMPAIGN_ADREADLegacy fetchScratchCard — availability TBD

TBD The authoritative event-type registry is not published. Your codes are agreed with Cheggout during campaign setup, and they must match what is configured for your channel or the trigger will not produce a reward. See Trigger events.

Avoiding duplicate triggers​

Firing bannerTriggerEvent repeatedly for the same article gives the customer a banner they already dismissed. The widget writes interaction state to browser storage that you can read to prevent it — see Interaction data.

const articleId = getCurrentArticleId();
const alreadyClicked =
  localStorage.getItem(`cheggout_banner_clicked_${articleId}`) === 'true';

if (!alreadyClicked) {
  window.CheggoutRewards.bannerTriggerEvent(virtualId, authToken, 'article_read', 'web', {});
}

Defensive calling​

The script loads asynchronously, so guard your calls:

function triggerCheggoutBanner(virtualId, authToken) {
  if (window.CheggoutRewards && window.CheggoutRewards.bannerTriggerEvent) {
    window.CheggoutRewards.bannerTriggerEvent(virtualId, authToken, 'article_read', 'web', {});
  }
  // If the widget hasn't loaded, do nothing. Never block your page on it.
}

Next​