手册
简介
左侧边栏包含指向相应部分的链接:
- 用户名 - 链接到个人资料。
- 仪表盘 - 以图表和图形的形式查看当前状态。
- 应用程序 - 应用管理。
- 解锁代码 - 自动生成的解锁码或您上传的解锁码。
- 付款 - 用户收款历史。
- 手册 - 当前的用户手册。
仪表盘
您可以为仪表盘中的所有小部件设置通用过滤器:
- 货币 - 仪表盘中用于转换收支金额的货币。
- 期间 - 仪表盘中图表和表格所显示数据的时间范围。它决定了分析和展示有关付款、应用程序及其他参数的信息和统计数据的周期。
余额
此仪表盘部分显示了可用于提现的关键财务指标。它展示了所有用户支付的汇总信息,其中已考虑支付系统及 PayToUse 服务扣除的费用。
此区块中显示以下金额:
- 总额:所选期间内所有用户支付金额的总和,未扣除任何费用。
- 净额:在扣除支付系统和 PayToUse 服务费后,所选期间内所有付款的总金额。
- 待处理:尚未可提现的付款净额。款项在付款完成7天后可提现。
- 可用余额:指目前已可提现至您账户的所有款项的净总额。这是反映您实际可提现余额的主要指标。
测试付款不计入上述四项金额,也不计入下方的付款小部件 - 它们从不涉及真实资金。
提现
在可用余额指示器下方,有一个“提现”按钮。该按钮用于发起将您赚取的资金转出的请求。
点击此按钮后,将弹出一个模态窗口,您需要在其中填写转账的支付信息。
重要提示:系统会自动使用相应字段中显示的全部可用金额进行提现。您无法指定低于可用余额的任意金额。提现总额为所有处于“可提现”状态的款项之和。
在弹出窗口中,您可以选择提现的金额和货币。可用的货币取决于您的支付方式。
注意:如果所选货币不支持指定的提现方式,提现请求将被拒绝。
如需了解提现请求的状态和历史记录的更多详情,请参阅提现部分。
付款
“付款”小部件包含所选期间内按应用程序分组的付款表。
表字段:
- 应用程序 - 应用程序。表格中仅显示在所选期间内有付款的应用程序。
- 付款 - 付款数量。
- 总额 - 所选期间内所有用户付款的总金额,未扣除支付系统和 PayToUse 的费用。
- 净额 - 所选时期内所有付款的总金额减去支付系统和PayToUse的费用。
图表显示了每天净额和总额值的动态。
新用户
新用户图表显示了每天的两个动态值:
- 新用户 - 新的 API 调用数量。只有在向 API 发送请求时传递了 device 参数(唯一设备标识符),才会记录 API 访问。该参数必须对设备真正唯一。 (查看发送请求)
- 付款 - 同期按日支付的数量。
转化
转化率指标用于评估将新用户转化为付款的销售效率。
图表显示了付款与新用户的数量比例,以百分比表示。
应用程序
当您进入此部分时,将打开您的应用程序列表。
应用程序表中的列列表:
- # - 唯一的应用程序标识符。用于验证应用程序代码或显示支付表单时。
- 名称 - 应用程序名称。该名称仅在报告和仪表盘中向您显示。点击应用程序名称可打开应用程序编辑页面。
- 状态 - 应用程序的当前状态,反映设置向导的完成进度。可能是:
- 创建时间 - 应用程序刚刚创建,应用程序 步骤尚未完成。
- 描述 - 描述 步骤尚未完成。
- 价格 - 价格 步骤尚未完成。
- 测试 - 所有设置步骤均已完成,但应用程序尚未启动,可用于测试付款,普通用户无法访问。
- 启动 - 应用程序已启动并接受真实付款。
- 创建时间 - 应用程序创建日期。
- 其他控制按钮:
- 删除 - 从列表中删除应用程序。
创建或编辑应用程序
为了接受付款,您必须依次填写所有必要的应用程序数据并激活应用程序。
创建新应用程序的按钮位于应用程序列表的标题栏中。
应用程序
创建应用程序时可用的字段:
- 名称 - 应用程序的名称,只有您能在报告或仪表盘中看到。该名称将显示在已保存应用程序的页眉中。应用程序保存之前,显示“新应用程序”而不是名称。该字段为必填项。
- 联系邮箱 - 接收发送给用户的邮件副本的电子邮件地址。该地址也会填入“Reply-to”字段,用户回复收到的含代码邮件时将发送到此地址。该字段为必填项。默认填入开发者资料中的邮箱,可更改为其他地址。
- 应用程序类型 - 应用程序类型:
- 单个 - 普通应用程序,拥有自己的付款表单和解锁代码。
- 带密钥的组(仅限一个应用) - 一次购买适用于多个应用程序。用户在组的付款表单上付款一次,代码可以在组内任意一个应用程序中激活。在一个应用程序中激活后,代码在其他应用程序中将不可用。
- 带密钥的组(适用于所有应用) - 一次购买适用于多个应用程序。用户在组的付款表单上付款一次,获得一个可在组内所有应用程序中使用的代码。代码在每个应用程序中分别激活并绑定到设备。代码的期限是共同的:从在组内任意应用程序中首次激活时开始计算。
- 组内应用程序列表 - 适用于组类型。在列表中选择应用程序并点击 添加。组中至少需要添加两个应用程序。列表中只提供您的、会生成解锁代码的单个应用程序。系统会为组内每个应用程序创建组代码的副本,在解锁代码列表中,这些代码显示在组代码下方,状态为 未知。
- 在支付过程中启用反馈 - 向付款表单添加一个字段,供用户输入自由文本。反馈将添加到开发人员的电子邮件副本中。还可以在付款详细信息中看到反馈。
在输入或更改值时,更改会自动保存,没有“保存”按钮。只有在无法保存时才会显示消息。您可以随时返回进行修改。
在页面标题中切换步骤,滚动时标题始终保持在顶部。当前步骤填写完成后,下一步变为可用;打开下一步会保存当前步骤。
描述
从列表中选择一种语言,然后单击“添加”。
将显示一个标签页,其中包含所选语言的本地化应用文本。
可用语言:
- 德语
- 英语
- 法语
- 西班牙语
- 俄语
- 简体中文
描述中的字段用于在付款表单上显示信息,并在向用户的回复消息中显示:
- 本地化名称 - 所选语言的应用程序名称。该名称将显示在支付表单和支付通知邮件中。默认情况下,添加语言时会自动填入应用程序名称。您可以为每种语言设置不同的名称。必填字段。
- 应用程序描述 - 应用程序的简要描述。显示在支付表单的应用程序名称下方。此字段为可选字段。如果您不想显示任何描述,可以留空。
- 购买确认消息 - 支付成功后将通过电子邮件发送给用户的补充信息。该回复内容将添加在电子邮件末尾的标准回复之后。
必须至少添加一种语言才能保存并进入下一页。
付款表单的语言根据用户的浏览器设置自动确定。用选项卡旁的单选按钮(提示 使用默认值)标记其中一种语言:当用户的语言不在已添加的语言中时,将显示该语言的文本。
要删除某种语言,请点击其选项卡上的删除按钮并确认删除。
在输入或更改值时,更改会自动保存,没有“保存”按钮。只有在无法保存时才会显示消息。您可以随时返回进行修改。
在页面标题中切换步骤,滚动时标题始终保持在顶部。当前步骤填写完成后,下一步变为可用;打开下一步会保存当前步骤。
价格
该页面包含与付款相关的价格列表和字段:
- 试用期 - 试用期的长度。
- 时间单位 - 试用期的时间单位。例如,如果您指定为 7 天,则表示在应用程序首次调用 API 后的 7 天内,系统将返回试用期已过期的响应。首次设备调用的时间会被保存下来。
- 价格计算方法 - 从列表中选择价格计算方式:
- 根据期限计算价格 - 在支付表单中,用户指定代码的有效期,系统将根据下表自动计算价格。用户将在回复邮件中收到自动生成的解锁码。
- 根据价格计算期限 - 在支付表单中,用户从列表中选择一个价格或自行输入价格,系统将根据下表自动计算出相应期限。用户将在回复邮件中收到自动生成的代码。
- 永久代码 - 在支付表单中,用户可从列表中选择一个价格,或自行输入价格。支付完成后,用户将在回复邮件中收到一个代码,该代码来自下方的列表,且与所选价格相对应。
- 捐赠 - 在支付表单中,用户可从列表中选择价格,或自行输入价格。对于捐赠类应用,系统不会生成解锁码。
- 临时代码,价格取决于期限 和 临时代码,期限取决于价格 - 应用程序从 API 获取设备的临时代码,并与指向付款表单的二维码一起显示给用户。用户为此代码付款:与上述方式相同,价格取决于所选期限,或期限取决于支付的价格。付款后,代码仅对该设备激活。此类代码无法重置,也无法转移到其他设备。
组应用程序仅可使用 根据期限计算价格 和 根据价格计算期限 方式。捐赠 方式不使用试用期。
价格表 表设置价格档位。使用 添加 按钮添加一行,使用 删除 按钮删除。表中的列取决于价格计算方式:
- 期限, 价格 - 代码期限(数字和时间单位:天、月、年或永久)及其价格。
- 价格, 代码 - 适用于 永久代码 方式:价格以及用户付款后获得的代码(最多 12 个字符)。
- 价格 - 适用于 捐赠 方式:仅建议金额。
用单选按钮(提示 使用默认值)标记的行会在付款表单上预先选中。
价格以美元为单位。最低价格为1美元。
在输入或更改值时,更改会自动保存,没有“保存”按钮。只有在无法保存时才会显示消息。您可以随时返回进行修改。
在页面标题中切换步骤,滚动时标题始终保持在顶部。当前步骤填写完成后,下一步变为可用;打开下一步会保存当前步骤。
预览
此页面设置以下值:
- 代码长度 - 生成的代码的长度(如果适用)。
- 代码字符集 - 产生代码的字符集:
- 数字代码 - 仅使用数字 0、1、2、3、4、5、6、7、8、9 生成代码。代码中可能包含前导零。验证代码时,前导零是重要的。
- 字母数字代码 - 使用字符 1、2、3、4、5、6、7、8、9、A、B、C、D、E、F、G、H、I、G、K、L、M、N、P、Q、R、S、T、U、V、X、Y、Z 生成代码。代码使用大写字符生成并发送给用户。验证代码时,字符的大小写不重要。
- 允许代码以零开头 - 允许生成的代码带有前导零。仅当字符集为数字代码时可用。
- 允许按设备 ID 重新发送代码 - 通过重复设备标识符检查,允许将代码重新发送到同一邮箱。仅适用于单一应用程序。
- 表盘设计器 - 此应用是在设计器中制作的表盘:此步骤显示设计器,而不是付款链接和代码示例。从首页创建的表盘会默认开启。
- 发布日期 - 应用程序对普通用户开放的日期。与发布后对测试人员免费一起,定义了在此日期之前联系应用程序的设备可享受的免费期限。
- 发布后对测试人员免费 - 授予首次API调用发生在时间单位之前的设备的免费期限长度(以所选发布日期为单位)。为这类设备创建的代码将获得未知状态。
- 检查代码的链接 - 用于代码验证的示例链接。
- 支付链接 - 付款链接。您可以复制该链接并粘贴到应用发布网站上的应用描述中。系统会为每个域名(https://pay-to-use.com适用于所有语言,https://pay-to-use.ru仅适用于俄语)生成单独的链接和二维码,可在链接字段上方的选项卡中查看。 需要传递的参数:
- app - 应用程序的唯一标识符。必填参数。
- amount - 购买时将在价格栏中指定的金额。默认价格会被忽略。但是,该金额不能低于最低价格,也不能低于为应用程序设置的最低价格。可选参数。
支付链接链接只有在应用程序启动后才会公开可用。在此之前,请使用下方的测试付款按钮,通过签名的临时访问令牌打开付款表单 - 表单和付款方式与真实付款相同,但不会实际扣款:付款会直接以测试状态创建,并会立即生成一个完全可用的代码(如适用)并通过电子邮件发送,无需经过支付系统。测试付款会显示在付款列表中,标记为测试状态,但不计入余额的汇总金额。
测试付款按钮会打开一个下拉菜单,用于选择打开测试付款表单的域名(https://pay-to-use.com或https://pay-to-use.ru)- 两者功能相同,只有在需要测试特定语言环境的行为时,选择才有意义。
要开始接受真实付款,请关闭 测试模式。在此之前,请确认所有输入的数据都正确。应用程序生成的密钥无法更改。测试模式开启时,应用程序名称旁会显示 测试 徽章。重新开启 测试模式(需确认)会停止接受真实付款,并再次提供 测试付款 按钮。
代码验证
检查应用程序的解锁代码分3个步骤进行:
- 编写并发送用于代码验证的请求
- API端的检查
- 接收并处理 API 响应
发送请求
要验证代码,您的应用程序用户必须在应用程序设置中的字段中输入它。
<properties>
<property id="UnlockCode" type="string"></property>
<property id="UnlockResult" type="string">Checking...</property>
...
<properties>
<settings>
<setting propertyKey="@Properties.UnlockCode" title="@Strings.UnlockCode">
<settingConfig type="alphaNumeric" maxLength="12"/>
</setting>
<setting propertyKey="@Properties.UnlockResult" title="@Strings.UnlockResult">
<settingConfig type="alphaNumeric" readonly="true"/>
</setting>
...
</settings>
然后,您需要向 Pay-to-use API 服务器发送请求:
function onTemporalEvent() as Void {
var ds = System.getDeviceSettings();
return Toybox.Communications.makeWebRequest(
"https://api.pay-to-use.com", // API URL
{
"device" => ds.uniqueIdentifier, // 设备唯一标识符
"app" => "6", // 您的应用程序 ID
"model" => ds.partNumber, // 设备部件号
"code" => Application.Properties.getValue("UnlockCode") // 您的应用程序中的解锁代码值
},
{
:method => Communications.HTTP_REQUEST_METHOD_POST,
:headers => { "Content-Type" => Communications.REQUEST_CONTENT_TYPE_JSON },
:responseType => Communications.HTTP_RESPONSE_CONTENT_TYPE_JSON
},
method(:onReceive)
);
}
API 请求参数:
- url - https://api.pay-to-use.com。必须使用HTTPS。
- 请求的正文(传递的值)。键值对字典:
- device - 设备的唯一标识符。
- app - 您的应用程序的唯一标识符。
- model - 设备型号标识符。可选参数。该数据用于显示新设备的统计信息。
- code - 用户在您的应用程序设置中输入的解锁代码。
- 请求选项:
- :method - API 支持 GET 和 POST 请求方法。
- :headers - 对于 POST 方法,参数需要以 JSON 格式传递。
- :responseType - 响应以 JSON 格式返回。
- responseCallback - 回调方法的引用,该方法应接受两个参数:
- responseCode - 服务器响应头代码。
- data - 如果请求成功,则为内容,否则为 null。
API端的检查
如果没有向 API 传递参数,则 API 返回 HTTP/1.1 404 Not Found 头。
如果至少向 API 传递了一个参数,则 API 返回头 HTTP/1.1 200 OK。
服务器响应包括:
- response - 响应代码
- msg - 响应的文本描述
- expires - UNIXTIME 时间戳(如果适用)
进行检查以确保传入的应用程序标识符是正确的。 支付时应用程序必须处于 已发布 状态。 如果出错,将返回响应代码 301。
如果传输了唯一设备标识符,则会搜索并存储该设备标识符。 如果在检查或保存时出现错误,则返回错误代码 402。 如果出现此类返回代码,请立即发送邮件至 [email protected] 联系技术支持
如果代码通过,那么对于 根据期限计算价格 和 根据价格计算期限 计算方法的应用程序,将执行以下步骤:
- 如果传输的是空代码,它将与前面步骤中确定的唯一设备标识符解除绑定。
- 如果传送了一个非空的代码,而它没有被激活,那么该代码的激活取决于购买该代码时指定的价格条件,与激活的日期无关。
- 如果未传输代码或传输的代码未找到,则返回错误代码 201。
- 已激活的代码与设备进行检查,如果在激活期间传输了与存储的唯一设备标识符不同的唯一设备标识符,则返回错误代码 202。
- 如果传输的代码没有到期日期并且所有先前的检查都已通过,则返回代码 101。
- 如果代码是有时间限制的,则执行检查。如果密钥未过期,则返回代码 101。如果代码已过期,则返回错误代码 203。
- 此类应用程序要求代码绑定到设备。如果未传输唯一设备标识符,则返回错误代码 304。
对于 永久代码 的应用,仅检查购买时代码是否存在。 如果找到代码,则返回代码 101。如果找不到代码,则返回错误代码 201。
对于使用捐赠计算方法的应用程序,代码不被检查。 始终返回代码 101。
如果传送的代码为空,且应用程序已填写 发布日期 字段,则检查测试版测试者期限:如果设备首次访问 API 的时间早于发布日期,且 发布后对测试人员免费 期限尚未结束,则返回代码 103。
如果启用了 允许按设备 ID 重新发送代码 选项且未传送代码,则查找已绑定到该设备的有效代码。如果找到,则返回代码 101 以及该代码本身。
如果前面的检查没有通过,则检查试用期。 如果自设备首次访问以来经过的时间超过当前应用程序设置的试用期,则返回错误代码 204。 如果试用期尚未到期,则返回错误代码 102。
如果仅传输应用程序 ID,而没有传输解锁代码或唯一设备 ID,则返回错误代码 303。
如果返回 500,请发送邮件至 [email protected] 联系技术支持
以下是所有返回的代码表:
| 代码 | 消息 |
|---|---|
| 101 |
根据期限计算价格 和 根据价格计算期限 计算方法:
|
| |
永久代码:
| |
捐赠:
| |
| 102 | |
| 103 | |
| 201 | |
| 202 | |
| 203 | |
| 204 | |
| 301 | |
| 302 | |
| 303 | |
| 304 | |
| 401 | |
| 402 | |
| 500 | |
检查响应
然后您应该检查 Pay-to-use API 服务器的响应:
function onReceive(responseHeader, data) as Void {
if (responseHeader == 200) { Toybox.Background.exit(data); }
}
您可以检查所有响应头和代码,也可以为方便用户显示自己的消息,但最简单的验证大致如下:
function onBackgroundData(data) as Void {
if (data.hasKey("response")) {
if (data.hasKey("msg")) {
// 您可以在属性字段中使用名称“UnlockResult”显示data["msg"]。
Application.Properties.setValue("UnlockResult", data["msg"]);
}
if (data["response"].toString().substring(0, 1).equals("2")) {
// 代码验证失败
// 付费功能不可用
...
} else {
// 代码检查成功,或者错误出在您或 API 一方
// 付费功能可用
...
}
}
}解锁代码
当您进入此部分时,将打开一个解锁代码列表。
解锁代码列表
您可以在顶部搜索栏中搜索电子邮件字段或代码。找到的代码将显示在列表中。您可以使用电子邮件或代码的全部或部分作为搜索标准。匹配项将以颜色突出显示。搜索和过滤器同时工作,彼此不排斥。
用户的最后使用的过滤器会被保存。也就是说,下次进入页面时,最后使用的过滤器将自动应用。解锁代码列表提供以下过滤器:
- 列 - 选择在解锁代码列表中显示的表列。
- 应用程序 - 仅显示所选应用程序的解锁代码。
- 状态 - 仅显示处于所选状态的解锁码。
解锁代码表中的列列表:
- 应用程序 - 您的应用程序。可通过链接编辑其设置。
- 代码 - 解锁代码。
- 电子邮件 - 与解锁码注册关联的电子邮件地址。该地址用于在网站的我的购买记录部分搜索客户解锁码。该部分对用户开放。
- 期限 - 已发送代码的有效期(在应用程序设置中指定)。该代码的有效期是根据生成时应用程序设置中的条件设定的。
- 状态 - 解锁代码状态。 (查看解锁代码状态)
- 创建时间 - 解锁代码创建日期。
- 语言 - 用户的语言,用于包含代码的邮件。
- 激活时间 - 代码的激活日期。该日期设定为该特定用户设备首次连接 PayToUse API 服务并提交此代码的时刻。此时,代码的状态将变为 已激活。只有未激活的代码才能被激活。如果由 ID 不同的设备提交已激活的代码,API 将返回错误代码 202。每个代码仅能与一台设备绑定。
- 到期时间 - 代码激活到期日期。对于在代码激活时具有有限有效期的代码进行设置。对于没有限制有效期的代码,到期日期保持为空白。
- 已删除 - 代码删除日期。删除后,代码状态设置为未知。
- 设备 - 代码所绑定设备的唯一标识符。
- 设备首次访问 - 设备首次调用 API 的日期。试用期和测试版测试者期限从此日期开始计算。
- 设备最后访问 - 设备最后一次调用 API 的日期。可用于检查应用程序是否仍在使用。
- 支付编号 - 该笔付款的唯一序列号。您可以点击链接查看付款详情。
- 备注 - 手动创建代码时输入的备注。
- 用于执行解锁代码相关操作的按钮。例如,删除。
解锁代码状态
在生命周期内,解锁码会经历不同的状态,这些状态可通过代码状态进行追踪。
| 状态 | 描述 |
|---|---|
| 可用 | 该状态分配给尚未执行任何操作的解锁代码,或已重置设备绑定的代码。 |
| 已激活 | 该状态适用于设置了激活日期的代码。当设备首次成功访问PayToUse API服务时,激活日期将被设置。此外,激活代码时还会设置代码的过期日期。 |
| 已过期 | 该状态适用于已过期的代码。解除代码与设备的关联不会重置代码的过期日期。使用此状态检查代码将返回错误203。 (查看API端的检查) |
| 未知 | 当代码被删除时,将设置该状态。使用此状态检查代码将返回错误201。 (查看API端的检查) |
| 未知 | 此状态适用于为设备创建的代码,该设备的首次API调用发生在应用程序的发布日期之前 - 会根据发布后对测试人员免费的配置,为其授予免费期限,而不是通常的试用期或付费激活。 |
| 未知 | 此状态适用于由多个分组应用程序共享的代码。它不与单个应用程序绑定,也不会出现在组内各个应用程序的代码列表中。 |
| 未知 | 与 未知 相同,但代码已不可用:代码已被删除,或者对于仅限一个应用程序的组,代码已在组内某个应用程序中激活。删除组代码时,其在组内所有应用程序中的副本也会被删除。 |
| 未知 | 当组内某个应用程序的代码被单独删除、而该组代码本身仍然保留时,会设置此状态。 |
代码详情
点击列表中的代码会打开代码详情页面。该页面显示与列表相同的字段,以及对代码进行操作的按钮:
- 重置 - 解除代码与设备的绑定并重置激活日期。代码状态变为 可用,代码可以在另一台设备上激活,例如在用户更换设备时。已激活代码的到期日期不会被重置。对于使用临时代码的应用程序,此按钮不可用,因为此类代码只能在一台设备上使用。
- 激活 - 适用于尚未付款的临时代码。输入用户的电子邮件和代码期限:代码将为其绑定的设备激活,就像已付款一样。例如,可用于免费向用户提供应用程序。
- 发送代码 - 将包含代码及其详情的邮件发送到代码的电子邮件地址。选择 消息语言。如果勾选了 将副本发送给开发者,邮件副本将发送到应用程序的联系邮箱。适用于用户丢失了包含代码的邮件的情况。
- 更改电子邮件 - 更改代码的电子邮件。对于组代码,会同时更改组代码及其所有副本的电子邮件。如果代码是通过付款获得的,付款的电子邮件也会更改。之后,用户可以在 我的购买记录 部分通过新的电子邮件找到代码。
- 删除 - 删除代码。代码状态变为 未知,验证代码时返回错误 201。未付款的临时代码会被完全删除。
如果已为付款发送代码,也可以在付款详情页面对代码进行操作。
创建
解锁代码列表标题栏中的 创建 按钮会打开无需付款即可创建代码的表单。例如,用于测试版测试者、评测者或通过其他方式付款的用户。表单字段:
- 电子邮件 - 接收所创建代码的地址。邮件副本将发送到应用程序的联系邮箱。
- 应用程序 - 为其创建代码的应用程序。仅提供状态为 测试 和 启动、价格计算方式为 根据期限计算价格 或 根据价格计算期限 的应用程序。
- 期限 和 时间单位 - 代码的有效期。从代码在设备上激活时开始计算。
- 数量 - 要创建的代码数量。
- 备注 - 与代码一起保存的任意文本。显示在列表的 备注 列中。
- 在电子邮件中添加备注 - 将备注添加到包含代码的邮件中。
代码根据应用程序的代码设置(长度和字符集)生成。保存后,将显示已创建代码的列表并发送邮件。
上传
上传 按钮用于导入在 PayToUse 之外发放的代码,例如从其他许可系统迁移时。请选择应用程序、文件和文件参数:
- 文件格式 - CSV,编码 UTF-8。最大文件大小显示在上传表单中。
- 包含标题 - 如果文件第一行包含列名,请勾选。此时将跳过第一行。
- 分隔符 - 分号、逗号或制表符。
文件的列,按以下顺序:
- 代码 - 解锁代码,必填。将转换为大写并截断为 12 个字符。应用程序中已存在的代码将被跳过。
- 电子邮件 - 用户的电子邮件。
- 创建时间 - 创建日期:日期或 UNIXTIME 时间戳。如果为空,则使用上传日期。
- 到期时间 - 到期日期:日期或 UNIXTIME 时间戳。如果代码尚未激活或没有到期日期,请留空。
- 期限 - 激活后的有效期:数字和单位,例如 12h、30d、6m 或 1y。如果为空,代码永久有效。
上传后将显示已导入行的表格。未导入的行以红色突出显示,并有消息显示总数中有多少行已插入。上传时不会向用户发送邮件。
下载
下载 按钮将解锁代码列表下载为 CSV 文件。在表单中选择要包含在文件中的字段。文件包含所有符合当前筛选条件和搜索的代码,而不仅仅是当前页面的代码。所选字段会被记住,供下次下载使用。
付款
当您进入此部分时,将打开用户付款列表。
以下支付系统用于接收付款:
支付系统费用之后,PayToUse将收取13%的费用。我们一直在努力降低费用。
如果在支付系统中出现任何争议或退款,支付系统的罚款将转嫁给开发者。因此,应避免此类情况发生。在争议情况下,不收取 PayToUse 费用。
付款列表
您可以在顶部搜索栏中搜索电子邮件字段或发送的代码。找到的付款将显示在列表中。您可以将电子邮件或发送的代码的全部或部分用作搜索标准。匹配项将以颜色高亮显示。搜索和过滤器同时工作,彼此不互斥。
最后使用的过滤器将保存给用户。也就是说,下次您进入页面时,将自动应用上次使用的过滤器。对付款列表可用的过滤器有:
- 列 - 选择要在付款列表中显示的表列。
- 期间 - 仅显示在所选日期范围内创建的付款。
- 应用程序 - 仅显示所选应用程序的付款记录。
- 系统 - 仅显示来自所选支付系统的付款。
- 状态 - 仅显示具有所选状态的付款。
付款表中的列列表:
- 应用程序 - 您的应用程序。可通过链接编辑其设置。
- # - 付款的唯一序列号。当用户从付款表单转到支付系统的付款页面时自动分配。您可以点击链接查看付款详情。
- 备注 - 用户在付款表单中输入的消息。
- 系统 - 用户选择的支付系统。
- 状态 - 付款状态。 (查看付款状态)
- 电子邮件 - 用户在付款表单中填写的电子邮件地址。
- 期限 - 发送代码的有效期限(在应用程序设置中指定)。
- 语言 - 用户选择的付款表单语言。
- 创建时间 - 付款创建日期。
- 发票金额 - 向用户收取的付款金额。根据应用程序的设置,在支付表格中指定。
- 付款日期 - 付款日期。
- 付款金额 - 由支付系统确认的支付金额。
- 发送的代码 - 发送给用户的代码。
- 可用金额 - 可提现金额。
- 提现金额 - 该付款已提现的金额。
付款详情
点击列表中付款记录的#即可打开其详情页面。
除了上面列出的字段外,详情页面还会显示:
- 代码 - 买家在付款表单中输入的代码,尚未经过验证和激活。仅在应用程序使用与设备绑定的临时代码时显示。
- 付款金额(总额) - 支付系统确认的金额,未扣除支付系统和PayToUse的手续费。
- 付款金额(净额) - 支付系统确认的金额,已扣除支付系统和PayToUse的手续费。
-
付款标识符 - 由支付系统分配的标识符,用于在需要时在该系统中查找此付款。显示的字段取决于所使用的支付系统:
- Stripe: Payment Intent、收据号码、卡号末四位。
- PayPal: 付款 ID、付款人 ID、交易 ID。
- Robokassa: 付款 ID、ID1、ID2。
如果已为付款发送代码,付款详情页面上将提供 重置代码、发送代码 和 更改电子邮件 按钮。它们的作用与代码详情页面上的相同。 (查看代码详情)
付款状态
在整个生命周期中,款项会流经不同的状态,这些状态可通过付款状态进行追踪。
| 状态 | 描述 |
|---|---|
| 不完整 | 该状态分配给尚未执行任何操作的付款。用户从付款表单转到支付系统表单时即创建付款,并分配唯一序列号以及基本属性:金额、支付系统、日期。 |
| 成功 | 该状态分配给从支付系统接收到正面响应的支付。下一步是向用户发送包含生成的代码或其他数据的电子邮件,具体取决于应用程序的设置。如果支付保留在此状态,则需要特别注意,因为尚未执行后续操作。 |
| 错误 | 该状态分配给从支付系统接收到负面答复的支付。不会执行后续步骤。需要特别注意此类支付,因为支付系统一侧的状态可能会延迟处理。 |
| 待处理 | 该状态分配给从支付系统收到肯定答复、且所有后续步骤均已成功完成的付款。此状态的付款不可提现。7 天后付款将自动转入下一个状态。 |
| 可用 | 该状态的支付可提现。 |
| 发送中 | 此状态用于下一次提现中包含的支付。如果提现被取消或拒绝,支付状态将返回可用状态。 |
| 已发送 | 此状态用于已进行提现的支付。等待确认收款。 |
| 已完成 | 此状态用于成功提现的支付。您可以通过在相应部分确认提现来手动设置状态。支付提现后14天状态也会自动更改。 |
| 已退款 | 已发出退款的支付转移到此状态。发出退款时会收取退款费用。该费用将从提现金额中扣除。 |
| 退款已关闭 | 已包含在已发送提现中的退款。由于已提现金额无法再减少,退款手续费将改为从开发者余额中扣除。 |
| 争议 | 买家已通过支付系统对该付款提出异议(拒付)。结果尚待处理。 |
| 争议已关闭 | 争议已解决。与退款一样,支付系统收取的任何争议手续费都会转嫁给开发者。 |
| 已取消 | 该付款在完成前已被取消。 |
| 未知 | 在将付款记录与支付系统报告进行核对时,如果其状态文本与上述任何已知状态都不匹配,则分配此状态。需要人工审核。 |
| 测试 | 在应用程序启动之前,处于测试模式状态时,通过其测试发起的测试付款。金额及生成的代码都是真实的,但不会实际扣款,且该付款不计入仪表盘的汇总金额。 |
下载
付款列表标题栏中的 下载 按钮将列表下载为 Excel 文件(XLSX)。文件按相同顺序包含 列 筛选器中所选的列,并包含所有符合当前筛选条件和搜索的付款,而不仅仅是当前页面的付款。
提现
当您进入此部分时,将打开您的提现列表。
提现
“提现”按钮用于发起将您赚取的资金转出的请求。
点击此按钮后,将弹出一个模态窗口,您需要在其中填写转账的支付信息。
重要提示:系统会自动使用相应字段中显示的全部可用金额进行提现。您无法指定低于可用余额的任意金额。提现总额为所有处于“可提现”状态的款项之和。
在弹出窗口中,您可以选择提现的金额和货币。可用的货币取决于您的支付方式。
注意:如果所选货币不支持指定的提现方式,提现请求将被拒绝。
提现列表
用户的上次使用的过滤器将被存储。也就是说,下次进入页面时,将自动应用上次使用的过滤器。提现列表可用的过滤器包括:
- 列 - 在提现列表中仅显示选定的列。
- 状态 - 只显示处于选定状态的提现。
提现表中的列列表:
- # - 提现的唯一序列号。它是在提现保存时自动分配给提现的。您可以点击该链接查看提现的详细信息。
- 状态 - 提现状态。 (查看提现状态)
- 创建时间 - 提现请求的日期。
- 金额 - 提现金额。
- 提现 - 提现发送的日期。
- 用于提现操作的按钮。例如,确认。
您可以在提现处于已发送状态时确认提现。
提现详情
点击列表中提现的 # 会打开其详情页面。除列表中的字段外,页面还显示 详情 - 提现申请中指定的、资金将转入的付款信息。
下方是该提现所包含的付款列表。与付款列表一样,可以使用 列、应用程序、系统 和 状态 筛选器。 (查看付款列表)
提现状态
在其生命周期中,提现会进入不同的状态,这可以通过提现状态来追踪。
| 状态 | 描述 |
|---|---|
| 待处理 | 提现创建时、尚未执行任何操作时分配此状态。 |
| 已取消 | 此状态分配给已取消的提现。提现可能因多种原因而取消。例如,未指定资金接收方式。此提现的所有款项都会进入 可用 状态,可再次提现。 |
| 已发送 | 提现资金发出时设置此状态。 |
| 已完成 | 开发者确认收到手动提现款项时设置此状态,或在发送 14 天后自动设置。 |
| 已拒绝 | 当银行或支付系统在发出后退回资金时,为提现设置此状态。此提现的所有款项都会进入 可用 状态,并可再次提现。 |
表盘设计器
设计器无需编程即可为您的应用创建 Garmin Connect IQ 表盘。您在每个手表型号的屏幕上放置元素,选择它们显示的内容以及哪些收费,然后下载成品文件:用于安装到自己手表上测试的 .prg,或用于在 Connect IQ Store 发布的 .iq。
完成的表盘会根据应用的付款方式,自行通过 PayToUse 检查付款。无需编写任何代码。
在应用页面上,点击应用名称旁边的火箭按钮即可打开设计器。
Connect IQ 开发者密钥
每个 .prg 和 .iq 文件都使用开发者密钥(4096 位 RSA 私钥)签名。它在个人资料中设置一次,并用于开发者的所有表盘。
- 如果您已在 Connect IQ Store 中有应用,请上传用于签名这些应用的密钥:由 Connect IQ SDK 创建的 developer_key 文件(例如在 Visual Studio Code 中使用 "Monkey C: Generate a Developer Key" 命令)。已在商店发布的应用只能用同一密钥更新。
- 如果您还没有密钥,请使用 “生成新密钥” 按钮生成。这样的密钥可用于将表盘安装到您的手表以及商店中的新应用,但无法用它更新已使用其他密钥发布的应用。
- 请下载密钥并将副本保存在安全的地方。如果密钥丢失,使用它发布的应用将无法再在商店中更新。
- 接受 DER 或 PEM 格式的文件。密钥不得受密码保护。
重要:更换密钥会影响开发者的所有表盘。之前的密钥会保存在服务器上,但新的构建将使用新密钥签名。
手表型号
设计器中可用的型号列表由管理员在手表型号页面设置:支持 Connect IQ 4 及更高版本的圆形和矩形型号。在设计器中,用型号按钮选择表盘的型号。
每个型号都有自己的布局:元素的位置、大小和字体单独设置,而元素列表、功能和付款设置对所有型号通用。新添加的型号会获得当前型号的布局,并按其屏幕缩放。
- 手表 / 屏幕 - 在手表图片上显示屏幕,或仅显示屏幕。
- 实际尺寸 - 按实际尺寸显示手表。
- 常亮显示 - AMOLED 屏幕常亮模式预览。
元素列表
表盘由四种类型的元素组成:
- 文本 - 显示功能的值:时间、日期、步数、心率、天气等。
- 静态文本 - 您自己输入的文本。
- 指针 - 模拟时针、分针和秒针。
- 图像 - 图片:背景或位于其他元素之上的图层。
元素按元素列表选项卡中的顺序绘制:第一个为最底层。可通过列表中的箭头以及置于底层和置于顶层按钮更改顺序。
可用鼠标或键盘方向键移动元素(1 px,按住 Shift 为 10 px)。Ctrl+D 复制元素,Ctrl+C / Ctrl+V 将其位置复制到其他型号,Delete 删除。复制到所有型号按钮将元素位置应用到所有选定型号。 全部复制到所有型号按钮会用当前型号的布局替换所有其他型号的布局:所有元素和背景,并按各屏幕缩放。
功能和付款
文本元素可以有多个功能。其中一个默认显示;如果启用了用户可在设置中选择功能,手表用户可在 Garmin Connect 的表盘设置中选择功能。
每个元素的每个功能都可以标记为收费:同一功能可以在一个元素中免费、在另一个元素中收费。功能选项卡在一个表格中显示所有使用的功能和元素。
带星号的功能需要额外权限(传感器历史、用户资料或位置),商店会在安装表盘时显示。仅当表盘使用此类功能时才会添加该权限。日出、日落以及昼/夜图标需要位置:手表最近的 GPS 位置(任何使用 GPS 的活动都会更新),否则使用天气预报的地点。
未付款时,表盘根据应用的付款方式表现如下:
| 付款方式 | 未付款时 |
|---|---|
| 根据期限计算价格, 根据价格计算期限, 永久代码 | 收费功能显示“paid”,收费图像会被隐藏。解锁码在表盘设置中输入;购买页面的二维码位于手表的设置菜单中。 |
| 临时代码,价格取决于期限, 临时代码,期限取决于价格 | 如果表盘使用收费功能,会显示锁定屏幕,其中包含手表代码和付款页面的二维码。 |
| 捐赠 | 不检查付款,收费标记将被忽略。 |
在触摸屏上,轻触锁定的表盘可试用所有功能 15 分钟。
图标
文本元素可以在功能值旁边显示图标。图标属于整个表盘中的功能:可以在元素功能表的图标列或功能选项卡中更改,更改会应用到所有使用该功能的元素。
- 来自词典(默认)- 管理员在图标词典中为该功能设置的图标。
- 无图标 - 该功能不显示图标。
- 单个图标 - 公共图标库或您自己的图标中的任意图标。
- 图标组 - 图标取决于功能的值:使用第一个“至”值不小于该值的行,最后一行用于所有更大的值。启用“白天 / 夜晚”时,每行都有自己的夜间图标,在日落到日出之间使用。
图标组的值:电池 - 电量 %,闹钟 - 数量,手机连接和勿扰 - 1 或 0,月亮 - 月龄(天),风 - 方向(度),天气 - 状况代码;其他功能 - 不带单位的数值。充电时,电池图标会轮流显示。
元素的显示设置可选择文本和图标、仅文本或仅图标。图标相对于文本的位置、大小、颜色、间距和偏移在每个型号的布局中设置。 元素的对齐方式作用于整个区块:文本、间距和图标一起。
您自己的图标在表盘选项卡的表盘图标部分添加:SVG 文件(可一次多个)或 TTF 字体,字体的每个字符都会成为一个图标。SVG 要求:
- 图标为单色:文件中的颜色会被忽略,图标使用设计器中选择的颜色绘制;
- 只使用填充形状;无填充的线条(stroke)需要在矢量编辑器中转换为形状(例如 Inkscape 的“描边转路径”或 Figma 和 Illustrator 的“Outline Stroke”);
- 孔洞必须是真正的镂空(复合路径或 evenodd 填充规则):黑色形状上的白色形状会变成填充区域;
- 图标大小为文件的 viewBox;不支持渐变、蒙版、文本和 CSS 类。
构建表盘时,图标会在手表上转换为所需大小的位图。
字体和图像
- 手表的系统字体适用于每个型号。数字字体只包含数字和少量符号。
- 您自己的 TTF 或 OTF 字体在表盘选项卡上传,并按每个型号和大小转换为位图。每个型号最多可以有 12 种不同大小的自有字体和图标。
- 图像(不超过 2000×2000 的 PNG、JPEG、GIF、WebP)在同一选项卡上传。图像可以填满任意型号的屏幕,也可以有自己的尺寸;它会按每个型号缩放,并保留透明度。每个型号最多 8 种不同的图像或尺寸。
- 图像会占用手表的图形内存;设计器会显示当前型号的使用量。
常亮模式
在 AMOLED 屏幕的常亮模式下,表盘只显示勾选了在常亮模式下显示的元素,背景为黑色,并且每分钟轻微移动以保护屏幕。Garmin 规定此模式下点亮的像素不得超过 10%;设计器会在屏幕上方显示该值。此模式下不显示秒和秒针。
构建
- 为此手表构建 (.prg) - 当前型号的文件,用于安装到您的手表上。
- 为 Connect IQ Store 构建 (.iq) - 所有选定型号的软件包,用于在 Connect IQ Store 发布。每次构建 .iq 都会获得新的版本号。
构建会加入队列,通常需要约一分钟。构建选项卡显示状态、下载链接和构建日志。
表盘选项卡上的应用 UUID用于在商店中识别应用。请勿在版本之间更改。要更新已发布的应用,请输入其 UUID。
在手表上安装 .prg 文件
用 USB 数据线将手表连接到电脑,并将 .prg 文件复制到手表的 GARMIN/Apps 文件夹。断开数据线后,表盘会出现在手表的表盘列表中。
- Windows:手表会在文件资源管理器中显示为设备(例如 "fēnix 7")。打开 Internal Storage → GARMIN → Apps 并将文件复制到其中。
- macOS:大多数新款手表通过 MTP 连接,而 macOS 在没有额外软件的情况下不支持 MTP。安装 OpenMTP(免费),连接手表,打开 GARMIN/Apps 并将文件复制到其中。请先关闭 Garmin Express,否则它会占用连接。
- Linux:手表会在文件管理器(GNOME Files、Dolphin)中显示为 MTP 设备;打开 GARMIN/Apps 并将文件复制到其中。没有图形环境时,可以用 jmtpfs 或 simple-mtpfs 挂载手表。
要删除表盘,请从 GARMIN/Apps 中删除文件,或在手表上删除。
注意:以这种方式安装的表盘无法在 Garmin Connect 应用中更改设置,它使用默认设置。要测试设置,请将表盘作为测试版应用在商店发布。
在 Connect IQ Store 发布
设计器不会将文件上传到商店。请登录 Connect IQ 开发者面板(apps.garmin.com/developer),创建 "watch face" 类型的应用,上传 .iq 文件,添加说明和截图,然后提交审核。
要更新应用,请构建新的 .iq 文件(其版本会自动增加),并将其作为同一应用的新版本上传。UUID 和开发者密钥必须保持不变。
API
概述
PayToUse API 具有以下功能:
- 检查解锁码的激活状态,并在必要时进行激活。
- 从 NightScout 应用中获取血糖数据。
- 获取指定位置的当前天气数据。
所有信息均可通过单次请求进行获取和返回。
API 端点
您可以使用以下任一端点:
- https://api.pay-to-use.com
- https://api.p2u.io
这两个端点都支持GET和POST请求。
请求参数
- device: 字符串 (必填) — 唯一设备标识符
- app: 整数 (必填) — 您的应用程序 ID
- model: 字符串 (可选) — 设备型号代码,用于收集和显示使用该应用的设备的统计数据
- code: 字符串 (可选) — 解锁码
- bg: 关联数组 (可选) — 用于从 NightScout 应用中获取血糖水平的数据
- url: 字符串 (可选) — NightScout 应用的地址
- weather: 关联数组 (可选) — 用于查询当前天气的数据
- appid: 字符串 (可选) — 天气 API 访问密钥
- lat: 浮点数 (可选) — 纬度
- lon: 浮点数 (可选) — 经度
- provider: 整数 (可选) — 天气服务提供商
支持的天气服务提供商列表
1. OpenWeatherMap
- 描述: OpenWeatherMap 提供全球天气数据,包括实时天气、历史数据以及 16 天预报。凭借广泛的地理覆盖范围和频繁的更新,OpenWeatherMap 已成为需要获取当前天气和长期预报的应用程序的热门选择。
- 提供的数据: 实时温度、湿度、风速、空气质量、降水概率等信息。提供当前及预报数据,包括部分地区的逐分钟天气数据。
- 服务提供商选择: 请在请求的 weather 部分添加 provider = 1,以选择 OpenWeatherMap 作为天气服务提供商。
- 使用说明: 提供免费和付费两种服务等级,用户可通过 API 密钥认证访问数据。付费套餐包含高级数据层和增值功能。
- One Call API 3.0: 紫外线指数仅在密钥订阅了 One Call API 3.0(OpenWeatherMap 账户中的单独订阅)时可用。使用此类密钥时,一次 One Call 请求即可替代单独的实时天气和预报请求。如果 One Call 拒绝该密钥,则使用免费的 2.5 API,并在一天后重新尝试 One Call。
- API文档: 点击此处查看。
2. QWeather
- 描述: QWeather(又名 HeWeather)提供以中国为重点的全面天气数据,同时也包含国际数据。该服务提供丰富的详细信息,包括实时天气、预报、空气质量信息以及预警。
- 提供的数据: 当前气温、湿度、紫外线指数、污染指数、每日及每小时预报,以及恶劣天气预警。该服务以详尽的空气质量数据和实时更新的天气变化信息而著称。
- 服务提供商选择: 请在请求的 weather 部分添加 provider = 2,以选择 QWeather 作为天气服务提供商。
- 使用说明: QWeather 提供 API 访问服务,包含免费和高级两个层级。免费层级提供的数据有限,而高级选项则涵盖更多数据点和地点。
- API文档: 点击此处查看。
3. MET Weather (MET Norway)
- 描述: 由挪威气象局(MET Norway)提供的 MET Weather API,可访问各种开放的气象数据,包括预报、历史数据以及挪威和北欧地区的专项数据。MET Weather 以其准确性和透明度著称,非常适合需要高度可靠气象数据的应用程序。
- 提供的数据: 当前天气状况、预报、降水、气温、风力数据及紫外线指数。MET Weather 提供针对北欧地区的专项数据,同时也支持全球天气信息。
- 服务提供商选择: 请在请求的 weather 部分添加 provider = 3,以选择 MET Weather 作为天气服务提供商。
- 使用说明: MET Weather 提供的所有数据均可在知识共享许可协议下免费使用,允许免费用于非商业和商业用途。挪威气象局以其环境数据而闻名,是备受信赖的数据提供商,尤其在欧洲地区。
- API文档: 点击此处查看。
请求示例
function onTemporalEvent() as Void {
var ds = System.getDeviceSettings();
if (!ds.phoneConnected) { // 检查设备是否已连接到手机,以便发送请求
return;
}
var id = ds.uniqueIdentifier;
if (id == null) { // 验证设备是否已被分配了一个唯一的标识符
return;
}
var request = {};
var lockCheck = Application.Storage.getValue("LastCodeCheckTimestamp");
if (lockCheck == null || lockCheck <= Time.now().value()) { // 如有必要,发送代码
request.put("code", Application.Properties.getValue("UnlockCode"));
}
var ns_url = Application.Properties.getValue("NS");
if (!ns_url.equals("")) { // 如有需要,将发送 NightScout 应用的链接
request.put("bg", { "url" => ns_url });
}
var wP = Application.Properties.getValue("Weather");
if (wP != 0) { // 如有需要,发送天气查询参数
var lat = Application.Properties.getValue("latitude");
var lon = Application.Properties.getValue("longitude");
if (!lat.equals("") && !lon.equals("")) {
request.put("weather", {
"appid" => Application.Properties.getValue("appID"),
"lat" => lat,
"lon" => lon,
"provider" => wP
});
}
}
if (!request.isEmpty()) {
// 填写所需的请求参数
request.put("device", id);
request.put("app", p2uAppID); // 您的应用程序 ID
request.put("model", ds.partNumber);
Toybox.Communications.makeWebRequest(
"https://api.p2u.io", // API端点
request,
{
:method => 3, // Communications.HTTP_REQUEST_METHOD_POST
:headers => {
"Content-Type" => 1 // Communications.REQUEST_CONTENT_TYPE_JSON
},
:responseType => 0 // Communications.HTTP_RESPONSE_CONTENT_TYPE_JSON
},
method(:onReceive)
);
}
}
API 响应
该 API 返回一个 JSON 对象,其中包含解锁状态、血糖水平和天气信息。
响应参数
解锁码验证结果(如果已发送请求):
- response: 整数 — 返回码
- msg: 字符串 — 关于验证结果的消息
- code: 字符串 — 结果所对应的解锁代码(如已知)
- expires: 整数 — 代码的过期时间戳(UNIXTIMESTAMP 格式)
- qr: array — 用于购买或验证序列号的二维码(如适用)
NightScout 应用响应(如果已发送请求):
- bg: 关联数组 — 来自 NightScout 应用的格式化回复
- value: 整数 — 血糖水平(单位:毫克/分升)
- date: 整数 — 代码过期的时间戳(UNIXTIMESTAMP 格式)
- direction: 字符串 — 血糖水平变化的趋势
天气 API 响应(如果已发送请求):
- weather: 关联数组 — 来自天气 API 的格式化响应
- provider: 整数 — 天气数据提供商标识符
- weather: array — 当前天气状况。可能返回一个或两个值;如果返回两个值,则分别代表白天和晚上的天气状况
- temp: 浮点数 — 当前温度(摄氏度)
- feels_like: 浮点数 — 体感温度(摄氏度)
- pressure: 整数 — 大气压(以百帕为单位)
- humidity: 整数 — 湿度(%)
- precipitation: 整数 — 降水概率(%)
对于 MET Weather,仅限北欧国家。 如果该值不可用,则为 -1。 - wind: 整数 — 风向(度)
- wind_speed: 浮点数 — 风速(米/秒)
- wind_gust: 浮点数 — 阵风风速(m/s)
QWeather 不提供。 对于 MET Weather,仅限北欧国家。 如果该值不可用,则为 -1。 - uvi: 浮点数 — 紫外线指数
对于 OpenWeatherMap,仅限订阅了 One Call API 3.0 的密钥。对于 QWeather,为每日最大值。对于 MET Weather,为晴空紫外线指数。 如果该值不可用,则为 -1。 - temp_low: 浮点数 — 今天的最低气温(摄氏度)
- temp_high: 浮点数 — 今天的最高气温(摄氏度)
- sunrise_today: 整数 — 今天日出的时间戳(UNIXTIMESTAMP 格式)
- sunset_today: 整数 — 今天日落时间戳(UNIXTIMESTAMP 格式)
- sunrise_tomorrow: 整数 — 明天日出的时间戳(UNIXTIMESTAMP 格式)
- sunset_tomorrow: 整数 — 明天日落时间戳(UNIXTIMESTAMP 格式)
- aqi: 关联数组 — 空气质量指数
- level: 整数 — 空气质量指数等级
- value: 整数 — 空气质量指数值
响应示例
{
"response": 103,
"msg": "Free for beta tester",
"expires": 0,
"qr": [
"11111110111011010110101111111",
"10000010111001001101001000001",
"10111010101100110110101011101",
"10111010110101000001001011101",
"10111010000001010100001011101",
"10000010100110001101001000001",
"11111110101010101010101111111",
"00000000010010110111100000000",
"11001110000100100100100101111",
"11111100011011011010011111111",
"01111011100111111100101000001",
"01111100101100110111011011011",
"00110110101010100101110000010",
"11001000010001011000001011111",
"01101010001001110100000001101",
"10111101100010100101100110011",
"01010111111100110100100100010",
"10000100111011011000101111011",
"00000110110110110100100000101",
"00111100011100001100101100011",
"11110111110010100111111111001",
"00000000111001011101100010001",
"11111110010001011111101011101",
"10000010100010100111100010010",
"10111010101101100111111111001",
"10111010010010110000010000001",
"10111010001111111110000001111",
"10000010111101011111101101011",
"11111110100011011110110010010"
],
"bg": {
"value": -102,
"date": 1730546101,
"direction": ""
},
"weather": {
"provider": 1,
"weather": [
89
],
"temp": 0.27,
"feels_like": -3.14,
"pressure": 999,
"humidity": 78,
"precipitation": 0,
"wind": 120,
"wind_speed": 2.96,
"wind_gust": 5.21,
"uvi": 0.4,
"temp_low": -3.8,
"temp_high": 0.27,
"sunrise_today": 1730527969,
"sunset_today": 1730551770,
"sunrise_tomorrow": 1730614492,
"sunset_tomorrow": 1730638051,
"aqi": {
"level": 1,
"value": 38
}
}
}
响应代码
解锁代码验证结果的 response 字段取以下值之一。响应示例和检查顺序请参见 API端的检查。
| 代码 | 描述 |
|---|---|
| 101 | 代码有效。可以解锁应用程序。 |
| 102 | 没有有效代码,但试用期尚未结束。可在 expires 字段中的日期之前解锁应用程序。 |
| 103 | 没有有效代码,但该设备是测试版测试者:其首次 API 调用早于应用程序 发布日期 字段中的日期。可在 expires 字段中的日期之前解锁应用程序(0 - 无限制)。 |
| 201 | 未找到代码或代码已被删除。 |
| 202 | 代码已在另一台设备上激活。 |
| 203 | 代码已过期。 |
| 204 | 试用期已结束,且未发送有效代码。 |
| 301 | 未找到应用程序或应用程序不可用。 |
| 302 | 代码的期限未定义。 |
| 303 | 请求中的参数不足。 |
| 304 | 此应用程序需要设备标识符。 |
| 401 | 保存代码时出错。请发送邮件至 [email protected] 联系支持。 |
| 402 | 保存设备时出错。请发送邮件至 [email protected] 联系支持。 |
| 500 | 未知错误。请发送邮件至 [email protected] 联系支持。 |
1xx 代码表示可以解锁应用程序,2xx 表示应用程序必须保持锁定,3xx 表示请求中有错误,4xx 和 5xx 表示 PayToUse 端出错。出现 4xx 和 5xx 错误时,建议保留上一次成功的结果,稍后重试请求。
如果在应用程序设置中启用了 允许按设备 ID 重新发送代码 选项,请求中包含设备标识符但不包含代码,且该设备已绑定有效代码,API 会返回 101,并在 code 字段中返回该代码。应用程序可以保存该代码,不再要求用户输入。
备注
- 包含 bg 的请求需要连接到 NightScout 应用。
- 对于每个包含 code 的请求,API 会自动检查该代码的状态,若处于非活动状态,则将其激活。
- 请注意,API 参数可能会随着时间的推移进行更新或修改,以提升功能、兼容性和安全性。建议您定期查阅 API 文档,了解可能影响集成或使用的任何变更。
天气提供商
以下是 weather 字段中返回的天气状况与各提供商取值的对应关系。
Garmin
有关 Garmin SDK 气象函数和常量的详细说明,请参阅此链接。您可以存储从 API 获取的值或 Garmin SDK 气象函数的计算结果(具体取决于所选的气象服务提供商),以确保屏幕上显示的数值保持一致。
| ID | 描述 | 天 | 夜晚 |
|---|---|---|---|
| 0 | 晴 |
0x53 |
0x54 |
| 40 | 晴好 | ||
| 23 | 大部晴朗 |
0x55 |
0x56 |
| 1 | 局部多云 |
0x57 |
0x58 |
| 22 | 多云间晴 | ||
| 2 | 大部多云 |
0x59 |
|
| 52 | 薄云 | ||
| 20 | 多云 |
0x5A |
|
| 45 | 多云,可能有雨 | ||
| 31 | 毛毛雨 |
0x3E |
|
| 14 | 小雨 |
0x42 |
|
| 24 | 小阵雨 | ||
| 3 | 雨 |
0x43 |
|
| 25 | 阵雨 | ||
| 27 | 有阵雨的可能性 |
0x46 |
|
| 11 | 零星阵雨 | ||
| 15 | 大雨 | ||
| 26 | 强阵雨 | ||
| 28 | 有雷暴的可能性 |
0x36 |
0x37 |
| 12 | 零星雷暴 |
0x38 |
|
| 6 | 雷暴 |
0x39 |
|
| 8 | 雾 |
0x4E |
|
| 9 | 朦胧 | ||
| 29 | 薄雾 | ||
| 39 | 阴霾 | ||
| 30 | 灰尘 |
0x4F |
|
| 35 | 沙 | ||
| 33 | 烟 | ||
| 38 | 火山灰 | ||
| 37 | 沙尘暴 | ||
| 13 | 降水 | ||
| 5 | 有风 |
0x52 |
|
| 36 | 飑 | ||
| 48 | 阵雪 | ||
| 32 | 龙卷风 |
0x50 |
|
| 41 | 飓风 | ||
| 42 | 热带风暴 | ||
| 50 | 冰粒 |
0x45 |
|
| 7 | 雨雪混合天气 | ||
| 18 | 小雨夹雪 | ||
| 19 | 大雨夹雪 | ||
| 21 | 雨夹雪 | ||
| 49 | 冻雨 | ||
| 44 | 降雨或降雪的可能性 | ||
| 47 | 多云,可能有雨或雪 | ||
| 34 | 冰 | ||
| 51 | 冰雪 | ||
| 43 | 降雪概率 |
0x4C |
0x4D |
| 16 | 小雪 | ||
| 46 | 多云,有降雪可能 |
0x4A |
|
| 4 | 雪 | ||
| 17 | 大雪 |
0x4B |
|
| 10 | 冰雹 |
0x3A |
|
Open Weather Map
请点击此处查看 OpenWeatherMap 的图标集作为示例。
| ID | 描述 | 天 | 夜晚 |
|---|---|---|---|
| 2xx | 雷暴 | ||
| 200 | 雷暴,伴有小雨 |
0x36 |
0x37 |
| 201 | 雷暴,伴有雨 |
0x38 |
|
| 202 | 雷暴,伴有大雨 | ||
| 210 | 小雷暴 | ||
| 211 | 雷暴 |
0x39 |
|
| 212 | 强雷暴 |
0x3B |
|
| 221 | 零星雷暴 | ||
| 230 | 雷暴,伴有小毛毛雨 |
0x3A |
|
| 231 | 雷暴,伴有毛毛雨 | ||
| 232 | 雷暴,伴有大毛毛雨 | ||
| 3xx | 毛毛雨 | ||
| 300 | 小毛毛雨 |
0x3C |
0x3D |
| 301 | 毛毛雨 |
0x3E |
|
| 302 | 大毛毛雨 |
0x3F |
|
| 310 | 小毛毛雨和雨 |
0x40 |
|
| 311 | 毛毛雨和雨 | ||
| 312 | 大毛毛雨和雨 |
0x41 |
|
| 313 | 阵雨和毛毛雨 | ||
| 314 | 强阵雨和毛毛雨 | ||
| 321 | 毛毛阵雨 | ||
| 5xx | 雨 | ||
| 500 | 小雨 |
0x42 |
|
| 501 | 中雨 |
0x43 |
|
| 502 | 大雨 |
0x44 |
|
| 503 | 暴雨 | ||
| 504 | 极端降雨 | ||
| 511 | 冻雨 |
0x45 |
|
| 520 | 小阵雨 |
0x46 |
|
| 521 | 阵雨 | ||
| 522 | 强阵雨 | ||
| 531 | 零星阵雨 | ||
| 6xx | 雪 | ||
| 600 | 小雪 |
0x4C |
0x4D |
| 601 | 雪 |
0x4A |
|
| 602 | 大雪 | ||
| 611 | 冰粒 |
0x45 |
|
| 612 | 小阵雨夹雪 | ||
| 613 | 阵雨夹雪 | ||
| 615 | 小雨夹雪 | ||
| 616 | 雨夹雪 | ||
| 620 | 小阵雪 |
0x4B |
|
| 621 | 阵雪 | ||
| 622 | 强阵雪 | ||
| 7xx | 大气现象 | ||
| 701 | 薄雾 |
0x4E |
|
| 711 | 烟 |
0x4F |
|
| 721 | 阴霾 | ||
| 731 | 沙尘旋涡 | ||
| 741 | 雾 | ||
| 751 | 沙 |
0x4F |
|
| 761 | 灰尘 | ||
| 762 | 火山灰 | ||
| 771 | 飑 |
0x52 |
|
| 781 | 龙卷风 |
0x50 |
|
| 800 | 晴 | ||
| 800 | 晴 |
0x53 |
0x54 |
| 80x | 云 | ||
| 801 | 少云 11–25% |
0x55 |
0x56 |
| 802 | 疏云 25–50% |
0x57 |
0x58 |
| 803 | 多云 51–84% |
0x59 |
|
| 804 | 阴天 85–100% |
0x5A |
|
QWeather
您可以点击此处查看原始的天气图标集
| ID | 描述 | 天 | 夜晚 |
|---|---|---|---|
| 302 | 雷阵雨 |
0x36 |
0x37 |
| 303 | 强雷暴 |
0x38 |
|
| 310 | 暴雨 |
0x39 |
|
| 317 | 暴雨到大暴雨 | ||
| 304 | 冰雹 |
0x3A |
|
| 311 | 大暴雨 |
0x3B |
|
| 312 | 特大暴雨 | ||
| 318 | 大暴雨到特大暴雨 | ||
| 309 | 毛毛雨 |
0x3C |
0x3D |
| 404 | 冰粒 |
0x3E |
|
| 305 | 小雨 |
0x42 |
|
| 314 | 小到中雨 | ||
| 306 | 中雨 |
0x43 |
|
| 315 | 中到大雨 | ||
| 399 | 雨 | ||
| 308 | 极端降雨 |
0x44 |
|
| 316 | 大雨到暴雨 | ||
| 313 | 冻雨 |
0x45 |
|
| 405 | 雨雪天气 | ||
| 300 | 阵雨 |
0x46 |
|
| 301 | 强阵雨 | ||
| 307 | 大雨 | ||
| 350 | 阵雨 | ||
| 351 | 强阵雨 | ||
| 400 | 小雪 |
0x4C |
0x4D |
| 408 | 小雪至中雪 | ||
| 499 | 雪 | ||
| 401 | 中雪 |
0x4A |
|
| 402 | 大雪 | ||
| 409 | 中到大雪 | ||
| 410 | 大雪至暴风雪 | ||
| 403 | 暴风雪 |
0x4B |
|
| 406 | 阵雨夹雪 | ||
| 407 | 阵雪 | ||
| 456 | 阵雨夹雪 | ||
| 457 | 阵雪 | ||
| 503 | 沙 |
0x4E |
|
| 504 | 灰尘 | ||
| 507 | 沙尘暴 | ||
| 508 | 沙尘暴 | ||
| 511 | 中度霾 | ||
| 512 | 重度霾 | ||
| 513 | 严重霾 | ||
| 500 | 薄雾 |
0x4F |
|
| 501 | 雾 | ||
| 502 | 阴霾 | ||
| 509 | 浓雾 | ||
| 510 | 强浓雾 | ||
| 514 | 大雾 | ||
| 515 | 特强浓雾 | ||
| 100 | 晴 |
0x53 |
0x54 |
| 150 | 晴 | ||
| 101 | 多云 |
0x55 |
0x56 |
| 151 | 多云 | ||
| 102 | 少云 |
0x57 |
0x58 |
| 152 | 少云 | ||
| 103 | 晴间多云 |
0x59 |
|
| 153 | 晴间多云 | ||
| 104 | 阴 |
0x5A |
|
MET Weather
请点击此处查看 MET Weather 的图标集作为示例。
| ID | 描述 | 天 | 夜晚 |
|---|---|---|---|
| lightrainshowers | 小阵雨 |
0x36 |
0x37 |
| lightrainshowersandthunder | 小雷阵雨 | ||
| rainshowersandthunder | 雷阵雨 | ||
| heavyrainshowersandthunder | 强雷阵雨 | ||
| heavyrainandthunder | 强雷雨 |
0x38 |
|
| rainandthunder | 雷雨 | ||
| lightrainandthunder | 小雷雨 |
0x39 |
|
| heavysleetandthunder | 大雨夹雪,伴有雷电 |
0x3B |
|
| lightsleetandthunder | 小雨夹雪,伴有雷电 |
0x3A |
|
| lightssleetshowersandthunder | 短时小雨夹雪,伴有雷电 | ||
| sleetandthunder | 雨夹雪,伴有雷电 | ||
| lightsleetshowers | 短时小雨夹雪 |
0x3C |
0x3D |
| sleetshowers | 短时雨夹雪 | ||
| sleetshowersandthunder | 短时雨夹雪,伴有雷电 | ||
| heavysleetshowers | 短时大雨夹雪 | ||
| heavysleetshowersandthunder | 短时大雨夹雪,伴有雷电 | ||
| lightsleet | 小雨夹雪 |
0x3E |
|
| sleet | 冰粒 |
0x3F |
|
| heavysleet | 大雨夹雪 |
0x45 |
|
| lightrain | 小雨 |
0x42 |
|
| rain | 雨 |
0x43 |
|
| heavyrain | 大雨 |
0x44 |
|
| rainshowers | 阵雨 |
0x46 |
|
| heavyrainshowers | 强阵雨 | ||
| heavysnow | 大雪 |
0x4B |
|
| heavysnowandthunder | 强雷雪 | ||
| snow | 雪 | ||
| snowandthunder | 雷雪 | ||
| lightsnowshowers | 小阵雪 |
0x4C |
0x4D |
| lightssnowshowersandthunder | 小雷阵雪 | ||
| snowshowers | 阵雪 | ||
| snowshowersandthunder | 雷阵雪 | ||
| heavysnowshowers | 强阵雪 | ||
| heavysnowshowersandthunder | 强雷阵雪 | ||
| lightsnow | 小雪 |
0x4A |
|
| lightsnowandthunder | 小雷雪 | ||
| fog | 雾 |
0x4F |
|
| clearsky | 晴 |
0x53 |
0x54 |
| fair | 晴好 |
0x55 |
0x56 |
| partlycloudy | 局部多云 |
0x57 |
0x58 |
| cloudy | 多云 |
0x59 |
|