术语表

本文描述游戏侧对接世游发行平台时，需要理解的概念与术语。

基础概念

Game

一款由世游发行的，接入了世游发行平台以及 Combo SDK 的游戏。

游戏客户端可以运行在 iOS、Android、Windows 多个平台上，但无论支持多少个平台，都是同一个 Game，而非多个 Game。

Game ID

由世游侧为游戏分配，用于标识游戏的业务代号，是一个字符串。

新接入世游发行平台的游戏，可以联系我们获得 Game ID。

Build Key

由世游侧为游戏分配，游戏侧和世游侧共享的 API Key，用于构建工具 Combo CLI 调用世游 Build REST API。

Build Key 仅在构建期出包时使用，且不会被打包进客户端。

Build Key 总是以 bk_ 为前缀，例如 bk_qvmdXKoNPvPjZi5QwMimw7joQYEiw5iG。

Publishable Key

由世游侧为游戏分配，游戏侧和世游侧共享的 API Key，用于 Combo SDK 在客户端运行期调用世游 Client REST API。

Publishable Key 不被认为是秘密。它仅用于标识游戏，会被打包在游戏客户端内，是可公开的。

Publishable Key 总是以 pk_为前缀，例如 pk_ftP0pJeQDBzdFi2NVxCJpIWEXCRcFtWq。

Secret Key

由世游侧为游戏分配，游戏侧和世游侧共享的 API Key，用于游戏服务端调用世游 Server REST API，以及用于游戏服务端接受来自世游服务端的通知。

顾名思义，Secret Key 应当被当作秘密对待，应当被存储在游戏服务器上，不应该放在游戏客户端。世游侧与游戏侧都应当严格控制对 Secret Key 的访问。

Secret Key 总是以 sk_ 为前缀，例如 sk_ccfnI47BVXdMv3iboHfI78H2ISyXPN6D。

API Endpoint

世游发行平台对外提供服务的 API 端点，是一个 URL。

国内和海外是独立的 API 端点。两者的区别仅在于 TLD，国内使用 com，海外使用 io。

端点	URL	备注
中国区域	https://api.seayoo.com	部署在中国大陆，用于国内发行的产品
全球区域	https://api.seayoo.io	部署在海外，用于全球发行的产品

提示

• 仅提供 HTTPS 端点，不提供 HTTP 端点。
• 在各个 SDK 中，均已内置了上述 Endpoint。

Server REST API

Server REST API 的请求来自于后端，通常由游戏的服务端发起调用。

目前我们提供了 Go 和 Node.js 的 Combo SDK，游戏侧接入这些 SDK 即可，不需要直接对接 REST API。

但如果游戏服务端使用的是其他编程语言，可按照 服务端接入 文档，编写代码进行接入。

Server Notifications

Server Notifications 是指从世游服务端发起的，到游戏服务端的 server-to-server 的 HTTP 调用。

HTTP 调用的标准由世游定义，游戏服务端负责实现，参见：服务端通知。

其原理可参考 App Store Server Notifications。

Notify URL

游戏服务端接收通知的一个 HTTP URL，通常又被称为 Webhook，参见：通知端点。

Parameter

Game 在接入世游发行平台和 Combo SDK 时的配置项，被称为 Parameter（参数）。

Game 的 Parameter 需要在 世游发行平台 Console 上进行配置。

未正确配置 Parameter 的 Game 是不能正常工作的，无法通过测试，也无法上线。

Domain

这里指的是 Domain-driven design (DDD) 中的 Domain。

Domain 起到分解系统复杂度，统领、串联前后端实现的作用。

Domain 就像积木，是可组合的：

• 游戏的 Parameter，按照 Domain 进行归类，每个 Parameter 从属于一个 Domain
• Combo SDK 内部的功能模块，按照 Domain 来组织，每个模块从属于一个 Domain
• 游戏的 Distro 包含哪些 Domain，决定了其具有哪些业务功能
• Combo SDK 的构建工具 CLI，根据要构建的 Distro 中包含的 Domain 决定要集成哪些 SDK 模块，以及要将哪些 Build Parameter 打入包中
• Combo SDK 在运行期获取的 Parameter，由 Distro 包含的 Domain 来决定
• 服务端根据业务功能所属的 Domain 去读取一组 Parameter 并使用

围绕着 Domain 这个概念，世游发行平台与 Combo SDK 有机地配合起来，并且相互并不过度耦合。

Distro (Distribution)

这里指的是 Software distribution 中的 Distro。

Distro 是游戏客户端的发行版本，这是一个世游定义的字符串。

每个 Distro 都会包含若干 Domain。包含哪些 Domain，决定了客户端的分发、推广、投放方式（从哪个应用商店或网站上下载，从什么途径获客），也决定了客户端使用的 IdP、Store，客户端包含哪些第三方 SDK，以及启用哪些功能。

这个概念在过去通常也被称为 发行渠道。

信息

发行版本举例：

• android 世游官网 Android 版本。使用世游通行证进行账号登录，使用世游游戏商城进行内购，使用微信/支付宝进行支付。
• app_store 苹果 App Store 的 iOS 版本。使用世游通行证进行账号登录，使用 App Store 进行内购。
• google_play Google Play 的 Android 版本。使用 Google 或 Facebook 账号登录，使用 Google Play 进行内购。
• xiaomi 小米游戏中心的 Android 版本。使用小米游戏 SDK 进行账号登录与内购。

发行版本与 IdP、Store 并非一一对应，切不可混为一谈。 某个发行版本，可以根据运营需求添加或改变所使用的 IdP 与 Store。 因此在前后端设计与实现时，需要保留充分的灵活度与可组合性，不能将上述概念耦合在一起。

Platform

游戏客户端的运行平台。

取值如下：

• ios 苹果的 iOS 平台，包含 iPhone、iPad 设备
• android 安卓平台，其中包括华为的鸿蒙、小米的澎湃 OS 等基于安卓的操作系统
• windows 微软的 Windows 桌面平台
• macos 苹果的 macOS 桌面平台
• weixin 腾讯的微信小游戏平台

注意，客户端的运行平台不等于操作系统。例如：

• 微信小游戏运行在 iOS 设备上：运行平台是 weixin，操作系统是 iOS
• iOS 游戏运行在 Apple Silicon 的 Mac 上：运行平台是 iOS，操作系统是 macOS

Bundle ID

游戏客户端的包名，用于标识应用。

Bundle ID 在不同的 Platform 上对应不同的值，语义和 Unity 中的 Application.identifier 相同。

Device ID

游戏客户端运行设备的唯一 ID，用于标识设备。

Device ID 在不同的 Platform 上对应不同的值，语义和 Unity 中的 SystemInfo.deviceUniqueIdentifier 相同。

Device Model

游戏客户端运行设备的型号，用于辅助标识设备。

Device Model 在不同的 Platform 上对应不同的值，语义和 Unity 中的 SystemInfo.deviceModel 相同。

账号与登录

Identity Provider (IdP)

身份提供方，俗称账号系统。

信息

身份提供方举例：

• 世游通行证
• 金山通行证
• 小米账号
• Sign-in with Apple (Apple ID)
• Google Account
• Facebook Login

Sign-in

登录。也称为 Login 或 Log in。

在 Combo SDK 的上下文中，登录行为分为两个步骤：

1. Combo SDK 和 IdP 交互。即用户在游戏客户端选择 IdP 并输入身份信息，验证通过后，Combo SDK 获得 IdP 的身份凭证，例如 id_token, access_token 或 session_token。
2. Combo SDK 和世游 REST API 交互。IdP 的身份凭证被 Combo SDK 发送给世游 REST API，后者在首次验证此身份通过后，会为其分配一个聚合用户标识 Combo ID，并生成 Identity Token。

Combo ID

Combo SDK 聚合了多种 IdP，供游戏侧作为登录方式使用。

游戏客户端通过 Combo SDK 登录后，会获得 IdP 提供的身份凭证，身份凭证经过世游 REST API 验证后，会转化为供游戏侧使用的聚合用户标识，我们称之为 Combo ID。

Combo ID 不会跨游戏。即玩家使用同一个 IdP 下的同一个身份（账号），在多个集成了 Combo SDK 的游戏进行登录，会获得不同的 Combo ID。

Combo ID 是全局唯一的，即在多个游戏之间也是唯一的，保证不会冲突。

游戏侧应当将 Combo ID 当作 string 对待。示例 1231031038970034。

Identity Token

世游 Client REST API 在 sign-in 成功后，为 Combo ID 分配的 JWT，用于游戏服务端验证客户端身份。

Identity Token 是用 Secret Key 签名的，包含了 Combo ID 等身份信息。

游戏服务端可使用 Secret Key 对 Identity Token 做本地验证，无需通过网络请求世游服务端。

内购与支付

Store

业内各类游戏分发平台内的数字、虚拟物品商店。

此类商店都包含一个商品目录（Product Catalog）供开发者对商品进行配置，并都会对接一种或多种支付方式，供用户进行付款。

信息

常用商城举例：

• seayoo 世游游戏商城，聚合了第三方支付平台（微信、支付宝）上的世游商户作为支付方式。用于：
  • Android 官网包
  • Android 官网包的各种换皮包、CPS 包
  • Windows (PC) 官网包
• app_store Apple 的 App Store 应用商店，用于 iOS 平台。
• google_play Google 的 Play 应用商店，用于 Android 平台。

Product

Store 中的虚拟商品。

开发者可在 Store 的开发者后台创建和配置商品。

商品的属性包括商品 ID、支持多语言的商品名称、售价等等。

在购买流程中，最终向 Store 发起购买时，需要指定 Store 中的商品 ID 与购买数量。

Order

内购的订单。

用户的每次内购，都会对应世游侧的一个订单。

订单用于串联购买、支付、发货的完整流程，抽象掉不同的 Distro 使用不同的 Store 购买不同的 Product 的各种细节，提供统一的内购流程。

每个订单有一个唯一的订单 ID，形如 223102645298。

订单的创建，总是由游戏服务端调用世游 Server REST API 来实现。

游戏客户端无法发起创建订单。

Order Token

世游 Server REST API 在订单创建成功后，为订单分配的 JWT，用于用于后续支付流程。

Order Token 是用世游服务端的私钥签名的，在后续支付流程中，世游服务端会对签名进行验证，从而避免客户端伪造或订单请求。

Payment Provider

支付提供方，又称支付平台。

信息

常见的支付平台：

• 微信支付
• 支付宝

Payment Method

Payment Provider 提供的支付方式。

信息

常见的支付方式：

• 微信支付的 App 支付。在移动端从游戏客户端跳转到微信，然后完成支付。
• 微信支付的扫码支付。使用移动端的微信扫描二维码，然后完成支付。
• 支付宝的 App 支付。在移动端从游戏客户端跳转到支付宝，然后完成支付。
• 支付宝的扫码支付。使用移动端的支付宝扫描二维码，然后完成支付。

Transaction

支付完成后，即产生一笔 Transaction（交易）。

每个 Transaction 都会有一个 Transaction ID 对其标识。

Transaction ID 通常都是由实际完成支付的 Store 或 Payment Provider 生成的。

例如，App Store、Google Play、微信支付、支付宝 都会在购买流程中的支付环节完成后，产生对应的 Transaction ID。

Shipping

在支付完成，并验证 Transaction 通过后，世游的服务端会将 Order 标记为已支付状态后，会启动 Shipping（发货）流程。

发货流程是同步 + 异步的：

• Transaction 验证通过后，世游服务端立即同步调用游戏服务端的接口，通知游戏服务端进行发货。
• 如果游戏服务端未能正确地处理，则进入异步流程。世游服务端按照该 重试策略 进行重试通知。

游戏内广告

Ad Token

世游 Client REST API 生成的一个供游戏服务端验证的 JWT。

游戏客户端需要将 Ad Token 传给游戏服务端，游戏服务端对 Ad Token 进行本地验证，从中获取可信的广告展示信息，从而给玩家发放激励广告的奖励。