目录

伙伴快应用方式领取卡券

概述

商户可以通过快应用的方式将卡券推送至华为钱包App。

目前这种方式暂时只支持中国大陆区域开放。

商户服务器生成卡劵包可参考服务端示例代码。

创建消息通道

商户快应用创建消息通道,通道建立后即可和华为钱包进行数据交互。

下方示例代码中的sign请联系华为开发人员获取,如果调用过程中出现“1002通道建立失败”错误码请联系华为钱包开发人员让其提供放开限制版本钱包进行调试。

//创建消息通道
 var channel = new messageChannel({
     package:'com.huawei.wallet',
     sign:'native app sign'
 });

判断是否可以添加卡券

商户应用通过调用CanAddPass接口判断当前移动设备是否满足加卡条件,是否已安装华为钱包App并且当前钱包版本支持该能力。

//调用CanAddPass接口查看卡券是否可以添加
channel.send({
     message: {
         code: 0,
         data: 'appId|passType'
     },
     success: function() {
         console.log('send success')
     },
     fail: function(data, code) {
         console.log(`handling fail, code = ${code}`)
     }
 });

添加卡券

  1. 商户服务器通过证书和私钥来签名卡券数据,并生成卡券包文件。

    商户需要替换服务器示例代码“src\test\resources\release.config.properties”文件中私钥和证书(证书和私钥请通过安全组件申请章节操作获取,然后将整个文件做base64转码后得到字符串放入到配置文件中),此证书和私钥用于签名卡券数据。

    • 卡券包由home.png, detail.png、signature、hwpass.json、manifest.json、home@2x.png, detail@2x.png七个文件组成,其中signture、manifest.json两个文件在调用服务端demo生成签名卡券包时会自动生成,不需要商户提供,商户需要按照下方的hwpass.json文件的生成规则生成hwpass.json文件并提供四张图片(图片为可选操作,如果商户不提供则使用钱包内默认底图)。
    • 卡券包大小应小于150KB,否则无法添加。
    • 卡券包在华为钱包的存储采用文件形式,每个卡券包都需要遵循相同的格式,整个文件采用zip压缩,文件后缀命名为.hwpass,文件名字字符只允许“a-z”,“A-Z”,“0-9”,“_”。

    卡券包组成

    文件名

    文件描述

    必选/可选

    格式要求

    备注(以电影票为例)

    hwpass.json

    卡券数据文件

    必选

    -

    取票号、影院、场次、座位、联系电话等变量由华为根据hwpass.json来填充。

    signature

    签名文件

    必选

    -

    -

    manifest.json

    对包中各文件的SHA256的Hash值

    必选

    -

    -

    home.png

    首页展示图片

    可选

    图片大小的要求:

    规格:320*200px

    大小:小于等于25kb

    商户商标、影片图片、影片上固定文字,可以采用本图片展示。影片失效后,需要生成新的home.png;通过更新pass压缩包来实现。

    detail.png

    详情页展示图片

    可选

    图片大小的要求:

    规格:656*405px

    大小:小于等于40kb

    商户商标、影片图片、影片上固定文字,可以采用本图片展示。影片失效后,需要生成新的detail.png;通过更新pass压缩包来实现。

    home@2x.png

    大屏展示时首页图片

    可选

    图片大小的要求:

    规格:480*300px

    大小:小于等于 25kb

    商户商标、影片图片、影片上固定文字,可以采用本图片展示。影片失效后,需要生成新的home@2x.png;通过更新pass压缩包来实现。

    detail@2x.png

    大屏展示时详情页图片

    可选

    图片大小的要求:

    规格:984*608px

    大小:小于等于40kb

    商户商标、影片图片、影片上固定文字,可以采用本图片展示。影片失效后,需要生成新的detail@2x.png;通过更新pass压缩包来实现。

    hwpass.json

    段名

    备注

    示例

    必选/可选

    formatVersion

    目前固定填写1.0。

    1.0

    必选

    passTypeIdentifier

    在开发者联盟注册的卡券类型Id。

    hwpass.membership.hotel

    必选

    passStyleIdentifier

    卡券在钱包的展示样式定义,目前以华为提供的为准,后续展示部分开放定制后可以在开发者联盟上注册对应卡券类型id的时候注册展示样式;建议和 passTypeIdentifier保持一致。

    hwpass.membership.hotel

    必选

    passesUpdateSince

    用于手机端侧与发卡系统交互,获取pass更新列表接口时作为参数传递给商户,商户根据此参数拿取最新的Pass包给钱包端侧。

    414994617

    必选

    organizationName

    展示在卡券上的发行机构名称。

    XX酒店会员卡

    必选

    organizationPassId

    具体的卡券号。

    E15285WF65

    必选

    webServiceURL

    用于手机端侧与发卡系统交互,交互链接地址。

    https://www.XXX.com/ download/pass

    必选

    authorizationToken

    用于手机端侧与发卡系统交互,鉴权token。

    ae13d3bsdfsfwwd7f9a4a5235f10803c09

    必选

    serialNumber

    用于手机端侧与发卡系统交互,建议与 organizationPassId不相同,防止卡号泄露。

    8a452215a35855dsffgwfce3aa94bbee

    必选

    fields.commonFields

    对于某种类型的卡券的必备展示字段。

    {

    "key": "name",

    "label": "名称",

    "value": "XXX"

    }

    必选

    fields.appendFields

    对于某种类型的卡券的可选展示字段。

    {

    "key": "detail",

    "label": "详细信息",

    "value": "https://xxx"

    }

    可选

    commonFields、appendFields区域,至少有一个区域有值。

    commonFields、appendFields区域规则:

    字段名

    字段描述

    示例

    可空

    Key

    字段关键字

    name

    不可

    label

    字段名称

    名称

    不可

    value

    字段值

    XXX国际酒店

    不可

    // 使用证书和私钥生成PassFileService用于生成签名卡券包 
    public PassFileService getPassFileService(Properties properties, String passKeyPrefix) { 
        PassCertificateService passCertificateService = new PassCertificateService() { 
            @Override 
            public byte[] getCertificateByPassType(String passTypeIdentifier) { 
                 String property = properties.getProperty(passKeyPrefix + "certificate." + passTypeIdentifier, ""); 
                 return Base64.decodeBase64(property);         
            } 
            @Override 
            public byte[] getPrivateKeyByPassType(String passTypeIdentifier) { 
                 String property = properties.getProperty(passKeyPrefix + "privatekey." + passTypeIdentifier, "");   
                 return Base64.decodeBase64(property);          
            } 
            @Override 
            public byte[] getPassCACertificate() { 
                String property = properties.getProperty(passKeyPrefix + "ca", ""); 
                return Base64.decodeBase64(property);         
            } 
            PassFileService passFileService = new PassFileServiceImpl(passCertificateService); 
            return passFileService; 
        } 
    } 
     
    // 生成签名卡券包 
    public byte[] createRandomPass(String passType, PassFileService passFileService) throws IOException, NoSuchAlgorithmException, PassException, CertificateException, InvalidKeySpecException,InvalidKeyException, SignatureException, NoSuchProviderException { 
        String passNumber = utilService.getCompressUUID(); 
        ObjectNode passJson = JsonNodeFactory.instance.objectNode(); 
        passJson.put("passTypeIdentifier", "hwpass.com.huawei.wallet.pass.sdktest"); 
        passJson.put("passStyleIdentifier", "hwpass.com.huawei.wallet.pass.sdktest"); 
        passJson.put("organizationName", "Business Name"); 
        passJson.put("organizationPassId", "passPackage unique value"); 
        passJson.put("webServiceURL", "Card update interface webServiceURL"); 
        passJson.put("authorizationToken", "Card update interface token"); 
        passJson.put("serialNumber", "Card update interface serialNumber"); 
        // fields中放入各商户卡券对应显示字段 
        ObjectNode fieldsPassJson = JsonNodeFactory.instance.objectNode(); 
        passJson.put("fields", fieldsPassJson); 
     
        // 如果涉及到图片资源,请将图片资源放到fileMap中 
        Map<String, byte[]> fileMap = new HashMap<String, byte[]>(); 
     
        byte[] signBytes = passFileService.createPass(fileMap, passJson); 
        return signBytes; 
    }

  2. 商户应用向商户服务器请求到卡券包并将其做Base64加密后,通过消息通道调用AddPass接口将卡券包推送给华为钱包。

    商户App将已签名过的卡券包推送给华为钱包,钱包会对接收到的卡券包进行验签操作,验签通过后将卡券包保存至钱包应用,用户可打开钱包卡包界面进行查看。

    //调用AddPass接口添加卡券
    channel.send({
         message: {
             code: 1,
             data: 'appId|hwPassData
         },
         success: function() {
             console.log('send success')
         },
         fail: function(data, code) {
             console.log(`handling fail, code = ${code}`)
         }
     });