#Native App Bridge pre

This SDK registers a global bridge between your web app and the First Iraqi Bank's native mobile app, allowing you to communicate with the native app for a seamless experience to authenticate users, pay for products and services when we include your web app in our native app.

npm install @first-iraqi-bank/sdk@pre

#Usage

This SDK is designed to be used in the browser, it accesses the global window object to register the bridge and communicate with the native app.

To use this functionality, you need to import the registerFIBNativeBridge function and call it in your JavaScript code, as soon as your web app loads.

For example if you're using React Router, you need to import it and call it in entry.client.tsx file, or in Vite you need to import it in the main JS/TS module inside index.html which is called an entry file.

For other frameworks, please consult their documentation on how to run code when the app loads.

// other imports
import { registerFIBNativeBridge } from "@first-iraqi-bank/sdk/fib-native-bridge"

registerFIBNativeBridge()

This will ensure that the bridge is registered and ready to use when your code needs to communicate with the native app or the native bridge needs to send an event to your app.

If your web application could be deployed to be embedded as FIB App in App and also run independently in the browser, you might need to check whether the current environment supports FIB Native Bridge or not. For this purpose, you can use the window.FIBNativeBridge.isFIBBridgeAvailable, it'll return true if your app is embedded as FIB App in App, otherwise it'll return false.

if(window.FIBNativeBridge.isFIBBridgeAvailable()){
  // Your app is running inside FIB Native App, you can use the bridge
}else{
  // Your app is running in the browser, the bridge is not available
}

When you want to send an event to the native app, you can use the window.FIBNativeBridge.sendMessage object:

window.FIBNativeBridge.sendMessage({
  type: "AUTHENTICATE",
  body: { readableId }
})

The Native app can send events to your app as well, when you're expecting such events and want to handle them, you can use the window.FIBNativeBridge.addEventListener method:

const { readableId } = loaderData

window.FIBNativeBridge.addEventListener("AUTHENTICATED", async (event)=>{
  // do something when this event is received
})

#Error Handling

There are two types of errors you might want to watch out for:

1. When the SDK is used in an app the isn't integrated with the First Iraqi Bank's native app, in this case the SDK will throw an UnsupportedPlatformError error when you try to send a message to the native app. You can catch this error and handle it gracefully, for example by showing an error message to the user.

   try {
     window.FIBNativeBridge.sendMessage({
       type: "AUTHENTICATE",
       body: { readableId }
     })
   } catch (error) {
     if(error instanceof UnsupportedPlatformError){
       console.error("FIB Native App Bridge is not available, call the SDK only when its loaded inside FIB Native apps!", error)
     }
   }
   

2. When you try to send a message to the native app, but the message type is not one of the supported sendable message types, or the body of the message doesn't contain necessary information, the SDK will throw an InvalidMessageError error.

   try {
     window.FIBNativeBridge.sendMessage({
       type: "UNKNOWN_MESSAGE_TYPE", // this is not a valid message type
     })
   } catch (error) {
     if(error instanceof InvalidMessageError){
       console.error("Invalid message type or body", error)
     }
   }
   

   or

   try {
     window.FIBNativeBridge.sendMessage({
       type: "AUTHENTICATE",
       // No `readableId` provided, this is not a valid message type
     })
   } catch (error) {
     if(error instanceof InvalidMessageError){
       console.error("Invalid message type or body", error)
     }
   }
   

#Typical App Flow

Here is how a typical flow of your web app would look like when using the native app bridge:

#Web → Native App Communication

When you want to send a message from your web app to the native app, you can use the sendMessage method on the FIBNativeBridge object. This method takes an object with two properties:

• type: a string indicating the type of the message, for example "AUTHENTICATE" or "PAYMENT".
• body: an object containing the data you want to send to the native app, for example, it can contain a readableId or other relevant information.

#AUTHENTICATE event

You can send this message to the native bridge after you obtained the readableId from your backend, this will trigger the native app to authenticate the readableId with user logged in on the Native FIB App.

const normalizedReadableId = readableId.replaceAll("-", "")

window.FIBNativeBridge.sendMessage({
  type: "AUTHENTICATE",
  body: { readableId: normalizedReadableId }
})

When FIB Native app successfully authenticates the readableId, it will send an AUTHENTICATED event back to your web app. You should add an event listener for this event to handle the authentication result.

#PAYMENT event

You can use FIB's payment API to create a payment when a user tries to purchase a product or service in your web app. Then, you can send a PAYMENT message to the native app bridge, which will display the payment screen in the FIB app.

const { paymentId: transactionId, readableId } = paymentDetails

const normalizedReadableId = readableId.replaceAll("-", "")

window.FIBNativeBridge.sendMessage({
  type: "PAYMENT",
  body: { transactionId, readableId: normalizedReadableId }
})

When the payment is authorized and successfully completed, the native app will send a PAYMENT_SUCCESSFULLY_PAID event back to your web app, which you can handle by adding an event listener for this event.

Otherwise if the payment is canceled or failed, the native app will send a PAYMENT_FAILED event back to your web app, which you can also handle by adding an event listener for this event.

#EXIT event

If you want to close your web app and return to the native app, you can send an EXIT message to the native app bridge.

window.FIBNativeBridge.sendMessage({ type: "EXIT" })

This will close the web view and return to First Iraqi Bank's native mobile Home Screen, allowing the user to continue using the native app.

#Native App → Web Communication

FIBNativeBridge extends the EventTarget interface, which means you can listen to events sent from the native app to your web app.

Use the window.FIBNativeBridge.addEventListener to register events and window.FIBNativeBridge.removeEventListener to remove them.

#AUTHENTICATED event

When the native app successfully authenticates the readableId, it will send an AUTHENTICATED event back to your web app.

window.FIBNativeBridge.addEventListener("AUTHENTICATED", async (event) => {
  checkSSOStatus()
})

#AUTHENTICATION_FAILED event

When the native app fails to authenticate the readableId, it will send an AUTHENTICATION_FAILED event back to your web app.

Authenticating can fail for various reasons, and you should handle this event to provide a better user experience, for example, by showing a retry screen or an error message.

window.FIBNativeBridge.addEventListener("AUTHENTICATION_FAILED", async (event) => {
  // handle authentication failure
  setShowRetryScreen(true)
})

#PAYMENT_SUCCESSFULLY_PAID event

When the native app successfully completes the payment, it will send a PAYMENT_SUCCESSFULLY_PAID event back to your web app.

window.FIBNativeBridge.addEventListener("PAYMENT_SUCCESSFULLY_PAID", async (event) => {
  const { transactionId } = event.detail.body
  // handle the payment success, for example, show a success message or redirect to a success page
})

#PAYMENT_FAILED event

When the native app fails to complete the payment, it will send a PAYMENT_FAILED event back to your web app.

window.FIBNativeBridge.addEventListener("PAYMENT_FAILED", async (event) => {
  const { transactionId, reason } = event.detail.body
  // handle the payment failure, for example, show an error message or redirect to an error page
})