Skip to content

Latest commit

 

History

History
215 lines (171 loc) · 13.6 KB

Vendor Device Storage & Operational Disclosures.md

File metadata and controls

215 lines (171 loc) · 13.6 KB

Vendor Device Storage & Operational Disclosures

IAB Europe Transparency & Consent Framework

Final v.2.0 | August 2019, Updated November 2022

Table of Contents

Version History

Date Version Comments
September 2022 1.0 Adding a new FAQ
June 2022 1.0 Update on the structure of the URL (path and filename) and use of this file by the CMPs
April 2022 1.0 Wildcards are now permitted through the field named identifier, adding a new field named domains and Disclosures object can be empty if the vendor does not make use of any client-side storage.
February 2022 1.0 Initial version. Augments and supersedes the Device Storage Duration & Access Disclosure specification.

Summary

This document is one of the IAB Europe Transparency and Consent Framework Specifications. It defines operational information disclosures required of Vendors by the Framework and the structure for publishing them. This information includes granular vendor device storage disclosures, as well as the complete list of domains the vendor uses. CMPs may disclose portions of this information to data subjects in Framework UIs. Transparency related to device storage took on urgency after a ruling by the Court of Justice of the European Union in Case C-673/17 Planet49.

Audience

Vendors who need to publish these disclosures, or registered CMPs, Publishers and others who wish to process them can use this document.

Relevant Documents

Required Information and JSON Structure

The TCF registration process requires Vendors to provide a secure URL to a JSON resource that conforms to the content and structure specified below. The Managing Organisation publishes the URL in the deviceStorageDisclosureURL` field in the Global Vendor List (GVL) along with other Vendor registration information.

The JSON contains two types of information, disclosures related to device storage access and duration (the Disclosures array and attributes) and the web domains the Vendor uses (the Domains array and attributes). Both are required, though not all information within each array is required. See the tables below.

Disclosures array

Vendors that use web-based storage MUST publish granular disclosures for ‘cookie’ and ‘web’ mechanism types. Vendors MAY provide ’app’ storage type disclosures, but are not required to do so. Vendors should leave the Disclosures array empty if they do not make use of any client-side storage.

FieldScopeTypeDescription
identifierrequiredstringKey or object name, depending on type, for the storage item. Wildcards '*' are permitted. For example, "id*" or "*id" describes multiple prefixed or suffixed identifiers, all having the same purpose(s).

Note : A wildcard alone is invalid. A wildcard MUST NOT be used to group different identifiers with different purpose(s), therefore disclose a separate record for each specific identifier.
typerequiredenumWhat type of storage or access mechanism is used: 'cookie', 'web', ‘app’. Note 'web' can represent local/session storage and IndexedDB.
maxAgeSecondsrequired if type = 'cookie' else nullintegerOnly required if type = ‘cookie’; otherwise null. The number, in seconds, of the duration for storage on a device, as set when using cookie storage. A 0 indicates session storage similar to the Set-Cookie spec. Note: this only includes what is declared when the storage is set and does not consider duration extensions should storage be refreshed.
For types of mechanisms (non-cookie) where duration cannot be set, this field should be null.
cookieRefreshonly required if type = ‘cookie’booleanIndicates the vendor is refreshing a cookie. See cookieRefresh description in the core specification. True indicates the vendor refreshes this cookie. False indicates the vendor does not refresh the cookie any time the browser reloads.
domainsoptionalarray

Use of this field is preferred. The less flexible domain field may be deprecated in a future release.

Required if type='cookie' or type='web'.

Value is one or more strings describing a domain.

Wildcards '*' are permitted. For example, "*.adtech123.com" indicates the identifier is used across multiple subdomains.

A wildcard alone is permitted only in cases where the number of domains is large and dynamic, such as when managing first party storage on many partners' properties.

Note : A wildcard MUST NOT be used to group identifiers having different purpose(s) with a group of domains.

domainoptionalstring

This field cannot be used at the same time as the field named domains when declaring one or multiple identifier(s). This field can only be used to declare one or multiple identifier(s) with only one domain. This field may be removed in a future release to only use the field domains.

Required if type='cookie' or type='web'.

Wildcards '*' are permitted. For example, "*.adtech123.com" indicates the identifier is used across multiple subdomains.

A wildcard alone is permitted only in cases where the number of domains is large and dynamic, such as when managing first party storage on many partners' properties.

Note : A wildcard MUST NOT be used to group identifiers having different purpose(s) with a group of domains. If an identifier is used for the same purposes on a finite set of domains, then disclose a separate record for each specific domain, e.g. one each for 'retarget.adtech123.com', 'retarget.adtech123.net' 'register.adtech123svcs.com', and so on.

purposes required array<integer> The purpose ID or purpose IDs from the Global Vendor List (GVL) for which the storage is used.

To indicate that use of the storage is subject to the consent requirement of the ePrivacy Directive, include Purpose ID 1 from the GVL.

To indicate that the use of storage is exempted from (and therefore not subject to) the consent requirement of the ePrivacy Directive, do not include Purpose ID 1 from the GVL.

Example 1

Below is sample JSON for a fictional TCF Vendor named AdTech123. AdTech123 owns the domain adtech123.com and has a "third-party" retargeting cookie that is set on the domain of retarget.adtech123.com. They also maintain a localStorage object that contains a user object with key “id” that can be accessed via JavaScript at window.localStorage.id.

{
  "disclosures": [
    {
      "identifier": "retarget-adtech123",
      "type": "cookie",
      "maxAgeSeconds": 2592000000,
      "cookieRefresh": false,
      "domains": ["retarget.adtech123.com"], 
      "purposes": [1,3,4,5,6]
    },
    {
      "identifier": "id",
      "type": "web",
      "maxAgeSeconds": null,
      "cookieRefresh": false,
      "domains": ["tracking.adtech123.com"], 
      "purposes": [1,3,4,5,6,7,8,9,10]
    }
  ],
  "domains": [
    ...
  ]
}

Example 2

Below is sample JSON for a fictional TCF Vendor that does not make use of any client-side storage.

{
    "disclosures": [],
    "domains": [
        ...
    ]
}

Domains array

Vendors MUST publish the domains they use for collecting and processing personal data in the context of their TCF registration. Vendors MUST NOT include Publishers’ delegated domains or subdomains they may use.

FieldScopeTypeDescription
domainrequiredstring“*.vendor.com” means multiple subdomains may exist.

Entry MUST NOT contain “http(s)://” or text other than the domain.
useoptionalstringTextual explanation of what the domain is used for.

There is no mechanism for requesting alternate translations. For widest readability, it is suggested that Vendors use English for the optional explanatory text.

Example

{
  "disclosures": [
    ...
  ],
  "domains": [
    {
      "domain": "retarget.adtech123.com",
      "use": "Retargeting and conversion tracking"
    },
    {
      "domain": "static.adtech123.com",
      "use": "Static CSS and JavaScript"
    },
    {
      "domain": "tracking.adtech123.com",
      "use": "Ad server and tracking"
    },
    {
      "domain": "video.adtech123.com",
      "use": "Video and banner distribution"
    }
  ]
}

Serving the JSON Resource

Around the JSON file

The vendor publishes the information and provides the URL (the specification makes no assumptions or requirements about the URL) to the TCF during the registration process. This file:

  • is in JSON format,
  • is created, named, and published by the vendor,
  • is publicly accessible,
  • contains cookies and/or other storage mechanisms (Localstorage etc...) and domains used for collecting and processing personal data in the context of TCF.

The URL need not be served by the Vendor’s company domain. It could be served from a CDN.

The role of the CMP

Usually, the CMP requests the file only when/if a user clicks to review additional information (it's unusual for the information to be disclosed directly on the secondary layer). In order to allow CMPs to request and load the JSON file on the client side, the vendor must enable Cross-Origin Resource Sharing (CORS) at the location servicing the URL. However, regardless of whether the CMP requests the JSON file from the vendor's server or CMP's server, Access-Control-Allow-Credentials must be set to false in order to not include any cookie in the request. Vendors must respond with the appropriate content-type header (application/json) and Cache-Control Directives so that CMPs are accessing and using the latest content when fetching from users’ browsers or when caching the file on their servers. A vendor should not use a cache-control directive of less than 24 hours.

CMPs must observe vendors’ cache-control directives when caching vendors’ JSON files. When the vendor has not configured any cache-control directives or the cache-control directive is invalid (less than 24 hours), CMPs must refresh the cached vendor’s JSON file at least daily.

In cases of unavailability of the vendor’s JSON file or non-conformance with the content and structure specified in the specifications, CMPs may rely, if available, on a previous version of the vendor’s JSON file temporarily and until the issue is resolved. (To expedite resolution, unavailability and non-conformance of a vendor’s JSON file can be reported using the non-compliance form here.)

Access method

For secure communications, the vendor must make publicly accessible the JSON file via HTTPS only (uses TLS or SSL to encrypt HTTP requests and responses) on the standard ports (80 and 443, respectively).

FAQ

The FAQ addresses questions including the use of domains instead of domain field, the use of wildcards, when the storage mechanism is set by a first party etc… The document will be updated over the time.