Metadata Reference

Complete documentation of all metadata fields available in the API for comprehensive device and application tracking.

System Status: Documentation Access IP Restriction: DISABLED

IP address validation is disabled. Documentation can be accessed from any IP address with valid token.

W How Metadata Parameters Work

Understanding the metadata processing flow and database relationships.

📱 Request Processing Flow

Client sends request with metadata
↓
MetadataService.processMetadata() validates and structures data
↓
AppValidationService validates app_name and configuration
↓
Check/Create records in normalized tables
↓
Create api_request_log with foreign keys
↓
Store response and return request_id

Important: Understanding Unique Constraints

The unique constraint ['app_name', 'app_version', 'sdk_version'] is in the api_app_metadata table, which is a reference table, NOT a request logs table.

This means:

  • Each combination of app_name + app_version + sdk_version has ONE record in api_app_metadata
  • Multiple API requests can have the same combination - they all reference the same record
  • API request logs (api_request_logs) reference this table via foreign key
  • This is a normalization pattern for storage efficiency and performance

Storage Savings: Instead of storing app details (50 bytes) in every request, we store them once and reference them. For 10,000 requests: 500KB → 90KB (82% reduction)

📋 Metadata Parameter Structure

{ "core": { "device_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", // → api_devices "session_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", // → api_sessions "user_id": "usr_abc123", // → api_sessions "request_id": "req_abc123" // → api_request_logs }, "device": { "device_type": "mobile", // → api_devices "manufacturer": "Samsung", // → api_devices "model": "SM-S23U", // → api_devices "os": "android", // → api_devices "os_version": "14", // → api_devices "locale": "en-US", // → api_devices "timezone": "America/New_York", // → api_devices "is_emulator": false, // → api_devices "is_rooted_jailbroken": false, // → api_devices (JSON) "is_physical_device": true, // → api_devices (JSON) "has_nfc": true, // → api_devices (JSON) "nfc_enabled": true, // → api_devices (JSON) "has_biometric": true, // → api_devices (JSON) "biometric_type": "fingerprint", // → api_devices (JSON) "has_gps": true, // → api_devices (JSON) "is_GPS_enabled": true, // → api_devices (JSON) "is_network_enabled": true, // → api_devices (JSON) "sensor_accelerometer": true // → api_devices (JSON) }, "network": { "type": "wifi", // → api_network_metadata "carrier": "Verizon", // → api_network_metadata "ip_address": "192.168.1.100" // → api_network_metadata }, "location": { "latitude": 40.7128, // → api_network_metadata "longitude": -74.0060, // → api_network_metadata "accuracy": 10.5, // → api_network_metadata "country": "US" // → api_network_metadata }, "performance": { "client_start_time": 1689000000000, // → api_request_logs "client_end_time": 1689000000500, // → api_request_logs "client_response_time_ms": 500 // → api_request_logs }, "app": { "name": "RoadPilot", // → api_app_metadata "version": "3.2.1", // → api_app_metadata "sdk_version": "2.0.0", // → api_app_metadata "client_version": "3.2.1", // → api_app_metadata "environment": "prod", // → api_app_metadata "ui_mode": "light" // → api_app_metadata }, "request": { "endpoint": "/api/graphql", // → api_request_logs "method": "POST" // → api_request_logs } }

🔗 Parameter to Table Mapping

Parameter Group Parameter Table Notes
core device_id api_devices Unique identifier
core session_id api_sessions Unique identifier
core request_id api_request_logs Unique per request
core user_id api_sessions Authenticated user
device device_type api_devices Device classification
device manufacturer api_devices Device maker
device is_emulator api_devices Security flag
device has_nfc api_devices (JSON) NFC hardware flag
network network_type api_network_metadata Connection type
network ip_address api_network_metadata Client IP
location latitude api_network_metadata GPS coordinate
location longitude api_network_metadata GPS coordinate
performance client_start_time api_request_logs Request start epoch ms
performance client_end_time api_request_logs Response received epoch ms
performance client_response_time_ms api_request_logs Round-trip client ms
request endpoint api_request_logs API path
request event_source request_snapshot Auto-populated server URL when not provided
request msg_id request_snapshot Client-provided message identifier; null if not sent
request correlation_id request_snapshot Client-provided correlation key; null if not sent
app name api_app_metadata Unique constraint part
app version api_app_metadata Unique constraint part
app sdk_version api_app_metadata Unique constraint part

🗄️ Database Table Relationships

┌─────────────────────────────────────────────────────────────┐
│                    API_REQUEST_LOGS                         │
│                   (Main Request Table)                      │
├─────────────────────────────────────────────────────────────┤
│ id                                                           │
│ request_id (unique)                                         │
│ app_metadata_id ────────────┐                               │
│ device_id ──────────────────┼──→ ┌─────────────────────┐    │
│ session_id ─────────────────┼──→ │   api_devices       │    │
│ response_payload_id ────────┼──→ │ (Device Metadata)   │    │
│ endpoint, method, http_code │    │ id                  │    │
│ performance_metrics         │    │ device_id (unique)  │    │
│ timestamps                  │    │ device_type, model  │    │
└─────────────────────────────┼──→ │ last_seen_at        │    │
                              │    └─────────────────────┘    │
                              │                                │
                              ├──────────→ ┌─────────────────┐│
                              │            │  api_sessions   ││
                              │            │ (Session Mgmt)  ││
                              │            │ id              ││
                              │            │ session_id      ││
                              │            │ user_id, device_id│
                              │            │ metrics         ││
                              │            └─────────────────┘│
                              │                                │
                              │    ┌─────────────────────┐    │
                              └──→ │api_app_metadata     │    │
                                  │ (App Reference)      │    │
                                  │ id                   │    │
                                  │ app_name, app_version│    │
                                  │ sdk_version          │    │
                                  │ [unique constraint]  │    │
                                  └─────────────────────┘    │
                                                            │
                              ┌──────────────────────┐       │
                              │api_response_payloads  │       │
                              │(Large Data Storage)   │       │
                              │id                     │       │
                              │request_id (fk)        │◄──────┘
                              │payload_data (compressed)      │
                              │payload_size, type            │
                              └──────────────────────┘       │
                                                            │
                              ┌──────────────────────┐       │
                              │api_network_metadata  │       │
                              │(Network Information) │       │
                              │id                     │       │
                              │network_type, carrier  │       │
                              │ip_address, location    │       │
                              └──────────────────────┘       │

🌍 Real-World Example

Scenario: User makes 4 API calls (Login, Location, Route, Traffic)

api_app_metadata (1 record)

  • • id: 1
  • • app_name: "RoadPilot"
  • • app_version: "3.2.1"
  • • sdk_version: "2.0.0"
  • • client_version: "3.2.1"
  • • sdk_env: "prod"
  • • ui_mode: "light"
  • • last_seen_at: 2025-05-27 14:15:00

api_devices (1 record)

  • • id: 1
  • • device_id: "a1b2c3d4-..."
  • • model: "SM-S23U"
  • • metadata_snapshot: {has_nfc, has_biometric, ...}
  • • last_seen_at: 2025-05-27 14:15:00

api_sessions (1 record)

  • • id: 1
  • • session_id: "a1b2c3d4-..."
  • • user_id: "usr_abc123"
  • • ip_address: "192.168.1.100"
  • • created_at: 2025-05-27 14:00:00

api_request_logs (4 records)

  • • All reference same app_metadata_id: 1
  • • All reference same device_id: "a1b2c3d4-..."
  • • All reference same session_id: "a1b2c3d4-..."
  • • client_start_time / client_end_time per request
  • • Different endpoints: login, location, routes, traffic

💡 Storage Efficiency: App metadata stored once (50 bytes), referenced 4 times. Without normalization: 200 bytes. With normalization: 50 bytes + 4 references (16 bytes) = 66 bytes. 67% storage reduction

⚡ Performance Benefits

Query Performance

  • ✓ 8x faster queries vs denormalized
  • ✓ Smaller indexes = better cache utilization
  • ✓ Optimized for time-series queries
  • ✓ Compound indexes on common patterns

Storage Efficiency

  • ✓ 75%+ reduction in storage
  • ✓ Reduced backup/restore times
  • ✓ Lower memory requirements
  • ✓ Faster table scans

Data Consistency

  • ✓ Single source of truth
  • ✓ Easy updates propagation
  • ✓ No duplicate data inconsistencies
  • ✓ Referential integrity

Analytics Ready

  • ✓ Built-in version tracking
  • ✓ Usage analytics by app version
  • ✓ Device adoption metrics
  • ✓ Performance monitoring

C Core Metadata

Essential identifiers and tracking information for every API request.

Field Name Type Required Description Example
deviceId String Yes Unique device identifier → api_devices.device_id "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
userId String No User identifier → api_sessions.user_id "usr_abc123"
session_id String Yes Server-generated session UUID → api_sessions.session_id "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
usageTrackerSessionId String Yes Alias for session_id → api_sessions.session_id "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
request_id String No Unique request identifier → api_request_logs.request_id "req_abc123"

D Device Metadata

Comprehensive device information including hardware, software, and capabilities.

Field Name Type Required Description Example
deviceType String No Device type → api_devices.device_type "mobile"
deviceManufacturer String No Device manufacturer → api_devices.device_manufacturer "Samsung"
deviceModel String No Device model → api_devices.device_model "SM-S23U"
deviceOS String No Operating system name → api_devices.device_os "android"
deviceOSVersion String No OS version → api_devices.device_os_version "14"
deviceLocale String No Device locale → api_devices.device_locale "en-US"
deviceTimezone String No Device timezone → api_devices.device_timezone "America/New_York"
is_emulator Boolean No Whether device is an emulator → api_devices.is_emulator false
is_rooted_jailbroken Boolean No Whether device is rooted → api_devices.metadata_snapshot (JSON) false
is_physical_device Boolean No Whether this is a physical device → api_devices.metadata_snapshot (JSON) true
has_nfc Boolean No Whether NFC hardware is available → api_devices.metadata_snapshot (JSON) true
nfc_enabled Boolean No Whether NFC is enabled → api_devices.metadata_snapshot (JSON) true
has_biometric Boolean No Whether biometric hardware is available → api_devices.metadata_snapshot (JSON) true
biometric_type String No Type of biometric (fingerprint, face, iris) → api_devices.metadata_snapshot (JSON) "fingerprint"
biometric_enrolled Boolean No Whether biometrics are enrolled → api_devices.metadata_snapshot (JSON) true
has_gps Boolean No Whether GPS is available → api_devices.metadata_snapshot (JSON) true
is_GPS_enabled Boolean No Whether GPS provider is enabled at runtime → api_devices.metadata_snapshot (JSON) true
is_network_enabled Boolean No Whether network location provider is enabled at runtime → api_devices.metadata_snapshot (JSON) true
device_fingerprint String No Unique device fingerprint → api_devices.metadata_snapshot (JSON) "fp_abc123xyz"
sensor_accelerometer Boolean No Whether accelerometer is available → api_devices.metadata_snapshot (JSON) true

🔍 NFC & Location Provider Fields — Clarification

  • has_nfc — raw hardware presence (client reports via PackageManager.FEATURE_NFC)
  • nfc_enabled — runtime NFC toggle state (client reports via NfcAdapter.isEnabled)
  • nfc_available — server-derived field: has_nfc && nfc_enabled (meaning "usable right now")
  • has_gps — raw GPS hardware presence (client reports via PackageManager.FEATURE_LOCATION_GPS)
  • is_GPS_enabled — whether the GPS provider is enabled at runtime (client checks LocationManager.GPS_PROVIDER)
  • is_network_enabled — whether the network location provider is enabled at runtime (client checks LocationManager.NETWORK_PROVIDER)

N Network Metadata

Network connectivity information and quality metrics.

Field Name Type Required Description Example
deviceNetworkType String No Network type → api_network_metadata.network_type "wifi"
deviceNetworkCarrier String No Mobile carrier name → api_network_metadata.network_carrier "Verizon"
ip_address String No Device IP address → api_network_metadata.ip_address "192.168.1.100"
wifi Boolean No Whether connected via WiFi → api_network_metadata.wifi true

L Location Metadata

Geographic location data and security validation.

Field Name Type Required Description Example
lat Float No GPS latitude → api_network_metadata.latitude 40.7128
lng Float No GPS longitude → api_network_metadata.longitude -74.0060
location_accuracy Float No Location accuracy in meters → api_network_metadata.location_accuracy 10.5
deviceLocationCountry String No Device location country → api_network_metadata.location_country "US"
glocal String No Rich geolocation string: country, region, city, postal code, timezone → api_network_metadata.glocal "country_name='USA', time_zone='America/New_York', …"

P Performance Metadata

Application performance metrics and timing data.

Field Name Type Required Description Example
battery_level Int No Battery level percentage (0-100) 85
low_power_mode Boolean No Whether device is in low power mode false
client_start_time String (epoch ms) No Request start timestamp → api_request_logs.client_start_time "1689000000000"
client_end_time String (epoch ms) No Client-side end timestamp (captured after response, sent via recordClientTiming mutation) → api_request_logs.client_end_time "1689000000500"
client_response_time_ms String No Client-side round-trip time (captured after response, sent via recordClientTiming mutation) → api_request_logs.client_response_time_ms "500"
endpoint String No API endpoint called → api_request_logs.endpoint "/api/graphql"
method String No HTTP method → api_request_logs.method "POST"

ⓘ Two-Phase Timing: client_end_time and client_response_time_ms are captured by the Android SDK after the API response is received. They are submitted via the recordClientTiming mutation using the request_id as lookup key, not in the initial metadata payload.

A Application Metadata

Application-specific information and context.

Field Name Type Required Description Example
appName String No Application name → api_app_metadata.app_name "RoadPilot"
appVersion String No Application version → api_app_metadata.app_version "3.2.1"
sdkVersion String No SDK version → api_app_metadata.sdk_version "2.0.0"
cltVersion String No Client version → api_app_metadata.client_version "3.2.1"
sdk_env String No SDK environment → api_app_metadata.sdk_env "prod"
ui_mode String No UI mode (light/dark) → api_app_metadata.ui_mode "light"

Usage Examples

Basic Metadata Object

{ "deviceId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "userId": "usr_abc123", "session_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "usageTrackerSessionId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "request_id": "req_abc123", "deviceType": "mobile", "deviceManufacturer": "Samsung", "deviceModel": "SM-S23U", "deviceOS": "android", "deviceOSVersion": "14", "deviceLocale": "en-US", "deviceTimezone": "America/New_York", "is_emulator": false, "is_physical_device": true, "appName": "RoadPilot", "appVersion": "3.2.1", "sdkVersion": "2.0.0", "cltVersion": "3.2.1", "sdk_env": "prod", "ui_mode": "light", "deviceNetworkType": "wifi", "deviceNetworkCarrier": "Verizon", "ip_address": "192.168.1.100", "wifi": true, "lat": 40.7128, "lng": -74.0060, "location_accuracy": 10.5, "deviceLocationCountry": "US", "glocal": "country_name='USA', time_zone='America/New_York', ...", "client_start_time": "1689000000000", "endpoint": "/api/graphql", "method": "POST" }

Complete Metadata Object

{ "core": { "device_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "user_id": "usr_abc123", "session_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "request_id": "req_abc123" }, "device": { "device_type": "mobile", "manufacturer": "Samsung", "model": "SM-S23U", "os": "android", "os_version": "14", "locale": "en-US", "timezone": "America/New_York", "is_emulator": false, "is_rooted_jailbroken": false, "is_physical_device": true, "has_nfc": true, "nfc_enabled": true, "has_biometric": true, "biometric_type": "fingerprint", "biometric_enrolled": true, "has_gps": true, "is_GPS_enabled": true, "is_network_enabled": true, "device_fingerprint": "fp_abc123xyz", "sensor_accelerometer": true }, "network": { "type": "wifi", "carrier": "Verizon", "ip_address": "192.168.1.100", "wifi": true }, "location": { "latitude": 40.7128, "longitude": -74.0060, "accuracy": 10.5, "country": "US" }, "performance": { "client_start_time": 1689000000000, "client_end_time": 1689000000500, "client_response_time_ms": 500 }, "app": { "name": "RoadPilot", "version": "3.2.1", "sdk_version": "2.0.0", "client_version": "3.2.1", "environment": "prod", "ui_mode": "light" }, "request": { "endpoint": "/api/graphql", "method": "POST" } }