<![CDATA[
# DeviceAtlas Device Detection for Web #
The DeviceAtlas Device Detection API for Web provides a way to detect devices based on
the HTTP headers. Using the headers, the API returns device information such as
screen width, screen height, is mobile, vendor, model etc.
To see a full list of properties in DeviceAtlas please visit:
https://deviceatlas.com/resources/available-properties .
### Data File ###
The DeviceAtlas API relies on a device data file to function. DeviceAtlas
provides daily data file updates so it is recommended to download the data file
on a regular basis. This can be done manually from your account page or
automated via the https://deviceatlas.com/getJSON page.
For more information please see:
https://deviceatlas.com/resources/getting-the-data
### Dependencies ###
This library does not depend on any third party libraries.
### Library ###
The DeviceAtlas API consists of a single `device` package.
#### DeviceApi (deviceatlas/device) ####
The device package loads the Device data file, detects and returns the
properties for a set of request headers or the user-agent. Client-side
properties can be optionally passed to this package to get more accurate
results.
### Basic Usage ###
The API can be used as follows:
To lookup the properties by manually passing the Hash of headers to the API:
```go
// (1) create an instance with default API settings
da := device.New()
defer da.Free()
// (2) load the data file
_, err := da.LoadDataFromFile("/path/to/apps_datafile_lowercased.json")
if err != nil {
// handle the errors related to loading the data file
}
// (3) look up device properties based on your custom header set
var headers map[string]string
headers[HEADER_NAME] = HEADER_VALUE
properties, err := da.Detect(headers)
if err != nil {
// handle the errors related to properties detection
}
// (4) use the properties - e.g. detect mobile device
// if there is a property named "mobileDevice" and the value is true
if mobileDevice, ok := properties["mobileDevice"]; ok {
// example 1: Get the screen width for image optimization
displayWidth := 100
use_bigger_icons := false
supports_geo_location := false
if displayWidth, ok := properties["displayWidth"] {
display_width = displayWidth.(int64)
}
// example 2: Get the device vendor name
vendor := properties["vendor"].(string)
// example 3: Touch screen optimization
if _, ok := properties["touchScreen"]; ok {
use_bigger_icons = true
}
// example 4: Is Geo Location enabled on the device?
if _, ok := properties["js.geoLocation"]; ok {
supports_geo_location = true
}
}
```
### Client-side Component ###
In addition to the properties from the data file, properties can be gathered
from the client's browser and used both on the client side and on the server
side. Please see the [Client-side readme file](README.ClientSide.html) for more
information.
#### Usage With Client-side Component ####
In addition to normal usage, DeviceAtlas has the capability to capture client
side properties and merge them into the server side properties.
The "deviceatlas.min.js" file must be included on your webpage in order for it
to detect the Client-side properties. The Client-side properties are returned to
the server in a cookie called DAPROPS. The contents of this cookie are
automatically detected with the request headers or can be passed separately,
with Headers or a User-Agent, to get the combined properties back. Both sets of
properties are used in additional logic to determine other properties such as
iPhone and iPad models which are normally not detectable.
* Sample code that demonstrates how to lookup the properties by manually passing
the headers and the client-side properties to the API:
```go
// (1) create an instance with default API settings
da := device.New()
defer da.Free()
// (2) load the data file
_, err := da.LoadDataFromFile("/path/to/datafile.json")
if err != nil {
// handle the errors related to loading the data file
}
// (3) look up device properties
// the client_side_properties value can be retrieved from the DAPROPS cookie or from a URL parameter
// see the Client-side readme file for more information
headers["DAPROPS"] := <THE DAPROPS COOKIE VALUE>
properties = da.Detect(headers)
// (4) use the properties - e.g. detect mobile device
// if there is a property named "mobileDevice" and the value is true
if mobileDevice, ok := properties["mobileDevice"]; ok {
// example 1: Get the screen width for image optimization
displayWidth := 100
use_bigger_icons := false
supports_geo_location := false
if displayWidth, ok := properties["displayWidth"] {
display_width = displayWidth.(int64)
}
// example 2: Get the device vendor name
vendor := properties["vendor"]
// example 3: Touch screen optimization
if _, ok := properties["touchScreen"]; ok {
use_bigger_icons = true
}
// example 4: Is Geo Location enabled on the device?
if _, ok := properties["js.geoLocation"]; ok {
supports_geo_location = true
}
}
}
```
### Code Examples ###
Various examples are included in this package to clearly demonstrate the API
features, usage and some use cases. These examples are very simple and are
heavily commented.
#### Basic Usage ####
There are multiple Go command line mini-applications available at the project root level under the `Examples` folder.
The braintree/manners dependency is required to run the Web examples. It can be installed via Go. Note that Go in
turn requires Git to install dependencies.
```bash
go get "github.com/braintree/manners"
```
The examples can be compiled to native executables via `go build` tool, or run as a script via the `go run` command.
* Command line example:
```bash
cd Examples/device/cli/detect
go run detect.go
```
* Web example:
```bash
cd Examples/device/web
go run device_web.go
```
And access `http://localhost:8180` from the browser.
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
_ Copyright (c) DeviceAtlas 2022. All Rights Reserved. _
https://deviceatlas.com
<!-- HTML+JS for document formatting when opened in browser -->
<div class="btn-group" id="main-menu" style="float:right"><a class="btn dropdown-toggle" data-toggle="dropdown" href="#">Menu<span class="caret"></span></a><ul class="dropdown-menu"><li><a href="README.html">Main</a></li><li><a href="README.DeviceApi.html">Building dependencies and API</a></li><li class="disabled"><a href="README.DeviceApi-Web.html">Device Detection for Web</a></li><li><a href="README.DeviceApi-Apps.html">Device Detection for Apps</a></li><li><a href="./ApiDocs/device.html">Device API Docs</a></li><li class="divider"></li><li><a href="README.DeviceApi-Config.html">Device Detection API Config</a></li><li><a href="README.Upgrade.html">Device Detection API Upgrade</a></li><li class="divider"></li><li><a href="README.CarrierApi.html">Carrier Identification API</a></li><li><a href="./ApiDocs/carrier.html">Carrier API Docs</a></li><li class="divider"></li><li><a href="README.CarrierApi-Config.html">Carrier Detection API Config</a></li></ul></div>]]>