This guide will take you through the process of integrating CedarMaps into your Android application.
All the mentioned methods and tools in this document have been tested on Android Studio v3.5.
To install the current stable version, first add the address of CedarMaps maven repository to the list of repositories. This is usually located in the build.gradle of your project module.
repositories {
maven {
url "https://repo.cedarmaps.com/android/"
}
}Then, add this to the build.gradle of your app module:
dependencies {
implementation 'com.cedarmaps:CedarMapsSDK:4.3.0'
}Note: CedarMaps is using AndroidX from version 4.2.0. The last version to support old Support Library is 4.1.0.
You may receive an error forcing you to use a minimum API version of N. This section will help you with that.
The Mapbox Maps SDK for Android introduces the use of Java 8. To fix any Java versioning issues, ensure that you are using Gradle version of 3.0 or greater. Once you’ve done that, add the following compileOptions to the android section of your app-level build.gradle file like so:
android {
...
compileOptions {
sourceCompatibility JavaVersion.VERSION_1_8
targetCompatibility JavaVersion.VERSION_1_8
}
}Make sure your app can access internet by adding this to AndroidManifest.xml:
<uses-permission android:name="android.permission.INTERNET"/>If your app needs to access location services, add the following as well:
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />On Android 6.0 and up, you have to check for "dangerous" permissions at runtime. Accessing location is considered a dangerous permission.
In order to use CedarMaps, you should set your clientID, clientSecret and a context in your application.
We suggest you do this in your Application subclass, in its onCreate method.
CedarMaps.getInstance()
.setClientID("YOUR_CLIENT_ID")
.setClientSecret("YOUR_CLIENT_SECRET")
.setContext(CONTEXT)If you've received an API Base URL, you can set it on CedarMaps shared object:
CedarMaps.getInstance()
.setAPIBaseURL("YOUR_API_BASE_URL")CedarMaps SDK is based on Mapbox GL Android SDK v8.0.0 and provides extra API methods over Mapbox. For more information about how to use MapView and other components such as Adding Markers, Showing Current Location, etc., please see Mapbox Getting Started.
The MapView class is the key component of this library for showing map tiles. It behaves
like any other ViewGroup and its behavior can be changed statically with an
XML layout
file, or programmatically during runtime.
Pay attention to the package when importing. CedarMaps MapView extends Mapbox MapView and they shall not be used interchangeably.
To add the CedarMaps MapView as a layout element, add the following to your xml file:
<com.cedarstudios.cedarmapssdk.MapView
android:id="@+id/mapView"
android:layout_width="match_parent"
android:layout_height="match_parent"
mapbox:mapbox_cameraZoom="14"
...
/>In your fragment or activity class, where you want to use MapView,
you need to set your desired style after the MapboxMap instance is ready.
Call getMapAsync in onCreate and wait for the callback.
You should use CedarMapsStyleConfigurator to configure a style and then set it on your MapboxMap instance.
You can choose between 3 different styles:
VECTOR_LIGHTVECTOR_DARKRASTER_LIGHT
Using Vector styles is recommended.
mMapView = (MapView) view.findViewById(R.id.mapView);
mMapView.getMapAsync(new OnMapReadyCallback() {
@Override
public void onMapReady(MapboxMap mapboxMap) {
mMapboxMap = mapboxMap;
CedarMapsStyleConfigurator.configure(
CedarMapsStyle.VECTOR_LIGHT, new OnStyleConfigurationListener() {
@Override
public void onSuccess(Style.Builder styleBuilder) {
mapboxMap.setStyle(styleBuilder);
}
@Override
public void onFailure(@NonNull String errorMessage) {
Log.e(TAG, errorMessage);
}
});
mMapboxMap.setMaxZoomPreference(17);
mMapboxMap.setMinZoomPreference(6);
mMapboxMap.addOnMapClickListener(point -> {
Log.i(TAG, "Tapped on map");
return true;
});
}
});Mapbox Plugins build on top of the Maps SDK providing extra features in lightweight dependencies. There are lots of plugins which you could check them out here.
We believe using the Annotation Plugin will help you a lot in adding custom markers and symbols onto your map. Many examples are also included in both Mapbox documentations page or our included Sample App.
Mapbox is built as a native library for every possible architecture. If you are supporting all architectures, please consider splitting the APK based on architecture.
An introduction from Google can be found here.
You can find APK splitting configurations in Sample App build.gradle as well.
In addition to using MapView, you can use CedarMaps API to retrieve location based data and street search.
All API calls are asynchronous; they don't block the thread on which they're called. The completion handlers are all called on the UiThread.
You can also consult CedarMaps.java for detailed info on all of our methods. Some of the main methods are mentioned below.
For finding a street or some limited POIs, you can easily call forwardGeocode methods.
CedarMaps.getInstance().forwardGeocode(query, new ForwardGeocodeResultsListener() {
@Override
public void onSuccess(@NonNull List<ForwardGeocode> results) {
}
}
@Override
public void onFailure(@NonNull String errorMessage) {
}
});More advanced street searches are available in the Sample App.
You can retrieve data about a location by using Reverse Geocode API.
CedarMaps.getInstance().reverseGeocode(
coordinate,
new ReverseGeocodeResultListener() {
@Override
public void onSuccess(@NonNull ReverseGeocode result {
}
@Override
public void onFailure(@NonNull String errorMessage) {
}
});This method calculates the direction between points. It can be called with up to 50 different pairs in a single request.
CedarMaps.getInstance().direction(departure, destination,
new GeoRoutingResultListener() {
@Override
public void onSuccess(@NonNull GeoRouting result) {
}
@Override
public void onFailure(@NonNull String error) {
}
});This method calculates the distance between points in meters. It can be called with up to 15 different points in a single request.
CedarMaps.getInstance().distance(departure, destination,
new GeoRoutingResultListener() {
@Override
public void onSuccess(@NonNull GeoRouting result) {
}
@Override
public void onFailure(@NonNull String error) {
}
});This method returns a static map image of desired size for the entered coordinate.
It automatically considers the screen density of the device on which it's being called for better image quality.
You can optionally specify marker positions to draw on the image.
CedarMaps.getInstance().staticMap(width, height, zoomLevel, centerPoint, markers,
new StaticMapImageResultListener() {
@Override
public void onSuccess(@NonNull Bitmap bitmap) {
}
@Override
public void onFailure(@NonNull String errorMessage) {
}
});The CedarMaps Android SDK is an Android Library Module, which means in order to test it out in an emulator or a device during development a Test Module is needed. We call this test module the SampleApp. It contains many different examples of new functionality or just ways to do certain things. We highly recommend checking it out.
The source code for these tests / examples is located under the CedarMapsSampleApp directory.
CedarMaps-Dev (the SampleApp) can also be downloaded from Google Play and Cafe Bazaar.