Mappls Camera SDK

---

Table of Contents

1. Introduction
2. Primary Objectives & Overview
3. Key Use Cases
4. Android SDK Integration
5. Product Overview
6. Overlay Components
7. SDK Configuration Attributes
8. Nearby Mappls PIN Selection
9. Output & Data Return Mechanism

1. Introduction & Background

The Mappls Camera SDK is a camera-based plugin designed for seamless integration into mobile application. It augments standard device camera functionality with rich, accurate geo-information derived from Mappls's location intelligence stack — including reverse geocoding, Mappls PINs (eLoc), and map-based visual context.

Despite providing its own default UI, the SDK is designed to be highly customizable so that consuming applications can tailor both the visual presentation and the data returned. It supports both static image capture and video recording.

Data is surfaced to the consuming application through two complementary mechanisms:

2. Primary Objectives

The primary objective of the Mappls Camera SDK is to embed accurate, trustworthy geo-information within images and videos at the point of capture — making that media a verifiable record of both what was captured and where (and when) it was captured.

This serves two high-level needs:

1. Geo-tagged Media as Evidence: Enable organisations to validate that field personnel, field visits, or events actually occurred at the claimed location, thereby combating fraud and errors in downstream services.
2. Location Intelligence Enrichment: Augment any use case involving photo/video capture with precise, human-readable, and machine-readable location data from the Mappls platform.

3. Use Cases

3.1 Field Visit Validation

Organisations deploying field agents (e.g., financial institutions, insurance companies, logistics providers, government services) can embed geo-information in photos captured at the point of visit. This creates an auditable, tamper-evident record validating that the field agent was physically present at the correct location.

Example: A bank agent photographs a customer's premises. The captured image contains the precise coordinates, reverse-geocoded address, Mappls PIN, and timestamp. The bank's backend system can automatically verify this against the expected address on record.

3.2 Digital KYC & Self-Verification

During self-service Digital KYC flows, users capture photos or videos of themselves or their documents. Embedding live geo-information ensures the self-KYC was completed from the expected location, reducing fraud risk.

3.3 Face-Recognition Login with Location Intelligence

Consuming apps implementing face-recognition-based login can use the SDK to simultaneously capture location data alongside the biometric. This merges biometric security with location intelligence — the app knows not only who logged in but where they logged in from.

3.4 Asset & Infrastructure Surveys

Field teams conducting surveys of assets, infrastructure, or real estate can capture geo-tagged photos and videos as a reliable ground-truth record that is easily indexed and audited.

3.5 Delivery & Logistics Proof-of-Delivery

Delivery agents can capture geo-tagged photos at the point of delivery, providing end-to-end traceability that links the delivery record to the physical location.

3.6 Insurance Claims Documentation

Claims investigators can capture geo-tagged photos of damage sites, providing insurers with credible, location-verified documentation.

4. Android SDK Integration

Add the dependency

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

Kotlin (build.gradle.kts)

implementation("com.mappls.sdk:mappls-camera:1.0.0")

Groovy (build.gradle)

implementation 'com.mappls.sdk:mappls-camera:1.0.0'

4.1 Layout Integration

<com.mappls.sdk.camera.MapplsCameraView 
android:id="@+id/camera" 
android:layout_width="match_parent" 
android:layout_height="match_parent"/>

4.2 Initialization

Kotlin

 val option = MapplsCameraOption.Builder() 
     .setCameraFacing(CameraFacing.REAR) 
     .setFlashMode(FlashMode.AUTO) 
     .setDefaultMediaMode(MediaMode.PHOTO) 
     .build()
mBinding.camera.initialize(option.build())

5. Product Overview

5.1 Media Output Types

Output Type	Description
Static Image	Single captured photo with geo-information overlay and embedded metadata
Video	Recorded video with real-time geo-information overlay rendered onto frames and metadata embedded in the video container

5.2 Default UI

The SDK ships with a ready-to-use default camera UI that includes:

• Live camera viewfinder
• Photo / Video mode toggle
• Capture button
• Camera switch button (front / rear)
• Flash toggle (rear camera only)
• Real-time geo-information overlay on the viewfinder
• Nearby Mappls PIN selector panel (swipe-up sheet)
• Branding logo area (top-right, configurable by consuming app)

All UI elements are customisable by the consuming application via configuration parameters and theming APIs.

6. Overlay Components

6.1.1 Map Thumbnail

• A small static map image (approximately 80×80dp) showing the current location pinned on the map.
• The map style should match Mappls's standard map style with a green marker pin at the current location.
• The Mappls logo is rendered in the bottom-left corner of the thumbnail.
• The thumbnail is positioned in the bottom-left of the overlay panel.

6.1.2 Mappls PIN (eLoc) URL

• Displayed as a formatted URL: mappls.com/{eloc}
  • Example: mappls.com/mmi000
• The eLoc portion is rendered in the Mappls brand colour (teal/green) to visually distinguish it.
• Rendered in the overlay panel header row.

6.1.3 Reverse-Geocoded Address

• Human-readable address derived from real-time reverse geocoding of the current coordinates via the Mappls Reverse Geocoding API.
• Displayed in 2–3 lines to maintain readability.
• Should include: building/place name (if available), street/area, city, state, PIN code.
• Example: 237, Okhla Industrial Estate Phase 3, Near Modi Mill, New Delhi, Delhi, 110020

6.1.4 Coordinates

• Displayed as decimal degrees: {latitude},{longitude}
  • Example: 28.550697, 77.268890
• Precision: 6 decimal places.

6.1.5 Date & Time

• Format: DD-MM-YYYY, HH:MM:SS (24-hour clock).
• The timestamp is captured at the moment of image shutter release or continually updated from the start of video recording, and is NOT frozen (updated continuously mid-video).
• Example: 08-04-2026, 17:25:11

6.1.6 QR Code

• A small QR code (approximately 64×64dp) positioned in the bottom-right of the overlay panel.
• The QR code can be configured to encode either:
  • The Mappls PIN URL: https://mappls.com/{eloc} (default)
  • The coordinate-based Mappls portal URL: https://mappls.com/@{latitude},{longitude}
    • Example: https://mappls.com/@28.5503,77.2502
• Scanning the QR code should take the user directly to the location on Mappls.

6.1.7 Branding Logo (Consuming App)

• A configurable logo supplied by the consuming application.
• Positioned in the top-right corner of the image/video frame (outside the geo-information overlay panel).
• Recommended maximum size: 100×40dp.
• Supports PNG with transparency.

6.1.8 Accuracy Indicator (Recommended Addition)

• Display the GPS accuracy radius in metres (e.g., ± 4 m) alongside the coordinates.
• Helps reviewers assess location confidence. A colour-coded indicator (green: ≤ 10 m, amber: 10–50 m, red: > 50 m) can be rendered as a small icon.

6.1.9 Network/Data Source Indicator (Recommended Addition)

• A small icon indicating the location source: GPS, Network, or Fused.
• Adds transparency about how the location was determined.

6.1.10 Altitude (Recommended Addition)

• Display altitude in metres above sea level where available.
• Particularly valuable for multi-storey building verification and infrastructure surveys.
• Example: Alt: 212 m

6.1.11 Device Heading / Compass Bearing (Recommended Addition)

• Display compass bearing (0°–360°) at the time of capture.
• Useful for directional documentation (e.g., photograph was taken facing north-east).

6.1.12 Client Text / Two line Text (Requested Addition)

Display two lines of limited textual information. (we can recommend string length limits) Useful when client wishes to highlight some of their own app's context (which employee captured this image by their name & employee id).

6.2 Overlay on Video

For video, the overlay is burned into the video frames and is not a separate subtitle/metadata track. Unlike a static image capture, the geo-information displayed in the overlay is updated at a defined refresh frequency throughout the duration of the recording, so that the burned-in overlay reflects location changes as the device moves.

Refresh behaviour:

• The overlay refresh interval is controlled by the videoOverlayRefreshInterval configuration parameter (see Section 7.1).
• Minimum interval: 2 seconds. Values below 2 seconds will be clamped to 2 seconds.
• Default interval: 5 seconds.
• At each refresh tick, the following overlay elements are updated with the latest available values: coordinates, GPS accuracy, altitude, compass bearing, and the map thumbnail. The date-time display is also updated to reflect the current time of that tick.
• The reverse-geocoded address and Mappls PIN (eLoc) are also refreshed at each tick on a best-effort basis, subject to API response latency. If a fresh reverse-geocoding response has not arrived before the next tick, the last successfully received values are retained on the overlay.
• The QR code is regenerated at each refresh tick to reflect the updated coordinates or eLoc.
• The overlay remains continuously visible throughout the recording; only its content is updated at the defined interval.

7. SDK Configuration Attributes

The consuming application configures the SDK through a MapplsCameraConfig (Android) / MapplsCameraConfiguration (iOS) object passed at SDK initialisation.

7.1 Core Configuration Parameters

Parameter	Type	Default	Description
showAddressOverlay	Boolean	true	Show/hide reverse-geocoded address in the overlay
showCoordinatesOverlay	Boolean	true	Show/hide latitude/longitude in the overlay
showDateTimeOverlay	Boolean	true	Show/hide date and time in the overlay
showMapThumbnail	Boolean	true	Show/hide the mini map thumbnail in the overlay
showElocationOverlay	Boolean	true	Show/hide the Mappls PIN URL in the overlay
showQRCodeOverlay	Boolean	true	Show/hide the QR code in the overlay
showAccuracyIndicator	Boolean	true	Show/hide the GPS accuracy indicator
showAltitudeOverlay	Boolean	false	Show/hide altitude in the overlay
showCompassBearingOverlay	Boolean	false	Show/hide device compass bearing
cameraFacing	Enum	REAR	REAR or FRONT
flashMode	Enum	AUTO	ON, OFF, AUTO (rear camera only)
defaultMediaMode	Enum	PHOTO	PHOTO or VIDEO — initial mode on launch
allowModeSwitching	Boolean	true	Allow user to switch between Photo and Video modes
enableNearbyPINSelection	Boolean	true	Allow user to pick a nearby Mappls PIN
nearbyPINSearchRadius	Integer (metres)	500	Radius for fetching nearby Mappls PINs
maxNearbyPINResults	Integer	20	Maximum number of nearby PINs shown
qrCodeContent	Enum	ELOC_URL	ELOC_URL or COORDINATE_URL
brandingLogo	Drawable/UIImage	null	Consuming app's branding logo for top-right corner
overlayOpacity	Float (0.0–1.0)	0.75	Transparency of the geo-information overlay panel
overlayPosition	Enum	BOTTOM	BOTTOM or TOP — position of the overlay panel
maxVideoDuration	Integer (seconds)	0 (unlimited)	Maximum allowed video recording duration; 0 = unlimited
imageOutputFormat	Enum	JPEG	JPEG or PNG
imageCompressionQuality	Float (0.0–1.0)	0.92	JPEG compression quality
videoResolution	Enum	HD_1080P	SD_480P, HD_720P, HD_1080P, UHD_4K
enableWatermarkProtection	Boolean	false	Embed a cryptographic hash of geo-metadata into the image to enable tamper detection
videoOverlayRefreshInterval	Integer (seconds)	5	Frequency at which the geo-information overlay is updated and re-rendered onto video frames during recording. Minimum enforced value: 2 seconds; values below this are clamped to 2. Applies to video mode only. Note: embedded video container metadata always reflects start-of-recording values regardless of this setting (see Section 6.2.1).
minimumAccuracyMetres	Float	50.0	If GPS accuracy is worse than this threshold, show a warning and optionally block capture
blockCaptureOnPoorAccuracy	Boolean	false	Prevent capture if accuracy is worse than minimumAccuracyMetres
saveToDeviceGallery	Boolean	true	Save captured image/video to device gallery
addressLanguage	String (BCP-47)	"en"	Language for reverse geocoded address (e.g., "hi" for Hindi)

7.2 Recommended Additional Configuration Parameters

Parameter	Type	Default	Description
overlayFont	FontConfig	System default	Custom font family and size for overlay text
overlayTextColour	Colour	White	Custom text colour for the overlay
overlayBackgroundColour	Colour	Dark	Custom background colour for the overlay panel
overlayCornerRadius	Float (dp)	8	Corner radius of the overlay panel
mapThumbnailStyle	Enum	STANDARD	STANDARD, SATELLITE, HYBRID — map thumbnail style
customWatermarkText	String	null	Additional custom text line to append to the overlay (e.g., employee ID)
allowCameraRollImport	Boolean	false	Allow user to pick an image from gallery (for re-processing / adding overlay)
enableSilentCapture	Boolean	false	Suppress shutter sound on capture (where device policy permits)
timerDelay	Enum	NONE	NONE, 3_SECONDS, 10_SECONDS — self-timer before capture
captureCountLimit	Integer	0 (unlimited)	Limit the number of images that can be captured in one session
showGridLines	Boolean	false	Show rule-of-thirds grid lines on the viewfinder
enablePinchToZoom	Boolean	true	Allow pinch-to-zoom on the viewfinder
maxZoomFactor	Float	8.0	Maximum allowed zoom factor

8. Nearby Mappls PIN Selection

When enableNearbyPINSelection is true, the SDK displays an option for the user to browse and select a nearby Mappls PIN to associate with the captured image/video. This is particularly useful when the GPS pin resolves to a compound or building with multiple registered units (e.g., a multi-tenant industrial estate).

8.1 Behaviour

• The nearby PINs are fetched from the Mappls Nearby Search API using the current coordinates and nearbyPINSearchRadius.
• Results are sorted in ascending order of distance from the current location.
• Distance is displayed alongside each result in metres (< 1 km) or kilometres (≥ 1 km).
• The nearest PIN is pre-selected by default.
• The user may select a different PIN if the pre-selected one is incorrect (e.g., they are inside a compound with multiple registered places).
• Each result displays:
  • The Mappls PIN URL (e.g., mappls.com/mmi000) in brand teal
  • Place name (bold)
  • Full formatted address
  • Distance from current location (right-aligned)
• The selected PIN is used to populate the overlay eLoc URL and QR code content.

8.2 API Response Handling

If the Mappls Nearby Search API returns no results within the configured radius, the SDK falls back to using the nearest reverse-geocoded address. The overlay still displays coordinates, address, and timestamp, but the eLoc URL and QR code will use the coordinate-based URL format (mappls.com/@{lat},{lng}).

9. Output & Data Return Mechanism

The SDK returns a rich data object to the consuming application through both pull and push mechanisms.

9.1 Data Model: MapplsCameraResult

Field	Type	Description
mediaType	Enum	IMAGE or VIDEO
filePath	String	Absolute path to the output file on device storage
latitude	Double	Captured latitude (decimal degrees)
longitude	Double	Captured longitude (decimal degrees)
altitude	Double	Altitude in metres (if available)
accuracyMetres	Float	GPS horizontal accuracy at time of capture
locationSource	Enum	GPS, NETWORK, FUSED
eloc	String	Mappls PIN code (e.g., mmi000); null if unavailable
elocUrl	String	Full Mappls PIN URL (e.g., https://mappls.com/mmi000)
formattedAddress	String	Reverse-geocoded address string
addressComponents	Object	Structured address (subLocality, locality, city, state, pinCode, country)
timestamp	Long	Unix epoch milliseconds at time of capture
timestampFormatted	String	DD-MM-YYYY, HH:MM:SS formatted timestamp
compassBearing	Float	Device heading in degrees (0–360); NaN if unavailable
cameraFacing	Enum	FRONT or REAR
videoDuration	Long	Duration in milliseconds (video only); 0 for images
imageDimensions	Object	{ width, height } in pixels (image only)
sdkVersion	String	Mappls Camera SDK version
selectedNearbyPIN	Object	The Mappls PIN entry selected by user (if PIN selection was enabled)
tamperHash	String	Cryptographic hash for tamper detection (if enableWatermarkProtection is true)

9.2 Push Mechanism (Callbacks / Delegates)

Android — Interface: MapplsCameraCallback

interface MapplsCameraCallback {
  fun onCaptureCancelled(){}
  fun onImageCaptured(result: MapplsCameraResult)
  fun onVideoCaptured(result: MapplsCameraResult)
  fun onError(errorCode: Int, errorMessage: String)

  fun onCancel()
  fun onLocationUpdated(latitude: Double, longitude: Double, accuracyMetres: Float)
  fun permissionResultCallback(cameraGranted: Boolean, audioGranted:Boolean,locationGranted: Boolean){}
  fun onNearbyPINsLoaded(pins: List<ReverseGeocodeNearbyResult>){}
  fun onCameraZoomChanged(newValue: Float){}
}

9.3 Pull Mechanism (Getter Methods)

The SDK exposes getter methods that can be called at any time after a capture:

Android (MapplsCamera object)

MapplsCamera.getLastCapturedResult(): MapplsCameraResult?
MapplsCamera.getLastLocation(): Location?
MapplsCamera.getLastEloc(): String?
MapplsCamera.getLastFormattedAddress(): String?

9.4 Error Codes

Code	Constant	Description
1001	ERR_CAMERA_PERMISSION_DENIED	Camera permission not granted
1002	ERR_LOCATION_PERMISSION_DENIED	Location permission not granted
1003	ERR_LOCATION_UNAVAILABLE	Device location could not be determined
1004	ERR_POOR_ACCURACY	GPS accuracy worse than minimumAccuracyMetres and blockCaptureOnPoorAccuracy is true
1005	ERR_GEOCODING_FAILED	Reverse geocoding API call failed
1006	ERR_STORAGE_FULL	Insufficient device storage to save media
1007	ERR_NEARBY_SEARCH_FAILED	Nearby Mappls PIN fetch failed
1008	ERR_FILE_WRITE_FAILED	Output file could not be written
1009	ERR_SDK_NOT_INITIALISED	SDK used before initialisation
1010	ERR_API_KEY_INVALID	Mappls API key is invalid or expired

For any queries and support, please contact:

Email us at apisupport@mappls.com

Support Need support? contact us!

@ Copyright 2026 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