TeyvatGuide/docs/UIGF.md

Author, Date, Description, Update

Author	Date	Description	Update
目棃	2023-04-07	UIGF v2.3 Backup	2023-04-07

本文档 Front-matter 由 MuCli 自动生成于2023-04-07 19:51:40

更新于 2023-04-07 19:51:40

本文档为 UIGF 的备份。

统一可交换祈愿记录标准 v2.3

Uniformed Interchangeable GachaLog Format standard (UIGF) v2.3

更新记录

版本	说明	兼容
v2.0	首个正式版本	v2.0
v2.1	简化了部分语言表述，与 v2.0在数据格式上完全一致	v2.1 and lower
v2.2	新增 info.export_timestamp 填充 UNIX 时间戳	v2.2 and lower
v2.3	扩充至非中文语境，使用 Json Schema 表述	v2.3 and lower

Id

原神的祈愿记录物品内包含了一项较为特殊的字段: id ，该值在 1.3版本后加入
所以先前查询出的物品若无特殊兼容性修改则不会包含相应的 id
App 导出 UIGF 时

• 需要确保每个物品的 id 的有效性。
• 从最后一个自带有效 id 的物品开始，向前（相对于时间）依次递减 id 的值,每次递减的值应保持为 1

导入 UIGF 到 App 时

• App不应假设所有的 gacha_item 都有有效的 id 值
• App应具有处理 id 字段为 null或 `` 空字符串的能力

GachaType

祈愿包含了会共享保底与概率的卡池，所以需要一个额外的字段来界定
我们在UIGF的所有格式中注入了uigf_gacha_type字段
在导出到UIGF格式时需要注意添加对应的uigf_gacha_type字段

映射关系

uigf_gacha_type	gacha_type
100	100
200	200
301	301 or 400
302	302

Json 格式

Uniformed Interchangeable GachaLog Format standard of Json (UIGF.J) Json 格式 由于 与从官方接口获取到的格式一致
更便于各App的导入与导出，我们也在此做出规范
该格式应仅用于各App间的数据互通

导出的格式

{
  "type": "object",
  "title": "UIGF object",
  "properties": {
    "info": {
      "type": "object",
      "properties": {
        "uid": {
          "type": "string",
          "title": "Uid",
          "description": "Uid"
        },
        "lang": {
          "type": "string",
          "title": "Language",
          "description": "语言 ISO 3166"
        },
        "uigf_version": {
          "type": "string",
          "title": "UIGF Version",
          "description": "UIGF 版本号"
        },
        "export_timestamp": {
          "type": "number",
          "title": "Export Timestamp",
          "description": "导出时间戳（秒）"
        },
        "export_time": {
          "type": "string",
          "description": "导出时间",
          "format": "date-time",
          "pattern": "yyyy-MM-dd HH:mm:ss",
          "title": "Export Time"
        },
        "export_app": {
          "type": "string",
          "title": "Export App",
          "description": "导出应用"
        },
        "export_app_version": {
          "type": "string",
          "title": "Export App Version",
          "description": "导出应用版本"
        }
      },
      "title": "Infomation",
      "required": [
        "uid",
        "lang",
        "uigf_version"
      ],
      "description": "包含导出方定义的基本信息"
    },
    "list": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "gacha_type": {
            "type": "string",
            "description": "祈愿类型"
          },
          "item_id": {
            "type": "string",
            "title": "Item Id",
            "description": "空字符串"
          },
          "count": {
            "type": "string",
            "title": "Count",
            "description": "数量"
          },
          "time": {
            "type": "string",
            "title": "Time",
            "description": "物品获取时间",
            "pattern": "yyyy-MM-dd HH:mm:ss",
            "format": "date-time"
          },
          "name": {
            "type": "string",
            "title": "Name",
            "description": "名称"
          },
          "item_type": {
            "type": "string",
            "title": "Item Type",
            "description": "物品类型"
          },
          "rank_type": {
            "type": "string",
            "title": "Item Quality",
            "description": "物品星级"
          },
          "id": {
            "type": "string",
            "title": "Id",
            "description": "内部数据库Id"
          },
          "uigf_gacha_type": {
            "type": "string",
            "title": "Query Type",
            "description": "向接口查询时需要的 gacha_type"
          }
        },
        "required": [
          "gacha_type",
          "name",
          "id",
          "uigf_gacha_type",
          "time"
        ],
        "title": "Gacha Item",
        "description": "祈愿物品"
      },
      "title": "List",
      "description": "物品列表"
    }
  },
  "required": [
    "info",
    "list"
  ],
  "description": "UIGF 根对象"
}

Excel 工作簿 (Workbook Format)

Uniformed Interchangeable GachaLog Format standard of Workbook (UIGF.W)

单元格的格式

• 在填充单元格内的数据时，应统一转换到 String 字符串类型后填入

表名及内容

表名	内容	类型	是否必要
统计分析	统计分析内容等	任意	否
角色活动祈愿	gacha_type : 301 or 400 的祈愿数据	祈愿表	否，但是应该导出
武器活动祈愿	gacha_type : 302 的祈愿数据	祈愿表	否，但是应该导出
常驻祈愿	gacha_type : 200 的祈愿数据	祈愿表	否，但是应该导出
新手祈愿	gacha_type : 100 的祈愿数据	祈愿表	否，但是应该导出
原始数据	全部祈愿数据	数据表	详见下方原始数据表结构说明

• 表的顺序可以是任意的
• 可以隐藏部分表，防止用户随意篡改数据
• Sheet 的名称应与游戏内祈愿记录页面显示的名称保持一致

App间应依据 原始数据表 的内容，来进行数据互通

祈愿表结构

本节内容是为了规范兼容分析类App

• 表头对应的内容填充顺序需要严格按照下方说明排布
• 共享保底的卡池按祈愿类型 (gacha_type) 区分
• 此类 Sheet 存在的目的，是为了便于用户观看与祈愿分析工具的分析

表头	内容	是否必要
时间	yyyy-MM-dd HH:mm:ss 格式的 time 时间	是
名称	name物品名称	是
物品类型	item_type	是
星级	rank_type	是
祈愿类型	gacha_type 的转义名称	是，尽管部分工具不会分析此项
...	...	否

如果你认为有必要的话，可以额外增加其他表头，但请确保表头的前几列为上表规范的内容
表内的数据通常按祈愿Id升序或降序排列，分析App不应假设表内的顺序为特定的升序与降序

gacha_type 转义名称

gacha_type	名称
100	新手祈愿
200	常驻祈愿
301	角色活动祈愿
400	角色活动祈愿-2
302	武器活动祈愿

示例

时间	名称	类别	星级	祈愿类型	...
2021-02-17 18:45:09	以理服人	武器	3	角色活动祈愿-2	...
...	...	...	...	...	...

原始数据表结构

导出时

• App 在导出时应尽可能询问用户是否应包含原始数据表
• 一旦在工作簿内包含了名为 原始数据 的表，即表示支持本格式
• 该表内的内容应严格按照本格式所述填充
• 表头的顺序需严格按照下表设置。
• 现有的字段采用字典顺序递增排序，后续新增的字段依添加的顺序排在后侧。
• 若无特殊需求，我们建议导出所有json 数据内包含的字段

导入时

• 强烈建议您编写不依赖于列的顺序位置便可实现导入的程序，以达到最大化的兼容。
• 如果省略了其中某些非必要字段的值，请保持表头存在，对应的列则空置。

表头	是否必要
count	否，但是建议保留，不排除后续会有count不为1的情况
gacha_type	是
id	是，且大部分App按此字段排序数据
item_id	否，目前官方已经弃用了此字段
item_type	是
lang	否，但建议保留，以便国际化
name	是
rank_type	否，但建议保留，以便分析
time	否，但建议保留，以便分析
uid	否，但建议将选择权交予用户，保留以便分析
uigf_gacha_type	是

示例

count	gacha_type	id	item_id	item_type	lang	name	rank_type	time	uid	uigf_gacha_type
1	301	1613556360008291100		武器	zh-cn	以理服人	3	2021-02-17 18:45:09	123456789	301
...	...	...	...	...	...	...	...	...	...	...