Passbook学习笔记

一、Passbook是什么

Passbook是苹果在IOS6推出的新功能，可以将航空公司的登机牌、电影票礼品卡等各种券整归到一处，有了它，我们出门的时候就不用带上一堆的票据了。去纸质化是未来信息传播的一大发展趋势，所以Passbook的推出可谓很有前瞻性。刚好项目里面用到了，就用心看看，将经验和大家分享。

其实关于Passbook，网上已经有很多不错的教程了，比如raywenderlich上的这两篇：

• iOS 6 Passbook 入门 1/2
• iOS 6 Passbook 入门 2/2
  

讲的非常详细，而本文着重介绍有些值得注意的点，或文章中没写的内容。

二、特性

1、可以设置时间和位置参数

当为Passbook设置了时间和位置参数，指定的时间到了或者用户抵达指定的位置，Passbook可以自动提醒用户有可用的Passbook

2、可更新

已经添加的Passbook，当有更新，比如登机牌上的起飞时间晚点了，Passbook拥有对已添加Passbook的更新机制。其中更新的方式有两种：

• 自动更新
• 用户手动下拉更新

见下图所示：

3、系统要求

使用 iOS 6 或更高版本的 iPhone 或 iPod touch

4、Passbook可以不依赖app

Passbook可以没有客户端，因为我们手工就可以制作一个Passbook，并且可以添加到Passbook列表中，当然前提是我们要有对应的证书。

5、有三种添加方式

• 邮件
• web浏览器
• 客户端

三、类型划分

1、五种类型

目前共支持五种类型，四个具体类型，一个通用类型：

• boardingPass（登机牌）
• coupon（优惠券）
• storeCard （购物券）
• eventTicket（活动门票）
• generic（通用）

对应的样式如下（图片来自这里）：

不同类型的Passbook的外形和界面布局都有所不同：

• 在外形上：

boardingPass：靠近顶部的位置左右两边各有一个缺口，两个缺口有一条直线连接

coupon：有锯齿状的边框

eventTicket：顶部有一个凹槽

不同风格的Passbook在是否有圆角上也有区别

• 界面布局

不同的类型在界面元素布局上也不尽相同

如何生成不同风格的Passbook会在下面的组成文件和文件格式部分详述。

四、内部结构

本节内容来自raywenderlich

Passbook文件的后缀名为.pkpass，其本质上上是一个.zip文件，如果将它重新命名为zip并且解压，就能得到下面的文件：

• pass.json – 关于这个 pass 的信息区域的描述，包括他们的内容， 和元信息，这是一个Passbook的核心部分。
• manifest.json – 这个文件描述了这个 pass 中的文件列表， 和每个文件的 SHA1 校验和。
• signature – manifest.json 一个分离的的 DER 签名， 通过苹果提供的证书生成的。
• background.png – 显示在 pass 正面的图片。
• background@2x.png – 视网膜屏尺寸的显示在 pass 正面的图片。
• logo.png – 在 pass 的头部区域显示的 logo。 苹果推荐的是一个纯色单色的 logo。 图片的尺寸由你决定， 但是高度不能大于 50px 以便适合头部的高度。
• logo@2x.png – 视网膜屏幕的 logo 图片
• icon.png – pass 的一个小图标， 当 pass 作为 email 附件的时候会被用到。 在写这篇教程的时候， 还没有关于这个图片尺寸的文档，但看起来像是 29×29 像素(大尺寸的图标会被缩放，所以他们的显示效果也不错)。
• icon@2x.png – 视网膜版本的图标
• strip.png 和 strip@2x.png – 用作主条目的背景；仅用于优惠劵和购物券

Passbook的主要文件是  pass.json  这个 JSON 文件。 在它里面你声明了这个 Passbook正面和反面的所有信息； 我们还需要提供需要显示的图片(优惠券仅仅需要指定background.png和它的视网膜版本)；最终，还需要一个清单文件manifest.json，它包含了所有这些文件的 SHA1 校验和；另外还的有一个分开的签名文件signature， 签名文件用于验证这个 Passbook在创建之后没有被修改过。

五、pass.json文件

1、至少包含的字段

作为一个Passbook最核心的部分，它决定显示的内容和位置布局。如下例所示，所有Passbook都必须包含的字段有以下几个：

<span style="word-break:break-all">{
  "formatVersion" : 1,
  "passTypeIdentifier" : "pass.com.lashou.passbook",
  "serialNumber" : "gT6zrHkaW",
  "teamIdentifier" : "4SK4K45JGW",
  "organizationName" : "Skyport Airways",
  "description" : "SFO to JFK",
}</span>

• formatVersion – 文件格式的版本，需要注意的是，必须用数字，而不是用字符串，否则会无效。
• passTypeIdentifier – 这是 Pass 的标识。 这个和 iOS 中的 bundle identifier 差不多。 稍后会更多的介绍关于这个标识的内容。
• serialNumber – 这个是 pass 的序列号。 你可以用任何方式生成它 – 它可以是数组， 例如 “00193”(注意，它仍然被写成字符串值)， 或者是字母和数字的组合，像是你在登机牌上面看到的序列号(例如 “XS83A”)。需要注意的是同一个passTypeIdentifier下面不能包含相同的serialNumber，否则会被认为是统一个Passbook，导致安装时发生覆盖。
• teamIdentifier – 这是苹果分配和每个 iOS 开发者的一个唯一的十个字符的标识。 如果你创建过你自己的 iOS 应用，你应该已经熟悉它了。 你可以登陆到 iOS Member Center 并点击你的组织名来找到你的 team identifier。你可以在 “Company/Organization ID” 标签后面找到它。 
• organizationName – 你的组织名称。
• description – 关于 pass 一个简短的介绍。

2、用于控制显示效果的字段

另外还可以通过下面的键值对调整Passbook的显示效果：

"logoText" : "Free Hugs LLC",
"foregroundColor" : "rgb(255, 255, 255)",
"backgroundColor" : "rgb(135, 129, 189)",
"labelColor" : "rgb(45, 54, 129)"

• logoText – 这是显示在 pass 头部并且紧挨着 logo 图片的文本。
• foregroundColor – 文本的颜色。
• backgroundColor – pass 的背景颜色。 Passbook 将会根据背景色的色值来创建一个漂亮的渐变效果， 这样来给 pass 的正面一个良好的视觉外观, 苹果推荐使用鲜艳的颜色。
• labelColor – 根据你的背景颜色，pass 上面的标签将会被渲染为一个和背景色反差比较大的颜色。如果你需要的话， 你可以为这些标签指定你自己的颜色。

下图更形象的展示了上述字段的作用效果：

3、条形码

条形码是Passbook的一大特点，在扫一扫随处可见的今天，增加条形码功能无疑很明智。为Passbook增加条形码的json结构如下：

"barcode" : {
        "message" : "All you need is love",
        "format" : "PKBarcodeFormatPDF417",
        "messageEncoding" : "iso-8859-1"
}

• message – 这是条形码包含的数据。 它可以是唯一的编码， 持有者的客户ID， 或者其他任何东西。 在 Free Hug 的例子中， 它仅仅是一个文本消息，用来让持有者得到一个免费的拥抱。
• format – 条形码的格式名称。 用来生成 2D 条形码。
• messageEncoding – 用来解码消息的文本编码名称。 如果你使用非拉丁语言， 你将要用 UTF8 或者其他形式适合你的文本编码（如果你私用标准的英语和数字， 它的默认值是 “iso-8859-1”）。

关于条形码，有两点说明：

①我们只需要将我们在条形码中包含的信息放在message字段中，Passbook会自动为我们生成一张二维码图片，不可谓不神奇。
②目前Passbook条形码只支持三种较新的格式：PKBarcodeFormatQR，PKBarcodeFormatPDF417和PKBarcodeFormatAztec。即上面的format字段可以选取上述三个值中的一个作为自己得编码格式。

4、如何决定不同的Passbook风格

前面讲过Passbook共有五种不同的类型，如何区别实现它们呢？我们需要写这样的一个json结构，以boardingPass类型为例：

"boardingPass" : {
    "transitType" : "PKTransitTypeAir",
    "headerFields" : [
      {
        "label" : "GATE",
        "key" : "gate",
        "value" : "23",
        "changeMessage" : "Gate changed to %@."
      }
    ],
    "primaryFields" : [
      {
        "key" : "depart",
        "label" : "SAN FRANCISCO",
        "value" : "SFO"
      },
      {
        "key" : "arrive",
        "label" : "NEW YORK",
        "value" : "JFK"
      }
    ],
    "secondaryFields" : [
      {
        "key" : "passenger",
        "label" : "PASSENGER",
        "value" : "John Appleseed"
      }
    ],
    "auxiliaryFields" : [
 {
        "key" : "expires",
        "label" : "EXPIRES",
        "value" : "2 weeks"
      },
      {
        "key" : "datefdasf",
        "label" : "DATE",
        "value" :  "7/22",
      },{
        "key" : "expires",
        "label" : "EXPIRES",
        "value" : "2 weeks"
      },
      {
        "key" : "datefdasf",
        "label" : "DATE",
        "value" :  "7/22",
      }
    ],
    "backFields" : [
      {
        "key" : "terms",
        "label" : "TERMS",
        "value" : "Extension of Validity\nIf after having commenced your journey."
      }
    ]
  }

当然不同类型的Passbook会以对应的不同的key包含headerFields、primaryFields、secondaryFields、auxiliaryFields、backFields等字段。

各个字段对应的位置如下图所示：

• 顶部抬头（图中区域1，对应headerFields）. 顶部条包含了一个容易辨认的 Logo 和一个公司名称。 头部区域用户会在 Passbook 的列表中看到。 它包含了你要给用户提供的最关键的信息， 这样他们就可以辨认出他们需要的 pass 了。

• 主体区域（图中区域2，对应primaryFields）. 这部分包含了 pass 的内容。 每个 pass 在这个区域都有不同的风格， 它通常在 pass 打开时显示最主要的信息。 像是 “打折 20%”， “一杯免费咖啡”, “余额 $120″ 或是其他这类的信息非常有用。
• 附加信息（图中区域3和4，分别对应auxiliaryFields和secondaryFields）. 第三个部分用作附加信息 – 仍然是很重要的资料(例子中的促销的有效性和开始时间)， 但绝对不像关于 pass 是什么东西这样的信息那么重要。
• 条形码（图中区域5，对应barcode）.条形码包含了编码后的信息， 可以通过条形码扫描器很容易的将这些信息转移到其他系统中。在上面的例子中， 条形码包含了一个加密代码。 档被扫描器节解码后， 它会给这个 pass 的所有者一个免费的拥抱(立即发送)。

上面的json文件中有这样的结构：

{
        "key" : "depart",
        "label" : "SAN FRANCISCO",
        "value" : "SFO"
}

这些字段的意义如下：

• key – 字段的名称，不会显示到界面中，而且我试过key重复也没问题。
• label – 字段的副区域文本，会显示在主文本区域的上边。
• value – 字段的主区域文本，会显示在副区域文本的下面。

至此，Passbook包含的全部文件都讲完了。