@tef-novum/webview-bridge

JavaScript library to access to native functionality. Requires a webview with a postMessage bridge.

Library size ~1.2 Kb (min + gzip)

AMD, UMD, IIFE, ES Module builds available (see package dist folder). Open an issue if you need a different build.

Usage

NPM

We recommend to manage your dependencies using npm or yarn and use a bundler like webpack or parcel. Once configured, you can use ES imports.

Install using npm:

npm i @tef-novum/webview-bridge

Install using yarn:

yarn add @tef-novum/webview-bridge

Import required function and use it:

import {setWebViewTitle} from '@tef-novum/webview-bridge';

setWebViewTitle('Hello, world');

CDN

Alternatively, you can import the library directly from a CDN:

<script src="https://unpkg.com/@tef-novum/webview-bridge/dist/webview-bridge-iife.min.js"></script>

<script>
    webviewBridge.setWebViewTitle('Hello, world');
</script>

API

• isWebViewBridgeAvailable
• requestContact
• createCalendarEvent
• share
• updateNavigationBar
• nativeConfirm
• nativeAlert
• nativeMessage
• logEvent
• setScreenName
• reportStatus
• checkPermissionStatus
• internalNavigation
• dismiss
• fetchContactsByPhone

isWebViewBridgeAvailable

Returns true if WebView Bridge is available. Use this function to implement fallbacks in case the bridge is not available.

isWebViewBridgeAvailable: () => boolean;

Example

import {isWebViewBridgeAvailable, nativeAlert} from '@tef-novum/webview-bridge';

if (isWebViewBridgeAvailable()) {
    nativeAlert('Hello'); // use bridge
} else {
    myCustomAlert('Hello'); // use alternative implementation
}

You may want to detect if the page is displayed inside a regular browser or an Android or iOS WebView.

import {isWebViewBridgeAvailable} from '@tef-novum/webview-bridge';

/** Returns true if application is running inside a Novum App WebView */
const isWebView = () => isWebViewBridgeAvailable();

/** Returns true if application is running inside a Novum App WebView running on Android */
const isAndroidWebView = () =>
    isWebViewBridgeAvailable() && navigator.userAgent.includes('Android');

/** Returns true if application is running inside a Novum App WebView running on iOS */
const isIOSWebView = () =>
    isWebViewBridgeAvailable() && !navigator.userAgent.includes('Android');

requestContact

Show native picker UI in order to let the user select a contact.

• Android only: picker UI elements can be filtered by available phones (default) or emails. filter property is ignored by iOS devices

requestContact: ({filter?: 'phone' | 'email'}) => Promise<{
    name?: string;
    email?: string;
    phoneNumber?: string;
    address?: {
        street?: string;
        city?: string;
        country?: string;
        postalCode?: string;
    };
}>;

All fields in response object are optional

Example

import {requestContact} from '@tef-novum/webview-bridge';

requestContact({filter: 'phone'}).then((contact) => {
    console.log(contact);
}).catch(err => {
    console.error(err);
};

createCalendarEvent

Inserts an event in calendar

createCalendarEvent: ({
    beginTime: number,
    endTime: number,
    title: string
}) => Promise<void>;

beginTime and endTime are timestamps with millisecond precision

Example

import {createCalendarEvent} from '@tef-novum/webview-bridge';

createCalendarEvent({
    beginTime: new Date(2019, 10, 06).getTime(),
    endTime: new Date(2019, 10, 07).getTime(),
    title: "Peter's birthday",
}).then(() => {
    console.log('event created');
}).catch(err => {
    console.error(err);
};

share

Invokes the native sharing mechanism of the device.

• Available for app versions 10.7 and higher
• Returning promise will be rejected if not supported (app versions lower than 10.7)

type ShareOptions =
    | {
          text: string;
      }
    | {
          url: string;
          fileName: string;
          text?: string;
      };

share: (options: ShareOptions) => Promise<void>;

• If no url is present, text is used as item to share
• If url param is present, it contains the URL to the shared file
• fileName param is mandatory if url is set
• If url and text are set, text is used as Intent BODY (if platform allows it)

Example

import {share} from '@tef-novum/webview-bridge';

// sharing a text string
share({text: 'Hello, world!'});

// sharing a file
share({url: 'https://path/to/file', fileName: 'lolcats.png'});

updateNavigationBar

Customize WebView NavigationBar properties

• You can set one or more properties in a single call
• Available for app versions 10.7 and higher
• Returning promise will be rejected if not supported (app versions lower than 10.7)

updateNavigationBar = ({
    title?: string;
    showBackButton?: boolean;
    showReloadButton?: boolean;
    showProfileButton?: boolean;
    backgroundColor?: string;
}) => Promise<void>

• title: updates NavigationBar title
• showBackButton: shows or hides NavigationBar Back button
• showReloadButton: shows or hides NavigationBar Reload button
• showProfileButton: shows or hides NavigationBar Profile button (which navigates to user profile). Only available in native app versions >= 11.7
• backgroundColor: change NavigationBar background color, use a hex color string (for example: '#FF128A')

Examples

import {updateNavigationBar} from '@tef-novum/webview-bridge';

// updates WebView NavigationBar title
updateNavigationBar({title: 'Hello, World!'});

// full featured example
updateNavigationBar({
    title: 'Hello',
    showBackButton: true,
    showReloadButton: false,
    showProfileButton: false,
    backgroundColor: '#FF0000', // red
});

isABTestingAvailable

Returns true if A/B testing named with the key is available.

• Available for app versions 10.8 and higher
• Returning promise will be rejected if not supported (app versions lower than 10.8)

isABTestingAvailable: (key: string) => Promise<boolean>;

Example

import {isABTestingAvailable} from '@tef-novum/webview-bridge';

isABTestingAvailable('key').then((isAvailable) => {
    console.log(isAvailable);
}).catch(err => {
    console.error(err);
};

nativeConfirm

Show a native confirm dialog.

If the bridge is not present (eg. showing the page in browser), fallbacks to a browser confirm.

nativeConfirm: ({
    message: string;
    title?: string;
    acceptText: string;
    cancelText: string;
}) => Promise<boolean>;

Example

import {nativeConfirm} from '@tef-novum/webview-bridge';

nativeConfirm({
    title: 'Confirm',
    message: 'Send message?',
    acceptText: 'Yes',
    cancelText: 'No',
}).then(res => {
    if (res) {
        console.log('message sent');
    }
});

nativeAlert

Show a native alert dialog.

If the bridge is not present (eg. showing the page in browser), fallbacks to a browser alert.

nativeAlert: ({
    message: string;
    title?: string;
    buttonText: string;
}) => Promise<void>;

Example

import {nativeAlert} from '@tef-novum/webview-bridge';

nativeAlert({
    message: 'Purchase completed!',
    title: 'Ok!',
}).then(res => {
    console.log('alert closed');
});

nativeMessage

Show a native message dialog. Use it to display feedback messages.

If the bridge is not present (eg. showing the page in browser), fallbacks to a browser alert.

• buttonText property is ignored in iOS.

nativeMessage: ({
        message: string;
        duration?: number; // milliseconds
        buttonText?: string; // Android only
        type?: 'INFORMATIVE' | 'CRITICAL' | 'SUCCESS';
}) => Promise<void>;

Example

Show a native "snackbar" with a configurable duration and optional close button

import {nativeMessage} from '@tef-novum/webview-bridge';

nativeMessage({
    message: 'Operation finished!',
    buttonText: 'Ok',
    duration: 5000, // 5 seconds
}).then(res => {
    console.log('alert closed');
});

logEvent

Log an event to firebase

logEvent: ({
    category: string; // Typically the object that was interacted with (e.g. 'Video')
    action: string; // The type of interaction (e.g. 'play')
    label?: string; // Useful for categorizing events (e.g. 'Fall Campaign')
    value?: number; // A numeric value associated with the event (e.g. 43)
}) => Promise<void>;

Example

import {logEvent} from '@tef-novum/webview-bridge';

logEvent({
    category: 'topup-flow',
    action: 'topup',
}).then(() => {
    console.log('event logged');
});

setScreenName

Log the current screen name (or page name) to firebase

setScreenName: (screenName: string) => Promise<void>;

Example

import {setScreenName} from '@tef-novum/webview-bridge';

setScreenName('Topup Flow').then(() => {
    console.log('screen name logged');
});

reportStatus

Report a given feature status

• Available for app versions 11.2 and higher

reportStatus: ({feature: 'ACCOUNT', status: 'CRITICAL' | 'GOOD' | 'BAD', reason: string}) => Promise<void>;

Example

import {reportStatus} from '@tef-novum/webview-bridge';

reportStatus({feature: 'ACCOUNT', status: 'GOOD', reason: 'whatever'});

onNativeEvent

Listens to native app events

• Available for app versions 11.3 and higher

type NativeEventHandler = ({ event }: {event: string}) => {action: 'default'};

onNativeEvent: (handler: NativeEventHandler) => () => void;

Example

onNativeEvent(({event}) => {
    if (event === 'tappedNavigationBarBackButton') {
        // do something
    }
    return {action: 'default'};
});

Available events

• tappedNavigationBarBackButton: fired when the user taps on the back button of the native Navigation Bar. Allowed response actions: default

checkPermissionStatus

Returns true if the app has the specific notifications permissions. You have to pass feature and required params for this request.

• Available for app versions 11.4 and higher

Avalaible features:

• notifications

checkPermissionStatus: (feature: string, params?: {[key: string]: string},) => Promise<boolean>;

Example

import {checkPermissionStatus} from '@tef-novum/webview-bridge';

checkPermissionStatus('notifications', {channelId: 'default'}).then(
    hasPermissions => {
        console.log(hasPermissions);
    },
);

internalNavigation

Init an internal and native navigation to a device specific feature

• Available for app versions 11.4 and higher

Avalaible features:

• notification-settings

internalNavigation: (feature: string) => Promise<void>;

Example

import {internalNavigation} from '@tef-novum/webview-bridge';

internalNavigation('notification-settings');

dismiss

Dismiss the current webview and optionally navigate to another url

• Available for app versions 11.5 and higher

dismiss: (onCompletionUrl?: string) => Promise<void>;

Example

import {dismiss} from '@tef-novum/webview-bridge';

dismiss('http://example.com');

requestVibration

Requests the phone to vibrate. Options are 'error' or 'success'.

import {requestVibration} from '@tef-novum/webview-bridge';

requestVibration('error');

fetchContactsByPhone

Returns contacts info given an array of phone numbers.

fetchContactsByPhone: (phoneNumbers: Array<string>) => Promise<Array<{
    phoneNumber: string;
    firstName?: string;
    middleName?: string;
    lastName?: string;
    encodedAvatar?: string;
}>>;

Error handling

If an error occurs, promise will be rejected with an error object:

{code: number, description: string}

License

This project is licensed under the terms of the MIT license. See the LICENSE file.