@realeyes/environment-detector/docs/README.md

# Environment Detector

## Installation

### NPM version

**Highlight:** flash detection removed from version 2.0

    $ npm i --save @realeyes/environment-detector

If you need to detect flash then you should use previous 1.x versions of Environment Detector for example install the latest 1.x

    $ npm i --save @realeyes/environment-detector@1.8.6

### CDN version

The general format for the script URL is `"https://codesdwncdn.realeyesit.com/environment-detector/release/{version}/environment-detector.js"`. You can specify which kinds of updates your app can accept using [semver](https://docs.npmjs.com/getting-started/semantic-versioning) string in a following format:
- `x.y` to receive bug fixes only: `https://codesdwncdn.realeyesit.com/environment-detector/release/2.0/environment-detector.min.js`
- `x` to receive bug fixes and new features (**recommended**): `https://codesdwncdn.realeyesit.com/environment-detector/release/2/environment-detector.min.js`

```html
<script src="https://codesdwncdn.realeyesit.com/environment-detector/release/2/environment-detector.min.js"></script>
```

### Self hosted

To create a self-hosted solution you will need to download the library archive [https://codesdwncdn.realeyesit.com/environment-detector/release/2/environment-detector.zip](https://codesdwncdn.realeyesit.com/environment-detector/release/2/environment-detector.zip). The archive contains the following files:
- environment-detector.js - Detector library 
- environment-detector.min.js - Minified version
- index.html - Example page
- log.gif - Tracking pixel

To use to detector you will need environment-detector.js.

```html
<script src="https://example.com/environment-detector.js"></script>
<script>
Realeyesit.EnvironmentDetector.detect()
    .then(function (result) {
        // result will be an EnvironmentDetectionResult object
    });
</script>
```

## API

The `Realeyesit.EnvironmentDetector` namespace contains one method: `detect()`. This method returns a `Promise` object that resolves with the EnvironmentDetectionResult object.
This is the type definition for the EnvironmentDetectionResult:

    {
      browser: {
        name: string,
        version: string,
      },
      platform: {
        type: string,
      },
      os: {
        name: string,
        version: string,
      },
      webcams: Array.<string>,
      capabilities: Array.<string>
    }

* **browser.name** is a string like "Chrome" or "Firefox"
* **browser.version** is a version string like "53.0"
* **platform.type** is one of "tablet", "mobile" or "desktop"
* **os.name** is a string like "windows" or "macos"
* **os.version** is a version string like "10.11"
* **webcams** is an array of strings, for example \["USB Camera", "iSight"\]
* **capabilities** is an array of strings

Here is the list of capabilities we can detect:

    {
        GET_USER_MEDIA: 'navigator.getUserMedia',
        MEDIA_RECORDER: 'MediaRecorder',
        WEBCAM: 'webcam',
        DOCUMENT_ALL: 'document.all',
        DOCUMENT_QUERY_SELECTOR: 'document.querySelector',
        HTTP: 'http',
        HTTPS: 'https',
    }

The `detect()` method can receive an optional `options` object with the following type definition:

    {
      logger: {
        path: string, // url of the tracking pixel
        disable: boolean, // pass true if you want to disable logging
      } // logger settings
    }

## Example usage

```javascript
Realeyesit.EnvironmentDetector.detect()
    .then(function (result) {
        // result will be an EnvironmentDetectionResult object
    });
```


## License

Copyright 2018 Realeyes OU.

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.