GS Bridge Services Package

An encapsulation of Bigtincan JSBridge API, that provides bridge services methods, also provides hooks

Get Started

Installation

yarn add @gs-libs/bridge

Quick Start

import {
  BridgeServices,
  QueryClient
  BridgeProvider,
  useQuery,
  useMutation
} from '@gs-libs/bridge';

const bridge = new BridgeServices();
const queryClient = new QueryClient();

// --- App.tsx ---
const App = () => {
  return (
    <BridgeProvider bridge={bridge} queryClient={queryClient}>
      <Home />
    </BridgeProvider>
  )
}

// --- Home.tsx ---
const Home = () => {
  const { data, status } = useQuery({
    action: 'getNewList',
    params: { entityName: 'story' }
  })

  const bridge = useBridge();

  const { mutate: openEntity } = useMutation(bridge.openEntity);

  const handleClick = (id: number) => () => openEntity({
    entityName: 'story',
    id,
  })

  return (
    <div>
      {status === 'success' && (
        data.map(story => (
          <div onClick={handleClick(story.id)}>
            {story.title}
          </div>
        ))
      )}
    </div>
  )
}

Docs

Bridge Services

This is the core part that implements all available APIs listed in the Bigtincan JavaScript Bridge API v3 Documentation, based on BTCA Client. So this BridgeServices is an encapsulation of the BTCA Client.

What is BTCA Client?

Due to the fact that our home screens are basically iframes, it has to talk to it's parent (The hub app) in order to perform certain actions e.g. opening a hub-native UI, proxying a request, etc.

So basically the BTCA Client does all the postMessage stuff to talk to the parent. And of course, it does more than just that.

But with the BridgeServices provided, we almost always don't need to know anything about the BTCA Client, so don't worry about it.

Incase you're interested, for more info, please visit BTCA Client, or its source code -> BTCA Client Source Code

BridgeServices Usage

Initialisation

There are two ways of initialising it.

The first way - initialising it with options

| param | desc | type | optional | default | | :-------------: | :------------------------------------------------------------------------------------------------------: | :-------: | :------: | :---------------: | | handle | BTCA Unique Identifier | string | yes | 'global-services' | | cache | simple cache for requests (too simple, only useful for debug) | boolean | yes | false | | log | logs actions to console | boolean | yes | false | | disableEvents | disables default events (see here) | boolean | yes | false |

import { BridgeServices } from '@gs-libs/bridge';

const bridge = new BridgeServices({
  handle: 'global-services',
  cache: false,
  log: false,
  disableEvents: false,
})

// The above is identical to
const bridge = new BridgeServices();

The second way - initialising it with BTCA Client, we almost always don't need to do this.

import { BTCAClient, BridgeServices } from '@gs-libs/bridge';

const client = new BTCAClient({
  handle: 'global-services',
  cache: false,
  log: false,
  disableEvents: false,
})

const bridge = new BridgeServices(client);

Consuming methods

The method names are identical to the action names that are listed in the Bigtincan JavaScript Bridge API v3 Documentation.

So too easy, just bridge.actionName -

const stories = bridge.getList<Story>({
  entityName: 'story',
  parentEntityName: 'channel',
  peid: 123456
})

BridgeServices Usage Suggestions

Using bridge is considered ineffiecient now as we also provides react hooks for it. So here's some cases that we think you should be using bridge.

1. You're out side of react component scope, e.g. you're in the store.
2. There's some complex logic that the react hooks provided cannot achieve, so you want to use the bridge to implement your own hooks or so.

The react hooks

This package also comes with hooks that we can easily use, please see here for documentation.