Accessibility Guide

The Lazarillo SDK is designed to be accessible to all users, including those using screen readers and other assistive technologies. This guide explains the accessibility features available in the SDK and how to customize them.

Overview

The SDK provides accessibility support for all interactive map UI elements:

• Zoom In Button: Increases the map zoom level
• Zoom Out Button: Decreases the map zoom level
• Current Location Button: Centers the map on the user’s current location
• Floor Selector: Allows users to select which building floor to display

All UI elements have proper contentDescription attributes that are read by screen readers (like TalkBack on Android) to describe the purpose of each control.

Default Accessibility Texts

By default, the SDK uses the following accessibility descriptions:

These default texts are defined in the SDK’s string resources and are in English. They follow Android accessibility best practices by being concise yet descriptive.

Customizing Accessibility Texts

You can customize the accessibility texts by overriding the SDK’s string resources in your own strings.xml file. This is the standard Android way to customize strings and supports localization automatically.

Overriding Strings in Your App

Simply create or update your app/src/main/res/values/strings.xml file and define the same string resource names:

<?xml version="1.0" encoding="utf-8"?>
<resources>
    <!-- Override SDK accessibility strings -->
    <string name="lz_map_zoom_in">Increase map zoom level</string>
    <string name="lz_map_zoom_out">Decrease map zoom level</string>
    <string name="lz_map_current_location">Center map on your current location</string>
    <string name="lz_map_floor_selector">Select building floor to display</string>
</resources>

Localization Support

To support multiple languages, create separate strings.xml files for each locale:

English (default): app/src/main/res/values/strings.xml

<string name="lz_map_zoom_in">Zoom in on the map</string>
<string name="lz_map_zoom_out">Zoom out on the map</string>
<string name="lz_map_current_location">Center map on your current location</string>
<string name="lz_map_floor_selector">Select building floor to display</string>

Spanish: app/src/main/res/values-es/strings.xml

<string name="lz_map_zoom_in">Aumentar zoom del mapa</string>
<string name="lz_map_zoom_out">Disminuir zoom del mapa</string>
<string name="lz_map_current_location">Centrar mapa en mi ubicación</string>
<string name="lz_map_floor_selector">Seleccionar piso del edificio</string>

Portuguese: app/src/main/res/values-pt/strings.xml

<string name="lz_map_zoom_in">Aumentar zoom do mapa</string>
<string name="lz_map_zoom_out">Diminuir zoom do mapa</string>
<string name="lz_map_current_location">Centralizar mapa na minha localização</string>
<string name="lz_map_floor_selector">Selecionar andar do edifício</string>

Android will automatically use the correct strings based on the device’s language settings.

Partial Customization

You only need to override the strings you want to customize. If you don’t override a string, the SDK’s default English text will be used.

Accessibility Best Practices

When customizing accessibility texts, follow these guidelines:

1. Be Clear and Concise: Keep descriptions short but informative (ideally under 50 characters)
2. Describe the Action: Focus on what the control does, not just what it is
3. Use Action Verbs: Start with verbs like “Zoom”, “Center”, “Select”
4. Avoid Redundancy: Don’t repeat information that screen readers already announce (like “Button”)
5. Match Your App’s Language: Use the same language and tone as the rest of your application

Good Examples

• “Increase map zoom level”
• “Center map on current location”
• “Select floor to display”
• “Zoom in on map”

Avoid

• “Zoom in button” (redundant - screen reader already says “button”)
• “Click here” (not descriptive of the action)
• “Zoom” (too vague)

String Resource Names

The SDK uses the following string resource names for accessibility texts. Override these in your strings.xml to customize them:

Screen Reader Visibility Control

You can control whether UI elements are accessible to screen readers while keeping them visible and functional. This is useful for:

• Blind users: Hide controls that provide only visual feedback (they can’t see the map changes)
• Low vision users: Keep controls accessible (they can see the visual feedback)

How It Works

When an element is hidden from screen readers:

• Element remains visible on screen
• Element remains functional (clickable)
• Screen readers will skip these elements during navigation

Configuring Screen Reader Visibility

Override the boolean resources in your app/src/main/res/values/bools.xml:

<?xml version="1.0" encoding="utf-8"?>
<resources>
    <!-- Hide controls from screen readers (useful for blind users) -->
    <bool name="lz_map_hide_zoom_in_from_screen_reader">true</bool>
    <bool name="lz_map_hide_zoom_out_from_screen_reader">true</bool>
    <bool name="lz_map_hide_current_location_from_screen_reader">false</bool>
    <bool name="lz_map_hide_floor_selector_from_screen_reader">true</bool>
</resources>

Boolean Resource Names

Note: Set to true to hide from screen readers, false to keep accessible.

Current Location Button Callback

The current location button provides a callback with detailed information about the operation result, allowing you to display custom messages or handle the result appropriately.

Using the Callback

lzMap?.updateOnMyLocationButtonClickListener { result ->
    if (result.success) {
        result.location?.let { location ->
            Toast.makeText(
                context,
                "Map centered at: ${location.latitude}, ${location.longitude}",
                Toast.LENGTH_SHORT
            ).show()
        }
    } else {
        Toast.makeText(
            context,
            "Error: ${result.error}",
            Toast.LENGTH_SHORT
        ).show()
    }
}

LocationButtonClickResult

The callback receives a LocationButtonClickResult object with the following properties:

Error Scenarios

The callback will be invoked with success = false in the following cases:

• No location available: Location provider couldn’t obtain a valid location within 5 seconds
• No repository: Location repository was not set via setLocationProvider()
• Exception occurred: An error occurred while trying to get the location

Example: Custom Error Handling

lzMap?.updateOnMyLocationButtonClickListener { result ->
    when {
        result.success -> {
            // Show success message with location details
            val location = result.location!!
            showSnackbar("Map centered at ${location.latitude}, ${location.longitude}")
        }
        result.error?.contains("not available") == true -> {
            // Handle "location not available" case
            showSnackbar("Please enable location services")
        }
        result.error?.contains("repository") == true -> {
            // Handle missing repository case
            showSnackbar("Location service not initialized")
        }
        else -> {
            // Handle other errors
            showSnackbar("Error: ${result.error}")
        }
    }
}

Testing Accessibility

To test accessibility features:

1. Enable TalkBack: Go to Settings > Accessibility > TalkBack and enable it
2. Navigate the Map: Swipe through the map controls and listen to the announcements
3. Verify Descriptions: Ensure all controls have meaningful descriptions
4. Test Custom Texts: Verify your custom accessibility texts are being used

UI Elements Overview

Zoom Controls

The zoom controls are ImageButton elements positioned on the right side of the map:

• Zoom In: Increases map zoom by 1 level (up to maxZoom)
• Zoom Out: Decreases map zoom by 1 level (down to minZoom)

Both buttons are visible by default but can be hidden using hideZoomIn and hideZoomOut in LazarilloMapConfig.

Current Location Button

The current location button is an ImageButton positioned in the top-right corner of the map. When clicked:

• It centers the map on the user’s current location
• Uses a zoom level of 17.0
• Animates the camera movement smoothly
• Provides a callback with operation result (success/failure and location data)

The button can be hidden using hideZoomToLocation in LazarilloMapConfig.

Callback Example:

lzMap?.updateOnMyLocationButtonClickListener { result ->
    if (result.success) {
        // Handle successful location centering
        result.location?.let { location ->
            // Use location data for custom UI feedback
        }
    } else {
        // Handle error case
        showError(result.error ?: "Unknown error")
    }
}

Floor Selector

The floor selector is a Spinner positioned in the bottom-left corner of the map. It:

• Allows users to select which building floor to display
• Shows only floors available for the current place
• Automatically filters map layers based on the selected floor

The floor selector can be hidden using hideFloorSelector in LazarilloMapConfig.

Related Documentation

• Android Accessibility Guidelines 

Support

If you encounter accessibility issues or need help customizing accessibility texts, please refer to the Troubleshooting Guide or contact support.