# DeviceAtlas Cloud Client API #
This section deals with usage of the DeviceAtlas Cloud API.
## 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
```
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.
#### Basic Usage ####
The DeviceAtlas Cloud Client API can be used as follows:
* Include the DeviceAtlas Cloud Client API in your application.
```python
from deviceatlas.cloud.device import Client
```
* Get an instance of the API, set your DeviceAtlas licence key and get the properties.
```python
# Detecting based on a set of HTTP headers:
headers = {
'User-Agent': 'THE USER AGENT...',
...
...
}
try:
client = Client()
client.LICENCE_KEY = 'ENTER-YOUR-LICENCE-KEY'
result = client.getDeviceData(headers)
if Client.KEY_PROPERTIES in device_data:
properties = device_data[Client.KEY_PROPERTIES]
except TypeError as type_error:
print("Invalid Licence Key")
except Exception as error:
print(error.message)
```
```python
# Detecting based on a user agent string
user_agent = 'THE USER AGENT...'
try:
client = Client()
client.LICENCE_KEY = 'ENTER-YOUR-LICENCE-KEY'
result = client.getDeviceData(user_agent=user_agent)
if Client.KEY_PROPERTIES in device_data:
properties = device_data[Client.KEY_PROPERTIES]
except TypeError as type_error:
print("Invalid Licence Key")
except Exception as error:
print(error.message)
```
```python
# To get the HTTP headers from a framework such a Django
try:
client = Client()
client.LICENCE_KEY = 'ENTER-YOUR-LICENCE-KEY'
result = client.getDeviceData(request.META)
if Client.KEY_PROPERTIES in device_data:
properties = device_data[Client.KEY_PROPERTIES]
except TypeError as type_error:
print("Invalid Licence Key")
except Exception as error:
print(error.message)
```
* Use the device properties:
```python
if "mobileDevice" in properties and properties["mobileDevice"]:
# example 1: Get the screen width for image optimization
display_width = properties.get('displayWidth', 100)
# example 2: Get the device vendor name
vendor = properties.get('vendor', "")
# example 3: Touch screen optimization
use_bigger_icons = properties.get('touchScreen', False)
# example 4: Send Geo Location JS to client?
support_geo_location = properties.get('js.geoLocation', False)
```
See the list of all property names here:
https://deviceatlas.com/resources/available-properties .
The availability of a property depends on the device and your licence,
before accessing a property always check if it exists in the set or not.
* When DEBUG_MODE = False or API version < 1.4
```python
client = Client()
client.LICENCE_KEY = 'ENTER-YOUR-LICENCE-KEY'
# try to find the HTTP headers in os.environ
device_data = client.getDeviceData()
# get the properties
if Client.KEY_ERROR in data:
print(device_data[Client.KEY_ERROR])
else:
# get the properties
if Client.KEY_PROPERTIES in device_data:
properties = device_data[Client.KEY_PROPERTIES]
```
### 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 ####
Includes two examples. One simple command line example which uses API to detect
and get properties from header sets. The other example is a web application.
This example uses the API for the current request to automatically detect and get
the properties. Using custom API configs and the client-side-component is shown
in this example.
* Command line example:
```shell
$ python deviceatlas-cloud-python-2.1/Examples/basic-usage/detect.py
```
* Web example:
```shell
$ python deviceatlas-cloud-python-2.1/Examples/web-app/example.py
```
And access http://localhost:3000 from browser.
See the list of all property names here:
https://deviceatlas.com/resources/available-properties
The availability of a property depends on the device and your licence, before
accessing a property always check if it exists in the set or not.
### Additional Examples ###
Please find more complete examples in the /Examples directory.
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
_ Copyright (c) DeviceAtlas Limited 2023. All Rights Reserved. _
https://deviceatlas.com