Bisatopup Widget - Integration Guide

📋 Overview

The Bisatopup Widget is a lightweight, embeddable PPOB (Payment Point Online Bank) solution that can be integrated into any website with just a few lines of code.

🔌 Easy Integration

Simple 3-line setup with automatic mount point creation

📱 Responsive Design

Works perfectly on desktop and mobile devices

⚡ No Dependencies

Self-contained widget with all dependencies bundled

🚀 Quick Start

1 Include Widget Files

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Your Website</title>

  <!-- Include the widget CSS -->
  <link rel="stylesheet" href="https://your-cdn.com/bisatopup-widget.css">
</head>
<body>
  <!-- Your website content -->

  <!-- Include the widget script -->
  <script src="https://your-cdn.com/bisatopup-widget.js"></script>

  <!-- Configure and initialize the widget -->
  <script>
    const widget = Object.create(btuPpob);
    widget.key = "your-api-key";
    widget.init();
  </script>
</body>
</html>

📌 Note: You don't need to add a specific HTML element for the widget to mount. The widget will automatically create a mount point (<div id="app">) if it doesn't exist.

2 Configuration

The widget requires only one mandatory configuration parameter:

Parameter	Type	Description
`key`	String	Your API key for authentication

🌐 API Server: The API server URL is automatically set to https://widget-api-new.amanahapp.run. You don't need to configure it.

🔧 Advanced Usage

Custom Mount Points

By default, the widget uses #app as the mount point. You can specify a custom mount point:

<!-- Option 1: Let the widget create the element automatically -->
<script>
  const widget = Object.create(btuPpob);
  widget.key = "your-api-key";
  widget.init('#ppob-widget'); // Widget will create <div id="ppob-widget"> automatically
</script>

<!-- Option 2: Create the element yourself (optional) -->
<div id="ppob-widget"></div>
<script>
  const widget = Object.create(btuPpob);
  widget.key = "your-api-key";
  widget.init('#ppob-widget'); // Widget will use existing element
</script>

Multiple Widget Instances

You can create multiple widget instances with different API keys:

<script>
  // First widget
  const widget1 = Object.create(btuPpob);
  widget1.key = "key1";
  widget1.init('#widget1');

  // Second widget
  const widget2 = Object.create(btuPpob);
  widget2.key = "key2";
  widget2.init('#widget2');
</script>

Error Handling

Always check if initialization was successful:

const widget = Object.create(btuPpob);
widget.key = "your-api-key";

if (widget.init()) {
  console.log("Widget initialized successfully");
} else {
  console.error("Failed to initialize widget");
}

📚 API Reference

Methods

Method	Parameters	Returns	Description
`init()`	mountPoint (optional)	Boolean	Initializes and displays the widget
`destroy()`	None	Void	Removes the widget from the page
`getConfig()`	None	Object	Returns current widget configuration
`isReady()`	None	Boolean	Checks if widget is properly configured

🎨 Widget Features

Floating Button: Appears in bottom-right corner
PPOB Services: Mobile top-up, Data packages, Electricity tokens, Bill payments
Transaction Management: View and track transactions
Payment Methods: Multiple payment options
Responsive Design: Works on desktop and mobile

📦 Build Files

The widget consists of these files:

bisatopup-widget.js - Main JavaScript UMD bundle (~607KB)
bisatopup-widget.css - Widget styling (~87KB)

⚠️ Important: Both files are required for the widget to work properly. Include the CSS file in the <head> section and the JavaScript file before your configuration script.

🌐 Browser Support

The widget supports modern browsers:

Chrome 88+
Firefox 85+
Safari 14+
Edge 88+

🔍 Troubleshooting

Widget doesn't appear

Check console for errors
Verify API URL and key are correct
Ensure the API server is accessible
Make sure both CSS and JS files are loaded correctly

CSS conflicts with your site

Widget CSS uses specific class names that shouldn't conflict
If conflicts occur, you can use more specific selectors to override
Consider loading widget CSS after your site's CSS for proper precedence

API connection failed

Verify your API key is valid
Check CORS settings on your API server
Ensure the API server is running

🔐 Security Notes

🔒 Security Best Practices:

Never expose your API key in client-side code in production
Use environment variables or server-side configuration
The widget masks API keys in console output for security
API keys should be rotated regularly

💡 Example Implementation

Here's a complete working example:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>My Website with Bisatopup Widget</title>

  <!-- Your website styles -->
  <style>
    body {
      font-family: Arial, sans-serif;
      margin: 0;
      padding: 20px;
      background: #f5f5f5;
    }
    .content {
      max-width: 800px;
      margin: 0 auto;
      background: white;
      padding: 20px;
      border-radius: 8px;
    }
  </style>

  <!-- Include Bisatopup Widget CSS -->
  <link rel="stylesheet" href="https://your-cdn.com/bisatopup-widget.css">
</head>
<body>
  <div class="content">
    <h1>Welcome to My Website</h1>
    <p>Your website content goes here...</p>
  </div>

  <!-- Include Bisatopup Widget JS -->
  <script src="https://your-cdn.com/bisatopup-widget.js"></script>

  <!-- Initialize Widget -->
  <script>
    // Configure widget
    const widget = Object.create(btuPpob);
    widget.key = "your-api-key-here";

    // Initialize
    if (widget.init()) {
      console.log('✅ Widget loaded successfully!');
    } else {
      console.error('❌ Widget failed to load');
    }
  </script>
</body>
</html>

🚀 Bisatopup Widget