@govflanders/mbp-embed-sdk

Mijn Burgerprofiel Embed SDK

@govflanders/mbp-embed-sdk - a javascript library designed to integrate designated pages into Mijn Burgerprofiel.

ℹ️ TIP:
The preferred way to read this is on our documentation site.
That way, you are working with the most recent version, and you get additional information (like generated type definitions).

What is this?

Digitaal Vlaanderen provides and hosts 'Mijn Burgerprofiel' applications, both for the Flemish government and local municipalities. Citizens either download a mobile app or log in to burgerprofiel.be.

There are a lot of external data sources and functionality that would be useful to include in those applications. Historically, this meant either linking to external pages, or custom development to build API's and integrate that external content. A more flexible approach would be to embed externally hosted content directly by using either iframes (for web aplications), or webviews (for native apps).

To enable this efficiently and securely, @govflanders/mbp-embed-sdk was created. It defines an official interface to embed your content in Mijn Burgerprofiel applications (and interact with them).

Main Components

• Host Environment: The application that will integrate your content, which could be burgerprofiel.be (via iframes) or a mobile app (via webviews).
• Embedded Page: The content you wish to embed.
• MbpEmbedClient: The client interface/library responsible for managing communication between the embedded page and the host.

Diagram: connection/communication flow

┌──────────┐                  ┌───────────────┐                ┌───────────────┐
│   Host   │                  │ Embedded Page │                │ mbp-embed-sdk │
└────┬─────┘                  └───────┬───────┘                └───────┬───────┘
     ├────┐                           │                                │
     │    │ Listens for connections   │                                │
     │    │  [status = loading]       │                                │
     │◄───┘                           │                                │
     │       Load page                │    createMbpEmbedClient(id)    │
     ├───────────────────────────────►├───────────────────────────────►│
     │                                │◄───────────────────────────────┤
     │                                │                                │
     │                                │            connect()           │
     │                                ├───────────────────────────────►│
     │      <connection request>      │                                │
     │◄----------------------------------------------------------------┤
     │----┐                           │                                │
     │    │ Validate connection       │                                │
     │◄---┘                           │     <connection response>      │
     │----------------------------------------------------------------►│
     │                                │                           ┌────┤
     │                                │       Validate connection │    │
     │                                │                           └───►│
     │                                │      success | exception       │
     │                                │◄───────────────────────────────┤
     │                                │                                │
     │                                │    setStatusLoading(false)     │
     │                                ├───────────────────────────────►│
     │      <status request>          │                                │
     │◄----------------------------------------------------------------┤
     ├────┐                           │                                │
     │    │ Show embedded page        │                                │
     │    │  [status = ready]         │                                │
     │◄───┘                           │        <status updated>        │
     │----------------------------------------------------------------►│
     │                                │◄───────────────────────────────┤
     │                                │                                │

Setup

Onboarding

To get started, you need to go through a short onboarding process with Digitaal Vlaanderen.
Contact Mijn Burgerprofiel aansluitingen with the following details:

• The URL (or URLs) of the page(s) you want to embed
• Where/how you would like them embedded (City app, Burgerprofiel app, burgerprofiel.be)

Once the integration has been approved, you will receive a client ID to use with the SDK.

Installation

You can install the library from npm (it's publicly available):

npm install @govflanders/mbp-embed-sdk

Client creation and connection

Next, import the library and create a client in your project:

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

const mbpClient = createMbpEmbedClient('your-client-id', {
  allowedHosts: [
    'https://*.burgerprofiel.be/*',
    'https://admin.vlaanderen.be/*',
  ],
});

Then, connect the client to the host environment (this is an asynchronous operation, so either use await or .then()):

try {
  await mbpClient.connect();
  console.log('Connection successful!');
} catch (e) {
  console.error('Failed to connect:', e);
}

Testing

When using the library in a standalone page, the client will time out after a while because there is no host environment to connect to.

To check if everything works correctly, you can use our embed preview tool.

Usage

ℹ️ NOTE:
For detailed usage, it's best to consult the official API documentation.
It is generated automatically based on the most recent version of the library.
Examples below are simplified and may not cover all available functionality.

UI Management

// Set the title
mbpClient.ui.setTitle('Mijn loket');

// Set loading status
mbpClient.ui.setStatusLoading(true);
setTimeout(() => {
  mbpClient.ui.setStatusLoading(false);
}, 1000);

// Set error status
mbpClient.ui.setStatusError({
  title: 'Oops',
  message: 'We are experiencing some problems, try again later!',
});

And more, see API documentation.

Navigation

// Make sure user confirms before leaving embed page
mbpClient.navigation.enableExitConfirmation({
  title: 'Are you sure?',
  message: 'There are unsaved changes - you will lose them!',
});

// Navigate back
mbpClient.navigation.back();

// Open a new embed
mbpClient.navigation.openNewEmbed('https://my-embed-url.local/new-page');

// Open an external link
mbpClient.navigation.openExternal('https://www.vlaanderen.be');

And more, see API documentation.

Retrieving context/data from host

// Get tenant information
const tenant = await mbpClient.context.getTenant();
console.log(tenant.branding.primaryColor); // '#0070c0', for example

// In cases where user was directed from a specific product/context, you can retrieve that information.
const ipdcProduct = await mbpClient.context.getIpdcProduct();
console.log(ipdcProduct.title); // 'Jobbonus voor werknemers en ambtenaren', for example

And more, see API documentation.

Contributing

This library is managed and developed internally by Digitaal Vlaanderen. For technical questions, feedback or suggestions: please contact Mijn Burgerprofiel App team.

Internal developers can consult CONTRIBUTING.md for details on getting things set up.