README
Progressive Web Apps API of APIs (Sponsor us)
Build Scalable Progressive Web Apps. Start via docs.pwafire.org site.
Welcome to @pwafire v.4.0.0 which is the second iterational foundation for our next generation of the pwafire api. Note that, these release is a breaking change, before upgrading, check the documentations first.
Breaking change for v4.0.0 moving forward
All responses returned have a new ok
value, a boolean type which replaces success
value, a boolean as shown below;
Install pwafire via NPM
npm i pwafire --save
Get pwafire over CDN as an E6 Module
Note that you can still use a specific version over the pwafire cdn
Latest version
import { pwa } from "https://unpkg.com/pwafire/esm/index.js";
Specific version
import { pwa } from "https://unpkg.com/pwafire@3.0.8/esm/index.js";
Import pwafire in your for e.g React App
import { check, pwa } from "pwafire";
All stable in Chrome 80 and later versions, also in MS Edge. Check Browser Support status.
API Spec
For all promise types, the promise value returned is an object - might include additional data for example, Contacts API returns an additional contacts value.
// Success...ok value is true...
{
ok : true,
message : "Success message",
}
// Fail...success value is false...
{
ok : false,
message : "Error message..."
}
// Async API...
const res = await pwa.CopyText(text);
// Lower versions...
if (res.success) {
// Do something...
}
// New version starting v4.0.0
if (res.ok) {
// Do something...
}
Do something with the response returned for e.g copyText;
// Copy text
pwa
.copyText(text)
.then((res) => {
// Do something with 'res'
if (res.ok) {
// Success...
} else {
// Fail...
}
})
.catch((err) => {
// Do something with 'err'
});
API Feature Detection
- Goal is to allow room for custom handlers if need be
- This approach is going to be experimental and will be updated
- This addition is going to be built for available stable apis
Example and use case
- Web Share is both on Edge desktop and mobile, but not with chrome. I'd like to show a copy link button for chrome
- Install latest pwafire version, already up for testing in v4 alpha-3*
npm i --save pwafire@latest
- Try it out
// Get the check instance from pwafire...
import { check } from "pwafire";
//...
// The response is a boolean, true or false...
const isSupported = await check.Share();
1. Copy Text
Copy text to clipboard.
Call the copyText method on pwa
// Copy text
pwa.copyText(text);
2. Copy image (Only PNG are supported for security purposes) to clipboard
Copy png images to clipboard
Call the copyImage method on pwa
pwa.copyImage(imgURL);
3. Web Share
Share links, text, and files to other apps installed on the device.
Define the data object to be shared
const data = {
// Title of what to share
title: `Some title..`,
// Text to share
text: `Some text...`,
// Url to share...
url: "https://pwafire.org",
};
Call the share method on pwa
pwa.Share(data);
4. Contacts Picker
Contacts Picker API allows a PWA to access contacts from the mobile device's native contacts manager.
Chrome 80 or higher running on Android M or later required.
Define the "properties" and "select type" option you need
const props = ["name", "email", "tel"];
const options = { multiple: true };
Call the contacts method on pwa, the promise resolves with an object
// Do something with the promise value...
pwa.Contacts(props, options).then((res) => {
// Do something with contacts...
const contacts = res.ok ? res.contacts : null;
//...
});
5. Show PWA Connectivity status
Pass in two call back funtions, aka online and offline handlers.
Declaring the two handlers separately
// Online handler...
const online = () => {
//...
};
// Offline handler...
const offline = () => {
//...
};
Call the connectivity method on pwa, adding the two parameters
pwa.Connectivity(online, offline);
6. Fullscreen
Open app in fullscreen on a click event
Call the fullscreen method
pwa.Fullscreen();
7. Notifications
Show notifications. Pass a data object
Add notification data
const data = {
title: "Hello Notification!",
options: {
body: "Progressive Web App Hello Notification!",
icon: "../images/icons/icon-192x192.png",
tag: "pwa",
},
};
data
object, for e.g
Call the notification method, pass in // Call the notification method...
pwa.Notification(data);
8. Install
Add custom install button, provide a "button element" as the parameter
Call the install method
pwa.Install(button);
9. Badging
Add badging for app icons
Badging makes it easy to subtly notify the user that there is some new activity that might require their attention, or indicate a small amount of information, such as an unread count.
Set the badge
Returns an object, which is either a success or an error type
// Set the badge
const unreadCount = 24;
pwa.setBadge(unreadCount);
Clear the badge
// Clear the badge
pwa.clearBadge();
10. Screen Wake Lock API
The Screen Wake Lock API provides a way to prevent devices from dimming or locking the screen when an application needs to keep running.
Call the install method, returns a promise value
pwa.WakeLock();
11. Visibility
Check if user is viewing a page. Pause/play video or games e.t.c
Define page visibilty handler
// Do something....
const isVisible = () => {
//...
};
If visbility api is not supported, define the handler
// Do something....
const notAvailable = () => {
//...
};
Call the visibility method with the two arguments
pwa.Visibility(isVisible, notAvailable);
12. The File System Access API
The File System Access API allows web apps to read or save changes directly to files and folders on the user's device.
Call pickFile method on pwa
The promise resolves with a file response
// Do something with the contents...
const res = await pwa.pickkFile();
const file = res.ok ? res.file : null;
Call the pickTextFile method on pwa
The promise resolves with a text response(contents of the picked text file)
// Do something with the contents...
const res = await pwa.pickTextFile();
const contents = res.ok ? res.contents : null;
13. Content Indexing
This API allows you to index your offline-capable pages.
Call the contentIndexing method on pwa
Note : The Content Indexing API was launched in Chrome 84 for Android.
const index = await pwa.contentIndexing();
if (index.ok) {
// Do something...like
// 1. Add a page to the index...
// 2. Remove a page from the index...
// 3. Get all indexed pages...
}
Add a page to the index
const res = await index.addItem({
// Required; set to something unique within your web app.
id: "article-123",
// Required; url needs to be an offline-capable HTML page.
url: "/articles/123",
// Required; used in user-visible lists of content.
title: "Article title",
// Required; used in user-visible lists of content.
description: "Amazing article about things!",
// Required; used in user-visible lists of content.
icons: [
{
src: "/img/article-123.png",
sizes: "64x64",
type: "image/png",
},
],
// Optional; valid categories are currently:
// 'homepage', 'article', 'video', 'audio', or '' (default).
category: "article",
});
Remove a page from the index
const res = index.removeItem({
// Required; provide the id of the item to remove...
id: "article-123",
});
Get all indexed pages
const items = await index.getAll();
14. Web Payments
Allows users select their preferred way of paying for things, and make that information available to a merchant.
Call Payment method with three arguments
pwa.Payment(pay, paydata, validatePayment);
Example : compute total amount to pay
Test Demo Application : Live Preview
// Calculations...
const payment = {
price: sale_price,
get discount() {
return this.price * 0.005;
},
get total() {
return this.price + this.tax - this.discount;
},
get tax() {
return 0.14 * this.price;
},
};
// Destructure payment object...
const { tax, discount, total } = payment;
Set Payment methods
const paymentMethods = [
{
supportedMethods: ["basic-card"],
data: {
supportedNetworks: ["visa", "mastercard"],
},
},
];
Set Payment details
const paymentDetails = {
total: {
label: "Total Amount",
amount: {
currency: "KSH",
value: total.toString(),
},
},
displayItems: [
{
label: "Discount",
amount: {
currency: "KSH",
value: discount.toString(),
},
},
{
label: "Taxes, 14% V.A.T",
amount: {
currency: "KSH",
value: tax.toString(),
},
},
],
};
Requesting additional info
const options = {
requestPayerName: true,
requestPayerEmail: true,
};
Create paydata object
const paydata = {
paymentMethods,
paymentDetails,
options,
};
Validate payment (Do something with the Payment Response)
const validatePayment = async(paymentResponse) => {
try {
// Check if payment was successful based on your payment gateway...
const condition = await yourSuccessHandler(paymentResponse);
// Please note that complete status can only be "success" or "fail"...
if (condition) {
//...
// Return sucesss...
await paymentResponse.complete("success");
} else {
//...
// Return fail...
await paymentResponse.complete("fail");
}
};
} catch(error) {
throw error;
}
Call Payment method on pwa
// Pay...
pwa.Payment(paydata, validatePayment);