diff --git a/index.html b/index.html index fe85908..cdb158c 100644 --- a/index.html +++ b/index.html @@ -5,10 +5,10 @@ Topics API - + - + - - +

Topics API

-

Draft Community Group Report,

+

Draft Community Group Report,

More details about this document
@@ -719,27 +719,28 @@

Table of Contents

  • 6 Determine topics calculation input data
  • 7 Collect page topics calculation input data
  • 8 Collect topics caller origin -
  • 9 Periodically calculate user topics -
  • 10 Epochs for caller -
  • 11 Get the number of distinct versions in epochs -
  • 12 Topics for caller -
  • 13 The JavaScript API +
  • 9 Derive top 5 topics +
  • 10 Periodically calculate user topics +
  • 11 Epochs for caller +
  • 12 Get the number of distinct versions in epochs +
  • 13 Topics for caller +
  • 14 The JavaScript API
  • - 14 fetch() and iframe integration + 15 fetch() and iframe integration
      -
    1. 14.1 send browsing topics header boolean associated with Request -
    2. 14.2 browsingtopics content attribute for HTMLIframeElement -
    3. 14.3 browsingTopics attribute in RequestInit -
    4. 14.4 Modification to request constructor steps -
    5. 14.5 Modification to "create navigation params by fetching" steps -
    6. 14.6 The `Sec-Browsing-Topics` HTTP request header -
    7. 14.7 Modification to HTTP-network-or-cache fetch algorithm -
    8. 14.8 Append or modify a request Sec-Browsing-Topics header -
    9. 14.9 The `Observe-Browsing-Topics` HTTP response header -
    10. 14.10 Modification to HTTP fetch steps +
    11. 15.1 send browsing topics header boolean associated with Request +
    12. 15.2 browsingtopics content attribute for HTMLIframeElement +
    13. 15.3 browsingTopics attribute in RequestInit +
    14. 15.4 Modification to request constructor steps +
    15. 15.5 Modification to "create navigation params by fetching" steps +
    16. 15.6 The `Sec-Browsing-Topics` HTTP request header +
    17. 15.7 Modification to HTTP-network-or-cache fetch algorithm +
    18. 15.8 Append or modify a request Sec-Browsing-Topics header +
    19. 15.9 The `Observe-Browsing-Topics` HTTP response header +
    20. 15.10 Modification to HTTP fetch steps
    -
  • 15 Permissions policy integration -
  • 16 Privacy considerations +
  • 16 Permissions policy integration +
  • 17 Privacy considerations
  • Conformance
      @@ -939,7 +940,50 @@

      9. Periodically calculate user topics

      +

      9. Derive top 5 topics

      +

      Given a list of topics history entries historyEntriesForUserTopics, the browser should provide an algorithm to derive top 5 topics, that are believed to be valuable for the Topics callers. The algorithm should return a list of 5 topic ids.

      +
      + Chrome’s initial release scores topics by the frequency of page loads with that topic. +
      + +
      +

      Given a list of topics history entries historyEntriesForUserTopics:

      +
        +
      1. +

        Let topicsCount be an empty map.

        +
      2. +

        For each topics history entry historyEntry in historyEntriesForUserTopics:

        +
          +
        1. +

          Let topicIds be the result of classifying historyEntry’s topics calculation input data.

          +
        2. +

          For each topicId in topicIds:

          +
            +
          1. +

            If topicsCount[topicId] does not exist:

            +
              +
            1. +

              Initialize topicsCount[topicId] to 0.

              +
            +
          2. +

            Increment topicsCount[topicId] by 1.

            +
          +
        +
      3. +

        Let top5Topics be a list containing the top up to 5 topicIds in topicsCount’s keys, where the topicIds with more count are retrieved first.

        +
      4. +

        If top5Topics has less than 5 entries:

        +
          +
        1. +

          Pad top5Topics with random topic ids from user agent’s taxonomy, until top5Topics has 5 entries.

          +
        +
      5. +

        Return top5Topics.

        +
      +
      +
      +
      +

      10. Periodically calculate user topics

      At the start of a browser session, run the schedule user topics calculation algorithm.

      This roughly schedules topic calculation every 7 days, unless the browser is inactive at the scheduled time(s), in which case a topic calculation will occur as soon as the browser restarts.
      @@ -982,7 +1026,7 @@

      duration from the Unix epoch to moment.

    1. -

      If either user agent’s model or taxonomy isn’t available:

      +

      If either user agent’s model or taxonomy isn’t available:

      1. Let epoch be an epoch struct with default initial field values.

        @@ -998,7 +1042,7 @@

        duration of 21 days).

      2. -

        For each topics history entry topicsHistoryEntry in user agent’s topics history storage:

        +

        For each topics history entry topicsHistoryEntry in user agent’s topics history storage:

        1. Let visitTime be topicsHistoryEntry’s time.

        2. If visitTime is before topicsCallerDataStartTime, then continue.

        3. -

          Classify topicsHistoryEntry’s topics calculation input data into topicIds.

          +

          Let topicIds be the result of classifying topicsHistoryEntry’s topics calculation input data.

          +
        4. +

          If visitTime is greater than userTopicsDataStartTime:

          +
            +
          1. +

            Append topicsHistoryEntry to historyEntriesForUserTopics.

            +

        5. For each topicId in topicIds:

            @@ -1021,38 +1071,20 @@

            list.

            -

          -
        6. -

          If topicsCount[topicId] does not exist:

          -
            -
          1. -

            Initialize topicsCount[topicId] to 0.

            +

            Initialize topicsCallers[topicId] to be an empty list.

        7. For each callerOrigin in topicsHistoryEntry’s topics caller origins:

          1. -

            Append callerOrigin to topicsCallers[topicId].

            -
          -
        8. -

          If visitTime is greater than userTopicsDataStartTime:

          -
            -
          1. -

            Increment topicsCount[topicId] by 1.

            +

            Append callerOrigin to topicsCallers[topicId].

    2. -

      Let top5Topics be a list containing the top up to 5 topicIds in topicsCount’s keys set, where the topicIds with more count are retrieved first.

      -
    3. -

      If top5Topics has less than 5 entries:

      -
        -
      1. -

        Pad top5Topics with random topic ids from user agent’s taxonomy, until top5Topics has 5 entries.

        -
      +

      Let top5Topics be the result of running derive top 5 topics algorithm, given historyEntriesForUserTopics.

    4. -

      Let top5TopicsWithCallerOrigins be an empty list.

      +

      Let top5TopicsWithCallerOrigins be an empty list.

    5. For each topTopicId in top5Topics:

        @@ -1079,7 +1111,7 @@

        Append topicWithCallerOrigins to top5TopicsWithCallerOrigins.

        +

        Append topicWithCallerOrigins to top5TopicsWithCallerOrigins.

    6. Let epoch be an epoch struct with default initial field values.

      @@ -1096,21 +1128,21 @@

      time to fromUnixEpochTime.

    7. -

      Append epoch to user agent’s user topics state's epochs.

      +

      Append epoch to user agent’s user topics state's epochs.

    8. If user agent’s user topics state's epochs has more than 4 entries, remove the oldest epoch.

    9. Schedule this calculate user topics algorithm to run at Unix epoch + fromUnixEpochTime + (a duration of 7 days).

    • -

    10. Epochs for caller

    +

    11. Epochs for caller

    To calculate the epochs for caller, given a topics caller context callerContext, perform the following steps. They return a list of epoch.

    1. Let epochs be user agent’s user topics state's epochs.

    2. -

      If epochs is empty, then return an empty list.

      +

      If epochs is empty, then return an empty list.

    3. Let numEpochs be epochs’s size.

    4. @@ -1126,7 +1158,7 @@

      Let timestamp be callerContext’s timestamp.

    5. -

      Let result be an empty list.

      +

      Let result be an empty list.

    6. Let startEpochIndex be -1.

    7. @@ -1143,7 +1175,7 @@

      Else:

      1. -

        Set startEpochIndex to max(numEpochs − 1, 0).

        +

        Set startEpochIndex to max(numEpochs − 3, 0).

      2. Set endEpochIndex to numEpochs − 1.

      @@ -1151,12 +1183,12 @@

      If endEpochIndex ≥ 0:

      1. -

        Let i bestartEpochIndex.

        +

        Let i be startEpochIndex.

      2. While i ≤ endEpochIndex:

        1. -

          Append epochs[i] to result.

          +

          Append epochs[i] to result.

        2. Set i to i + 1.

        @@ -1166,7 +1198,7 @@

    This roughly returns 3 recently calculated epochs, either counting back from the last epoch, or from the second to the last epoch. The decision depends on whether some fixed duration (between 0 and 2 days, sticky to a user agent & site) has passed since the last epoch was calculated. This essentially adds a per-site fixed delay to the epoch switch time, to make it harder to correlate the same user across sites via the time that topics are changed. The HMAC helps to compute the per-site delay on the fly, without needing to store extra data for each site.
    -

    11. Get the number of distinct versions in epochs

    +

    12. Get the number of distinct versions in epochs

    To get the number of distinct versions in epochs, given a topics caller context callerContext, perform the following steps. They return an integer.
      @@ -1186,14 +1218,14 @@

      size.

    -

    12. Topics for caller

    +

    13. Topics for caller

    To calculate the topics for caller, given a topics caller context callerContext, perform the following steps. They return a list of BrowsingTopics.

    1. Let epochs be the result of running the calculate the epochs for caller algorithm given callerContext as input.

    2. -

      Let result be an empty list.

      +

      Let result be an empty list.

    3. For each epoch in epochs:

        @@ -1265,7 +1297,7 @@

        This roughly selects one random topic from each of the previous epochs (to limit cross-site reidentification capabilities), and only returns those that were observed by the caller (so that this provides roughly only a subset of the capabilities of third-party cookies). For each epoch, there is a 5% chance to return a random topic from the full taxonomy, rather than returning the real top topic, so as to provide some amount of plausible deniability. This random topic will only be returned if the caller would have received the real top topic (i.e. observed by the caller). This makes it non-trivial to detect which topics are the random topics (see github issue). All the randomnesses involved in this process are sticky to the user agent, epoch, and site. The HMAC helps to compute the random sticky values on the fly, without needing to store extra data for each epoch and site.

    -

    13. The JavaScript API

    +

    14. The JavaScript API

    The Topics API lives under the Document interface, and is only available if the document is in secure context.

    dictionary BrowsingTopicsOptions {
   boolean skipObservation = false;
@@ -1342,49 +1374,49 @@
    -

    14. fetch() and iframe integration

    +

    15. fetch() and iframe integration

    Topics can be sent in the HTTP header for fetch() requests and for iframe navigation requests. The response header for a topics related request can specify whether the caller should to be recorded. -

    14.1. send browsing topics header boolean associated with Request

    +

    15.1. send browsing topics header boolean associated with Request

    A request has an associated send browsing topics header boolean. Unless stated otherwise it is false.

    TODO: make the modification directly to the fetch spec.

    -

    14.2. browsingtopics content attribute for HTMLIframeElement

    +

    15.2. browsingtopics content attribute for HTMLIframeElement

    The iframe element contains a browsingtopics content attribute. The IDL attribute browsingTopics reflects the browsingtopics content attribute. 
    partial interface HTMLIFrameElement {
   [CEReactions] attribute boolean browsingTopics;
 };

    TODO: make the modification directly to the html spec.

    -

    14.3. browsingTopics attribute in RequestInit

    +

    15.3. browsingTopics attribute in RequestInit

    The RequestInit dictionary contains a browsingTopics attribute: 
    partial dictionary RequestInit {
   boolean browsingTopics;
 };

    TODO: make the modification directly to the fetch spec.

    -

    14.4. Modification to request constructor steps

    +

    15.4. Modification to request constructor steps

    The following step will be added to the new Request(input, init) constructor steps, before step "Set this’s request to request":

    1. If init["browsingTopics"] exists, then set request’s send browsing topics header boolean to it.

    TODO: make the modification directly to the fetch spec.

    -

    14.5. Modification to "create navigation params by fetching" steps

    +

    15.5. Modification to "create navigation params by fetching" steps

    The following step will be added to the create navigation params by fetching steps, after step "Let request be a new request, with ...":

    1. If navigable’s container is an iframe element, and if it has a browsingtopics content attribute, then set request’s send browsing topics header boolean to true.

    TODO: make the modification directly to the html spec.

    -

    14.6. The `Sec-Browsing-Topics` HTTP request header

    +

    15.6. The `Sec-Browsing-Topics` HTTP request header

    This specification defines a `Sec-Browsing-Topics` HTTP request header. It is used to send the topics.

    -

    14.7. Modification to HTTP-network-or-cache fetch algorithm

    +

    15.7. Modification to HTTP-network-or-cache fetch algorithm

    The following step will be added to the HTTP-network-or-cache fetch algorithm, before step "Modify httpRequest’s header list per HTTP. ...":

    1. Append or modify a request `Sec-Browsing-Topics` header for httpRequest.

    TODO: make the modification directly to the fetch spec.

    -

    14.8. Append or modify a request Sec-Browsing-Topics header

    +

    15.8. Append or modify a request Sec-Browsing-Topics header

    To append or modify a request `Sec-Browsing-Topics` header, given a request request, run these steps:
      @@ -1467,7 +1499,7 @@

      topic id (e.g. for Chrome’s initial taxonomy, topicMaxLength is 3, as the topic id has maximum 3 digits).

      +

      Let topicMaxLength be number of base-10 digits in the maximum topic id (e.g. for Chrome’s initial taxonomy, topicMaxLength is 3, as the topic id has maximum 3 digits).

    1. Let versionMaxLength be the length of the current maximum version string length.

    2. @@ -1536,12 +1568,12 @@

      Three returned topics, and underlying epochs have three different versions:

      (100);v=chrome.1:1:20, (200);v=chrome.1:1:40, (300);v=chrome.1:1:60, ();p=P

    -

    Why adding paddings: servers typically have a GET request size limit e.g. 8KB, and will return an error when the limit is reached. An attacker can rely this to learn the number of topics for a different origin, and/or a small amount of information about the topics themselves (e.g whether the topic ids are < 10, < 100, etc.)

    +

    Why adding paddings: servers typically have a GET request size limit e.g. 8KB, and will return an error when the limit is reached. An attacker can rely this to learn the number of topics for a different origin, and/or a small amount of information about the topics themselves (e.g whether the topic ids are < 10, < 100, etc.)

    The various lengths being returned (that depends on the number of distinct versions) could leak which epochs the user had disabled topics or didn’t use the browser, if it coincided with the version change. But this leak is minor. The most common cases (i.e. returning same version topics, or no topics) will have the same length.

    In Chrome’s experimentation phase, it will additionally require a valid Origin Trial token to exist in initiatorWindow’s associated document for the request to be eligible for topics.
    -

    14.9. The `Observe-Browsing-Topics` HTTP response header

    +

    15.9. The `Observe-Browsing-Topics` HTTP response header

    The `Observe-Browsing-Topics` HTTP response header can be used to record a caller’s topics observation.

    To handle topics response, given a response response and a request request: @@ -1566,7 +1598,7 @@

    14.10. Modification to HTTP fetch steps

    +

    15.10. Modification to HTTP fetch steps

    The following step will be added to the HTTP fetch steps, before checking the redirect status (i.e. "If actualResponse’s status is a redirect status, ..."):
    1. @@ -1575,14 +1607,14 @@

      TODO: make the modification directly to the fetch spec.

      -

      15. Permissions policy integration

      +

      16. Permissions policy integration

      This specification defines a policy-controlled feature identified by the string "browsing-topics". Its default allowlist is *.

      For backward compatibility, this specification also defines a policy-controlled feature identified by the string "interest-cohort". Its default allowlist is *.

      -

      16. Privacy considerations

      +

      17. Privacy considerations

      The Topics API attempts to provide just enough relevant interest information for advertisers to be able to personalize their ads for the user while maintaining user privacy. Some privacy safeguards include: usage in secure contexts only, topic limitation to a human curated taxonomy, different topics given to different sites in the same epoch to prevent cross-site reidentification, noised topics, a limited number of topics provided per epoch, user opt outs, site opt outs, and a suggestion that user agents provide UX to give users choice in which Topics are returned.

      @@ -1617,23 +1649,23 @@

      Index

      Terms defined by this specification

        -
      • append or modify a request `Sec-Browsing-Topics` header, in § 14.8 +
      • append or modify a request `Sec-Browsing-Topics` header, in § 15.8
      • BrowsingTopic, in § 4 -
      • browsing-topics, in § 15 +
      • browsing-topics, in § 16
      • browsingTopics -
      • browsingtopics, in § 14.2 -
      • browsingTopics(), in § 13 -
      • browsingTopics(options), in § 13 -
      • BrowsingTopicsOptions, in § 13 -
      • browsing topics task source, in § 13 -
      • calculate the epochs for caller, in § 10 -
      • calculate the topics for caller, in § 12 -
      • calculate user topics, in § 9 +
      • browsingtopics, in § 15.2 +
      • browsingTopics(), in § 14 +
      • browsingTopics(options), in § 14 +
      • BrowsingTopicsOptions, in § 14 +
      • browsing topics task source, in § 14 +
      • calculate the epochs for caller, in § 11 +
      • calculate the topics for caller, in § 13 +
      • calculate user topics, in § 10
      • caller origin, in § 2
      • caller origins, in § 2
      • classify, in § 2 @@ -1648,6 +1680,7 @@

        config version, in § 2
      • configVersion, in § 4 +
      • derive top 5 topics, in § 9
      • document id
      • modelVersion, in § 4 -
      • Observe-Browsing-Topics, in § 14.9 -
      • schedule user topics calculation, in § 9 -
      • Sec-Browsing-Topics, in § 14.6 -
      • send browsing topics header boolean, in § 14.1 -
      • skipObservation, in § 13 +
      • Observe-Browsing-Topics, in § 15.9 +
      • schedule user topics calculation, in § 10 +
      • Sec-Browsing-Topics, in § 15.6 +
      • send browsing topics header boolean, in § 15.1 +
      • skipObservation, in § 14
      • taxonomy
          @@ -1811,6 +1844,7 @@

          contain
        • exist
        • implementation-defined +
        • keys
        • list
        • ordered map
        • size @@ -2210,156 +2244,158 @@

          I