Make a new blank project. In the example we have used Android Studio as developer environment, but you can use other tools to create this example app. 

Don’t forget to choose the “Phone and Tablet” option when setting the “Target Android Device”. Set the minimum Android API level to at least 15. At the “Add an Activity to Mobile” step pick an empty activity.

You can find the MAPCAT Android SDK -needed for application- in the Maven Central.  Add the MavenCentral constructor  to the project’s build.gradle file repository list.

(SCRIPT:
// Top-level build file where you can add configuration options common to all sub-projects/modules.
buildscript {
   repositories {
       google()
       jcenter()
   }
   dependencies {
       classpath 'com.android.tools.build:gradle:3.1.1'
       // NOTE: Do not place your application dependencies here; they belong
       // in the individual module build.gradle files
   }
}
allprojects {
   repositories {
       google()
       jcenter()
       mavenCentral()
   }
}
task clean(type: Delete) {
   delete rootProject.buildDir
}
/SCRIPT)

Add the next lines to our applications build.gradle file dependence list :

implementation 'com.mapcat.mapcatsdk:mapcat-android-sdk:1.0.7'
implementation 'com.mapbox.mapboxsdk:mapbox-android-services:2.2.9'

(SCRIPT:
apply plugin: 'com.android.application'
android {
   compileSdkVersion 27
   defaultConfig {
       applicationId "com.example.mapcat.mapcattestapp"
       minSdkVersion 15
       targetSdkVersion 27
       versionCode 1
       versionName "1.0"
       testInstrumentationRunner "android.support.test.runner.AndroidJUnitRunner"
   }
   buildTypes {
       release {
           minifyEnabled false
           proguardFiles getDefaultProguardFile('proguard-android.txt'), 'proguard-rules.pro'
       }
   }
}
dependencies {
   implementation fileTree(dir: 'libs', include: ['*.jar'])
   implementation 'com.android.support:appcompat-v7:27.1.1'
   implementation 'com.android.support.constraint:constraint-layout:1.1.0'
   implementation 'com.mapcat.mapcatsdk:mapcat-android-sdk:1.0.7'
   implementation 'com.mapbox.mapboxsdk:mapbox-android-services:2.2.9'
   testImplementation 'junit:junit:4.12'
   androidTestImplementation 'com.android.support.test:runner:1.0.1'
   androidTestImplementation 'com.android.support.test.espresso:espresso-core:3.0.1'
}
/SCRIPT)

Then, we need to add following line to the AndroidManifest.xml file within the app:
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />

(SCRIPT
<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
   package="com.example.mapcat.mapcattestapp">
   <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
   <application
       android:allowBackup="true"
       android:icon="@mipmap/ic_launcher"
       android:label="@string/app_name"
       android:roundIcon="@mipmap/ic_launcher_round"
       android:supportsRtl="true"
       android:theme="@style/AppTheme">
       <activity android:name=".MainActivity">
           <intent-filter>
               <action android:name="android.intent.action.MAIN" />
               <category android:name="android.intent.category.LAUNCHER" />
           </intent-filter>
       </activity>
   </application>
</manifest>
/SCRIPT)

After this the SDK can be used to visualize the MAPCAT map.

Map Visualization

In the activity_main.xml layout file change “Hello World” text to (TextView content) this:

<com.mapcat.mapcatsdk.maps.MapView 
android:id="@id/mapView" 
android:layout_width="match_parent" 
android:layout_height="match_parent"/>

For the initialization of MAPCAT map do the following steps.

Define a private variable for mapView. Then, in the onCreate () method, create a Mapcat instance using the API key we mentioned earlier. Finally, invite the initMAPCATMap function on mapView.

private MapView mapView;
@Override 
protected void onCreate(Bundle savedInstanceState) { 
super.onCreate(savedInstanceState); 
Mapcat.getInstance(this, "< Your MAPCAT Visualization API key >"); 
setContentView(R.layout.activity_main); 
mapView = (MapView) findViewById(R.id.mapView); 
mapView.initMapcatMap(new LayerOptions(false, false)); 
mapView.onCreate(savedInstanceState); 
MapViewInitHandler.registerListener(this);
}

As you can see in the code above, the initMapcatMap () method parameter requires a LayerOptions object to control the display of cycling routes. The following pictures shows the same area with different bicycle road settings.

To handle errors from the MAPCAT Visualization API (such as trying to use a bad API key or network failure) we need both MapViewInitHandler class and MapViewInitListener interface from the MAPCAT Android SDK. With the help of the MapViewInitHandler, register our running application in the onCreate () method and also  in the onDestroy () method.

By implementing the MapViewInitError and onMapViewInitSuccess functions of the MapViewInitListener, we can manage the responses from the MAPCAT Visualization API.

@Override
public void onMapViewInitError(final String error) {
Log.i("MAPINIT", "Error: " + error);
}
@Override
public void onMapViewInitSuccess() {
Log.i("MAPINIT", "Success");
}

To use this application, we also have to implement the following functions in MainActivity as follows:

@Override
public void onStart() { 
super.onStart(); 
mapView.onStart(); 
} 
@Override
public void onResume() { 
super.onResume(); 
mapView.onResume(); 
} 
@Override
public void onPause() { 
super.onPause(); 
mapView.onPause();
} 
@Override
public void onStop() { 
super.onStop(); 
mapView.onStop(); 
} 
@Override
public void onLowMemory() { 
super.onLowMemory(); 
mapView.onLowMemory(); 
} 
@Override
protected void onDestroy() { 
super.onDestroy(); 
mapView.onDestroy(); 
MapViewInitHandler.unregisterListener(this);
} 
@Override
protected void onSaveInstanceState(Bundle outState) { 
super.onSaveInstanceState(outState); 
mapView.onSaveInstanceState(outState); 
}

Setting the map language

You can easily change the language of the map texts using the setLanguage () function of the mapView variable. The parameter of the function is a two-letter language code corresponding to ISO 639-1. 

With the following code line, you can change the map language to Chinese at the end of the onCreate () method

mapView.setLanguage(“zh”);

Assistance

Now, your Android map app is hopefully up and running.
In case you need further assistance with the MAPCAT APIs, please check our developer site or contact us with your questions at support@mapcat.com