添加库 · WearCheckout 文档

库会替你绘制每个付款界面。你只需添加它的文件夹、一项权限、一个小配置文件和一行代码。

文件

从应用的“安装”标签页下载库。解压后是一个 wearcheckout 文件夹。

路径	作用
`lib/watch/app/Pay.mc`	应用：向我们的服务器检查、根据服务器应答绘制的购买界面、其时间限制，以及带提示音和振动的解锁。
`lib/watch/glance/PayScope.mc`	`active()`、`unlocked()` 和 `trialLeft()`，注解为 `(:glance)`：适用于没有后台服务的应用。
`lib/watch/glance-bg/PayScope.mc`	同上，但注解为 `(:glance, :background)`：适用于有后台服务的应用。两者只能用其一。
`lib/watch/face/PayFace.mc`, `PayFaceScope.mc`	表盘和数据字段：后台检查、`drawQr` 和设置链接。参见表盘和数据字段。
`lib/watch/extras/PayExtras.mc`	仅在你出售“评价与回复”或使用店铺时需要：评价提示、你的回复以及“已经买了？”界面。参见应用中的附加功能。Connect IQ 3.1 之前的手表会跳过它。
`lib/watch/export/PayExport.mc`	仅在你出售“导出到手机”时需要：把应用数据导出为电子表格，在手表上加密，并把链接发送到买家的手机。
`lib/watch/feeds/PayFeeds.mc`	仅当你的应用使用数据源时：天气、日月、礼拜时间、潮汐等。参见数据源。
`lib/watch/resources/strings/pay.xml`	购买界面在没有服务器时显示的 4 行英文。
`lib/watch/resources-<lang>/strings/pay.xml`	其他 7 种语言中的同样 4 行。

添加到你的项目

把库解压到应用文件夹旁边：

IntervalTimer/
    manifest.xml
    monkey.jungle
    resources/
    source/
        PaywallConfig.mc
wearcheckout/
    lib/watch/...

然后把它的文件夹添加到你的 jungle：

monkey.jungle

base.sourcePath = source;../wearcheckout/lib/watch/app;../wearcheckout/lib/watch/glance
base.resourcePath = resources;../wearcheckout/lib/watch/resources

只用相对路径。绝对路径中的空格会让 jungle 出错。
或者复制文件。把库复制到你自己的 source 和 resources 文件夹（以及每个 resources-<lang> 文件夹）后，就不需要 jungle 那一行了。
无需设置注解。一次构建适用于所有手表。Instinct 的副屏在运行时识别。

有后台服务时

如果你的应用有自己的后台服务，请用 glance-bg 代替 glance，给 PaywallConfig 加上 (:glance, :background) 注解，并添加 Background 权限。任何 (:background) 代码都会让编译器要求该权限，所以才有两个版本。

monkey.jungle

base.sourcePath = source;../wearcheckout/lib/watch/app;../wearcheckout/lib/watch/glance-bg

允许网络访问

手表通过手机的连接询问我们的服务器，带 Wi-Fi 的手表也可通过 Wi-Fi。添加 Communications 权限：

manifest.xml

<iq:permissions>
    <iq:uses-permission id="Communications"/>
</iq:permissions>

PaywallConfig.mc

从应用的“安装”标签页下载：它包含应用的真实地址。该地址是公开的，不是密钥。

source/PaywallConfig.mc

// PaywallConfig.mc: from your dashboard (Interval Timer). Public, not a secret.
import Toybox.Lang;

(:glance)
module PaywallConfig {
    const URL = "https://pay.example/api/K7Q2/c";   // your app's address
    const TRIAL_DAYS = 7;
}

URL：你的应用地址。所有检查都发往这里。
TRIAL_DAYS：不设试用就省略。请与控制台中的试用期保持一致：手表计算的天数永远不会超过 TRIAL_DAYS。
注解与你使用的 PayScope.mc 对应：(:glance)，或 (:glance, :background) 搭配 glance-bg。

那一行代码

在 getInitialView() 中，通过库返回你的视图：

source/YourApp.mc

return Paywall.gate([new MainView(), new MainDelegate()]);   // the whole app is paid for
return Paywall.start([new MainView(), new MainDelegate()]);  // or: only some features are

gate 开始试用，按时询问服务器，锁定期间以购买界面代替你的应用。按 BACK 退出应用。付费后，按 BACK 或 START 打开你自己的视图。
start 照常打开你的应用，试用结束时显示一次购买界面。之后每个付费功能会先检查：

source/HistoryDelegate.mc

if (Paywall.unlocked()) { showHistory(); } else { Paywall.open(); }

无论使用哪一个，在购买界面关闭时于手机上完成的购买，都会在手表收到消息后自动打开解锁界面。给付费功能加锁列出了所有调用。

设置中的 Premium 项

设置菜单中的“Premium”项会打开购买界面。如果已经显示了一个，就回到那个：永远不会出现第二个。

source/SettingsDelegate.mc

Paywall.open();

删除数据

如果你的应用有“删除数据”选项，请保留 Paywall.keys() 返回的键。其余数据会在下次启动时从服务器恢复。

source/SettingsDelegate.mc

// Delete data: everything except the payment keys
var st = Application.Storage;
var keep = Paywall.keys();
var saved = [];
for (var i = 0; i < keep.size(); i++) {
    saved.add(st.getValue(keep[i]));
}
st.clearValues();
for (var j = 0; j < keep.size(); j++) {
    if (saved[j] != null) {
        st.setValue(keep[j], saved[j]);
    }
}

应用中的附加功能

其中三项付费附加功能需要各自的文件夹，这样不用它们的应用可以保持小巧。手表统计不需要文件夹。

评价与回复，以及“已经买了？”

添加 extras 文件夹，然后在那一行代码之前开启它：

monkey.jungle

base.sourcePath = source;../wearcheckout/lib/watch/app;../wearcheckout/lib/watch/glance;../wearcheckout/lib/watch/extras

source/YourApp.mc

PayExtras.on();
return Paywall.gate([new MainView(), new MainDelegate()]);

评价提示在第 3、7 或 14 天显示：先是星级评分，然后是打开商店页面的 QR 码，以及写给你的留言。
你的回复会在应用上方显示一次。在小屏手表上，较长的回复会占两屏：START 显示其余部分。
如果买家先在你的店铺页面付款，“已经买了？”会在新手表上显示一次手表代码。
没有该文件夹时，该应用的手表不会显示提示，你的回复会留在服务器上等待，店铺买家则扫描普通购买界面。Connect IQ 3.1 之前的手表也会跳过该文件夹。

导出到手机

添加 export 文件夹，在 PayExport.ready() 为 true 时提供导出，并用一次返回一行的方法启动它：

monkey.jungle

base.sourcePath = source;../wearcheckout/lib/watch/app;../wearcheckout/lib/watch/glance;../wearcheckout/lib/watch/export

source/ExportDelegate.mc

// Row 0 is the header; rows 1 to n are your data.
function row(i as Number) as Array {
    if (i == 0) { return ["Date", "Minutes"]; }
    var s = sessions[i - 1];
    return [s[:date], s[:minutes]];
}

if (PayExport.ready()) {
    PayExport.start(method(:row), sessions.size());
}

值可以是文本、数字、true 或 false，或 null。
其余交给库：它发送加密的数据块，然后以 Garmin Connect 通知的形式把链接发到买家手机。买家点开后，手机会打开电子表格。START 会再次发送链接。链接需要买家的手机与手表保持连接。
公式永远不会执行。以 =、+、- 或 @ 开头的文本会先加上 '。

数据源

添加 feeds 文件夹，然后在应用需要的地方请求数据源。你的方法会收到 HTTP 代码和应答：

monkey.jungle

base.sourcePath = source;../wearcheckout/lib/watch/app;../wearcheckout/lib/watch/glance;../wearcheckout/lib/watch/feeds

source/MainView.mc

PayFeeds.get("weather", {
    "lat" => lat, "lon" => lon,
    "tz" => System.getClockTime().timeZoneOffset
}, method(:onWeather));

function onWeather(code as Number, data as Dictionary or Null) as Void {
    if (code == 200) {
        temp = data["now"]["temp"];
        WatchUi.requestUpdate();
    }
}

数据源：太阳、月亮、礼拜时间、世界时钟、汇率、天气、天气预警（美国）、地震、极光、潮汐（美国）和公共假日。各自的参数和字段见控制台的“数据源”页面，可在那里试一试。
保留在手表上。每个应答在其 ttl（秒）内有效。在此之前对同一数据源、几乎相同的地点再次请求，会立即返回保留的应答，不发出请求。
地点用度数表示。时间为 Unix 秒，单位为公制。
显示来源说明：数据源卡片要求时显示，例如“Weather: MET Norway”。
其他代码返回 null：403 表示此应用的附加功能已关闭，429 或 503 表示稍后重试，负数代码来自 Garmin（无手机、无网络）。测试手表的所有数据源都免费。
费用：来自正式手表的请求每百万次 US$2，计入月度账单。手表上保留的应答不收费。

手表统计

无需代码：每次检查都会带上手表型号。如果还想查看应用版本，请在 PaywallConfig 中添加版本号：

source/PaywallConfig.mc

const VERSION = "1.3";

语言

库支持英语、德语、法语、西班牙语、葡萄牙语、韩语和中文（简体和繁体）。由手表自身的语言决定。其他语言显示英语。

界面内容来自我们的服务器，使用手表的语言，因此修改措辞无需更新应用。
手表上只存放 4 行文字，用于服务器尚未应答时。

字符串	英文	显示时机
`PwWait`	加载中…	收到第一次应答前
`PwPhone`	离线	没有手机、蓝牙或网络
`PwBusy`	稍后再试	服务器没有正常应答
`PwBack`	按 BACK 关闭	完全没有应答可显示时

每种语言添加一行 jungle。把你自己的文件夹放在前面；应用没有某种语言的文件夹时，就省略那一部分。

monkey.jungle

base.lang.deu = resources-deu;../wearcheckout/lib/watch/resources-deu
base.lang.fre = resources-fre;../wearcheckout/lib/watch/resources-fre
base.lang.spa = resources-spa;../wearcheckout/lib/watch/resources-spa
base.lang.por = resources-por;../wearcheckout/lib/watch/resources-por
base.lang.kor = resources-kor;../wearcheckout/lib/watch/resources-kor
base.lang.zhs = resources-zhs;../wearcheckout/lib/watch/resources-zhs
base.lang.zht = resources-zht;../wearcheckout/lib/watch/resources-zht

检查事项

应用名称字符串。没有应答可显示时，购买界面会显示你的 AppName 字符串。请在资源中保留该字符串。
计时器。购买界面占用一个计时器，PayExtras 再占一个。手表只允许少数几个，“Too Many Timers” 会使应用退出：如果你的应用已在运行两个或更多，请确认没有超出限制。
长按按键。按住按键太久会打开手表自带的菜单。购买界面只响应短按。
旧的调用仍然可用。getInitialView() 中的 Paywall.startTrial(); Paywall.launch();，以及第一个界面 onShow() 中的 Paywall.showOver()，作用与一行 gate 和 start 相同。