Docs / readme
This commit is contained in:
@@ -0,0 +1,389 @@
|
||||
# Android Device Info Library - API Documentation
|
||||
|
||||
This document provides a comprehensive reference for all classes, functions, and properties available in the Android Device Info library.
|
||||
|
||||
## Table of Contents
|
||||
|
||||
- [AndroidInfo Object](#androidinfo-object)
|
||||
- [DeviceInfo Object](#deviceinfo-object)
|
||||
- [AndroidDeviceInfo Object](#androiddeviceinfo-object)
|
||||
- [AltDeviceNames Object](#altdevicenames-object)
|
||||
- [DeviceDatabase Class](#devicedatabase-class)
|
||||
- [Device Types](#device-types)
|
||||
- [Data Classes](#data-classes)
|
||||
|
||||
---
|
||||
|
||||
## AndroidInfo Object
|
||||
|
||||
The main object for accessing static device information and type detection.
|
||||
|
||||
### Properties
|
||||
|
||||
#### Info Object
|
||||
Access to basic device information from `Build` class:
|
||||
|
||||
```kotlin
|
||||
AndroidInfo.Info.brand: String // Device brand (e.g., "samsung")
|
||||
AndroidInfo.Info.model: String // Device model (e.g., "SM-G998U")
|
||||
AndroidInfo.Info.device: String // Device name (e.g., "p3qsqw")
|
||||
AndroidInfo.Info.product: String // Product name
|
||||
AndroidInfo.Info.manufacturer: String // Manufacturer (e.g., "Samsung")
|
||||
AndroidInfo.Info.hardware: String // Hardware name
|
||||
AndroidInfo.Info.board: String // Board name
|
||||
AndroidInfo.Info.fingerprint: String // Build fingerprint
|
||||
```
|
||||
|
||||
#### Version Object
|
||||
Access to Android version information:
|
||||
|
||||
```kotlin
|
||||
AndroidInfo.Version.release: String // Android version (e.g., "13")
|
||||
AndroidInfo.Version.incremental: String // Incremental version
|
||||
AndroidInfo.Version.sdkInt: Int // SDK version number (e.g., 33)
|
||||
AndroidInfo.Version.codename: String // Version codename
|
||||
```
|
||||
|
||||
#### Device Detection Properties
|
||||
|
||||
```kotlin
|
||||
AndroidInfo.isEmulator: Boolean // True if running on emulator
|
||||
AndroidInfo.isPhysicalDevice: Boolean // True if running on physical device
|
||||
```
|
||||
|
||||
### Functions
|
||||
|
||||
#### getType(context: Context): DeviceType
|
||||
Determines the type of device.
|
||||
|
||||
**Parameters:**
|
||||
- `context: Context` - Application context
|
||||
|
||||
**Returns:** `DeviceType` enum value
|
||||
|
||||
**Example:**
|
||||
```kotlin
|
||||
val deviceType = AndroidInfo.getType(context)
|
||||
when (deviceType) {
|
||||
AndroidInfo.DeviceType.SMARTPHONE -> // Handle smartphone
|
||||
AndroidInfo.DeviceType.TABLET -> // Handle tablet
|
||||
// ... other cases
|
||||
}
|
||||
```
|
||||
|
||||
### Vendor-Specific Objects
|
||||
|
||||
Empty objects ready for future vendor-specific functionality:
|
||||
|
||||
```kotlin
|
||||
AndroidInfo.Samsung // Samsung-specific features
|
||||
AndroidInfo.Xiaomi // Xiaomi-specific features
|
||||
AndroidInfo.Oppo // Oppo-specific features
|
||||
AndroidInfo.Huawei // Huawei-specific features
|
||||
AndroidInfo.OnePlus // OnePlus-specific features
|
||||
AndroidInfo.Vivo // Vivo-specific features
|
||||
AndroidInfo.LG // LG-specific features
|
||||
AndroidInfo.Lenovo // Lenovo-specific features
|
||||
AndroidInfo.Sony // Sony-specific features
|
||||
AndroidInfo.Google // Google Pixel-specific features
|
||||
AndroidInfo.Asus // Asus-specific features
|
||||
AndroidInfo.Realme // Realme-specific features
|
||||
AndroidInfo.Motorola // Motorola-specific features
|
||||
AndroidInfo.Nokia // Nokia-specific features
|
||||
AndroidInfo.Honor // Honor-specific features
|
||||
AndroidInfo.Infinix // Infinix-specific features
|
||||
AndroidInfo.Tecno // Tecno-specific features
|
||||
AndroidInfo.ZTE // ZTE-specific features
|
||||
AndroidInfo.Meizu // Meizu-specific features
|
||||
AndroidInfo.Sharp // Sharp-specific features
|
||||
AndroidInfo.Micromax // Micromax-specific features
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## DeviceInfo Object
|
||||
|
||||
Provides async device information retrieval with online API integration.
|
||||
|
||||
### Properties
|
||||
|
||||
```kotlin
|
||||
DeviceInfo.api_url_base: String // Base API URL (default: "https://cdn.oxmc.me/api")
|
||||
DeviceInfo.api_device: String // Device API endpoint
|
||||
DeviceInfo.api_deviceSearch: String // Device search endpoint
|
||||
DeviceInfo.api_reportDevice: String // Device reporting endpoint
|
||||
DeviceInfo.api_version: String // API version (default: "v2")
|
||||
```
|
||||
|
||||
### Functions
|
||||
|
||||
#### getDeviceInfo(context: Context): Array<String?>
|
||||
**Suspend function** - Gets comprehensive device information including image URL.
|
||||
|
||||
**Parameters:**
|
||||
- `context: Context` - Application context
|
||||
|
||||
**Returns:** Array containing:
|
||||
- `[0]` - Device name
|
||||
- `[1]` - Manufacturer
|
||||
- `[2]` - Model
|
||||
- `[3]` - Codename
|
||||
- `[4]` - Image URL (nullable)
|
||||
|
||||
**Example:**
|
||||
```kotlin
|
||||
lifecycleScope.launch {
|
||||
val (name, manufacturer, model, codename, imageUrl) = DeviceInfo.getDeviceInfo(context)
|
||||
// Use the information
|
||||
}
|
||||
```
|
||||
|
||||
#### getDeviceName(context: Context): String
|
||||
Gets the user-configured device name or falls back to manufacturer + model.
|
||||
|
||||
**Parameters:**
|
||||
- `context: Context` - Application context
|
||||
|
||||
**Returns:** Device name string
|
||||
|
||||
**Example:**
|
||||
```kotlin
|
||||
val deviceName = DeviceInfo.getDeviceName(context)
|
||||
```
|
||||
|
||||
#### getDeviceImage(context: Context, codename: String, model: String, manufacturer: String): String?
|
||||
**Suspend function** - Fetches device image URL from API.
|
||||
|
||||
**Parameters:**
|
||||
- `context: Context` - Application context
|
||||
- `codename: String` - Device codename
|
||||
- `model: String` - Device model
|
||||
- `manufacturer: String` - Device manufacturer
|
||||
|
||||
**Returns:** Image URL string or null if not found
|
||||
|
||||
**Example:**
|
||||
```kotlin
|
||||
lifecycleScope.launch {
|
||||
val imageUrl = DeviceInfo.getDeviceImage(context, "p3qsqw", "SM-G998U", "Samsung")
|
||||
// Load image from URL
|
||||
}
|
||||
```
|
||||
|
||||
#### reportDeviceInfo(context: Context, deviceName: String, manufacturer: String, model: String, codename: String): Boolean
|
||||
**Suspend function** - Reports device information to the server.
|
||||
|
||||
**Parameters:**
|
||||
- `context: Context` - Application context
|
||||
- `deviceName: String` - Device name
|
||||
- `manufacturer: String` - Manufacturer
|
||||
- `model: String` - Device model
|
||||
- `codename: String` - Device codename
|
||||
|
||||
**Returns:** True if successful, false otherwise
|
||||
|
||||
---
|
||||
|
||||
## AndroidDeviceInfo Object
|
||||
|
||||
Handles device name resolution and caching.
|
||||
|
||||
### Functions
|
||||
|
||||
#### getCurrentDeviceInfo(context: Context): DeviceInfo
|
||||
**Worker thread function** - Gets current device information with caching.
|
||||
|
||||
**Parameters:**
|
||||
- `context: Context` - Application context (nullable)
|
||||
|
||||
**Returns:** `DeviceInfo` data class instance
|
||||
|
||||
**Example:**
|
||||
```kotlin
|
||||
// Call from background thread
|
||||
val deviceInfo = AndroidDeviceInfo.getCurrentDeviceInfo(context)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## AltDeviceNames Object
|
||||
|
||||
Provides alternative device name mappings for known devices.
|
||||
|
||||
### Functions
|
||||
|
||||
#### getAlternateNameOrDefault(model: String, manufacturer: String, codename: String, default: String): String
|
||||
Gets alternative device name or returns default.
|
||||
|
||||
**Parameters:**
|
||||
- `model: String` - Device model
|
||||
- `manufacturer: String` - Device manufacturer
|
||||
- `codename: String` - Device codename
|
||||
- `default: String` - Default name if no alternative found
|
||||
|
||||
**Returns:** Alternative device name or default
|
||||
|
||||
**Example:**
|
||||
```kotlin
|
||||
val alternateName = AltDeviceNames.getAlternateNameOrDefault(
|
||||
"SM-G998U",
|
||||
"Samsung",
|
||||
"p3qsqw",
|
||||
"Galaxy S21 Ultra"
|
||||
)
|
||||
```
|
||||
|
||||
#### containsIdentifier(model: String, manufacturer: String, codename: String): Boolean
|
||||
Checks if device identifiers exist in the alternate names database.
|
||||
|
||||
**Parameters:**
|
||||
- `model: String` - Device model
|
||||
- `manufacturer: String` - Device manufacturer
|
||||
- `codename: String` - Device codename
|
||||
|
||||
**Returns:** True if identifiers are found, false otherwise
|
||||
|
||||
---
|
||||
|
||||
## DeviceDatabase Class
|
||||
|
||||
SQLite database helper for device information storage.
|
||||
|
||||
### Constructor
|
||||
|
||||
```kotlin
|
||||
DeviceDatabase(context: Context, autoUpdateDB: Boolean = true)
|
||||
```
|
||||
|
||||
**Parameters:**
|
||||
- `context: Context` - Application context
|
||||
- `autoUpdateDB: Boolean` - Whether to automatically update database (default: true)
|
||||
|
||||
### Functions
|
||||
|
||||
#### queryToDevice(codename: String, model: String): DeviceInfo?
|
||||
Queries the database for device information.
|
||||
|
||||
**Parameters:**
|
||||
- `codename: String` - Device codename
|
||||
- `model: String` - Device model
|
||||
|
||||
**Returns:** `DeviceInfo` object or null if not found
|
||||
|
||||
#### close()
|
||||
Closes the database connection.
|
||||
|
||||
**Example:**
|
||||
```kotlin
|
||||
DeviceDatabase(context).use { database ->
|
||||
val deviceInfo = database.queryToDevice("p3qsqw", "SM-G998U")
|
||||
// Use deviceInfo
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Device Types
|
||||
|
||||
### DeviceType Enum
|
||||
|
||||
```kotlin
|
||||
enum class DeviceType {
|
||||
EMULATOR, // Development emulator
|
||||
SMARTPHONE, // Standard phone
|
||||
TABLET, // Tablet device
|
||||
SMARTWATCH, // Wearable device
|
||||
SMART_TV, // TV or set-top box
|
||||
AUTOMOTIVE, // Car infotainment
|
||||
IOT, // Internet of Things device
|
||||
EREADER, // E-book reader
|
||||
GAMING, // Gaming device/console
|
||||
VR, // Virtual Reality headset
|
||||
FOLDABLE // Foldable device
|
||||
}
|
||||
```
|
||||
|
||||
### Device Type Detection Logic
|
||||
|
||||
The library uses the following criteria to determine device types:
|
||||
|
||||
- **EMULATOR**: Checks build fingerprint, model, manufacturer, and hardware for emulator indicators
|
||||
- **SMARTWATCH**: Device name starts with "wear", "smartwatch", "watch", or "wrist"
|
||||
- **SMART_TV**: Device name starts with "tv", "television", "settopbox", "streaming", "media", or "dongle"
|
||||
- **AUTOMOTIVE**: Device name starts with "car", "automotive", "infotainment", "dashboard", "headunit", or "vehicle"
|
||||
- **IOT**: Device name starts with "iot", "smart", "connected", "home", "appliance", or "device"
|
||||
- **EREADER**: Device name starts with "ereader", "ebook", "tablet", or "kindle"
|
||||
- **GAMING**: Device name starts with "gaming", "console", "handheld", or "portable"
|
||||
- **VR**: Device name starts with VR-related terms or "quest", "oculus", "meta", "rift"
|
||||
- **FOLDABLE**: Device name starts with "fold", "flip", "clamshell", "booklet", "dual", or "trifold"
|
||||
- **TABLET**: Screen smallest width >= 600dp OR model contains "tab"
|
||||
- **SMARTPHONE**: Default fallback for mobile devices
|
||||
|
||||
---
|
||||
|
||||
## Data Classes
|
||||
|
||||
### DeviceInfo Data Class
|
||||
|
||||
```kotlin
|
||||
class DeviceInfo(
|
||||
val manufacturer: String?, // Device manufacturer
|
||||
val marketName: String?, // Market/commercial name
|
||||
val codename: String, // Internal codename
|
||||
val model: String, // Model identifier
|
||||
val timestamp: Long = 0 // Cache timestamp
|
||||
) {
|
||||
val name: String // Computed property: marketName or capitalized model
|
||||
}
|
||||
```
|
||||
|
||||
**Properties:**
|
||||
- `manufacturer`: Device manufacturer (e.g., "Samsung")
|
||||
- `marketName`: Commercial device name (e.g., "Galaxy S21 Ultra")
|
||||
- `codename`: Internal device code (e.g., "p3qsqw")
|
||||
- `model`: Model identifier (e.g., "SM-G998U")
|
||||
- `timestamp`: When the information was cached
|
||||
- `name`: The display name (marketName if available, otherwise capitalized model)
|
||||
|
||||
### Alternative Constructor
|
||||
|
||||
```kotlin
|
||||
DeviceInfo(jsonObject: JSONObject, timestamp: Long)
|
||||
```
|
||||
|
||||
Creates DeviceInfo from cached JSON data.
|
||||
|
||||
---
|
||||
|
||||
## Error Handling
|
||||
|
||||
Most functions handle errors gracefully:
|
||||
|
||||
- Network operations return null or false on failure
|
||||
- Database operations fall back to alternate name resolution
|
||||
- Type detection defaults to SMARTPHONE for unknown devices
|
||||
- Caching operations ignore JSON parsing errors
|
||||
|
||||
## Thread Safety
|
||||
|
||||
- **AndroidInfo**: Thread-safe (uses lazy initialization)
|
||||
- **DeviceInfo**: Use suspend functions from coroutine scope
|
||||
- **AndroidDeviceInfo.getCurrentDeviceInfo()**: Must be called from worker thread
|
||||
- **DeviceDatabase**: Not thread-safe, use appropriate synchronization
|
||||
|
||||
## Performance Considerations
|
||||
|
||||
- Device information is cached locally for 30 days
|
||||
- Network requests have 5-second timeouts
|
||||
- Database queries are optimized for common device lookups
|
||||
- Lazy initialization used for expensive operations
|
||||
|
||||
## API Configuration
|
||||
|
||||
You can customize API endpoints:
|
||||
|
||||
```kotlin
|
||||
DeviceInfo.api_url_base = "https://your-api.com"
|
||||
DeviceInfo.api_version = "v3"
|
||||
// Other endpoints will be constructed based on these values
|
||||
```
|
||||
Reference in New Issue
Block a user