Vizbl iOS SDK

Vizbl iOS SDK is an augmented reality SDK that allows you to embed a fully interactive AR scene into your app and place 3D objects created in Vizbl into the real world.

The SDK is designed for simple integration:

you provide an object identifier through tinuuid
you present ARView
the SDK handles AR, placement, interaction, and user guidance

A demo project is available at github.com/VIZBL/vizbl-ios-demo.

Minimal integration

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

Object identifiers

`tinuuid`

tinuuid is the unique identifier of a Vizbl object.

You copy it directly from the Vizbl dashboard.

try await controller.add(tinuuid: "your-tinuuid", hid: nil)

`hid`

hid is the identifier of a material variant.

You copy it from the Vizbl dashboard.

try await controller.add(
    tinuuid: "your-tinuuid",
    hid: "material-id"
)

If hid is not provided, the default material is used.

AR lifecycle

AR starts automatically when ARView is created
AR closes through the built-in SDK UI
no manual start or stop calls are required

Placement mechanics

Placement behavior is defined by the object configuration in Vizbl.

Supported mechanics:

floor
all surfaces
wall
ceiling
carpet and floor covering with segmentation

Behavior is handled automatically by the SDK.

Notes

ceiling placement without LiDAR uses the built-in manual marking flow
carpet placement uses segmentation-based placement mode

Adding objects

try await controller.add(tinuuid: "your-tinuuid", hid: nil)

Behavior:

placement mode starts
a surface is detected
the object is placed at screen center

Multiple objects

calling add(...) again starts a new placement
each object is placed independently
all objects remain in the scene

Users can:

select any object
move, rotate, and scale objects independently

Replace vs add

`add`

starts placement flow
creates a new object

`replace`

try await controller.replace(
    replacing: existingId,
    withTinuuid: "new-tinuuid",
    hid: nil
)

replaces an existing object
keeps its position and transform

Removing objects

Remove selected

if let id = controller.selectedPlacedId {
    controller.remove(id: id)
}

Remove all

controller.removeAll()

Interaction

Configure interaction through ARObjectConfiguration.

ARObjectConfiguration(
    allowsTapToSelect: true,
    allowsMove: true,
    allowRotation: true,
    allowScale: true
)

User gestures:

tap - select
drag - move
pinch - scale
rotate gesture - rotate

Materials and colors

If an object has materials:

the user can switch materials directly in AR
no SDK calls are required
material selection is handled entirely by the SDK

Scene state

Use these properties to sync your UI.

controller.placedObjects
controller.selectedPlacedId

Overlay UI

The SDK provides overlay regions:

add
primary
secondary

You can use:

your own UI
SDK buttons such as AddButton, BuyButton, and FavoriteButton

Example with custom UI

struct ContentView: View {
    @StateObject private var controller = ARViewController(configuration: .default)

    var body: some View {
        ZStack {
            ARView(controller: controller)

            VStack {
                Spacer()

                HStack {
                    Button("Add") {
                        Task {
                            try? await controller.add(tinuuid: "example", hid: nil)
                        }
                    }

                    Button("Remove") {
                        if let id = controller.selectedPlacedId {
                            controller.remove(id: id)
                        }
                    }
                }
                .padding()
            }
        }
    }
}

Overview