@mobiloud/ml-popup-widget
v1.0.0
Published
MobiLoud popup widget
Downloads
71
Readme
WIP MobiLoud Popup Widget
MobiLoud Popup Widget
A seamless user experience is crucial for app retention. One effective way to ensure users have the latest features and bug fixes is by implementing update popups. These timely notifications encourage users to update their app, leading to improved performance and satisfaction.
By effectively utilizing update popups, you can drive app engagement, improve user satisfaction, and ultimately increase your app's success.
Features
ML Popup Widget features:
- Configuration options:
- Popup position
- Popup delay
- Texts fonts
- Texts color
- Popup BG
- Popup stlyes : it comes with a predefined iOS-like UI
- Text content (for button and heading/description)
- Entering animation
- Android and iOS links
- Button Link applies automatically depending on user agent: If Android, it uses the provided android link if iOS, uses the provided ios link.
- deviceData method available: its a function that can be called to get the current browser OS, useful for triggering external functions'. It returns a string containing "android" | "ios" | "windows"
- Default options set (if not texts, images or colors provided, it shows placeholder info, useful for catching errors or for testing while implementing the popup)
- Popup can be used as a module or used directly in an html / script tag
- Code written in Typescript and minified/bundled with Vite
How to use 📖
Popup Widgets can be used importing the JS code via CDN or as a module using NPM
With CDN 🚀
<script type="module" src="https://cdn.jsdelivr.net/npm/@mobiloud/ml-popup-widget/dist/ml-popup-widget.min.js"></script>
<script>
function addPopupWidget() {
new PopupWidget().init();
}
window.addEventListener('load', addPopupWidget);
</script>
NPM 📦
Copy directly in yor site 📄
Copy the following code at the end of your page body, modify values as necessary. Scroll down this docs for further explanation for each part of the code. This code shows up when the minimum version required of the app doesnt match the current app's version:
const popupOptions = {
popupStyle: 'ios',
fontFamily: `"Source Sans Pro", "Arial", sans-serif`,
textColor: '#222',
textHeading: 'Upgrade required',
textDescription: 'This app is out of date, please visit store to upggrade to the latest version',
buttonText: 'Download new version',
buttonColor: '#000000',
buttonTextColor: "#ffffff",
widgetColor: '#fff',
backDrop: true,
backDropBlur: true,
backDropZIndex: 888888,
zIndex: 999999,
position: 'center',
animation: 'fadeIn',
display: 'onLoad',
radius: '10px',
delay: 0,
shadow: true,
useSession: false,
maxWidth: "700px",
closable: false,
padding: '20px',
linkIos: 'https://itunes.apple.com/',
linkAndroid: 'https://play.google.com/',
};
function addPopupWidget() {
if(deviceData.isMobile || deviceData.isCanvas ){
const minVersion = 1.0;
const appVersion = nativeFunctions.getDeviceInfo().appVersion;
const compareVersions = deviceData.compareAppVersion(minVersion, appVersion)
if(deviceData.compareAppVersion(minVersion, appVersion)) {
new PopupWidget(popupOptions);
}
}
}
window.addEventListener('load', addPopupWidget);
Configuration options ⚙️
const popupOptions = {
popupStyle: 'ios', //'ios' | 'normal' - defines the popup style, ios gives the popup an iOS UI style, 'normal' gives the possibility to apply custom styles
fontFamily: `"Source Sans Pro", "Arial", sans-serif`, // string - Font family for widget texts, defaults to system safe fonts
textColor: '#222', // string - Widget texts color (any color property value)
textHeading: 'Upgrade required', // string - Heading Text
textDescription: 'This app is out of date, please visit store to upggrade to the latest version', // string - Description text
buttonText: 'Download new version', // string - button text
buttonColor: '#000000', // string - button background color, uses css color values
buttonTextColor: "#ffffff", // string - button text color, uses css color values
widgetColor: '#fff', // string - Popup background color
backDrop: true, // boolean - If true, shows a subtle dark backdrop behind popup that locks page scroll
backDropBlur: true, // boolean - If true, all content behind backdrop gets blurred
backDropZIndex: 888888, // number - this should be higher than any other element in the page but lower than zIndex value
zIndex: 999999, // number - Popup's z-index, this should be higher than any other element in the page
position: 'center', // string - Position of the widget, default 'center'. 'center' | 'top' | 'bottom'
animation: 'fadeIn', // string - Widget animation, default 'fadeIn'. 'fadeIn' | null,
display: 'onLoad', // string - Display options, default 'onLoad'. 'onLoad', can be adjusted with a delay using the 'delay' option
radius: '10px', // string - Widget radius with units, modifies the CTA radius too
delay: 0, // number - defines how much time to wait until the element shows up
shadow: true, // boolean - If true applies soft shadow, true | false
useSession: false, // boolean - if true, once closed, saves a key in browser's LocalStorage
maxWidth: "700px", // string - popup max width
closable: false, // boolean - if true, popup can be closed with a close button or clicking the blackdrop
padding: '20px', // string - Popup's internal padding
linkIos: 'https://itunes.apple.com/', // string - Link for iOS
linkAndroid: 'https://play.google.com/', // string - Link for Android
};
Methods 💡
deviceData.os // returns current os "android" | "ios" | "windows" | "desktop"
deviceData.isCanvas // returns true or false
deviceData.isMobile // returns true or false
deviceData.compareAppVersion(a, b) // Accepts 2 strings with semantic app versions ('1.0.0', '2.1.4', etc) returns:
/*
0: version strings are equal
1: version a is greater than b
-1: version b is greater than a
*/
Recipes 🍳
This are useful ways to implement the widget. We always recommend using an Event Listener to trigger the code when the document is loaded window.addEventListener('load', fnName)
Detecting current version & implementing widget
The widget is great for cases where you want users to update the app before using it. For achieving this, our Canvas platform frovides some useful functions that can be called within your website to get specific device / app information.
Native Functions - Get user information
const popupOptions = {/*insert popup options here*/};
function addPopupWidget() {
if(deviceData.isMobile || deviceData.isCanvas ){
/* THIS IS THE MINIMUM APP VERSION THE USER SHOULD BE USING*/
const minVersion = 1.0;
/* This returns an object containing useful device/app information */
const appVersion = nativeFunctions.getDeviceInfo().appVersion;
const compareVersions = deviceData.compareAppVersion(minVersion, appVersion)
/*
Returns 0, 1 or -1
0: version strings are equal
1: version a is greater than b
-1: version b is greater than a
*/
if(deviceData.compareAppVersion(minVersion, appVersion)) {
new PopupWidget(popupOptions);
}
}
}
window.addEventListener('load', addPopupWidget);
Insert Popup Widget in Canvas only
function addPopupWidget() {
if(deviceData.isMobile || deviceData.isCanvas ){
new PopupWidget(options);
}
}
window.addEventListener('load', addPopupWidget);
Using deviceData method to filter devices
const options = {
// Set params here
}
// Insert widgets only in our Canvas platform
if(deviceData.isCanvas) {
const popupWidget = new PopupWidget(options);
}
// Apply specific configs based on OS
if(deviceData.os === "android" || deviceData.os === "windows") {
const popupWidget = new PopupWidget(options1);
}
if(deviceData.os === "desktop" || deviceData.os === "ios") {
const popupWidget = new PopupWidget(options2);
}
// Insert widgets only in Mobile userAgent
if(deviceData.isMobile) {
const popupWidget = new PopupWidget(options3);
}
Development
npm run build
produces a production version into /dist foldernpm run dev
runs dev version and starts a dev server
Testing Widgets 🧪
www.mobiloud.com/docs/testing-widgets
License
Copyright (c) MobiLoud