文件

程式庫

錶面與資料欄位

錶面在畫面上無法接收按鈕操作,也無法連上網路。因此程式庫會在背景向我們的伺服器確認,你的錶面在你選定的位置繪製 QR 碼,Garmin 的登入通知則讓買家不必掃描就能付款。資料欄位的運作方式相同。

運作方式

  • 由背景程式詢問。錶面的背景服務會在伺服器指定的時間,向我們的伺服器傳送與應用程式相同的請求。
  • 時間始終在最上層。在錶面上,查看時間是主要功能,Garmin 建議不要用付費牆遮住它。鎖定時,你的錶面會在你選定的位置繪製 QR 碼。資料欄位則在自己的區域內繪製。
  • 連結在設定中。錶面也會把購買連結寫入它的設定,手機上的 Connect IQ 應用程式會顯示它。買家不必掃描就能從那裡開啟。
  • 通知可省去掃描。錶面鎖定且手機已連線時,它會傳送 Garmin 的登入通知。買家點一下、付款,錶面幾秒內就會解鎖。

加入錶面或資料欄位

錶面和資料欄位只使用 lib/watch/face:PayFace.mc 和 PayFaceScope.mc。

monkey.jungle
base.sourcePath = source;../wearcheckout/lib/watch/face
manifest.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()、購買畫面及其字串。切勿從概覽或背景程式碼呼叫。
Esc