🏅How to get started?

Quickstart

Integrate Natively into your existing web application to unlock native mobile capabilities. Choose your integration method below to get started.

The fastest way to convert your Bubble web app into a native mobile experience.

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 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 (or similar events). 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.

This plugin's elements must be set to Visible on page load to initialize correctly. It should be placed directly on the page root and not inside hidden containers, such as Popups, Floating Groups, Group Focus elements, or Repeating Groups. To hide the element from your UI, you may set its dimensions to 0x0 px.

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/[email protected]/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.20.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.

Installation

Install the Natively package via npm.

npm install natively@">=2.20.0"

Usage & The 'use client' Rule

If you are using Next.js (App Router), the Natively SDK relies on the browser's window object. Therefore, any component interacting with Natively must be rendered on the client side. You must declare 'use client'; at the very top of your file.

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

import { NativelyInfo, useNatively } from 'natively';

export default function NativeDashboard() {
  // 1. Initialize the Wrapper
  // useNatively() is a safe React wrapper around the standard 'window.natively' object.
  // Use this hook instead of calling window.natively directly in React.
  const natively = useNatively(); 

  // 2. Fetch Device Info
  const info = new NativelyInfo();
  const browserInfo = info.browserInfo();

  // 3. Define Actions
  const handleOpenConsole = () => {
    // Check if we are actually inside the compiled mobile app before firing native commands
    if (browserInfo.isNativeApp) {
        natively.openConsole();
    } else {
        console.warn("Console command ignored: You are viewing this in a standard web browser.");
    }
  };

  // 4. Render UI
  return (
    <div style={{ padding: '20px', fontFamily: 'sans-serif' }}>
      <h2>📱 App Environment Status</h2>
      
      <p>
        Running inside Native App: 
        <strong> {browserInfo.isNativeApp ? "✅ True" : "❌ False"}</strong>
      </p>
      
     <button 
  onClick={handleOpenConsole}
  style={{ 
    padding: '12px 24px', 
    backgroundColor: '#FD734B', 
    color: '#FFFFFF', 
    borderRadius: '8px', 
    border: 'none', 
    cursor: 'pointer',
    fontFamily: '"Inter", sans-serif',
    fontWeight: 700,
    fontSize: '16px'
  }}
>
  Open Natively Debug Console
</button>
    </div>
  );
}

Example project: https://github.com/romanfurman6/nextjs-boilerplate

You can target a specific version by modifying the version number (e.g., 2.20.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.

PreviousIntegration (Native Features)NextAdMob Integration Guide

Last updated 18 days ago

hashtagQuickstart

Quickstart