Kigo TOP SDK Context Configuration

The Kigo TOP SDK Context is a dynamic configuration system that allows partners to tailor the behavior, branding, and user experience of the Kigo Tokenized Offers Platform (TOP). This context provides flexible, deeply mergeable customization for program branding, theming, components, labels, language, UX features, and more.

Setting the Kigo Context

Initial Setup

You can configure the KigoContext when the Kigo TOP SDK is initialized. This is typically done within the Kigo.onReady method, which fires once the SDK is fully loaded and ready:

window.Kigo.onReady = function (kigo) {
  kigo.setContext({
    theme: {
      palette: {
        primary: '#007BFF',
        secondary: '#F5F5F5',
        fontAccentColor: '#007BFF' // optional. Used for link-style buttons, e.g. "Return to offers", estimated savings
      }
    }
  });
};

Updating the Context Asynchronously

After the SDK is ready, you can modify the context at runtime using Kigo.setContext, ideal for updating data after authentication or fetching dynamic configurations:

window.Kigo.setContext({
  locale: {
    merchantProductLabel: { singular: 'merchant', plural: 'merchants' }
  },
  showTrendingTags: true
});

Deep Merging Behavior

The Kigo TOP SDK uses deep merging for context updates. Only the properties you provide will override defaults or previous values—everything else remains unchanged. Arrays are replaced, not concatenated.

// Only updates the wallet banner display; other wallet config stays intact
window.Kigo.setContext({
  walletConfig: {
    showBanner: false
  }
});

📘
Validation
The SDK validates the merged context. theme.palette.primary and theme.palette.secondary must be hex colors (#RGB or #RRGGBB). If validation fails, the SDK shows its error screen instead of the experience.

Context Type Reference

The KigoContext supports the following commonly used options. All fields are optional unless noted.

type KigoContext = {
  theme?: {
    palette: {
      primary: string;            // hex color
      secondary: string;          // hex color
      fontAccentColor?: string;   // link-style buttons and text highlights
      iconAccentColor?: string;
      bannerAccentColor?: string;
      sectionTitleColor?: string; // homepage section titles
      categoryChip?: CategoryChipPalette; // category filter chips
      categoryTile?: CategorySurfacePalette; // Popular Categories tiles
    };
    typography?: {
      fontFamily?: string;
      titleFontFamily?: string;
      buttonFontFamily?: string;
      fontSources?: Array<{ family: string; url: string }>;
      // Per-variant overrides: { fontFamily?, fontSize?, fontWeight?, letterSpacing?, lineHeight? }
      titleXl?; titleLg?; titleMd?; titleSmBd?; titleSm?; titleXs?;
      bodyMdBold?; bodyMd?; bodySmBold?; bodySm?; bodyXsBold?; bodyXs?;
    };
    customStyles?: {
      injectedCSS?: string; // raw CSS injected into the SDK's Shadow DOM
    };
  };
  i18n?: {
    locale?: 'en' | 'fr-CA';
    translations?: { [language: string]: { [namespace: string]: Record<string, unknown> } };
  };
  locale?: {
    // Each label is { singular?: string; plural?: string }
    merchantProductLabel?; rewardLabel?; walletLabel?; offerLabel?; cashBackLabel?;
    programNameLabel?; cardLabel?; locationLabel?; lightningDealLabel?; receiptLabel?;
  };
  components?: {
    Header?: {
      defaultProps: {
        logo: string;
        backgroundColor: string;
        secondaryLogo?: string;
        logoMaxWidth?: string;
        logoMaxHeight?: string;
        textColor?: string;
        borderColor?: string;
        headerButtonBackgroundColor?: string;
        headerButtonTextColor?: string;
      };
    };
    Landing?: {
      defaultProps: {
        backgroundImage?: string;
        merchantProduct?: string;
        landingTitle?: string;
        zipCode?: string;
      };
    };
  };
  provider?: {
    partnerId?: string;
    partnerName?: string;
    programId?: string;
    externalProgramId?: string;
    programName?: string;
    logo?: string;
  };
  user?: {
    accountId?: string;
    email?: string;
    firstName?: string;
    lastName?: string;
    authorized?: boolean;
  };
  programCampaign?: {
    id?: string;
    programId?: string;
    partnerId?: string;
    startDate?: string; // ISO 8601
    endDate?: string;   // ISO 8601
    campaignName?: string;
  };
  contacts?: {
    supportEmail?: string;
    supportLinkUrl?: string;
    shopLinkUrl?: string;
    faqLinkUrl?: string;
  };
  uiuxOverride?: {
    'welcome-modal'?: {
      enabled: boolean;
      pages?: Array<{
        title: string;
        copyText: string;
        pageOrder: number;
        imageUrl?: string;
        backgroundImage?: string;
        backgroundGradient?: string;
      }>;
    };
    'estimated-savings-count'?: { enabled?: boolean };
    'wallet-icon'?: { enabled?: boolean };
    'wallet-icon-url'?: { url?: string };
    'share-with-friend'?: { enabled?: boolean };
    'send-to-phone'?: { enabled?: boolean };
    'show-chip-filters'?: { enabled?: boolean };
    'category-filter-chips'?: { enabled?: boolean };
    'return-to-home-link-offer-list'?: { enabled?: boolean; label?: string };
    'first-time-favorite-modal'?: { enabled?: boolean };
    'redemption-survey'?: { enabled?: boolean };
    'language-selector'?: { enabled?: boolean };
    'offer-click'?: { preventDefaultNavigation?: boolean };  // hand offer clicks to window.Kigo.onOfferClick
    'token-click'?: {                                         // hand token clicks to window.Kigo.onTokenClick
      preventDefaultNavigation?: boolean;
      preventDefaultNavigationByType?: Record<string, boolean>;
    };
    'offer-search'?: { preventDefaultNavigation?: boolean }; // hand searches to window.Kigo.onSearch
    'filter-modal'?: {
      hiddenSections?: Array<'trending_deals' | 'categories' | 'how_to_use' | 'offer_type'>;
      hiddenChips?: { [section: string]: string[] };
    };
    'page-configurations'?: PageConfigurationsContext; // see Component Placement
  };
  deeplinkUrls?: {
    shareToken?: string;
  };
  location?: {
    address?: string;                // full address, city, state, or zip code
    respectUserSetLocation?: boolean; // don't apply `address` if the user already set a location
  };
  walletConfig?: {
    showBanner?: boolean;
    showCashbackChip?: boolean;
    showRedeemedValue?: boolean;
    showShareWithFriend?: boolean;
    showMyOrdersChip?: boolean;
    showEstimatedSavings?: boolean;
  };
  redemption?: {
    clickThroughUrlTarget?: string; // e.g. '_self'. Default '_blank'
    clickThroughURLPrefix?: string; // prefix added to click-through URLs
  };
  showCashBackOffers?: boolean;
  showTrendingTags?: boolean;
  showLightningDealsFilter?: boolean;
  showAccountDropdown?: boolean;
  accountDropdownConfig?: {
    showLabel: boolean;
    showHistory: boolean;
    showManageAccount: boolean;
    showHelpAndFAQs: boolean;
    showLegal: boolean;
    showSignOut?: boolean;
    helpAndFAQsUrl?: string;
    showTermsOfService?: boolean;
    termsOfServiceUrl?: string;
    showPrivacyPolicy?: boolean;
    privacyPolicyUrl?: string;
  };
  loggerOptions?: {
    level?: 'debug' | 'info' | 'warn' | 'error'; // default 'error'
  };
};

Example Usage

window.Kigo.onReady = function (kigo) {
  kigo.setContext({
    theme: {
      palette: {
        primary: '#1B998B',
        secondary: '#E6FFFA'
      }
    },
    i18n: {
      locale: 'en'
    },
    walletConfig: {
      showBanner: true,
      showCashbackChip: true,
      showRedeemedValue: true,
      showShareWithFriend: true
    },
    uiuxOverride: {
      'welcome-modal': {
        enabled: true,
        pages: [
          {
            title: 'Welcome!',
            copyText: 'Start saving with local offers.',
            pageOrder: 1
          }
        ]
      }
    }
  });
};

Summary

Initial Setup: Use Kigo.onReady to configure context during SDK load.
Async Updates: Use Kigo.setContext anytime after the SDK is ready.
Deep Merging: Partial updates preserve previous settings; arrays are replaced.
Modular Flexibility: Configure components, branding, language, labels, and UX overrides.

The KigoContext empowers partners to deliver a branded, dynamic, and feature-rich experience through the Kigo TOP SDK, tailored to each program or hosted site.