HandlersManager - Documentation

Handlers which take over behavior across all SDK features.

Methods

createRouterNavigationHandler(options) → {NavigationHandler}

Creates a navigation handler for use with setNavigationHandler which routes same-origin URLs through your client-side router. URLs on other origins (or outside basePath) are left to the SDK's default handling.

The handler waits for navigate to finish. If it throws or rejects, the SDK opens the URL itself instead, and if the router rejected late, e.g. after an async navigation guard, the popup blocker can block it.

This is for routers which use the URL's path (/settings). Hash-based routers (/#/settings) need their own handler, see the hash-based router example on setNavigationHandler.

Parameters:

Name	Type	Description
`options`	`RouterNavigationHandlerOptions`	the router options

Returns:

Type:: NavigationHandler

Examples

// React Router (data router)
const router = createBrowserRouter(routes) // from react-router
sdk.handlers.setNavigationHandler(
  sdk.handlers.createRouterNavigationHandler({
    navigate: (path) => router.navigate(path),
  })
)

// Next.js, with `basePath: '/shop'` in next.config.js
const router = useRouter() // from next/navigation
useEffect(() => {
  sdk.handlers.setNavigationHandler(
    sdk.handlers.createRouterNavigationHandler({
      navigate: (path) => router.push(path),
      basePath: '/shop',
    })
  )
  // the router only lives as long as the component
  return () => sdk.handlers.setNavigationHandler(undefined)
}, [router])

setNavigationHandler(handler) → {void}

Sets a navigation handler which can take over navigation to URLs opened by the SDK, e.g. to route them through your single-page app's client-side router rather than loading a new page.

The handler receives URLs the SDK opens itself, such as a Scene's URL actions. Markdown links within a Scene's text, and URLs opened from push notifications, aren't passed to it.

URL triggers are currently only evaluated when the SDK starts, so unlike loading a new page, a navigation your router handles won't show Scenes triggered by the URL it navigates to.

Return true from openUrl once you have handled the navigation; return false to let the SDK handle it as it normally would. Pass undefined to remove the handler.

Parameters:

Name	Type	Description
`handler`	`NavigationHandler` \| `undefined`	the handler, or `undefined` to remove it

Returns:

Type:: void

Examples

sdk.handlers.setNavigationHandler({
  openUrl: (url) => {
    const parsed = new URL(url, window.location.href)
    if (parsed.origin !== window.location.origin) return false
    myRouter.push(parsed.pathname + parsed.search + parsed.hash)
    return true
  },
})

// hash-based router, e.g. React Router's `HashRouter` or Vue Router's
// `createWebHashHistory`
sdk.handlers.setNavigationHandler({
  openUrl: (url) => {
    const parsed = new URL(url, window.location.href)
    if (parsed.origin !== window.location.origin) return false
    if (parsed.pathname !== window.location.pathname) return false
    myRouter.push(parsed.hash.slice(1) || '/')
    return true
  },
})