> 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?
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**.
#### **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](/guides/integration/push-notifications-onesignal.md) via OneSignal.
* `revenuecat_apiKey` - Allows your Bubble web app to verify purchases and sync subscription statuses with RevenueCat ([In-app purchases](/guides/integration/in-app-purchases.md)).
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 `` tag:
```javascript
```
{% 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**
```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 (
);
}
```
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 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 %}