Kigo Welcome Modal Configuration

Overview

The Kigo Welcome Modal System provides partners the ability to configure an introductory modal experience for SDK-hosted sites. This modal is commonly used to guide first-time users, highlight new features, or onboard users to specific program benefits.

The configuration is defined within the WelcomeModalContext type, which allows granular control over modal visibility, title, descriptive text, image assets, and the page order within the modal.

Priority & Structure

The welcome modal settings are defined under the uiuxOverride property in the SDK context. The structure allows multiple UI customizations, including but not limited to the welcome modal.

Configuration Priority

1. Program-level configuration (set in database)
2. Hosted site override via uiuxOverride context
3. SDK default behavior (fallback, disabled by default)

Welcome Modal Context Structure

export type WelcomeModalContext = {
  enabled: boolean;
  pages?: Array<{
    title: string;
    copyText: string;
    pageOrder: number;
    imageUrl?: string;
  }>;
};

Each page object defines a step in the welcome flow. The order of display is controlled by pageOrder. Pages without a valid title or copyText will be ignored.

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.partner.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.partner.com/images/welcome-2.png'
      }
    ]
  }
};

Implementation Guide

1. Enabling the Modal

Set enabled: true to activate the welcome modal. If omitted or set to false, the modal will not render.

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. Controls display sequence.
• imageUrl (string, optional): Optional image to visually support the message.

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: [...]
  },
  'estimated-savings-count': {
    enabled: true
  },
  'wallet-icon': {
    enabled: true
  },
  'wallet-icon-url': {
    url: 'https://cdn.partner.com/icons/wallet.svg'
  },
  'national-deals': {
    title: 'Popular Deals in Your Area'
  }
};

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

• First-time only: Consider tracking modal completion to only show once per session or user.
• Device testing: Validate layout on mobile, tablet, and desktop.
• Loading: Use optimized images (preferably SVG or compressed PNG/JPEG).

Troubleshooting

Common Issues

1. Modal not displaying: Ensure enabled: true and that the SDK has the latest uiuxOverride context.
2. Page order incorrect: Confirm unique pageOrder values and that they start from 1 or 0.
3. Image not loading: 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.
• Check console logs for warnings about malformed pages.
• 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.