Skip to content

Ticket in app page API

Jump to bottom
Lee Yeh edited this page Oct 19, 2022 · 9 revisions

功能与 URL

Baseurl

https://{domain}/in-app/v1/categories/:root-category-id

这是所有功能页面的基础 URL，其中：

  • domain：应用绑定的的独立域名。
  • root-category-id： 一个厂商下可能会有多个独立的应用，在用户侧应用内的工单应该是隔离的。所以一般在工单系统后台会将一级分类按应用分。用户侧则通过 root-category-id 指定所对应的分类（分类的 ID 可以在客服后台的分类配置详情页面找到）。 对于不分应用的厂商（一个厂商一个应用），root-category-id 填 - ，会显示所有分类。

功能页面

应用可以直接打开对应的 URL 展示相应的页面：

  • {baseurl}/ 落地页，会展示客服配置的常见问题（如有），工单列表入口，以及第一级分类（供发起新工单）。一般应用内的客服入口会指到这个页面。
  • {baseurl}/tickets 用户工单列表页，可以看到用户所有历史工单。
  • {baseurl}/tickets/new?category_id={id} 提交新工单的页面，一般是用户从落地页选择分类之后自动跳转过去，也可以由应用带着指定的 category_id 直接打开。

登录

本文已过时，请参考 https://xindong.atlassian.net/wiki/spaces/TDS/pages/478384609

终端用户应该只能看到自己的工单，所以工单系统有一个账号系统，必须要登录才能使用工单。登录有几种不同的方式。

匿名登录

这里的匿名指的是工单系统完全不知道应用账号系统的存在（工单系统的所有的用户都是匿名的）。此时，应用需要提供一个 UUID 作为工单的匿名账号 ID。然后在打开的 URL 中通过 hash 传入以下信息：

{url}#anonymous-id=c58e106c-2857-4c9e-9b0a-548bfa3c3b80

这里的匿名账号 ID 需要应用侧提供并维护，工单系统不关心这个匿名账号 ID 的来源，也不会进行任何的校验，这也意味着丢失了这个 ID 则无法访问历史工单，泄露了这个 ID 则历史工单也会被泄露。我们推荐使用一个专门为工单系统生成的 UUID 来作为这个 ID，应用也可以使用其他的 ID，但必须满足以下条件：

  • 用户唯一且不会变
  • 无法被猜测到、无法枚举
  • 不会被用户通过分享或截图等方式泄露

匿名登录与现有账号系统的关系

匿名登录的对象是工单系统，与是否登录应用账号没有必然的关系。应用有账号系统也可以使用匿名登录的方式对接工单系统。一种推荐的实践：

  • 在未登录应用账号的状态下，如果用户点击工单入口，生成一个 UUID 作为工单系统用户 ID 在设备本地持久化。
  • 注册账号时，如果当前设备上已经有一个工单系统用户 ID，直接将其关联到这个新账号上（存储到账号系统数据库中）。
  • 登录应用账号后：
    • 如果设备上没有未登录状态下的工单用户 ID，什么都不用做。在此之后，如果用户点击了工单入口：
      • 如果该帐号没有关联的工单用户 ID（说明这个账号从未用过工单），新生成一个 UUID 关联到登录账号上。
      • 如果该帐号有关联的工单用户 ID，什么都不用做，直接用这个 ID 继续即可。
    • 如果设备上有未登录状态下的工单用户 ID：
      • 该帐号没有关联的工单用户 ID，如果用户确认要合并，将本地的 ID 直接关联到登录账号上然后清除本地 ID。
      • 该帐号有关联的工单用户 ID，但设备上有本地工单用户 ID，如果用户确认要合并，需要调用一个合并账号的 API，然后清除本地 ID。

与现有账号系统关联登录

独立部署不再支持该功能，多租户方案参见： https://xindong.atlassian.net/wiki/spaces/TDS/pages/232508585

工单系统也提供了更加安全的方式来与现有的账号系统关联登录。需要在 auth.data 中提供一个用户的唯一 ID，以及一个校验的方式。举个（虚构的）例子：

{url}#auth={"platform":"taptap","data":{uid:"31351623",signature:"a-jwt-token"}}

需要注意，hash 是需要 URL 转义的，为了可读性上面的 URL 显示的是在浏览器地址栏中展示的值，其实际的值是：

"{url}#auth=%7B%2522platform%2522%3A%2522taptap%2522%2C%2522data%2522%3A%7Buid%3A%252231351623%2522%2Csignature%3A%2522a-jwt-token%2522%7D%7D"

这里在传入 uid 的同时提供了一个 signature。工单会支持在登录时在服务端触发一个 hook 来校验这个 signature 是否是正确且有效（需要使用云引擎），只有有效签名的登录请求才会被放行。除了校验签名，这套流程也支持在 hook 中访问一个现有账号系统的 API 来校验信息等多种鉴权方式。

通过 TapSDK 登录（暂未实现）

如果应用使用了 TapSDK 的用户系统，则可以直接使用 SDK 提供的 API 登录。SDK 同样支持匿名账号登录与 TapSDK 账号系统登录。该部分待 SDK 实现后给出。

传参

工单中支持在 URL hash 中传入设备、用户相关的信息。这些信息可以打开（任意）工单页面时带上，在提交工单时会与该工单关联。这些信息被分为两类：

用户不可见的信息

这部分信息仅客服可见，最常见的如设备机型、网络状况、用户的一些配置。可以通过下面的参数传递（记得对 meta 的值 encode）：

{url}#meta={"key":"value"}

meta 在客服后台的呈现形式是这样的，其中 key 的值与 value 的类型没有任何限制（key 的含义可以在后台配置）：

image

用户可见的表单信息

工单的分类可以设置一个表单，通过用户填写表单的信息收集一些结构化的信息，这些信息也可以通过 URL 参数来预填写。请注意这些信息是用户可见且可以修改的，如果不希望用户看见，或者不允许用户修改，可能使用上一段说的 meta 更合适。

{url}#fields={"{id}":{value},"60d18c10d604b86f6cd5ba60":"13123456789"}

其中 ID 可以在客服后台的字段设置详情页找到：

image

应用层需要实现的逻辑

Webview 的打开与关闭

更新提醒（小红点）

该部分已过时，更新：https://xindong.atlassian.net/wiki/spaces/~LiYe.XD/pages/83624068/SDK

目前我们只支持应用内的更新提醒。后续会支持通过推送服务推送更新提醒。

应用内需要如果没有使用 SDK，则应用需要自行通过轮询获取更新提醒。

对于匿名登录接入的应用。首先当前账号或者当前设备上没有工单系统 ID（也就是从来没用过），则不需要轮询。否则可以每隔 30 分钟（或者使用某种更高效的 backoff interval 策略）以该 ID 为参数请求一下接口获取有无未读消息：

> curl https://{domain}/api/2/unread -X GET -H "x-anonymous-id: c58e106c-2857-4c9e-9b0a-548bfa3c3b80"
< true / false
Clone this wiki locally