苹果钱包（AppleWallet）接入操作手册，超详细

本是古典何须时尚 2023-09-30 17:05 14阅读 0赞

## 一、写在前面 ##

### 1.1 起源 ###

最近有一点忙，更新博客出现了一些延迟。由于在工作中使用了Apple Wallet，所以在结束后准备以此记录一下。希望后面有要做此功能的同学，能够有所启发，觉得有帮助的，记得`点赞收藏关注`哦~

### 1.2 Apple Wallet 扫盲： ###

#### 1.2.1 什么是Apple Wallet? ####

*  总体来说：苹果钱包是Apple推出的软件，可以用于集中保管和使用的信用卡、借记卡、交通卡、登机牌、活动门票、学生证等等。全都收纳在您 iPhone 或 Apple Watch 的“钱包”中。
 *  简单来说：我们日常会办理非常多的卡片，比如银行卡、礼品卡、购物卡、会员卡等等，日常出行中这些卡片不易携带，但是又不可或缺。使用Apple Wallet能够将这些卡片装入Apple Wallet 这个软件中，更加方便快捷；

#### 1.2.2 使用Apple Wallet 的优点 ####

*  从用户的角度：
    
     *  方便，使用apple wallet 卡片能够不用带实体卡
     *  使用简单，只需要扫描即可添加到设备中
     *  不易丢失，卡片能够通过icloud 同步，随时保存和分享
     *  新颖，与传统的实体卡更进一步
     *  管理方便，一个app就可以管理所有的卡片；
     *  能够查看更多的信息，卡片还能够随时更新和获取推送；
 *  从企业的角度：
    
     *  扩展业务，丰富使用场景，比竞品更多竞争力。
     *  增强用户体验，随时随地能够使用apple wallet 卡片来进行交易、认证、提醒等；
     *  独立使用，即便用户不下载企业应用、登录企业网站，依然可以在apple wallet中获取到企业生产的礼品卡，并随时获取最新内容；
     *  成本低，通过直接与Apple Wallet 集成，无缝衔接。Apple Wallet 的后期生成、更新不会收费。
     *  提高产品能力，比如机票卡片能够让用户及时收到飞机起飞前的通知提醒，会员卡可以让用户不需要带着实体卡就可以进店结账消费；

#### 1.2.2 我们接入了Apple Wallet 能够做什么？ ####

Apple Wallet 为我们提供了丰富的卡片场景，主要的卡片类型有以下几种：

![format_png][]

> 简单来说，提供的这几种通行证（Apple Wallet 卡片）区分的类型只是为我们描述了具体的使用场景。我们可以根据实际需要来选择合适的卡片。

#### 1.2.3 什么是通行证？ ####

*  上面提到了，通行证就是Apple Wallet 的卡片。同时也是我们发给用户、用户使用的卡片的统称；它的具体形式可以是礼品卡、活动门票等；

#### 1.2.4 如何选择合适的通行证？ ####

*  对于通行证来说，不同的通行证类型卡片上展示的字段存在差异，同时排列的位置也会有一些区别。所以我们只需要根据实际要展示的元素，选择合适的通行证即可；
 *  如果是要做某一个通行证，选择对应类型的通行证无法满足要求的话，我们可以选择通用通行证，它往往卡片的字段更多，能容易满足要求；

#### 1.2.5 如何生成和使用通行证？ ####

*  如何生成通行证：
    
     *  注册成为Apple Developer
     *  申请Apple Wallet 安全证书（一般有效期为一年）
     *  设计礼品卡样式，可点击查看[官方参考文档][Link 1]
     *  将安全证书放入你的项目工程中，并引用jpasskit 工程创建礼品卡文件；
     *  将此文件传给调用方即可使用。这个接口我们可以使用 `Add to Apple Wallet` 图标来做触发，可点击查看[官方参考文档][Link 2]
 *  如何传递通行证：
    
     *  在手机端上来说，用户点击了`Add Apple Wallet`图标后触发调用后端接口，拿到了 xxx.pkpass 的通行证，使用Safari 浏览器会自动识别，并在用户允许后添加至用户苹果设备的Apple Wallet中；
     *  在Web端上来说，我们可以使用二维码来做展示；当用户点击了`Add Apple Wallet`图标后会显示一个二维码，用户通过使用原生相机扫描后可以跳转至Safari 浏览器触发后端接口，然后拿到通行证后添加至Apple Wallet；
 *  如何添加通行证：
    
     *  对于用户来说，拿到通行证后会出现如下的预览界面，用户点击**添加**之后即可加入到自己的Apple Wallet 中：
        
         *  ![format_png 1][]
     *  对于开发人员来说，需要使用jpasskit 来生成通行证，然后再发送给页面即可；后面会详细介绍这部分内容；
 *  如何使用通行证：
    
     *  主要看通行证对于企业来说，用于什么目的，做对应的查看、使用、提醒等等即可；
     *  比如登记牌卡片，对于航空公司来说可以设置地理位置，当客户到达机场能够自动识别并对应处理，也可以在飞机起飞前40分钟对用户提醒，提醒用户及时登机等；（礼品卡支持地理位置、通知、甚至NFC功能）
 *  如何更新通行证
    
     *  对于用户来说，只需要下拉刷新即可更新。或者用户在企业系统中对应礼品卡数据发生了变更会自动推送更新；对于后者，比如用户使用礼品卡进行了消费，那么礼品卡的余额会发生扣减，服务器会同步信息到Apple Wallet 中；
     *  对于开发人员来说，我们关注的也只有手动更新和自动更新两种形式；一种是用户手动下拉刷新，一种是服务器推送至手机；实现细节后面会进行详细介绍；
 *  如何删除通行证：
    
     *  对于用户来说，只需要简单的在Apple Wallet删除对应通行证即可；

### 1.3 前置准备 ###

*  Apple Developer Account： 对于前置准备，我们最需要的就是Apple 开发者账号，这个可以请公司对应人员帮忙注册；
 *  安全证书：注册账号之后，需要在Apple Developer 中生成安全证书，它用于与Apple Wallet 推送通知、生成通行证能够被Apple 设备信任的要素；
 *  证书形式如下，有效期一般为一年，需要定时替换最新：
    
    ![format_png 2][]

> 此步骤可以请公司内相关人员帮忙注册和生成，同时网上相关的资料应该很多，此文不加赘述；

## 二、创建通行证卡片 ##

### 2.1 理论知识 ###

1.  通行证的创建从原理上来说很简单
    
     *  前端页面需要使用官方的`Add to Apple Wallet`图标来支持Apple Walllet功能
     *  后端提供一个接口，当用户点击`Add to Apple Wallet`图标后会调用这个接口来获取一个通行证文件；
     *  这个通行证文件是一个压缩文件，像这样：
        
         *  ![format_png 3][]
         *  我们将其pkpass 后缀修改为zip，可以将其解压，能够看到里面的结构；
     *  如何创建这样的一个通行证呢？
        
        1.  首先设计好通行证的样式和字段，设计好之后就知道了通行证的预期样式是什么样的了；
        2.  然后引入[jpasskit][] 依赖到项目中；
        3.  再然后将安全证书导入到resource 目录中；
        4.  最后就可以使用jpasskit 的工具类`PKFileBasedSigningUtil`调用`createSignedAndZippedPkPassArchive`方法创建通行证字节码数组；
        5.  将字节码数组写入流，并发送给前端；
2.  接下来我将用实际代码演示这个过程；

### 2.2 代码演示 ###

1.  设计通行证，点击查看[官方参考文档][Link 1]
2.  引入[jpasskit][] 依赖到项目中：

<dependency>
        <groupId>de.brendamour</groupId>
        <artifactId>jpasskit</artifactId>
        <version>0.1.2</version>
    </dependency>
    复制代码

> 如果出现找不到类等情况，就看一下是否缺失某些依赖，因为jpasskit里面还关联了其他的一些依赖，但是目前项目中没有的；

1.  将证书导入项目中，如图所示：
    
    ![format_png 4][]
2.  加载安全证书
    
    1.  使用本地真实路径加载证书（可以本地测试使用, 其中PROJECT\_PATH可以换成真实的全路径）：
        
            String privateKeyPassword = "xxxx"; // the password you used to exportprivateKeyPath
            String appleWWDRCA = PROJECT_PATH + "AppleWWDRCA.cer"; // this is apple's developer relation cert
            String privateKeyPath = PROJECT_PATH + "passtype_key_dev.p12"; // the private key you exported from keychain
            try {
                PKSigningInformation pkSigningInformation = PKSigningUtil.
                        loadSigningInformationFromPKCS12FileAndIntermediateCertificateFile(
                                privateKeyPath, privateKeyPassword, appleWWDRCA);
            } catch (Exception e){
            }
            复制代码
    2.  使用流的形式加载证书（可以用于服务器环境）
        
            // 这里密码是你自己的证书密码
                public static final String PRIVATE_KEY_PASSWORD = "xxxx";
                public static final String APPLE_WWDRCA = "AppleWWDRCA.cer";
                public static final String PASSTYPE_KEY_DEV = "passtype_key_dev.p12";
            
                @PostConstruct
                public void init() {
                    try {
                        appleWWDRCA = ClassUtils.getDefaultClassLoader().getResourceAsStream(APPLE_WWDRCA);
                        privateKeyPath = ClassUtils.getDefaultClassLoader().getResourceAsStream(PASSTYPE_KEY_DEV);
                        pkSigningInformation = new PKSigningInformationUtil()
                                .loadSigningInformationFromPKCS12AndIntermediateCertificate(privateKeyPath
                                        , PRIVATE_KEY_PASSWORD,
                                        appleWWDRCA);
                    } catch (Exception e) {
                    }
                }
            复制代码

> 如果是本地测试，直接用方法1，要发布到测试环境了可以用方法二来创建证书；

1.  创建通行证卡片，以下为礼品卡的示例代码

// 这里PKPass 是通行证对象，我们需要填充里面的内容；
     PKPass pass = new PKPass();
     // 固定设置1
     pass.setFormatVersion(1);
     // 这个字段用户apple wallet 更新，如果不需要Apple Wallet 更新可以去掉，目前只做创建也可以先删除调
     // pass.setWebServiceURL(new URL("https://xxxx:xxx/"));
     // 这个信息从Apple Developer中获取，对应替换成自己的
     pass.setPassTypeIdentifier("pass.com.xxx.xxx.xxx");
     // 这个信息从Apple Developer中获取, 对应替换成自己的
     // pass.setAuthenticationToken("xxxxxxxxxxxxxxxxx");
     String serialNumber = UUID.randomUUID().toString();
     // 这个是通行证唯一id，如果每次生成都是一个新的，那么可以每次重新New UUID。如果要去重，就需要保存这个ID，将它与业务id数据形成一对一关系；
     pass.setSerialNumber(serialNumber);
     // 来源于Apple Developer
     pass.setTeamIdentifier("xxxxxx"); // replace this with your team ID
     // 以下的信息都是通行证中的通用基本元素
     pass.setOrganizationName("Org name");
     pass.setBackgroundColor("#0F0242");
     pass.setForegroundColor("#FFFFFF");
     pass.setLabelColor("#FFFFFF");
     pass.setDescription("some description");
     pass.setLogoText("");
     pass.setExpirationDate(new Date());
     // 通行证中的二维码
     PKBarcode barcode = new PKBarcode();
     barcode.setFormat(PKBarcodeFormat.PKBarcodeFormatQR);
     barcode.setMessage("123456789");
     barcode.setMessageEncoding(Charset.forName("UTF-8"));
     pass.setBarcodes(Arrays.asList(barcode));
     // 这里的是通行证中的一些指定通行证的对应元素；如果不是使用PKStoreCard,替换成对应的就可以，然后根据自己预先设计的礼品卡样式来填充即可；
     PKStoreCard pkStoreCard = new PKStoreCard();        
     PKField pkField = new PKField();
     pkField.setKey("CardName");
     pkField.setValue("JD E-card");
     pkStoreCard.setPrimaryFields(ImmutableList.of(pkField));
     pass.setStoreCard(pkStoreCard);
     
     // 地理位置，可以不设置；
     PKLocation location = new PKLocation();
     location.setLatitude(xxxx); // replace with some lat
     location.setLongitude(xxxx); // replace with some long
     List<PKLocation> locations = new ArrayList<PKLocation>();
     locations.add(location);
     pass.setLocations(locations);
     
     // 这里 isValid可以判断前面的元素是否都满足了，如果通过了就继续填充logo、图标等图形；
     if (pass.isValid()) {
         PKPassTemplateInMemory pkPassTemplateInMemory = new PKPassTemplateInMemory();
         // 这里PROJECT_PATH 替换为自己的项目文件路径
         pkPassTemplateInMemory.addFile(PKPassTemplateInMemory.PK_ICON, PROJECT_PATH + "images" + FILE_SEPARATOR + "icon.png");
         pkPassTemplateInMemory.addFile(PKPassTemplateInMemory.PK_ICON_RETINA, PROJECT_PATH + "images" + FILE_SEPARATOR + "icon@2x.png");
         pkPassTemplateInMemory.addFile(PKPassTemplateInMemory.PK_ICON_RETINAHD, PROJECT_PATH + "images" + FILE_SEPARATOR + "icon@3x.png");
         PKFileBasedSigningUtil pkSigningUtil = new PKFileBasedSigningUtil();
         // 传入通行证内容、通行证图片模板、和通行证安全证书，生成通行证文件byte[] 数据；
         byte[] signedAndZippedPkPassArchive = pkSigningUtil.createSignedAndZippedPkPassArchive(pass, pkPassTemplateInMemory, pkSigningInformation);
    }
    复制代码

1.  将文件发送给前端

private void sendHttpResponse(HttpServletResponse httpServletResponse, ServletOutputStream out, byte[] signedAndZippedPkPassArchive) throws IOException {
        httpServletResponse.setHeader("Cache-Control", "no-cache,no-store");
        httpServletResponse.setHeader("Pragma", "no-cache");
        httpServletResponse.setHeader("Expires", "0");
        httpServletResponse.setHeader("Content-Disposition", "attachment; filename=\"pass.pkpass\"");
        httpServletResponse.setContentType("application/vnd.apple.pkpass");
        httpServletResponse.setContentLength(signedAndZippedPkPassArchive.length);
        httpServletResponse.setHeader("last-modified", String.valueOf(System.currentTimeMillis()));
        out.write(signedAndZippedPkPassArchive);
        out.flush();
    }
    复制代码

### 2.3 注意事项 ###

1.  卡片标题会自动变为大写；
2.  设置了过期日期的卡片如果过期了则不支持更新
3.  卡片本身可以设置多语言等丰富形式，建议可以找一些[第三方设计平台][Link 3]设计好了，然后解压通行证文件解析有哪些字段；
4.  IPAD 设备不支持礼品卡

## 三、更新通行证 ##

### 3.1 理论知识 ###

*  通行证的更新要比通行证的创建要复杂一点。
    
     *  更新逻辑是：我们在创建通行证时设置我们服务器的回调地址：`pass.setWebServiceURL(new URL("https://xxxx:xxx/"));`
     *  用户下拉刷新会直接调用我们`获取最新通行证接口`
     *  如果是服务器推送的话我们会`先发送设备token给苹果APNS`，然后APNS会通知对应的设备来查询我们`是否存在需要更新的通行证接口`,如果有的话，就会继续调用`获取最新通行证接口`达到更新目的；
     *  当用户删除通行证时，我们也需要将它的设备token和绑定信息删除掉，以便于下次重新添加时注册；
 *  如果增加用户在Apple Wallet 下拉刷新的功能，那么只需要提供一个下拉刷新的接口即可，它的全路径是： `回调服务器地址/v1/passes/{passTypeIdentifier}/{serialNumber}`，在这个接口中Apple 会传入要更新的通行证id，我们则根据通行证id查询到该通行证绑定的业务最新数据，并重新生成通行证（重复之前创建通行证的部分步骤）发送给**Apple 设备** ；
 *  如果增加服务器推送，让对应用户的对应设备自动调用获取最新通行证接口（也就是步骤2的接口），我们需要增加五个接口来完成这一个完整的功能；它们分别是：
    
     *  注册设备接口，当添加时只要设置了回调地址，客户手机会自动访问这个接口将他的设备token发送给我们进行保存；
     *  检查是否存在需要更新的通行证接口，服务器推送更新到APNS时，用户手机会访问这个接口来检查是否存在需要被更新的通行证，如果存在的话，就会调用获取最新通行证接口；
     *  获取最新通行证接口，这个接口会像创建通行证一样，获取最新的信息并返回；它跟手动下拉刷新访问的接口是同一个
     *  删除设备接口，在这个里面我们需要删除对应的设备信息，以便于下次的注册使用；
 *  这里描述可能有一些宽泛，同学们可以查看官方文档以获取详细内容：
    
     *  [接口设计规则][Link 4]
     *  [通行证设计、创建、更新指南][Link 5]

### 3.2 代码演示 ###

import com.xxx.service.DemoService;
    import com.xxx.service.RequestBodyUtils;
    import com.alibaba.fastjson.JSON;
    import com.google.common.collect.ImmutableList;
    import com.turo.pushy.apns.PushNotificationResponse;
    import com.turo.pushy.apns.util.SimpleApnsPushNotification;
    import com.turo.pushy.apns.util.concurrent.PushNotificationFuture;
    import de.brendamour.jpasskit.apns.PKSendPushNotificationUtil;
    import io.swagger.annotations.Api;
    import io.swagger.annotations.ApiOperation;
    import lombok.AllArgsConstructor;
    import lombok.Data;
    import lombok.NoArgsConstructor;
    import org.springframework.beans.factory.annotation.Autowired;
    import org.springframework.http.HttpStatus;
    import org.springframework.http.ResponseEntity;
    import org.springframework.web.bind.annotation.*;
    import org.springframework.web.context.request.RequestAttributes;
    import org.springframework.web.context.request.RequestContextHolder;
    import org.springframework.web.context.request.ServletRequestAttributes;
    import org.springframework.web.context.support.HttpRequestHandlerServlet;
    import springfox.documentation.annotations.ApiIgnore;
    
    import javax.servlet.http.HttpServletRequest;
    import javax.servlet.http.HttpServletResponse;
    import java.io.BufferedReader;
    import java.io.IOException;
    import java.io.InputStreamReader;
    import java.io.Serializable;
    import java.util.Date;
    import java.util.List;
    
    @RestController
    @RequestMapping
    @Api(tags = {"ceshi"})
    public class DemoController {
    
        @Autowired
        private DemoService demoService;
    
        @GetMapping("addWallet")
        @ResponseBody
        @ApiOperation("添加到苹果钱包中")
        public void addWallet(@ApiIgnore HttpRequestHandlerServlet httpRequest, @ApiIgnore HttpServletResponse httpResponse) {
            // 根据之前的创建通行证生成完善这个接口就可以；
        }
    
    
        /**
         * 注册设备以接收通行证的推送通知
         *
         * @param deviceLibraryIdentifier 用于在未来请求中识别和验证此设备的唯一标识符。
         * @param passTypeIdentifier      通行证的类型，在通行证中指定。
         * @param serialNumber            通行证的序列号，在通行证中指定。
         * @param version                 协议版本——当前为 v1。
         *                                说明：此处可能用于将设备编号等信息记录；
         *                                header ： 提供了 Authorization 标头；它的值是单词ApplePass，后跟一个空格，然后是通行证中指定的通行证的授权令牌。
         *                                这里授权令牌看要不要进行保存；
         *                                如果此设备的序列号已注册，则返回 HTTP 状态 200。
         *                                如果注册成功，则返回 HTTP 状态 201。
         *                                如果请求未授权，则返回 HTTP 状态 401。
         *                                否则，返回适当的标准 HTTP 状态。
         *                                这里可能要创建一个设备表，用于记录用户是否已经注册，如果注册成功则返回success
         */
        //Registering a Device to Receive Push Notifications for a Pass
        @PostMapping("v1/devices/{deviceLibraryIdentifier}/registrations/{passTypeIdentifier}/{serialNumber}")
        @ApiOperation("注册设备")
        public ResponseEntity registrationWallet(@PathVariable("deviceLibraryIdentifier") String deviceLibraryIdentifier,
                                                 @PathVariable("passTypeIdentifier") String passTypeIdentifier,
                                                 @PathVariable("serialNumber") String serialNumber,
                                                 @RequestBody PushToken pushToken
        ) {
            // 这里的pushToken需要保存起来，然后推送更新时，将这个pushToken带上即可；
            System.err.println("time:"+ new Date());
            System.err.println("[暗余]. 注册设备");
            System.err.println("deviceLibraryIdentifier:"+deviceLibraryIdentifier);
            System.err.println("passTypeIdentifier:"+passTypeIdentifier);
            System.err.println("serialNumber:"+serialNumber);
            System.err.println("pushToken:"+ JSON.toJSONString(pushToken));
            return new ResponseEntity(HttpStatus.OK);
        }
    
    
    
        /**
         * 获取与设备关联的通行证的序列号
         *
         * @param version                 协议版本——当前为 v1。
         * @param deviceLibraryIdentifier 用于识别和验证设备的唯一标识符。
         * @param passTypeIdentifier      通行证的类型，在通行证中指定。
         * @param tag                     来自先前请求的标签。（可选的）
         *                                如果passesUpdatedSince参数存在，则仅返回自 指示的时间以来已更新的通行证tag。否则，返回所有通行证。
         * @return 如果有匹配的通行证，则返回 HTTP 状态 200 以及带有以下键和值的 JSON 字典：
         * lastUpdated（细绳）
         * 当前的修改标签。
         * <p>
         * serialNumbers（字符串数组）
         * 匹配通行证的序列号。
         * <p>
         * 如果没有匹配的通行证，则返回 HTTP 状态 204。
         * 否则，返回适当的标准 HTTP 状态
         */
        // Getting the Serial Numbers for Passes Associated with a Device
        @GetMapping("/v1/devices/{deviceLibraryIdentifier}/registrations/{passTypeIdentifier}")
        @ResponseBody
        @ApiOperation("获取与设备关联的通行证的序列号")
        public ResponseEntity getSerialNumber(
                @PathVariable("deviceLibraryIdentifier") String deviceLibraryIdentifier,
                @PathVariable("passTypeIdentifier") String passTypeIdentifier,
                @RequestParam(value = "passesUpdatedSince",required = false) String passesUpdatedSince
        ) {
            // 这里的pushToken需要保存起来，然后推送更新时，将这个pushToken带上即可；
            System.err.println("time:"+ new Date());
            System.err.println("[暗余]. 获取与设备关联的通行证的序列号");
            System.err.println("passTypeIdentifier:"+passTypeIdentifier);
    
            SerialNumberBo serialNumberBo = new SerialNumberBo();
            serialNumberBo.setLastUpdateTime("123455");
            serialNumberBo.setSerialNumbers(ImmutableList.of("aed1a60b-20fa-4346-8d26-43d8fe14f29d","123","456"));
    //        serialNumberBo.setSerialNumbers(ImmutableList.of("123"));
            return new ResponseEntity(serialNumberBo, HttpStatus.OK);
        }
    
        /**
         *
         * passTypeId 凭证的类型，从服务器中指定
         * serial 服务器分配给凭证模板的序列号。您可以通过调用 xxx 来获取它；getPassbookTemplate
         */
        /**
         * 获取最新版本的通行证
         *
         * @param version            协议版本——当前为 v1。
         * @param passTypeIdentifier 通行证的类型，在通行证中指定。
         * @param serialNumber       通行证中指定的唯一通行证标识符。
         *                           header: 提供了 Authorization 标头；它的值是单词ApplePass，后跟一个空格，然后是通行证中指定的通行证的授权令牌。
         *                           如果请求被授权，则返回 HTTP 状态 200 以及传递数据的有效负载。
         *                           如果请求未授权，则返回 HTTP 状态 401。
         *                           否则，返回适当的标准 HTTP 状态。
         *                           支持此端点上的标准 HTTP 缓存：检查If-Modified-Since标头，如果通道未更改，则返回 HTTP 状态代码 304。
         */
        @GetMapping("/v1/passes/{passTypeIdentifier}/{serialNumber}")
        @ResponseBody
        @ApiOperation("获取最新版本的通行证")
        public void pushWallet(
                @PathVariable("passTypeIdentifier") String passTypeIdentifier,
                @PathVariable("serialNumber") String serialNumber,
                @ApiIgnore HttpServletResponse httpResponse
        ) {
            // 这里的pushToken需要保存起来，然后推送更新时，将这个pushToken带上即可；
            System.err.println("time:"+ new Date());
            System.err.println("[暗余]. 获取最新版本的通行证");
    
            System.err.println("passTypeIdentifier:"+passTypeIdentifier);
            System.err.println("serialNumber:"+serialNumber);
            demoService.pushWallet(passTypeIdentifier, serialNumber, httpResponse);
        }
    
        /**
         * @param version                 协议版本——当前为 v1。
         * @param deviceLibraryIdentifier 设备库标识符  用于识别和验证设备的唯一标识符。
         * @param passTypeIdentifier      通行证的类型，在通行证中指定。
         * @param serialNumber            通行证中指定的唯一通行证标识符。
         *                                header: 提供了 Authorization 标头；它的值是单词ApplePass，后跟一个空格，然后是通行证中指定的通行证的授权令牌。
         *                                如果解除关联成功，则返回 HTTP 状态 200。
         *                                如果请求未授权，则返回 HTTP 状态 401。
         *                                否则，返回适当的标准 HTTP 状态。
         *                                <p>
         *                                服务器解除指定设备与通行证的关联，当通行证发生变化时，不再向该设备发送推送通知。
         */
    //    注销设备
        @ResponseBody
        @DeleteMapping("/v1/devices/{deviceLibraryIdentifier}/registrations/{passTypeIdentifier}/{serialNumber}")
        @ApiOperation("注销设备")
        public ResponseEntity unregisteringDevice(
                @PathVariable("version") String version,
                @PathVariable("deviceLibraryIdentifier") String deviceLibraryIdentifier,
                @PathVariable("passTypeIdentifier") String passTypeIdentifier,
                @PathVariable("serialNumber") String serialNumber
        ) {
            // 这里的pushToken需要保存起来，然后推送更新时，将这个pushToken带上即可；
            System.err.println("time:"+ new Date());
            System.err.println("[暗余]. 注销设备");
            System.err.println("version:"+version);
            System.err.println("deviceLibraryIdentifier:"+deviceLibraryIdentifier);
            System.err.println("passTypeIdentifier:"+passTypeIdentifier);
            System.err.println("serialNumber:"+serialNumber);
            return new ResponseEntity(HttpStatus.OK);
        }
    
       /**
         * 记录错误日志
         * @param version 版本号
         * @param request 日志信息
         * @return 默认成功
         */nseBody
        @RequestMapping(value = "/v1/log", method = RequestMethod.GET)
        public ResponseEntity<Void> log(
                @RequestBody LogContentRequest request
        ) {
            if (Objects.nonNull(request)) {
                System.out.println(JSON.toJSONString(request));
            }
            return new ResponseEntity<>(HttpStatus.OK);
        }
    
        public static String getRequestBody() throws IOException {
            RequestAttributes attributes = RequestContextHolder.getRequestAttributes();
            ServletRequestAttributes servletRequestAttributes = (ServletRequestAttributes) attributes;
            HttpServletRequest request = servletRequestAttributes.getRequest();
            BufferedReader reader = new BufferedReader(new InputStreamReader(request.getInputStream()));
            //读取输入流的内容转换为String类型IOUtils必须引入org.apache.dubbo.common.utils.IOUtils;包
            String body = RequestBodyUtils.read(reader);
            return body;
        }
    
    
        @Data
        @NoArgsConstructor
        @AllArgsConstructor
        static class SerialNumberBo implements Serializable{
            private String lastUpdateTime;
            private List<String> serialNumbers;
        }
    
        @Data
        @NoArgsConstructor
        @AllArgsConstructor
       static class LogContentRequest implements Serializable {
            private List<String> logs;
        }
    
        @Data
        @NoArgsConstructor
        @AllArgsConstructor
       static class PushToken implements Serializable {
            private String pushToken;
        }
    
        // 主动推送通知
        public static void main(String[] args) throws IOException {
    
            String privateKeyPath = "D:\\xxx\\passtype_key_dev.p12"; // the private key you exported from keychain
            String privateKeyPassword = "xxxx "; // the password you used to exportprivateKeyPath
            String pushToken = "xxx";
            PKSendPushNotificationUtil pkSendPushNotificationUtil = new PKSendPushNotificationUtil(privateKeyPath, privateKeyPassword);
            PushNotificationFuture<SimpleApnsPushNotification, PushNotificationResponse<SimpleApnsPushNotification>> simpleApnsPushNotificationPushNotificationResponsePushNotificationFuture =
                    pkSendPushNotificationUtil.sendPushNotificationAsync(pushToken);
            SimpleApnsPushNotification pushNotification = simpleApnsPushNotificationPushNotificationResponsePushNotificationFuture.getPushNotification();
            System.err.println(JSON.toJSONString(pushNotification));
        }
    }
    
    复制代码

### 3.3 注意事项 ###

*  通行证更新，需要使用https接口，并且证书认证应该是可信机构认证的；如果本地想进行测试的话，可以使用http，但是Iphone手机需要连接电脑开启开发者权限，在手机的开发者选项中允许HTTP请求即可；
 *  苹果定义的这几个接口，实际里面的内容需要我们根据我们自己的业务去完善。也就是说，从负责的内容来说，企业需要从生成、更新全流程把控自己的礼品卡，而Apple只提供用户的主动访问接口、APNS的通知，以及保证带了正确安全证书的通行证是可信的。
 *  更新存在延迟甚至丢包，所以不能保证每次都能成功更新，所以每个接口要保证其健壮性；

## 四、写在最后 ##

### 4.1 结尾 ###

这篇文章是博主实战得出的一些经验总结，如果有纰漏欢迎指出。写文不易，觉得不错的话麻烦点点关注鼓励一下哦，后续会继续更新原创精品内容！后面会继续讲Google Wallet 的部分，如果小伙伴谁遇到了问题可以留在评论区，我能解答的话会帮忙看一下；笔芯~

### 4.2 补充说明 ###

以下是我对Apple Wallet 的封装代码，有需要可供参考

import com.google.common.collect.ImmutableList;
    import com.google.common.collect.Lists;
    import de.brendamour.jpasskit.PKBarcode;
    import de.brendamour.jpasskit.PKField;
    import de.brendamour.jpasskit.PKPass;
    import de.brendamour.jpasskit.enums.PKBarcodeFormat;
    import de.brendamour.jpasskit.enums.PKDateStyle;
    import de.brendamour.jpasskit.enums.PKTextAlignment;
    import de.brendamour.jpasskit.passes.PKGenericPass;
    import de.brendamour.jpasskit.signing.PKFileBasedSigningUtil;
    import de.brendamour.jpasskit.signing.PKPassTemplateInMemory;
    import de.brendamour.jpasskit.signing.PKSigningException;
    import de.brendamour.jpasskit.signing.PKSigningInformation;
    import org.apache.commons.collections.CollectionUtils;
    import org.apache.commons.lang3.StringUtils;
    import org.springframework.http.HttpStatus;
    
    import java.io.IOException;
    import java.io.InputStream;
    import java.io.Serializable;
    import java.net.HttpURLConnection;
    import java.net.MalformedURLException;
    import java.net.URL;
    import java.nio.charset.StandardCharsets;
    import java.security.InvalidParameterException;
    import java.util.List;
    import java.util.Objects;
    import java.util.Optional;
    import java.util.UUID;
    
    /**
     * @author csdn 暗余
     */
    public  class AppleWallet {
    
        private final PKPass pkPass;
        private final String serialNumber;
        private final PKGenericPass pkGenericPass;
        private final List<PKField> headerFields;
        private final List<PKField> primaryFields;
        private final List<PKField> secondaryFields;
        private final List<PKField> auxiliaryFields;
        private final List<PKField> backFields;
        private PKSigningInformation pkSigningInformation;
    
        private final PKPassTemplateInMemory pkPassTemplateInMemory;
    
        private static final String VALID_ERROR = "The apple pass is NOT Valid!";
    
        public AppleWallet(String serialNumber) {
            pkPass = new PKPass();
            this.serialNumber = serialNumber;
            pkPass.setSerialNumber(serialNumber);
            pkGenericPass = new PKGenericPass();
            headerFields = Lists.newArrayList();
            primaryFields = Lists.newArrayList();
            secondaryFields = Lists.newArrayList();
            auxiliaryFields = Lists.newArrayList();
            backFields = Lists.newArrayList();
            pkPassTemplateInMemory = new PKPassTemplateInMemory();
        }
    
    
        public AppleWallet buildWhole(String backgroundColor, String foregroundColor, String labelColor, String description, String logoText) {
            pkPass.setBackgroundColor(backgroundColor);
            pkPass.setForegroundColor(foregroundColor);
            pkPass.setLabelColor(labelColor);
            pkPass.setDescription(description);
            pkPass.setLogoText(logoText);
            return this;
        }
    
        public AppleWallet buildQrCode(String message) {
            PKBarcode pkBarcode = new PKBarcode();
            pkBarcode.setFormat(PKBarcodeFormat.PKBarcodeFormatQR);
            pkBarcode.setMessage(message);
            pkBarcode.setMessageEncoding(StandardCharsets.UTF_8);
            pkPass.setBarcodes(ImmutableList.of(pkBarcode));
            return this;
        }
    
        public AppleWallet buildField(GenericPassEnum genericPassType, String keyField, String label, String value, PKDateStyle timeStyle, PKDateStyle dateStyle, PKTextAlignment pkTextAlignment) {
            if (Objects.nonNull(value) && value.length() > 0) {
                PKField pkField = new PKField();
                pkField.setKey(Optional.ofNullable(keyField).orElse(StringUtils.EMPTY));
                pkField.setLabel(Optional.ofNullable(label).orElse(StringUtils.EMPTY));
                pkField.setValue(value);
                pkField.setTimeStyle(timeStyle);
                pkField.setDateStyle(dateStyle);
                pkField.setTextAlignment(pkTextAlignment);
                addGenericList(genericPassType, pkField);
            }
            return this;
        }
    
        private void addGenericList(GenericPassEnum genericPassType, PKField pkField) {
            switch (genericPassType) {
                case HEADER:
                    headerFields.add(pkField);
                    break;
                case PRIMARY:
                    primaryFields.add(pkField);
                    break;
                case SECONDARY:
                    secondaryFields.add(pkField);
                    break;
                case AUXILIARY:
                    auxiliaryFields.add(pkField);
                    break;
                case BACK:
                    backFields.add(pkField);
                    break;
                default:
                    throw new InvalidParameterException("Undefined type!");
            }
        }
    
        public AppleWallet buildField(GenericPassEnum genericPassType, String keyField, String label, Serializable value, PKTextAlignment pkTextAlignment) {
            PKField pkField = new PKField();
            pkField.setKey(Optional.ofNullable(keyField).orElse(StringUtils.EMPTY));
            pkField.setLabel(Optional.ofNullable(label).orElse(StringUtils.EMPTY));
            pkField.setValue(Optional.ofNullable(value).orElse(StringUtils.EMPTY));
            pkField.setTextAlignment(pkTextAlignment);
            addGenericList(genericPassType, pkField);
            return this;
        }
    
    
        public AppleWallet startGenericPass() {
            pkGenericPass.setHeaderFields(headerFields);
            pkGenericPass.setPrimaryFields(primaryFields);
            pkGenericPass.setSecondaryFields(secondaryFields);
            pkGenericPass.setAuxiliaryFields(auxiliaryFields);
            pkGenericPass.setBackFields(backFields);
            pkPass.setGeneric(pkGenericPass);
            return this;
        }
    
        public AppleWallet addFile(String pkPassTemplateInMemoryType, String url) throws IOException {
            int responseCode = 0;
            URL fileUrl = null;
            if (StringUtils.isNotEmpty(url)) {
                try {
                    fileUrl = new URL(url);
                    HttpURLConnection con = (HttpURLConnection) fileUrl.openConnection();
                    responseCode = con.getResponseCode();
                } catch (Exception e) {
                    responseCode = HttpStatus.NOT_FOUND.value();
                }
            }
    
            if (responseCode < HttpStatus.MULTIPLE_CHOICES.value() && responseCode >= HttpStatus.OK.value()) {
                pkPassTemplateInMemory.addFile(pkPassTemplateInMemoryType, Objects.requireNonNull(fileUrl));
            }
            return this;
        }
    
        public AppleWallet addFile(String pathInTemplate, InputStream inputStream) throws IOException {
            pkPassTemplateInMemory.addFile(pathInTemplate, inputStream);
            return this;
        }
    
        public PKPassTemplateInMemory getPKPassTemplateInMemory() {
            return pkPassTemplateInMemory;
        }
    
    
        public String getSerialNumber() {
            return serialNumber;
        }
    
        public byte[] create2Byte() throws PKSigningException {
            PKFileBasedSigningUtil pkSigningUtil = new PKFileBasedSigningUtil();
            return pkSigningUtil.createSignedAndZippedPkPassArchive(pkPass, pkPassTemplateInMemory, pkSigningInformation);
        }
    
        public AppleWallet buildWholeParent(String passTypeIdentifier, String authenticationToken, String teamIdentifier, String organizationName, PKSigningInformation pkSigningInformation) {
            this.pkSigningInformation = pkSigningInformation;
            pkPass.setPassTypeIdentifier(passTypeIdentifier);
            pkPass.setAuthenticationToken(authenticationToken);
            pkPass.setTeamIdentifier(teamIdentifier);
            pkPass.setOrganizationName(Optional.ofNullable(organizationName).orElse(StringUtils.EMPTY));
            return this;
        }
    
        public PKPass getPkPass() {
            return pkPass;
        }
    
        public AppleWallet isValid() {
            if (!pkPass.isValid()) {
                List<String> validationErrors = this.pkPass.getValidationErrors();
                String error = CollectionUtils.isNotEmpty(validationErrors) ? validationErrors.get(0) : VALID_ERROR;
                throw new RuntimeException(error);
            } else {
                return this;
            }
        }
    
        public AppleWallet setWebServiceURL(String url) {
            try {
                pkPass.setWebServiceURL(new URL(url));
                pkPass.setFormatVersion(1);
            } catch (MalformedURLException e) {
               	
            }
            return this;
        }
    
        public enum GenericPassEnum {
            HEADER, PRIMARY, SECONDARY, AUXILIARY, BACK, OTHER
        }
    }

[format_png]: https://img-blog.csdnimg.cn/img_convert/f65e1418ad06e5dff86152bce5a34e1b.webp?x-oss-process=image/format,png
[Link 1]: https://link.juejin.cn?target=https%3A%2F%2Fdeveloper.apple.com%2Flibrary%2Farchive%2Fdocumentation%2FUserExperience%2FConceptual%2FPassKit_PG%2FCreating.html%23%2F%2Fapple_ref%2Fdoc%2Fuid%2FTP40012195-CH4-SW1
[Link 2]: https://link.juejin.cn?target=https%3A%2F%2Fdeveloper.apple.com%2Fcn%2Fwallet%2Fadd-to-apple-wallet-guidelines%2F
[format_png 1]: https://img-blog.csdnimg.cn/img_convert/8cce60dda2df066e8d4c5af5e44c2d04.webp?x-oss-process=image/format,png
[format_png 2]: https://img-blog.csdnimg.cn/img_convert/f1af5bae6724745e92b2855decc83548.webp?x-oss-process=image/format,png
[format_png 3]: https://img-blog.csdnimg.cn/img_convert/e6ef8edec214f104631ab6d7da06fab9.webp?x-oss-process=image/format,png
[jpasskit]: https://link.juejin.cn?target=https%3A%2F%2Fgithub.com%2Fdrallgood%2Fjpasskit
[format_png 4]: https://img-blog.csdnimg.cn/img_convert/7e69e37799e77c3298f6b6ebb08828ab.webp?x-oss-process=image/format,png
[Link 3]: https://link.juejin.cn?target=https%3A%2F%2Fwww.pass2u.net%2Flogin
[Link 4]: https://link.juejin.cn?target=https%3A%2F%2Fdeveloper.apple.com%2Flibrary%2Farchive%2Fdocumentation%2FPassKit%2FReference%2FPassKit_WebService%2FWebService.html%23%2F%2Fapple_ref%2Fdoc%2Fuid%2FTP40011988
[Link 5]: https://link.juejin.cn?target=https%3A%2F%2Fdeveloper.apple.com%2Flibrary%2Farchive%2Fdocumentation%2FUserExperience%2FConceptual%2FPassKit_PG%2FYourFirst.html%23%2F%2Fapple_ref%2Fdoc%2Fuid%2FTP40012195-CH2-SW1