Navigation

Connect the client with connect() before using navigation methods:

await mbpClient.connect();

All navigation methods return a promise. Await the promise when later work depends on the navigation request reaching the host application.

Prefer a new embed for a new screen

Use openNewEmbed() when an action opens a screen that needs its own back behaviour. The host opens the URL as a new embed and adds it to its native screen stack:

await mbpClient.navigation.openNewEmbed(
  'https://example.be/appointments/new',
);

This is the preferred way to move between screens in an embed. The host handles native back navigation and gives the user a screen transition that matches the rest of the app.

Do not open a new embed for every local change. Tabs, expandable sections, filters, and similar controls can stay within the current page when they do not need a separate navigation entry or back behaviour.

Using a nested embed can take extra work in an existing application. These are solvable implementation tasks:

  • A screen may not yet have its own URL. Add a route when the screen needs its own host navigation entry.
  • An earlier webview may need to reflect data changed on a deeper screen. Refresh its shared state when it becomes visible again, for example with the browser visibilitychange event.
  • A server-rendered screen may need performance work before it can load quickly enough during navigation.

Use a nested embed when the screen needs its own navigation entry. Keep in-page navigation for controls that belong within the current screen.

Handle in-page back navigation

When the current webview owns its own navigation history, register onBackNavigation() to handle the host's native back action. This is a fallback for in-page navigation, not a replacement for openNewEmbed().

For example, an embed may keep its own routes inside one webview. Its router records each route the user opens. When the host triggers back navigation, the callback checks that route state:

  1. If the current route has a parent route, the embed router returns to it and the callback returns false.
  2. If the current route is the embed root, the callback returns true so the host returns to its previous screen.
const removeBackNavigationHandler = mbpClient.navigation.onBackNavigation(() => {
  if (router.canGoBack()) {
    router.back();
    return false;
  }

  return true;
});

// Remove the handler when this page no longer owns the decision.
removeBackNavigationHandler();

Return false after handling the back action in the webview. Return true when the host should pop its own screen stack. The callback must return synchronously, and the host waits at most 100 ms. Do not show an asynchronous dialog from this callback.

A client has one back-navigation callback. Registering another one replaces the previous callback. If no callback is registered, the SDK allows the host navigation.

Go back from an action

Use back() when an action in the embed should return the user to the previous host screen:

await mbpClient.navigation.back();

Ask for confirmation before leaving

Use exit confirmation for a form or another stateful screen. The host shows the confirmation UI when the user tries to leave:

await mbpClient.navigation.enableExitConfirmation({
  title: 'Wijzigingen annuleren?',
  message: 'Uw niet-opgeslagen wijzigingen gaan verloren.',
  confirm: 'Annuleren',
  ignore: 'Verder bewerken',
});

Remove it as soon as the user can leave without losing work:

await mbpClient.navigation.disableExitConfirmation();

disableExitConfirmation() changes the embed status back to ready. Do not use it as general component cleanup. Enable and disable it when the state that needs protection changes.

Open an external page

Use openExternal() for a link that should leave the host's embed flow:

await mbpClient.navigation.openExternal('https://www.vlaanderen.be');

The host decides whether it can open a requested URL. Handle a rejected navigation request as a normal technical error in the embed.

Open a host route

Use openHostRoute() to open a screen supplied by Mijn Burgerprofiel. Import routes from the SDK instead of writing route strings:

import { AppHostRoutes } from '@govflanders/mbp-embed-sdk';

await mbpClient.navigation.openHostRoute(AppHostRoutes.Notificaties);

Choose the route list for the host where the embed runs. See Client.AppHostRoutes for routes available in the mobile app and Client.WebHostRoutes for routes available in the web host. Those references are generated from the current SDK route definitions.

Use only routes supported by the current host. The TypeScript route constants help catch invalid route names, but they do not make an app-only route available in the web host.

API reference

See Client.MbpEmbedClientNavigation for method signatures. Individual methods have stable links, such as openNewEmbed() and onBackNavigation().

Settings

On This Page

Navigation