Synapse: Web Package

Making web and native communication much more simpler and effective!

Table of Contents

• Installation
• Integration
• Web Bridge
• Usage
• Platform Utility

Installation

Synapse web package can be installed easily via NPM (Node Package Manager) -

npm i @tata1mg/synapse

Note- Currently it has support for Node.js based environments.

Integration

Synapse installation can be done in two easy steps.

Firstly, we need to add platform identity information at the server side. (currently has support for nodejs)

const { identity } = require("@tata1mg/synapse/server")

identity.set(req, res, {
    platform: "android", // current environment of the web app (android/ios/web)
    version: "16.1.0", // current version of the native app (major.minor.patch)
    support: {
        // versions from which synapse will be initalised
        android: "16.0.0",
        ios: "15.0.0",
    },
    cookie: {} // cookie properties, if any
    devMode: true/false, // configures synapse in development mode
})

Note- synapse adds certain cookies within the response object namely - synapse:init, synapse:legacy, synapse:config, which needs to be whitelisted for platform identification.

In the next step, we need to add information about the event bridge path required for callbacks initialization at the client side.

const { initialize } = require("@tata1mg/synapse")

initialize({
    nativeBridge: {
        bridgeName: "AppCallbacks",
        androidBridgePath: "window.AppCallbacks",
        iosBridgePath: "window.webkit.messageHandlers",
    },
    webBridge: {
        bridgeName: "WebCallbacks",
    },
})

Web Bridge

Synapse package comes shipped with some generic interfaces out of the box, namely -

1. navigator
2. storage
3. onMessage etc.

In addtion to these, we can add and modify new and existing web interfaces too.

const { webBridge } = require("@tata1mg/synapse")

webBridge.register(
    {
        interaction: {
            showToastMessage: (data = {}) => {
                if (data && data.message) {
                    document.getElementById("toast").innerText = data.message
                } else {
                    document.getElementById("toast").innerText = "onMessage Test Success!"
                }
            },
            ...
        },
        onMessage: {
            ...
        },
        ...
    }, 
    true/false // overrides pre-existing interfaces, if any
)

Usage

Synapse also ships required tools for handling AppCallbacks and WebView identification utilities.

AppCallback Handlers

The callback handler package consists of basic function wrappers which can be used for handling native callbacks (AppCallbacks).

Has support for legacy handler which can be used for handling fallback callbacks based on version support headers.

const { callbackHandler, legacyHandler } = require("@tata1mg/synapse/handler")

callbackHandler(callback [, support])

callbackHandler is a function wrapper which can be used for calling native callbacks in a WebView environment.

callbackHandler(() => window.synapse.AppCallbacks.<interfaceName>.<methodName>(arguments))

Has additional feature for support version overrides, which can be used to add future callbacks based on their app support versions.

callbackHandler(() => window.synapse.AppCallbacks.<interfaceName>.<methodName>(arguments), { android: "16.1.0", ios: "15.1.0" })

legacyHandler(callbackObject [, support])

legacyHandler is a function wrapper which can be used in case you want to have support for lower support version AppCallbacks.

legacyHandler({
    current: () => window.synapse.AppCallbacks.<interfaceName>.<methodName>(arguments),
    legacy: () => legacyFunctionHandler(arguments)
})

Has additional feature for support version overrides, which can be used to override legacy callback handling.

legacyHandler({
    current: () => window.synapse.AppCallbacks.<interfaceName>.<methodName>(arguments),
    legacy: () => legacyFunctionHandler(arguments)
}, 
{ android: "16.1.0", ios: "15.1.0" })

Platform Utility

The platform utility package consists of various tools and utilities required while working with WebView environment.

const { isSSR, isWebView, ...utils } = require("@tata1mg/synapse/utils")

Tool	Description	Returns
isSSR()	Checks if the rendering is server side or not	true/false
isWebView([req][, res])	Performs WebView identification, supports both SSR and CSR flows	true/false
getPlatform()	Gets the platform value for the current environment	android/ios/web
checkVersionSupport(support)	Checks support for feature based on current and support version object passed	true/false
isLegacyWebView(req [, res])	Determines if the current WebView flow is legacy based or not	true/false
injectCallback(interfaceName, methodName [, args][, nonce])	Used for injecting native callbacks in raw HTML docs and scripts	stringified HTML script