Responsibilities

What the Controller Handles

The controller automatically manages data fetching and actions.

Data fetching: get-content-page, get-user-vouchers, get-campaign, user-wallet-ledger.

Actions: Voucher claim/unclaim, wallet select/deselect, campaign interactions. You can disable specific handlers using Handler Overrides.

See Operation Handling Matrix for a complete API-by-API overview.

What You Handle

Authentication

Spaaza does not handle login or token-refresh flows. The host application provides credentials. Two methods are supported. See Controller API > SpaazaAuthConfig for the type reference.

Session-based auth

Use Spaaza's /signup, /login, or /get-user-login-status endpoints to obtain a session key and user ID, then pass them in:

config: {
  auth: {
    sessionKey: 'from-your-login-endpoint',
    userID: 'from-your-login-endpoint',
    myPriceAppHost: '{MyPrice App hostname}'
  }
}

See API Documentation for the login flow.

JWT-based auth

Use when an external identity provider issues JWT access tokens that Spaaza can verify. Pass the token in:

config: {
  auth: {
    jwt: 'eyJhbGciOiJSUzI1NiI...',
    myPriceAppHost: '{MyPrice App hostname}'
  }
}

The host is responsible for the JWT lifecycle. Spaaza is never in the refresh flow:

1. Obtain the initial token from your identity provider.
2. Detect expiry by reading the exp claim and refresh shortly before it expires.
3. Refresh against your identity provider (standard OAuth refresh, outside Spaaza).
4. Swap the token via controller.setJwt(newToken). The next API request uses the new token, SPA-style, no page reload. See Controller API > Controller Methods.

const newToken = await refreshFromYourIdentityProvider();
controller.setJwt(newToken);

User & Store Selection

Fetch the user object with /get-user after authentication. The user object contains the home_store.home_store_id which you pass as businessId to filter content by store:

await initializeSpaazaElements({
  // ...
  businessId: user.home_store.home_store_id
});

Omit businessId to show content for all stores. Use /get-businesses to retrieve available stores. Use /alter-user to update the user's home store ID (home_store_id). See API Documentation for details.

Navigation

• Controller fires content:select events when users click content
• Both web components are always mounted. You control their visibility
• To load new data, set properties (pagename, campaignid, voucherid) on the web components. The controller fetches automatically
• Or reload the URL passing the data as query parameters

See Navigation for the two approaches (URL reload and SPA) and Navigation Handling Examples for full implementation patterns.

Handler Overrides

Handler overrides let you disable the controller's automatic handling for specific operations, so your application can handle them instead.

const controller = await initializeSpaazaElements({
  config: {...},
  handlerOverrides: {
    'voucher-claim': 'disabled',
    'wallet-value-select': 'disabled'
  }
});

The keys correspond to event action names as listed in the Operation Handling Matrix. When an action is disabled, content:action:start still fires. You listen for it and handle the action yourself:

document.addEventListener('content:action:start', (event) => {
  const { action, campaign_info, voucher_info } = event.detail;

  if (action === 'voucher-claim') {
    showConfirmDialog().then((confirmed) => {
      if (confirmed) {
        yourApi.claimVoucher(voucher_info.voucherId);
      }
    });
  }
});

Useful for custom confirmation dialogs, intercepting actions for analytics, or conditionally enabling actions based on app state.