Attribution Reporting API 开发者指南

开发者预览版 Beta 版

在阅读 Privacy Sandbox on Android 文档时，请使用开发者预览版或 Beta 版按钮选择您所使用的程序版本，因为说明可能会有所不同。

---

Attribution Reporting API 旨在通过消除对跨方用户标识符的依赖来更好地保护用户隐私，并支持跨应用进行归因和转化衡量的关键用例。本开发者指南将介绍如何配置和测试 Attribution Reporting API，通过调用为广告点击、观看和转化事件注册相关触发器和来源的方法来注册广告点击、观看和转化。

本指南将指导您设置服务器端点并构建调用这些服务的客户端应用。如需详细了解 Attribution Reporting API 的整体设计，请参阅设计方案。

关键术语

• “归因来源”是指点击或观看。
• 触发器是可归因于转化的事件。
• 报告包含有关触发器和相应归因来源的数据。这些报告是响应触发器事件而发送的。Attribution Reporting API 支持事件级报告和可汇总报告。

准备工作

为了使用 Attribution Reporting API，请完成以下几部分中列出的服务器端任务和客户端任务。

设置 Attribution Reporting API 端点

Attribution Reporting API 需要一组可通过测试设备或模拟器进行访问的端点。请为以下每个服务器端任务创建一个端点：

• 注册归因来源（观看或点击）
• 注册触发器（转化）
• 接受事件级报告
• 接受可汇总报告

您可以通过多种方法来设置所需端点：

• 最快上手的方法是，将示例代码库中的 OpenAPI v3 服务定义部署到模拟或微服务平台。您可以使用 Postman、Prism 或接受此格式的任何其他模拟服务器平台。部署每个端点，并跟踪在您的应用中使用的 URI。如需验证报告发送，请参阅之前对模拟或无服务器平台发出的调用。
• 使用基于 Spring Boot 的 Kotlin 示例运行您自己的独立服务器。在云服务提供商的基础架构或内部基础架构上部署此服务器。
• 使用服务定义作为示例，将端点集成到您的现有系统中。

注意：如需详细了解如何注册 URI，请参阅注册 Privacy Sandbox 账号。以下几部分中提供了一些端点名称示例。

接受来源注册

此端点应可通过如下所示的 URI 寻址：

https://adtech.example/attribution_source

当客户端应用注册归因来源时，会提供此服务器端点的 URI。然后，Attribution Reporting API 会发出请求并在其中包含以下标头之一：

• 对于点击事件：

  Attribution-Reporting-Source-Info: navigation
  

• 对于观看事件：

  Attribution-Reporting-Source-Info: event
  

配置服务器端点，让其使用以下内容进行响应：

// Metadata associated with attribution source.
Attribution-Reporting-Register-Source: {
  "destination": "[app package name]",
  "web_destination": "[eTLD+1]",
  "source_event_id": "[64 bit unsigned integer]",
  "expiry": "[64 bit signed integer]",
  "event_report_window": "[64-bit signed integer]",
  "aggregatable_report_window": "[64-bit signed integer]",
  "priority": "[64 bit signed integer]",
  "filter_data": {
    "[key name 1]": ["key1 value 1", "key1 value 2"],
    "[key name 2]": ["key2 value 1", "key2 value 2"],
    // Note: "source_type" key will be automatically generated as
    // one of {"navigation", "event"}.
  },
  // Attribution source metadata specifying histogram contributions in aggregate
  // report.
  "aggregation_keys": {
    "[key1 name]": "[key1 value]",
    "[key2 name]": "[key2 value]",
  },

    "debug_key": "[64-bit unsigned integer]",
    "debug_reporting": [boolean]
}
// Specify additional ad tech URLs to register this source with.
Attribution-Reporting-Redirect: <Ad Tech Partner URI 1>
Attribution-Reporting-Redirect: <Ad Tech Partner URI 2>

以下是一个添加了示例值的示例：

Attribution-Reporting-Register-Source: {
  "destination": "android-app://com.example.advertiser",
  "source_event_id": "234",
  "expiry": "259200",
  "event_report_window": "172800",
  "aggregatable_report_window": "172800",
  "priority": "5",
  "filter_data": {
    "product_id": ["1234"]
  },
  "aggregation_keys": {
  // Generates a "0x159" key piece named (low order bits of the key) for the key
  // named "campaignCounts".
  // User saw an ad from campaign 345 (out of 511).
    "campaignCounts": "0x159",

  // Generates a "0x5" key piece (low order bits of the key) for the key named
  // "geoValue".
  // Source-side geo region = 5 (US), out of a possible ~100 regions.
    "geoValue": "0x5",
  },
  // Opts in to receiving verbose debug reports
  "debug_reporting": true
}

Attribution-Reporting-Redirect:
https://adtechpartner1.example?their_ad_click_id=567
Attribution-Reporting-Redirect:
https://adtechpartner2.example?their_ad_click_id=890

注意：为了获得一致的结果，对于预期采用数字值的属性，例如 source_event_id 或 expiry，应以字符串值并用英文引号括起的形式发送，如示例中所示。

如果 Attribution-Reporting-Redirects 包含广告技术合作伙伴的 URI，Attribution Reporting API 就会向每个 URI 发出类似的请求。每个广告技术合作伙伴都必须配置一台服务器，让其使用以下标头进行响应：

Attribution-Reporting-Register-Source: {
  "destination": "[app package name]",
  "web_destination": "[eTLD+1]",
  "source_event_id": "[64 bit unsigned integer]",
  "expiry": "[64 bit signed integer]",
  "event_report_window": "[64-bit signed integer]",
  "aggregatable_report_window": "[64-bit signed integer]",
  "priority": "[64 bit signed integer]",
  "filter_data": {
    "[key name 1]": ["key1 value 1", "key1 value 2"],
    "[key name 2]": ["key2 value 1", "key2 value 2"],
    // Note: "source_type" key will be automatically generated as
    // one of {"navigation", "event"}.
  },
  "aggregation_keys": {
    "[key1 name]": "[key1 value]",
    "[key2 name]": "[key2 value]",
  }
}
// The Attribution-Reporting-Redirect header is ignored for ad tech partners.

注意 ：只有发起 API 调用的广告技术平台才能指定合作伙伴 在 Attribution-Reporting-Redirect 中。

接受转化触发器注册

此端点应可通过如下所示的 URI 寻址：

https://adtech.example/attribution_trigger

当客户端应用注册触发器事件时，会提供此服务器端点的 URI。然后，Attribution Reporting API 会发出请求并在其中包含以下标头之一：

配置服务器端点，让其使用以下内容进行响应：

// Metadata associated with trigger.
Attribution-Reporting-Register-Trigger: {
  "event_trigger_data": [{
    // "trigger_data returned" in event reports is truncated to
    // the last 1 or 3 bits, based on conversion type.
    "trigger_data": "[unsigned 64-bit integer]",
    "priority": "[signed 64-bit integer]",
    "deduplication_key": "[signed 64-bit integer]",
    // "filter" and "not_filters" are optional fields which allow configuring
    // event trigger data based on source's filter_data. They consist of a
    // filter set, which is a list of filter maps. An event_trigger_data object
    // is ignored if none of the filter maps in the set match the source's
    // filter data.
    // Note: "source_type" can be used as a key in a filter map to filter based
    // on the source's "navigation" or "event" type. The first
    // Event-Trigger that matches (based on the filters/not_filters) will be
    // used for report generation. If none of the event-triggers match, no
    // event report will be generated.
    "filters": [{
      "[key name 1]": ["key1 value 1", "key1 value 2"],
      // If a key is missing from filters or source's filter_data, it won't be
      // used during matching.
      "[key name 2]": ["key2 value 1", "key2 value 2"],
    }],
    "not_filters":  [{
      "[key name 1]": ["key1 value 1", "key1 value 2"],
      // If a key is missing from not_filters or source's filter_data, it won't
      // be used during matching.
      "[key name 2]": ["key2 value 1", "key2 value 2"],
    }]
  }],
  // Specify a list of dictionaries that generates aggregation keys.
  "aggregatable_trigger_data": [
    // Each dictionary entry independently adds pieces to multiple source keys.
    {
      "key_piece": "[key piece value]",
      "source_keys": ["[key name the key piece value applies to]",
      ["list of IDs in source to match. Non-matching IDs are ignored"]]
      // filters/not_filters are optional fields similar to event trigger data
      // filter fields.
      "filters": [{
        "[key name 1]": ["key1 value 1", "key1 value 2"]
      }],
      "not_filters":  [{
          "[key name 1]": ["key1 value 1", "key1 value 2"],
          "[key name 2]": ["key2 value 1", "key2 value 2"],
      }]
    },
    ..
  ],
  // Specify an amount of an abstract value which can be integers in [1, 2^16]
  // to contribute to each key that is attached to aggregation keys in the
  // order they are generated.
  "aggregatable_values": [
     // Each source event can contribute a maximum of L1 = 2^16 to the
     // aggregate histogram.
    {
     "[key_name]": [value]
    },
    ..
  ],
  aggregatable_deduplication_keys: [{
  deduplication_key": [unsigned 64-bit integer],
    "filters": {
        "category": [filter_1, …, filter_H]
      },
    "not_filters": {
        "category": [filter_1, …, filter_J]
      }
  },
  ...
  {
  "deduplication_key": [unsigned 64-bit integer],
    "filters": {
        "category": [filter_1, …, filter_D]
      },
    "not_filters": {
        "category": [filter_1, …, filter_J]
      }
    }
  ]

  "debug_key": "[64-bit unsigned integer]",
  "debug_reporting": [boolean]

}
// Specify additional ad tech URLs to register this trigger with.
// Repeated Header field "Attribution-Reporting-Redirect"
Attribution-Reporting-Redirect: <Ad Tech Partner URI 1>
Attribution-Reporting-Redirect: <Ad Tech Partner URI 2>

以下是一个添加了示例值的示例：

Attribution-Reporting-Register-Trigger: {
  "event_trigger_data": [{
    "trigger_data": "1122", // Returns 010 for CTCs and 0 for VTCs in reports.
    "priority": "3",
    "deduplication_key": "3344"
    "filters": [{ // Filter strings can not exceed 25 characters
      "product_id": ["1234"],
      "source_type": ["event"]
    }]
  },
  {
    "trigger_data": "4", // Returns 100 for CTCs and 0 for VTCs in reports.
    "priority": "3",
    "deduplication_key": "3344"
    "filters": [{ // Filter strings can not exceed 25 characters
      "product_id": ["1234"],
      "source_type": ["navigation"]
    }]
  }],
  "aggregatable_trigger_data": [
    // Each dictionary independently adds pieces to multiple source keys.
    {
      // Conversion type purchase = 2 at a 9-bit offset, i.e. 2 << 9.
      // A 9-bit offset is needed because there are 511 possible campaigns,
      // which takes up 9 bits in the resulting key.
      "key_piece": "0x400",// Conversion type purchase = 2
      // Apply this key piece to:
      "source_keys": ["campaignCounts"]
       // Filter strings can not exceed 25 characters
    },
    {
      // Purchase category shirts = 21 at a 7-bit offset, i.e. 21 << 7.
      // A 7-bit offset is needed because there are ~100 regions for the geo
      // key, which takes up 7 bits of space in the resulting key.
      "key_piece": "0xA80",
      // Apply this key piece to:
      "source_keys": ["geoValue", "nonMatchingIdsAreIgnored"]
      // source_key values must not exceed the limit of 25 characters
    }
  ],
  "aggregatable_values":
    {
      // Privacy budget for each key is L1 / 2 = 2^15 (32768).
      // Conversion count was 1.
      // Scale the count to use the full budget allocated: 1 * 32768 = 32768.
      "campaignCounts": 32768,

      // Purchase price was $52.
      // Purchase values for the app range from $1 to $1,024 (integers only).
      // Scaling factor applied is 32768 / 1024 = 32.
      // For $52 purchase, scale the value by 32 ($52 * 32 = $1,664).
      "geoValue": 1664
    }
  ,
  // aggregatable_deduplication_keys is an optional field. Up to 50 "keys"
  // can be included in the aggregatable_deduplication_keys list. Filters, not
  // filters, and deduplication_key are optional fields. If deduplication_key
  // is omitted, it will be treated as a null value. See
  // https://wicg.github.io/attribution-reporting-api/#triggering-aggregatable-attribution
  aggregatable_deduplication_keys:
  [
    {
    deduplication_key": 3,
        "filters": {
          "category": [A]
        }
    },
    {
    "deduplication_key": 4,
        "filters": {
          "category": [C, D]
        },
        "not_filters": {
          "category": [F]
        }
    }
  ]
  // Opts into receiving verbose debug reports
  "debug_reporting": true
}
Attribution-Reporting-Redirect:https://adtechpartner.example?app_install=567

每个汇总键 ID 和过滤条件字符串的长度上限为 25 个字节。也就是说，汇总键 ID 和过滤字符串不应超过 25 个字符。在此示例中，campaignCounts 是 14 个字符，因此是一个有效的汇总键 ID；1234 是 4 个字符，因此是一个有效的过滤条件字符串。如果汇总键 ID 或过滤条件字符串超过 25 个字符，该触发器便会被忽略。

如果 Attribution-Reporting-Redirect 包含广告技术合作伙伴的 URI，Attribution Reporting API 就会向每个 URI 发出类似的请求。每个广告技术合作伙伴都必须配置一台服务器，让其使用以下标头进行响应：

// Metadata associated with trigger.
Attribution-Reporting-Register-Trigger: {
  "event_trigger_data": [{
    // "trigger_data" returned in event reports is truncated to
    // the last 1 or 3 bits, based on conversion type.
    "trigger_data": "[unsigned 64-bit integer]",
    "priority": "[signed 64-bit integer]",
    "deduplication_key": "[signed 64-bit integer]",
    // filter and not_filters are optional fields which allow configuring
    // different event trigger data based on source's filter_data. They
    // consist of a filter set, which is a list of filter maps. An
    // event_trigger_data object is ignored if none of the filter maps in the
    // set match the source's filter data. Note: "source_type" can be used as
    // a key in a filter map to filter based on the source's "navigation" or
    // "event" type. The first Event-Trigger that matches (based on the
    // filters/not_filters) will be used for report generation. If none of the
    // event-triggers match, no report will be generated.
    "filters": [{
      "[key name 1]": ["key1 value 1", "key1 value 2"],
      // If a key is missing from filters or source's filter_data, it will not be
      // used during matching.
      "[key name 2]": ["key2 value 1", "key2 value 2"],
    }],
    "not_filters":  [{
      "[key name 1]": ["key1 value 1", "key1 value 2"],
      // If a key is missing from not_filters or source's filter_data, it will not
      // be used during matching.
      "[key name 2]": ["key2 value 1", "key2 value 2"],
    }]
  }],
  "aggregatable_trigger_data": [
    // Each dictionary entry independently adds pieces to multiple source keys.
    {
      "key_piece": "[key piece value]",
      "source_keys": ["[key name the key piece value applies to]",
      ["list of IDs in source to match. Non-matching IDs are ignored"]],
      // filters/not_filters are optional fields similar to event trigger data
      // filter fields.
      "filters": [{
        "[key name 1]": ["key1 value 1", "key1 value 2"]
      }],
      "not_filters":  [{
          "[key name 1]": ["key1 value 1", "key1 value 2"],
          "[key name 2]": ["key2 value 1", "key2 value 2"],
      }]
    },
    ..
  ],
  // Specify an amount of an abstract value which can be integers in [1, 2^16] to
  // contribute to each key that is attached to aggregation keys in the order they
  // are generated.
  "aggregatable_values": [
    // Each source event can contribute a maximum of L1 = 2^16 to the aggregate
    // histogram.
    {
     "[key_name]": [value]
    }
  ]
}
// The Attribution-Reporting-Redirect header is ignored for ad tech partners.

注意：只有发起 API 调用的广告技术平台才能在 Attribution-Reporting-Redirect 中指定合作伙伴。

接受事件级报告

此端点应可通过 URI 寻址。如需详细了解如何注册 URI，请参阅注册 Privacy Sandbox 账号。（系统会根据用于接受来源注册和触发器注册的服务器来源推断 URI。）使用接受来源注册和接受触发器注册的端点的示例 URI，推断出来的此端点 URI 为：

https://adtech.example/.well-known/attribution-reporting/report-event-attribution

配置此服务器，让其接受使用以下格式的 JSON 请求：

{
  "attribution_destination": "android-app://com.advertiser.example",
  "source_event_id": "12345678",
  "trigger_data": "2",
  "report_id": "12324323",
  "source_type": "navigation",
  "randomized_trigger_rate": "0.02"
   [Optional] "source_debug_key": "[64-bit unsigned integer]",
   [Optional] "trigger_debug_key": "[64-bit unsigned integer]",
}

调试键可让您进一步了解归因报告；详细了解配置方式。

接受可汇总报告

此端点应可通过 URI 寻址。如需详细了解如何注册 URI，请参阅注册 Privacy Sandbox 账号。（系统会根据用于接受来源注册和触发器注册的服务器来源推断 URI。）使用接受来源注册和接受触发器注册的端点的示例 URI，推断出来的此端点 URI 为：

https://adtech.example/.well-known/attribution-reporting/report-aggregate-attribution

注意 ：加密的可汇总报告本身的设计宗旨并非供 技术平台而是用作汇总服务的输入，由汇总服务处理报告并生成摘要报告供广告技术平台使用。

对于可汇总报告，系统会同时填充已加密字段和未加密字段。已加密报告可以让您开始使用汇总服务进行测试，而未加密字段则可让您了解设置的键值对的数据构建方式。

配置此服务器，让其接受使用以下格式的 JSON 请求：

{
  // Info that the aggregation services also need encoded in JSON
  // for use with AEAD. Line breaks added for readability.
  "shared_info": "{
     \"api\":\"attribution-reporting\",
     \"attribution_destination\": \"android-app://com.advertiser.example.advertiser\",
     \"scheduled_report_time\":\"[timestamp in seconds]\",
     \"source_registration_time\": \"[timestamp in seconds]\",
     \"version\":\"[api version]\",
     \"report_id\":\"[UUID]\",
     \"reporting_origin\":\"https://reporter.example\" }",

  // In the current Developer Preview release, The "payload" and "key_id" fields
  // are not used because the platform does not yet encrypt aggregate reports.
  // Currently, the "debug_cleartext_payload" field holds unencrypted reports.
  "aggregation_service_payloads": [
    {
      "payload": "[base64 HPKE encrypted data readable only by the aggregation service]",
      "key_id": "[string identifying public key used to encrypt payload]",

      "debug_cleartext_payload": "[unencrypted payload]"
    },
  ],

  "source_debug_key": "[64 bit unsigned integer]",
  "trigger_debug_key": "[64 bit unsigned integer]"
}

调试键可让您进一步了解归因报告；详细了解配置方式。

设置 Android 客户端

客户端应用需要注册归因来源和触发器，并允许生成事件级报告和可汇总报告。如需准备 Android 客户端设备或模拟器以使用 Attribution Reporting API，请执行以下操作：

1. 为 Privacy Sandbox on Android 设置开发环境。
2. 将系统映像安装到受支持的设备上或设置支持 Privacy Sandbox on Android 的模拟器。

3. 通过运行以下 adb 命令启用对 Attribution Reporting API 的访问权限。（此 API 默认处于停用状态。）

   adb shell device_config put adservices ppapi_app_allow_list \"\*\"

4. 如果您是在本地测试 Attribution Reporting API（例如在您有权访问的设备上进行测试），可运行以下命令来停用注册功能：

   adb shell device_config put adservices disable_measurement_enrollment_check "true"

5. 在 Android 清单文件中添加 ACCESS_ADSERVICES_ATTRIBUTION 权限，并为应用创建广告服务配置，以便使用 Attribution Reporting API：

   <uses-permission android:name="android.permission.ACCESS_ADSERVICES_ATTRIBUTION" />
   

6. （可选）如果您打算接收调试报告，可在 Android 清单文件中添加 ACCESS_ADSERVICES_AD_ID 权限：

   <uses-permission android:name="android.permission.ACCESS_ADSERVICES_AD_ID" />
   

7. 在清单的 <application> 元素中引用广告服务配置：

   <property android:name="android.adservices.AD_SERVICES_CONFIG"
             android:resource="@xml/ad_services_config" />
   

8. 指定清单中引用的广告服务 XML 资源，例如 res/xml/ad_services_config.xml。详细了解广告服务权限和 SDK 访问权限控制。

   <ad-services-config>
       <attribution allowAllToAccess="true" />
   </ad-services-config>
   

注册广告事件

您的应用应在来源和转化发生时进行记录，以确保正确报告来源和转化。 MeasurementManager 类提供相关方法，可帮助您注册归因来源事件和转化触发器。

注册归因来源事件

有人观看或点击广告时，发布商应用会调用 registerSource() 来注册代码段中所示的归因来源。

Attribution Reporting API 支持以下类型的归因来源事件：

• 点击：通常在与 onClick() 类似的回调方法中注册。相应的触发器事件通常紧跟在点击事件之后发生。此类事件提供有关用户互动的详细信息，因此适合作为高优先级的归因来源。

• 观看：通常在与 onAdShown() 类似的回调方法中注册。相应的触发器事件可能会在观看事件发生几小时或几天后发生。

Kotlin

companion object {
    private val CALLBACK_EXECUTOR = Executors.newCachedThreadPool()
}

val measurementManager = context.getSystemService(MeasurementManager::class.java)
var exampleClickEvent: InputEvent? = null

// Use the URI of the server-side endpoint that accepts attribution source
// registration.
val attributionSourceUri: Uri =
  Uri.parse("https://adtech.example/attribution_source?AD_TECH_PROVIDED_METADATA")

val future = CompletableFuture<Void>()

adView.setOnTouchListener(_: View?, event: MotionEvent?)) ->
    exampleClickEvent = event
    true
}

// Register Click Event
measurementManager.registerSource(
        attributionSourceUri,
        exampleClickEvent,
        CALLBACK_EXECUTOR,
        future::complete)

// Register View Event
measurementManager.registerSource(
        attributionSourceUri,
        null,
        CALLBACK_EXECUTOR,
        future::complete)

Java

private static final Executor CALLBACK_EXECUTOR = Executors.newCachedThreadPool();
private InputEvent exampleClickEvent;

MeasurementManager measurementManager =
        context.getSystemService(MeasurementManager.class);

// Use the URI of the server-side endpoint that accepts attribution source
// registration.
Uri attributionSourceUri =
Uri.parse("https://adtech.example/attribution_source?AD_TECH_PROVIDED_METADATA");

CompletableFuture<Void> future = new CompletableFuture<>();

adView.setOnTouchListener(v, event)) -> {
    exampleClickEvent = event;
    return true;
}

// Register Click Event
measurementManager.registerSource(attributionSourceUri, exampleClickEvent,
        CALLBACK_EXECUTOR, future::complete);

// Register View Event
measurementManager.registerSource(attributionSourceUri, null,
        CALLBACK_EXECUTOR, future::complete);

注册后，API 会向位于 attributionSourceUri 所指定地址的服务端点发出 HTTP POST 请求。端点的响应包含 destination, source_event_id, expiry 和 source_priority 的值。

如果发起调用的广告技术平台希望共享来源注册信息，那么原始归因来源 URI 可以包含指向其他广告技术端点的重定向。如需详细了解适用于重定向的限制和规则，请参阅技术提案。

新增了对 registerSource 和 registerTrigger 的菊花链重定向的支持。除了注册标头之外，API 使用方现在还可以提供 HTTP 重定向作为服务器响应，其中包括 302 状态代码以及注明下一个所要访问网址的“Location”标头，以进行其他注册。

只有在第一次访问中提供的“destination”字段才会在整个菊花链中使用。访问次数的限制与“Attribution-Reporting-Redirect”标头相同。此重定向支持是对现有“Attribution-Reporting-Redirect”支持的补充，如果两者都存在，则优先使用“Attribution-Reporting-Redirect”。

注册转化触发器事件

如需注册转化触发器事件，请在您的应用中调用 registerTrigger()：

Kotlin

companion object {
    private val CALLBACK_EXECUTOR = Executors.newCachedThreadPool()
}

val measurementManager = context.getSystemService(MeasurementManager::class.java)

// Use the URI of the server-side endpoint that accepts trigger registration.
val attributionTriggerUri: Uri =
    Uri.parse("https://adtech.example/trigger?AD_TECH_PROVIDED_METADATA")

val future = CompletableFuture<Void>()

// Register trigger (conversion)
measurementManager.registerTrigger(
        attributionTriggerUri,
        CALLBACK_EXECUTOR,
        future::complete)

Java

private static final Executor CALLBACK_EXECUTOR = Executors.newCachedThreadPool();

MeasurementManager measurementManager =
        context.getSystemService(MeasurementManager.class);

// Use the URI of the server-side endpoint that accepts trigger registration.
Uri attributionTriggerUri =
        Uri.parse("https://adtech.example/trigger?AD_TECH_PROVIDED_METADATA");

CompletableFuture<Void> future = new CompletableFuture<>();

// Register trigger (conversion)
measurementManager.registerTrigger(
        attributionTriggerUri,
        CALLBACK_EXECUTOR,
        future::complete)

注册后，API 会向位于 attributionTriggerUri 指定地址的服务端点发出 HTTP POST 请求。端点的响应包含事件和汇总报告的值。

如果发起调用的广告技术平台允许共享触发器注册信息，那么该 URI 可以包含指向属于其他广告技术平台的 URI 的重定向。如需详细了解适用于重定向的限制和规则，请参阅技术方案。

注册跨应用和跨网站衡量

如果在从来源到触发器的用户历程中应用和浏览器二者都发挥了作用，那么注册广告事件的实现就略有不同。如果用户在应用中看到广告并被重定向到浏览器中完成转化，那么来源由应用注册，转化则由网络浏览器注册。同理，如果用户先在网络浏览器中看到广告，然后被定向到应用中完成转化，那么就由浏览器注册来源，由应用注册转化。

由于广告技术在网站和 Android 平台中的组织方式有所不同，因此我们添加了新的 API，用于注册浏览器上产生的来源和触发器。这些 API 与基于应用的相应 API 之间的主要区别在于，我们希望浏览器跟踪重定向，应用任何浏览器专用过滤器，并通过调用 registerWebSource() 或 registerWebTrigger() 将有效注册传递给平台。

以下代码段展示了将用户定向到应用之前，浏览器为注册归因来源而发出的 API 调用示例：

Kotlin

companion object {
    private val CALLBACK_EXECUTOR = Executors.newCachedThreadPool()
}

val measurementManager =
        context.getSystemService(MeasurementManager::class.java)
var exampleClickEvent: InputEvent? = null

// Use the URIs of the server-side endpoints that accept attribution source
// registration.
val sourceParam1 = WebSourceParams.Builder(Uri.parse(
        "https://adtech1.example/attribution_source?AD_TECH_PROVIDED_METADATA"))
// True, if debugging is allowed for the ad tech.
    .setDebugKeyAllowed(true)
    .build()

val sourceParam2 = WebSourceParams.Builder(Uri.parse(
        "https://adtech2.example/attribution_source?AD_TECH_PROVIDED_METADATA"))
    .setDebugKeyAllowed(false)
    .build()

val sourceParam3 = WebSourceParams.Builder(Uri.parse(
        "https://adtech3.example/attribution_source?AD_TECH_PROVIDED_METADATA"))
    .build()

val sourceParams = Arrays.asList(sourceParam1, sourceParam2, sourceParam3)
val publisherOrigin = Uri.parse("https://publisher.example")
val appDestination = Uri.parse("android-app://com.example.store")
val webDestination = Uri.parse("https://example.com")

val future = CompletableFuture<Void>()

adView.setOnTouchListener {_: View?, event: MotionEvent? ->
    exampleClickEvent = event
    true
}
val clickRegistrationRequest = WebSourceRegistrationRequest.Builder(
          sourceParams,
          publisherOrigin)
      .setAppDestination(appDestination)
      .setWebDestination(webDestination)
      .setInputEvent(event)
      .build()
val viewRegistrationRequest = WebSourceRegistrationRequest.Builder(
          sourceParams,
          publisherOrigin)
      .setAppDestination(appDestination)
      .setWebDestination(webDestination)
      .setInputEvent(null)
      .build()

// Register a web source for a click event.
measurementManager.registerWebSource(
        clickRegistrationRequest,
        CALLBACK_EXECUTOR,
        future::complete)

// Register a web source for a view event.
measurementManager.registerWebSource(
        viewRegistrationRequest,
        CALLBACK_EXECUTOR,
        future::complete)

Java

private static final Executor CALLBACK_EXECUTOR =
        Executors.newCachedThreadPool();
private InputEvent exampleClickEvent;

MeasurementManager measurementManager =
        context.getSystemService(MeasurementManager.class);

// Use the URIs of the server-side endpoints that accept attribution source
// registration.
WebSourceParams sourceParam1 = WebSourceParams.Builder(Uri.parse(
        "https://adtech1.example/attribution_source?AD_TECH_PROVIDED_METADATA"))
    // True, if debugging is allowed for the ad tech.
    .setDebugKeyAllowed(true)
    .build();

WebSourceParams sourceParam2 = WebSourceParams.Builder(Uri.parse(
        "https://adtech2.example/attribution_source?AD_TECH_PROVIDED_METADATA"))
    .setDebugKeyAllowed(false)
    .build();

WebSourceParams sourceParam3 = WebSourceParams.Builder(Uri.parse(
        "https://adtech3.example/attribution_source?AD_TECH_PROVIDED_METADATA"))
    .build();

List<WebSourceParams> sourceParams =
        Arrays.asList(sourceParam1, sourceParam2, sourceParam3);
Uri publisherOrigin = Uri.parse("https://publisher.example");
Uri appDestination = Uri.parse("android-app://com.example.store");
Uri webDestination = Uri.parse("https://example.com");

CompletableFuture<Void> future = new CompletableFuture<>();

adView.setOnTouchListener(v, event) -> {
    exampleClickEvent = event;
    return true;
}

WebSourceRegistrationRequest clickRegistrationRequest =
        new WebSourceRegistrationRequest.Builder(sourceParams, publisherOrigin)
    .setAppDestination(appDestination)
    .setWebDestination(webDestination)
    .setInputEvent(event)
    .build();
WebSourceRegistrationRequest viewRegistrationRequest =
        new WebSourceRegistrationRequest.Builder(sourceParams, publisherOrigin)
    .setAppDestination(appDestination)
    .setWebDestination(webDestination)
    .setInputEvent(null)
    .build();

// Register a web source for a click event.
measurementManager.registerWebSource(clickRegistrationRequest,
        CALLBACK_EXECUTOR, future::complete);

// Register a web source for a view event.
measurementManager.registerWebSource(viewRegistrationRequest,
        CALLBACK_EXECUTOR, future::complete);

以下代码段展示了用户从应用被定向到浏览器之后，浏览器为注册转化而发出的 API 调用示例：

Kotlin

companion object {
    private val CALLBACK_EXECUTOR = Executors.newCachedThreadPool()
}

val measurementManager = context.getSystemService(MeasurementManager::class.java)

// Use the URIs of the server-side endpoints that accept trigger registration.
val triggerParam1 = WebTriggerParams.Builder(Uri.parse(
        "https://adtech1.example/trigger?AD_TECH_PROVIDED_METADATA"))
    // True, if debugging is allowed for the ad tech.
    .setDebugKeyAllowed(true)
    .build()

val triggerParam2 = WebTriggerParams.Builder(Uri.parse(
        "https://adtech2.example/trigger?AD_TECH_PROVIDED_METADATA"))
    .setDebugKeyAllowed(false)
    .build()

val triggerParams = Arrays.asList(triggerParam1, triggerParam2)
val advertiserOrigin = Uri.parse("https://advertiser.example")

val future = CompletableFuture<Void>()

val triggerRegistrationRequest = WebTriggerRegistrationRequest.Builder(
        triggerParams,
        advertiserOrigin)
    .build()

// Register the web trigger (conversion).
measurementManager.registerWebTrigger(
    triggerRegistrationRequest,
    CALLBACK_EXECUTOR,
    future::complete)

Java

private static final Executor CALLBACK_EXECUTOR =
        Executors.newCachedThreadPool();

MeasurementManager measurementManager =
        context.getSystemService(MeasurementManager.class);

// Use the URIs of the server-side endpoints that accept trigger registration.
WebTriggerParams triggerParam1 = WebTriggerParams.Builder(Uri.parse(
        "https://adtech1.example/trigger?AD_TECH_PROVIDED_METADATA"))
    // True, if debugging is allowed for the ad tech.
    .setDebugKeyAllowed(true)
    .build();

WebTriggerParams triggerParam2 = WebTriggerParams.Builder(Uri.parse(
        "https://adtech2.example/trigger?AD_TECH_PROVIDED_METADATA"))
    .setDebugKeyAllowed(false)
    .build();

List<WebTriggerParams> triggerParams =
        Arrays.asList(triggerParam1, triggerParam2);
Uri advertiserOrigin = Uri.parse("https://advertiser.example");

CompletableFuture<Void> future = new CompletableFuture<>();

WebTriggerRegistrationRequest triggerRegistrationRequest =
        new WebTriggerRegistrationRequest.Builder(
            triggerParams, advertiserOrigin)
    .build();

// Register the web trigger (conversion).
measurementManager.registerWebTrigger( triggerRegistrationRequest,
        CALLBACK_EXECUTOR, future::complete);

增加噪声来保护隐私

事件级报告包含目标位置、归因来源 ID 和触发器数据，会以原始（未加密）格式发送到报告来源。为了保护用户的隐私，报告中可以添加噪声，以提高识别具体用户的难度。系统会按照差分隐私框架，生成并发送添加了噪声的事件级报告。以下是不同场景下的默认噪声百分比值：

来源类型	来源目标位置值	每次注册来源时生成添加了噪声的报告的概率
观看	应用或网站	0.0000025
观看	应用和网站	0.0000042
点击	应用或网站	0.0024263
点击	应用和网站	0.0170218

在应用到网站的归因衡量中，来源可以同时促成在应用和网站目标位置的转化，而事件级报告可以指出触发器是出现在应用中还是网站上。为了补充这一额外的细节，在生成的添加了噪声的报告中，点击量最多增至大约 7 倍，浏览量最多增至大约 1.7 倍。

某些广告技术平台不需要事件级报告来指出触发器是出现在应用目标位置还是网站目标位置。广告技术平台可以使用 Attribution-Reporting-Register-Source 标头下的 coarse_event_report_destinations 字段来减少噪声。如果指定了 coarse_event_report_destinations 字段的来源赢得归因，生成的报告将同时包含应用和网站目标位置，而不会区分触发器的实际出现位置。

在下面的示例中，用户点击了一个广告，并通过 API 注册了该来源。随后，用户又分别在广告客户的应用和网站上完成转化。这两次转化都会注册为触发器，并归因于最初的点击。

基于点击的来源注册 HTTP 标头：

Attribution-Reporting-Register-Source: {
    "destination": "android-app://com.advertiser.example",
    "web_destination": "https://advertiser.com",
    "source_event_id": "234",
    "expiry": "60000",
    "priority": "5",
    // Ad tech opts out of receiving app-web destination distinction
    // in event report, avoids additional noise
    "coarse_event_report_destinations": "true"
}

从软件包名称为 com.advertiser.example 的应用中注册触发器：

Attribution-Reporting-Register-Trigger: {
    "event_trigger_data": [{
    "trigger_data": "1",
    "priority": "1"
    }],
}

通过浏览器从位于 eTLD+1 网域的 https://advertiser.com 网站中注册触发器：

Attribution-Reporting-Register-Trigger: {
    "event_trigger_data": [{
    "trigger_data": "2",
    "priority": "2"
    }],
}

生成相应的事件级报告。假设这两个触发器都归因于该来源，则会生成以下事件级报告：

  {
    "attribution_destination": ["android-app://com.advertiser.example,https://advertiser.com"],
    "scheduled_report_time": "800176400",
    "source_event_id": "53234",
    "trigger_data": "1",
    // Can be "event" if source were registered by user viewing the ad
    "source_type": "navigation",
    // Would be 0.0170218 without coarse_event_report_destinations as true in the source
    "randomized_trigger_rate": 0.0024263
  }

生成并发送报告

Attribution Reporting API 会将报告发送到您的服务器上接受事件级报告和可汇总报告的端点。

强制运行报告作业

注册归因来源事件或注册触发器事件后，系统会安排运行报告作业。默认情况下，此作业每 4 小时运行一次。出于测试目的，您可以强制运行报告作业或缩短两次作业之间的间隔时间。

强制运行归因作业：

adb shell cmd jobscheduler run -f com.google.android.adservices.api 5

强制运行事件级报告作业：

adb shell cmd jobscheduler run -f com.google.android.adservices.api 3

强制运行可汇总报告作业：

adb shell cmd jobscheduler run -f com.google.android.adservices.api 7

查看 logcat 中的输出，了解作业的运行时间。输出应如下所示：

JobScheduler: executeRunCommand(): com.google.android.adservices.api/0 5 s=false f=true

强制发送报告

即使强制运行报告作业，系统仍会按照安排的发送时间（从几小时到几天不等）发送报告。出于测试目的，您可以将设备的系统时间向前调到安排的延迟时间之后，以便立即开始发送报告。

在服务器上验证报告

报告发送后，请查看收到的报告、适用的服务器日志（如模拟服务器历史记录）或您的自定义系统，验证报告是否成功发送。

解码汇总报告

收到汇总报告时，debug_cleartext_payload 字段会包含汇总报告的未加密版本。虽然此版本的报告未加密，但仍需要解码。

下面是分两步解码 debug_cleartext_payload 字段内容的示例：第一步是使用 Base 64 解码，第二步是使用 CBOR 解码。

String base64DebugPayload  = "omRkYXRhgqJldmFsdWVEAAAGgGZidWNrZXRQAAAAAAAAAAAAAAAAAAAKhaJldmFsdWVEAACAAGZidWNrZXRQAAAAAAAAAAAAAAAAAAAFWWlvcGVyYXRpb25paGlzdG9ncmFt";
byte[] cborEncoded = Base64.getDecoder().decode(base64DebugPayload);

// CbodDecoder comes from this library https://github.com/c-rack/cbor-java
final List<DataItem> dataItems = new CborDecoder(new ByteArrayInputStream(cborEncoded)).decode();

// In here you can see the contents, but the value will be something like:
// Data items: [{ data: [{ value: co.nstant.in.cbor.model.ByteString@a8b5c07a,
//   bucket: co.nstant.in.cbor.model.ByteString@f812097d },
//   { value: co.nstant.in.cbor.model.ByteString@a8b5dfc0,
//   bucket: co.nstant.in.cbor.model.ByteString@f8120934 }], operation: histogram }]
Log.d("Data items : " + dataItems);

// In order to see the value for bucket and value, you can traverse the data
// and get their values, something like this:
final Map payload = (Map) dataItems.get(0);
final Array payloadArray = (Array) payload.get(new UnicodeString("data"));

payloadArray.getDataItems().forEach(i -> {
    BigInteger value = new BigInteger(((ByteString) ((Map)i).get(new UnicodeString("value"))).getBytes());
    BigInteger bucket = new BigInteger(((ByteString) ((Map)i).get(new UnicodeString("bucket"))).getBytes());
    Log.d("value : " + value + " ;bucket : " + bucket);
});

测试

为帮助您开始使用 Attribution Reporting API，您可以使用 GitHub 上的 MeasurementSampleApp 项目。该示例应用演示了归因来源注册和触发器注册。

对于服务器端点，请考虑使用以下参考资源或您的自定义解决方案：

• MeasurementAdTechServerSpec 包含 OpenAPI 服务定义，您可将这些定义部署到受支持的模拟或微服务平台。
• MeasurementAdTechServer 包含一个模拟服务器的参考实现，以用于 Google App Engine 的 Spring Boot 应用为基础。

前提条件

在可通过测试设备或模拟器进行访问的远程端点上部署模拟 API。为便于测试，请参阅 MeasurementAdTechServerSpec 和 MeasurementAdTechServer 示例项目。

需要测试的功能

• 进行归因来源和转化触发器注册。检查服务器端端点是否以正确格式进行响应。
• 执行报告作业。
• 在测试服务器的后端或控制台上验证报告是否成功发送。

即将发布的功能

灵活事件级配置

建议在启动实用性测试时使用事件级报告的默认配置，但不一定适合所有用例。Attribution Reporting API 将支持更灵活的可选配置，以便广告技术平台可以更好地控制其事件级报告的结构，并能够最大限度地利用数据。这种额外的灵活性将分两个阶段引入 Attribution Reporting API：

• 第 1 阶段：精简版灵活事件级配置；涵盖第 2 阶段的部分设置。
• 第 2 阶段：完整版灵活事件级配置。

第 1 阶段：精简版灵活事件级

我们将在 Attribution-Reporting-Register-Source 的 JSON 中添加以下两个可选参数：

• max_event_level_reports
• event_report_windows

{
  ...
  // Optional. This is a parameter that acts across all trigger types for the
  // lifetime of this source. It restricts the total number of event-level
  // reports that this source can generate. After this maximum is hit, the
  // source is no longer capable of producing any new data. The use of
  // priority in the trigger attribution algorithm in the case of multiple
  // attributable triggers remains unchanged. Defaults to 3 for navigation
  // sources and 1 for event sources
  "max_event_level_reports": <int>,

  // Optional. Represents a series of time windows, starting at 0. Reports
  // for this source will be delivered an hour after the end of each window.
  // Time is encoded as seconds after source registration. If
  // event_report_windows is omitted, will use the default windows. This
  // field is mutually exclusive with the existing `event_report_window` field.
  // // End time is exclusive.
  "event_report_windows": {
    "start_time": <int>,
    "end_times": [<int>, ...]
  }
}

注意：如果同时存在 event_report_window 和 event_report_windows，该来源会被忽略。来源中只能出现其中一项 注册。

自定义配置示例

如果开发者希望进行优化，以便在报告期早期接收报告，则可采用此示例配置。

{
  ...
  "max_event_level_reports": 2,
  "event_report_windows": {
    "end_times": [7200, 43200, 86400] // 2 hours, 12 hours, 1 day in seconds
  }
}

第 2 阶段：完整版灵活事件级

除了在第 1 阶段添加的参数之外，我们还将向 Attribution-Reporting-Register-Source 中的 JSON 添加一个额外的可选参数 trigger_specs。

{
  // A trigger spec is a set of matching criteria, along with a scheme to
  // generate bucketized output based on accumulated values across multiple
  // triggers within the specified event_report_window. There will be a limit on
  // the number of specs possible to define for a source.
  "trigger_specs": [{
    // This spec will only apply to registrations that set one of the given
    // trigger data values (non-negative integers) in the list.
    // trigger_data will still appear in the event-level report.
    "trigger_data": [<int>, ...]

    // Represents a series of time windows, starting at the source registration
    // time. Reports for this spec will be delivered an hour after the end of
    // each window. Time is encoded as seconds after source registration.
    // end_times must consist of strictly increasing positive integers.
    //
    // Note: specs with identical trigger_data cannot have overlapping windows;
    // this ensures that triggers match at most one spec. If
    // event_report_windows is omitted, will use the "event_report_window" or
    // "event_report_windows" field specified at the global level for the source
    // (or the default windows if none are specified). End time is exclusive.
    "event_report_windows": {
      "start_time": <int>,
      "end_times": [<int>, ...],
    }

    // Represents an operator that summarizes the triggers within a window
    // count: number of triggers attributed within a window
    // value_sum: sum of the value of triggers within a window
    // The summary is reported as an index into a bucketization scheme. Defaults
    // to "count"
    "summary_window_operator": <one of "count" or "value_sum">,

    // Represents a bucketization of the integers from [0, MAX_INT], encoded as
    // a list of integers where new buckets begin (excluding 0 which is
    // implicitly included).
    // It must consist of strictly increasing positive integers.
    //
    // e.g. [5, 10, 100] encodes the following ranges:
    // [[0, 4], [5, 9], [10, 99], [100, MAX_INT]]
    //
    // At the end of each reporting window, triggers will be summarized into an
    // integer which slots into one of these ranges. Reports will be sent for
    // every new range boundary that is crossed. Reports will never be sent for
    // the range that includes 0, as every source is initialized in this range.
    //
    // If omitted, then represents a trivial mapping
    // [1, 2, ... , MAX_INT]
    // With MAX_INT being the maximum int value defined by the browser.
    "summary_buckets": [<bucket start>, ...]
  }, {
    // Next trigger_spec
  } ...],

  // See description in phase 1.
  "max_event_level_reports": <int>
  // See description in phase 1.
  "event_report_windows": {
    "start_time": <int>,
    "end_times": [<int>, ...]
  }
}

此配置为每个来源注册完全指定了事件级报告的输出空间。对于每个触发器规范，我们都会完整指定以下内容：

• 一组匹配条件：
  • 该规范适用的特定触发器数据。此来源只能与具有 trigger_specs 中所指定 trigger_data 值之一的触发器匹配。换句话说，如果触发器的 trigger_data 不是来源配置中的值，即便与该来源匹配，也会被忽略。
  • 特定触发器匹配该规范的时机（使用 event_report_windows）。请注意，即使触发器不符合前面提到的两个匹配条件，仍可能与来源匹配，以生成可汇总的报告。
• 用于对归因回溯期内所有触发器进行汇总和分桶的特定算法。该算法可让触发器指定 value 参数，该参数会针对特定规范求和，但报告为分桶值。

注意：这些匹配条件在将触发器归因于特定来源后才使用。如果为来源指定了 trigger_specs，但在归因后未找到匹配的规范，该触发器就会被忽略。

触发器还支持在 event_trigger_data 内的字典中添加可选值参数。

{
  "event_trigger_data": [
    {
      "trigger_data": "2",
      "value": 100,  // Defaults to 1
      "filters": ...
    },
    ...
  ]
}

每个触发器注册最多与一个触发器规范匹配，并会更新其关联的摘要值。概括来讲，在触发时，我们将：

• 应用全局归因过滤器。
• 针对每个触发器规范，使用规范的 event_reporting_window 评估规范的 event_trigger_data，以查找匹配项。如有任何触发器规范缺少 event_report_windows 子字段，顶级 event_reporting_windows 就会用作默认值。
• 选择第一个匹配的规范进行归因，并且摘要值会按 value 递增。

当规范的 event_report_window 结束时，系统会将其摘要值映射到分桶，并针对汇总分桶中因归因的触发器值引起的每次递增发送事件级报告。报告将附带一个额外的字段，即 trigger_summary_bucket。

{
  ...
  "trigger_summary_bucket": [<bucket start>, <bucket end>],
}

与当前版本等效的配置

以下分别是 API 当前事件来源和导航来源的等效配置。尤其是对于导航来源，这说明了在保持相同 epsilon 值的情况下，为什么噪声水平相对于事件来源如此之高：因为导航来源的输出空间要大得多。

鉴于某些参数可以设置为默认值或遭到删减，因此可能存在多个等效配置。

等效事件来源

// Note: most of the fields here are not required to be explicitly listed.
// Here we list them explicitly just for clarity.
{
  "trigger_specs": [
  {
    "trigger_data": [0, 1],
    "event_report_windows": {
      "end_times": [<30 days>]
    },
    "summary_window_operator": "count",
    "summary_buckets": [1],
  }],
  "max_event_level_reports": 1,
  ...
  // expiry must be greater than or equal to the last element of the end_times
  "expiry": <30 days>,
}

等效导航来源

// Note: most of the fields here are not required to be explicitly listed.
// Here we list them explicitly just for clarity.
{
  "trigger_specs": [
  {
    "trigger_data": [0, 1, 2, 3, 4, 5, 6, 7],
    "event_report_windows": {
      "end_times": [<2 days>, <7 days>, <30 days>]
    },
    "summary_window_operator": "count",
    "summary_buckets": [1, 2, 3],
  }],
  "max_event_level_reports": 3,
  ...
  // expiry must be greater than or equal to the last element of the end_times
  "expiry": <30 days>,
}

自定义配置示例

以下是一些除默认值之外的其他配置。在所有这些示例中，开发者需要权衡以下方面：

• 减少默认配置的某个维度（#triggers、触发器数据基数、#windows），以再增加一个维度来保持噪声水平
• 减少默认配置的某个维度（#triggers、触发器数据基数、#windows），以降低噪声水平

报告触发器值分桶

如果开发者希望仅针对一个报告期（例如 7 天）优化值数据，可采用此示例配置来缩减报告期，从而减少噪声。在此示例中，任何将 trigger_data 设置为非 0 值的触发器都不符合归因条件。

{
  "trigger_specs": [
  {
    "trigger_data": [0],
    "event_report_windows": {
      "end_times": [604800, 1209600] // 7 days, 14 days represented in seconds
    },
    "summary_window_operator": "value_sum",
    "summary_buckets": [5, 10, 100]
  }],
}

您可以通过设置 value 字段来注册触发器，系统会对相关值求和并进行分桶。例如，如果在来源注册后的 7 天内有 3 个触发器，其值分别为 1、3 和 4。

{ "event_trigger_data": [{"trigger_data": "0", "value": 1}] }
{ "event_trigger_data": [{"trigger_data": "0", "value": 3}] }
{ "event_trigger_data": [{"trigger_data": "0", "value": 4}] }

这些值的总和为 8，并会在 7 天 + 1 小时后出现在以下报告中：

// Report 1
{
  ...
  "trigger_summary_bucket": [5, 9]
}

在随后的 7 天内，注册了以下触发器：

{ "event_trigger_data": [{"trigger_data": "0", "value": 50}] }
{ "event_trigger_data": [{"trigger_data": "0", "value": 45}] }

这些值的总和为：8 + 50 + 45 = 103。14 天 + 1 小时后生成的报告如下：

// Report 2
{
  ...
  "trigger_summary_bucket": [10, 99]
},

// Report 3
{
  ...
  "trigger_summary_bucket": [100, MAX_INT]
}

报告触发器统计

以下示例展示了开发者该如何配置来源才能一次最多统计 10 个触发器。

{
  "trigger_specs": [
  {
    "trigger_data": [0],
    "event_report_windows": {
      "end_times": [604800] // 7 days represented in seconds
    },
    // This field could be omitted to save bandwidth since the default is "count"
    "summary_window_operator": "count",
    "summary_buckets": [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
  }],
}

系统会对 trigger_data 设为 0 的归因触发器进行统计，最多 10 个。由于 summary_window_operator 设为 count，因此系统会忽略触发器值。如果有 4 个触发器被注册并归因于该来源，报告将如下所示：

// Report 1
{
  ...
  "trigger_summary_bucket": [1, 1]
}
// Report 2
{
  ...
  "trigger_summary_bucket": [2, 2]
}
// Report 3
{
  ...
  "trigger_summary_bucket": [3, 3]
}
// Report 4
{
  ...
  "trigger_summary_bucket": [4, 4]
}

报告频率更高的二进制情况

如果开发者想要了解在前 10 天内是否至少发生了一次转化（无论价值为何），但希望以比默认间隔时间更短的时间接收报告，可采用此示例配置。同样，在此示例中，任何将 trigger_data 设置为非 0 值的触发器都不符合归因条件。这就是我们将此用例称为“二进制情况”的原因。

{
  "trigger_specs": [
  {
    "trigger_data": [0],
    "event_report_windows": {
      // 1 day, 2 days, 3 days, 5 days, 7 days, 10 days represented in seconds
      "end_times": [86400, 172800, 259200, 432000, 604800, 864000]
    },
    // This field could be omitted to save bandwidth since the default is "count"
    "summary_window_operator": "count",
    "summary_buckets": [1]
  }],
}

触发器规范因来源而异

注意：trigger_specs 注册可能因来源而异。此示例有两种配置，一种指定只有 trigger_data 值介于 0 到 3 之间的触发器符合归因条件，另一种指定只有 trigger_data 值介于 4 到 7 之间的触发器符合归因条件。用户可以将一半的来源配置为前者，将一半的来源配置为后者。这样做的结果是，添加到报告中的噪声约为导航来源默认配置噪声的 15%。

{
  "trigger_specs": [
  {
    "trigger_data": [0, 1, 2, 3],
    "event_report_windows": {
      "end_times": [172800, 604800, 2592000] // 2 days, 7 days, 30 days represented in seconds
    }
  }],
  "max_event_level_reports": 3
}

{
  "trigger_specs": [
  {
    "trigger_data": [4, 5, 6, 7],
    "event_report_windows": {
      "end_times": [172800, 604800, 2592000] // 2 days, 7 days, 30 days represented in seconds
    }
  }],
  "max_event_level_reports": 3
}

欢迎开发者针对这个 API 扩展程序提出不同的用例建议，我们将据此更新本说明文档，在其中提供相关用例的示例配置。

无重定向的跨广告网络归因

广告技术平台应使用重定向来注册多个归因来源触发器并执行跨广告网络归因。在无法跨广告网络进行重定向的情况下，这项功能可协助进行跨广告网络归因。了解详情。

广告技术平台可以在触发器注册响应中发送配置，选择由其他广告技术平台注册的来源来生成派生来源；然后将这些派生来源用于归因。如果触发器归因于派生来源，则会生成汇总报告。系统不支持为派生来源生成事件报告。

广告技术平台可从其注册来源中选择打算与合作伙伴广告技术平台共享的 aggregation_keys。这些键可在来源注册标头 Attribution-Reporting-Register-Source 下的可选 shared_aggregation_keys 字段中声明：

"shared_aggregation_keys": ["[key name1]", "[key name2]"]

派生来源是根据触发器注册标头 Attribution-Reporting-Register-Trigger 下的配置生成的：

  // Specifies the configuration based on which derived sources should be
  // generated. Those derived sources will be included for source matching at the
  // time of attribution. For example, if adtech2 is registering a trigger with an
  // attribution_config with source_network as adtech1, available sources
  // registered by adtech1 will be considered with additional filtering criteria
  // applied to that set as mentioned in the attribution_config. Derived
  // sources can have different values to priority, post_install_exclusivity_window
  // etc.

  "attribution_config": [
    {
      // Derived sources are created from this adtech's registered sources
      "source_network": "[original source's adtech enrollment ID]",
      //(optional) Filter sources whose priority falls in this range
      "source_priority_range": {
        "start": [priority filter lower bound],
        "end": [priority filter upper bound]
      },
      // (optional) Filter sources whose at least one of filter maps matches these
      // filters
      "source_filters": {
        "key name 1": ["key1 value 1"]
      },
      // (optional) Filter sources whose none of filter map matches these
      // filters
        "source_not_filters": {
          "key name 1": ["key1 value 1"]
        },
      // (optional) Apply this priority to the generated derived sources
      "priority": "[64 bit signed integer]",
      // (optional) The derived source will have expiry set as this or parent
      // source's, whichever is earlier
      "expiry": "[64 bit signed integer]",
      // (optional) set on the derived source
      "filter_data": {
        "key name 1": ["key1 value 1"]
      },
      // (optional) set on the derived source
      "post_install_exclusivity_window": "[64-bit unsigned integer]"
    }
  ]

以下是添加了示例值的版本：

  "attribution_config": [
    {
      "source_network": "adtech1-enrollment-id",
      "source_priority_range": {
        "start": 50,
        "end": 100
      },
      "source_filters": {
        "source_type": ["NAVIGATION"]
      },
      "source_not_filters": {
        "product_id": ["789"]
      },
      "priority": "30",
      "expiry": "78901",
      // (optional) set on the derived source
      "filter_data": {
        "product_id": ["1234"]
        },
      // (optional) set on the derived source
      "post_install_exclusivity_window": "7890"
    }
  ]

触发器注册标头添加了两个新的选填字段。这些字段用于在可汇总报告键中启用胜出广告技术平台的标识符：

• x_network_bit_mapping：注册 ID 到广告技术平台标识符的位映射
• x_network_data：胜出广告技术平台的 x_network_bit_mapping 与触发器键部分进行 OR 运算的偏移量（左移）

示例：

"Attribution-Reporting-Register-Trigger": {
  "attribution_config": [...],
  "aggregatable_trigger_data": [
    {
     "key_piece": "0x400",
     "source_keys": ["campaignCounts"]
      "x_network_data" : {
        "key_offset" : 12 // [64 bit unsigned integer]
      }
    }
    …
  ]
  …
  "x_network_bit_mapping": {
   // This mapping is used to generate trigger key pieces with AdTech identifier
   // bits. eg. If AdTechA's sources wins the attribution then 0x1 here will be
   // OR'd with the trigger key pieces to generate the final key piece.
    "AdTechA-enrollment_id": "0x1", // Identifier bits in hex for A
    "AdTechB-enrollment_id": "0x2"  // Identifier bits in hex for B
  }
  …
}

下面是为 AdTechB 的来源生成报告时，触发器键部分的计算结果：

• key_piece：0x400 (010000000000)
• key_offset：12
• AdtechB 的 enrollment_id 值：2 (010)（来自 x_network_bit_mapping）
• 生成的触发器键部分：0x400 | 0x2 << 12 = 0x2400

限制

有关 SDK 运行时的正在开发中的功能列表，请查看版本说明。

报告 bug 和问题

您的反馈对 Privacy Sandbox on Android 至关重要！如果发现任何问题或有任何关于改进 Privacy Sandbox on Android 的想法，欢迎告诉我们。