加入程式庫 · 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-bg 的 (:glance, :background)。

那一行程式碼

在 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 行文字，用於伺服器尚未回應時。

String	英文	顯示時機
`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 一行完成的事相同。