Client device detection

Try to guess client device.

/!\ It uses UserAgent, so don't rely on this for critical stuff

This autoload bundle only works with the website socle.

• Dependencies
• Request
• Autoload configuration
• Route configuration as middleware
• Device feature support
• BuiltIn feature support

Dependencies

• detect-browser

Request

It will add a new property on the request object: request.clientDevice.

It contains (example with Chrome 89):

{
    "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/89.0.4389.90 Safari/537.36",
    "browser": "chrome",
    "features": {},
    "version": {
        "text": "89.0.4389.90",
        "major": 89,
        "minor": 0,
        "patch": 4389
    },
    "type": "browser",
    "isUnknown": false,
    "isBrowser": true,
    "isBot": false,
    "isiOS": false,
    "isAndroid": false,
    "isWindows": false,
    "isMacOs": true
}

Autoload configuration

The package will be automatically added to to the autoload array in the config/app/bundles.json file.

If not, do it manually:

{
    "autoload": [
        ...,
        {
            "name":   "@creative-web-solution/client-device-detection"
        },
        ...
    ]
}

You can set a configuration if needed:

{
    "autoload": [
        ...,
        {
            "name":   "@creative-web-solution/client-device-detection",
            "config": {
                "configName": "clientDeviceDetection"
            }
        },
        ...
    ]
}

Add a clientDeviceDetection.json file in config/packages/ looking like this:

{
    "clientDeviceDetection": {
        // Optional: See below for feature detection
        "builtIn": [ "builInFeatureName" ],
        // Optional
        "features": {
            // See below for feature detection
            ...
        }
    }
}

It will be executed on every route except the static ones.

Configuration as middleware

export default [
    {
        "name":   "some.route",
        "route":  AppPath.getUrlWithBasePath( '/path' ),
        "method": "get",
        "middlewares": [
            addMiddleware({
                "middlewarePath": "@creative-web-solution/client-device-detection",
                // Optional
                "data": {
                    // Optional: See below for feature detection
                    "builtIn": [ "builInFeatureName" ],
                    "features": {
                        // See below for feature detection
                        ...
                    }
                }
            }),
            ...
        ]
    }
]

See "Custom middlewares" in 7-middlewares.md to access the result in the controller.

Device feature support

Add a features property the the data object sent to the middleware. it's contain the name of the feature and the browser version it works on:

{
    "features": {
        "featureName": {
            "browserName1": [ major [, minor [, patch ]] ],
            "browserName2": [ major [, minor [, patch ]] ]
        }
    }
}

major version is mandatory

For example with webp images support:

export default [
    {
        "name":   "some.route",
        "route":  AppPath.getUrlWithBasePath( '/path' ),
        "method": "get",
        "middlewares": [
            addMiddleware({
                "middlewarePath": "@core/Middleware/ClientDeviceDetection",
                "data": {
                    "features": {
                        "webp": {
                            // Optional
                            "header": [ "accept", "image/webp" ],
                            "deviceVersion": {
                                "chrome":   [ 32 ],
                                "firefox":  [ 65 ],
                                "edge": [ 18 ],
                                "edge-chromium": [ 88 ],
                                "opera": [ 19 ],
                                "samsung": [ 4 ],
                                "ios": [ 14, 5 ]
                            }
                        }
                    }
                }
            }),
            ...
        ]
    }
]

header is optional and has 2 versions:

• With 1 parameter like header": [ "some-header" ]: check the header existence
• With 2 parameters like header": [ "some-header", "some-value" ]: check the header value (lowerCase the header value and use indexOf on it to check)

deviceVersion is optional. Here the list of available browsers name:

aol, edge, edge-ios, yandexbrowser, kakaotalk, samsung, silk, miui, beaker, edge-chromium, chrome, chromium-webview, phantomjs, crios, firefox, fxios, opera-mini, opera, ie, bb10, android, ios, safari, facebook, instagram, ios-webview, curl, searchbot

If both header and deviceVersion are set, the header will be check first. If the feature is not detected with the header part, the deviceVersion check will be use.

It will update the features property of the result object, with the name of the feature and true or false

{
    "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/89.0.4389.90 Safari/537.36",
    "browser": "chrome",
    "features": {
        "webp": true
    },
    ...
}

BuiltIn feature support

There are 3 features test:

• lazyLoading
• webp
• avif

To use it, insert their name in the builtIn array:

{
    "clientDeviceDetection": {
        "builtIn": [ "lazyLoading", ... ],
        // Optional
        "features": {
            ...
        }
    }
}