Understanding the BuildFire Architecture

Plugin-Based Development

BuildFire apps are constructed using modular plugins—either pre-built or custom-developed. Each plugin operates within a controlled iframe sandbox and interacts with core APIs via the BuildFire SDK. This abstraction simplifies development but limits low-level debugging.

Cloud Backend and Deployment

All plugin assets, app metadata, and configurations are stored and deployed via BuildFire's cloud infrastructure. Misconfigured manifests or expired JWT tokens can cause silent deployment failures or plugin loading issues on devices.

Common BuildFire Issues and Root Causes

1. Plugin Fails to Load or Render Blank

This often occurs when:

• Incorrect plugin.json structure
• Missing required fields like "widget" or "control"
• Uncaught JavaScript exceptions not visible in standard logs

Use browser developer tools and BuildFire's emulator to identify script errors.

2. Plugin API Calls Not Resolving

Plugins communicate with BuildFire core via message-passing. If buildfire.datastore.get or similar calls never resolve, it typically indicates:

• SDK not initialized correctly
• Wrong context in iframe
• Missing permissions in plugin manifest

3. Push Notifications Not Received

Notifications rely on device token registration via BuildFire SDK. Issues arise when:

• The user denies notification permissions initially
• The app is updated without refreshing tokens
• Platform-specific quirks (especially Android 13+)

Diagnostic Techniques

1. Inspect Plugin Lifecycle Events

buildfire.events.on("pluginLoaded", function(){
  console.log("Plugin initialized.");
});

Track plugin bootstrap sequences to detect early failures in iframe communication.

2. Use buildfire.logger for Remote Logs

buildfire.logger.log("Custom init log");

These logs can be viewed in the BuildFire Control Panel under plugin logs. Useful for debugging on real devices where browser tools are unavailable.

3. Validate Permissions and Manifest Structure

{
  "pluginType": "widget",
  "control": { "content": "control.html" },
  "widget": { "content": "widget.html" },
  "permissions": ["datastore", "notifications"]
}

Ensure all used APIs are declared in the permissions block to avoid silent rejections.

Fixes and Stability Improvements

1. Safely Wrap All SDK Calls

try {
  buildfire.datastore.get("settings", function(err, result){
    if(err) console.error("Datastore error", err);
  });
} catch (e) {
  console.error("Unexpected SDK failure", e);
}

This prevents plugin crashes due to unpredictable API states.

2. Avoid DOM Assumptions in Cross-Device Scenarios

BuildFire plugins run in embedded web views. Heavy DOM manipulation or CSS assumptions (e.g., fixed positioning, viewport scaling) can break layout on certain devices. Use responsive frameworks (e.g., Bootstrap 4) consistently.

3. Refresh Device Tokens on App Resume

document.addEventListener("resume", function(){
  buildfire.notifications.registerDeviceToken();
});

Ensures push notification functionality remains valid after app updates or user sessions.

Best Practices for Production-Ready Plugins

• Always validate plugin.json via BuildFire's validator before deployment
• Namespace all data keys to prevent collisions
• Test plugins across emulators and real devices for layout and permission edge cases
• Use feature flags for backward compatibility in multi-version deployments
• Implement fallback content for offline or error states

Conclusion

BuildFire accelerates mobile development but introduces unique debugging challenges due to its abstraction layers and cloud-managed lifecycle. Many failures remain silent—such as plugin loading errors or SDK rejections—unless explicitly monitored. By adopting structured logging, strict manifest validation, and proactive lifecycle handling, development teams can avoid these hidden pitfalls and deliver stable, performant BuildFire apps at scale.

FAQs

1. Why is my plugin showing a blank screen after deployment?

This usually means there's a JavaScript error during initialization or an incorrect path in widget.html. Check browser console logs and validate plugin.json structure.

2. How do I test push notifications during development?

Use BuildFire's emulator to simulate notifications, but validate on real devices with debug tokens to confirm FCM/APNs delivery and permission handling.

3. Can I update a plugin without re-publishing the whole app?

Yes. Plugins are modular and can be updated independently through the BuildFire Control Panel. However, core SDK changes require full app resubmission.

4. What causes datastore.get to silently fail?

Common causes include missing permissions in the manifest, SDK not initialized, or running outside the expected iframe context. Always check the iframe URL and load order.

5. How do I handle version control for custom plugins?

Use Git-based workflows locally, then upload ZIP builds tagged by version. Maintain changelogs and backward-compatible fallbacks to avoid breaking live apps.