# DeviceAtlas Cloud Client API # DeviceAtlas Cloud is a web service that can return device information such as screen width, screen height, is mobile, vendor, model etc. To see a full list of properties, please visit https://deviceatlas.com/resources/available-properties . This Client API provides an easy way to query DeviceAtlas Cloud. It provides the ability to cache returned data locally to greatly improve performance and has automatic failover should one of the global DeviceAtlas Cloud endpoints become unavailable. As of version 1.2, the Client API is able to leverage data collected by the DeviceAtlas Client Side Component. This data is sent to DeviceAtlas Cloud to augment the data found from the normal HTTP headers and also allows the detection of the various iPhone and iPad models. ### Compatibility ### The DeviceAtlas Cloud Python library is compatible with both Python 2 and 3. It can be used inside any Python script, cgi or any WSGI Python web framework. ### Requirements ### - Python 2.7 (or above) - pip (already installed if Python 2 >=2.7.9 or Python 3 >=3.4 is in use) ### Installation ### 1. Unpack the deviceatlas-cloud-2.0.0.0.zip 2. Install with pip ```shell $ pip install deviceatlas-cloud-python-2.0.0.0/Api/deviceatlas-cloud-2.0.0.zip ``` 3. Include the DeviceAtlas Cloud Client API in your application. ```python from deviceatlas.cloud.device import Client ``` ### Dependencies ### This library does not depend on any third party libraries. ### Configuration ### The DeviceAtlas Cloud Client API is configured by setting the properties at the top of the "Client.py" file. The only required setting is your DeviceAtlas licence key. Note: as of version 1.4 the API throws exceptions on errors and failures unless the class property "DEBUG_MODE" at the top of the "Client.py" file is set to False. It is recommended to keep "DEBUG_MODE" set to True during implementation time. #### 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.0.0.0/Examples/basic_usage_cli/detect.py ``` * Web example: ```shell $ python deviceatlas-cloud-python-2.0.0.0/Examples/basic_usage_web/example.py ``` And access http://localhost:3000 from browser. #### Redirection #### This web example uses the API to get properties for the current request and then uses some basic property values to decide which website provides the most suitable content for the device making the request. ```shell $ python deviceatlas-cloud-python-2.0.0.0/Examples/redirection/example.py ``` And access http://localhost:3000 from browser. #### Content Adaptation #### This web example uses the API to get properties for the device making the current request and then uses some basic property values to choose a suitable template to wrap around the content. ```shell $ python deviceatlas-cloud-python-2.0.0.0/Examples/content_adaption/example.py ``` And access http://localhost:3000 from browser. #### Analytics #### This web example uses the API to get properties for user-agents from a given list. Some properties such as vendor, browser name and device type are aggregated and the results are displayed as graphs and numbers. ```shell $ python deviceatlas-cloud-python-2.0.0.0/Examples/analytics/example.py ``` And access http://localhost:3000 from browser. #### Content Targeting #### This example uses the API to detect the device and use some of its properties to show certain advertisements and download links which may be related or of interest to the user, considering his/her device. ```shell $ python deviceatlas-cloud-python-2.0.0.0/Examples/content_targeting/example.py ``` And access http://localhost:3000 from browser. Note that in the web examples which use the API, the client side properties are taken into account automatically by the API if the cookie exists on the browser. This means if the cookie already exists within your browser you will still see the client side properties in the result even when the DeviceAtlas client side component is not added to the page. You can delete the cookie manually to see the differences between the results from examples which use the client side component and those that don't. ### Caching ### The API can cache the returned data after a call to the DeviceAtlas Cloud service, this will speed up subsequent requests. The API has a file caching mechanism. It is recommended to always use the file cache if possible. The file cache stores the returned properties on your server disk. The cache location is typically the system temp directory but this can be overridden with the "CUSTOM_CACHE_DIR" property. Items in the cache expire after a set time period to ensure the data is up-to-date. This cache is enabled by default. It is recommended to always have file caching enabled even when you are using cookie cache. Items in the cache expire after a set time period to ensure the data is up-to-date. ### 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 [ClientSide 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 contents of this cookie are automatically detected with the request headers. Both sets of properties are used in additional logic to determine other properties such iPhone and iPad models which are normally not detectable. By default, if the cookie exists it will be used by the API. To disable using the client side cookie: ```python client = Client() client.LICENCE_KEY = 'ENTER-YOUR-LICENCE-KEY' client.USE_CLIENT_COOKIE = False ``` ### DeviceAtlas Cloud Service End-points ### The DeviceAtlas Cloud Service is powered by independent clusters of servers spread around the world. This ensures optimum speed and reliability. The API is able to automatically switch to a different end-point if the current end-point becomes unavailable. It can also (optionally) auto-rank all of the service end-points to choose the end-point with the lowest latency for your location. The Cloud service end-points are defined in the SERVERS variable at the top of the "Client.py" file. ```python SERVERS = [ {'host': 'server1-url', 'port': server1-port}, {'host': 'server2-url', 'port': server2-port}, {'host': 'server3-url', 'port': server3-port}, ] ``` By default the API will analyze the end-points from time to time to rank them by their stability and response speed. The ranked list is then cached and used whenever the Client API needs to query the DeviceAtlas Cloud Service. If an end- point fails, the Client API will automatically switch to the next end-point on the list. There is no need to set the servers array if auto-ranking is turned on. If you wish, you may re-order the array and turn auto-ranking off. In this case the API will respect your preferred order of end-points and only switch to a different end-point should the primary one fail to resolve. #### Notes #### * With the default auto-ranking settings, the ranking is done every 24 hours. The actual time may be more than 24 hours as the ranking is only triggered by a request to the Client API and the cached server list is older than value set to AUTO_SERVER_RANKING_LIFETIME. * During end-point analysis a number of requests are made to each end-point. Please note that these requests count towards your total hits to the Cloud service. e.g: ``` if # Server list contains 3 servers # AND Client.AUTO_SERVER_RANKING_LIFETIME == 1440 # AND Client.AUTO_SERVER_RANKING_NUM_REQUESTS == 3 then # Auto ranking will add 9 (3x3) hits per day ``` #### Methods #### * Get the ranked server list: ```python rankedServerList = client.getServers() ``` The first end-point in the list will be used to make a request to the cloud, if it fails the next end-point will be take it's place. * Get the end-point used for the last request: ```python server = client.getCloudUrl() ``` Note that if the data comes from cache this method will return "None". * Get end-point info. This is useful when you want to manually rank the server list: ```python server = client.getServersLatencies() ``` Please see https://deviceatlas.com/resources/cloud-service-end-points for more information. #### Cloud Server end-point settings #### ##### AUTO_SERVER_RANKING = True ##### To turn auto ranking on/off. To manually rank the servers set to "false" and edit the $SERVERS array to set your preferred order of end-points. The API will not rank the servers and will use the SERVERS list items directly with the topmost server used first to get device data. On fail- over the next end-point in the list will be used. ##### CLOUD_SERVICE_TIMEOUT = 2 ##### Time in seconds. If an end-point fails to respond in this amount of time the API will fail-over to the next end-point on the list. ##### AUTO_SERVER_RANKING_MAX_FAILURE = 1 ##### When auto ranking servers, if a server fails more than this number of times it will not be included in the list. ##### AUTO_SERVER_RANKING_NUM_REQUESTS = 3 ##### When auto ranking servers, number of requests to perform for service speed calculation. ##### AUTO_SERVER_RANKING_LIFETIME = 1440 ##### Time in minutes. How often to auto rank servers. 0 = servers will be ranked and cached only once and this list will not be updated automatically. You can update this list manually: client::rankServers() Note: AUTO_SERVER_RANKING must be set "true" so this cached server list will be used by the API, even if AUTO_SERVER_RANKING_LIFETIME is set to 0. If AUTO_SERVER_RANKING = False then the cached server list will be totally ignored. ##### SERVER_PHASEOUT_LIFETIME = 1440 ##### Used when auto ranking is OFF. Specifies how long to use the fail-over endpoints before the preferred end-point is re-checked. If the preferred end-point is available it will be added back into the list of end-points and used for future requests. ### Extra Tools ### This package comes with extra tools that can help you enhance your mobile websites. #### DeviceAtlas Client Side Component #### This is the DeviceAtlas Client Side component which discovers device info on client side to augment the server data. This library is used in the DeviceAtlas Cloud Client API examples. #### Latency Checker #### There are two command line tools included in this package to help you tweak the DeviceAtlas Cloud API end-point selecting. ##### Check Server Latency ##### This tool can be used to get info about the DeviceAtlas Cloud Service end-points. The info shown can be used for manually setting up the DeviceAtlas Cloud service end-points in the API. To access the cloud servers a valid DeviceAtlas licence would be required. Usage (command line): ```shell $ python deviceatlas-cloud-python-2.0.0.0/ExtraTools/LatencyChecker/CheckServerLatency.py LICENCE_KEY ``` ##### Update Server Ranking Cache ##### When AUTO_RANKING is set ON you can use this tool to re rank the DeviceAtlas Cloud end-points. All you need to do is to run this script in regular intervals which are smaller than the "AUTO_SERVER_RANKING_LIFETIME". Usage (command line): ```shell $ python deviceatlas-cloud-python-2.0.0.0/ExtraTools/LatencyChecker/UpdateServerRankingCache.py LICENCE_KEY ``` - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - _ Copyright (c) Afilias Technologies Limited 2019. 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 class="disabled"><a href="README.CloudApi.html">Cloud Client API</a></li><li><a href="README.Upgrade.html">Cloud API Upgrade</a></li><li><a href="./ApiDocs/index.html">Cloud Client API docs</a></li><li class="divider"></li><li><a href="README.ClientSide.html">Client-side Component</a></li></ul></div>