您现在的位置: IOS教程網 >> IOS系統 >  >> iOS 程式開發 >> iOS 開發綜合

iOS 6 Passbook 入門(上):從零手刻一張 .pkpass

編輯:iOS 開發綜合

Passbook 是 iOS 6 最受矚目的新技術,它把「票券、集點卡、登機證」這類紙本物品搬進手機。而它與你以往用過的蘋果技術最大的不同在於:蘋果不處理後端。Pass 檔案由你自己產生、自己簽章、自己派送,用什麼語言、什麼架構都隨你。

換個角度說,你對最終呈現的控制權遠高於其他蘋果 API。

本篇(上半部)的目標:從一個空白檔案開始,手工做出一張完整、經過數位簽章的 Pass。

Pass 是什麼

蘋果的官方說法是「你口袋裡的一切東西」。它可以是電影票、咖啡店的集點卡、健身房會員證、演唱會門票——任何原本印在紙上的東西。

如上圖的「Free hug!」優惠券,可以輕易辨識出幾個元素:最上方是 logo 與公司名稱,中間清楚描述這張 Pass 的用途與有效時間,最下方則是條碼。

Pass 的四個組成區塊

  1. 頂部抬頭(Header)——包含 logo 與公司名稱。這是用戶在 Passbook 列表中辨識 Pass 的依據,必須放最關鍵的資訊。
  2. 主要區域(Primary)——Pass 打開後視覺重心所在,通常放最重要的內容,例如「打折 20%」、「一杯免費咖啡」、「餘額 $120」。
  3. 附加資訊(Secondary / Auxiliary)——重要性較低但仍需要的資料,例如促銷有效期、開始時間。
  4. 條碼(Barcode)——承載機器可讀的編碼資訊,掃描後可傳入其他系統完成核銷。

五種 Pass 類型

蘋果預定義了四種 Pass,加上一種通用型:

  • 優惠券(Coupon)
  • 登機牌(Boarding Pass)
  • 商店卡/集點卡(Store Card)
  • 活動門票(Event Ticket)
  • 通用型(Generic)

為什麼要分這麼多種?因為不同用途需要不同的版面配置。健身房會員證需要放照片,音樂會門票不需要;登機牌需要兩欄來放出發與抵達城市。

差異不只在使用者看得到的配置,連圓角、剪紙缺口等視覺細節都不同。因此選對 Pass 類型是設計的起點。

.pkpass 的真面目

Pass 以副檔名 .pkpass 的檔案形式交付給使用者(pk = PassKit)。而 .pkpass 其實就是一個 ZIP 壓縮檔——改名解壓後會看到這些內容:

  • pass.json——Pass 的主資料檔,描述正反面所有欄位內容與中繼資訊。
  • manifest.json——列出包內所有檔案及其 SHA1 校驗碼。
  • signature——manifest.json 的 DER 格式分離簽章,由你的 Pass 憑證產生。
  • background.png / @2x.png——Pass 背景圖(含 Retina 版)。
  • logo.png / @2x.png——頭部 logo。蘋果建議使用單色,高度不得超過 50px。
  • icon.png / @2x.png——小圖示,Pass 作為郵件附件時使用,約 29×29 像素。
  • strip.png / @2x.png——主要欄位的背景條,僅優惠券與商店卡使用。

寫第一份 JSON

在 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"
}

各欄位意義:

  • formatVersion——檔案格式版本,目前為 1。必須是數字,寫成字串會導致檔案失效。
  • passTypeIdentifier——Pass 的類型識別碼,概念近似 iOS 的 Bundle ID。
  • serialNumber——Pass 的序號,格式自訂("001"、"XS83A" 皆可),用來區分同類型的不同 Pass。
  • teamIdentifier——蘋果分配給每個開發者的十碼識別字,用來把 Pass 關聯到你的開發者帳號。
  • organizationName——組織名稱。
  • description——Pass 的簡短說明。

為什麼用 JSON 而不是 plist?因為 Pass 多半由 Web 伺服器動態產生,而 PHP、.NET、Ruby、Python 對 JSON 的支援都相當成熟。選 JSON 是為了讓任何後端技術都能輕鬆產出 Pass。

申請 Pass 憑證

登入 iOS Developer Portal,開啟 iOS Provisioning Portal,左側會看到 Pass Type IDs 項目。點進去後選擇 New Pass Type ID:

  • Description 填 Free Hug Pass
  • Identifier 填 pass.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)"
  • logoText——顯示在 logo 旁的文字。
  • foregroundColor——前景文字顏色。
  • backgroundColor——背景色。Passbook 會依此自動產生漸層,蘋果建議使用鮮豔的顏色。
  • labelColor——欄位標籤顏色,可自訂以確保與背景有足夠對比。

加入條碼

PassKit 支援三種二維條碼格式:QR、PDF417、Aztec。不支援傳統的一維條碼。

在 barcode 字典的結尾大括號後補上逗號,並貼入:

"barcode" : {
    "message" : "All you need is love",
    "format" : "PKBarcodeFormatPDF417",
    "messageEncoding" : "iso-8859-1"
}
  • message——條碼承載的資料,可以是唯一編碼、會員 ID 或任何字串。
  • format——PKBarcodeFormatQR / PKBarcodeFormatPDF417 / PKBarcodeFormatAztec 擇一。
  • messageEncoding——解碼時使用的文字編碼。非拉丁語言請改用 UTF-8。

目前 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 是陣列,因為每個區塊可以顯示一個或多個欄位,需要有序清單來決定先後。陣列中每個字典描述一個欄位:

  • key——欄位名稱,必須唯一,用於後續更新時定位。
  • label——欄位標籤,以小字顯示。
  • value——欄位內容,以大字體顯示。

加入圖片素材

把 PassAssets.zip 解壓後的 PNG 檔全部放進你的 Pass 工作目錄即可。

不需要在 pass.json 中寫任何圖片路徑——Passbook 依標準命名規則自動載入 icon.png、logo.png、strip.png 及各自的 @2x 版本。

注意:圖片必須匯出為 PNG24 格式。較小尺寸的 PNG8 在 Passbook 中不會顯示,這是個很容易浪費半小時的坑。

產生 manifest.json

這個檔案列出包內所有檔案及其 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 是私鑰密碼。

打包成 .pkpass

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 背面。

沒成功?檢查這幾點

  • JSON 格式是否合法——用 jsonlint.com 貼上去驗證,最常見的錯誤是多餘或缺少逗號。
  • manifest 是否與 pass.json 一致——只要在算完 SHA1 之後動過 pass.json,就一定失效,必須重算。
  • 圖片是否為 PNG24——PNG8 不會顯示。
  • 憑證與私鑰是否正確拆出——passcertificate.pem 與 passkey.pem 必須成對。
  • zip 是否包含 signature——少了它 Passbook 一律拒收。

想看更多範例,可用手機瀏覽器造訪 passk.it/samples。下半部會進一步談 Pass 的動態更新與推送通知機制。

  1. 上一篇文章:
  2. 下一篇文章:
蘋果刷機越獄教程| IOS教程問題解答| IOS技巧綜合| IOS7技巧| IOS8教程
Copyright © IOS教程網 All Rights Reserved