factual

Factual Developer Documenation

Welcome to the factual-devdocs developer hub. You'll find comprehensive guides and documentation to help you start working with factual-devdocs as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    

Observation Graph SDK FAQ

What’s the average battery consumption?

The SDK should a have less than 1% difference in overall power consumption per hour

I’m seeing 403 messages in my logs, is that a problem?

The SDK makes occasional requests for Factual data. If there is no data for the area being requested the server will return a 403.

What data is collected/transmitted by the SDK

The Observation Graph SDK collects a variety of data points to enable enterprises, marketers and developers to better understand customer behavior, target potential buyers and create compelling user experiences. Factual proactively created policies and practices to use data responsibly and to protect personal information and location data. Please find below a breakdown of the information collected by Factual OG’s iOS and Android SDKs and please review carefully our Privacy Policy.


Android SDK

Configuration Request

Data sent to the Factual backend for configuration and authorization purposes. This request is required to enable the OG SDK and is made either once per 24-hour period or on each SDK restart.

Name Description
API Key Factual API Key
SDK Version SDK Version #
SDK Status [stopped, started]
Factual User ID Factual user unique identifier
App Name App bundle
Organization ID An organization might have many app ids
Device ID Device unique identifier (either GAID or generated GUID)
Advertiser ID Google advertiser id
Make Device manufacturer
Model Device Model
OS Device operating system
OS Version Device operating system version
Preferred Language Device current language using ISO-639-1
Carrier Carrier name
Carrier Country Carrier Country (2 letters ISO code)
App State Foreground, Background, Unknown
Connection Type Network connection type

Location Data Information

Periodic location data sent to the Factual backend for analytics purposes.

Name Description
Entry Timestamp Timestamp in milliseconds of when the entry was added
Entry Type Location or on-demand location
Sensor Timestamp When the event occured
Request Timestamp When the location request was made
Received Timestamp When the OS reported the event to the OG SDK
Dwell Time Dwell time spent by a device at the associated location
Location Data Type Source of location data. Refer to List 5.20 of the OpenRTB 2.5 spec
Latitude Latitude of the device as reported by OS
Longitude Longitude of the device as reported by OS
Horizontal Accuracy Horizontal accuracy in meters as reported by the OS
Speed Speed in meters per second as reported by the OS
Activity Activity as reported by the OS (Stationary, Walking)
Bearing Direction as reported by the OS (North, South…)
Altitude Altitude in meters as reported by the OS
Altitude Accuracy Altitude accuracy in meters as reported by the OS
Floor Level Floor of the building on which the device is located, as reported by the OS

App Permissions

Permission Name Description
android.permission.ACCESS_FINE_LOCATION Enables most accurate location
android.permission.INTERNET Enables Factual to send data to the cloud
android.hardware.location.gps Enables GPS access
android.hardware.location.network Enables location updates via WiFi and Cellular Networks

App Compatibility

  • Android API level support: 20
  • Google Play Version: 11.0.4

iOS SDK

Configuration Request

Data sent to the Factual backend for configuration and authorization purposes. This request is required to enable the OG SDK and is made either once per 24-hour period or on each SDK restart.

Name Description
API Key Factual API Key
SDK Version SDK Version #
SDK Status [stopped, started]
Factual User ID Factual user unique identifier
App Name App bundle
Organization ID An organization might have many app ids
Device ID Device unique identifier (either IDFA or generated GUID)
Advertiser ID Apple advertiser id
Make Device manufacturer
Model Device Model
OS Device operating system
OS Version Device operating system version
Preferred Language Device current language using ISO-639-1
Carrier Carrier name
Carrier Country Carrier Country (2 letters ISO code)
App State Foreground, Background, Unknown
Connection Type Network connection type

Location Data Information

Name Description
Entry Timestamp Timestamp in milliseconds of when the entry was added
Entry Type Location or on-demand location
Sensor Timestamp When the event occured
Request Timestamp When the location request was made
Received Timestamp When the OS reported the event to the OG SDK
Dwell Time Dwell time spent by a device at the associated location
Location Data Type Source of location data. Refer to List 5.20 of the OpenRTB 2.5 spec
Latitude Latitude of the device as reported by OS
Longitude Longitude of the device as reported by OS
Horizontal Accuracy Horizontal accuracy in meters as reported by the OS
Speed Speed in meters per second as reported by the OS
Activity Activity as reported by the OS (Stationary, Walking)
Bearing Direction as reported by the OS (North, South…)
Altitude Altitude in meters as reported by the OS
Altitude Accuracy Altitude accuracy in meters as reported by the OS
Floor Level Floor of the building on which the device is located, as reported by the OS

Permission Required

Permission Name Description
Location “When in Use” or “Always” The user permits location for the app

App Plist Declaration

Key Description
NSLocationWhenInUseUsageDescription Message displayed to users on location permission request
NSLocationAlwaysAndWhenInUseUsageDescription Message displayed to users on location permission request
UIBackgroundModes location Location updates background mode