Skip to content

Latest commit

 

History

History
227 lines (185 loc) · 6.22 KB

TVMarketAPI.md

File metadata and controls

227 lines (185 loc) · 6.22 KB

GameCenter/AppStore API 草案(9月4日更新)

概念

  • Namespace 命名空间，可缩写为NS，代表是GameCenter或AppStore，可选的值为:

    • app AppStore
    • game GameCenter
    • video Videos

  • Item 商店中售卖的商品，对应GameCenter中的Game，AppStore中的App

  • Album 专辑，一组Item和Album的集合，有一些Album的ID是特定用途的:

    • recommend 推荐页(主页)
    • categories 所有Category的入口页
    • {category} 分类category中的所有Item集合
    • {category}/{subcategory} category中子分类subcategory种所有的Item集合

  • Type 组织Item的一种方式，可选值为:

    • album 以专辑为视角的Item组织方式，是一个集合
    • item 以单个Item为视角，是单个Item

  • UI Type UI类型，用于表达展示一组Item或一个Item的展示方法，例如

    • metro 使用类Metro布局展示
    • detail 展示一个Item的Detail

  • Sort 观察一组Item的排序方式，可选值为:

    • weighting 综合排序（默认)
    • created 创建时间逆序
    • updated 更新时间逆序
    • name 名称正序
    • score 最佳
    • download 下载数

  • Image 一张图片的URL及展现形式

  • Image Group 多张图片组成的一个展现效果，分为背景图和覆盖图

  • Flags 一组标志变量，用于表示Item的某种能力，例如:

    • upgrade App或Game是否可更新
    • joystick: Game是否支持游戏手柄

资源的URL模式

通用模式为/{NS}/{Type}?id={ID}，例如:

  • /game/album?id=album1_id GameCenter中ID为album1_id的游戏专辑
  • /game/album?id=recommand Game的主页内容
  • /game/album?id=action 所有动作类游戏(action)的专辑
  • /game/item?id=game1_id GameCenter中ID为game1_id的单个游戏

实体

实体是Item, Album 一种表达形式，使用JSON形式

  • 规则

    1. 使用{Entity}来表达引用一个实体的类型
    2. 在API调用时，指定ui参数，可使返回的Item具有不同的FieldSet

  • Image 单张图片:

    {
    "url": "http://...", // 图片的URL
	"bgcolor": "#3Fde88", // 图片在绘制前需要绘制的背景色
    "pos": {"x":100, "y":300}, // (Optional) 图片的位置，如果为null则为坐标0,0
    "ani": { ... } // (Optional) 图片的动画效果，如果为null则表示无动画
    "size": {"w": 890, "h": 789} // 图片大小
}

  • ImageGroup 一组图片，有背景图和其他覆盖在其上面的图片

     {
 	"bg": {Image}, // 背景图
     "text": {Image}, // 文字图
     "spirit": {Image}, // 精灵图
     "icon": {Image}, // 图标
     "thumb":{Image}, // 缩略图
     //...
 }

  • UI 关于UI显示的相关信息

     {
 	"type": "..."，// 当前UI的UI Type
     "layout": { // 适用于当前UI Type的布局信息，如不存在为null
     	"w": ..
         "h": ..
     }
 }

  • DisplayItem 作为一个Item在列表中展示的基本Fields

     {
 	"ns": "app|game|video", // Namespace
     "type": "category|album|item", // Type
     "id": "...", // 字符串形式的ID，对于Category来说，可能为空串
     "name": "..." // 名称
     "images": {ImageGroup}, // 图片
     "_ui": {UI}
 }

  • Item Item完整公用信息(对于App或Game来说还有各自的信息)

     // extends DisplayItem
 {
     "package": "...", // 应用包名
     "phrase": "...", // 一句话简介
     "vendor": { // 开发商
     	"id": "..."
     	"name": "北京春雨天下软件有限公司"
     },
     "flags": {
     	"upgrade": true
     }, // 标志
 	"description": "..." // 完整描述
     "times": {
     	"updated": 1909088888, // 更新时间
     },
     "ver": {
     	"code": "200", // 字符串形式的Version Code
         "name": "1.0.1" // 字符串形式的Version name
     },
     "sizes": {
     	"package": 1941662, // Byte单位的下载包大小
         "installed": 20098900, // Byte单位的安装后占用空间
     },
     "category": {
     	"id": "c1/c2", // 最为详细的分类路径
         "name": "...", // 所在分类名称
     },
     "score": 70, // 0-100的评分
     "screenshots": [
     	{ImageGroup},
         {ImageGroup},
         // ...
     ]
     "counts": {
     	"download": ... // 下载数量
       	// ...
     },
 }

  • Album Album信息，包含有Item的列表

     // extends DisplayItem
 {
 	"is_category": true|false，这个album是否是category
     "sort": "..", // sort 规则，如为Album返回则此值为null
     "pagi": "..", // 当前页码(基于1)
     "items": [
     	{DisplayItem},
         {DisplayItem},
         // ...
     ]
 }

  • AlbumList 多页Album

     {
 	"body": [{Album}, {Album}, ...]
     "preload": {
     	"images": [
         	"...",
             "..."
         ]
     }
 }

  • ItemList

     {
 	"body": [{Item}, {Item}],
     "preload": {
     	"images": [
         	"...",
             "..."
         ]
     }
 }

API

API公用信息

所有API都会附加下列参数，使用HTTP参数形式传递

  • locale 区域代码，例如zh_CN
  • res 分辨率，值为hd720 | hd1080 | hd2160
  • device设备类型
  • device_id 设备ID，一般为设备MAC地址的md5
  • ns_key Namespace的Key
  • opaque 利用ns_key和URI即参数算出的URL签名

API 列表

  • GET /1/{ns}/category?id={id}&sort={sort}&page={page}&filter=... 返回{AlbumList} 获取Category内容

    1. page是基于1的，默认值为1
    2. sort参数对非Category类Album不起作用

  • GET /1/{ns}/album?id={id}，返回: {AlbumList} 获取Album内容

  • GET /1/{ns}/search?q=word&category=c1/c2，返回: {AlbumList} 搜索

  • GET /1/{ns}/home，返回: {AlbumList} 主页

  • GET /1/{ns}/item?id={id}，返回: {ItemList} 获取单个Item信息

  • GET /1/{ns}/download?item={id}，返回: 待定