AppNative.js

Getting started

Include the script in your HTML, either from this website:

<script src="https://finnfreitag.com/tools/pwabuilder/appnative-1.0.js"></script>

or download it and put it into your project (recommended for ZIP uploads, so your app also works offline):

<script src="appnative-1.0.js"></script>

Then use the global AppNative object:

AppNative.showToast("Hello from Android!");
AppNative.vibrate(200);

AppNative.onBack(() => {
  if (menuOpen) { closeMenu(); return true; }
});

How it works

• APKs from the builder contain a native bridge (Capacitor) and a fixed set of native plugins. AppNative calls them for you.
• In a normal browser, every function falls back to a web API (or does nothing and logs a warning), so you never need separate code for web and app.
• All functions return Promises and never throw. Listener functions return a function that removes the listener.
• It works for ZIP/HTML uploads and for apps built from a website URL; in URL mode, your website must include the script.
• You can still use any Capacitor plugin API directly through window.Capacitor.Plugins for the plugins included in the APK (App, Haptics, Toast, LocalNotifications, Preferences, Share, Filesystem, Clipboard, Network, Browser).
• The file name is versioned (appnative-1.0.js), so updates will never break existing apps.

Contents

• isNativeApp
• showToast
• vibrate
• haptic
• scheduleNotification
• cancelNotification
• showNotification
• onBack
• exitApp
• onPause
• onResume
• onNetworkChange
• storage
• share
• copyToClipboard
• openExternal
• keepScreenOn
• setStatusBar

Environment

AppNative.isNativeApp(): boolean

if (AppNative.isNativeApp()) {
  document.body.classList.add("in-app");
}

Feedback

AppNative.showToast(text: string, options?: { long?: boolean }): Promise<void>

AppNative.showToast("Saved!");
AppNative.showToast("Level complete – well done!", { long: true });

AppNative.vibrate(pattern: number | number[]): Promise<void>

AppNative.vibrate(200);
AppNative.vibrate([100, 50, 100]); // buzz – pause – buzz

AppNative.haptic(style: "light" | "medium" | "heavy"): Promise<void>

button.addEventListener("click", () => AppNative.haptic("light"));

Notifications

AppNative.scheduleNotification({ at: Date, title: string, text: string, repeat?: "minute" | "hour" | "day" | "week" }): Promise<number | null>

const id = await AppNative.scheduleNotification({
  at: new Date(Date.now() + 60_000),
  title: "Timer",
  text: "Your 1 minute timer is done!",
});

// Every day at 08:00
const tomorrow8 = new Date();
tomorrow8.setDate(tomorrow8.getDate() + 1);
tomorrow8.setHours(8, 0, 0, 0);
AppNative.scheduleNotification({ at: tomorrow8, title: "Daily Maze", text: "A new maze is waiting!", repeat: "day" });

AppNative.cancelNotification(id: number): Promise<void>

AppNative.cancelNotification(id);

AppNative.showNotification(title: string, text: string): Promise<void>

AppNative.showNotification("Download finished", "Your level pack is ready.");

Back gesture & app lifecycle

AppNative.onBack(handler: () => boolean | void): () => void

const off = AppNative.onBack(() => {
  if (menuOpen) {
    closeMenu();
    return true; // handled, don't leave the page
  }
});

// later: off();

AppNative.exitApp(): Promise<void>

quitButton.onclick = () => AppNative.exitApp();

AppNative.onPause(fn: () => void): () => void

AppNative.onPause(() => game.pause());

AppNative.onResume(fn: () => void): () => void

AppNative.onResume(() => refreshData());

AppNative.onNetworkChange(fn: (online: boolean) => void): () => void

AppNative.onNetworkChange(online => {
  banner.hidden = online;
});

Storage

AppNative.storage.set(key: string, value: any): Promise<void>
AppNative.storage.get(key: string): Promise<any | null>
AppNative.storage.remove(key: string): Promise<void>

await AppNative.storage.set("highscore", 42);
await AppNative.storage.set("settings", { sound: true, level: 3 });

const score = await AppNative.storage.get("highscore"); // 42
await AppNative.storage.remove("settings");

Sharing, clipboard & links

AppNative.share({ title?: string, text?: string, url?: string, image?: Blob | File | HTMLCanvasElement | string }): Promise<boolean>

AppNative.share({ title: "Daily Maze", text: "I solved today's maze in 42s!", url: "https://example.com" });

// Share a screenshot of a canvas
AppNative.share({ text: "My new highscore!", image: document.querySelector("canvas") });

// Share an image file from your project
AppNative.share({ image: "images/badge.png" });

AppNative.copyToClipboard(text: string): Promise<boolean>

await AppNative.copyToClipboard(inviteCode);
AppNative.showToast("Copied!");

AppNative.openExternal(url: string): Promise<void>

AppNative.openExternal("https://finnfreitag.com");

Screen & status bar

AppNative.keepScreenOn(enabled: boolean): Promise<void>

AppNative.keepScreenOn(true);
// ...
AppNative.keepScreenOn(false);

AppNative.setStatusBar({ color?: string, lightIcons?: boolean }): Promise<void>

AppNative.setStatusBar({ color: "#000000", lightIcons: true });
AppNative.setStatusBar({ color: "#ffffff" }); // dark icons chosen automatically