@tef-novum/webview-bridge
Advanced tools
JavaScript library to access to native functionality. Requires a webview with a postMessage 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.
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');
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>
Returns true if WebView Bridge is available. Use this function to implement fallbacks in case the bridge is not available.
isWebViewBridgeAvailable: () => boolean;
iframeBy 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.
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');
Show native picker UI in order to let the user select a contact.
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
import {requestContact} from '@tef-novum/webview-bridge';
requestContact({filter: 'phone'}).then((contact) => {
console.log(contact);
}).catch(err => {
console.error(err);
};
Inserts an event in calendar
createCalendarEvent: ({
beginTime: number,
endTime: number,
title: string
}) => Promise<void>;
beginTime and endTime are timestamps with millisecond precision
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);
};
Invokes the native sharing mechanism of the device.
type ShareOptions =
| {
text: string;
}
| {
url: string;
fileName: string;
text?: string;
};
share: (options: ShareOptions) => Promise<void>;
url is present, text is used as item to shareurl param is present, it contains the URL to the shared filefileName param is mandatory if url is seturl and text are set, text is used as Intent BODY (if platform
allows it)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'});
Customize WebView NavigationBar properties
updateNavigationBar = ({
title?: string;
expandedTitle?: string;
showBackButton?: boolean;
showReloadButton?: boolean;
showProfileButton?: boolean;
backgroundColor?: string;
}) => Promise<void>
title: updates NavigationBar titleexpandedTitle: 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.8showBackButton: shows or hides back icon in NavigationBarshowReloadButton: shows or hides NavigationBar Reload buttonshowProfileButton: shows or hides NavigationBar Profile button (which
navigates to user profile). Only available in native app versions >= 11.7backgroundColor: change NavigationBar background color, use a hex color
string (for example: '#FF128A')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
});
Returns true if A/B testing named with the key is available.
isABTestingAvailable: (key: string) => Promise<boolean>;
import {isABTestingAvailable} from '@tef-novum/webview-bridge';
isABTestingAvailable('key').then((isAvailable) => {
console.log(isAvailable);
}).catch(err => {
console.error(err);
};
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>;
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');
}
});
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>;
import {nativeAlert} from '@tef-novum/webview-bridge';
nativeAlert({
message: 'Purchase completed!',
title: 'Ok!',
}).then((res) => {
console.log('alert closed');
});
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>;
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');
});
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>;
If you want to use new Google Analytics 4 event format you can use this method too:
logEvent: ({
name: string; // The event name is mandatory
[key: string]: any; // You can set any other event parameters
}, {
sanitize?: boolean; // Whether to sanitize the event params, this only affects to FirebaseEvents. true by default.
}) => Promise<void>;
import {logEvent} from '@tef-novum/webview-bridge';
logEvent({
category: 'topup-flow',
action: 'topup',
}).then(() => {
console.log('event logged');
});
// Or with GA4 format
logEvent({
name: 'user_interaction',
component_type: 'primary_button',
component_copy: 'topup',
}).then(() => {
console.log('event logged');
});
By default, GA4 event params are sanitized. The sanitization consists of removing whitespaces and some special characters, lowercasing and trimming. This allows us having a consistent event format accross events.
In some cases you may want to disable this behavior. To do so, you can set the
sanitize option to false:
logEvent(yourEvent, {sanitize: false});
Log the current screen name (or page name) to firebase
setScreenName: (screenName: string, params?: {[key: string]: any}) => Promise<void>;
import {setScreenName} from '@tef-novum/webview-bridge';
setScreenName('Topup Flow').then(() => {
console.log('screen name logged');
});
You can also send additional params with the screen name:
setScreenName('Topup Flow', {someParam: 'some value'});
Set a user property to firebase
setUserProperty: (name: string, value: string) => Promise<void>;
import {setUserProperty} from '@tef-novum/webview-bridge';
setUserProperty('obIds', 'any-value').then(() => {
console.log('User property logged');
});
Report a given feature status
reportStatus: ({feature: 'ACCOUNT', status: 'CRITICAL' | 'GOOD' | 'BAD', reason: string}) => Promise<void>;
import {reportStatus} from '@tef-novum/webview-bridge';
reportStatus({feature: 'ACCOUNT', status: 'GOOD', reason: 'whatever'});
Listens to native app events
type NativeEventHandler = ({ event }: {event: string}) => {action: 'default'};
onNativeEvent: (handler: NativeEventHandler) => () => void;
onNativeEvent(({event}) => {
if (event === 'tappedNavigationBarBackButton') {
// do something
}
return {action: 'default'};
});
tappedNavigationBarBackButton: fired when the user taps on the back button
of the native Navigation Bar. Allowed response actions: defaultReturns true if the app has the specific notifications permissions. You have to pass feature and required params for this request.
Avalaible features:
notificationsread-contacts (Available for app versions 13.10 and higher)write-contacts (Available for app versions 13.10 and higher)checkPermissionStatus: (feature: string, params?: {[key: string]: string}) => Promise<boolean>;
import {checkPermissionStatus} from '@tef-novum/webview-bridge';
checkPermissionStatus('notifications', {channelId: 'default'}).then(
(hasPermissions) => {
console.log(hasPermissions);
},
);
Init an internal and native navigation to a device specific feature
Avalaible features:
notification-settingscontact-settings (Available for app versions 13.10 and higher)internalNavigation: (feature: string) => Promise<void>;
import {internalNavigation} from '@tef-novum/webview-bridge';
internalNavigation('notification-settings');
Dismiss the current webview and optionally navigate to another url
dismiss: (onCompletionUrl?: string) => Promise<void>;
import {dismiss} from '@tef-novum/webview-bridge';
dismiss('http://example.com');
Requests the phone to vibrate. Options are 'error' or 'success'.
import {requestVibration} from '@tef-novum/webview-bridge';
requestVibration('error');
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;
}>>;
Check if an app is installed in the phone
getAppMetadata: (appToken: string) => Promise<{isInstalled: boolean; marketUrl: string; appUrl: string}>;
import {getAppMetadata} from '@tef-novum/webview-bridge';
getAppMetadata('tokenAppToCheck').then(({isInstalled, marketUrl, appUrl}) => { ... });
appToken: token that refers to a "friend" applicationappUrl: string url to launch an app installed on the phonemarketUrl: string url to launch the store in a specific applicationSets the hash of the current subscription for the customer, which is used for tracking purposes.
import {setCustomerHash} from '@tef-novum/webview-bridge';
setCustomerHash(
'e658ad63bef9b86863b487697dfb75d64bddb6191ec14099abe443655f6b7cc6',
);
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}) => { ... });
Return info about how much free disk space the device has
getDiskSpaceInfo: () => Promise<{availableBytes: number, totalBytes: number}>;
import {getDiskSpaceInfo} from '@tef-novum/webview-bridge';
getDiskSpaceInfo().then(({availableBytes, totalBytes}) => { ... });
availableBytes: number to see available bytes in the devicetotalBytes: number to see the total bytes in the deviceReturn info about the esim capabilities of the device
getEsimInfo: () => Promise<{supportsEsim: boolean}>;
import {getEsimInfo} from '@tef-novum/webview-bridge';
getEsimInfo().then(({supportsEsim}) => { ... });
supportsEsim: true if the device supports eSIM, false otherwiseSets a property related to some specific tracking system
setTrackingProperty: (system: 'palitagem' | 'medallia', name: string, value?: string) => Promise<void>;
system: Tracking system that will handle the propertyname: name of the propertyvalue: value of the property (nullable)Method that allows defining an specific behavior (such as showing a confirmation) before the specific native actions are executed. This method also allows disabling any previous behaviors set.
type ActionBehavior =
| {
behavior: 'confirm';
title: string;
message: string;
acceptText: string;
cancelText: string;
}
| {
behavior: 'default';
}
| {
behavior: 'cancel';
};
setActionBehavior: (actions: {webviewClose?: ActionBehavior, navigationBack?: ActionBehavior}) => Promise<void>;
navigationBack and webviewClose actions are currently available:
navigationBack: Action bar back button pressed (also for physical back
button in android but not swipe back gesture in iOS, which will be
disabled).webviewClose: Action bar close button pressed. Includes both "X" and
"Close" buttons (but not swipe down gesture in iOS, which will be disabled).Both have same allowed json parameters, and 3 allowed behaviors:
confirm Show a confirmation dialog with the required title, message and
buttons.cancel Prevent action from being performed, just ignoring it.default Set default behavior for the action. (Usually to reset any
previously specified behavior).Actions can be optionally included in the payload. Any not included action won’t change its current behavior set.
All actions behaviors will be automatically set to default on full page loads.
import {setTrackingProperty} from '@tef-novum/webview-bridge';
setTrackingProperty('some_system', 'some_property_name', 'some_property_value');
Tell the app to renew the session.
renewSession = (
oldAccessToken: string | null,
options: {timeout?: number} = {},
) => Promise<string>
Defines a callback that will be executed when the native app renews the session. Returns the unsubscribe function.
onSessionRenewed = (
handler: (newAccessToken: string) => void,
) => (() => void)
A method that requests a user logout.
logout = () => Promise<{success: boolean}>
Returns the Topaz token.
getTopazToken = (options: {timeout?: number} = {}) => Promise<{token: string}>
Show native app rating dialog
showAppRating = () => Promise<void>
Show native bottom sheet ui
bottomSheet = (payload: SheetUI) => Promise<SheetResponse>
// see SheetUI and SheetResponse types
:warning: If you try to call this method repeatedly while a sheet is already
being opened (for example, user accidental double tap), it will throw an Error
with code 423 (Locked)
There are some specific cases of bottom sheet, and we have some utility methods to make them simpler to use:
For single selection use bottomSheetSingleSelector:
bottomSheetSingleSelector = ({
title?: string;
subtitle?: string;
description?: string;
selectedId?: string;
items: Array<SheetRowItem>;
}) => Promise<{action: 'SUBMIT' | 'DISMISS'; selectedId: string}>
For a bottom sheet with a list of actions use bottomSheetActionSelector:
bottomSheetActionSelector = ({
title?: string;
subtitle?: string;
description?: string;
items: Array<SheetActionItem>;
}) => Promise<{action: 'SUBMIT' | 'DISMISS'; selectedId: string}>
For an informative bottom sheet use bottomSheetInfo:
bottomSheetInfo = ({
title?: string;
subtitle?: string;
description?: string;
items: Array<SheetInfoItem>;
}) => Promise<void>
import {bottomSheetSingleSelector} from '@tef-novum/webview-bridge';
const {action, selected} = await bottomSheetSingleSelector({
title: 'Some title',
subtitle: 'Some subtitle',
description: 'Some description',
selectedId: 'item-1',
items: [
{
id: 'item-0',
title: 'item 0 title',
description: 'item 0 description',
},
{
id: 'item-1',
title: 'item 1 title',
description: 'item 1 description',
},
{
id: 'item-2',
title: 'item 2 title',
description: 'item 2 description',
},
],
});
Fetch all the phone numbers of the native phonebook
fetchPhoneNumbers:() => Promise<Array<{
id: string;
value: string;
}>>;
Updates the given phone numbers in the native phonebook
updatePhoneNumbers:(Array<{
id: string;
value: string;
}>) => Promise<Void>;
Method that allows a WebView to ask an iOS app user about the authorization status of his ATT (App Tracking Transparency) permission.
Resolves to null if the app is not running on iOS or if the method is not
available
getAttStatus: () => Promise<{status:'granted' | 'denied' | 'unknown'} | null>;
If an error occurs, promise will be rejected with an error object:
{code: number, description: string}
This project is licensed under the terms of the MIT license. See the LICENSE file.
v.3.24.0 - 2023-07-20
getAttStatus methodFAQs
JavaScript library to access to native functionality. Requires a webview with a postMessage bridge.
The npm package @tef-novum/webview-bridge receives a total of 876 weekly downloads. As such, @tef-novum/webview-bridge popularity was classified as not popular.
We found that @tef-novum/webview-bridge demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 0 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
PEP 770 proposes adding SBOM support to Python packages to improve transparency and catch hidden non-Python dependencies that security tools often miss.
Security News
Socket CEO Feross Aboukhadijeh discusses open source security challenges, including zero-day attacks and supply chain risks, on the Cyber Security Council podcast.
Security News
Research
Socket researchers uncover how threat actors weaponize Out-of-Band Application Security Testing (OAST) techniques across the npm, PyPI, and RubyGems ecosystems to exfiltrate sensitive data.