Getting Started

This guide will help you integrate the Kigo TOP Web SDK into your application, allowing you to provide a seamless TOP experience for your users.

The SDK is delivered as a single script that registers the <kigo-top-sdk> web component and exposes a global window.Kigo object. The component renders inside its own Shadow DOM, so its styles do not leak into (or inherit from) your page.

Step 1: Include the SDK via CDN

Add one of the following script tags to your HTML file:

<!-- STAGING -->
<script src="https://d3td6rmpnfkvdh.cloudfront.net/kigo-top-sdk/latest/kigo-top-sdk.iife.js"></script>

<!-- PROD -->
<script src="https://d1rp7meewdhinj.cloudfront.net/kigo-top-sdk/latest/kigo-top-sdk.iife.js"></script>

Step 2: Obtain a User Session Token

The SDK authenticates every request with a user-level session token that your backend creates. For detailed instructions, refer to the following resources:

Step 3: Set Up the SDK in Your HTML

Add the <kigo-top-sdk> element to your page, then load the SDK script and configure it from window.Kigo.onReady:

<!DOCTYPE html>
<html lang="en">
<head>
    <title>Kigo TOP Web SDK Example</title>
</head>
<body>
    <!-- Add the kigo-top-sdk web component to your page -->
    <kigo-top-sdk></kigo-top-sdk>

    <script>
      function setupKigo() {
        window.Kigo.onReady = function (kigo) {
          kigo.initialEntries = ['/home']; // Default. To open an offer directly use ['/offers/{offer_id}']. See "Initial Entries".
          kigo.setAuthorizationToken('your-session-token');

          // Called when the stored token has expired, before the next API request.
          // Return a new token (the SDK stores it for you).
          kigo.refreshAuthorizationToken = async function () {
            const response = await fetch('/api/your-backend-endpoint', { method: 'POST' });
            const data = await response.json();
            return data.token;
          };

          // Called when an API request returns 401 Unauthorized.
          kigo.onAuthorizationError = function (error) {
            fetch('/api/your-backend-endpoint', { method: 'POST' })
              .then((response) => response.json())
              .then((data) => kigo.setAuthorizationToken(data.token));
          };

          kigo.setContext({
            theme: {
              palette: {
                primary: '#000000',   // Required format: hex color (#RGB or #RRGGBB)
                secondary: '#FFFFFF', // Required format: hex color (#RGB or #RRGGBB)
                fontAccentColor: '#000000', // Optional. Used for link-style buttons, e.g. "Return to offers", estimated savings
              },
              typography: { // Optional. Only needed for custom fonts
                fontSources: [
                  {
                    family: 'Inter',
                    url: 'https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700;800&display=swap',
                  },
                ],
                fontFamily: 'Inter, -apple-system, BlinkMacSystemFont, sans-serif',
                titleFontFamily: 'Inter, -apple-system, BlinkMacSystemFont, sans-serif',
                // Optional per-variant overrides
                titleXl: {
                  fontSize: '48px',
                  fontWeight: 800,
                  letterSpacing: '-0.02em',
                  lineHeight: '1.1',
                },
                bodyMd: {
                  fontSize: '16px',
                  fontWeight: 400,
                  lineHeight: '1.5',
                },
              },
            },
            provider: {
              externalProgramId: 'your-external-program-id',
              programName: 'your-program-name',
              partnerId: 'your-partner-id',
            },
            uiuxOverride: {
              'welcome-modal': { enabled: true },           // optional - boolean
              'estimated-savings-count': { enabled: true }, // optional - boolean
              'wallet-icon': { enabled: true },             // optional - boolean
              'wallet-icon-url': { url: '' },               // optional - string
              'share-with-friend': { enabled: false },      // optional - shows/hides "Share with friend" on the offer details page
            },
            redemption: {
              clickThroughUrlTarget: '_self', // optional - target for online offer links. Default is "_blank" (new tab)
              clickThroughURLPrefix: 'app://', // optional - prefix added to click-through URLs, e.g. "app://https://example.com"
            },
            location: {
              // Optional. Pre-sets the user's location. Can be a full address, city, state, or zip code.
              // e.g. "Minnesota", "55432", "Minneapolis", "123 Main St, Minneapolis, MN 55401"
              address: '',
            },
          });
        };
      }
    </script>

    <!-- Include the Kigo TOP SDK script (PROD) -->
    <script
      src="https://d1rp7meewdhinj.cloudfront.net/kigo-top-sdk/latest/kigo-top-sdk.iife.js"
      onload="setupKigo()"
      crossorigin="anonymous"
    ></script>

    <!-- Include the Kigo TOP SDK script (STAGING) -->
    <!-- <script -->
      <!-- src="https://d3td6rmpnfkvdh.cloudfront.net/kigo-top-sdk/latest/kigo-top-sdk.iife.js" -->
      <!-- onload="setupKigo()" -->
      <!-- crossorigin="anonymous" -->
    <!-- ></script> -->
</body>
</html>

📘
Context validation
The SDK validates the context when it is set. Values such as theme.palette.primary and theme.palette.secondary must be valid hex colors; an invalid context shows the SDK's error screen instead of the experience. See Kigo Context for all options.

`window.Kigo` Reference

Member	Type	Description
`onReady`	`(kigo) => void`	Called once the SDK has mounted. `kigo` is the `window.Kigo` object.
`setAuthorizationToken`	`(token: string) => void`	Stores the user session token. See Authentication.
`refreshAuthorizationToken`	`() => Promise<string>`	Optional. Called when the stored token has expired. Return a new token.
`onAuthorizationError`	`(error) => void`	Optional. Called when an API request returns `401`.
`setContext`	`(context) => void`	Deep-merges configuration into the current context. See Kigo Context.
`initialEntries`	`string[]`	Route(s) the SDK opens on load. Defaults to `['/home']`. See Initial Entries.
`navigate`	`(params) => void`	Navigates within the SDK after it has loaded. See Initial Entries.
`onOfferClick`	`(data) => void`	Optional. Called when a user clicks an offer. Receives `offerId`, `locationId`, `latitude`, `longitude`, `merchantId`, `redemptionMethods`.
`onTokenClick`	`(data) => void`	Optional. Called when a user clicks a token in the wallet. Receives `tokenId`, `tokenName`, `tokenType`, `offerId`, `locationId`, `redemptionMethods`.
`onSearch`	`(data) => void`	Optional. Called when a user submits the header search. Receives `searchText`, `latitude`, `longitude`.
`onCheckoutSuccess`	`(data) => void`	Optional. Called when a user lands on the order confirmation page. Receives `orderId`.
`onWalletCountChange`	`(data) => void`	Optional. Called with `count` when the number of active wallet items changes.

To handle offer clicks, token clicks, or searches entirely in your application, set preventDefaultNavigation: true under uiuxOverride['offer-click'], uiuxOverride['token-click'], or uiuxOverride['offer-search']. The SDK then calls your callback without navigating.

Step 4: Confirm Your Integration

After following these steps, the Kigo TOP SDK should be successfully rendered in your application. You can now begin exploring the SDK's features and customizing the user experience.

Step 1: Include the SDK via CDN

Step 2: Obtain a User Session Token

Step 3: Set Up the SDK in Your HTML

Context validation

window.Kigo Reference

Step 4: Confirm Your Integration

`window.Kigo` Reference