Navigation interception

All sites inherit the optional ui.actions.navigate callback. It receives a serializable request before SDK navigation. It works in both web and app modes.

Return handled when the host takes responsibility (including intentionally cancelling). Return continue to execute the SDK behavior. Promises are supported; the SDK waits. Only continue proceeds: exceptions, rejected promises and invalid results cancel the request and log an error. With no callback, existing behavior is preserved.

MindtrainingPlatform.init('mindtraining', {
  ui: {
    actions: {
      navigate: function (request) {
        if (request.destination === 'statistics') {
          nativeBridge.openStatistics(request)
          return 'handled'
        }
        return 'continue'
      },
    },
  },
})

Contract

type NavigationDecision = 'handled' | 'continue'

type NavigationRequest = {
  kind: 'route' | 'surface' | 'external'
  action: 'push' | 'replace' | 'back' | 'forward' | 'go' | 'open' | 'close'
  destination: string
  path?: string
  url?: string
  fromUrl: string
  surface?: string
  presentation?: string
  gameConfigurationId?: string
  gameType?: string
  variant?: string
  date?: string
  target?: string
}

An internal route uses the active history adapter to produce url, including basepath and default/hash/query routing. path is the SDK history path. A surface without a route has no destination URL. In-app history back uses destination: history and omits url/path: browsers do not expose the previous URL. fromUrl is the current absolute URL.

destination: home, gameEntry, game, archive, statistics, route, history, external; surface: homeArchive, gameArchive, statistics, statisticsOverview, howToPlay, gameSettings, gameCompletion, achievementGameDetail, achievementUnlock.

Coverage and boundaries

SDK route navigation, in-app back buttons, help, settings, archive/statistics panels, completion panels and achievement detail actions are intercepted. URLs opened by external-link buttons and quiz references also pass through the callback. Ordinary native links within the SDK page boundary participate after access and link handlers.

Native browser Back/Forward, reload, direct URL entry, downloads, fragment-only anchors and modified/middle clicks remain browser-owned. Login, registration, subscription, sharing APIs, gameplay controls, confirmation dialogs and automatic achievement notifications retain their existing contracts. Closing an achievement notification is a surface action.

The callback takes precedence over legacy internal openUrl notifications, preventing duplicate host navigation. External-link and quiz fallbacks still use openUrl when the decision is continue. Access checks and paywall callbacks retain their existing order; interception never grants access.

Latest pending route/surface decisions are discarded when superseded. There is no implicit timeout or automatic continuation. A compound flow may contain several explicit intents (for example close settings, then open help). Internal virtual-page history bookkeeping and browser restoration do not dispatch a second request.

For external new-tab navigation, return synchronously if the browser must open the tab; an asynchronous continuation can lose browser user activation. A native bridge can handle the request itself. Do not call an SDK navigation API recursively from this callback; return continue to let the SDK proceed.

Runtime updates

MindtrainingPlatform.updateConfig({ ui: { actions: { navigate: () => 'continue' } } })
MindtrainingPlatform.updateConfig({ ui: { actions: { navigate: undefined } } })