Android Core Concepts

This page summarizes the main ideas used by Vizbl Android SDK integrations.

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.

ARObjectIdentifier.Tinuuid("your-tinuuid")

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

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

VizblARController is the control surface for the scene. Use it to add, replace, remove, pause, resume, or dismiss AR content.

controller.add(model)
controller.remove(instanceId)
controller.removeAll()
controller.pauseSession()
controller.resumeSession()
controller.dismiss()

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 can be configured through ARObjectConfiguration.

controller.add(model) {
    allowsTapToSelected(true)
    allowsMove(true)
    allowRotation(true)
}

Common gestures include tap to select, drag to move, and rotate to rotate.

Scene state

The controller exposes scene state that your app can use to sync custom UI.

controller.placedObjects
controller.selectedInstanceId
controller.lastAddedInstanceId

Built-in AR controls

Use VizblActionHandler when your app needs to react to built-in AR control actions.

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

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.