Getting Started

The Getting Started section of the Android Maps SDK is specifically crafted to facilitate a seamless and efficient onboarding process for developers. It provides a comprehensive guide that outlines the prerequisites, requirements, and necessary steps to start utilizing the SDK effectively. From installation instructions to information on Maven dependencies, this section offers detailed guidance to ensure a smooth integration of the Android Maps SDK into developers' projects.

By following the step-by-step instructions and recommendations provided in this section, developers can swiftly set up the Android Maps SDK and begin constructing captivating maps for their users. Additionally, the section includes a Quickstart guide that offers a concise and practical demonstration of how to create a basic map using the SDK.

Prerequisites

• Access Key: if you don’t have your Access Key yet, don’t hesitate to contact us
• IDE (Android Studio): to build and develop the Android application
• There are no restrictions on IDE version, but we recommend developers to use Arctic Fox | 2020.3.1 and above.

Installation

The guide explains how to install the SDK by adding the necessary dependencies to your project. It provides instructions on adding the maven dependencies of SDK to your app's build.gradle file.

Maven dependencies

In your app-level build.gradle file, add the Nextbillion.ai dependency for the Maps SDK for Android.

1
dependencies {
2
    def version = "1.0.2"
3
    implementation 'ai.nextbillion:nb-maps-android:$version'
4
}

This line of code tells Gradle to download the Nextbillion Android Maps SDK version 0.0.1 from the Maven Central repository and include it in the build process for your app, making the functionality provided by the SDK available to your app at runtime. The use of the variable version allows easy updating of the SDK version, by changing just one line of code.

Initialization

Before we start using any functionalities from both SDK, we need to initialize the Maps SDK first, by initializing it means to pass your Access Key to the singleton method of the class Nextbillion.

A common way to initialize the SDK is to put the following code in an Application’s onCreate() callback, otherwise, please make sure you have called the code below before you start using any functionalities of the SDK.

1
Nextbillion.getInstance(getApplicationContext(), "your access key");

Access Key

The maps SDK doesn’t enforce users to configure the access key in any strict manner, users can maintain and store their key in the below ways:

1. Local file(xml, Sharedpreference, or file)
2. Database
3. Cloud/Backend server
4. More

For instance, if you prefer to configure the access key in an XML file, you can do so like this:

1
<string name="nbmap_access_key">your-access-key</string>

Once you have your access key configured, you can pass the value to the SDK as follows:

1
Nextbillion.getInstance(getApplicationContext(), "your access key");

This flexibility allows you to adapt the access key configuration to your specific use case and security requirements.

Base URI

By default the Maps SDK will try to read the XML strings resource to see if users have set the desired base Uri to nbmap_base_uri, and all instances of MapView will use this base Uri to request style and tiles.

1
<string name="nbmap_base_uri">http://api.nextbillion.io</string>

If we want to override the base Uri for a particular MapView, there are two ways:

• Set nbmap_baseUri in layout XML file

  1
  <ai.nextbillion.maps.core.MapView
  2
  android:id="@+id/mapView"
  3
  android:layout_width="match_parent"
  4
  android:layout_height="match_parent"
  5
  app:nbmap_basrUri="https://api.nextbillion.io" />

• Set apiBaseUri in NextbillionMapOptions

  1
  NextbillionMapOptions options = NextbillionMapOptions.createFromAttributes(this, null)
  2
  .apiBaseUri("https://api.nextbillion.io");
  3
  mapView = new MapView(this, options);

Quickstart Guide

In this guide, we will walk you through the process of displaying a simple map view in an activity. The focus of this example is to provide a basic UI without complicated functions. By following this guide, you will be able to quickly set up and showcase a clean and straightforward map view in your Android application. Let's get started!

For all code examples, refer to Android Maps SDK Code Examples

activity_simple_map_view.xml view source

1
<?xml version="1.0" encoding="utf-8"?>
2
<androidx.constraintlayout.widget.ConstraintLayout xmlns:android="http://schemas.android.com/apk/res/android"
3
   xmlns:app="http://schemas.android.com/apk/res-auto"
4
   xmlns:tools="http://schemas.android.com/tools"
5
   android:layout_width="match_parent"
6
   android:layout_height="match_parent"
7
   tools:context=".MainActivity">
8

9
   <ai.nextbillion.maps.core.MapView
10
       android:id="@+id/simple_map_view"
11
       android:layout_width="match_parent"
12
       android:layout_height="match_parent"
13
       app:nbmap_uiAttribution="false"
14
       app:nbmap_cameraTargetLat="53.550813508267716"
15
       app:nbmap_cameraTargetLng="9.992248999933745"
16
       app:nbmap_cameraZoom="12" />
17

18
</androidx.constraintlayout.widget.ConstraintLayout>

SimpleMapViewActivity view source

1
package ai.nextbillion;
2

3
import android.os.Bundle;
4

5
import androidx.annotation.NonNull;
6
import androidx.appcompat.app.AppCompatActivity;
7
import ai.nextbillion.maps.core.MapView;
8
import ai.nextbillion.maps.core.NextbillionMap;
9
import ai.nextbillion.maps.core.OnMapReadyCallback;
10
import ai.nextbillion.maps.core.Style;
11

12
public class SimpleMapViewActivity extends AppCompatActivity implements OnMapReadyCallback {
13

14
   private MapView mapView;
15
   private NextbillionMap mMap;
16

17
   @Override
18
   protected void onCreate(Bundle savedInstanceState) {
19
       super.onCreate(savedInstanceState);
20
       setContentView(R.layout.activity_simple_map_view);
21
       mapView = findViewById(R.id.simple_map_view);
22
       mapView.onCreate(savedInstanceState);
23
   }
24

25
   @Override
26
   public void onMapReady(@NonNull NextbillionMap nextbillionMap) {
27
       mMap = nextbillionMap;
28
       mMap.getStyle(new Style.OnStyleLoaded() {
29
           @Override
30
           public void onStyleLoaded(@NonNull Style style) {
31
           }
32
       });
33
   }
34

35
   ///////////////////////////////////////////////////////////////////////////
36
   // Lifecycle
37
   ///////////////////////////////////////////////////////////////////////////
38

39
   @Override
40
   protected void onStart() {
41
       super.onStart();
42
       mapView.onStart();
43
   }
44

45
   @Override
46
   protected void onResume() {
47
       super.onResume();
48
       mapView.onResume();
49
   }
50

51
   @Override
52
   protected void onPause() {
53
       super.onPause();
54
       mapView.onPause();
55
   }
56

57
   @Override
58
   protected void onStop() {
59
       super.onStop();
60
       mapView.onStop();
61
   }
62

63
   @Override
64
   protected void onSaveInstanceState(@NonNull Bundle outState) {
65
       super.onSaveInstanceState(outState);
66
       mapView.onSaveInstanceState(outState);
67
   }
68

69
   @Override
70
   protected void onDestroy() {
71
       super.onDestroy();
72
       mapView.onDestroy();
73
   }
74

75
   @Override
76
   public void onLowMemory() {
77
       super.onLowMemory();
78
       mapView.onLowMemory();
79
   }
80
}

Code summary

The SimpleMapViewActivity class extends the AppCompatActivity class and implements the OnMapReadyCallback interface. It can be used to display a map view in an Android app.

The class has the following members:

• mapView: A MapView object that is used to display the map.
• mMap: A NextbillionMap object that represents the map data.

The class overrides the following methods:

• onCreate(): This method is called when the activity is first created. It initializes the map view and sets the map's style.
• onMapReady(): This method is called when the map is ready to be used. It sets the map's center and zoom level.
• onStart(): This method is called when the activity starts. It starts the map view.
• onResume(): This method is called when the activity resumes. It resumes the map view.
• onPause(): This method is called when the activity pauses. It pauses the map view.
• onStop(): This method is called when the activity stops. It stops the map view.
• onSaveInstanceState(): This method is called when the activity is saved to the state. It saves the map view's state.
• onDestroy(): This method is called when the activity is destroyed. It destroys the map view.
• onLowMemory(): This method is called when the device is low on memory. It reduces the map view's memory usage.

Here are some additional details about the code:

• The onCreate() method initializes the map view and sets the map's style. The map view is initialized by calling the setContentView() method and passing it the R.layout.activity_simple_map_view layout resource. The map's style is set by calling the mMap.getStyle() method and pass it to a listener that will be called when the style is loaded.
• The onMapReady() method is called when the map is ready to be used. It sets the map's center and zoom level. The map's center is set by calling the mMap.setCenter() method and passing it the coordinates of the center point. The map's zoom level is set by calling the mMap.setZoom() method and passing it the zoom level.
• The other methods in the class implement the lifecycle methods for an activity. These methods are called when the activity starts, pauses, stops, resumes, is destroyed or is low on memory.