The Flip Bridge handles communication between your embeddable apps and the Flip App or Flip Admin Console.
Contents
npm install --save @getflip/bridge
# or
yarn add @getflip/bridgeThe library exposes a set of functions and listeners you can use to communicate with the Flip App and Flip Admin Console (host app for short).
Before using the provided functions, you have to call the initFlipBridge
function to set up the Flip Bridge.
import { initFlipBridge } from "@getflip/bridge";
initFlipBridge({
debug: true,
hostAppOrigin: "http://localhost:4200", // has to be the origin of the targeted host app
});Get all available languages of the host app.
Returns Promise<string[]>
Example
import { getAvailableLangs } from "@getflip/bridge";
const availableLanguages = await getAvailableLangs(); // e.g. ['de', 'en', 'fr', …]Get the current language of the host app.
Returns Promise<string>
Example
import { getLang } from "@getflip/bridge";
const currentLanguage = await getLang(); // e.g. 'en'Navigate to a specific route.
Param string
Returns Promise<boolean>
Example
import { navigate } from "@getflip/bridge";
await navigate("/my-app/settings");Get the current theme.
Returns
Promise<{
activeTheme: "light" | "dark";
preferredTheme: "light" | "dark" | undefined;
}>Example
import { getTheme } from "@getflip/bridge";
const theme = await getTheme();Creates a modal dialog rendered by the host app.
Param
{
hideLabel?: boolean;
id: string;
intent?: 'primary' | 'critical';
label: string;
text: string;
primaryAction?: {
label: string;
};
secondaryAction?: {
label: string;
};
}Returns
Promise<{
id: string;
open: () => Promise<boolean>;
close: () => Promise<boolean>;
destroy: () => Promise<boolean>;
}>Example
import { createDialog } from "@getflip/bridge";
const dialog = await createDialog({
id: "my-dialog",
label: "My Dialog",
text: "Lorem ipsum",
primaryAction: {
label: "Close",
},
});
await dialog.open();Opens a dialog.
Param
{
id: string; // the dialog id
}Returns Promise<boolean>
Example
import { createDialog, openDialog } from "@getflip/bridge";
await createDialog({
id: "my-dialog",
label: "My Dialog",
text: "Lorem ipsum",
});
await openDialog({ id: "my-dialog" });Closes a dialog.
Param
{
id: string; // the dialog id
}Returns Promise<boolean>
Example
import { closeDialog } from "@getflip/bridge";
await closeDialog({ id: "my-dialog" });Destroys a dialog, removing it from the DOM.
Param
{
id: string; // the dialog id
}Returns Promise<boolean>
Example
import { destroyDialog } from "@getflip/bridge";
await destroyDialog({ id: "my-dialog" });Creates a modal rendered by the host app. The modal will show the passed URL as an iFrame.
Param
{
id: string;
label: string;
primaryAction?: {
label: string;
};
secondaryAction?: {
label: string;
};
url: string;
}Returns
Promise<{
id: string;
open: () => Promise<boolean>;
close: () => Promise<boolean>;
destroy: () => Promise<boolean>;
}>Example
import { createModal } from "@getflip/bridge";
const modal = await createModal({
id: "my-moadl",
label: "My Modal",
primaryAction: {
label: "Close",
},
url: "https://google.com",
});
await modal.open();Opens a modal.
Param
{
id: string; // the modal id
}Returns Promise<boolean>
Example
import { createModal, openModal } from "@getflip/bridge";
await createModal({
id: "my-modal",
label: "My Modal",
url: "https://google.com",
});
await openModal({ id: "my-modal" });Closes a modal.
Param
{
id: string; // the modal id
}Returns Promise<boolean>
Example
import { closeModal } from "@getflip/bridge";
await closeModal({ id: "my-modal" });Destroys a modal, removing it from the DOM.
Param
{
id: string; // the modal id
}Returns Promise<boolean>
Example
import { destroyModal } from "@getflip/bridge";
await destroyModal({ id: "my-modal" });Shows a toast by the host app.
Param
{
text: string;
duration?: number;
icon?: string;
intent?: SwirlToastIntent;
}Returns Promise<boolean>
Example
import { showToast } from "@getflip/bridge";
await showToast({
text: "My toast",
duration: 5000,
icon: "icon",
intent: "success",
});Use the subscribe functions to subscribe to events.
import { subscribe, BridgeEventType } from "@getflip/bridge";
const unsubscribe = await subscribe(BridgeEventType.THEME_CHANGE, (event) => {
console.log(event.data);
});
// …
await unsubscribe();Fires when the application successfully navigated to a different route.
Event
{
data: {
route: string; // e.g. '/notifications'
}
type: BridgeEventType.NAVIGATION_END;
}Fires when the user selected language changes.
Event
{
data: string; // e.g. 'en'
type: BridgeEventType.LANG_CHANGE;
}Fires when the primary action button of a dialog or modal is clicked.
Event
{
data: {
parentId: string; // id of the action's dialog or modal
}
type: BridgeEventType.PRIMARY_ACTION_CLICK;
}Fires when the secondary action button of a dialog or modal is clicked.
Event
{
data: {
parentId: string; // id of the action's dialog or modal
}
type: BridgeEventType.SECONDARY_ACTION_CLICK;
}Fires when the user theme changes.
Event
{
data: {
activeTheme: "light" | "dark";
preferredTheme: "light" | "dark" | undefined;
}
type: BridgeEventType.THEME_CHANGE;
}All provided functions return promises that throw an error if the execution failed. The errors have the following format.
{
code: BridgeErrorCode; // e.g. 'FORBIDDEN_ORIGIN'
}Thrown when the origin of the requesting app is not allowed by the host app.
Please check if your app is correctly registered in the Flip Partner Dashboard
and the hostAppOrigin option is set (see Usage).
The host app identified the request as invalid. This typically occurs when the provided parameters are invalid.
Start the compiler in watch mode for local development:
yarn dev
Production builds and releases are managed via our Github workflows. Make sure
to create a Changeset using yarn changeset if you want to trigger a new
release.