🐞Debug Console

Inspect native feature communication and monitor logs directly on your device.

What is the Debug Console?

The Debug Console is a built-in inspector that slides up over your app, letting you monitor the communication between your web app and the native mobile environment in real time. It's the most powerful tool for diagnosing issues with native features - you can see exactly what data is being sent and received between your app and native SDKs like OneSignal or RevenueCat.

When submitting a support ticket about a native feature not working, always attach a screenshot of the Debug Console. It gives our team the raw logs needed to diagnose the issue immediately.

Prerequisites

This feature is available in all plans. See all plans

Implementation

Choose your integration method below: Bubble.io Plugin (No-Code), JavaScript SDK (Code), NPM Package (React/Next.js), or AI Agents (for AI-powered editors like Lovable, Base44, and Replit).

Initialization

Check Plugin

Before starting, verify if the Natively plugin is already installed in your Bubble project.

Open your Bubble editor and navigate to the Plugins tab in the left sidebar.
Check Installed Plugins: Look through your list of installed plugins for "Natively iOS & Android app builder".
- If it IS installed: Check the version number. If an update is available (e.g., you see a button saying "Update"), click it to ensure you have the latest features and bug fixes.

If it is NOT installed: Click the + Add plugins button, search for "Natively", and click Install.

Check SDK

Before writing any logic, ensure the Natively SDK is correctly installed and up-to-date in your codebase.

Open your project's main HTML file (or header settings) and look for the Natively script tag inside the <head> section.
Install/Update: If missing or outdated, add the following code. You can specify the SDK version in the URL (e.g., @2.26.0).

<head>
  <script async onload="nativelyOnLoad()" src="https://cdn.jsdelivr.net/npm/natively@2.26.0/natively-frontend.min.js"></script>
</head>

To ensure you are using the most up-to-date version, check the Natively GitHub releases page for the latest version number.

Check npm Package

Before writing any logic, ensure the Natively NPM package is installed and up to date in your project.

npm install natively@latest

Initialize the SDK

AI-powered editors like Lovable, Base44, and Replit use the JavaScript SDK to implement Natively features. Before implementing any feature, the Natively SDK must be initialized in your project.

Copy the line below and paste it into your AI agent to check and set up the Natively SDK in your project.

Check if the following Natively SDK script is present in the <head> of index.html. If missing or outdated, add it: <script async onload="nativelyOnLoad()" src="https://cdn.jsdelivr.net/npm/natively@2.26.0/natively-frontend.min.js"></script><script>function nativelyOnLoad() { window.natively.setDebug(true); console.log("✅ Natively SDK loaded successfully."); }</script> For reference: https://docs.buildnatively.com/guides/integration/how-to-get-started https://github.com/buildnatively/js-sdk/releases

Setup Logic

[Action] Natively - Open Debug Console

Opens the Debug Console overlay. No parameters required. Add this action to any workflow - for example, when a button is clicked.

// ============================================================================
// NATIVELY DEBUG CONSOLE - DOCUMENTATION & EXAMPLES
// ============================================================================

// No initialization required — openConsole is available directly
// on the global window.natively object.

// ============================================================================
// ALL AVAILABLE METHODS
// ============================================================================
// window.natively.openConsole()
//   - Opens the Debug Console overlay.
//   - No parameters required. No callback.

// --- Debug Console. Example. Start ---

window.natively.openConsole();

// --- Debug Console. Example. End ---

'use client';

import { useNatively } from 'natively';

export default function DebugButton() {
  const natively = useNatively();

  return (
    <button onClick={() => natively.openConsole()}>
      Open Debug Console
    </button>
  );
}

AI-powered editors like Lovable, Base44, and Replit use the JavaScript SDK to implement Natively features.

Copy the line below and paste it into your AI agent.

[Your feature description] using the Natively Debug Console SDK: // window.natively.openConsole() — opens the Debug Console overlay. No parameters or callback required. For reference: https://docs.buildnatively.com/guides/integration/debug-console

Replace the placeholder at the beginning with a description of what you want to build - for example: "Add a hidden debug button that opens the Natively Debug Console when tapped 3 times".

How to use

Trigger from a button, not on page load

The most common pattern is adding a hidden button somewhere in your app - for example, in a developer settings screen or triggered by tapping a logo multiple times - that opens the console on demand. Avoid triggering it automatically on page load.

Check if running inside the native app first

The Debug Console only works inside a Natively app. Use Browser Info to check browserInfo.isNativeApp before calling openConsole(), so you don't trigger it accidentally in a web browser.

Monitor native SDK communication

Open the console and trigger the feature you're debugging - push notifications, in-app purchases, AdMob - then watch the logs appear in real time. You can see exactly what data your web app is sending to the native layer and what's coming back.

Attach a screenshot to support tickets

When something isn't working, and you're contacting Natively support, always include a screenshot of the Debug Console showing the relevant logs. This allows the support team to skip the diagnosis phase and go straight to a fix.

Use setDebug(true) during development

Setting window.natively.setDebug(true) in your SDK initialization shows native OS alerts when an SDK error occurs, giving you an additional layer of visibility during development. Set it to false before releasing to production.

Troubleshooting

Nothing happens when triggering the Debug Console

Two common causes:

Not running inside a Natively app - the Debug Console is a native feature and will not work in a standard mobile browser (Safari, Chrome) or wrappers created by other services. Test on a real device using a Natively build or the Preview app.
SDK not correctly installed - the openConsole() command is a message sent from your website to the native app. If the Natively SDK isn't properly installed in your web app's <head>, the message is never sent. To verify, open your browser's inspector on desktop and type window.natively - if it returns undefined, the SDK is not integrated correctly.

The console opens but shows no logs for a specific feature

Make sure you trigger the feature after the page has loaded. The console shows logs accumulated since page load - if you triggered the feature before the page fully loaded, those logs may not appear. Try refreshing the page and triggering the feature again before opening the console.

Debug Console is not available in a web browser

This is expected - the Debug Console is a native feature. Use your browser's built-in developer tools (console.log) for web-side debugging instead.

PreviousDate Picker

NextDevice Info

Last updated 2 months ago