Query the server-side information from the users agent data.
- Credit
- Installation
- Check
- Redirect
- Data
- Full
- Browser/platform version
- Magic is-method
- Mobile Detection
- Match User Agent
- Accept Languages
- Device Name
- Desktop Detection
- Phone Detection
- Robot Detection
- Robot Name
- Extra
- Agent.js
Via compsoer:
composer require marknotton/agent
Or manually in your compsoer.json:
"require": {
"marknotton/agent": "^1.1.4"
}
Perform a number of checks to determine wether the users browser type is a match. Returns boolean
.
Returns true if current browser is either 'IE, Edge, or Firefox'
{{ craft.agent.check('ie', 'edge', 'firefox') }}
Returns true if current browser is greater than IE 9
{{ craft.agent.check('ie > 9') }}
Returns true if current browser is greater or equal to IE 9
{{ craft.agent.check('ie => 9') }}
Returns true if current browser is either, IE version 9, Chrome version 50 or above, or any version of Firefox
{{ craft.agent.check('ie 9', 'chrome > 49', 'firefox') }}
Redirect users if their current agent doesn't meet any of these conditions. Following the same syntax as the 'check' function, this will redirect users to a specific template. You can also pass in a status code too.
{% set criteria = [
'ie 11',
'chrome > 55',
'firefox > 44',
'safari >= 7',
'edge >= 15',
'opera > 50'
] %}
{{ craft.agent.redirect(criteria, 'no-support.twig', 302) }}
Returns a string in the format of data attributes containing the browser name and version number, platform and device type. Ideal for querying via Javascript or CSS. See the included agent.js file for more information.
{{ craft.agent.data }}
data-browser="chrome 52"
if ( $('html[data-browser^=chrome]').length ) {...}
html[data-browser^=chrome] {...}
Simply returns the name and version of the users browser.
Returns browser name and version number in an array
{{ craft.agent.full }}
Returns browser name
{{ craft.agent.full.name }}
Returns version number
{{ craft.agent.full.version }}
MobileDetect recently added a version
method that can get the version number for components. To get the browser or platform version you can use:
{% set browser = craft.agent.browser() }}
{% set version = craft.agent.version($browser) }}
{% set platform = craft.agent.platform() }}
{% set version = craft.agent.version($platform) }}
Note, the version method is still in beta, so it might not return the correct result.
Magic method that does the same as the previous is()
method:
{{ craft.agent.isAndroidOS() }}
{{ craft.agent.isNexus() }}
{{ craft.agent.isSafari() }}
Check for mobile device:
{{ craft.agent.isMobile() }}
{{ craft.agent.isTablet() }}
Search the user agent with a regular expression:
{{ craft.agent.match('regexp') }}
Get the browser's accept languages. Example:
{% set languages = craft.agent.languages() %}
// ['nl-nl', 'nl', 'en-us', 'en']
Get the device name, if mobile. (iPhone, Nexus, AsusTablet, ...)
{{ craft.agent.device() }}
Get the operating system. (Ubuntu, Windows, OS X, ...)
{{ craft.agent.platform() }}
Get the browser name. (Chrome, IE, Safari, Firefox, ...)
{{ craft.agent.browser() }}
Check if the user is using a desktop device.
{{ craft.agent.isDesktop() }}
This checks if a user is not a mobile device, tablet or robot.
Check if the user is using a phone device.
{{ craft.agent.isPhone() }}
Check if the user is a robot. This uses jaybizzle/crawler-detect to do the actual robot detection.
{{ craft.agent.isRobot() }}
Get the robot name.
{{ craft.agent.robot() }}
All Agent service methods are accessible without the need to define 'craft.'. So all of the functions above can be called like this too:
{{ agent.browser() }}
Agent comes complete with a Javascript class to help make it easier to query some of the user agent data.
You can include the agent.js like this:
{% do view.registerJsFile(
craft.app.assetManager.getPublishedUrl('@agent/assets/scripts/agent.js', true),
{'position' : constant('\\yii\\web\\View::POS_HEAD')}
)%}
You can initialise it like this:
let agent = new Agent();
By default, we assume the Twig data function is defined in your HTML tag via Twig:
<html {{ craft.agent.data|default }}>
If you're using it on another tag, you'll need to define the element like this:
let agent = new Agent($('body')[0]);
Now you have access to these methods:
Function | Return Example | Description |
---|---|---|
agent.browser | {name: "chrome", version: "66"} |
Gets the users browser name and version number |
agent.viewport | {width: 1345, height: 1321} |
Gets the users viewport width and height |
agent.screen | {pixelWidth: 2560, pixelHeight: 1440} |
Gets the users device resolution. This takes into account condensed pixels |
agent.platform | osx |
Gets the users platform type |
agent.mobile | true |
Checks if the user is on a mobile device |
agent.tablet | true |
Checks if the user is on a tablet device |
agent.desktop | true |
Checks if the user is on a desktop |
agent.touch | true |
Checks if the users device supports touch input |
agent.orientation | landscape |
Checks the orientation of the users display/device |
agent.notch | left |
Checks if the users device has a notch, and tells you what side it's on |
Orientation, Touch, and Notch data is stored in the DOM window as device
. Referring to this will return something like this:
[orientation: "landscape", touch: true, type: "iphoneX", notched: true, notch: "left"]
All of the above methods are auto loaded when the Agent Class is initialised. Each method stores data to the DOM window. So rather than actioning each method when you need it, you can refer to the cached data in your Window. Meaning you can simply call browser
in your script to get the data. You can disable this by passing in false
as argument: new Agent(false)
.