@gs-libs/bridge

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.