ℹ️Device Info

Access details about the user's device, app, and runtime environment.

What is Device Info?

Device Info gives your app access to details about the user's device and your app's runtime environment - device model, OS version, app build info, dark mode status, and screen orientation. It also lets you listen for app state changes (foreground/background) and keyboard visibility, and includes an error handler for managing HTTP request failures without showing the default error screen.

For platform detection (iOS, Android, or web), see Browser Info instead.

Prerequisites

This feature is available in all plans. See all plans

Implementation

Choose your integration method below: Bubble.io Plugin (No-Code), JavaScript SDK (Code), or AI Agents (for AI-powered editors like Lovable, Base44, and Replit).

Initialization

Check Plugin

Before starting, verify if the Natively plugin is already installed in your Bubble project.

Open your Bubble editor and navigate to the Plugins tab in the left sidebar.
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.

Check SDK

Before writing any logic, ensure the Natively SDK is correctly installed and up-to-date in your codebase.

Open your project's main HTML file (or header settings) and look for the Natively script tag inside the <head> section.
Install/Update: If missing or outdated, add the following code. You can specify the SDK version in the URL (e.g., @2.26.0).

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

To ensure you are using the most up-to-date version, check the Natively GitHub releases page for the latest version number.

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

Setup Logic

[Element] Natively - Device

Refresh App Info action is called automatically on element load, so device information is available as soon as the element initializes. Avoid adding multiple Natively - Device elements on the same page, as each one sends a request to the device on load.

Events:

App Info received - fires when device and app information is successfully retrieved.
App went foreground - fires when the user opens the app.
App went background - fires when the user minimizes the app without exiting.
Keyboard is visible - fires when the on-screen keyboard appears.
Keyboard is hidden - fires when the on-screen keyboard is dismissed.
Error occurred - fires when an HTTP request fails, and the Set Error Handler action has been previously called on the current page. (Available starting from v. 2.26.0)

States:

Device - device model identifier. (iOS values can be decoded with this list)
OS Version - Android / iOS version.
App Version - your app's build version.
Build Number - your app's build number.
Natively SDK Version - the Natively SDK version in use.
OS Name - "Android" or "iOS".
isDarkMode - Yes / No.
Orientation - "PORTRAIT" or "LANDSCAPE".
Error Code - the HTTP status code of the failed request (e.g. 404, 500).
Error Description - a text description of the error provided by the requester endpoint.
Error Response Data - the raw response body (JSON/Text) returned by the server for the failed HTTP request (if available).

Actions:

Refresh App Info - retrieves the latest device and app information.
Set Error Handler - enables custom error handling for the current page session. When active, the app will not automatically display the native error screen when an HTTP request fails. Instead, it fires the Error occurred event.

How to use the Error Handler

To ensure consistent error handling across your app, place the logic in a Reusable Element (like your Header or a dedicated technical Reusable) that exists on every page.

Place the Natively - Device element inside your Reusable Element.
When Natively - Device's Device state is not empty (this ensures the element is fully initialized) > call the Set Error Handler action.
Create a workflow to handle the error when it happens (the event Error occurred is fired).
The error's details can also be visible in the Debug console.

Device Info

// ============================================================================
// NATIVELY DEVICE INFO - DOCUMENTATION & EXAMPLES
// ============================================================================

// Initialize
const info = new NativelyInfo();

// ============================================================================
// ALL AVAILABLE METHODS
// ============================================================================
// info.getAppInfo(callback)
//   - Retrieves device, OS, and app build information.
//   - Returns the result via callback.
//
// info.app_state(callback)
//   - Listens for app state changes (foreground/background).
//
// info.keyboard_visibility(callback)
//   - Listens for changes in on-screen keyboard visibility.

// ============================================================================
// CALLBACK RESPONSE FIELDS - getAppInfo
// ============================================================================
// resp.device        - Device model (iOS values can be decoded with this list:
//                       https://github.com/pbakondy/ios-device-list/blob/master/devices.json)
// resp.osVersion     - Android/iOS version.
// resp.osName        - "iOS" or "Android".
// resp.buildVersion  - Your app's build version.
// resp.buildNumber   - Your app's build number.
// resp.sdkVersion    - The Natively SDK version in use.
// resp.isDarkMode    - Boolean. true if the device is in dark mode.
// resp.orientation   - "PORTRAIT" or "LANDSCAPE".

// ============================================================================
// CALLBACK RESPONSE FIELDS - app_state
// ============================================================================
// resp.state   - Boolean. true if the app is in the foreground, false if backgrounded.

// ============================================================================
// CALLBACK RESPONSE FIELDS - keyboard_visibility
// ============================================================================
// resp.visible - Boolean. true if the on-screen keyboard is visible, false if hidden.


// --- Device Info. Get App Info Example. Start ---

const app_info_callback = function(resp) {
    console.log(resp.device);       // iPhone14,2
    console.log(resp.osVersion);    // 15.6
    console.log(resp.osName);       // iOS / Android
    console.log(resp.buildVersion); // 1.0.0
    console.log(resp.buildNumber);  // 1
    console.log(resp.sdkVersion);   // 3
    console.log(resp.isDarkMode);   // true/false
    console.log(resp.orientation);  // PORTRAIT / LANDSCAPE
};

info.getAppInfo(app_info_callback);

// --- Device Info. Get App Info Example. End ---


// --- Device Info. App State Example. Start ---

const app_state_callback = function(resp) {
    if (resp.state) {
        console.log("App went foreground");
    } else {
        console.log("App went background");
    }
};

info.app_state(app_state_callback);

// --- Device Info. App State Example. End ---


// --- Device Info. Keyboard Visibility Example. Start ---

const keyboard_visibility_callback = function(resp) {
    if (resp.visible) {
        console.log("Keyboard is visible");
    } else {
        console.log("Keyboard is hidden");
    }
};

info.keyboard_visibility(keyboard_visibility_callback);

// --- Device Info. Keyboard Visibility Example. End ---

Error Handler

// ============================================================================
// NATIVELY ERROR HANDLER - DOCUMENTATION & EXAMPLES
// ============================================================================

// No initialization required — setErrorHandler is available directly
// on the global window.natively object.

// ============================================================================
// ALL AVAILABLE METHODS
// ============================================================================
// window.natively.setErrorHandler(callback)
//   - Suppresses the default native error screen on failed HTTP requests.
//   - Fires the callback instead, letting you handle the error in your own workflow.

// ============================================================================
// CALLBACK RESPONSE FIELDS
// ============================================================================
// resp.code          - HTTP status code of the failed request (e.g. 404, 500, 0).
// resp.description   - Text description of the error (e.g. "Network Request Failed", "Not Found").
// resp.url           - The URL of the failed request.
// resp.type          - "NETWORK_ERROR" or "HTTP_ERROR".
// resp.response_data - The raw response body (usually an Object — stringify it to read it).

// --- Error Handler. Example. Start ---

const error_handler_callback = function(resp) {
    console.log(resp.code);
    console.log(resp.description);
    console.log(resp.url);
    console.log(resp.type);
    console.log(JSON.stringify(resp.response_data));
};

window.natively.setErrorHandler(error_handler_callback);

// --- Error Handler. Example. End ---

AI-powered editors like Lovable, Base44, and Replit use the JavaScript SDK to implement Natively features.

Copy the relevant line below and paste it into your AI agent.

Device Info

[Your feature description] using the Natively Device Info SDK: const info = new NativelyInfo(); // info.getAppInfo(callback) — retrieves device info. resp.device: device model. resp.osVersion: OS version. resp.osName: "iOS" or "Android". resp.buildVersion: app version. resp.buildNumber: build number. resp.sdkVersion: SDK version. resp.isDarkMode: boolean. resp.orientation: "PORTRAIT" or "LANDSCAPE". // info.app_state(callback) — listens for app state changes. resp.state: boolean (true=foreground, false=background). // info.keyboard_visibility(callback) — listens for on-screen keyboard visibility changes. resp.visible: boolean (true=visible, false=hidden). For reference: https://docs.buildnatively.com/guides/integration/device-info

Replace the placeholder at the beginning with a description of what you want to build - for example: "When the app loads, get the device info and display the OS name and app version on the settings page".

Error Handler

[Your feature description] using the Natively Error Handler: // window.natively.setErrorHandler(callback) — suppresses default error screen on HTTP failures. No initialization required. resp.code: HTTP status code. resp.description: error description. resp.url: failed URL. resp.type: "NETWORK_ERROR" or "HTTP_ERROR". resp.response_data: raw response body (stringify to read). For reference: https://docs.buildnatively.com/guides/integration/device-info

Replace the placeholder at the beginning with a description of what you want to build - for example: "Handle HTTP errors silently without showing the native error screen, and display a custom error message instead".

How to use

Reading device info on app load

Call info.getAppInfo() early in your app's initialization, ideally inside nativelyOnLoad(), so device details are available before any conditional logic runs. Store the result rather than calling it repeatedly.

Detect dark mode

Use resp.isDarkMode to apply the correct theme when the app loads. Combine with app_state to re-check when the user returns to the foreground, since they may have changed their system appearance while the app was backgrounded.

Handle orientation changes

Use resp.orientation from getAppInfo() to adjust your layout on load. Note that this is a snapshot at the time of the call - it won't update automatically as the device rotates. Call getAppInfo() again inside app_state if you need to track rotation.

App state: foreground and background

Use resp.state inside app_state to pause or resume activity when the user switches apps. Common use cases include pausing media playback, stopping timers, or refreshing data when the user returns.

Keyboard visibility

Use resp.visible inside keyboard_visibility to adjust your layout when the keyboard appears or disappears - for example, scrolling to a focused input or hiding a bottom navigation bar.

Error Handler - when to use it

Enable the Error Handler when you want to handle HTTP failures gracefully instead of showing the native error screen. Place it in a Reusable Element that exists on every page so it's always active. Use resp.type to distinguish between network failures (NETWORK_ERROR) and server errors (HTTP_ERROR), and resp.code to respond differently to specific status codes like 401 or 500.

Troubleshooting

getAppInfo() returns empty or undefined values

Make sure the call is made after the SDK has fully loaded. Call it inside nativelyOnLoad() or trigger it from a user interaction rather than immediately on page load.

app_state is not firing

The app_state listener needs to be registered after the SDK is loaded. Register it inside nativelyOnLoad() to ensure it's active before any state changes occur.

Orientation is not updating on device rotation

getAppInfo() returns a snapshot of the orientation at the time of the call - it does not update automatically. Call getAppInfo() again inside your app_state callback when the app returns to the foreground to get the latest orientation value.

Keyboard visibility events are not firing

Keyboard visibility is reported through the separate keyboard_visibility method, not app_state. Make sure you've registered a callback with info.keyboard_visibility(callback) and that it's called after the SDK has loaded.

Error Handler is not suppressing the native error screen

Make sure window.natively.setErrorHandler() is called before any HTTP requests are made. Place it in a Reusable Element that loads on every page so it's always active. If it's only called on specific pages, the error screen will still appear on pages where it hasn't been set.

resp.response_data is not readable

resp.response_data is usually an Object - use JSON.stringify(resp.response_data) to convert it to a readable string before logging or displaying it.

PreviousDebug Console NextGeolocation

Last updated 1 month ago