# DeviceAtlas Client-side Component # The DeviceAtlas APIs can work in conjunction with a JavaScript property detection file and merge the resulting properties for use on the server side. The client properties are also available to other JavaScript libraries. The DeviceAtlas client detection file needs to be included on your web page for this to function. ## Introduction ## DeviceAtlas typically uses HTTP headers to accurately identify devices and return a set of properties. This is achieved by passing the headers to a server-side DeviceAtlas API. The API will do a lookup using the headers and return a set of properties. This approach is suitable for the vast majority of cases except for two situations: 1. Apple Devices: The data passed from Apple devices in the HTTP headers does not contain any information to indicate which specific model is accessing the server. It only shows if it is an iPhone, iPad or iPod Touch. This is a large problem if device specific data is required for these devices. Client-side data can be used to augment the server-side DeviceAtlas data to more accurately identify Apple devices. 2. Contextual information: Client-side data can help indicate the current context of the user/device such as the current device orientation of the device is or if the user has cookies enabled. It can also improve the server-side property set for JavaScript and HTML5 properties for less well-known browsers. ## Client-side Component ## DeviceAtlas provides a small client-side JavaScript library that can be included in a website. This library detects client-side properties and optionally creates a cookie containing the data. The cookie is used as a means of transferring the client-side data to the server but alternative approaches can be used such as sending the data in an Ajax request. The client-side data sent to the server must then be passed to the DeviceAtlas API along with the device HTTP headers. The API will use the HTTP headers and the client-side properties to more accurately detect Apple Devices and merge the server-side and client-side properties together. All of the client-side properties are also exposed on the client-side for use in other JavaScript code. Full documentation and example code is included in the API packages. ### Client-side Access to Properties ### The properties gathered from the DeviceAtlas JavaScript detection are available to other JavaScript functions and can be accessed on the client-side by using the "DeviceAtlas" namespace. **Example:** ```JavaScript // Does the browser support Web GL ? var supportsWebGl = DeviceAtlas.js.webGl; ``` The normal DeviceAtlas property name should be used to access the client-side property. ### Server Side Access to Properties ### The JavaScript detection file creates a special cookie with the detected client properties. The usage is different in the Enterprise and Cloud APIs. #### Use with Enterprise API #### If the cookie is available and the DeviceApiWeb extension is used, the API will automatically use the cookie contents as a part of the detection. However it is also possible to pass the client-side properties manually to the APIs. ** Apache / NGINX / IIS web server modules handle the cookie automatically. ** #### Use with Cloud API #### If the cookie is available and the API is configured to use the cookie, the API will automatically forward the cookie contents to the Cloud service and will be used as a part of the detection. For further information about usage of the Enterprise and Cloud APIs please, refer to their documentation. The client-side properties override any data file properties and also serve as an input into additional logic to determine other properties such iPhone models which are normally not detectable. The cookie containing the properties is called "DAPROPS". ### Basic Server Side Usage ### 1. Include the deviceatlas-X.X.min.js file on your web page. 2. In your web application, pass the contents of the DeviceAtlas cookie to the DeviceAtlas API. NOTE: the cookie contents will only be set after the first request. It is recommended to not rely on the client-side properties for the very first page. Please see the Example code bundled with the API for more information. ### Custom Configuration ### To customize a cookie name or other cookie parameters like a domain or a path you can use the code below - just remember that this code must be used before you include deviceatlas-X.X.min.js file. ```JavaScript var DeviceAtlas = { cookieName: 'DAPROPS', // the cookie name cookieExpiryDays: 1, // the time the cookie expires in days cookieDomain: '.yourdomain.tld', // custom domain cookiePath: '/' // custom path } ``` ### Sending client-side data via URL ### In a restricted environment where cookies are not allowed it is possible to get the client-side data using the JavaScript getPropertiesAsString() method and pass it as a URL parameter. NOTE: When integrating with a web application, the value should be fetched from the URL and passed to the DeviceAtlas API properly. **Example:** ```JavaScript <script type="text/JavaScript"> window.onload = function() { var img = document.createElement('img'); img.setAttribute('id', 'ad-banner'); img.setAttribute('src', './ads.php?DAPROPS=' + encodeURIComponent(DeviceAtlas.getPropertiesAsString())); document.body.appendChild(img); } </script> ``` ### Apple devices identification ### The DeviceAtlas Client-side Component add accuracy to the identification of Apple devices. Using it with the Enterprise and Cloud APIs, we can identify all variants of iPhone and iPad models as follows: | Apple device | Without Client-side | With Client-side 1.5 | | ------------ | ------------------- | -------------------- | | iPhone | iPhone | iPhone/iPhone 3G/iPhone 3GS | | iPhone 3G | iPhone | iPhone/iPhone 3G/iPhone 3GS | | iPhone 3GS | iPhone | iPhone/iPhone 3G/iPhone 3GS | | iPhone 4 | iPhone | iPhone 4 | | iPhone 4S | iPhone | iPhone 4S | | iPhone 5 | iPhone | iPhone 5/iPhone 5C | | iPhone 5C | iPhone | iPhone 5/iPhone 5C | | iPhone 5S | iPhone | iPhone 5S | | iPhone 6 | iPhone | iPhone 6 | | iPhone 6 Plus | iPhone | iPhone 6 Plus | | iPhone 6S | iPhone | iPhone 6S | | iPhone 6S Plus | iPhone | iPhone 6S Plus | | iPhone SE | iPhone | iPhone SE | | iPhone 7 | iPhone | iPhone 7 | | iPhone 7 Plus | iPhone | iPhone 7 Plus | | iPad | iPad | iPad | | iPad 2 | iPad | iPad 2/iPad mini | | iPad 3 | iPad | iPad 3 | | iPad 4 | iPad | iPad 4 | | iPad Air | iPad | iPad Air/iPad mini 2/iPad mini 3 | | iPad Air 2 | iPad | iPad Air 2 | | iPad mini | iPad | iPad 2/iPad mini | | iPad mini 2 | iPad | iPad Air/iPad mini 2/iPad mini 3 | | iPad mini 3 | iPad | iPad Air/iPad mini 2/iPad mini 3 | | iPad mini 4 | iPad | iPad mini 4 | | iPad Pro | iPad | iPad Pro | ### Adding device properties ### You can extend and customize capabilities of Client-side component by adding or replacing functions to detect device properties. **Example:** ```JavaScript <script type="text/javascript"> /** * Adding two new properties: * * platform: Platform the browser is built for (e.g. Win32). * js.alertSupport: Whether the JavaScript engine supports window.alert() function. * */ var DeviceAtlas = { properties: { 'platform': function() { return (navigator.platform) ? navigator.platform : null; }, 'js.alertSupport': function() { return (typeof window.alert === "function"); } } } </script> <script type="text/javascript" src="./deviceatlas-X.X.min.js"></script> ``` ### Client-side Component Variants ### #### Standard Library #### The standard version of the Client-side Component is distributed in the deviceatlas-x.x.min.js file. It provides the detection of [the full property set](https://deviceatlas.com/resources/client-side-properties). #### Lite Variant #### The Lite variant, a subset of the standard component for optimization purposes, is distributed in the deviceatlas-lite-x.x.min.js file. It solely identifies those device properties that are required to distinguish the underlying hardware of iOS based devices. #### Custom Build #### From DeviceAtlas site you can download a customized component with a subset of properties tailored specifically to your needs. The resulting JavaScript file will be optimized in terms of size and speed to improve end-user experience. Check out the [DeviceAtlas Client-side Component generator](https://deviceatlas.com/resources/clientside). - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - _ Copyright (c) DeviceAtlas Limited 2021. All Rights Reserved. _ <!-- 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 Detection API</a></li><li><a href="README.Upgrade.html">Device Detection API Upgrade</a></li><li><a href="DeviceApiDocs/mobi.mtld.da.device.device_api.DeviceApi-class.html">Device API docs</a></li><li class="divider"></li><li class="disabled"><a href="README.ClientSide.html">Client-side Component</a></li><li><a href="README.ConnectivityAnalyser.html">Connectivity Analyser</a></li><li class="divider"></li><li><a href="README.CarrierApi.html">Carrier Identification API</a></li><li><a href="CarrierApiDocs/mobi.mtld.da.carrier.carrier_api.CarrierApi-class.html">Carrier API docs</a></li></ul></div>