🏅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.

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 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. 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 via OneSignal.

• revenuecat_apiKey - Allows your Bubble web app to verify purchases and sync subscription statuses with RevenueCat (In-app purchases).

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

• Credentials: Username: 1 / Password: 1

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.

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.

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:

<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>

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 for the latest version number.

npm Package

Installation

Install the Natively package via npm.

npm install natively@">=2.26.0"

Usage

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();

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.

'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

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 for the latest version number.

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