What analytic data is collected by your SDK?
The main purpose of this is to improve the connection quality of the SDK. The SDK collects anonymous data about a device, configuration requests and connection start and stop attempts.
The SDK performs Network Availability Test for better understanding what's happening when a connection error is received. It includes diagnostics of the current network connection such as a Captive Portal check, pinging of a popular public web resource, etc.
The SDK does not collect or analyze any Personal Identifiable Information.
all the geolocation data is inaccurate and provide an approximation
cell phone service provider and ISP data is used for statistical purposes only
any hardware information is used for the service quality improvement
all the identifiers are auto-generated
The latest version of Android SDK provides an option to turn on/off event sending. It is up to the application developer to use or not use this function of the SDK.
Common properties
Common Android device-related properties:
Property Name
Type
Description
af_platform
String
android
uid
String
Application UID. The kernel user-ID that has been assigned to this application by the operating system of the device; currently this is not a unique ID (multiple applications can have the same UID).
app_name
String
Application package name
app_build
String
ID based on app signature. Helpful to figure out if the app was cracked.
app_version
String
Application version name
app_release
String
Application version code
carrier
String
Telephony carrier name
has_telephone
Boolean
Shows if the device is a phone or other type of device
memory_remains
String
Remaining RAM
memory_total
String
Total RAM
model
String
android.os.Build.MODEL
device_manufacturer
String
android.os.Build.MANUFACTURER
locale
String
Current device locale (provided by the device itself)
device_language
String
Current device language (provided by the device itself)
hydra_base_url
String
Base API URL
android_sdk_int
String
Build.VERSION.SDK_INT
android_version_name
String
Build.VERSION.RELEASE
connection_type
String
Type of current active network
time_zone
String
Device time zone in "-0800" format (is taken from the device settings)
af_hash
String
Device ID auto-generated on the first app install
sdk_version
String
SDK version name
sdk_version_code
Integer
SDK version code
Common iOS and macOS device-related properties
Property Name
Type
Description
af_platform
String
“ios”
app_name
String
Application package name
app_release
String
Application version code
distinct_id
String
Unique id auto-generated on the first app install
epoch
Integer
Time of generated event in UNIX format
carrier
String
Telephony carrier name
model
String
iPhone model, eg. iPhone8,2
manufacturer
String
“Apple”
af_hash
String
Device id auto-generated on first app install
sdk_version
String
SDK version name
lib_version
String
Analytics SDK version
os
String
Device OS (iOS)
os_version
String
OS version, e.g., 13.1.2
screen_height
Integer
Device screen height
screen_width
Integer
Device screen width
server_protocol
String
SDK server protocol e.g., hydra
sim_country
String
Country of the carrier (provided by the SIM card)
wifi
Bool
Indicates if a device is using a Wi-Fi network (with no specific information on this network)
time
Integer
The current time on the device (in UNIX format)
Common configuration request properties for all platforms
Property Name
Type
Description
platform
String
Device platform
sdk_version
String
SDK version name
project
String
Carrier name
device_id
String
Device unique identificator generated by SDK or provided by App
app_version
String
App version name
attempt_id
String
Unique Id of a pair of requests/response
server_domain
String
Backend server domain
endpoint/source
String
Backend server endpoint
duration
Integer
Request duration
status_code/status
Integer
HTTP Status Code or 0 in case of non-HTTP error
api_id
String
Value of the x-amz-cf-id HTTP response header (might be empty)
error_code
Integer
Request error code
time
Integer
The current time on the device (in UNIX format)
Common connection properties for all platforms
Property Name
Type
Description
catime
Integer
UNIX millisecond timestamp (since Epoch) on the client, when a connection attempt was initiated
caid
String
Connection attempt ID auto-generated by the client on the actual attempt
reason
String
Describes the source of a VPN session initiation or termination (user click, reconnect, etc.)
error_code
Integer
Numerical code of an error category (0 = success). See section "error_code" below
error
String
Error description. See the "error" section below
protocol
String
The protocol used for the connection attempt
server_ip
String
The server IP address used to establish a connection (empty if the attempt was unsuccessful)
session_id
String
An identifier assigned by the VPN node in case of a successful connection attempt (should match with the value on the server). The identifier is valid until the intended end of the session.
hydra_version
String
The version of Hydra protocol used to establish a connection
notes
JSON
Extra information on service delivery configuration (in case Hydra was used), region ID, ISP name, and a numerical representation of the network availability test result.
parent_caid
String
caid of the original connection attempt (in case the connection was broken). This property is used to recover the session.
is_ipv6_only
Integer
This flag shows if the ISP support IPv6 protocol only (1 - yes, 0 - no)
first
Boolean
Indicates the first launch of the application. Always has a "false" value after the initial launch.
Configuration requests events
SDK reports data only about internal requests to the Backend which are used to get up to date configurations for VPN connections.
There are 3 configuration requests events:
auth,
api_request,
api_response.
Event: auth
Event reports a retrieval of a token for configuration requests from the Backend.
Properties specific for event auth:
Property Name
Type
Description
details
JSON
information about when the token was issued and when it’s going to expire
reason
String
why the request was initiated (token is absent or expired)
Event: api_request
Event reports the data about configuration request to the Backend.
Properties specific for event api_request:
Property Name
Type
Description
api_content.params
JSON
parameters that were passed to the Backend for config retrieval
api_content.configs
JSON
list of requested configs and their local versions
Event: api_response
Event reports the data about configuration response from the Backend.
Properties specific for event api_response:
Property Name
Type
Description
api_content.response
JSON
response from the Backend, contains a list of received sections or error if failed
Connection events
There are 4 connection events:
connection_start,
connections_start_detailed,
connection_end,
connection_end_detailed.
We are using *_detailed events mostly for diagnostic if a connection really works and what the possible reason for a connection could not be established.
Event: connection_start
Event reports every connection attempt.
Properties specific for event connection_start:
Property Name
Type
Description
duration
Integer
how long it took to establish a connection or stop trying to connect, in milliseconds
notes
JSON
Provides additional information if any related to the connection process.
Event: connection_start_detailed
Event reports additional details regarding all finished connection attempts to particular IPs (main, offload), including successful.
If the connection attempt was unsuccessful, a network availability check should be performed and reported in network_availability and notes properties.
Properties specific for event connection_start_detailed:
Property Name
Type
Description
network_availability
Float
Share of passed Network Availability tests rounded to 2 digits after the decimal point.
notes
JSON
detailed results of the Network Availability Test.
details
JSON
an array of JSON with connection results of all low-level attempts to connect.
Event: connection_end
The event should be reported when a Connection is terminated. All properties specific for connection-related events should be reported for this event as well.
Properties specific for event connection_end:
Property Name
Type
Description
duration
Integer
the duration of the VPN session in milliseconds
traffic
JSON
traffic statistics in bytes
{
"bytes_in: 100,
"bytes_out": 100
}
When a connection is terminated unexpectedly (no user intention to terminate the session), network availability tests should be performed and the connection_end_detailed event should be reported. If a user has canceled, no need to send the event. Properties specific for event connection_end_detailed:
Property Name
Type
Notes
network_availability
Float
Share of passed Network Availability tests rounded to 2 digits after the decimal point.
notes
JSON
detailed results of the Network Availability Test.
Property for “error_code”
connection_start
error_code
Description
0 (success)
No error (the connection has been established successfully)
1 (internal error)
Internal problems during initialization or establishing communication (e.g. Failed to open TUN, VPN permissions are not given, Hydra "Bad Configuration" error, etc.) or any other unclassified errors
2 (connection error)
Failed to establish a connection due to networking issues (e.g. host is unreachable, can't send data, timeout on receiving data, etc.)
4 ("no network" error)
The network has been lost during the connection (e.g. WiFi lost or changed) or the network is up, but unavailable (e.g. due to a walled garden or as mobile data is disabled)
6 (canceled)
The connection establishment has been terminated in the middle of the process. No connection has been established.
7 (app level error)
Application denied starting establishing the VPN connection (i.e. user tried to use some elite features from the free app, PC adapter is not ready to connect)
connection_end
error_code
Description
0 (success)
No error (the connection has ended as expected and successfully)
1 (internal error)
An internal problem that broke established connection (e.g. OpenVPN or Hydra quit unexpectedly, etc.)
2 (connection error)
The connection has broken due to connection problems (e.g. Hydra or OpenVPN detected communication problem, etc.)
3 (connection stuck)
Connection is established, but no exchange happening ("KeepAlive problem")
Property for “error”
error_code
error
Description
0
Success
No error
1
Internal error
Platform-specific internal problems during initialization, connection, or operation. (e.g. Failed to open TUN, Hydra "Bad configuration" error, VPN permissions are not given, etc.) Also, this code should be used for any unclassified errors (with a detailed description).
2
Connection error
The error should be supplied with an HTTP code / VPN error code. This code is used for the situation when a connection has not been established or has been broken.
3
Connection stuck
The connection has been established, but no data exchange is happening. Should be supplied with a platform-specific description.
4
No network
The network connection has been lost during the VPN session
5
Failed
The backend has responded with an error. A relevant error should be provided.
connection_start
Name
Description
m_ui
Connection is initiated via interaction with the UI elements
m_system
Connection is initiated via interaction with the system menu
m_tray
Connection is initiated via interaction with a notification message or a tile
m_other
Connection is initiated via some other type of interaction
a_app_run
Connection is initiated automatically on the app launch
a_reconnect
Connection is initiated after an intended VPN session termination
a_error
Connection is initiated as a result of an unexpected VPN session disconnect
a_sleep
Connection is initiated after a device has returned from the sleep/hibernation mode
a_network
Connection is initiated due to the network status change
a_other
Connection is initiated automatically due to any other reason
There are several reasons for a connection attempt to fail or an established connection to drop unexpectedly. It can be an infrastructure issue or a client bug that can and shall be fixed. It can be a blockage that should be addressed by changing the configuration or in the worst case improving the VPN core and re-releasing the client. But it can also be a. problem with the network that can’t be fixed in principle.
In order to distinguish these cases, a network availability test will be performed on every unsuccessful connect or unintended disconnect that will report whether the network is available or not.
This test includes: check the captive portal, current network type, ping test, and security certificate test.
Captive Portal test
This test is to check if there is a Captive portal. It usually means that all requests are redirected by the network provider to their own login page.
Network type test
Certificate test
In some particular cases, there can be more significant issues with your connection like issues with web certificates. To test this case SDK sends a request to one of the following URL and checks that the certificate is valid:
Event samples
auth
api_request
api_response
connection_start
connection_start_detailed
connection_end
connection_end_detailed
Last updated
Was this helpful?