GDPR API参考

关注
Avatar
Dora Kishinevsky
Updated

了解如何使用 Singular API 支持 GDPR 请求。

 

有关数据主体请求如何融入更广泛的同意架构，以及为什么删除（erasure）与停止跟踪并不相同，请参阅 Consent Management with the Singular SDK: A Decision Framework。

删除并不等于选择退出（opt-out）。

此 API 会删除 Singular 针对某个标识符收集的用户级数据。它不会阻止用户设备上的 SDK 继续发送未来的事件。如果某个用户请求删除并且还应当停止被跟踪，那么除了提交 API 请求之外，应用还需要调用 stopAllTracking()（或对 SDK 初始化进行控制）。请在同一用户流程中同时处理这两项操作。

GDPR 端点

端点 方法 URL 说明
Discovery GET https://gdpr.singular.net/gdpr/discovery 返回 Singular 可通过 GDPR API 处理的所有当前支持的请求类型。
Requests POST https://gdpr.singular.net/gdpr/requests 使用此端点发送新的 GDPR 请求，通过 HTTP POST 请求发送，同时指定请求数据主体的设备 ID。
Status GET https://gdpr.singular.net/gdpr/requests/request_id 返回先前发送的请求的当前状态，该状态由请求 ID 标识。
Cancellation DELETE https://gdpr.singular.net/gdpr/requests/request_id 使用该端点可取消之前的请求。只要请求处于 "待处理 "状态，就可以取消请求。

发现端点

GET https://gdpr.singular.net/api/gdpr/discovery

使用方法

OpenGDPR Discovery 端点会返回 Singular 目前可通过 GDPR API 处理的所有支持请求类型。

查询示例

import requests
  response = requests.get("https://gdpr.singular.net/api/gdpr/discovery")
  print(response.text)

输出示例

{
    "api_version": "0.1.4",
    "supported_identities": [
      {"identity_format": "raw","identity_type": "android_advertising_id"},
      {"identity_format": "raw","identity_type": "android_id"},
      {"identity_format": "raw","identity_type": "ios_advertising_id"},
      {"identity_format": "raw","identity_type": "ios_vendor_id"},
      {"identity_format": "raw","identity_type": "user_id"}
    ],
    "supported_subject_request_types": [
        "erasure",
        "access"
    ]
  }

请求端点

POST https://gdpr.singular.net/api/gdpr/requests

使用方法

OpenGDPR Requests 端点处理新的 GDPR 请求，通过 HTTP POST 请求发送，同时指定请求数据主体的设备 ID。

完成时间： 删除请求会在提交后最多 30 天内完成。响应会返回 expected_completion_time；请使用它来设定您的 GDPR 第 12 条响应承诺。

支持的请求

OpenGDPR 请求端点支持以下类型的请求，与不同的 GDPR 权利相对应：

  • `erasure` - 支持用户根据 GDPR 第 17 条 "删除权"提出的数据删除请求
  • `access` - 支持用户根据 GDPR 第 15 条 "访问权 "提出的数据访问请求。

支持的 ID

OpenGDPR 请求端点支持以下类型的 ID：

  • `android_advertising_id` - 通过提供谷歌广告 ID（又称 GAID 或 AIFA）提出的请求
  • `android_id` - 通过提供 Android ID（又称 ANDI）提出的请求
  • `ios_advertising_id` - 通过提供 IDFA（即 iOS 广告 ID）发出的请求
  • `ios_vendor_id` - 通过提供 IDFV（供应商的 iOS ID）提出的请求
  • `user_id` - 通过提供自定义用户 ID 提出的请求

全零 IDFA 会被静默忽略。

在启用了 limit-ad-tracking 或 ATT AuthorizationStatus 为 denied 的设备上，IDFA 会被置零（"00000000-0000-0000-0000-000000000000"）。以置零 IDFA 为键的请求会被忽略，且 API 不会返回错误。请改为为这些用户提交 `ios_vendor_id`（IDFV）。由于该失败是静默的，您的 DSR 管道必须为拒绝 ATT 的 iOS 用户携带并提交 IDFV。

查询示例

import requests
  
  url = "https://gdpr.singular.net/api/gdpr/requests"
  
  payload = {
    "subject_request_id": "1c8b23f4-12eb-4fe8-af1c-0f72807dfec2",
    "subject_request_type": "access",
    "submitted_time": "2018-05-25T10:00:00Z",
    "subject_identities": [
      {
        "identity_type": "android_advertising_id",
        "identity_value": "38400000-8cf0-11bd-b23e-10b96e40000d",
        "identity_format": "raw"
      }
    ],
    "property_id": "Android:com.myapp.xyz",
  }
  
  headers = {
    "content-type": "application/json",
    "Authorization": "[API_KEY]"
  }
  
  response = requests.post(url, json=payload, headers=headers)
  print(response.text)

查询参数

参数 格式 说明 示例
subject_request_id String UUIDv4 字符串  
subject_request_type String 表示 OpenGDPR 请求类型的字符串值。Singular 目前支持以下值："擦除"、"可移植性"、"访问  
subject_identities Array 描述每个设备 ID 类型、值和格式的身份对象列表，以满足请求。一个请求最多可包含 100 个设备 ID。 
[
  {
    "identity_type":
    "android_advertising_id",
    "identity_value": 
    "38400-8cf0-11bd-b23e-1000d",
    "identity_format": "raw"
  }
  ]
submitted_time   RFC 3339 日期字符串，代表数据主体提出原始请求的时间 2010-05-25T10:00:00Z
property_id String 平台]:[长名]对，用于指定相关应用程序。 iOS:com.myapp.xyz

输出示例

{
    "controller_id":"example_controller_id",
    "received_time":"2018-05-25T10:00:01Z",
    "expected_completion_time": "2018-06-24T10:00:01Z",
    "encoded_request":"<BASE64 ENCODED REQUEST>",
    "subject_request_id":"1c8b23f4-12eb-4fe8-af1c-0f72807dfec2",
    "results_url": "https://url-to-results-in-json-format",
    "api_version": "0.1.4"
  }

删除范围

删除会移除 Singular 针对该标识符保存的用户级记录（日志和归因明细）。聚合数据（例如群组汇总）在聚合之后无法按设备定位，因此不受删除影响。请在您自己的隐私文档中说明这一区别。

状态端点

GET https://gdpr.singular.net/api/gdpr/requests/<REQUEST_ID>

使用方法

返回先前发送的请求的当前状态，该状态由请求 ID 标识。

查询示例

import requests
  url = "https://gdpr.singular.net/api/gdpr/requests/"
  subject_request_id = "1c8b23f4-12eb-4fe8-af1c-0f72807dfec2"
  headers = {"Authorization": "<API KEY>"}
  response = requests.get(url+subject_request_id, headers=headers)
  print(response.text)

输出示例

{
      "controller_id": "example_controller_id",
      "request_status": "completed",
      "expected_completion_time": "2018-06-24T10:00:01Z",
      "subject_request_id": "1c8b23f4-12eb-4fe8-af1c-0f72807dfec2",
      "api_version": "0.1.4"
  }

取消端点

DELETE https://gdpr.singular.net/gdpr/requests/<REQUEST_ID>

使用方法

使用此端点可取消先前的请求。只要请求处于 "待处理 "状态，就可以取消。

查询示例

import requests
  url = "https://gdpr.singular.net/api/gdpr/requests/"
  subject_request_id = "1c8b23f4-12eb-4fe8-af1c-0f72807dfec2"
  headers = {"Authorization": "<API KEY>"}
  response = requests.delete(url+subject_request_id, headers=headers)
  print(response.text)

输出示例

{
    "controller_id":"example_controller_id",
    "subject_request_id":"1c8b23f4-12eb-4fe8-af1c-0f72807dfec2",
    "received_time":"2018-05-25T10:00:01Z",
    "api_version":"0.1"
  }