目录

Wallet Kit手工转换指导书

概述

  1. 在HMS中,优惠券、礼品卡、会员卡均对应PassObject对象,不做区分。
  2. PassObject采用builder模式,参数的设置均通过builder提供,需要在builder中设置好参数之后,再通过build()方法构建PassObject对象,如下:
    PassObject loyaltyObject = PassObject.getBuilder().setSerialNumber("12345")
        .addImageList(new ArrayList<>())
        //... 其他设置由您根据情况自己选择添加
        .build();
  3. PassObject的大部分属性都是用了通用的AppendField和CommonField接口,分别通过PassObject.Builder的addAppendFields()方法和addCommonFields()方法进行设置,采用(key/label/value)的键值结构,不提供单独的get/set方法。其中Key值常用属性定义在WalletPassConstant类中。

addInfoModuleDataLabeValueRow(LabelValueRow row)

LabelValue信息在HMS中,被合并到textData中。

To HMS API转换参考如下代码,将LabelValueRow对象中的LabelValue列表转换为HMS中的AppendField列表,LabelValue中的label和value属性,分别赋值给AppendField中的label和value属性,最后调用PassObject对象的addTextList()方法,将AppendField对象列表赋予PassObject对象:

// 下面的row1/row2对应LabelValueRow中LabelValueLie表中的对象
AppendField row1= AppendField.getBuilder().setKey("uniqueKey1") // 此处key值可以随意指定,但必须保证在一个对象中是唯一的
    .setLabel("Next Reward") // label值对应LabelValue中的label
    .setValue("2 coffees")   // value值对应LabelValue中的value
    .build();
AppendField row2= AppendField.getBuilder().setKey("uniqueKey2")
    .setLabel("Member Since")
    .setValue("01/15/2013")
    .build();
ArrayList<AppendField> textList = new java.util.ArrayList<>();
textList.add(row1);
textList.add(row2);
PassObject.getBuilder().addTextList(textList);

addInfoModuleDataLabelValueRows(Collection<LabelValueRow> rows)

To HMS API中,此方法转换请参见addInfoModuleDataLabeValueRow(LabelValueRow row)。

addImageModuleDataMainImageUri(UriData uriData)

To HMS API替换如下:

addImageModuleDataMainImageUris(Collection<UriData> uris)

To HMS API替换具体操作请参见addImageModuleDataMainImageUri(UriData uriData)。

addLinksModuleDataUri(UriData uriData)

Add HMS API和To HMS API请统一按如下指导转换。

会员卡、礼品卡、优惠券转换方法均相同,以会员卡为例说明:

将LoyaltyWalletObject中的:

public LoyaltyWalletObject.Builder addLinksModuleDataUri(UriData uriData);

按以下指导:

参数uriData 属性uri值类型目前可分为Nearby stores、Main page、Hotline三种类型,构建HMS中AppendField对象时,对应HMS的key值常量为:

WalletPassConstant.PASS_APPEND_FIELD_KEY_NEARBY_LOCATIONS,

WalletPassConstant.PASS_APPEND_FIELD_KEY_MAINPAGE,

WalletPassConstant.PASS_APPEND_FIELD_KEY_HOTLINE。

HMS中的AppendField对象的value可取参数uriData的uri值,Label值可取uriData的description值。

构建一个类型为AppendField对象实例hotlineAppendField,放入List<AppendField> appendFields中,最后通过PassObject的addAppendFields()方法将appendFields赋给PassObject对象。

Hotline示例代码:

PassObject.Builder passBuilder = PassObject.getBuilder();
ArrayList<AppendField> appendFields = new ArrayList<>();
String hotlineLabel = "hotline";
String hotlineValue = "4000";
AppendField hotlineAppendField = AppendField.getBuilder() 
    .setKey(WalletPassConstant.PASS_APPEND_FIELD_KEY_HOTLINE)        
    .setLabel(hotlineLabel)        
    .setValue(hotlineValue)        
    .build();
appendFields.add(hotlineAppendField);
passBuilder.addAppendFields(appendFields);

addLinksModuleDataUris(Collection<UriData> uris)

Add HMS API和To HMS API转换请参见addLinksModuleDataUri(UriData uriData)。

addLocation(LatLng latLng)

To HMS API替换如下:

addLocations(Collection<LatLng> locations)

To HMS API替换具体操作请参见addLocation(LatLng latLng)。

addMessage(WalletObjectMessage walletObjectMessage)

To HMS API替换如下:

addMessages(Collection<WalletObjectMessage> messages)

To HMS API替换请参见addMessage(WalletObjectMessage walletObjectMessage)。

addTextModuleData(TextModuleData textModuleData)

To HMS API替换如下:

addTextModulesData(Collection<TextModuleData> textModulesData)

To HMS API替换请参见addTextModuleData(TextModuleData textModuleData)。

CreateWalletObjectsRequest.Builder build()

Add HMS API

调用build创建Request之前,需要执行以下步骤:

  1. 您将PassObject对象转换成的json字符串发送到自己的服务器,并接收返回的JWE数据串。
  2. 将示例代码中的getJweFromAppServer(passObjectJson)进行替换为从服务器获取的加密JWE。
  3. 您拿到JWE后需要使用CreateWalletPassRequest.Builder的setContent()方法将数据传送给request。
会员卡、优惠券和礼品卡示例代码:
if (org.xms.g.utils.GlobalEnvSetting.isHms()) {
    String passObjectJson = ((com.huawei.hms.wallet
.pass
.PassObject) (wob.getHInstance())).toJson();  
    String jweString = getJweFromAppServer(passObjectJson);
    ((com.huawei.hms.wallet.CreateWalletPassRequest.Builder) (build.getHInstance())).setContent(jweString);
}
//wob是PassObject的对象实例。
//build是CreateWalletPassRequest的对象实例。

To HMS API

调用build创建Request之前,需要执行以下步骤:

  1. 您将PassObject对象转换成的json字符串发送到自己的服务器,并接收返回的JWE数据串。
  2. 将示例代码中的getJweFromAppServer(passObjectJson)进行替换为从服务器获取的加密JWE。
  3. 您拿到JWE后需要使用CreateWalletPassRequest.Builder的setContent()方法将数据传送给request。
会员卡、优惠券和礼品卡示例代码:
PassObject passObject = new PassObject();  // 此处new仅供示例用,实际代码中要取对应的卡券PassObject对象
String passObjectJson = passObject.toJson();  
String jweString = getJweFromAppServer(passObjectJson);  
CreateWalletPassRequest.Builder builder =  CreateWalletPassRequest.getBuilder();
builder.setContent(jweString);

GiftCardWalletObject.Builder build()、LoyaltyWalletObject.Builder build()和OfferWalletObject.Builder build()

您在创建GiftCardWalletObject之前,需要手动设置PassTypeIdentifier。PassTypeIdentifier的值为用户在AppGallery网站上注册WalletKit卡券服务时的服务号,示例代码中GiftCardWalletObject、LoyaltyWalletObject、OfferWalletObject的PassTypeIdentifier的值分别是:“hwpass.type.giftcard.hmspublic”,“hwpass.type.loyalty.hmspublic”和“hwpass.type.offer.hmspublic”。

java.lang.String getBarcodeAlternateText()

Add HMS API和To HMS API均按如下方式转换:

PassObject passObject = new PassObject();  // 此处new仅供示例用,实际代码中要取对应的卡券PassObject对象
BarCode barCode = passObject.getBarCode();
String text = barCode.getText();

java.lang.String getBarcodeType()

Add HMS API和To HMS API均按如下方式转换:

PassObject passObject = new PassObject();  // 此处new仅供示例用,实际代码中要取对应的卡券PassObject对象
BarCode barCode = passObject.getBarCode();
String text = barCode.getType();

java.lang.String getBarcodeValue()

Add HMS API和To HMS API均按如下方式转换:

PassObject passObject = new PassObject();  // 此处new仅供示例用,实际代码中要取对应的卡券PassObject对象
BarCode barCode = passObject.getBarCode();
String text = barCode.getValue();

LabelValue

在HMS中LabelValue对象需要转换成AppendField对象使用。

Add HMS API和To HMS API均参见如下方式转换:

AppendField field = AppendField.getBuilder().setKey("key")  // 说明,Key值可以随意填写,但是需要保证在同一个PassObject中不能重复
    .setLabel("LabelValue.getLabel()")
    .setValue("LabelValue.getValue()")
    .build();

LabelValueRow类可参考此类和addInfoModuleDataLabeValueRow(LabelValueRow row)。

LoyaltyPoints

在HMS中,会员卡积分只支持值和标签的设置,值为String类型,不区分货币类型。可以参见setLoyaltyPoints(LoyaltyPoints loyaltyPoints)。

setAccountId(String accountId)

To HMS API替换如下:

setAccountName(String accountName)

To HMS API替换如下:

setBalanceMicros(long balanceMicros)

To HMS API替换如下:

setBalanceUpdateTime(long balanceUpdateTime)

To HMS API替换如下:

setBarcodeAlternateText(String barcodeAlternate)

使用HMS Wallet方案时,二维码相关信息要一次性全部设置完成,BarCode的Type分别是BarCode.BARCODE_TYPE_QR_CODE(二维码)和BarCode.BARCODE_TYPE_CODABAR(条形码)。

Add HMS API和To HMS API替换如下:

PassObject.Builder passObject= PassObject.getBuilder();
BarCode barCode = BarCode.getBuilder().setType(BarCode.BARCODE_TYPE_QR_CODE).setText("12345").setValue("28343E3").build();
passObject.setBarCode(barCode);

setBarcodeValue(String barcodeValue)

请参见setBarcodeAlternateText(String barcodeAlternate)。

setBarcodeType(String barcodeType)

请参见setBarcodeAlternateText(String barcodeAlternate)。

setCardNumber(String cardNumber)

只有礼品卡做转换。

To HMS API替换如下:

setEventNumber(String eventNumber)

To HMS API替换如下:

setId(String id)

在HMS中,每个卡券均新增了一个passId字段,是个必填字段。在优惠券设置Id时,passId与id值相同,需要一同设置。

To HMS API转换如下(优惠券):

String id = "abc123";//说明,id由您自己输入
PassObject.getBuilder().setSerialNumber(id).setOrganizationPassId(id);

setIssuerName(String merchantName)

To HMS API替换如下:

setLoyaltyPoints(LoyaltyPoints loyaltyPoints)

To HMS API替换如下:

setPin(String pin)

To HMS API替换如下:

setProgramName(String programName)

To HMS API替换如下:

setState(int state)

在HMS中,卡片的状态和有效时间共同组成PassStatus对象。

Add HMS API和To HMS API替换如下:

构建PassObject对象,为其属性status赋值。PassObject的属性status的数据类型为PassStatus对象,PassStatus对象的属性state的值根据实际情况设置,具体状态为"active","completed","expired","inactive"。

示例:

SimpleDateFormat format = new SimpleDateFormat("yyyy-MM-dd'T'HH:mm:ss.SSS'Z'");        
Long startTime = 0L;        
Long endTime = 0L;
PassStatus passStatus = PassStatus.getBuilder()        
    .setState("active")        
    .setEffectTime(format.format(new Date(startTime)))        
    .setExpireTime(format.format(new Date(endTime)))        
    .build();
PassObject.Builder passBuilder = PassObject.getBuilder();
passBuilder.setStatus(passStatus);

注释:startTime和endTime是时间的毫秒值,可根据卡券的实际的时间的毫秒值填写。

setTitle(String title)

To HMS API替换如下:

setValidTimeInterval(TimeInterval timeInterval)

Add HMS API和To HMS API替换如下:

TimeInterval的属性startTimestamp和endTimestamp分别对应HMS的PassStatus对象属性effectTime和expireTime,具体构建请参见setState(int state)。

TextModuleData

在HMS中TextModuleData对象需要转换成AppendField对象使用。

Add HMS API和To HMS API均参见如下方式转换:

AppendField field = AppendField.getBuilder().setKey("key")  // 说明,Key值可以随意填写,但是需要保证在同一个PassObject中不能重复
    .setLabel("TextModuleData.getHeader()")
    .setValue("TextModuleData.getBody()")
    .build();

可以参见addTextModuleData(TextModuleData textModuleData)。

TimeInterval

在HMS中,TimeInterval对象已没有支持了。当前卡券有效期可以转换到PassStatus中使用,参见setState(int state)。

UriData

在HMS中UriData对象需要转换成AppendField对象使用。

Add HMS API和To HMS API均参见如下方式转换:

AppendField field = AppendField.getBuilder().setKey("key")  // 说明,Key值可以随意填写,但是需要保证在同一个PassObject中不能重复
    .setLabel("UriData.getDescription()")
    .setValue("UriData.getUri()")
    .build();

可以参见addImageModuleDataMainImageUri(UriData uriData)。

WalletObjectMessage

在HMS中WalletObjectMessage对象需要转换成AppendField对象使用。

Add HMS API和To HMS API均参见如下方式转换:

AppendField field = AppendField.getBuilder().setKey("key")  // 说明,Key值可以随意填写,但是需要保证在同一个PassObject中不能重复
    .setLabel("WalletObjectMessage.getHeader()")
    .setValue("WalletObjectMessage.getBody()")
    .build();

可以参见addMessage(WalletObjectMessage walletObjectMessage)。

WalletObjectsClient getWalletObjectsClient(Activity activity, Wallet.WalletOptions options)

To HMS API中,在HMS中使用如下方法替代:

public static WalletPassClient getWalletPassClient(Activity activity);

WalletObjectsConstants

在HMS中,卡券状态通过字符串常量来标志,常量定义在com.huawei.hms.wallet.constant.WalletPassConstant类中:

public static final String PASS_STATE_COMPLETED = "completed";
public static final String PASS_STATE_EXPIRED = "expired";
public static final String PASS_STATE_INACTIVE = "inactive";
public static final String PASS_STATE_ACTIVE = "active";

可以参见setState(int state)。

getImageModuleDataMainImageUris()

List<com.google.android.gms.wallet.wobs.UriData> getImageModuleDataMainImageUris()

在HMS中,没有类可以完全对应UriData,UriData可以被HMS中的AppendField类替代。

To HMS API中,以上接口可以通过如下代码替代:

PassObject passObject = new PassObject(); // 此处new仅供示例用,实际代码中要取对应的卡券PassObject对象
List<AppendField> imageList = passObject.getImageList();

返回值不一样,AppendField中的属性值与UriData的属性值的对应关系,请参见addImageModuleDataMainImageUri(UriData uriData)。

类似的,以下接口也是一样的替换方式:

getIssuerName()

在HMS中,没有对应的get方法,如果需要获取issuerName,可以参见如下代码修改,通过指定key值从PassObject的CommonFIelds中获取属性值。

PassObject passObject = new PassObject(); // 此处new仅供示例用,实际代码中要取对应的卡券PassObject对象
String issuerName;
List<CommonField> fields = passObject.getCommonField();
for (CommonField field : fields) {
    if (WalletPassConstant.PASS_COMMON_FIELD_KEY_MERCHANT_NAME.equals(field.getKey())) {
        issuerName = field.getValue();  // 获取到issuerName属性值
        break;
    }
}

类似的,如下获取属性值的接口也可以使用上述代码进行替换,只需使用对应的key值即可。

另外,以下两个接口,也可以用上述类似方法获取属性值,只是其key值是在AppendField中。

PassObject passObject = new PassObject(); // 此处new仅供示例用,实际代码中要取对应的卡券PassObject对象
String eventNumber;
List<AppendField> fields = passObject.getAppendFields();  // 对比上面的例子,这里需要调用getAppendFields()方法
for (AppendField field : fields) {
    if (WalletPassConstant.PASS_APPEND_FIELD_KEY_EVENT_NUMBER.equals(field.getKey())) {
        eventNumber= field.getValue(); // 获取到eventNumber属性值
        break;
    }
}
  1. getLoyaltyPoints()方法的返回为LoyaltyPoints对象,但是LoyaltyPoints对象在HMS中没有与其匹配的类,通过对应的Key值获取到的只是积分的数值。
  2. 上述get方法的使用可以参考本文中各个set方法的说明,更容易理解。

getLocations()

List<com.google.android.gms.maps.model.LatLng> getLocations()

To HMS API中,使用如下代码获取HMS中的对应信息:

PassObject passObject = new PassObject(); // 此处new仅供示例用,实际代码中要取对应的卡券PassObject对象
List<Location> locationList = passObject.getLocationList();

返回值为Location列表,其中Location为Wallet Kit自定义的对象,您使用此方法需自行对返回值使用的地方做适配。

getRedemptionCode()

在HMS中,礼品卡没有设置单独的兑换码字段,其值已转换为条形码/二维码的码值,请参见java.lang.String getBarcodeType()获取兑换码。

getState()

在HMS中,卡片的状态和有效时间共同组成PassStatus对象,所以没有单独的接口获取卡片状态属性,您可以通过以下方式获取卡片的状态和有效期。

PassObject passObject = new PassObject(); // 此处new仅供示例用,实际代码中要取对应的卡券PassObject对象
PassStatus passStatus = passObject.getStatus();
String state = passStatus.getState(); // 字符串表示的卡片状态
String effectiveTime = passStatus.getEffectTime();  // 卡券生效时间
String expireTime = passStatus.getExpireTime();  // 卡券过期时间

可以参见setState(int state)接口的说明。

getValidTimeInterval()

HMS中,没有与TimeInterval对应的类,如果用户需要获取卡片的有效期,可以参见getState()方法。

LoyaltyPointsBalance

HMS中没有类与LoyaltyPointsBalance对应,而且HMS中的会员卡积分不区分数据类型,均按字符串形式存储。所以您如果需要在HMS中使用此类,按以下方式替换。

Add HMS API和To HMS API均需要按如下方式使用:

设置积分的方法:

public final com.google.android.gms.wallet.wobs.LoyaltyPointsBalance.Builder setInt(int)
public final com.google.android.gms.wallet.wobs.LoyaltyPointsBalance.Builder setDouble(double)
public final com.google.android.gms.wallet.wobs.LoyaltyPointsBalance.Builder setString(java.lang.String)
public final com.google.android.gms.wallet.wobs.LoyaltyPointsBalance.Builder setMoney(java.lang.String,long)

以上四个设置积分的方法均参见如下方法进行修改:

String label = "Points";
String value = "123";
String currencyCode = "12";//此处仅供示例用,实际开发中要根据需求获取对应的数据
PassObject.Builder passBuilder = PassObject.getBuilder();
List<AppendField> fields = new ArrayList<>();
AppendField balance = AppendField.getBuilder()
    .setKey(WalletPassConstant.PASS_APPEND_FIELD_KEY_POINTS)  
    .setValue(value) // value为字符串形式的积分值
    .setLabel(label) // label为标签字符串,同LoyaltyPointsBalance中的label
    .build();
fields.add(balance);
passBuilder.addAppendFields(fields);
// 如果积分为货币,需要设置货币码时,可以按如下方式设置
passBuilder.setCurrencyCode(currencyCode);

获取积分值的方法:

public final long getCurrencyMicros()
public final double getDouble()
public final int getInt()
public final java.lang.String getString()

以上4个获取积分值的方法均参见如下方法进行修改,并且都是返回字符串形式的积分:

PassObject passObject = new PassObject(); // 此处new仅供示例用,实际代码中要取对应的卡券PassObject对象
String loyaltyPoints;
List<AppendField> appendFields = passObject.getAppendFields();
for (AppendField field : appendFields) {
    if (WalletPassConstant.PASS_APPEND_FIELD_KEY_POINTS.equals(field.getKey())) {
        loyaltyPoints = field.getValue(); // 此处获取字符串类型的积分
        break;
    }
}

获取货比码的方法:

public final java.lang.String getCurrencyCode()

以上获取货比码的方法,直接使用PassObject的getCurrencyCode()方法即可:

PassObject passObject = new PassObject(); // 此处new仅供示例用,实际代码中要取对应的卡券PassObject对象
String currencyCode = passObject.getCurrencyCode();