> For the complete documentation index, see [llms.txt](https://docs.buildnatively.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.buildnatively.com/guides/integration/debug-console.md).
# Debug Console
## 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.
{% hint style="info" %}
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.
{% endhint %}
## Prerequisites
{% hint style="success" %}
This feature is available in all plans. [See all plans](/getting-started/subscription-plans.md)
{% endhint %}
## 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
{% tabs %}
{% tab title="Bubble.io Plugin" %}
**Check Plugin**
Before starting, verify if the Natively plugin is already installed in your Bubble project.
1. Open your Bubble editor and navigate to the Plugins tab in the left sidebar.
2. **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.
{% endtab %}
{% tab title="JavaScript SDK" %}
**Check SDK**
Before writing any logic, ensure the Natively SDK is correctly installed and up-to-date in your codebase.
1. Open your project's main HTML file (or header settings) and look for the Natively script tag inside the `` section.
2. Install/Update: If missing or outdated, add the following code. You can specify the SDK version in the URL (e.g., `@2.26.0`).
```javascript
```
{% hint style="info" %}
To ensure you are using the most up-to-date version, check the [Natively GitHub releases page](https://github.com/buildnatively/js-sdk/releases) for the latest version number.
{% endhint %}
{% endtab %}
{% tab title="npm Package" %}
**Check npm Package**
Before writing any logic, ensure the Natively NPM package is installed and up to date in your project.
```bash
npm install natively@latest
```
{% endtab %}
{% tab title="AI Agents" %}
**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 of index.html. If missing or outdated, add it: For reference: https://docs.buildnatively.com/guides/integration/how-to-get-started https://github.com/buildnatively/js-sdk/releases
```
{% endtab %}
{% endtabs %}
### Setup Logic
{% tabs %}
{% tab title="Bubble.io Plugin" %}
#### \[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.
{% endtab %}
{% tab title="JavaScript SDK" %}
```javascript
// ============================================================================
// 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 ---
```
{% endtab %}
{% tab title="npm Package" %}
```javascript
'use client';
import { useNatively } from 'natively';
export default function DebugButton() {
const natively = useNatively();
return (
);
}
```
{% endtab %}
{% tab title="AI Agents" %}
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
{% hint style="warning" %}
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".
{% endhint %}
{% endtab %}
{% endtabs %}
### 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 ``, 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.
[^1]: Replace this placeholder
