Tutorials

Setup the access key for the NextBillion mapview

Modify AndroidManifest.xml

Locate the <application> tag in your project's AndroidManifest.xml file and include the following element inside it. This element declares androidx.startup.InitializationProvider, which is responsible for application initialization.

1
<provider
2
    android:name="androidx.startup.InitializationProvider"
3
    android:authorities="${applicationId}.androidx-startup"
4
    android:exported="false"
5
    tools:node="merge">
6
    <meta-data
7
    android:name=".AppDataInitStartup"
8
    android:value="androidx.startup" />
9
</provider>
10

Create AppDataInitStartup Class

Next, create a class named AppDataInitStartup in your project. This class implements the Initializer interface. In the create method of this class, perform the application's initialization tasks.

In this example, the initialization task is performed using Nextbillion.getInstance(context, "YOUR-ACCESS-KEY").

Replace "YOUR-ACCESS-KEY" with your actual access key.

1
class AppDataInitStartup : Initializer<Boolean> {
2

3
    override fun create(context: Context): Boolean {
4
        Nextbillion.getInstance(context, "YOUR-ACCESS-KEY")
5
        return true
6
    }
7

8
    override fun dependencies(): List<Class<out Initializer<*>>> {
9
        return emptyList()
10
    }
11
}

By following these steps, you have integrated the AppDataInitStartup code into your Android project. This code will be executed when the application starts, performing the initialization tasks defined in the create method.

Add NextBillionMap to your app

This example embeds NextBillionMap into your application using the Compose extension.

1
import ai.nextbillion.maps.extension.compose.NextBillionMap
2

3
public class SimpleMapActivity : ComponentActivity() {
4

5
    override fun onCreate(savedInstanceState: Bundle?) {
6
        super.onCreate(savedInstanceState)
7
        setContent {
8
            NextBillionMap(modifier = Modifier.fillMaxSize())
9
        }
10
    }
11
    ...
12
}

Setting Up the Map Style and Initial Camera Position

To configure the initial map style and camera position, utilize the NextbillionMapOptions by constructing it with the context obtained from the createFromAttributes function. The NextbillionMapOptions is the same object used when constructing a MapView.

1
override fun onCreate(savedInstanceState: Bundle?) {
2
        super.onCreate(savedInstanceState)
3
        setContent {
4
            NextBillionMap(
5
                modifier = Modifier.fillMaxSize(),
6
                mapType = MapType.SATELLITE,
7
                mapOptionsFactory = { context ->
8
                    NextbillionMapOptions.createFromAttributes(context)
9
                        .camera(
10
                            CameraPosition.Builder()
11
                                .target(LatLng(21.142364, 79.094730))
12
                                .zoom(12.0)
13
                                .build()
14
                        )
15
                }
16
            )
17
        }
18
    }

Use raw NextbillionMap methods through NextBillionMapEffect

The NextBillion Compose Extension is constructed around MapView within the SDK of the base maps. Due to the extensive API surface of the map SDK, it's impractical to cover every aspect within this wrapper. Hence, we provide access to the raw NextBillionMap reference through NextBillionMapEffect. This enables you to leverage the entire API surface within a NextBillionMapEffect.

It's essential to exercise caution when employing raw NextBillionMap APIs within NextBillionMapEffect. Doing so may introduce internal state changes that could potentially disrupt Compose states, leading to unexpected behaviors.

The subsequent example showcases how to activate debug features using NextBillionMapEffect.

1
override fun onCreate(savedInstanceState: Bundle?) {
2
        super.onCreate(savedInstanceState)
3
        setContent {
4
            NextBillionMap(
5
                modifier = Modifier.fillMaxSize(),
6
            ) {
7
                NextBillionMapEffect(Unit) { nbMap ->
8
                    // Use NextbillionMap to access all the NextBillion Maps APIs .
9
                    // For example, to enable debug mode:
10
                    nbMap.isDebugActive = true
11
                }
12
            }
13
        }
14
    }

Use Camera Animation or Position state APIs

In the Compose environment, the map's camera and position animations are accessed through CameraPositionState. Internally, these functionalities are implemented using the Transform feature of the base maps SDK.

Currently, we offer high-level camera animation APIs such as setCameraPosition, animate,easeCamera, and move within the CameraPositionState.

Below is an example demonstrating the addition of a button to execute a flyTo animation to the designated camera position.

1
override fun onCreate(savedInstanceState: Bundle?) {
2
  super.onCreate(savedInstanceState)
3
  setContent {
4
    // Hold the hoisted CameraPositionState to manipulate the map camera.
5
    val cameraPositionState = rememberCameraPositionState{
6
        position = CameraPosition.Builder().target(LatLng(21.142364, 79.094730)).zoom(15.0)
7
            .build()
8
    }
9

10
    Box(modifier = Modifier.fillMaxSize()) {
11
        NextBillionMap(
12
            modifier = Modifier.matchParentSize(),
13
            cameraPositionState = cameraPositionState,
14
        )
15
        Button(
16
            onClick = {
17
                cameraPositionState.easeCamera(CameraPosition.Builder().target(LatLng(21.152364, 79.098730)).build(), durationMs = 5000)
18
            }
19
        ) {
20
            Text(text = "Animate camera with easeCamera")
21
        }
22
    }
23
  }
24
}

Add Annotations to the map

The Annotation support is added with the initial compose extension. You can add Marker, Polyline, and Polygon annotations as composable functions within the NextBillionMap composable function.

Add a single Marker to the map

The following example showcases adding one marker annotation to the map.

1
override fun onCreate(savedInstanceState: Bundle?) {
2
        super.onCreate(savedInstanceState)
3
        setContent {
4
            NextBillionMap(
5
                modifier = Modifier.fillMaxSize(),
6
                ) {
7
                Marker(
8
                    state = MarkerState(LatLng(21.152364, 79.098730))
9
                )
10
            }
11
        }
12
    }

Add a Polyline to the map

The following example showcases adding one polyline annotation to the map.

1
 override fun onCreate(savedInstanceState: Bundle?) {
2
        super.onCreate(savedInstanceState)
3
        setContent {
4
            NextBillionMap(
5
                modifier = Modifier.fillMaxSize(),
6
                mapOptionsFactory = { context ->
7
                    NextbillionMapOptions.createFromAttributes(context)
8
                        .camera(
9
                            CameraPosition.Builder()
10
                                .target(LatLng(4.454029847741182, 102.12279928897392))
11
                                .zoom(7.0)
12
                                .build()
13
                        )
14
                }
15
            ) {
16
                Polyline(
17
                    color = Color.Red,
18
                    points = listOf(LatLng(4.173966011743196, 102.56143332932972), LatLng(4.757388856118707, 102.84923902653723)),
19
                    width = 10.0f,
20
                    onClick = {
21
                       // On click call back here
22
                    }
23
                )
24
            }
25
        }
26
    }

Add a Polygon to the map

The following example showcases adding one polygon annotation to the map.

1
override fun onCreate(savedInstanceState: Bundle?) {
2
        super.onCreate(savedInstanceState)
3
        setContent {
4
            NextBillionMap(
5
                modifier = Modifier.fillMaxSize(),
6
                mapOptionsFactory = { context ->
7
                    NextbillionMapOptions.createFromAttributes(context)
8
                        .camera(
9
                            CameraPosition.Builder()
10
                                .target(LatLng(5.454029847741182, 102.12279928897392))
11
                                .zoom(7.0)
12
                                .build()
13
                        )
14
                }
15
            ) {
16
                Polygon(
17
                    points = listOf<LatLng>(
18
                        LatLng(5.905950548125056, 102.20094147543449),
19
                        LatLng(5.447582810324074, 102.4236053421908),
20
                        LatLng(5.319304234490461, 103.13322846086854),
21
                        LatLng(5.113456220724453, 101.63920008098916),
22
                        LatLng(5.5704634364237124, 101.24733645772515),
23
                        LatLng(5.5069783817472056, 101.93764874951532),
24
                        LatLng(5.905950548125056, 102.20094147543449)
25
                    ),
26
                    fillColor = Color.Blue,
27
                    strokeColor = Color.Red,
28
                    onClick = {
29
                        // On click call back
30
                    }
31
                )
32
            }
33
        }

These examples demonstrate how to add various types of annotations to the map within your Compose-based application.

Configure MapView settings

You can easily configure MapView settings such as AttributionSettings, CompassSettings, GesturesSettings, LocationComponentSettings, and LogoSettings by using MutableState within the NextBillionMap composable functions.

Gestures settings

In this example, we configure the gestures setting using MutableState. The user can interact with a button to update the gestures settings dynamically.

1
override fun onCreate(savedInstanceState: Bundle?) {
2
        super.onCreate(savedInstanceState)
3

4
        setContent {
5
            var gesturesSettings by remember { mutableStateOf(GesturesSettings { }) }
6
            NextBillionMap(
7
                modifier = Modifier.fillMaxSize(),
8
                gesturesSettings = gesturesSettings
9
            )
10
            Button(
11
                onClick = {
12
                    gesturesSettings =
13
                        gesturesSettings.toBuilder().setScrollGesturesEnabled(false).build()
14
                }
15
            ) {
16
                Text(text = "Disable gesture scroll")
17
            }
18
        }
19
    }

Users can configure other MapView settings using the MutableState in the same manner.