Passbook 是 iOS 6 最受矚目的新技術,它把「票券、集點卡、登機證」這類紙本物品搬進手機。而它與你以往用過的蘋果技術最大的不同在於:蘋果不處理後端。Pass 檔案由你自己產生、自己簽章、自己派送,用什麼語言、什麼架構都隨你。
換個角度說,你對最終呈現的控制權遠高於其他蘋果 API。
本篇(上半部)的目標:從一個空白檔案開始,手工做出一張完整、經過數位簽章的 Pass。
蘋果的官方說法是「你口袋裡的一切東西」。它可以是電影票、咖啡店的集點卡、健身房會員證、演唱會門票——任何原本印在紙上的東西。
如上圖的「Free hug!」優惠券,可以輕易辨識出幾個元素:最上方是 logo 與公司名稱,中間清楚描述這張 Pass 的用途與有效時間,最下方則是條碼。
蘋果預定義了四種 Pass,加上一種通用型:
為什麼要分這麼多種?因為不同用途需要不同的版面配置。健身房會員證需要放照片,音樂會門票不需要;登機牌需要兩欄來放出發與抵達城市。
差異不只在使用者看得到的配置,連圓角、剪紙缺口等視覺細節都不同。因此選對 Pass 類型是設計的起點。
Pass 以副檔名 .pkpass 的檔案形式交付給使用者(pk = PassKit)。而 .pkpass 其實就是一個 ZIP 壓縮檔——改名解壓後會看到這些內容:
在 Xcode 中選擇 File → New → File… → iOS / Other / Empty,命名為 pass.json,存到一個專門的 Pass 工作目錄(後續所有檔案都會放在同一處)。
先寫入最基本的元資料:
{
"formatVersion" : 1,
"passTypeIdentifier" : "pass.com.yourdomain.couponfreehug",
"serialNumber" : "001",
"teamIdentifier" : "<YOUR TEAM IDENTIFIER>",
"organizationName" : "Free Hugs LLC",
"description" : "Coupon for 1 Free Hug"
}
各欄位意義:
1。必須是數字,寫成字串會導致檔案失效。"001"、"XS83A" 皆可),用來區分同類型的不同 Pass。為什麼用 JSON 而不是 plist?因為 Pass 多半由 Web 伺服器動態產生,而 PHP、.NET、Ruby、Python 對 JSON 的支援都相當成熟。選 JSON 是為了讓任何後端技術都能輕鬆產出 Pass。
登入 iOS Developer Portal,開啟 iOS Provisioning Portal,左側會看到 Pass Type IDs 項目。點進去後選擇 New Pass Type ID:
Free Hug Passpass.com.yourdomain.couponfreehug蘋果建議 Pass Type ID 使用以 pass 開頭的反向網域名稱寫法。正式專案中請把 com.yourdomain 換成你實際擁有的網域。
重要:若之後修改了這個識別碼,pass.json 中的 passTypeIdentifier 必須同步修改,否則簽章驗證會失敗。
按下 Submit 後,那顆指示燈不會變綠——因為還缺憑證。點 Configure:
這個頁面會顯示你的十碼 Team Identifier(以 ABC 開頭),請用它更新 pass.json 中的 teamIdentifier——只替換佔位符,保留兩側引號。
回到 Provisioning Portal 再點一次 Configure,啟動 Pass Certificate Assistant 並跟著精靈走完。憑證生成後下載,雙擊匯入鑰匙串。
在 description 那行末尾加上逗號,然後在結尾大括號前補上:
"logoText" : "Free Hugs LLC", "foregroundColor" : "rgb(255, 255, 255)", "backgroundColor" : "rgb(135, 129, 189)", "labelColor" : "rgb(45, 54, 129)"
PassKit 支援三種二維條碼格式:QR、PDF417、Aztec。不支援傳統的一維條碼。
在 barcode 字典的結尾大括號後補上逗號,並貼入:
"barcode" : {
"message" : "All you need is love",
"format" : "PKBarcodeFormatPDF417",
"messageEncoding" : "iso-8859-1"
}
PKBarcodeFormatQR / PKBarcodeFormatPDF417 / PKBarcodeFormatAztec 擇一。目前 pass.json 的樣子:
{
"formatVersion" : 1,
"passTypeIdentifier" : "pass.com.yourdomain.couponfreehug",
"serialNumber" : "001",
"teamIdentifier" : "ABC1230000",
"organizationName" : "Free Hugs LLC",
"description" : "Coupon for 1 Free Hug",
"logoText" : "Free Hugs LLC",
"foregroundColor" : "rgb(255, 255, 255)",
"backgroundColor" : "rgb(135, 129, 189)",
"labelColor" : "rgb(45, 54, 129)",
"barcode" : {
"message" : "All you need is love",
"format" : "PKBarcodeFormatPDF417",
"messageEncoding" : "iso-8859-1"
}
}
在 barcode 字典後補逗號,加上 Pass 類型:
"coupon" : { }
再往這個空字典裡塞入欄位定義:
"primaryFields" : [
{
"key" : "offer",
"label" : "for you",
"value" : "Free hug"
}
]
這結構第一眼有點怪,但邏輯很清楚:primaryFields 是陣列,因為每個區塊可以顯示一個或多個欄位,需要有序清單來決定先後。陣列中每個字典描述一個欄位:
把 PassAssets.zip 解壓後的 PNG 檔全部放進你的 Pass 工作目錄即可。
不需要在 pass.json 中寫任何圖片路徑——Passbook 依標準命名規則自動載入 icon.png、logo.png、strip.png 及各自的 @2x 版本。
注意:圖片必須匯出為 PNG24 格式。較小尺寸的 PNG8 在 Passbook 中不會顯示,這是個很容易浪費半小時的坑。
這個檔案列出包內所有檔案及其 SHA1 校驗碼:
{
"strip.png":"25b4c9ff2bafe056f3e28379db0ef3fb460c718b",
"strip@2x.png":"dee775ed6fb3c7278b84c65853401e760caabc92",
"icon.png":"8eaa0896db93f2165fa417df3d002ce9c61fcd92",
"icon@2x.png":"555ce7f70f2f44fb7ac9d9f46df5738ec6250f37",
"logo.png":"e8c4edfbcae41d9d88fad7137d8ed30ae5f73e67",
"logo@2x.png":"1f9b1cc4c75b380ade07e9f2b7f37f988d9d14c3",
"pass.json":"<INSERT YOUR PASS SHA1 HERE>"
}
最後一項要自己算。開啟終端機並切到 Pass 目錄:
cd ~/Desktop/FreeHugCoupon
然後執行:
openssl sha1 pass.json
輸出類似:
SHA1(pass.json)= c24766ef5aa92197eace640fcc4fb584a505a733
把這串值填回 manifest.json 的佔位符處(保留雙引號),存檔。
關鍵警告:從這一刻起不要再修改 pass.json。哪怕只加一個字元,SHA1 就會改變,manifest 隨即失效,Passbook 會判定這個 Pass 已被竄改。
開啟鑰匙串存取,在「憑證」分類中找到 Pass Type ID: pass.com.yourdomain.couponfreehug,選憑證本身而非底下的私鑰,右鍵選擇「匯出」:
存為 Certificates.p12。跳出密碼框時直接按 OK,匯出為無密碼保護的版本(正式環境請務必設密碼)。
接著回到終端機,把憑證與私鑰拆成兩個檔案:
openssl pkcs12 -in Certificates.p12 -clcerts -nokeys -out passcertificate.pem -passin pass:
成功時會顯示 MAC verified OK。
openssl pkcs12 -in Certificates.p12 -nocerts -out passkey.pem -passin pass: -passout pass:12345
簽章還需要蘋果的 WWDR 中繼憑證。在鑰匙串中找到 Apple Worldwide Developer Relations Certification Authority,右鍵匯出並選擇 Privacy Enhanced Mail (.pem) 格式,命名為 WWDR.pem。
若找不到這張憑證,可至 apple.com/certificateauthority/ 下載。
一切就緒,產生簽章:
openssl smime -binary -sign -certfile WWDR.pem \
-signer passcertificate.pem \
-inkey passkey.pem \
-in manifest.json \
-out signature \
-outform DER \
-passin pass:12345
參數其實很好懂:signer 是你的 Pass 憑證、inkey 是私鑰、in 是輸入檔、out 是輸出檔、outform DER 指定分離式簽章格式、passin 是私鑰密碼。
zip -r freehugcoupon.pkpass manifest.json pass.json signature \
logo.png logo@2x.png icon.png icon@2x.png strip.png strip@2x.png
就是這樣——你完成了一張 Pass。
寫一封郵件,把 .pkpass 當附件寄給自己在 iOS 6 裝置上設定的信箱。
打開郵件,點擊附件,Passbook 就會彈出來:
按下右上角 Add,你會看到一張精緻的動畫把 Pass 收進 Passbook。退出郵件、開啟 Passbook,這就是你的第一張 Pass。
點擊右下角的斜體「i」可以翻到 Pass 背面。
jsonlint.com 貼上去驗證,最常見的錯誤是多餘或缺少逗號。passcertificate.pem 與 passkey.pem 必須成對。想看更多範例,可用手機瀏覽器造訪 passk.it/samples。下半部會進一步談 Pass 的動態更新與推送通知機制。