Conversion Measurement

Draft Community Group Report,

This version:
https://wicg.github.io/conversion-measurement-api
Issue Tracking:
GitHub
Inline In Spec
Editor:
(Google Inc.)

Abstract

A new API to measure and attribute cross-site conversions.

Status of this document

This specification was published by the Web Platform Incubator Community Group. It is not a W3C Standard nor is it on the W3C Standards Track. Please note that under the W3C Community Contributor License Agreement (CLA) there is a limited opt-out and other conditions apply. Learn more about W3C Community and Business Groups.

1. Introduction

This section is non-normative

This specification describes how web browsers can provide a mechanism to the web that allows measuring and attributing conversions (e.g. purchases) to ads a user interacted with on another site. This mechanism should remove one need for cross site identifiers like third party cookies.

1.1. Overview

An anchor tag with impressiondata and conversiondestination attributes is classified as an impression tag. When impression tags are clicked, and the resulting navigation commits in a document matching the conversiondestination, then the impression is stored in UA storage.

At a later point, the conversiondestination site may fire an HTTP request to trigger conversion registration, which matches up with any previously stored impressions. If matching impressions exist, they are scheduled to be reported at a later time, possibly multiple days in the future.

Reports are sent to reporting endpoints that are configured in impression tags and conversion registration requests.

2. Fetch monkeypatches

Patch into fetch for cancelling requests redirected to the .well-known conversion domain.

3. HTML monkeypatches

Rewrite the anchor element to accept the following attributes:

partial interface HTMLAnchorElement {
    [CEReactions, Reflect] attribute DOMString conversiondestination;
    [CEReactions, Reflect] attribute DOMString impressiondata;
    [CEReactions, Reflect] attribute DOMString reportingorigin;
    [CEReactions, Reflect] attribute unsigned long long impressionexpiry;
};

The conversiondestination is the declared destination scheme-and-registrable-domain of the anchor for purposes of conversion measurement

The impressiondata is a string containing information about the impression tag and will be supplied in the conversion report.

The reportingorigin declares the intended origin to send the conversion report for this impression.

The impressionexpiry is the amount of time in milliseconds the impression should be considered for conversion measurement and reporting reporting.

Need monkey patches passing impression data in navigation, and a mechanism for validating the resulting document matches the conversiondestination.

4. Structures

4.1. Impression

An impression is a struct with the following items:

4.2. Conversion

A conversion is a struct with the following items:

4.3. Conversion report

A conversion report is a struct with the following items:

5. Algorithms

5.1. Parsing a conversion destination

To parse a conversion destination from an a tag anchor,

  1. Let url be the result of running the URL parser on the value of the anchor’s conversiondestination.

  2. Return the result of obtaining a site from url’s origin.

5.2. Activating an impression

To activate an impression from an a tag anchor,

  1. Let currentTime be the current time.

  2. Let impression be a new impression struct whose items are:

    impression source

    anchor’s relevant settings object's top-level origin.

    impression data

    The result of applying parsing conversion data to anchor’s impressiondata attribute.

    conversion destination

    The result of running parse a conversion destination on anchor.

    reporting endpoint

    The origin of the result of running the URL parser on the value of anchor’s reportingorigin attribute.

    expiry

    currentTime + impressionexpiry milliseconds.

    impression time

    currentTime.

  3. Need to spec how to store the impression.

5.3. Creating a conversion

To create a conversion from a url url and an environment settings object environment, return a new conversion struct with the items:

conversion source

environment’s top-level origin.

conversion data

The result of applying parsing conversion data to the value associated with the "conversion-data" field of url’s query.

conversion time

The current time.

Formalize how to parse the query similar to URLSearchParams.

5.4. Register a conversion

To register a conversion from a request request, run the following steps:

  1. If request’s current url’s path is not .well-known/register-conversion, return.

  2. If request’s redirect count is less than 1, return.

  3. Let previousUrl be the second to last URL in request’s URL list.

  4. If request’s current url’s origin is not same origin with previousUrl’s origin, return.

  5. Let conversionToRegister be the result of applying create a conversion from the request’s current url.

    Note: the restriction to require a redirect is needed to ensure that the request’s origin is aware and in control of the conversion registration.

  6. Need to spec how to store the conversion.

5.5. Parsing data fields

This section defines how to parse and extract both impression data and conversion data from a string input and a unsigned long long maxData.

Parsing conversion data from input with maxData returns the result of the following steps:

  1. Let decodedInput be the result of decoding input as a base-16 integer.

  2. Let clampedDecodedInput be the remainder when dividing decodedInput by maxData.

  3. Let encodedOutput be the result of encoding clampedDecodedInput as a base 16 encoding.

  4. Return encodedOutput.

5.6. Establishing report delivery time

The report delivery time for an impression impression and a conversion time conversionTime is the result of the following steps:
  1. Let conversionTimeAfterImpression be the difference between the conversion time and impression time.

  2. Let expiryDelta be the difference between the expiry and the impression time

    Note: conversionTimeAfterImpression should always be less than expiryDelta because it should not be possible to convert an expired impression.

  3. If:

    conversionTimeAfterImpression <= (2 days - 1 hour)
    return impression time + 2 days.
    expiryDelta > (2 days - 1 hour)
    • and expiryDelta < (7 days - 1 hour)

    • and conversionTimeAfterImpression <= expiryDelta

    return the expiry + 1 hour.
    conversionTimeAfterImpression <= (7 days - 1 hour)
    return impression time + 7 days
    Otherwise
    return the expiry + 1 hour.

5.7. Queuing a conversion report

TODO

5.8. Establishing attribution credit

TODO

6. Security consideration

TODO

7. Privacy consideration

TODO

Conformance

Document conventions

Conformance requirements are expressed with a combination of descriptive assertions and RFC 2119 terminology. The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in the normative parts of this document are to be interpreted as described in RFC 2119. However, for readability, these words do not appear in all uppercase letters in this specification.

All of the text of this specification is normative except sections explicitly marked as non-normative, examples, and notes. [RFC2119]

Examples in this specification are introduced with the words “for example” or are set apart from the normative text with class="example", like this:

This is an example of an informative example.

Informative notes begin with the word “Note” and are set apart from the normative text with class="note", like this:

Note, this is an informative note.

Conformant Algorithms

Requirements phrased in the imperative as part of algorithms (such as "strip any leading space characters" or "return false and abort these steps") are to be interpreted with the meaning of the key word ("must", "should", "may", etc) used in introducing the algorithm.

Conformance requirements phrased as algorithms or specific steps can be implemented in any manner, so long as the end result is equivalent. In particular, the algorithms defined in this specification are intended to be easy to understand and are not intended to be performant. Implementers are encouraged to optimize.

Index

Terms defined by this specification

Terms defined by reference

References

Normative References

[FETCH]
Anne van Kesteren. Fetch Standard. Living Standard. URL: https://fetch.spec.whatwg.org/
[HTML]
Anne van Kesteren; et al. HTML Standard. Living Standard. URL: https://html.spec.whatwg.org/multipage/
[INFRA]
Anne van Kesteren; Domenic Denicola. Infra Standard. Living Standard. URL: https://infra.spec.whatwg.org/
[RFC2119]
S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Best Current Practice. URL: https://tools.ietf.org/html/rfc2119
[URL]
Anne van Kesteren. URL Standard. Living Standard. URL: https://url.spec.whatwg.org/
[WebIDL]
Boris Zbarsky. Web IDL. 15 December 2016. ED. URL: https://heycam.github.io/webidl/

IDL Index

partial interface HTMLAnchorElement {
    [CEReactions, Reflect] attribute DOMString conversiondestination;
    [CEReactions, Reflect] attribute DOMString impressiondata;
    [CEReactions, Reflect] attribute DOMString reportingorigin;
    [CEReactions, Reflect] attribute unsigned long long impressionexpiry;
};

Issues Index

Patch into fetch for cancelling requests redirected to the .well-known conversion domain.
Need monkey patches passing impression data in navigation, and a mechanism for validating the resulting document matches the conversiondestination.
Need to spec how to store the impression.
Formalize how to parse the query similar to URLSearchParams.
Need to spec how to store the conversion.