offen/analyticstxt
2
0
Fork 0
mirror of https://github.com/offen/analyticstxt.git synced 2024-11-22 09:00:29 +01:00
Code Issues Packages Projects Releases Wiki Activity

use a single sentence per line for easier diffing

Browse Source
This commit is contained in:
Frederik Ring 2021-03-26 20:16:44 +01:00
parent 766e4280d6
commit 44d8896e42
1 changed files with 57 additions and 24 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

81
draft-offen-analyticstxt.md
View File

@ -30,15 +30,22 @@ informative:
--- abstract --- abstract
Privacy has become an important feature for users of websites and services. This document propopes a discoverable way for websites and services to declare their usage of analytics and tracking software to both users and the tooling used by users. analytics.txt aims to be an elaborate standard that describes the usage of analytics and tracking software in a non-biased way that is understandable for a non-technical audience, but also useful for consumption by tools and software. Privacy has become an important feature for users of websites and services.
This document propopes a discoverable way for websites and services to declare their usage of analytics and tracking software to both users and the tooling used by users.
analytics.txt aims to be an elaborate standard that describes the usage of analytics and tracking software in a non-biased way that is understandable for a non-technical audience, but also useful for consumption by tools and software.
--- middle --- middle
# Introduction # Introduction
The usage of analytics software and user tracking on websites is becoming an increasingly important factor for users on the internet. Yet, there is no well-defined way of accessing such information in a standardized way. Legislation only covers certain technological implementations, incentivizing software to find workarounds, thus being able hiding their presence from users. Automated audits are limited to aspects that are possible to detect in clients. The usage of analytics software and user tracking on websites is becoming an increasingly important factor for users on the internet.
Yet, there is no well-defined way of accessing such information in a standardized way.
Legislation only covers certain technological implementations, incentivizing software to find workarounds, thus being able to hide their presence from users.
Automated audits are limited to aspects that are possible to detect in clients.
This document defines a way to specify the privacy related characteristics of analytics and tracking software. We aim for this information to be consumable both by humans as well as other software. For example, search engines or browser extensions could make use of this data and display information to users. This document defines a way to specify the privacy related characteristics of analytics and tracking software.
We aim for this information to be consumable both by humans as well as other software.
For example, search engines or browser extensions could make use of this data and display information to users.
The file "analytics.txt" is not intended to replace the requirement for complying to certain regulations, but supposed to give insights beyond the scope of these regulations. The file "analytics.txt" is not intended to replace the requirement for complying to certain regulations, but supposed to give insights beyond the scope of these regulations.
@ -59,18 +66,28 @@ The term "implementors" refers to the providers of services and websites that wi
This document defines a text file format that can be used by implementors to signal information about their usage of analytics software to both users and software. This document defines a text file format that can be used by implementors to signal information about their usage of analytics software to both users and software.
By convention, this file is called analytics.txt. Its location and scope are described in {{location}}. By convention, this file is called analytics.txt.
Its location and scope are described in {{location}}.
This text file contains multiple fields with different values. A field contains a "name" which is the first part of a field all the way up to the colon (for example: "Author:") and follows the syntax This text file contains multiple fields with different values.
defined for "field-name" in section 3.6.8 of {{?RFC5322}}. Field names are case-insensitive (as per section 2.3 of {{?RFC5234}}). The "value" comes after the field name and follows the syntax defined for "unstructured" in section 3.2.5 of {{?RFC5322}}. The file MAY also contain blank lines. A field contains a "name" which is the first part of a field all the way up to the colon (for example: "Author:") and follows the syntax
defined for "field-name" in section 3.6.8 of {{?RFC5322}}.
Field names are case-insensitive (as per section 2.3 of {{?RFC5234}}).
The "value" comes after the field name and follows the syntax defined for "unstructured" in section 3.2.5 of {{?RFC5322}}.
The file MAY also contain blank lines.
A field MUST always consist of a name and a value (for example: "Author: Jane Doe <jane.doe@example.com>"). An analytics.txt file can have an unlimited number of fields. Each field MUST appear on its own line. Unless specified otherwise by the field definition, multiple values MUST be chained together for a single field (for example: "Compliance: gdpr, ccpa") using the "," (%x2c). Unless otherwise indicated in a definition of a particular field, a field MAY NOT appear multiple times. A field MUST always consist of a name and a value (for example: "Author: Jane Doe <jane.doe@example.com>").
An analytics.txt file can have an unlimited number of fields.
Each field MUST appear on its own line.
Unless specified otherwise by the field definition, multiple values MUST be chained together for a single field (for example: "Compliance: gdpr, ccpa") using the "," (%x2c).
Unless otherwise indicated in a definition of a particular field, a field MAY NOT appear multiple times.
Implementors SHOULD aim for creating an analytics.txt file that is easy to understand by non-technical audiences. Implementors SHOULD aim for creating an analytics.txt file that is easy to understand by non-technical audiences.
## Comments ## Comments
Any line beginning with the "#" (%x23) symbol MUST be interpreted as a comment. The content of the comment may contain any ASCII or Unicode characters in the %x21-7E and %x80-FFFFF ranges plus the tab (%x09) and space (%x20) characters. Any line beginning with the "#" (%x23) symbol MUST be interpreted as a comment.
The content of the comment may contain any ASCII or Unicode characters in the %x21-7E and %x80-FFFFF ranges plus the tab (%x09) and space (%x20) characters.
Example: Example:
@ -86,19 +103,22 @@ Every line MUST end either with a carriage return and line feed characters (CRLF
## Extensibility ## Extensibility
Like many other formats and protocols, this format may need to be extended over time to fit the ever-changing landscape of the Internet. Special attention is required for defining the allowed values in enumerations to ensure they are a. extendable and b. do not become obsolete too quickly. Like many other formats and protocols, this format may need to be extended over time to fit the ever-changing landscape of the Internet.
Special attention is required for defining the allowed values in enumerations to ensure they are a. extendable and b. do not become obsolete too quickly.
## Field Definitions ## Field Definitions
Field names are case-insensitive, yet implementors SHOULD use the capitalized style used in this document for consistency. Field names are case-insensitive, yet implementors SHOULD use the capitalized style used in this document for consistency.
Field values are case-insensitive. In case a field contains an enumeration of multiple values, implementors MUST refer to the allowed values given by the specification. Field values are case-insensitive.
In case a field contains an enumeration of multiple values, implementors MUST refer to the allowed values given by the specification.
### Author {#author-field} ### Author {#author-field}
This REQUIRED field holds an OPTIONAL author name and a REQUIRED email address providing information about who is responsible for maintaining the contents of the file. The field MUST contain a valid email address which shall be used for inquiries about the correctness and additions to the data provided in the file. This REQUIRED field holds an OPTIONAL author name and a REQUIRED email address providing information about who is responsible for maintaining the contents of the file.
The field MUST contain a valid email address which shall be used for inquiries about the correctness and additions to the data provided in the file.
Example: #### Example
``` ```
Contact: Jane Doe <jane.doe@example.com> Contact: Jane Doe <jane.doe@example.com>
@ -106,7 +126,8 @@ Contact: Jane Doe <jane.doe@example.com>
### Collects ### Collects
This REQUIRED multi-value field indicates which potentially privacy relevant user specific data is being collected or used in session identification. These MUST also be specified if properties are not persisted as-is, but stored or otherwise computed in a hashed and/or combined form. This REQUIRED multi-value field indicates which potentially privacy relevant user specific data is being collected or used in session identification.
These MUST also be specified if properties are not persisted as-is, but stored or otherwise computed in a hashed and/or combined form.
#### Allowed values #### Allowed values
@ -144,7 +165,8 @@ The duration of a visit, either on page- or on session-level is measured and use
##### custom-events ##### custom-events
Custom events like conversion goals are defined and used. This can be left out in case the analytics software in use offers such functionality, but implementors chose not to use the feature. Custom events like conversion goals are defined and used.
This can be left out in case the analytics software in use offers such functionality, but implementors chose not to use the feature.
##### session-recording ##### session-recording
@ -158,17 +180,20 @@ Collects: url, device-type, referrer
### Stores ### Stores
This REQUIRED multi-value field indicates whether data is persisted on the client during the collection of analytics data and declares the browser features used for doing so. If no data is being persisted, the value `none` MUST be used. This REQUIRED multi-value field indicates whether data is persisted on the client during the collection of analytics data and declares the browser features used for doing so.
If no data is being persisted, the value `none` MUST be used.
#### Allowed values #### Allowed values
##### first-party-cookies ##### first-party-cookies
First party cookies are in use. There is no differentiation between session or persistent cookies, just like HTTP and JavaScript cookies are considered equal. First party cookies are in use.
There is no differentiation between session or persistent cookies, just like HTTP and JavaScript cookies are considered equal.
##### third-party-cookies ##### third-party-cookies
Third party cookies are in use. There is no differentiation between session or persistent cookies, just like HTTP and JavaScript cookies are considered equal. Third party cookies are in use.
There is no differentiation between session or persistent cookies, just like HTTP and JavaScript cookies are considered equal.
##### local-storage ##### local-storage
@ -200,7 +225,7 @@ A client-side script is used to collect data.
##### pixel ##### pixel
A resource - typically a pixel - downloaded via HTTP is being used to collect data through the request parameters. A static resource - typically a pixel - downloaded via HTTP is being used to collect data through the request parameters.
##### server-side ##### server-side
@ -222,7 +247,8 @@ Uses: script
### Allows ### Allows
This REQUIRED multi-value field discloses information about whether user consent is being acquired before collecting analytics data, and if it is possible for users to opt out of the collection of usage data. Regulations about user consent do not apply to this field. This REQUIRED multi-value field discloses information about whether user consent is being acquired before collecting analytics data, and if it is possible for users to opt out of the collection of usage data.
Existing regulations about user consent do not apply to this field.
#### Allowed values #### Allowed values
@ -246,7 +272,9 @@ Allows: opt-in, opt-out
### Retains ### Retains
This REQUIRED single-value field indicates the duration for which the analytics data is being stored before being delete. The value is a duration as defined in {{!RFC 3339}}. Implementors SHOULD add a comment providing a human readable value to this field. This REQUIRED single-value field indicates the duration for which the analytics data is being stored before being delete.
The value is a duration as defined in {{!RFC 3339}}.
Implementors SHOULD add a comment providing a human readable value to this field.
#### Example #### Example
@ -257,7 +285,8 @@ Retains: P12M
### Session ### Session
This OPTIONAL, RECOMMENDED single-value field indicates the coverage in session tracking. It MUST contain a single value only. This OPTIONAL, RECOMMENDED single-value field indicates the coverage in session tracking.
It MUST contain a single value only.
#### Allowed values #### Allowed values
@ -393,13 +422,16 @@ In case multiple of these signals are being used, the precedence taken is:
## Scope of a file ## Scope of a file
An analytics.txt file MUST only apply to the domain or IP address in the URI used to retrieve it, not to any of its subdomains or parent domains. An analytics.txt file MAY also apply to products and services provided by the organization publishing the file. An analytics.txt file MUST only apply to the domain or IP address in the URI used to retrieve it, not to any of its subdomains or parent domains.
An analytics.txt file MAY also apply to products and services provided by the organization publishing the file.
# Security Considerations # Security Considerations
## Incorrect or stale information ## Incorrect or stale information
If information given in an "analytics.txt" file is incorrect or not kept up to date, this can result in usage of services under wrong assumptions, thus exposing users to possibly unwanted data collection and handling. Not having an "analytics.txt" file may be preferable to having incorrect or stale information in this file. Implementors MUST use the "Author" field (see {{author-field}}) to allow inquiries about the correctness of the given information. If information given in an "analytics.txt" file is incorrect or not kept up to date, this can result in usage of services under wrong assumptions, thus exposing users to possibly unwanted data collection and handling.
Not having an "analytics.txt" file may be preferable to having incorrect or stale information in this file.
Implementors MUST use the "Author" field (see {{author-field}}) to allow inquiries about the correctness of the given information.
## Spam ## Spam
@ -407,7 +439,8 @@ Implementors should be aware that disclosing mandatory author information as per
## Multi-user Environments ## Multi-user Environments
In multi-user / multi-tenant environments, it may possible for a single user to take over the location of the "/.well-known/security.txt" file which would also apply to others. Organizations should ensure the ".well-known" location is properly protected. Implementors can instead use other locations as per {{location}} in such scenarios. In multi-user / multi-tenant environments, it may possible for a single user to take over the location of the "/.well-known/security.txt" file which would also apply to others.
Organizations should ensure the ".well-known" location is properly protected. Implementors can instead use other locations as per {{location}} in such scenarios.
# IANA Considerations # IANA Considerations