> 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/how-to-get-started.md).

# How to get started?

Everything you need to integrate the Natively JavaScript SDK or Bubble plugin into your project.

Natively provides several ways to integrate native features into your web app: the **JavaScript SDK** for loading via CDN script tag, **Bubble plugin** for no-code Bubble apps, **NPM package** for framework-based projects like React or Next.js, and support for **AI-powered editors** like Lovable, Base44, and Replit. This page covers the global setup and configuration that applies across all features. For feature-specific implementation, refer to the individual feature pages.

{% tabs %}
{% tab title="Bubble.io Plugin" %}
The fastest way to add native features to your Bubble app without writing any code.

#### **Installation**

* Navigate to the **Plugins** tab in your Bubble editor.
* Search for [Natively](https://bubble.io/plugin/natively---fast-mobile-app-wrapper-1654595882459x381599056563798000) and click **Install**.

<figure><img src="https://3352617162-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F90tV7pYflEQdiAr2VfWu%2Fuploads%2FIn6GrYUzjDiDwS2kLeg6%2Fnatively_bubble_plugin.png?alt=media&amp;token=fde581cd-173c-43f1-97bb-e01b67b69354" alt=""><figcaption></figcaption></figure>

#### **Configuration (Headers)**

The **mode** field in the plugin settings controls environment-specific behavior:

* `debug` - enables detailed error alerts and console logs. Recommended during development.
* `preview` - Required for testing Push Notifications within the [Natively Preview app](/natively-platform/preview.md). Remove this tag before testing your own build.

#### **Configuration (API Keys)**

* `onesignal_appId` - links your mobile app to your specific OneSignal project to enable device registration.
* `onesignal_apiKey` - authorizes your Bubble web app to trigger [push notifications](/natively-platform/features/notifications/onesignal-push-notifications.md) via OneSignal.
* `revenuecat_apiKey` - Allows your Bubble web app to verify purchases and sync subscription statuses with RevenueCat ([In-app purchases](/hidden-pages/in-app-purchases.md)).

<figure><img src="https://3352617162-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F90tV7pYflEQdiAr2VfWu%2Fuploads%2F6AYBdHUh4kPSRO1zgehO%2Fnatively_bubble_plugin_settings.png?alt=media&amp;token=bc20a184-e201-495f-806d-f303975cedb3" alt=""><figcaption></figcaption></figure>

Explore our Example App to see a full configuration of the Natively plugin. Use this sandbox to inspect functional workflows, element states, and API setups.

* Editor Link: [Natively QA Sandbox](https://bubble.io/page?name=index\&id=nativelyqa\&tab=tabs-1)
* Credentials: `Username: 1` / `Password: 1`

{% hint style="warning" %}
Avoid calling **Get** actions (like getting Device Info) on Page Load. The Natively plugin needs a few milliseconds to inject into your site. Use a slight delay or trigger actions based on user interaction to ensure the plugin is active.
{% endhint %}

{% hint style="warning" %}
Plugin elements must be set to **Visible on page load** to initialize correctly. Place them directly on the page root - not inside hidden containers such as Popups, Floating Groups, Group Focus elements, or Repeating Groups. To hide an element from your UI, set its dimensions to **0x0 px**.
{% endhint %}
{% endtab %}

{% tab title="JavaScript SDK" %}
Include the Natively SDK to bridge the gap between your web code and the mobile OS. Add the following to your `<head>` tag:

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

  <script>
    function nativelyOnLoad() {
      // The SDK is now successfully injected into the global window object.

      // --- DEBUG MODE ---
      // Set to TRUE during development: Shows native OS alerts if an SDK error occurs.
      // Set to FALSE or not included in production: Prevents users from seeing raw error messages.
      window.natively.setDebug(true);

      console.log("✅ Natively SDK loaded successfully.");

      // Add any other automatic initializations here:
      // e.g., Check permissions, initialize analytics, or setup your audio player.
    }
  </script>
</head>
```

{% hint style="info" %}
You can target a specific SDK version by modifying the version number in the CDN URL (e.g., `2.26.0`).

* Standard Syntax: `https://cdn.jsdelivr.net/npm/natively@VERSION_NUMBER/natively-frontend.min.js`
* To ensure you are using the most up-to-date features, refer to the [Natively GitHub Repository](https://github.com/buildnatively/js-sdk/releases) for the latest version number.
  {% endhint %}
  {% endtab %}

{% tab title="npm Package" %}
**Installation**

Install the Natively package via npm.

```bash
npm install natively@">=2.26.0"
```

**Usage**&#x20;

```typescript
import { NativelyInfo, useNatively } from 'natively';

// useNatively() is a safe React wrapper around window.natively
const natively = useNatively();

// All Natively SDK classes work the same as with the CDN approach
const info = new NativelyInfo();
const browserInfo = info.browserInfo();
```

{% hint style="danger" %}
The Natively SDK relies on the browser's `window` object and cannot run server-side. If you are using a framework with server-side rendering (Next.js, Nuxt, SvelteKit, Remix, etc.), ensure that Natively code only runs on the client side. In Next.js App Router, declare `'use client';` at the top of any file that uses the Natively SDK.
{% endhint %}

```typescript
'use client'; // <--- CRITICAL: Natively cannot be executed on the server-side 

import { NativelyInfo, useNatively } from 'natively';

export default function NativeDashboard() {
  const natively = useNatively();
  const info = new NativelyInfo();
  const browserInfo = info.browserInfo();

  const handleOpenConsole = () => {
    if (browserInfo.isNativeApp) {
      natively.openConsole();
    } else {
      console.warn("Console command ignored: You are viewing this in a standard web browser.");
    }
  };

  return (
    <div>
      <p>Running inside Native App: <strong>{browserInfo.isNativeApp ? "✅ True" : "❌ False"}</strong></p>
      <button onClick={handleOpenConsole}>Open Natively Debug Console</button>
    </div>
  );
}
```

Example project: [Next.js boilerplate](https://github.com/romanfurman6/nextjs-boilerplate)

{% hint style="info" %}
You can target a specific version by modifying the version number (e.g., `2.26.0`).

* Standard Syntax: `npm install natively@">=VERSION_NUMBER"`
* To ensure you are using the most up-to-date features, refer to the [Natively GitHub Repository](https://github.com/buildnatively/js-sdk/releases) for the latest version number.
  {% endhint %}
  {% endtab %}

{% tab title="AI Agents" %}
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
```

{% endtab %}
{% endtabs %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.buildnatively.com/guides/integration/how-to-get-started.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.