# Core Concepts Android Core Concepts [#android-core-concepts] This page summarizes the main ideas used by Vizbl Android SDK integrations. tinuuid [#tinuuid] `tinuuid` is the Vizbl object identifier. Your app copies it from the object's page in `connection.vizbl.com` and passes it to the SDK when adding an object. ```kotlin ARObjectIdentifier.Tinuuid("your-tinuuid") ``` Material ID [#material-id] Material ID selects a material for the object. In the Android API, this parameter is named `materialId`; in Vizbl content, it corresponds to `hid`. If `materialId` is `null`, the SDK loads the default material. AR scene [#ar-scene] `VizblARScene` is the Composable that renders the AR scene. The scene starts the AR session, shows guidance, and displays the built-in AR controls. AR controller [#ar-controller] `VizblARController` is the control surface for the scene. Use it to add, replace, remove, pause, resume, or dismiss AR content. ```kotlin controller.add(model) controller.remove(instanceId) controller.removeAll() controller.pauseSession() controller.resumeSession() controller.dismiss() ``` Placement [#placement] Placement behavior comes from the object configuration in Vizbl. The current mobile SDK supports floor, wall, and ceiling placement. Carpet and floor covering placement are planned for a future mobile SDK update. The SDK handles surface detection, user guidance, and placing the object at the screen center during the placement flow. Interaction [#interaction] Interaction can be configured through `ARObjectConfiguration`. ```kotlin controller.add(model) { allowsTapToSelected(true) allowsMove(true) allowRotation(true) } ``` Common gestures include tap to select, drag to move, and rotate to rotate. Scene state [#scene-state] The controller exposes scene state that your app can use to sync custom UI. ```kotlin controller.placedObjects controller.selectedInstanceId controller.lastAddedInstanceId ``` Built-in AR controls [#built-in-ar-controls] Use `VizblActionHandler` when your app needs to react to built-in AR control actions. ```kotlin override fun onAddObjectClick() {} override fun onBuyClick(url: String, previewUrl: String?) {} override fun onCloseClick() {} override fun onConfirmClick() {} override fun onDeleteClick() {} override fun onQRScanned(url: String) {} override fun onScreenshotClick(view: SurfaceView?) {} ``` Responsibility split [#responsibility-split] The SDK owns AR rendering, placement, guidance, interaction, material UI, and built-in AR controls. Your app owns product selection, catalog UI, checkout, navigation, analytics, and any custom business logic around the AR experience. # Overview Overview [#overview] Vizbl Android SDK is an augmented reality toolkit for embedding Vizbl-powered product visualization into native Android applications. Instead of building AR rendering, placement guidance, object controls, and material selection from scratch, your app presents the SDK AR scene and passes the object identifier that should be shown in AR. How it works [#how-it-works] Each 3D object in Vizbl has a `tinuuid`. Your app gets that value from the object's page in `connect.vizbl.com` and sends it to the SDK. The SDK loads the object, starts placement, guides the user, and manages interaction after the object is placed. The app remains responsible for product selection, catalog UI, checkout, analytics, account logic, and any custom business flow around AR. What the SDK handles [#what-the-sdk-handles] * AR rendering. * Placement guidance. * Object selection. * Move and rotate gestures. * Material selection UI. * Built-in AR controls. What your app handles [#what-your-app-handles] * Choosing which product to show. * Passing the correct `tinuuid`. * Passing an optional Material ID (`materialId` in the Android API). * Presenting custom product UI outside AR. * Handling built-in AR control actions such as buy, close, add, confirm, delete, screenshot, or QR scan. * Managing app navigation and business logic. Good fit [#good-fit] Vizbl Android SDK is useful for ecommerce, product catalogs, showrooms, and any Android app where users need to preview 3D products in their real environment before taking the next step. SDK repository [#sdk-repository] [https://github.com/VIZBL/vizbl-android-sdk](https://github.com/VIZBL/vizbl-android-sdk) # Overview Overview [#overview] Vizbl Android SDK is an augmented reality toolkit for embedding Vizbl-powered product visualization into native Android applications. Instead of building AR rendering, placement guidance, object controls, and material selection from scratch, your app presents the SDK AR scene and passes the object identifier that should be shown in AR. How it works [#how-it-works] Each 3D object in Vizbl has a `tinuuid`. Your app gets that value from the object's page in `connection.vizbl.com` and sends it to the SDK. The SDK loads the object, starts placement, guides the user, and manages interaction after the object is placed. The app remains responsible for product selection, catalog UI, checkout, analytics, account logic, and any custom business flow around AR. What the SDK handles [#what-the-sdk-handles] * AR rendering. * Placement guidance. * Object selection. * Move and rotate gestures. * Material selection UI. * Built-in AR controls. What your app handles [#what-your-app-handles] * Choosing which product to show. * Passing the correct `tinuuid`. * Passing an optional Material ID (`materialId` in the Android API). * Presenting custom product UI outside AR. * Handling built-in AR control actions such as buy, close, add, confirm, delete, screenshot, or QR scan. * Managing app navigation and business logic. Good fit [#good-fit] Vizbl Android SDK is useful for ecommerce, product catalogs, showrooms, and any Android app where users need to preview 3D products in their real environment before taking the next step. SDK repository [#sdk-repository] [https://github.com/VIZBL/vizbl-android-sdk](https://github.com/VIZBL/vizbl-android-sdk) # Quick Start Android Quick Start [#android-quick-start] This guide shows the fastest path from an Android project to a minimal Vizbl AR scene. Before you start [#before-you-start] You need: * Android Studio. * A physical Android device with AR support. * Camera permission in the app. * GitHub Packages access for the SDK. * A Vizbl object `tinuuid` from `connection.vizbl.com`. 1\. Add the SDK repository [#1-add-the-sdk-repository] Add the GitHub Packages repository to `settings.gradle.kts`. ```kotlin dependencyResolutionManagement { repositories { google() mavenCentral() maven { url = uri("https://maven.pkg.github.com/VIZBL/vizbl-android-sdk") credentials { username = "YOUR_GITHUB_USERNAME" password = "YOUR_GITHUB_TOKEN" } } } } ``` 2\. Add the dependency [#2-add-the-dependency] Add the SDK dependency to your app module. ```kotlin dependencies { implementation("com.vizbl:sdk:VERSION") } ``` Replace `VERSION` with the SDK version provided by Vizbl. 3\. Add your object tinuuid [#3-add-your-object-tinuuid] Open your object in `connection.vizbl.com` and copy its `tinuuid`. Replace `your-tinuuid` in the example below with that value before running the app. The SDK needs a real `tinuuid` to load your object. 4\. Create a minimal AR screen [#4-create-a-minimal-ar-screen] Render the AR scene (`VizblARScene`), wait for the AR controller (`VizblARController`), then add the object when the AR session is ready. ```kotlin @Composable fun ARScreen() { var controller by remember { mutableStateOf(null) } val scope = rememberCoroutineScope() VizblARScene( onControllerReady = { controller = it }, onSessionReady = { val model = ARObjectReference.Single( id = ARObjectIdentifier.Tinuuid("your-tinuuid"), materialId = null ) scope.launch { controller?.add(model) } } ) } ``` 5\. Run on a device [#5-run-on-a-device] Build the app and run it on a physical AR-compatible Android device. When the AR scene opens, the SDK starts the AR flow and guides the user through placement. Demo project [#demo-project] A working Android demo project is available on GitHub: [https://github.com/VIZBL/vizbl-android-demo](https://github.com/VIZBL/vizbl-android-demo) Next steps [#next-steps] * Pass Material ID (`materialId`) when you want to open a specific material. * Add a `VizblActionHandler` when your app needs to respond to built-in AR control actions such as close, buy, add, confirm, delete, screenshot, or QR scan. * Use `controller.remove(...)`, `controller.removeAll()`, or `controller.replace(...)` when your app needs object management controls. # Core Concepts iOS Core Concepts [#ios-core-concepts] This page summarizes the main ideas used by Vizbl iOS SDK integrations. tinuuid [#tinuuid] `tinuuid` is the Vizbl object identifier. Your app copies it from the object's page in `connection.vizbl.com` and passes it to the SDK when adding an object. ```swift try await controller.add(tinuuid: "your-tinuuid", hid: nil) ``` Material ID [#material-id] Material ID selects a material for the object. In the iOS API, this parameter is named `hid`. If `hid` is `nil`, the SDK loads the default material. AR scene [#ar-scene] `ARView` renders the AR scene. When it is presented, the SDK starts the AR session, shows guidance, and displays the configured built-in AR controls. AR controller [#ar-controller] `ARViewController` manages the AR scene. Use it to add, replace, remove, or inspect placed objects. ```swift try await controller.add(tinuuid: "your-tinuuid", hid: nil) if let id = controller.selectedPlacedId { controller.remove(id: id) } controller.removeAll() ``` Placement [#placement] Placement behavior comes from the object configuration in Vizbl. The current mobile SDK supports floor, wall, and ceiling placement. Carpet and floor covering placement are planned for a future mobile SDK update. The SDK handles surface-specific guidance and placement behavior automatically. Interaction [#interaction] Interaction can be configured through `ARObjectConfiguration`. ```swift ARObjectConfiguration( allowsTapToSelect: true, allowsMove: true, allowRotation: true, allowScale: true, scaleFactor: 1.0 ) ``` Common gestures include tap to select, drag to move, pinch to scale, and rotate gesture to rotate. Scene state [#scene-state] The controller exposes scene state that your app can use to sync custom UI. ```swift controller.placedObjects controller.selectedPlacedId ``` Built-in AR controls [#built-in-ar-controls] The SDK provides built-in AR controls for common AR actions. On iOS, these controls are configured through `AROverlayControls`; your app can use SDK-provided controls such as `AddButton`, `BuyButton`, and `FavoriteButton`, or build custom SwiftUI controls around the AR scene. Responsibility split [#responsibility-split] The SDK owns AR rendering, placement, guidance, interaction, material UI, and built-in AR control support. Your app owns product selection, catalog UI, checkout, navigation, analytics, and any custom business logic around the AR experience. # Overview Overview [#overview] Vizbl iOS SDK is an augmented reality toolkit for embedding Vizbl-powered product visualization into native iOS applications. Instead of building AR rendering, placement guidance, object controls, and material selection from scratch, your app presents the SDK AR scene and passes the object identifier that should be shown in AR. How it works [#how-it-works] Each 3D object in Vizbl has a `tinuuid`. Your app gets that value from the object's page in `connect.vizbl.com` and sends it to the SDK. The SDK loads the object, starts placement, guides the user, and manages interaction after the object is placed. The app remains responsible for product selection, catalog UI, checkout, analytics, account logic, and any custom business flow around AR. What the SDK handles [#what-the-sdk-handles] * AR rendering. * Placement guidance. * Object selection. * Move, rotate, and scale gestures. * Material selection UI. * Built-in AR controls. What your app handles [#what-your-app-handles] * Choosing which product to show. * Passing the correct `tinuuid`. * Passing an optional Material ID (`hid` in the iOS API). * Presenting custom product UI outside AR. * Handling navigation and business logic. * Adding custom AR controls when needed. Good fit [#good-fit] Vizbl iOS SDK is useful for ecommerce, product catalogs, showrooms, and any iOS app where users need to preview 3D products in their real environment before taking the next step. SDK repository [#sdk-repository] [https://github.com/VIZBL/vizbl-ios-sdk](https://github.com/VIZBL/vizbl-ios-sdk) # Overview Overview [#overview] Vizbl iOS SDK is an augmented reality toolkit for embedding Vizbl-powered product visualization into native iOS applications. Instead of building AR rendering, placement guidance, object controls, and material selection from scratch, your app presents the SDK AR scene and passes the object identifier that should be shown in AR. How it works [#how-it-works] Each 3D object in Vizbl has a `tinuuid`. Your app gets that value from the object's page in `connection.vizbl.com` and sends it to the SDK. The SDK loads the object, starts placement, guides the user, and manages interaction after the object is placed. The app remains responsible for product selection, catalog UI, checkout, analytics, account logic, and any custom business flow around AR. What the SDK handles [#what-the-sdk-handles] * AR rendering. * Placement guidance. * Object selection. * Move, rotate, and scale gestures. * Material selection UI. * Built-in AR controls. What your app handles [#what-your-app-handles] * Choosing which product to show. * Passing the correct `tinuuid`. * Passing an optional Material ID (`hid` in the iOS API). * Presenting custom product UI outside AR. * Handling navigation and business logic. * Adding custom AR controls when needed. Good fit [#good-fit] Vizbl iOS SDK is useful for ecommerce, product catalogs, showrooms, and any iOS app where users need to preview 3D products in their real environment before taking the next step. SDK repository [#sdk-repository] [https://github.com/VIZBL/vizbl-ios-sdk](https://github.com/VIZBL/vizbl-ios-sdk) # Quick Start iOS Quick Start [#ios-quick-start] This guide shows the fastest path from an Xcode project to a minimal Vizbl AR scene. Before you start [#before-you-start] You need: * Xcode. * A physical iOS device. * iOS 18+ for `VizblKit`. * Camera permission in the app. * A Vizbl object `tinuuid` from `connection.vizbl.com`. 1\. Add the Swift Package [#1-add-the-swift-package] In Xcode: 1. Open `File -> Add Package Dependencies`. 2. Enter the package URL. ```text https://github.com/VIZBL/vizbl-ios-sdk ``` 3. Select a version rule, for example `Up to Next Major`. 4. Add the `VizblKit` product to your app target. 2\. Import the SDK [#2-import-the-sdk] ```swift import VizblKit ``` 3\. Add camera permission text [#3-add-camera-permission-text] If your app does not already include camera usage text, add `NSCameraUsageDescription` to `Info.plist`. ```xml NSCameraUsageDescription This app uses the camera to place products in augmented reality. ``` 4\. Add your object tinuuid [#4-add-your-object-tinuuid] Open your object in `connection.vizbl.com` and copy its `tinuuid`. Replace `your-tinuuid` in the example below with that value before running the app. The SDK needs a real `tinuuid` to load your object. 5\. Create a minimal AR scene [#5-create-a-minimal-ar-scene] Create an AR controller (`ARViewController`), present the AR scene (`ARView`), and add an object by `tinuuid`. ```swift import SwiftUI import VizblKit struct ContentView: View { @StateObject private var controller = ARViewController(configuration: .default) var body: some View { ARView(controller: controller) .onAppear { Task { try? await controller.add(tinuuid: "your-tinuuid", hid: nil) } } } } ``` 6\. Run on a device [#6-run-on-a-device] Build the app and run it on a physical iOS device. When the AR scene opens, the SDK starts the AR flow and guides the user through placement. Demo project [#demo-project] A working iOS demo project is available on GitHub: [https://github.com/VIZBL/vizbl-ios-demo](https://github.com/VIZBL/vizbl-ios-demo) Next steps [#next-steps] * Pass Material ID (`hid`) when you want to open a specific material. * Add custom AR controls when your app needs product actions inside AR. * Use controller methods such as `remove(id:)`, `removeAll()`, or `replace(...)` when your app needs object management controls. # Overview Packages [#packages] * `@neurodyn/react-model-viewer` * `@neurodyn/model-viewer` # Overview Packages [#packages] * `@neurodyn/react-room-viewer` * `@neurodyn/room-viewer` # JavaScript Use a Package Manager [#use-a-package-manager] Install [#install] ```bash pnpm add @neurodyn/model-viewer ``` ```bash npm install @neurodyn/model-viewer ``` ```bash yarn add @neurodyn/model-viewer ``` ```bash bun add @neurodyn/model-viewer ``` Create a Trigger [#create-a-trigger] Model Viewer reads configuration from data attributes on the element you bind. The same markup can be used with the package manager, global, and embed integrations. ```html ``` Initialize `ModelViewerDialog`: ```ts import { ModelViewerDialog } from '@neurodyn/model-viewer' const viewer = new ModelViewerDialog('[data-neurodyn-model-viewer-dialog]') // Later, when the triggers are no longer needed: // viewer.destroy() ``` Use Model Viewer from CDN [#use-model-viewer-from-cdn] You can use Model Viewer directly from a CDN without installing a package. Use the global build when you want to initialize triggers yourself, or the embed build when the script should initialize matching triggers automatically. Global Build [#global-build] The global build exposes `ModelViewerDialog`, so you can choose exactly which elements should open the dialog. ```html ``` Full example: ```html ``` Embed Build [#embed-build] The embed build initializes itself and listens for clicks on elements with `data-neurodyn-model-viewer-dialog`. ```html ``` Next steps [#next-steps] * Read the [JavaScript API reference](/docs/model-viewer/reference/javascript). # React Use this package with react\@19 and react-dom\@19. For React 18 or earlier, use @neurodyn/model-viewer. Install [#install] Add the React package to your application with your preferred package manager. ```bash pnpm add @neurodyn/react-model-viewer ``` ```bash npm install @neurodyn/react-model-viewer ``` ```bash yarn add @neurodyn/react-model-viewer ``` ```bash bun add @neurodyn/react-model-viewer ``` Render the Dialog [#render-the-dialog] `ModelViewerDialog` is a controlled component. Render it from a client component and pass the object data that should open in the viewer. ```tsx 'use client' import { useState } from 'react' import { ModelViewerDialog } from '@neurodyn/react-model-viewer' export function App() { const [open, setOpen] = useState(false) return ( <> ) } ``` Next steps [#next-steps] * Read the [React API reference](/docs/model-viewer/reference/react). # JavaScript Options [#options] Data Attributes [#data-attributes] | Attribute | Required | Default | Description | | ------------------------------------ | -------- | -------------- | --------------------------------------------- | | `data-neurodyn-model-viewer` | No | - | Marks a viewer container for the embed build. | | `data-neurodyn-model-viewer-dialog` | No | - | Marks a dialog trigger for the embed build. | | `data-neurodyn-model-viewer-tinuuid` | Yes | - | The unique identifier of the object. | | `data-neurodyn-model-viewer-api-key` | Yes | - | Public API key sent as `x-api-key`. | | `data-neurodyn-model-viewer-hid` | No | First material | The identifier of a material variant. | # React `ModelViewerLayout` [#modelviewerlayout] ```ts type ModelViewerLayout = 'default' | 'model' ``` `ModelViewerBackground` [#modelviewerbackground] ```ts type ModelViewerBackground = 'default' | 'transparent' ``` `ModelViewer` [#modelviewer] `ModelViewerDialog` [#modelviewerdialog] # JavaScript Use a Package Manager [#use-a-package-manager] Install [#install] ```bash pnpm add @neurodyn/room-viewer ``` ```bash npm install @neurodyn/room-viewer ``` ```bash yarn add @neurodyn/room-viewer ``` ```bash bun add @neurodyn/room-viewer ``` Create a Trigger [#create-a-trigger] Room Viewer reads configuration from data attributes on the element you bind. The same markup can be used with the package manager, global, and embed integrations. ```html ``` Initialize `RoomViewerDialog`: ```ts import { RoomViewerDialog } from '@neurodyn/room-viewer' const viewer = new RoomViewerDialog('[data-neurodyn-room-viewer-dialog]') // Later, when the triggers are no longer needed: // viewer.destroy() ``` Use Room Viewer from CDN [#use-room-viewer-from-cdn] You can use Room Viewer directly from a CDN without installing a package. Use the global build when you want to initialize triggers yourself, or the embed build when the script should listen for matching triggers automatically. Global Build [#global-build] The global build exposes `RoomViewerDialog`, so you can choose exactly which elements should open the dialog. ```html ``` Full example: ```html ``` Embed Build [#embed-build] The embed build initializes itself and listens for clicks on elements with `data-neurodyn-room-viewer-dialog`. ```html ``` Next steps [#next-steps] * Read the [JavaScript API reference](/docs/room-viewer/reference/javascript). # React Use this package with react\@19 and react-dom\@19. For React 18 or earlier, use @neurodyn/room-viewer. Install [#install] Add the React package to your application with your preferred package manager. ```bash pnpm add @neurodyn/react-room-viewer ``` ```bash npm install @neurodyn/react-room-viewer ``` ```bash yarn add @neurodyn/react-room-viewer ``` ```bash bun add @neurodyn/react-room-viewer ``` Render the Dialog [#render-the-dialog] `RoomViewerDialog` is a controlled component. Render it from a client component and pass the resource data that should open in the viewer. ```tsx 'use client' import { useState } from 'react' import { RoomViewerDialog } from '@neurodyn/react-room-viewer' export function App() { const [open, setOpen] = useState(false) return ( <> ) } ``` Next steps [#next-steps] * Read the [React API reference](/docs/room-viewer/reference/react). # JavaScript `RoomViewerResourceType` [#roomviewerresourcetype] ```ts type RoomViewerResourceType = 'wallart' | 'rugs' | 'flooring' ``` `RoomViewerDimensionUnit` [#roomviewerdimensionunit] ```ts type RoomViewerDimensionUnit = 'm' | 'cm' | 'in' ``` `RoomViewerDisplayUnit` [#roomviewerdisplayunit] ```ts type RoomViewerDisplayUnit = 'cm' | 'in' ``` Options [#options] Data Attributes [#data-attributes] | Attribute | Required | Default | Description | | ------------------------------------------ | -------- | ----------- | --------------------------------------------------------------- | | `data-neurodyn-room-viewer-dialog` | No | - | Marks an element for the embed build. | | `data-neurodyn-room-viewer-type` | Yes | - | Resource type. Use `wallart`, `rugs`, or `flooring`. | | `data-neurodyn-room-viewer-name` | Yes | - | Title shown in the dialog header. | | `data-neurodyn-room-viewer-src` | No | - | Wall-art image URL. Used when `type` is `wallart`. | | `data-neurodyn-room-viewer-tinuuid` | No | - | The object's tinuuid. Used when `type` is `rugs` or `flooring`. | | `data-neurodyn-room-viewer-width` | No | - | Wall-art width. Used when `type` is `wallart`. | | `data-neurodyn-room-viewer-height` | No | - | Wall-art height. Used when `type` is `wallart`. | | `data-neurodyn-room-viewer-dimension-unit` | No | `m` | Unit used by wall-art width and height. Use `m`, `cm`, or `in`. | | `data-neurodyn-room-viewer-display-unit` | No | `cm` | Unit used to display UI measurements. Use `cm` or `in`. | | `data-neurodyn-room-viewer-language` | No | User locale | UI language override. Use `en` or `ru`. | | `data-neurodyn-room-viewer-api-key` | No | - | Public API key sent as `x-api-key`. | | `data-neurodyn-room-viewer-source` | No | `default` | Backend source mode. Use `default` or `shopify`. | # React `RoomViewerResourceType` [#roomviewerresourcetype] ```ts type RoomViewerResourceType = 'wallart' | 'rugs' | 'flooring' ``` `RoomViewerDimensionUnit` [#roomviewerdimensionunit] ```ts type RoomViewerDimensionUnit = 'm' | 'cm' | 'in' ``` `RoomViewerDisplayUnit` [#roomviewerdisplayunit] ```ts type RoomViewerDisplayUnit = 'cm' | 'in' ``` `RoomViewerDialog` [#roomviewerdialog]