@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
• getAppMetadata
• setCustomerHash
• getDiskSpaceInfo
• getEsimInfo
• setTrackingProperty

isWebViewBridgeAvailable

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

isWebViewBridgeAvailable: () => boolean;

Inside an iframe

By default, the bridge will be disabled inside an iframe. If you want to enable it, add a data-enable-webview-bridge attribute to the host iframe element.

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;
    expandedTitle?: string;
    showBackButton?: boolean;
    showReloadButton?: boolean;
    showProfileButton?: boolean;
    backgroundColor?: string;
}) => Promise<void>

• title: updates NavigationBar title
• expandedTitle: updates NavigationBar expandedTitle. If the value is an empty string, the expanded navigation bar will not be shown. Only available in native app versions >= 11.8
• showBackButton: shows or hides left icon in NavigationBar. Depending on the navigation mode, could be a close (X) or back (<) icon
• 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',
    expandedTitle: 'Hello, World!',
    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;
}>>;

getAppMetadata

Check if an app is installed in the phone

• Available for app versions 11.8 and higher

getAppMetadata: (appToken: string) => Promise<{isInstalled: boolean; marketUrl: string; appUrl: string}>;

Example

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

getAppMetadata('tokenAppToCheck').then(({isInstalled, marketUrl, appUrl}) => { ... });

• appToken: token that refers to a "friend" application
• appUrl: string url to launch an app installed on the phone
• marketUrl: string url to launch the store in a specific application

setCustomerHash

Sets the hash of the current subscription for the customer, which is used for tracking purposes.

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

setCustomerHash(
    'e658ad63bef9b86863b487697dfb75d64bddb6191ec14099abe443655f6b7cc6',
);

getCustomerHash

Gets the hash of the current subscription for the customer, which is used for tracking purposes.

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

getCustomerHash().then(({hash}) => { ... });

getDiskSpaceInfo

Return info about how much free disk space the device has

• Available for app versions 11.10 and higher

getDiskSpaceInfo: () => Promise<{availableBytes: number, totalBytes: number}>;

Example

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

getDiskSpaceInfo().then(({availableBytes, totalBytes}) => { ... });

• availableBytes: number to see available bytes in the device
• totalBytes: number to see the total bytes in the device

getEsimInfo

Return info about the esim capabilities of the device

• Available for app versions 12.3 and higher

getEsimInfo: () => Promise<{supportsEsim: boolean}>;

Example

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

getEsimInfo().then(({supportsEsim}) => { ... });

• supportsEsim: true if the device supports eSIM, false otherwise

setTrackingProperty

Sets a property related to some specific tracking system

• Available for app versions 12.4 and higher

setTrackingProperty: (system: 'palitagem' | 'medallia', name: string, value?: string) => Promise<void>;

• system: Tracking system that will handle the property
• name: name of the property
• value: value of the property (nullable)

Example

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

setTrackingProperty('some_system', 'some_property_name', 'some_property_value');

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.

Changelog

v.3.0.0 - 2021-07-22

• Breaking change: webview-bridge will be disabled inside iframes by default. It can be enabled by setting a data-enable-webview-bridge property to the iframe element.