Mappls Location Capture SDK

Getting started

A lightweight, on-demand location capture SDK for Android that enables applications to fetch a user’s current location efficiently with accuracy limits, timeout control, and minimal battery usage. The SDK supports single-shot and subscribed location fetching without continuous tracking.

Key Capabilities

• One-time location capture with accuracy threshold

• Subscribed mode until accuracy or timeout is reached

• Automatic termination (no background tracking)

• Accuracy, timeout, and retry limits

• Mock location detection

• Network and GPS state awareness

Lightweight footprint suitable for KYC, attendance, onboarding, check-ins

Installation

Add Mappls Repository

• Add the Mappls repository to your settings.gradle or settings.gradle.kts file:

  Kotlin (settings.gradle.kts)

  pluginManagement {
      repositories {
          maven(url = "https://maven.mappls.com/repository/mappls/")
      }
  }
  dependencyResolutionManagement {
  repositories {
      google()
      mavenCentral()
      maven(url = "https://maven.mappls.com/repository/mappls/")
  }
  }

  Groovy (settings.gradle)

  pluginManagement {
      repositories {
          maven {
              url 'https://maven.mappls.com/repository/mappls/'
          }
      }
  }
  dependencyResolutionManagement {  
  repositories {  
          google()  
          mavenCentral()  
          maven {  
              url 'https://maven.mappls.com/repository/mappls/'  
          }  
  }  
  } 

Adding Mappls Configuration file

• Download Configuration files for your app (associated with Package Name and Signing Certificate SHA-256)
• Add Configuration files (<appId>.a.olf and <appId>.a.conf) into the module app-level root directory of your app
• Add Mappls Service Plugin as a dependency in your project level build.gradle or build.gradle.kts

  Kotlin (build.gradle.kts)

  buildscript {
      dependencies {
          classpath("com.mappls.services:mappls-services:1.0.0")
          // NOTE: Do not place your application dependencies here; they belong
          // in the individual module build.gradle files
      }
  }

  Groovy (build.gradle)

  buildscript {
      dependencies {
          classpath 'com.mappls.services:mappls-services:1.0.0'
          // NOTE: Do not place your application dependencies here; they belong
          // in the individual module build.gradle files
      }
  }

• Add Mappls Services Plugin in your app-level build.gradle or build.gradle.kts file

  Kotlin (build.gradle.kts)

  plugins {
      id("com.android.application")
      // Add the Mappls services Gradle plugin    
      id("com.mappls.services.android")
  }

  Groovy (build.gradle)

  plugins {
      id 'com.android.application'
      // Add the Mappls services Gradle plugin
      id 'com.mappls.services.android'
  }

Add the dependency

• Add below dependency in your app-level build.gradle

Kotlin (build.gradle.kts)

implementation("com.mappls.sdk:location-capture-sdk:1.0.0")

Groovy (build.gradle)

implementation 'com.mappls.sdk:location-capture-sdk:1.0.0'

Initialization (Required)

Initialization must be completed before invoking any location fetch method.

• What happens during initialization

  • Location permissions validation

  • Configuration setup (accuracy, timeout, attempts)

  • Location engine configuration

  • SDK readiness check

Add MapplsLocationSdk initialization

Kotlin

val mapplsLocationEngineRequest = MapplsLocationEngineRequest.Builder(5000L)
            .setDisplacement(0f)
            .setPriority(PRIORITY_HIGH_ACCURACY)
            .build()

val option = LocationCaptureConfig.Builder()
            .setMapplsLocationEngineRequest(mapplsLocationEngineRequest)
            .setTimeoutValueInSecond(60)
            .setAccuracy(15.0)
            .setNumberOfAttempts(5)
            .build()

LocationServiceProviderManager.getInstance().initialise(this, object : OnLocationPluginInitialise {
                public override fun onSuccess() {
                        LocationServiceProviderManager.getInstance().setLocationCaptureConfig(option)
                }

                public override fun onFailure(code: Int, reason: String) {

                }
    })

Java

 MapplsLocationEngineRequest mapplsLocationEngineRequest = new MapplsLocationEngineRequest.Builder(5000L)
                .setDisplacement(0f)
                .setPriority(PRIORITY_HIGH_ACCURACY)
                .build();

    LocationCaptureConfig option = new LocationCaptureConfig.Builder()
                .setMapplsLocationEngineRequest(mapplsLocationEngineRequest)
                .setTimeoutValueInSecond(60)
                .setAccuracy(15.0)
                .setNumberOfAttempts(5)
                .build();
  LocationServiceProviderManager.getInstance().initialise(this, new OnLocationPluginInitialise() {
             @Override
             public void onSuccess() {
                LocationServiceProviderManager.getInstance().setLocationCaptureConfig(option); 
             }

             @Override
             public void onFailure(int code, String reason) {
                
             }
    });
  
       
 

Configuration Parameters

LocationCaptureConfig

Parameter	Description	Default
Interval	Preferred location update interval	5 seconds
Accuracy	Minimum acceptable accuracy (meters)	15m
Timeout	Maximum time SDK attempts location fetch	60 seconds
NumberofAttempts	Maximum location packets	5

MapplsLocationEngineRequest

Parameter	Description	Default
Priority	Location priority mode	HIGH_ACCURACY
Displacement	Minimum movement required	0 meters

The SDK automatically stops once accuracy OR timeout/attempt limit is reached.

Location Fetch Methods

1. Single-Shot Location Fetch

Fetches one valid location snapshot and terminates automatically.

Kotlin

     LocationServiceProviderManager.getInstance()
            .getOneTimeLocation(object : MapplsLocationListener {
                override fun onLocation(mapplsLocationData: MapplsLocationData) {
                    val log = "MapplsLocationData{" +
                            "lat=" + mapplsLocationData.getLocation().getLatitude() +
                            ", lng=" + mapplsLocationData.getLocation().getLongitude() +
                            ", accuracy=" + mapplsLocationData.getLocation().getAccuracy() +
                            ", provider=" + mapplsLocationData.getLocation().getProvider() +
                            ", time=" + mapplsLocationData.getLocation().getTime() +
                            ", isAcceptable=" + mapplsLocationData.isAcceptable() +
                            ", isMockLocation=" + mapplsLocationData.isMockLocation() +
                            "}"
                    Log.d("location", log)
                }

                override fun onError(code: Int, reason: String) {
                    Toast.makeText(this@MainActivity, reason.toString(), Toast.LENGTH_SHORT).show()
                }
            })

Java

      LocationServiceProviderManager.getInstance().getOneTimeLocation(new MapplsLocationListener() {
                    @Override
                    public void onLocation(MapplsLocationData mapplsLocationData) {
                        
                    
                    }

                    @Override
                    public void onError(int code, String reason) {
                        Toast.makeText(MainActivity.this, reason.toString(), Toast.LENGTH_SHORT).show();
                    }
                });

2. Subscribed Location Fetch (Limited)

Continuously receives location updates until accuracy or timeout is met, then auto-unsubscribes.

  
    LocationServiceProviderManager.getInstance()
            .subscribeLocationUpdate(object : MapplsLocationListener {
                override fun onLocation(mapplsLocationData: MapplsLocationData) {
                    val log = "MapplsLocationData{" +
                            "lat=" + mapplsLocationData.getLocation().getLatitude() +
                            ", lng=" + mapplsLocationData.getLocation().getLongitude() +
                            ", accuracy=" + mapplsLocationData.getLocation().getAccuracy() +
                            ", provider=" + mapplsLocationData.getLocation().getProvider() +
                            ", time=" + mapplsLocationData.getLocation().getTime() +
                            ", isAcceptable=" + mapplsLocationData.isAcceptable() +
                            ", isMockLocation=" + mapplsLocationData.isMockLocation() +
                            "}"
                    Log.d("location", log)
                }

                override fun onError(code: Int, reason: String) {
                    Toast.makeText(this@MainActivity, reason.toString(), Toast.LENGTH_SHORT).show()
                }
            })

Java

    LocationServiceProviderManager.getInstance().subscribeLocationUpdate(new MapplsLocationListener() {
                    @Override
                    public void onLocation(MapplsLocationData mapplsLocationData) {
                        String log = "MapplsLocationData{" +
                                "lat=" + mapplsLocationData.getLocation().getLatitude() +
                                ", lng=" + mapplsLocationData.getLocation().getLongitude() +
                                ", accuracy=" + mapplsLocationData.getLocation().getAccuracy() +
                                ", provider=" + mapplsLocationData.getLocation().getProvider() +
                                ", time=" + mapplsLocationData.getLocation().getTime() +
                                ", isAcceptable=" + mapplsLocationData.isAcceptable() +
                                ", isMockLocation=" + mapplsLocationData.isMockLocation() +
                                "}";
                        Log.d("location",log);
                    
                    }

                    @Override
                    public void onError(int code, String reason) {
                        Toast.makeText(MainActivity.this, reason.toString(), Toast.LENGTH_SHORT).show();
                    }
                });

Output Details

Each successful callback provides:

• Latitude & Longitude
• Accuracy (meters)
• Timestamp
• Provider / mode
• Mock location flag
• Acceptable accuracy flag

Error Codes

During Initialization

Error Code	Message	Description
10	UnknownHostException	Returned when there is no internet connectivity during SDK initialization
11	Exception message	Returned for any unexpected exception during the initialization API call

During Function Calls

Error Code	Message	Description
12	LocationPlugin not initialized properly	Function invoked before SDK initialization or before onSuccess() callback
13	Missing location permission	Required location permission not granted by the user
14	GPS is not enabled	Device GPS / location service is disabled

For any queries and support, please contact:

Email us at apisupport@mappls.com

Support Need support? contact us!

@ Copyright 2025 CE Info Systems Ltd. All Rights Reserved.

Terms & Conditions | Privacy Policy | Supplier Sustainability Policy | Health & Safety Policy | Environmental Policy & CSR Report

Customer Care: +91-9999333223