Creating a Map

Why initialization is necessary: The SDK requires initialization to set up internal state, configure HTTP caching for map tiles, initialize analytics tracking, and prepare the location system. Without initialization, all SDK operations will fail.

Why parentPlaceId matters: Providing the parent place ID during initialization allows the SDK to pre-load sub-places (stores, floors, etc.) in the background, resulting in faster access when displaying place markers or floor selectors. This is especially important for venues with many sub-places.

First, you need to initialize the library as it follows:


LzSdkManager.initialize(
    context = applicationContext,
    apiKey = "<YOUR_API_KEY>",
    targetParentPlaceId = "<your_place_id>",  // Optional: pre-loads sub-places for faster access
    enableLogging = BuildConfig.DEBUG  // Enable logging for debugging
)

Where targetParentPlaceId refers to the Lazarillo ID related to the place you want to interact with in your app. It also allows to get information about the place, including subplaces related to it.

Next, you have to set up the map configuration before the creation of the map. For that, it’s necessary to use a LazarilloMapConfig object:

Why configuration matters: Map configuration determines the initial camera position, UI controls visibility, styling, and behavior. Proper configuration ensures the map displays correctly and provides the desired user experience.

Key configuration decisions:

parentPlaceId: Automatically centers map and loads place-specific styling (recommended)
zoom limits: Prevent users from zooming too far in/out, maintaining appropriate detail level
limitToRadius: Restricts panning to venue boundaries (useful for venue-specific apps)
trackingConfig: Enables automatic location tracking reactivation after zoom changes (essential for navigation apps)


val lzMapConfig = LazarilloMapConfig()
lzMapConfig.apply {
    parentPlaceId = "<your_place_id>"  // Auto-centers map and loads place styling
    center = LatLng(
        <latitude>,
        <longitude>
    )  // Only used if parentPlaceId is null
    zoom = 17  // Initial zoom level (higher = more zoomed in)
    minZoom = 17.0  // Prevents zooming out too far (maintains detail)
    maxZoom = 20.0  // Prevents zooming in too far (avoids pixelation)
    showCompass = false  // Hide compass if not needed
    limitToRadius = 100.0  // Restrict panning to 100m radius (venue-specific apps)
    locationIcon = "outlined_person" // or baseline_android_24 or any url
    compassIcon = "<url_to_your_compass_icon>"
 
    // Enable automatic location tracking reactivation (important for navigation)
    trackingConfig = TrackingConfig(
        enableReactivation = true,
        reactivationDelayMs = 1000L
    )
}

For more details on LazarilloMapConfig and accessibility, please refer to the API reference documentation and the Accessibility Guide.

Note: To customize accessibility texts, override the string resources (lz_map_zoom_in, lz_map_zoom_out, lz_map_current_location, lz_map_floor_selector) in your app’s strings.xml file. See the Accessibility Guide for details.

Then, create a map through LazarilloMap object as it follows:


val myMap = LazarilloMap(
    id = "my-cool-map",
    config = lzMapConfig,
    passedContext = this@MainFragment.requireContext(),
    inflater = this@MainFragment.layoutInflater,
    this@MainFragment.lifecycleScope,
    positionRepository = null
)

Then the map object must be added to a View. This object must be persistent during the app’s execution because further interactions with the map are called through LazarilloMap.

Here’s a full example of the code that creates the map in an app using Jetpack Compose :


class MainFragment: Fragment(){
    private lateinit var binding: FragmentMainBinding
    private var lzMap : LazarilloMap? = null
 
    override fun onCreateView(
        inflater: LayoutInflater, container: ViewGroup?,
        savedInstanceState: Bundle?
    ): View {
 
        // Bind
        binding = DataBindingUtil.inflate(inflater, R.layout.fragment_main, container, false)
 
        binding.composeView.apply {
            // Dispose of the Composition when the view's LifecycleOwner
            // is destroyed
            setViewCompositionStrategy(ViewCompositionStrategy.DisposeOnViewTreeLifecycleDestroyed)
            setContent {
                // In Compose world
                FeaturesSection(mainViewModel = mainViewModel)
            }
        }
 
        val lzMapConfig = LazarilloMapConfig()
        lzMapConfig.apply {
            parentPlaceId = "cool_place_id"
            center = LatLng(
                0.0,
                0.0
            )
            zoom = 17
            minZoom = 17.0
            maxZoom = 20.0
            showCompass = false
            limitToRadius = 100.0
            locationIcon = "outlined_person" // or baseline_android_24 or any url
            compassIcon =
                "https://link-to-compass.png"
        }
 
 
        lzMap = LazarilloMap(
            id = "my-cool-map",
            config = lzMapConfig,
            passedContext = this@MainFragment.requireContext(),
            inflater = this@MainFragment.layoutInflater,
            this@MainFragment.lifecycleScope,
            positionRepository = null
        ) {
            println("Map ready")
        }
 
        binding.mfMap.addView(lzMap)
 
        // Return view
        return binding.root
    }
 
}