Kigo Welcome Modal Configuration

Overview

The Kigo Welcome Modal System provides partners the ability to configure an introductory modal experience for SDK-hosted sites using the Kigo TOP SDK. The modal is a multi-page carousel used to guide first-time users, highlight features, or onboard users to specific program benefits.

The modal is shown once per member: the first time a signed-in member enters the experience. It is not shown in anonymous sessions.

The configuration is defined within the WelcomeModalContext type, which controls modal visibility, page titles, descriptive text, and page artwork.

Priority & Structure

The welcome modal settings are defined under uiuxOverride['welcome-modal'] in the SDK context.

Visibility

Hosted site override: enabled: false always hides the modal; enabled: true shows it without any backend configuration
Program-level configuration (set by Kigo) when no context override is set

📘
Default
The Kigo TOP SDK default context sets 'welcome-modal': { enabled: true }. Set enabled: false to turn the modal off.

Page Content

Hosted site override: pages in context, when one or more pages are provided
Program-level configuration (set by Kigo)
SDK default pages (built-in, translated slides)

Welcome Modal Context Structure

export type WelcomeModalPage = {
  title: string;
  copyText: string;
  pageOrder: number;
  imageUrl?: string;
  backgroundGradient?: string;
  backgroundImage?: string;
};

export type WelcomeModalContext = {
  enabled: boolean;
  pages?: WelcomeModalPage[];
};

Each page object defines a step in the welcome flow. Pages are displayed in the order they appear in the pages array, so list them in the order you want them shown.

Example Configuration

const uiuxOverride = {
  'welcome-modal': {
    enabled: true,
    pages: [
      {
        title: 'Welcome to Your Rewards!',
        copyText: 'Discover and redeem local and online offers instantly.',
        pageOrder: 1,
        imageUrl: 'https://cdn.example.com/images/welcome-1.png'
      },
      {
        title: 'Track Your Savings',
        copyText: 'Keep an eye on how much you save with each redemption.',
        pageOrder: 2,
        imageUrl: 'https://cdn.example.com/images/welcome-2.png'
      }
    ]
  }
};

window.Kigo.setContext({ uiuxOverride });

Implementation Guide

1. Enabling the Modal

Set enabled: true to activate the welcome modal, or enabled: false to suppress it. If you omit the 'welcome-modal' key entirely, the SDK default (enabled: true) applies.

2. Defining Pages

title (string): Required. Displayed at the top of the modal page.
copyText (string): Required. Supporting description or guidance text.
pageOrder (number): Required. Must be unique per page. Display order follows the array order.
imageUrl (string, optional): Image displayed on the page.
backgroundGradient (string, optional): CSS gradient painted behind the page artwork, e.g. 'linear-gradient(180deg, #E992FD 0%, #FEA3C4 50%, #FFF 100%)'.
backgroundImage (string, optional): Artwork image composited over backgroundGradient.

3. Artwork Styles

The modal renders pages in one of two styles:

Image style (default): each page's imageUrl is displayed as the page image.
Gradient style: used when any page sets backgroundGradient or backgroundImage. Each page shows its backgroundImage over its backgroundGradient, and imageUrl is not displayed.

Use one style consistently across all pages.

4. Using the Default Pages

To keep the SDK's built-in (translated) pages, set enabled: true and leave pages unset. Passing pages replaces any program-level and default pages.

Integration with UIUX Overrides

The welcome modal is part of a broader configuration system under uiuxOverride. Here’s how it fits alongside other configurable features:

const uiuxOverride = {
  'welcome-modal': {
    enabled: true,
    pages: [...]
  },
  'first-time-favorite-modal': {
    enabled: true
  },
  'estimated-savings-count': {
    enabled: true
  },
  'wallet-icon': {
    enabled: true
  },
  'wallet-icon-url': {
    url: 'https://cdn.example.com/icons/wallet.svg'
  }
};

For homepage layout options, see Kigo Context - UI/UX Page Configuration.

Best Practices

1. Modal Design Guidelines

Concise text: Keep title and copyText brief and scannable.
Consistent visuals: Use brand-compliant imagery sized appropriately for all screen sizes.
Accessible colors and contrast: Ensure text and images meet accessibility standards.

2. UX Considerations

Language: Pages passed in context are displayed as-is in every language. Leave pages unset to use the SDK's translated default pages, or update pages when the language changes.
Device testing: Validate layout on mobile, tablet, and desktop.
Loading: Use optimized images (preferably SVG or compressed PNG/JPEG).

Troubleshooting

Common Issues

Modal not displaying: Ensure enabled is not false, the member is signed in (not an anonymous session), and this is the member's first visit. The modal is shown only once per member.
Page order incorrect: Pages are shown in array order. Reorder the pages array and keep pageOrder values unique.
Image not showing: If any page sets backgroundGradient or backgroundImage, imageUrl is not displayed. Otherwise, check CORS policies and ensure the image URL is reachable from the hosted SDK domain.

Debugging Tips

Use browser dev tools to inspect the window.Kigo.setContext() payload.
Validate image URLs manually in the browser to rule out loading issues.

This configuration allows partners to create a branded and informative onboarding experience that complements their existing reward and offer strategies within the Kigo platform.