Navigation, minimap, and deep links

Destination-first navigation

GraffityARMode.Navigation is the default. The SDK opens a full-screen destination map before creating the AR scene. Once the user selects a destination, AR/VPS starts and route guidance begins after localization and section data loading.

import android.content.Context
import tech.graffity.android.arcloud.publicapi.*
 
fun makeVenueNavigation(context: Context, accessToken: String): GraffityARCloudSDK {
    val configuration = GraffityARCloudConfiguration.Builder(accessToken)
        .mode(GraffityARMode.Navigation)
        .minimap(true)
        .build()
    return GraffityARCloudSDK(context, configuration)
}

Attach a factory-created view or fragment as in the quick start. Grant camera and precise location permissions first. The picker uses a live coordinate or initialLocation seed; without a coordinate it cannot perform nearby-venue lookup.

Docked minimap

.minimap(true) enables a display-only floor map with live position and route. It defaults to false, appears only when localized with an active resolved route, and is honored only in Navigation.

The destination picker is independent of the minimap. Disabling the minimap still leaves the initial picker in navigation mode. ARContent has no destination UI.

QR codes and app links

Your app parses its incoming URL or QR payload and passes identifiers through GraffityARDeepLink. The SDK does not register Android app links or parse arbitrary URLs for you.

import android.content.Context
import tech.graffity.android.arcloud.publicapi.*
 
fun makeLinkedNavigation(
    context: Context,
    accessToken: String,
    placeId: String,
    sectionId: String,
    poiId: String
): GraffityARCloudSDK {
    val configuration = GraffityARCloudConfiguration.Builder(accessToken)
        .mode(GraffityARMode.Navigation)
        .minimap(true)
        .deepLink(GraffityARDeepLink(
            poiId = poiId,
            placeId = placeId,
            sectionId = sectionId
        ))
        .build()
    return GraffityARCloudSDK(context, configuration)
}

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

The deep link applies to the first picker presentation only. Later presentations let the user choose again. ARContent has no picker to consume it.

Journeys across sections

The SDK routes through authored section transitions to reach destinations on other floors. At a transition it pauses localization and displays instructions; after the user confirms they have crossed, it restarts localization and plans the next leg from the new section.

.preferredTransitionTypeId(id) accepts a venue transition type ID, not a section ID or transport name such as "elevator". The backend honors it only when that type can cover every hop, otherwise it uses the unrestricted shortest path. This preference does not guarantee an accessible route. A preference chosen in the picker takes precedence over the configuration value.

Programmatic navigation

import kotlinx.coroutines.CancellationException
import tech.graffity.android.arcloud.publicapi.*
 
suspend fun navigate(sdk: GraffityARCloudSDK, poiId: String) {
    try {
        sdk.startNavigation(toPoiId = poiId)
    } catch (cancelled: CancellationException) {
        throw cancelled
    } catch (error: GraffityARCloudError) {
        println(error.message)
    }
}
 
fun stopRoute(sdk: GraffityARCloudSDK) {
    sdk.stopNavigation()
}

Call startNavigation after localization and POI loading. It resolves IDs from the active section’s loaded POIs; a blank, unknown, or unavailable ID throws NavigationGraphUnavailable. It does not perform arbitrary cross-section lookup, and the public state has no POI list. Use the picker and deep links for venue-wide selection.

In navigation mode, stopNavigation() clears the journey and returns to the destination picker on the current section.

Progress and arrival

Observe state.navigation or listener events. During a journey, destination ID/name refer to the final destination; action and distances refer to the current leg. ARRIVING can indicate a section transition. Use onNavigationArrived for final arrival.

Unconnected sections produce NavigationRouteUnavailable(destination, fromSection). These values are display names. The SDK offers a recovery action to choose another destination; repeating localization from the same location does not author missing transitions.