Use Adobe Analytics data to target browsers.
browserslist-adobe-analytics provides a CLI and Node API which can pull analytics data about what browsers your users use, and convert that data into a
browserslist-stats.json file so browserslist can select the appropriate browsers based on your user base. To achieve this a browser report is fetched from the Adobe Analytics API, each browser entry is then converted to the format browserslist supports.
Please note that to do this browserslist-adobe-analytics uses very loose matching rules e.g:
Chrome 1.2.3 could be interpretted as
chrome 1.2.7 in browserslist land, this is so we do not ignore any data. It is better to support more browsers less accurately than less browsers more accuratly in my opinion, so please do not rely on the output to report actual browser usage.
Important Note: In order to use this package an Adobe Experience Cloud account with a valid Adobe Analytics license is required. You will also need developer permissions in order to create an integration.
Creating an Adobe Analytics Integration
You will need an Integration for Adobe Analytics as it will allow you to set up JWT authorization so browserslist-adobe-analytics can retrieve your user browser usage data.
- Log in to the Adobe I/O Console: https://console.adobe.io/
- Navigate to the "Integrations" tab, make sure the dropdown in the top-left is set to the correct organization and select "New Integration".
- Go through the setup wizard selecting the following:
- Q: "Do you want to access an API or receive near-real time events?" A: "Access an API"
- Q: "Select the Adobe service you wish to integrate with" A: "Experience Cloud" > "Adobe Analytics" > "Service Account Integration"
- Q: "Integration Details" A:
- The name and description is up to you, I went with "Browserslist Integration" and "Pull Adobe Analytics data to use as custom data for browserslist."
- For "Public keys certificates" follow https://github.com/AdobeDocs/adobeio-auth/blob/stage/AuthenticationOverview/ServiceAccountIntegration.md#step-2-create-a-public-key-certificate
- Q: "Select one or more product profiles for Adobe Analytics" A: "Reports & Analytics Access" 5: Finally click "Continue to Integration Details" and you will have access to most of the information you will need to pass to browserslist-adobe-analytics
Using this module
browserslist-adobe-analytics is shipped as an npm module. It has 2 primary ways of usage, either via the CLI or via the Node API. Either way you will need to install it either on a per project basis or as part of a shareable config. To install the module use:
yarn add browserslist-adobe-analytics --dev # or npm install browserslist-adobe-analytics --save-dev
The CLI (Command Line Interface) provides a configurable way to generate a
browserslist-stats.json file from your preferred terminal. This is intended to facilitate CI (Continuos Integration) processes, as well as quickly testing the API locally.
There are 2 commands provided:
baa writewhich directly writes the statistics data to a
browserslist-stats.jsonfile in the cwd (current working directory). The configurable options can be seen below:
$ baa write --help baa write Write browserslist stats to file from Adobe Analytics data. Adobe Analytics --clientId, --cid Integration client ID. [string] [required] --technicalAccountId, -t Integration technical account ID. [string] [required] --orgId, -o Integration organization ID. [string] [required] --clientSecret, --cs Integration client secret. [string] [required] --privateKey, --pk Integration private key. [string] --privateKeyPath, --pkp Integration private key path. [string] --passphrase, -p Passphrase used to secure integration public/private key. [string] --ims, -i Identity management system ID. [string] --rsid, -r Report Suite ID. [string] [required] --globalId, -g Global ID. [string] [required] --limit, -l The maximum number of browser entries to request. [number] [default: 50] Time --duration, -d Period of time to request data for. [string] [default: P3M] --from, -f Date to request data from. [string] --until, -u Date to request data until. [string] [default: Today's date] File Writing --cwd, -c The current working directory to write the file in. [string] [default: process.cwd()] --filename, --fn The name of the file to write. [string] [default: browserslist-stats.json] Options: --version Show version number [boolean] --config Path to JSON config file --help Show help [boolean]
baawhich logs the statistics data in JSON format to the command line. This is intended for testing locally and also provides a way to use unix output redirection (e.g:
baa > browserslist-stats.json). The configurable options can be seen below:
$ baa --help baa Generate browserslist stats from Adobe Analytics data. Commands: baa Generate browserslist stats from Adobe Analytics data. [default] baa write Write browserslist stats to file from Adobe Analytics data. Adobe Analytics --clientId, --cid Integration client ID. [string] [required] --technicalAccountId, -t Integration technical account ID. [string] [required] --orgId, -o Integration organization ID. [string] [required] --clientSecret, --cs Integration client secret. [string] [required] --privateKey, --pk Integration private key. [string] --privateKeyPath, --pkp Integration private key path. [string] --passphrase, -p Passphrase used to secure integration public/private key. [string] --ims, -i Identity management system ID. [string] --rsid, -r Report Suite ID. [string] [required] --globalId, -g Global ID. [string] [required] --limit, -l The maximum number of browser entries to request. [number] [default: 50] Time --duration, -d Period of time to request data for. [string] [default: P3M] --from, -f Date to request data from. [string] --until, -u Date to request data until. [string] [default: Today's date] Options: --version Show version number [boolean] --config Path to JSON config file --help Show help [boolean] For possible duration formats see https://momentjs.com/docs/#/durations/ For possible date formats see https://momentjs.com/docs/#/parsing/string/
The Node API provides a more raw approach where you can retrieve a stats object in order to directly pass it to browserslist's JS API.
There are 2 exported methods from the primary API:
getBrowserslistStats(options)which will return a Promise which resolves to a browserslist stats object. See options section for more details.
writeBrowserslistStats(options)which will return a promise which when resolved will have generated and written a
browserslist-stats.jsonfile assuming nothing goes wrong. See write options section for more details.
clientSecret can all be found on your integration details page after you have followed the steps from Creating an Adobe Analytics Integration.
You need to specify one of either
privateKeyPath, which should be the raw contents of the
private.key file that you generated during the "Creating an Adobe Analytics Integration" step or a path to said file.
passphrase is optional so only pass it if you secured your public/private key with a passphrase when creating it.
ims is optional and you likely do not use the Identity Manager System, but if you do see https://docs.adobe.com/content/help/en/campaign-classic/using/integrating-with-adobe-experience-cloud/connecting-via-an-adobe-id/configuring-ims.html.
To find your
rsid do the following:
- Login to Adobe Experience Cloud: https://experiencecloud.adobe.com
- Navigate to Adobe Analytics either in the "Quick Access" section or the menu on the top nav.
- Select your report suite in the top right (the one you want to pull browser data from).
- Open a report e.g. "Technology: PC / Browsers".
- Click "Try in Workspace [NEW]" at the top of the report.
- Open devtools and type
adobe.tools.debug.includeOberonXml = truein the console, and refresh the page.
- Click one of the debug (beatle) icons in the report then select the latest "Freeform Table" request.
- Scroll down to the JSON request, the first field should be
To find your
globalId do the following:
- Navigate to https://adobedocs.github.io/analytics-2.0-apis/ and login.
- Open the "/reports" accordion and click "Try it out" next to "Parameters".
- Click "Execute" you should see a "Request URL" field.
- The "Request URL" field should look something like
https://analytics.adobe.io/api/company0/reportswhere company0 is your
The time settings
until are all parsed with moment.js. The Node API can accept anything that
moment.duration can accept whereas the CLI can only accept single strings so you are best using the ISO 8601 format. Only one of
until should be used, they basically define the anchor point for where the duration is added or subtracted from/to respectively.
||Integration client ID.||
||Integration technical account ID.||
||Integration organization ID.||
||Integration client secret.||
||Integration private key.||
||Integration private key path.||
||Passphrase used to secure integration public/private key.||
||Identity management system ID.||
||Report Suite ID.||
||Period of time to request data for.||
||Date to request data from.||
||Date to request data until.||
||The maximum number of browser entries to request.||
These are additional options used when writing directly to a file. The standard options also need to be specified.
||The current working directory to write the file in.||
||The name of the file to write.||
This module was built to facilitate Xerox's shareable browserslist configuration which generates a new
browserslist-stats.json file every month based on the previous 3 months of analytics data across all the various Xerox websites. Said config is open-source and uses a CircleCi cron job to run the
baa CLI. You can view the implementation here: https://github.com/xeroxinteractive/config/tree/master/packages/xerox-browserslist-config