pingboxjs

pingboxjs is a JavaScript SDK that lets websites send real native mobile push notifications without building a native mobile app.

Instead of browser notifications, users install a single companion Android app once. After a one time device binding, any website using pingboxjs can send true native notifications that work even when the browser is closed.

The purpose of pingboxjs is simple. Enable native mobile notifications using only JavaScript.

How it works

1. The user installs the pingbox companion Android app
2. The user visits your website
3. Your website generates a binding code
4. The user enters the code inside the mobile app
5. The device is linked to your website
6. Your website can now send native push notifications

Requirements

1. A running pingbox backend server
2. A Firebase project with Firebase Cloud Messaging enabled
3. The pingbox Android mobile app installed on the user device

Getting an API key

To use pingboxjs you need an API key generated from the developer dashboard.

Run the dashboard locally or deploy it:

cd pingbox-dashboard
npm install
npm run dev

Open http://localhost:3000 in your browser and register your website to generate an API key.

Backend setup

The backend handles device binding and notification delivery and requires Firebase.

cd pingbox-backend
npm install
# place your firebase service account file in this folder
node server.js

By default the backend runs on http://localhost:3001.

Important. When testing on a real Android device, replace localhost with your computer local IP address.

Mobile app

The pingbox Android app must be built and installed manually.

cd pingboxapp
npm install
cd android && ./gradlew assembleRelease

The generated APK can be found at:

android/app/build/outputs/apk/release/app-release.apk

Install this APK on the Android device.

Installing the SDK

For local development, include the built SDK file:

<script src="/path/to/pingbox.min.js"></script>

When published to npm:

npm install pingboxjs

The SDK is used through the global pingbox object.

Initializing pingboxjs

pingboxjs uses an init based API and does not use a constructor.

const pingbox = pingbox.init("YOUR_API_KEY", {
  baseUrl: "http://YOUR_LOCAL_IP:3001",
  logLevel: "debug"
});

baseUrl must point to your running backend server.

Binding a device

Generate a binding code and display it to the user.

const { bindingCode, expiresIn } = await pingbox.lockin();

console.log("Enter this code in the pingbox app:", bindingCode);
console.log("Expires in", expiresIn, "seconds");

The user enters this code inside the mobile app to complete the binding.

Sending a notification

Once a device is bound, you can send notifications at any time.

await pingbox.shoot(
  "Welcome",
  "Thanks for joining our platform",
  {
    url: "https://yourwebsite.com",
    queueIfOffline: true
  }
);

Notifications are delivered as real native mobile notifications.

If the backend is temporarily unreachable, notifications are automatically queued and retried.

Minimal example

<!DOCTYPE html>
<html>
<body>
  <button onclick="connect()">Bind Device</button>
  <button onclick="notify()">Send Notification</button>

  <script src="/path/to/pingbox.min.js"></script>
  <script>
    const pingbox = pingbox.init("YOUR_API_KEY", {
      baseUrl: "http://YOUR_LOCAL_IP:3001"
    });

    async function connect() {
      await pingbox.lockin();
      alert("Enter the displayed code in the pingbox app");
    }

    async function notify() {
      await pingbox.shoot("Hello", "Notification from the web");
    }
  </script>
</body>
</html>