跳到主要内容

Session.ApproverEmailUpdate

当家长更改其 k-ID 账户的电子邮件地址时发出，该地址所批准的每个孩子各发出一次。负载中同时包含旧地址和新地址，因此你的服务器仅凭此事件就能找到已保存的记录并完成更新。

会话在其他方面不会发生变化。它仍为 ACTIVE，保留相同的 sessionId 和权限，孩子可以不受中断地继续使用。改变的只是 k-ID 之后向该孩子发送验证请求、批准和通知所使用的地址。

请订阅此事件

Webhook 端点只会收到它已订阅的事件类型。请在 Compliance Studio 中该产品的 Developer Settings 页面为你的端点选择 Session.ApproverEmailUpdate，否则 k-ID 会直接丢弃该事件，既不尝试投递也不返回错误。只有在你的组织启用了家长电子邮件更改后，该项才会出现在列表中。

投递与重试

Webhook 事件在失败时最多重试 2 次。详见投递、重试与恢复。

触发时机​

家长在 Family Connect 中发起电子邮件更改，并使用发送到新地址的一次性验证码进行确认。当家长提交更改时，k-ID 会将其每个孩子的会话重新指向新地址，并为每个孩子的会话发出一次 Session.ApproverEmailUpdate。

  • 每个孩子、每个产品一次。 如果一位家长在你的产品中有三个孩子，就会产生三个事件，各自带有不同的 id，以及相同的 oldEmail 和 newEmail。
  • 仅限拥有活跃会话的孩子。 在你的产品中没有活跃会话的孩子没有可重新指向的对象，因此不会为其发出事件。如果该孩子之后获得会话，该会话会直接基于新地址创建。
  • 提交更改只触发一次。 k-ID 只会重新指向批准人仍为 oldEmail 的会话，因此重试提交不会为已迁移的孩子发出第二个事件。但投递仍为至少一次语义，请保持处理逻辑幂等。

字段​

字段类型必填说明
eventTypestring是始终为 "Session.ApproverEmailUpdate"
dataobject是电子邮件更改详情
data.idstring (UUID)是该孩子在你产品中的会话的会话 ID
data.productIdnumber是该产品的 productId
data.oldEmailstring是家长更改前使用的地址
data.newEmailstring是家长更改后使用的地址，k-ID 此后会将该孩子的邮件发送至此

示例​

{
  "eventType": "Session.ApproverEmailUpdate",
  "data": {
    "id": "2d064cf7-0726-4193-b19a-8bd387937e60",
    "productId": 12345,
    "oldEmail": "parent@example.com",
    "newEmail": "new.parent@example.com"
  }
}

处理该事件​

  • 使用 data.id 匹配。它是此次更改所作用的会话，并且在更改前后保持不变：会话不会被重建，改变的只是其背后的地址。使用 data.oldEmail 来确认你更新的正是预期的那条记录，而不要用它来查找会话。
  • 更新你为该孩子保存的家长电子邮件地址，并同步更新所有向玩家或家长展示该地址的位置。
  • 不要让孩子重新走一遍同意流程。该会话所持有的批准没有改变，其权限也完全保持家长设置的状态。
  • 预期同一事件可能收到多次。投递为至少一次语义，因此请把处理逻辑写成幂等的：对于 newEmail 已经应用过的事件，应当不做任何操作。
  • 如果你的产品把某些内容以家长电子邮件地址而非会话作为键，那么正是此事件在防止该键过期。更稳妥的做法是以会话为键，并把电子邮件地址视为挂在其下的数据。参见最佳实践。