概述

Branch Data Subject Request API 通过数据保护法的两个关键组成部分为我们的客户提供支持,例如《通用数据保护条例》 2016/679(GDPR)和《加利福尼亚消费者隐私法案》(CCPA)–访问个人数据的权利和请求的权利删除个人数据(也称为权利被遗忘)。

借助此 API,Branch 客户可以通过编程方式:

  • 访问由 Branch 存储的终端用户个人数据。
  • 从 Branch 抹除终端用户的个人数据。

🚧

此 API 仅适用于 Branch 客户。

如果您使用的是使用 Branch 的应用或网站的用户,则需要直接通过相应的应用或网站提出请求以访问您的个人数据(GDPR 是您的个人数据的控制者),以要求您提供个人数据将从 Branch 删除,或用于其他 Data Subject Request。然后,那些使用 Branch 的应用和网站将把该请求传递给我们。我们完全致力于与我们的应用和网站合作伙伴合作,以根据适用的数据保护法解决您的权利。

🚧

仅按要求

Access to the GDPR API is by request only. Please contact our support team to gain access to this feature.

认证

调用 Data Subject Request API 时,需要将 api_key 查询 string 参数与每个请求一起传递。 API Key 是基于每个用户生成的,并且是永久的。

Learn how to retrieve your API key (a.k.a. Access Token)

访问级别

为了访问 Data Subject Request API,用户将需要具有敏感数据访问权限以及 应用级别的读取/编辑访问权限

For more details on how to give a user the required access, please read Default Access Levels, Users Roles & Permissions.

第三方访问

由于 Data Subject Request API 的独特目的,因此不允许第三方(例如代理商)访问此 API。这包括具有上述必需访问级别的代理。

频率限制

Data Subject Request API 包括以下限制:

  • 每个请求1000个身份对象限制
  • 每秒5个请求
  • 每分钟10个请求
  • 每小时100个 API 访问权限

访问 Endpoint

POST https://api2.branch.io/v1/gdpr?app_id=<App-ID>
Content-type: application/json
Host: api2.branch.io

从 Branch Metrics 中访问与已知给定身份相关联的任何个人数据。

HTTP Header参数

HTTP Header参数

api_key / access token | REQUIRED | String

您的 API Key/访问 Token。

查询参数

查询参数

app_id | REQUIRED | Long

Branch 分配的应用 ID;可在 Dashboard -> Account Settings -> Profile tab -> About your App 查看

Body 参数

Body 参数

subject_request_type | REQUIRED | String

发送的发布请求的类型。在这种情况下,“访问”是由 Branch 分配的 App ID;可在操作后台 (Dashboard)->Account Settings->Profile tab->About your App 访问

subject_identities | REQUIRED | String

这是一个包含以下 JSON 格式的设备 ID 的数组。

identity_type | REQUIRED | String

发送的身份类型。形式可以为 “BROWSER_ID”,“DEVICE_ID”,“USER_ID” 或 “DEVELOPER_ID”。

BROWSER_ID | Either of one identity_type mandatory | String

浏览器用户身份标识,例如 browser_fingerprint_id。

DEVICE_ID | Either of one identity_type mandatory | String

The device user identifier such as IDFA, IDFV, Google_advertising_id.

USER_ID | Either of one identity_type mandatory | String

应用范围的 user-id。

identity_value | REQUIRED | String

identity_type,IDFA,Google_advertising_id 的值。

identity_format | NOT REQUIRED | String

以 “raw” 形式发送。Branch 目前仅支持 “raw”。

样品访问请求

curl -X POST 'https://api2.branch.io/v1/gdpr?app_id=<YOUR _APP_ID_HERE>'
    -H "Content-Type: application/json"
    -H "Access-Token: YOUR_ACCESS_TOKEN_HERE"
    -d '{ "subject_request_type": "access",
                  "subject_identities": [
                      {
                           "identity_type": "BROWSER_ID",
                           "identity_value": "123",
                           "identity_format": "raw"
                       }
                       {
                            "identity_type": "BROWSER_ID",
                            "identity_value": "123",
                            "identity_format": "raw"
                       }
                    ]
                 }

样本访问响应

响应码:200

成功注册访问请求

{
  "request_id": "79c03c22-e8a7-4ae4-a4f6-a8349ef0016a",
  "request_status": "PENDING"
}

响应参数

request_id | String

为发出的请求生成的 UUID。以后可以使用它来检查请求的状态。

request_status | String

这是您的请求状态。可能的值:

  • “SUCCESS”:请求已完成。
  • “ PENDING”:已收到正确的请求,并且当前在队列中
  • “ IN_PROGRESS”:该请求当前正在执行。

抹除 Endpoint

POST https://api2.branch.io/v1/gdpr/status
Content-type: application/json
Host: api2.branch.io

从 Branch Metrics 中删除与已知给定身份相关的任何个人数据。

HTTP Header参数

HTTP Header参数

iapi_key / access token | REQUIRED | String

您的 API Key/访问 Token。

查询参数

查询参数

iapp_id | REQUIRED | Long

Branch 分配的应用 ID;可在 Dashboard -> Account Settings -> Profile tab -> About your App 查看

Body 参数

Body 参数

subject_request_type | REQUIRED | String

发送的发布请求的类型。在这种情况下,“erasure

subject_identities | REQUIRED | String

这是一个包含以下 JSON 格式的设备 ID 的数组。

identity_type | REQUIRED | String

发送的身份类型。形式可以为 “BROWSER_ID”,“DEVICE_ID”,“USER_ID” 或 “DEVELOPER_ID”。

BROWSER_ID | Either of one identity_type mandatory | String

浏览器用户身份标识,例如 browser_fingerprint_id。

DEVICE_ID | Either of one identity_type mandatory | String

The device user identifier such as IDFA, IDFV, Google_advertising_id.

USER_ID | Either of one identity_type mandatory | String

应用范围的 user-id。

identity_value | REQUIRED | String

identity_type,IDFA,Google_advertising_id 的值。

identity_format | NOT REQUIRED | String

以 “raw” 形式发送。Branch 目前仅支持 “raw”。

样品清除请求

curl -X POST 'https://api2.branch.io/v1/gdpr?app_id=<YOUR _APP_ID_HERE>'
    -H "Content-Type: application/json"
    -H "Access-Token: YOUR_ACCESS_TOKEN_HERE"
    -d '{ "subject_request_type": "erasure",
                   "subject_identities": [
                      {
                           "identity_type": "BROWSER_ID",
                           "identity_value": "123",
                           "identity_format": "raw"
                       }
                       {
                             "identity_type": "USER_ID",
                             "identity_value": "ABC123",
                             "identity_format": "raw"
                       }
                    ]
                 }

样品清除响应

响应码:200
成功注册删除请求

{
  "request_id": "79c03c22-e8a7-4ae4-a4f6-a8349ef0016a",
  "request_status": "PENDING"
}

响应参数

request_id | String

为发出的请求生成的 UUID。以后可以使用它来检查请求的状态。

request_status | String

这是您的请求状态。有可能
“SUCCESS”:请求已完成。
“ PENDING”:已收到正确的请求,并且当前在队列中
“ IN_PROGRESS”:该请求当前正在执行。

下载/状态请求

获取从访问/清除 POST 请求生成的给定 request_id 的请求的当前状态。

HTTP Header参数

HTTP Header参数

api_key / access token | REQUIRED | String

您的 API Key/访问 Token。

查询参数

查询参数

app_id | REQUIRED | Long

Branch 分配的应用 ID;可在 Dashboard -> Account Settings -> Profile tab -> About your App 查看

Body 参数

Body 参数

request_id | String

为发出的请求生成的 UUID。以后可以使用它来检查请求的状态。

样本下载/状态请求

curl -X POST 'https://api2.branch.io/v1/gdpr/status?app_id=<YOUR _APP_ID_HERE>'
-H "Content-Type: application/json"
-H "Access-Token: YOUR_ACCESS_TOKEN_HERE"
-d '{"request_id": "<ID>"}'

样品状态响应

响应码:200
成功注册状态请求

{
  "request_id": "79c03c22-e8a7-4ae4-a4f6-a8349ef0016a",
  "request_status": "SUCCESS"
}

响应参数

request_id | String

为发出的请求生成的 UUID。以后可以使用它来检查请求的状态。

request_status | String

这是您的请求状态。有可能
“SUCCESS”:请求已完成。
“ PENDING”:已收到正确的请求,并且当前在队列中
“ IN_PROGRESS”:该请求当前正在执行。

样本下载响应

响应码:200
成功注册状态请求

{
  "request_id": "79c03c22-e8a7-4ae4-a4f6-a8349ef0016a",
  "request_status": "COMPLETED",
  "export_url": "presigned_s3_link"
}

响应参数

request_id | String

为发出的请求生成的 UUID。以后可以使用它来检查请求的状态。

request_status | String

这是您的请求状态。有可能
“SUCCESS”:请求已完成。
“ PENDING”:已收到正确的请求,并且当前在队列中
“ IN_PROGRESS”:该请求当前正在执行。

export_url | String

预先分配的 s3 URL 链接,用于下载包含请求的身份对象的 CSV 文件。

附录

错误代码

1. RC 400 错误请求

  • 缺少或无效的 Branch Key:
{
    "error": {
        "message": "Invalid or missing app id, Branch key, or secret",
        "code": 400
    }
}
  • 无效的 JSON:
{
    "error": {
        "code": 400,
        "message": "Invalid JSON"
    }
}
  • 缺少必填字段/格式格式错误:
{
    "error": {
        "subject_request_type": "not a valid option",
        "submitted_time": "wrong field type",
        "subject_identities": [
            "identity_type": "not a valid option",
            "identity_value": "wrong field type",
            "identity_format": "not a valid option"
        ]
    }
}

2. RC 429:已达到频率限制

{
    "error": {
        "code": 429,
        "message": "Rate limit reached."
    }
}

3. RC 404:找不到/错误的 API URL

<html>
<head><title>404 Not Found</title></head>
<body bgcolor="white">
<center><h1>404 Not Found</h1></center>
<hr><center>openresty/1.13.6.2</center>
</body>
</html>