Installation

Reminder:

Bear in mind that this tutorial only scratches the surface of what Android SDK does.

Installing Android SDK is quite simple and straightforward.

SDK in Jcenter:

We have 2 .aar file. To use our map, you have to add sdk-map. we added it to Jcenter, so you can add this lib by adding below line to dependencies in your build.gradle file.

* implementation 'ir.map.sdk:sdk_map:3.0.4'


Go to app Gradle and add following library dependency to your gradlle and sync.


  dependencies {
      implementation 'com.mapbox.mapboxsdk:mapbox-sdk-services:3.4.1'
      implementation 'com.mapbox.mapboxsdk:mapbox-sdk-geojson:3.4.1'
      implementation 'com.mapbox.mapboxsdk:mapbox-android-telemetry:3.5.7'
      implementation 'com.mapbox.mapboxsdk:mapbox-android-gestures:0.3.0'
      implementation 'com.google.android.gms:play-services-location:11.0.4'
    }

Please get your ACCESS_TOKEN from our support team. You have to initialize our sdk in your Application class like below:


    import android.app.Application;
    import ir.map.sdk_map.Mapir;

    public class AppController extends Application {

        @Override
        public void onCreate() {
            super.onCreate();

            //TODO Please add your ACCESS_TOKEN
            Mapir.getInstance(this, "mapir_ujhggl55415jhjf");
        }
    }

Please go to Manifest file and set name attribue value to "YOUR_APPLICATION_CLASS_NAME"


      <application
          .....
          android:name=".AppController"
          android:allowBackup="true"
          android:largeHeap="true">
          ......
      </application>

Please go to build.gradle file and add below code to android scope:


      android {
          ......

          compileOptions {
              sourceCompatibility JavaVersion.VERSION_1_8
              targetCompatibility JavaVersion.VERSION_1_8
          }
      }

Tips:

  • Manually Sync the project. If sync fails please Use some VPN in order to sucessfully build the project dependency
  • Once setup is succesfull follow the tutorial below

Getting started

Basic map:

Creating a basic map is pretty easy. You begin with calling the Android SDK.

1. Go to your activity layout (Ex:activity_basic_map.xml) file and paste the content


<fragment
    class="ir.map.sdk_map.maps.SupportMapFragment"
    android:id="@+id/myMapView"
    android:layout_width="match_parent"
    android:layout_height="match_parent">
</fragment>

Tips:

  • The element property Class in the fragment XML is very important do not forget to add it:
    class="ir.map.sdk_map.maps.SupportMapFragment"

2. Go to Manifest file and add following permissions.


3. Create an application class in your src (main) folder and extend it from Application(or MultidexApplication) class in project.


import android.app.Application;
import ir.map.sdk_map.Mapir;

public class AppController extends Application {

    @Override
    public void onCreate() {
        super.onCreate();

        //TODO Please add your ACCESS_TOKEN
        Mapir.getInstance(this, "mapir_ujhggl55415jhjf");
    }
}

4. Do not forget to add application class name in manifest file


    <application
        .....
        android:name=".AppController"
        android:allowBackup="true"
        android:largeHeap="true">
              .....
    </application>

5. Build the project and run it, Enjoy your Map view.

Current Location:

After creating a map, to set current location enable in your map view, add below code to your Activity:


import android.Manifest;
import android.content.pm.PackageManager;
import android.location.Location;
import android.os.Bundle;
import android.support.v4.app.ActivityCompat;
import android.support.v7.app.AppCompatActivity;

import com.mapbox.android.core.location.LocationEngineListener;

import ir.map.sdk_map.camera.CameraUpdateFactory;
import ir.map.sdk_map.geometry.LatLng;
import ir.map.sdk_map.location.LocationComponent;
import ir.map.sdk_map.maps.MapirMap;
import ir.map.sdk_map.maps.SupportMapFragment;

public class CurrentLocationActivity extends AppCompatActivity implements LocationEngineListener {

    private MapirMap mapirMap;

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_current_location);

        ((SupportMapFragment) getSupportFragmentManager().findFragmentById(R.id.myMapView))
                .getMapAsync(mapirMap -> {

                    CurrentLocationActivity.this.mapirMap = mapirMap;
                    if (CurrentLocationActivity.this.mapirMap != null) {
                        //region get permissions
                        if (ActivityCompat.checkSelfPermission(getApplicationContext(),
                                Manifest.permission.ACCESS_FINE_LOCATION) != PackageManager.PERMISSION_GRANTED)
                            ActivityCompat.requestPermissions(
                                    CurrentLocationActivity.this, new String[]{Manifest.permission.ACCESS_FINE_LOCATION}, 1);
                        if (ActivityCompat.checkSelfPermission(getApplicationContext(), Manifest.permission.ACCESS_COARSE_LOCATION) != PackageManager.PERMISSION_GRANTED)
                            ActivityCompat.requestPermissions(
                                    CurrentLocationActivity.this, new String[]{Manifest.permission.ACCESS_COARSE_LOCATION}, 1);
                        //endregion get permissions

                        if (ActivityCompat.checkSelfPermission(getApplicationContext(), Manifest.permission.ACCESS_FINE_LOCATION) == PackageManager.PERMISSION_GRANTED
                                && ActivityCompat.checkSelfPermission(getApplicationContext(), Manifest.permission.ACCESS_COARSE_LOCATION) == PackageManager.PERMISSION_GRANTED) {
                            LocationComponent component = CurrentLocationActivity.this.mapirMap.getLocationComponent();
                            component.activateLocationComponent(CurrentLocationActivity.this);
                            component.setLocationComponentEnabled(true);
                            if (component.getLocationEngine() != null) {
                                component.getLocationEngine().addLocationEngineListener(CurrentLocationActivity.this);
                            }
                            mapirMap.animateCamera(CameraUpdateFactory
                                    .newLatLngZoom(new LatLng(component.getLastKnownLocation().getLatitude(),
                                            component.getLastKnownLocation().getLongitude()), 14));
                        }
                    }
                });
    }

    @Override
    public void onConnected() {
    }

    @Override
    public void onLocationChanged(Location location) {
        //TODO add your code
        if (location != null)
            mapirMap.animateCamera(CameraUpdateFactory.newLatLngZoom(new LatLng(location.getLatitude(), location.getLongitude()), 14));
    }
}

Tips:

  • If your android version is more than Android 6.0 (API level 23), handle permission for location with code.

Zoom Location:

After creating a map, to apply zoom in your map view, add below code to your Activity:


import android.os.Bundle;
import android.support.v7.app.AppCompatActivity;

import ir.map.sdk_map.camera.CameraUpdateFactory;
import ir.map.sdk_map.geometry.LatLng;
import ir.map.sdk_map.maps.MapirMap;
import ir.map.sdk_map.maps.SupportMapFragment;

public class ZoomLocationActivity extends AppCompatActivity {

    //Change the following constants for getting your desired location
    public static final double FOCUSED_LATITUDE = 35.699773;
    public static final double FOCUSED_LONGITUDE = 51.337888;
    public static final int FOCUSED_ZOOM_LEVEL = 15;

    private MapirMap mapirMap;

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_zoom_location);

        //TODO Zoom in Specific Location
        ((SupportMapFragment) getSupportFragmentManager().findFragmentById(R.id.myMapView))
                .getMapAsync(map -> {
                    mapirMap = map;
                    if (mapirMap != null) // Checks if we were successful in obtaining the map
                        mapirMap.animateCamera(CameraUpdateFactory
                                .newLatLngZoom(new LatLng(FOCUSED_LATITUDE, FOCUSED_LONGITUDE), FOCUSED_ZOOM_LEVEL));
                });
    }
}

Tips:

  • Change the value according to your focused Latitude and longitude. The zoom level parameter can set a zoom level for the map view.

Adding Features

Adding a marker:

After creating a map, to create a marker follow below steps:

1. Add any drawable ic_marker for showing marker.

2. Add below code to your Activity:


import android.os.Bundle;
import android.support.v7.app.AppCompatActivity;

import ir.map.sdk_map.annotations.Marker;
import ir.map.sdk_map.annotations.MarkerOptions;
import ir.map.sdk_map.geometry.LatLng;
import ir.map.sdk_map.maps.MapirMap;
import ir.map.sdk_map.maps.SupportMapFragment;

public class AddMarkerActivity extends AppCompatActivity {

    private static final LatLng TEHRAN = new LatLng(35.699773, 51.337888);
    private MapirMap mapirMap;
    private Marker mTehran;

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_add_marker);

        ((SupportMapFragment) getSupportFragmentManager().findFragmentById(R.id.myMapView))
                .getMapAsync(map -> {
                    mapirMap = map;

                    if (mapirMap != null) { // Checks if we were successful in obtaining the map
                        //TODO : Don't forget add a drawable named : ic_marker
                        //mTehran object hold marker instance for future use
                        mTehran = mapirMap.addMarker(new MarkerOptions()
                                .position(TEHRAN).title("Tehran").snippet("Population: 8,627,300"));
                    }
                });
    }
}

Tips:

  • The snippet and title will allow you to show a dialog if click the marker.
  • Its a very useful feature in order to tooltip something from the marker.

Adding a polyline:

After creating a map, to add a polyline in your map view, Add below code to your Activity:


import android.os.Bundle;
import android.support.v7.app.AppCompatActivity;

import ir.map.sdk_map.annotations.PolylineOptions;
import ir.map.sdk_map.geometry.LatLng;
import ir.map.sdk_map.maps.MapirMap;
import ir.map.sdk_map.maps.SupportMapFragment;

public class AddPolylineActivity extends AppCompatActivity {

    private static final LatLng ARAK = new LatLng(34.0954, 49.7013);
    private static final LatLng SHIRAZ = new LatLng(29.591, 52.5837);
    private static final LatLng RASHT = new LatLng(37.2682, 49.5891);

    private MapirMap mapirMap;

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_polyline);

        ((SupportMapFragment) getSupportFragmentManager().findFragmentById(R.id.myMapView))
                .getMapAsync(map -> {
                    mapirMap = map;
                    if (mapirMap != null) // Checks if we were successful in obtaining the map
                        mapirMap.addPolyline((new PolylineOptions()).add(ARAK, SHIRAZ, RASHT));
                });
    }
}

Adding a polygon:

After creating a map, to add a polygon in your map view, Add below code to your Activity:



  import ir.map.sdk_common.MaptexLatLng;
  import ir.map.sdk_map.wrapper.MaptexMap;
  import ir.map.sdk_map.wrapper.MaptexPolygonOptions;
  import ir.map.sdk_map.wrapper.OnMaptexReadyCallback;
  import ir.map.sdk_map.wrapper.SupportMaptexFragment;

  public class MainActivity extends AppCompatActivity {

      private static final MaptexLatLng ARAK = new MaptexLatLng(34.0954, 49.7013);
      private static final MaptexLatLng SHIRAZ = new MaptexLatLng(29.591, 52.5837);
      private static final MaptexLatLng MASHHAD = new MaptexLatLng(36.2605, 59.6168);
      private static final MaptexLatLng RASHT = new MaptexLatLng(37.2682, 49.5891);
      private List polygonPointList = new ArrayList<>();
      private MaptexMap maptexMap;

      @Override
      protected void onCreate(Bundle savedInstanceState) {
          super.onCreate(savedInstanceState);
          setContentView(R.layout.activity_main);

          ((SupportMaptexFragment) getSupportFragmentManager().findFragmentById(R.id.myMapView))
                  .getMaptexAsync(new OnMaptexReadyCallback() {
                      @Override
                      public void onMaptexReady(MaptexMap map) {
                          maptexMap = map;
                          if (maptexMap != null) { // Checks if we were successful in obtaining the map

                              polygonPointList.add(ARAK);
                              polygonPointList.add(SHIRAZ);
                              polygonPointList.add(MASHHAD);
                              polygonPointList.add(RASHT);

                              maptexMap.addPolygon(new MaptexPolygonOptions()
                                      .addAll(polygonPointList)
                                      .fillColor(Color.TRANSPARENT)
                                      .strokeColor(Color.BLUE)
                                      .strokeWidth(5));
                          }
                      }
                  });
      }
  }