Skip to main content

API Reference

Complete API reference for the MOSA Mobile SDK across all platforms.

Overview​

This section provides comprehensive API documentation for all SDK methods, models, and enums. APIs are organized by functional domain and include multi-platform code examples. All APIs are designed to be consistent across Android, iOS, and Flutter platforms.

Table of Contents​

Initialization​

Initialize the SDK with API key and user ID. See Getting Started for detailed initialization instructions.

val sdk = MOSADockSDK.builder()
    .setActivity(this)
    .setApiKey("your-api-key")
    .setUserId("user-123")
    .setAutoRequestPermissions(true)
    .build()

Unlock Key Management​

The SDK provides unlock key management for authenticating and authorizing dock operations. Unlock keys are temporary cryptographic keys requested from the backend with a limited validity period (typically 15 minutes).

requestUnlockKey​

Request an unlock key for dock operations. The SDK provides different unlock key types for various dock operations. Each type has specific required arguments.

Parameters:

  • type (UnlockKeyType) - Type of unlock key (bikeLock, bikeUnlock, rentBikeUnlock, rentBikeLock, testLock)
  • areaId (String, optional) - Area ID (required for bikeLock, rentBikeUnlock, rentBikeLock, testLock)

Returns: UnlockKey object or null if request fails

Unlock Key Types​

bikeLock​

Use Case: Lock a bike at a parking area

Required Arguments: areaId (String) - ID of the parking area

val unlockKey = sdk.requestUnlockKey(
    type = MOSADockUnlockKeyType.BikeLock,
    areaId = "area-123"
)
bikeUnlock​

Use Case: Unlock a bike from a parking dock

Required Arguments: None

val unlockKey = sdk.requestUnlockKey(
    type = MOSADockUnlockKeyType.BikeUnlock
)
rentBikeUnlock​

Use Case: Rent/unlock a bike from a sharing area

Required Arguments: areaId (String) - ID of the sharing area

val unlockKey = sdk.requestUnlockKey(
    type = MOSADockUnlockKeyType.RentBikeUnlock,
    areaId = "area-123"
)
rentBikeLock​

Use Case: Return/lock a bike at a sharing area

Required Arguments: areaId (String) - ID of the sharing area

val unlockKey = sdk.requestUnlockKey(
    type = MOSADockUnlockKeyType.RentBikeLock,
    areaId = "area-123"
)
testLock​

Use Case: Perform a test unlock. The dock won't go into the in-use state and remains ready for use again after attaching the chain back.

Required Arguments: areaId (String) - ID of the test area

val unlockKey = sdk.requestUnlockKey(
    type = MOSADockUnlockKeyType.TestLock,
    areaId = "area-123"
)

getLastStoredUnlockKey​

Retrieve the last stored unlock key from local cache.

val lastKey = sdk.getLastStoredUnlockKey()

Returns: UnlockKey object or null if no key is stored

Dock Operations​

unlockSmartLock / handleClientUnlock​

Execute dock unlock/lock operation. This method handles the complete flow: NFC scanning, BLE connection, key transmission, and dock state changes.

sdk.unlockSmartLock(
    unlockKey = unlockKey,
    gfaLocationType = MOSADockLocationType.PARKING,
    callback = callback
)

Parameters:

  • unlockKey (UnlockKey) - The unlock key obtained from requestUnlockKey()
  • locationType (LocationType) - Location type: parking or sharing

Callbacks: See SDK Callbacks for complete callback documentation

Area Management​

getAreas​

Search and retrieve areas with optional filters.

val areas = sdk.getAreas(
    status = "active",
    areaType = "parking",
    query = "downtown",
    page = 1,
    limit = 20
)

Parameters:

  • status (String, optional) - Filter by area status
  • areaType (String, optional) - Filter by area type (parking/sharing)
  • query (String, optional) - Search query
  • page (Int, default: 1) - Page number
  • limit (Int, default: 20) - Results per page
  • sortBy (String, default: "name") - Sort field
  • sortOrder (String, default: "asc") - Sort order (asc/desc)

Returns: AreaSearchResponse containing list of areas and pagination info

getAreasForMap​

Retrieve areas within a geographic radius for map display.

val areas = sdk.getAreasForMap(
    areaType = "parking",
    latitude = 37.7749,
    longitude = -122.4194,
    radius = 1000.0,
    limit = 100
)

Parameters:

  • areaType (String, optional) - Filter by area type
  • status (String, optional) - Filter by area status
  • latitude (Double) - Center latitude
  • longitude (Double) - Center longitude
  • radius (Double, optional) - Search radius in meters
  • limit (Int, default: 100) - Maximum results

Returns: AreaSearchResponse containing list of areas

Session Management​

getCurrentSession​

Retrieve the current active session, if any.

val currentSession = sdk.getCurrentSession()

Returns: Session object or null if no active session

getSessionHistory​

Retrieve paginated session history for the current user.

val history = sdk.getSessionHistory(
    page = 1,
    limit = 20
)

Parameters:

  • page (Int, default: 1) - Page number
  • limit (Int, default: 20) - Results per page

Returns: SessionHistoryResponse containing list of sessions and pagination info

getSessionStatistics​

Retrieve session statistics for the current user.

val stats = sdk.getSessionStatistics()

Returns: SessionStatistics object with aggregated session data

Device Capabilities​

isBLESupported​

Check if the device supports Bluetooth Low Energy.

val supported = sdk.isBLESupported()

Returns: Boolean indicating BLE support

isNFCSupported​

Check if the device supports NFC.

val supported = sdk.isNFCSupported()

Returns: Boolean indicating NFC support

isBLEEnabled​

Check if Bluetooth is currently enabled on the device.

val enabled = sdk.isBLEEnabled()

Returns: Boolean indicating if BLE is enabled

isNFCEnabled​

Check if NFC is currently enabled on the device.

val enabled = sdk.isNFCEnabled()

Returns: Boolean indicating if NFC is enabled

Permission Management​

checkAndRequestPermissions​

Check and request all required permissions for SDK operations.

val granted = sdk.checkAndRequestPermissions()

Returns: Boolean indicating if all permissions were granted

hasRequiredPermissions​

Check if all required permissions are currently granted.

val hasPermissions = sdk.hasRequiredPermissions()

Returns: Boolean indicating if all required permissions are granted

getMissingPermissions​

Get a list of missing required permissions.

val missing = sdk.getMissingPermissions()

Returns: List of permission names that are missing

Sync Operations​

forceSyncNow​

Manually trigger synchronization of pending events to the backend.

sdk.forceSyncNow()

getPendingEventsCount​

Get the number of events pending synchronization.

val count = sdk.getPendingEventsCount()

Returns: Integer count of pending events

See Also: Offline and Sync for detailed sync documentation

Evidence Management​

storeEvidencePhoto​

Store an evidence photo for a session.

val photoId = sdk.photoOperations().storeEvidencePhoto(
    sessionId = "session-123",
    photoPath = "/path/to/photo.jpg"
)

Parameters:

  • sessionId (String) - Session ID to associate the photo with
  • photoPath (String) - Local file path to the photo

Returns: String photo ID

getEvidencePhotos​

Retrieve evidence photos for a session.

val photos = sdk.photoOperations().getEvidencePhotos("session-123")

Parameters:

  • sessionId (String) - Session ID

Returns: List of evidence photo objects

getEvidencePhotoURL​

Get the URL for an evidence photo.

val url = sdk.photoOperations().getEvidencePhotoURL("photo-123")

Parameters:

  • photoId (String) - Photo ID

Returns: String URL to the photo

Event Streams​

The SDK provides reactive event streams for real-time updates. Subscribe to these streams to receive callbacks and state changes.

dockCallbackEvents​

Stream of dock operation callbacks (NFC scan, BLE connection, dock state changes, etc.).

// Android uses callback interface, not streams
sdk.unlockSmartLock(
    unlockKey = unlockKey,
    gfaLocationType = MOSADockLocationType.PARKING,
    callback = object : MOSADockSDKCallback {
        override fun onNFCScanCompleted(mosaTag: MosaTag) { }
        override fun onBleConnected() { }
        // ... other callbacks
    }
)

See Also: SDK Callbacks for complete callback documentation

syncStateEvents​

Stream of sync state changes (syncing, idle, error).

sdk.isSyncingStateFlow().collect { syncing ->
    // Handle sync state
}

bleConnectionStateEvents​

Stream of BLE connection state changes.

sdk.getBleConnectionStateFlow().collect { connected ->
    // Handle connection state
}

sdkLogs​

Stream of SDK log messages for debugging.

// Enable advanced logging during initialization
val sdk = MOSADockSDK.builder()
    .setAdvancedLogging(true)
    .build()

Data Models​

UnlockKey​

The UnlockKey represents a temporary cryptographic key used to authenticate and authorize dock operations. Keys are requested from the backend and have a limited validity period (typically 15 minutes).

Properties:

  • keyId (String, non-null) - Unique identifier for the key
  • sessionId (String, non-null) - Associated session ID
  • token (Array of integers, non-null) - The actual unlock token
  • expiryTime (Integer, non-null) - Expiry time as Unix timestamp (seconds)
  • keyType (UnlockKeyType, non-null) - Type of unlock key (enum)
  • userId (String, nullable) - User ID
  • assetId (String, nullable) - Asset ID
  • areaId (String, nullable) - Area ID

Usage Example:

lifecycleScope.launch {
    // Request key
    val unlockKey = sdk.requestUnlockKey(
        type = MOSADockUnlockKeyType.BikeLock,
        areaId = "area-123"
    )
    
    if (unlockKey != null && !unlockKey.isExpired) {
        // Use key for dock operation
        sdk.unlockSmartLock(
            unlockKey = unlockKey,
            gfaLocationType = MOSADockLocationType.PARKING,
            callback = this@MainActivity
        )
    } else {
        // Handle expired or null key
        showError("Key expired or request failed")
    }
}

Session​

Represents a single bike/dock usage period. Sessions are automatically created and managed by the SDK.

Properties:

  • id (String) - Unique session identifier
  • userId (String) - User ID associated with the session
  • areaId (String, nullable) - Area ID where the session takes place
  • dockId (String, nullable) - Dock ID where the session takes place
  • factoryDockId (String, nullable) - Factory dock ID (hardware identifier)
  • bikeId (String, nullable) - Bike ID associated with the session
  • status (SessionStatus) - Current session status
  • startTime (DateTime, nullable) - Session start time
  • endTime (DateTime, nullable) - Session end time
  • createdAt (DateTime) - Session creation time
  • updatedAt (DateTime) - Session last update time
  • usageTime (Double, nullable) - Usage time in seconds
  • areaName (String, nullable) - Area name (populated from area data)
  • areaType (AreaType, nullable) - Area type (populated from area data)
  • areaFormattedAddress (String, nullable) - Area formatted address
  • areaLocationPin (GeoJSONPoint, nullable) - Area location pin
  • areaGeoFencePath (GeoJSONPolygon, nullable) - Area geofence path
  • areaShadowPolygon (GeoJSONPolygon, nullable) - Area shadow polygon
  • evidenceImageId (String, nullable) - Evidence image ID
  • evidenceImageUrl (String, nullable) - Evidence image URL
  • metadata (String, nullable) - Additional metadata as JSON string

Area​

Represents a parking or sharing area.

Properties:

  • id (String) - Unique area identifier
  • name (String) - Area name
  • type (AreaType) - Area type (parking or sharing)
  • status (String) - Area status
  • formattedAddress (String, nullable) - Formatted address
  • locationPin (GeoJSONPoint, nullable) - Location coordinates
  • geoFencePath (GeoJSONPolygon, nullable) - Geofence boundary
  • shadowPolygon (GeoJSONPolygon, nullable) - Map display polygon
  • images (List<String>, nullable) - Image URLs
  • level (AreaLevel, nullable) - Area level (overground or underground)

MosaTag​

Represents NFC tag data read from a dock during scanning.

Properties:

  • macAddress (String) - Dock MAC address
  • tagData (String) - Raw tag data
  • dockId (String, nullable) - Dock ID if available

Enums​

UnlockKeyType​

Defines the purpose of an unlock key. The UnlockKeyType enum defines the purpose of an unlock key.

Values:

  • bikeLock - Lock a bike at a parking area
  • bikeUnlock - Unlock a bike from a parking dock
  • rentBikeUnlock - Rent/unlock a bike from a sharing area
  • rentBikeLock - Return/lock a bike at a sharing area
  • testLock - Perform a test unlock. The dock won't go into the in-use state and remains ready for use again after attaching the chain back.

LocationType​

Defines the location context for dock operations.

Values:

  • parking - Parking area context
  • sharing - Sharing area context

SessionStatus​

Defines the current state of a session.

Values:

  • created - Session created but not yet active
  • active - Session is currently active
  • completed - Session completed successfully
  • failed - Session failed
  • cancelled - Session was cancelled

AreaType​

Defines the type of area.

Values:

  • parking - Parking area
  • sharing - Sharing area

AreaLevel​

Defines the level of an area.

Values:

  • overground - Above ground level
  • underground - Below ground level