< page.
> **Note:** The data file downloadable from the DeviceAtlas website is only
compatible with the production 2.x APIs. It will not work with this API. Please
use the provided sample data file instead.
## Client Side Library - Apple Device Identification ##
In addition to the server-side API, an optional client-side Javascript library
is available. This library is important for two reasons:
1. It facilitates identification of Apple devices. Apple devices are _not_
identifiable using only HTTP User-Agent data.
2. It allows for the collection of dynamic or changing properties.
When the client-side library is embedded in a web page it collects additional
properties from the client's web browser. This data is then sent back to the
server and must be passed to the DeviceAtlas API along with the HTTP headers.
The combination of the client data and the server side data allow for accurate
identification of Apple devices.
The client-side library may be included on a webpage by adding the following
snippet:
```Javascript
<!-- Adding the DeviceAtlas client side component to get client side properties -->
<script type="text/javascript" src="https://cs-cdn.deviceatlas.com/dacs.2.2.beta.js" async></script>
```
By default, the client-side library returns the data via a cookie. If this is
present in the `HttpServletRequest` object it will be automatically used. The
cookie name is configurable via the `Config` class.
Alternatively, the client data may be returned via AJAX and passed to the server
side API manually.
For additional information, please see the [Client Side Library](https://docs.deviceatlas.com/apis/clientside/latest/README.ClientSide.html) documentation.
## Setup & Usage ##
The usage of the DeviceAtlas server side library is straightforward. In all
cases, the data file must be loaded before any device identification calls are
made.
> **Note:** It is highly recommended to ensure the data file is only loaded once.
This is particularly important for batch processing and web applications.
### Requirements ###
- A C compiler (C++ compiler for the wrapper)
- CMake 2.8 (or above).
The following compilers have been tested and are able to compile all
components:
- GCC (4.2 or above (5.x, 7.x and onwards are recommended, the 6.x versions could possibly impact
negatively the performances due to optimisations bugs)).
- Clang 3.x or above.
- TinyCC 0.9 or above.
### Build ###
The API is compatible with ASLR with PIE enabled.
#### Ubuntu/Debian ####
```shell
% sudo apt-get install gcc (or clang) cmake
```
#### RedHat/CentOS ####
```shell
% sudo dnf install gcc (or clang) cmake
```
#### MacOS ####
```shell
% brew install gcc (or clang ; not necessary if clang from XCode is already installed)
cmake
```
#### FreeBSD ###
```shell
sudo pkg install gcc<any version> (or llvm<any version>) if another compiler different from the base system is preferred
```
### Install the API (Optional) ###
```shell
% cd <path to the extracted api archive>
% sudo make install
% sudo ldconfig
```
### Usage Examples ###
The following sections shows how to call the DeviceApi. Please note that
exception handling has been omitted for brevity.
#### EXAMPLE 1: Basic Usage - Single User-Agent ####
```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
var headers map[string]string
headers["user-agent"] = "Mozilla/5.0 (Linux; Android 11; SM-G998B) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/87.0.4280.141 Mobile Safari/537.36";
properties, err := da.Detect(headers)
if mobileDevice, ok := properties["mobileDevice"]; ok {
// do something
}
```
#### EXAMPLE 2: Passing Client Side Data ####
The data collected by the DeviceAtlas Client-side Library is automatically
passed when a `HttpServletRequest` is used. If a `HttpServletRequest` object
is not available the client-side data can be passed manually as a second
parameter to the `getProperties()` method.
```go
...
headers["user-agent"] = "Mozilla/5.0 (Linux; Android 12; SM-G998B) AppleWebKit/537.36 (KHTML, like Gecko) Version/4.0 Chrome/102.0.0.0 Mobile Safari/537.36";
headers["daprops"] = "scsVersion:2.1|bcookieSupport:1|bcss.animations:1|bcss.columns:1|bcss.transforms:1|bcss.transitions:1|sdeviceAspectRatio:1795/1010"
...
```
#### Additional Examples ####
Please find more complete examples in the /Examples directory.
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
_ Copyright (c) DeviceAtlas Limited 2023. 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">Device API Usage C</a></li><li><a href="README.ClientHints.html">Client Hints Support</a></li><li><a href="README.CarrierApi.html">Carrier Identification API</a></li><li><a href="README.Upgrade.html">Device API Upgrade</a></li><li><a href="README.Cpp.html">Device API C++</a></li><li><a href="README.Nginx.html">NGINX Module</a></li><li><a href="README.Apache2.html">Apache2 Module</a></li><li><a href="README.JsonConverter.html">Device Identification API C JSONConverter</a></li><li class="disabled"><a href="README.Go-DeviceApi.html">Device API Usage Go</a></li><li><a href="README.Go-Upgrade.html">Device API Upgrade Go</a></li><li><a href="https://docs.deviceatlas.com/apis/clientside/latest/README.ClientSide.html" target="_blank">Client-side component</a></li><li class="divider"></li><li><a href="./ApiDocs/index.html">C ApiDocs</a></li><li><a href="./ApiCppDocs/index.html">C ++ interface ApiDocs</a></li><li><a href="./Go-ApiDocs/carrier.html">Go ApiDocs Carrier</a></li><li><a href="./Go-ApiDocs/device.html">Go ApiDocs Device</a></li></ul></div>]]>