Navigation, minimap, and deep links

Destination-first navigation

Use mode: .navigation (the default) to show the full-screen destination map before AR localization. Selecting a destination starts AR/VPS; route guidance begins after the relevant section data loads.

import GraffityARCloud
 
@MainActor
func makeVenueNavigation(accessToken: String) throws -> GraffityARCloud {
    try GraffityARCloud(configuration: GraffityARCloudConfiguration(
        accessToken: accessToken,
        mode: .navigation,
        minimap: .enabled
    ))
}

Host the SDK using the quick-start pattern. Location authorization and a coordinate are needed for the nearby-venue picker. initialLocation can seed the coordinate while GPS is pending.

Docked minimap

GraffityARMinimapConfiguration.enabled opts into a display-only floor map with live position and route. The default is .disabled. It appears when localization and an active route are available, and is installed only in .navigation. Enabling it in .arContent has no effect.

The initial destination picker and docked minimap are separate. Disabling the minimap does not disable the picker.

QR codes and universal links

Your app parses an incoming URL or QR payload and passes identifiers through GraffityARDeepLink. The SDK does not register your app’s universal links or parse arbitrary URLs for you.

import GraffityARCloud
 
@MainActor
func makeLinkedNavigation(
    accessToken: String,
    placeId: String,
    sectionId: String,
    poiId: String
) throws -> GraffityARCloud {
    let deepLink = GraffityARDeepLink(
        poiId: poiId,
        placeId: placeId,
        sectionId: sectionId
    )
    return try GraffityARCloud(configuration: GraffityARCloudConfiguration(
        accessToken: accessToken,
        mode: .navigation,
        minimap: .enabled,
        deepLink: deepLink
    ))
}

All three IDs are optional. placeId opens a venue, sectionId opens a floor, and poiId selects a POI within the supplied place or section. POI IDs use source prefixes such as default:<uuid> or console:<uuid>, also reported by GraffityARDestination.id.

A deep link applies to the first picker presentation only. Later presentations let the user choose again. In .arContent, there is no picker to consume the deep link.

Journeys across sections

For a destination across sections, the SDK plans a journey through authored transitions. At a floor transition, it pauses AR and shows a transition screen. When the user confirms they have crossed, it restarts localization and plans the remainder from the new section.

preferredTransitionTypeId is a transition type ID from the venue’s authored data, not a floor ID or transport name such as "elevator". The backend honors the type only if it can cover every hop; otherwise it returns the unrestricted shortest path. This preference does not guarantee an accessible route. A preference selected in the picker takes precedence over the configuration value.

Programmatic navigation

import GraffityARCloud
 
@MainActor
func navigate(sdk: GraffityARCloud, poiId: String) async {
    do {
        try await sdk.startNavigation(to: poiId)
    } catch {
        print(error.localizedDescription)
    }
}
 
@MainActor
func stopRoute(sdk: GraffityARCloud) {
    sdk.stopNavigation()
}

Call startNavigation(to:) after localization and POI loading. It looks up the ID in the active section’s loaded POIs; an unknown or not-yet-loaded ID throws .navigationGraphUnavailable. It does not perform arbitrary cross-section destination lookup, and public state exposes no POI list. Use the picker and deep links for venue-wide selection.

stopNavigation() clears active navigation. The built-in Exit control additionally returns to the picker in navigation mode; the public method does not itself reopen the picker.

Observe progress

Use didStartNavigationTo, didArriveAt, and graffityARCloudDidStopNavigation on the delegate, or inspect state.navigation.

During a journey, destinationId and destinationName describe the final destination; action and distanceToDestinationMeters describe the current leg. .arriving can mean reaching a floor transition. Use didArriveAt to recognize final arrival. distanceToNextActionMeters is currently published as nil.

Unconnected sections or unresolved destination data produce .navigationRouteUnavailable(destination:fromSection:). Re-localizing from the same place does not author a missing route. The built-in recovery control lets the user choose another destination.