@getflip/bridge

Flip Bridge

The Flip Bridge handles communication between your embeddable apps and the Flip App or Flip Admin Console.

Contents

• Installation
• Usage
• Methods
  • Internationalization
  • Navigation
  • Theming
  • Dialogs
  • Modals
  • Toasts
• Events
• Error Handling
• Development

Installation

npm install --save @getflip/bridge
# or
yarn add @getflip/bridge

Usage

The 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
});

Methods

Internationalization

getAvailableLangs

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', …]

getLang

Get the current language of the host app.

Returns Promise<string>

Example

import { getLang } from "@getflip/bridge";

const currentLanguage = await getLang(); // e.g. 'en'

Navigation

navigate

Navigate to a specific route.

Param string

Returns Promise<boolean>

Example

import { navigate } from "@getflip/bridge";

await navigate("/my-app/settings");

Theming

getTheme

Get the current theme.

Returns

Promise<{
  activeTheme: "light" | "dark";
  preferredTheme: "light" | "dark" | undefined;
}>

Example

import { getTheme } from "@getflip/bridge";

const theme = await getTheme();

setTheme

Set the theme. Pass undefined to reset to the user's system theme.

Param "light" | "dark" | undefined

Returns Promise<"light" | "dark" | undefined>

Example

import { setTheme } from "@getflip/bridge";

const newTheme = await setTheme("dark");

Dialogs

createDialog

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();

openDialog

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" });

closeDialog

Closes a dialog.

Param

{
  id: string; // the dialog id
}

Returns Promise<boolean>

Example

import { closeDialog } from "@getflip/bridge";

await closeDialog({ id: "my-dialog" });

destroyDialog

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" });

Modals

createModal

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();

openModal

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" });

closeModal

Closes a modal.

Param

{
  id: string; // the modal id
}

Returns Promise<boolean>

Example

import { closeModal } from "@getflip/bridge";

await closeModal({ id: "my-modal" });

destroyModal

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" });

Toasts

showToast

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",
});

Events

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();

NAVIGATION_END

Fires when the application successfully navigated to a different route.

Event

{
  data: {
    route: string; // e.g. '/notifications'
  }
  type: BridgeEventType.NAVIGATION_END;
}

LANG_CHANGE

Fires when the user selected language changes.

Event

{
  data: string; // e.g. 'en'
  type: BridgeEventType.LANG_CHANGE;
}

PRIMARY_ACTION_CLICK

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;
}

SECONDARY_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;
}

THEME_CHANGE

Fires when the user theme changes.

Event

{
  data: {
    activeTheme: "light" | "dark";
    preferredTheme: "light" | "dark" | undefined;
  }
  type: BridgeEventType.THEME_CHANGE;
}

Error Handling

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'
}

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).

INVALID_REQUEST

The host app identified the request as invalid. This typically occurs when the provided parameters are invalid.

Development

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.