程式庫
錶面與資料欄位
錶面在畫面上無法接收按鈕操作,也無法連上網路。因此程式庫會在背景向我們的伺服器確認,你的錶面在你選定的位置繪製 QR 碼,Garmin 的登入通知則讓買家不必掃描就能付款。資料欄位的運作方式相同。
運作方式
- 由背景程式詢問。錶面的背景服務會在伺服器指定的時間,向我們的伺服器傳送與應用程式相同的請求。
- 時間始終在最上層。在錶面上,查看時間是主要功能,Garmin 建議不要用付費牆遮住它。鎖定時,你的錶面會在你選定的位置繪製 QR 碼。資料欄位則在自己的區域內繪製。
- 連結在設定中。錶面也會把購買連結寫入它的設定,手機上的 Connect IQ 應用程式會顯示它。買家不必掃描就能從那裡開啟。
- 通知可省去掃描。錶面鎖定且手機已連線時,它會傳送 Garmin 的登入通知。買家點一下、付款,錶面幾秒內就會解鎖。
加入錶面或資料欄位
錶面和資料欄位只使用 lib/watch/face:PayFace.mc 和 PayFaceScope.mc。
monkey.jungle
base.sourcePath = source;../wearcheckout/lib/watch/facemanifest.xml
<iq:permissions>
<iq:uses-permission id="Background"/>
<iq:uses-permission id="Communications"/>
</iq:permissions>設定檔標註為 (:background),因為背景程式會讀取它。請在其中保留 TRIAL_DAYS,不提供試用時設為 0:錶面部分會直接讀取它。
source/PaywallConfig.mc
// PaywallConfig.mc: from your dashboard (Trail Face). Public, not a secret.
import Toybox.Lang;
(:background)
module PaywallConfig {
const URL = "https://pay.example/api/K7Q2/c"; // your app's address
const TRIAL_DAYS = 7;
}掛鉤
| 位置 | 呼叫 |
|---|---|
getInitialView() | 每次啟動時執行 Paywall.startTrial(); Paywall.schedule(false); |
getServiceDelegate() | return [new PayBg()]; |
onBackgroundData(data) | Paywall.take(data); |
onSettingsChanged() | Paywall.soon(); |
onUpdate(dc) | if (!Paywall.unlocked()) { Paywall.drawQr(dc, x, y, side); } |
完整的錶面,鎖定時時間在上方,代碼在下方:
source/PayFaceApp.mc
import Toybox.Application;
import Toybox.Background;
import Toybox.Graphics;
import Toybox.Lang;
import Toybox.System;
import Toybox.Time;
import Toybox.WatchUi;
// A small face for measuring: the time, and the QR code under it while locked.
(:background)
class PayFaceApp extends Application.AppBase {
function initialize() {
AppBase.initialize();
}
function onStart(state as Dictionary or Null) as Void {
}
function getInitialView() {
Paywall.startTrial();
Paywall.schedule(false);
return [new PayFaceView()];
}
function getServiceDelegate() {
return [new PayBg()];
}
function onBackgroundData(data) as Void {
Paywall.take(data);
}
// Saving the face's settings on the phone (the buy page suggests it after paying): ask now
// (5 minutes after the last check at the soonest, Garmin's rule).
function onSettingsChanged() as Void {
Paywall.soon();
}
}
class PayFaceView extends WatchUi.WatchFace {
function initialize() {
WatchFace.initialize();
}
function onUpdate(dc as Graphics.Dc) as Void {
var w = dc.getWidth();
var h = dc.getHeight();
var t = System.getClockTime();
dc.setColor(Graphics.COLOR_WHITE, Graphics.COLOR_BLACK);
dc.clear();
dc.drawText(w / 2, h * 30 / 100, Graphics.FONT_NUMBER_MEDIUM, t.hour.format("%02d") + ":" + t.min.format("%02d"),
Graphics.TEXT_JUSTIFY_CENTER | Graphics.TEXT_JUSTIFY_VCENTER);
if (!Paywall.unlocked()) {
Paywall.drawQr(dc, w / 2, h * 68 / 100, w * 36 / 100);
}
}
}設定連結
新增唯讀的 unlock 屬性。錶面會以伺服器回應中的購買連結填入。在你自己的資源中定義 UnlockTitle 字串。
resources/settings/settings.xml
<resources>
<!-- The buy link, written by the face from the server's answer: the phone's Connect IQ app
shows it in this face's settings, so a buyer can open it without scanning. -->
<properties>
<property id="unlock" type="string"></property>
</properties>
<settings>
<setting propertyKey="@Properties.unlock" title="@Strings.UnlockTitle">
<settingConfig type="alphaNumeric" readonly="true"/>
</setting>
</settings>
</resources>繪製代碼
Paywall.drawQr(dc, x, y, side)在白色方塊上繪製寬side的代碼,中心位於x,y。收到第一次回應前不繪製任何內容。- 只在
!Paywall.unlocked()時呼叫。 - 只在螢幕完全亮起時繪製,絕不要在 AMOLED 手錶的恆亮模式下繪製。
Garmin 的登入通知
- 傳送時機:檢查首次發現錶面鎖定時傳送一次(試用結束或沒有試用)。之後在鎖定期間,買家每次儲存錶面設定時再傳送。只在手機連線時傳送:它需要手機本身,Wi-Fi 不行。
- 買家看到的內容:手機上 Garmin 自己的通知。文字由 Garmin 撰寫(「<app> needs you to sign in」),任何應用程式都無法更改。點一下會在 Garmin Connect 內建的瀏覽器中開啟你的結帳頁面。
- 付款後:頁面結束,手機把結果交給手錶,錶面的背景程式向我們的伺服器詢問。單憑結果無法解鎖,因為任何人都能輸入它的網址。只有我們伺服器的回應才會解鎖。
- 絕不會誤傳兩次:背景程式會自行標記為已傳送(CIQ 3.2 及以上),即使錶面之後沒有馬上執行。在無法傳送的手錶上,QR 碼和設定連結仍可使用。
應用程式不會傳送。應用程式的購買畫面在付款後約一秒就會解鎖。
解鎖需要多久
我們的伺服器無法主動連上手錶。錶面只有在下一次檢查時才會得知付款,而 Garmin 最多每 5 分鐘允許一次背景檢查。
| 買家如何付款 | 錶面解鎖 |
|---|---|
| 點了登入通知 | 幾秒內 |
| 在安裝後或試用結束後的 2 天內,掃描代碼或使用設定連結 | 10 分鐘內 |
| 相同,但較晚 | 一小時內 |
| 付款後在手機上儲存錶面設定 | 在 Garmin 允許的最早檢查時:距上一次至少 5 分鐘 |
- 檢查發現結帳頁面已開啟後,錶面會在半小時內每 5 分鐘檢查一次。
- 試用期間,錶面會在試用結束時或每天檢查一次,以較早者為準。
- 檢查失敗後(沒有手機),下一次在一小時後。
標註與作用範圍
概覽和背景程式碼只能存取為它們標註的程式碼。保留程式庫原本的標註,並讓你自己的標註與之一致。
- 錶面和資料欄位:
PaywallConfig為(:background),你的AppBase類別也是,如範例所示:它的getServiceDelegate()在背景執行。PayBg和PayFaceScope.mc已加上標註。 - 有概覽的應用程式:
glance/PayScope.mc和PaywallConfig為(:glance)。概覽只能呼叫Paywall.active()、Paywall.unlocked()和Paywall.trialLeft()。 - 有自己背景服務的應用程式:
glance-bg/PayScope.mc、標註為(:glance, :background)的PaywallConfig,以及 Background 權限。 - 僅限應用程式:
Pay.mc中的所有內容,包括Paywall.open()、購買畫面及其字串。切勿從概覽或背景程式碼呼叫。