User agent list
A list of apps, services and bots that consume podcast data. (A human view is over here).
Contributing to the list
For now, the simplest way is to add to the file at
src/user-agents.json. Each app, service or
bot should have its own entry.
Each entry must contain the following properties:
user_agents(array of strings): a list of regular expressions against which the requesting user-agent should be validated. Backslaches ("\") should be escaped, so instead of
^Echo\/1\., the string should read
Each entry can contain one of the following properties:
bot(boolean): set to
truewhen the requesting agent is a bot (no need to set to
app(string): set to the human-readable name of the app or service.
device(string): set to a slug of the device type, usually one of
pc(meaning a desktop or laptop computer running Linux, macOS or Windows)
radio(a smart radio)
os(string): set to the slug of the operating system, usually one of
description(string): intended to be a humanly readable description of the app, bot or other
infourl(string): a link to the homepage of the app, bot or other, for public consumption
svg(string): a name of a square SVG file, intended for use in app dashboards for identification purposes
developernotes(string): freeform notes for developers, where it is helpful to leave notes on behaviour of certain useragents or bots.
bot is set to
true, no other properties need to be specified.
A slug is a lowercase alphanumeric (ASCII) representation of a string, consisting only of numbers, letters and, in our case, underscores. It's up to apps that implement the list to display this information however they see fit, and using a slug is better for disambiguation.
It is proposed that we only specify a property above when it is known (not assumed). For example, it's often difficult to know whether an Android app is running on a phone or a tablet. We can assume that since Android tablets are rarer, almost all requests will be via Android phones, but we can't know that.
Right now, there isn't a great deal of thought put into the order... it's sort-of alphabetical depending on circumstance. It might be worth ordering based on the accuracy of each set of regexes.
To stop the list becoming unwieldy, in the future it may be possible to separate out the apps into separate files, that are then combined together automatically. That makes it harder to make a static list available via Github, but it's possible to run a static site and use a CI script -- a script that is called when code is committed to this repository -- to combine the files and generate the static file.
Happy to accept advice or actual code to make this happen :)
Also, if we do use multiple files, it will become necessary to have some sort of
property for each agent, so that they can be combined in parsing order.