礼品卡支持模板渲染。如果未定义模板,系统将使用默认模板。
模板定义
卡券模板在类级别定义,用于显示与类相关联的任何对象。该模板可定义要在卡券的不同部分中显示的字段。
该模板分为以下几个部分:
卡片标题
默认卡片标题
宽幅徽标卡片标题
|
默认卡片标题
宽幅徽标卡片标题
|
卡片标题部分会显示徽标、商家名称和余额。用于填充这些要素的字段引用以及这些要素的位置都不能更改。
设置宽幅徽标字段后,在 Android 设备上,包含徽标和发卡机构名称的默认模板标题会替换为宽幅徽标。
在制作宽幅标题徽标时,请遵循 宽幅徽标图片指南,以便在卡券上以最佳方式显示图片。
卡片模板
卡片模板部分用于显示额外的行。这些行可以包含文本型结构化数据字段或文本模块字段。
您可以在 class.classTemplateInfo.cardTemplateOverride.cardRowTemplateInfos[]
列表中指定用于确定对象数的行数。该列表至少需要一个元素,我们建议最多使用两个元素。每个元素必须是以下类型之一:
-
oneItem
,接受一项:item
-
twoItems
,接受两项:startItem
endItem
-
threeItems
,接受三项:startItem
middleItem
endItem
每项内容可以定义为一个字段选择器 (.firstValue
)、两个字段选择器(.firstValue
和 .secondValue
)或预定义项 (.predefinedItem
)。系统会同时显示所选字段的值及其对应的标签。当您定义两个字段选择器时,系统会使用“/”分隔符将所选字段的值分隔开。所选字段的标签也是如此。预定义项用于定义更为复杂的呈现。
以下代码示例展示了如何替换卡片模板的卡片行部分,以指定两行。每行包含三项,每项都引用六个类级别的 textModuleData
自定义字段及其标题作为标签:
{
... //Rest of class
"textModulesData": [
{
"header": "Label 1",
"body": "Some info 1",
"id": "myfield1"
},
{
"header": "Label 2",
"body": "Some info 2",
"id": "myfield2"
},
{
"header": "Label 3",
"body": "Some info 3",
"id": "myfield3"
},
{
"header": "Label 4",
"body": "Some info 4",
"id": "myfield4"
},
{
"header": "Label 5",
"body": "Some info 5",
"id": "myfield5"
},
{
"header": "Label 6",
"body": "Some info 6",
"id": "myfield6"
}
],
"classTemplateInfo": {
"cardTemplateOverride": {
"cardRowTemplateInfos": [{
"threeItems": {
"startItem": {
"firstValue": {
"fields": [{
"fieldPath": "class.textModulesData['myfield1']"
}]
}
},
"middleItem": {
"firstValue": {
"fields": [{
"fieldPath": "class.textModulesData['myfield2']"
}]
}
},
"endItem": {
"firstValue": {
"fields": [{
"fieldPath": "class.textModulesData['myfield3']"
}]
}
},
}
},{
"threeItems": {
"startItem": {
"firstValue": {
"fields": [{
"fieldPath": "class.textModulesData['myfield4']"
}]
}
},
"middleItem": {
"firstValue": {
"fields": [{
"fieldPath": "class.textModulesData['myfield5']"
}]
}
},
"endItem": {
"firstValue": {
"fields": [{
"fieldPath": "class.textModulesData['myfield6']"
}]
}
},
}
}]
}
}
}
// Rest of class
.setTextModulesData((new ArrayList<TextModuleData>() {
{
add((new TextModuleData()).setHeader("Label 1")
.setBody("Some info 1")
.setId("myfield1"));
add((new TextModuleData()).setHeader("Label 2")
.setBody("Some info 1")
.setId("myfield2"));
add((new TextModuleData()).setHeader("Label 3")
.setBody("Some info 3")
.setId("myfield3"));
add((new TextModuleData()).setHeader("Label 4")
.setBody("Some info 4")
.setId("myfield4"));
add((new TextModuleData()).setHeader("Label 5")
.setBody("Some info 5")
.setId("myfield5"));
add((new TextModuleData()).setHeader("Label 6")
.setBody("Some info 5")
.setId("myfield6"));
}
}))
.setClassTemplateInfo((new ClassTemplateInfo())
.setCardTemplateOverride((new CardTemplateOverride())
.setCardRowTemplateInfos(new ArrayList<CardRowTemplateInfo>() {
{
add((new CardRowTemplateInfo()).setThreeItems((new CardRowThreeItems())
.setStartItem((new TemplateItem()).setFirstValue((new FieldSelector()).setFields(new ArrayList<FieldReference>(){
{
add((new FieldReference()).setFieldPath("class.textModulesData['myfield1']"));
}
})))
.setMiddleItem((new TemplateItem()).setFirstValue((new FieldSelector()).setFields(new ArrayList<FieldReference>(){
{
add((new FieldReference()).setFieldPath("class.textModulesData['myfield2']"));
}
})))
.setEndItem((new TemplateItem()).setFirstValue((new FieldSelector()).setFields(new ArrayList<FieldReference>(){
{
add((new FieldReference()).setFieldPath("class.textModulesData['myfield3']"));
}
})))
));
add((new CardRowTemplateInfo()).setThreeItems((new CardRowThreeItems())
.setStartItem((new TemplateItem()).setFirstValue((new FieldSelector()).setFields(new ArrayList<FieldReference>(){
{
add((new FieldReference()).setFieldPath("class.textModulesData['myfield4']"));
}
})))
.setMiddleItem((new TemplateItem()).setFirstValue((new FieldSelector()).setFields(new ArrayList<FieldReference>(){
{
add((new FieldReference()).setFieldPath("class.textModulesData['myfield5']"));
}
})))
.setEndItem((new TemplateItem()).setFirstValue((new FieldSelector()).setFields(new ArrayList<FieldReference>(){
{
add((new FieldReference()).setFieldPath("class.textModulesData['myfield6']"));
}
})))
));
}
})))
// Rest of class
$textModulesData1 = new Google_Service_Walletobjects_TextModuleData();
$textModulesData1->setBody("Some info 1");
$textModulesData1->setHeader("Label 1");
$textModulesData1->setId("myfield1");
$textModulesData2 = new Google_Service_Walletobjects_TextModuleData();
$textModulesData2->setBody("Some info 2");
$textModulesData2->setHeader("Label 2");
$textModulesData2->setId("myfield2");
$textModulesData3 = new Google_Service_Walletobjects_TextModuleData();
$textModulesData3->setBody("Some info 3");
$textModulesData3->setHeader("Label 3");
$textModulesData3->setId("myfield3");
$textModulesData4 = new Google_Service_Walletobjects_TextModuleData();
$textModulesData4->setBody("Some info 4");
$textModulesData4->setHeader("Label 4");
$textModulesData4->setId("myfield4");
$textModulesData5 = new Google_Service_Walletobjects_TextModuleData();
$textModulesData5->setBody("Some info 5");
$textModulesData5->setHeader("Label 5");
$textModulesData5->setId("myfield5");
$textModulesData6 = new Google_Service_Walletobjects_TextModuleData();
$textModulesData6->setBody("Some info 6");
$textModulesData6->setHeader("Label 6");
$textModulesData6->setId("myfield6");
$textModulesDatas = array($textModulesData1, $textModulesData2, $textModulesData3,
$textModulesData4, $textModulesData5, $textModulesData6);
$startItemField = new Google_Service_Walletobjects_FieldReference();
$startItemField->setFieldPath("class.textModulesData['myfield1']");
$startItemFirstValue = new Google_Service_Walletobjects_FieldSelector();
$startItemFirstValue->setFields(array($startItemField));
$startItem = new Google_Service_Walletobjects_TemplateItem();
$startItem->setFirstValue($startItemFirstValue);
$middleItemField = new Google_Service_Walletobjects_FieldReference();
$middleItemField->setFieldPath("class.textModulesData['myfield2']");
$middleItemFirstValue = new Google_Service_Walletobjects_FieldSelector();
$middleItemFirstValue->setFields(array($middleItemField));
$middleItem = new Google_Service_Walletobjects_TemplateItem();
$middleItem->setFirstValue($middleItemFirstValue);
$endItemField = new Google_Service_Walletobjects_FieldReference();
$endItemField->setFieldPath("class.textModulesData['myfield3']");
$endItemFirstValue = new Google_Service_Walletobjects_FieldSelector();
$endItemFirstValue->setFields(array($endItemField));
$endItem = new Google_Service_Walletobjects_TemplateItem();
$endItem->setFirstValue($endItemFirstValue);
$cardRowTemplate = new Google_Service_Walletobjects_CardRowThreeItems();
$cardRowTemplate->setStartItem($startItem);
$cardRowTemplate->setMiddleItem($middleItem);
$cardRowTemplate->setEndItem($endItem);
$cardRowTemplateInfo1 = new Google_Service_Walletobjects_CardRowTemplateInfo();
$cardRowTemplateInfo1->setThreeItems($cardRowTemplate);
$startItemField2 = new Google_Service_Walletobjects_FieldReference();
$startItemField2->setFieldPath("class.textModulesData['myfield4']");
$startItemFirstValue2 = new Google_Service_Walletobjects_FieldSelector();
$startItemFirstValue2->setFields(array($startItemField2));
$startItem2 = new Google_Service_Walletobjects_TemplateItem();
$startItem2->setFirstValue($startItemFirstValue2);
$middleItemField2 = new Google_Service_Walletobjects_FieldReference();
$middleItemField2->setFieldPath("class.textModulesData['myfield5']");
$middleItemFirstValue2 = new Google_Service_Walletobjects_FieldSelector();
$middleItemFirstValue2->setFields(array($middleItemField2));
$middleItem2 = new Google_Service_Walletobjects_TemplateItem();
$middleItem2->setFirstValue($middleItemFirstValue2);
$endItemField2 = new Google_Service_Walletobjects_FieldReference();
$endItemField2->setFieldPath("class.textModulesData['myfield6']");
$endItemFirstValue2 = new Google_Service_Walletobjects_FieldSelector();
$endItemFirstValue2->setFields(array($endItemField2));
$endItem2 = new Google_Service_Walletobjects_TemplateItem();
$endItem2->setFirstValue($endItemFirstValue2);
$cardRowTemplate2 = new Google_Service_Walletobjects_CardRowThreeItems();
$cardRowTemplate2->setStartItem($startItem2);
$cardRowTemplate2->setMiddleItem($middleItem2);
$cardRowTemplate2->setEndItem($endItem2);
$cardRowTemplateInfo2 = new Google_Service_Walletobjects_CardRowTemplateInfo();
$cardRowTemplateInfo2->setThreeItems($cardRowTemplate2);
$cardTemplateOverride = new Google_Service_Walletobjects_CardTemplateOverride();
$cardTemplateOverride->setCardRowTemplateInfos(array($cardRowTemplateInfo1,
$cardRowTemplateInfo2));
$classTemplateInfo = new Google_Service_Walletobjects_ClassTemplateInfo();
$classTemplateInfo->setCardTemplateOverride($cardTemplateOverride);
$payload->setTextModulesData($textModulesDatas);
$payload->setClassTemplateInfo($classTemplateInfo);
此代码会按照以下代码模板部分的格式创建卡券:
如果某项为空,则不会显示该项。如需了解详情,请参阅字段引用。如果某行中的所有项均为空,则不显示该行。如果某行中某些项(而非所有项)为空,系统会重新排列非空项并将其显示为项数较少的行。
如果您没有替换卡片模板,则系统会使用默认行数、默认项数和默认字段引用。如需了解详情,请参阅默认模板。
定义主打图片后,如果 cardRowTemplateInfos
列表中包含多行,则主打图片会显示在第一行之后;如果只有一行,则会显示在该行上方。
卡片条形码
|
|
卡片条形码部分用于在条形码上方和下方显示额外的文本或图片。此部分中的所有字段都不是必填字段。
有三个字段选择器,可用于定义两个并排字段(在条形码上方)和另外一个字段(位于条形码下方)。这些字段不显示标签,可以是文本型结构化数据字段、文本模块字段或图片模块字段。如果您使用图片,则应遵循品牌推广指南。
条形码由类型和值定义。如需查看受支持的条形码类型的列表,请参阅参考文档。此外,文本可以显示在条形码的正下方。此文本可用于简化条形码扫描等操作。
以下代码示例展示了如何替换卡券的条形码部分,以在条形码上方显示图片:
#... rest of class
"imageModulesData": [
{
"mainImage": {
"sourceUri": {
"uri": "http://farm4.staticflickr.com/3738/12440799783_3dc3c20606_b.jpg",
"description": "Coffee"
}
},
"Id": "myimage"
}
],
"classTemplateInfo": {
"cardBarcodeSectionDetails": {
"firstTopDetail": {
"fieldSelector": {
"fields": [
{
"fieldPath": "class.imageModulesData['myimage'].mainImage"
}
]
}
}
}
}
}
//... rest of class
.setImageModulesData((new ArrayList<ImageModuleData>() {
{
add((new ImageModuleData())
.setId("myimage")
.setMainImage((new Image()).setSourceUri((new ImageUri()).setDescription("Coffee beans")
.setUri("http://farm4.staticflickr.com/3738/12440799783_3dc3c20606_b.jpg"))));
}
}))
.setClassTemplateInfo((new ClassTemplateInfo())
.setCardBarcodeSectionDetails((new CardBarcodeSectionDetails())
.setFirstTopDetail((new BarcodeSectionDetail())
.setFieldSelector((new FieldSelector())
.setFields((new ArrayList<FieldReference>(){
{
add((new FieldReference()).setFieldPath("class.imageModulesData['myimage'].mainImage"));
}
})))))
}
//... rest of class
$imageUri = new Google_Service_Walletobjects_ImageUri();
$imageUri->setUri("https://farm8.staticflickr.com/7340/11177041185_a61a7f2139_o.jpg");
$imageUri->setDescription("Baconrista flights image");
$image = new Google_Service_Walletobjects_Image();
$image->setSourceUri($imageUri);
$imageModulesData = new Google_Service_Walletobjects_ImageModuleData();
$imageModulesData->setMainImage($image);
$imageModulesData->setId("myimage");
$cardBarcodeFieldReference = new Google_Service_Walletobjects_FieldReference();
$cardBarcodeFieldReference->setFieldPath("class.imageModulesData['myimage'].mainImage");
$cardBarcodeFieldSelector = new Google_Service_Walletobjects_FieldSelector();
$cardBarcodeFieldSelector->setFields(array($cardBarcodeFieldReference));
$cardBarcodeDetail = new Google_Service_Walletobjects_BarcodeSectionDetail();
$cardBarcodeDetail->setFieldSelector($cardBarcodeFieldSelector);
$cardBarcodeSectionDetails = new Google_Service_Walletobjects_CardBarcodeSectionDetails();
$cardBarcodeSectionDetails->setFirstTopDetail($cardBarcodeDetail);
$classTemplateInfo = new Google_Service_Walletobjects_ClassTemplateInfo();
$classTemplateInfo->setCardBarcodeSectionDetails($cardBarcodeSectionDetails);
$payload->setClassTemplateInfo($classTemplateInfo);
$payload->setImageModuleData($imageModulesData);
此代码会按照以下条形码部分的格式创建卡券:
如果您没有替换条形码部分,系统则使用默认的条形码字段。 如需了解详情,请参阅默认模板。
详细信息模板
|
|
详细信息模板部分是多个项 (class.classTemplateInfo.detailsTemplateOverride.detailsItemInfos[]
) 的列表。这些项可以包含任何类型的结构化数据字段、文本模块字段、链接模块字段、图片模块字段或消息。
每项内容可以定义为一个字段选择器 (.firstValue
)、两个字段选择器(.firstValue
和 .secondValue
)或预定义项 (.predefinedItem
)。系统会同时显示所选字段的值及其对应的标签。当您定义两个字段选择器时,系统会使用“/”分隔符将所选字段的值分隔开。所选字段的标签也是如此。预定义项用于定义更为复杂的呈现。图片模块字段以全宽图片呈现,没有标签。
以下代码示例展示了如何替换卡券的详细信息部分,以显示带有标签的单个 linksModuleData
字段:
//... rest of class
"linksModuleData": {
"uris": [
{
"uri": "http://maps.google.com/",
"description": "Nearby Locations",
"id":"mylink"
}
]
},
"classTemplateInfo": {
"detailsTemplateOverride": {
"detailsItemInfos": [
{
"item":{
"firstValue": {
"fields": [{
"fieldPath": "class.linksModuleData.uris['mylink']"
}]
}
}
}
]
}
}
//... rest of class
//... rest of class
.setLinksModuleData((new ArrayList<LinksModuleData>() {
{
add((new LinksModuleData()).setDescription("Nearby Locations")
.setUri("http://maps.google.com/")
.setId("mylink"));
}))
.setClassTemplateInfo((new ClassTemplateInfo())
.setDetailsTemplateOverride((new DetailsTemplateOverride())
.setDetailsItemInfos(new ArrayList<DetailsItemInfo>(){
{
add((new DetailsItemInfo())
.setItem((new TemplateItem()).setFirstValue((new FieldSelector()).setFields(new ArrayList<FieldReference>(){
{
add((new FieldReference()).setFieldPath("class.linksModuleData.uris['mylink']"));
}
}))));
}
}))
//... rest of class
//... rest of class building
$locationUri = new Google_Service_Walletobjects_Uri();
$locationUri->setUri("http://maps.google.com/");
$locationUri->setDescription("Nearby Locations");
$locationUri->setId("mylink");
$linksModuleData = new Google_Service_Walletobjects_LinksModuleData();
$linksModuleData->setUris(array($locationUri));
$detailItemFieldReference = new Google_Service_Walletobjects_FieldReference();
$detailItemFieldReference->setFieldPath("class.linksModuleData.uris['mylink']");
$detailItemFieldSelector = new Google_Service_Walletobjects_FieldSelector();
$detailItemFieldSelector->setFields(array($detailItemFieldReference));
$detailItem = new Google_Service_Walletobjects_TemplateItem();
$detailItem->setFirstValue($detailItemFieldSelector);
$detailsItemInfo = new Google_Service_Walletobjects_DetailsItemInfo();
$detailsItemInfo->setItem($detailItem);
$cardDetailsTemplateOverride = new Google_Service_Walletobjects_DetailsTemplateOverride();
$cardDetailsTemplateOverride->setDetailsItemInfos(array($detailsItemInfo));
$classTemplateInfo = new Google_Service_Walletobjects_ClassTemplateInfo();
$classTemplateInfo->setDetailsTemplateOverride($cardDetailsTemplateOverride);
$payload->setClassTemplateInfo($classTemplateInfo);
$payload->setLinksModuleData($linksModuleData);
//... rest of class
此代码会按照以下详细信息部分的格式创建卡券:
如果某项为空,则不会显示该项。如需了解详情,请参阅字段引用。
如果您没有替换详细信息模板,则系统会显示默认的引用字段(按默认顺序)列表。如需了解详情,请参阅默认模板。
列表模板
|
列表模板部分用于选择要在 Google 钱包应用的“卡券”视图中显示的字段。卡券在列表中以徽标、背景颜色和三行表示。
以下代码示例演示了如何替换卡券的列表模板,以在列表模板的第一行中显示单个卡券对象的到期日期字段:
#... rest of class definition
"classTemplateInfo": {
"listTemplateOverride":{
"firstRowOption": {
"fieldOption":{
"fields": [{
"fieldPath": "object.validTimeInterval.end"
}]
}
}
}
}
}
//... rest of class
.setClassTemplateInfo((new ClassTemplateInfo())
.setListTemplateOverride((new ListTemplateOverride())
.setFirstRowOption((new FirstRowOption())
.setFieldOption((new FieldSelector()).setFields(new ArrayList<FieldReference>(){
{
add((new FieldReference()).setFieldPath("object.validTimeInterval.end"));
}
}))))
//... rest of class
//... rest of class
$fieldReference = new Google_Service_Walletobjects_FieldReference();
$fieldReference->setFieldPath("object.validTimeInterval.end");
$fieldOption = new Google_Service_Walletobjects_FieldSelector();
$fieldOption->setFields(array($fieldReference));
$firstRowOption = new Google_Service_Walletobjects_FirstRowOption();
$firstRowOption->setFieldOption($fieldOption);
$listTemplateOverride = new Google_Service_Walletobjects_ListTemplateOverride();
$listTemplateOverride->setFirstRowOption($firstRowOption);
$classTemplateInfo = new Google_Service_Walletobjects_ClassTemplateInfo();
$classTemplateInfo->setListTemplateOverride($listTemplateOverride);
$payload->setClassTemplateInfo($classTemplateInfo);
//... rest of class
此代码会按照以下列表的模板呈现创建卡券:
可以使用字段选择器定义这三行。 显示的字段没有标签。
标签
所有结构化数据字段都有 Google 提供的标签。Google 负责以支持的所有语言为每个标签提供译文。
您可以使用其中某个 class.custom<name_of_the_field>Label
字段自定义其中某些标签。当您自定义某个标签时,您将负责以您希望支持的所有语言为该特定标签提供译文。
字段引用
字段引用可用于模板的不同部分中,其格式为 class.classTemplateInfo.*.fields[]
。字段引用包含结构化数据字段、文本模块字段、链接模块字段、图片模块字段或消息的路径列表。
并非所有类型的路径都在每个字段引用中受支持。例如,某些字段引用仅允许文本型结构化数据字段或文本模块字段的路径。 文本型结构化字段是类型字符串、本地化字符串、日期或货币的结构化数据字段。
该列表可用于实现回退逻辑。这意味着如果列表中的第一个路径解析为空白字段,则系统会评估下一个路径。回退逻辑主要针对文本型结构化数据字段或文本模块字段。请勿在同一列表中混合使用不同类型的字段。使用回退逻辑时应谨慎,并且只能在特定情况下(例如,您需要在部分对象而无需在其他对象中遵循一致的字段格式)使用该逻辑。大多数情况下,为不同的用例创建单独的类更容易。
如果字段引用列表中的所有路径都解析为空白字段,则系统不会显示使用该字段引用的项。如果您希望使用该字段引用的项始终存在,请确保至少有一个路径不为空。我们建议您将某个字段设置为特殊字符(例如“-”)以表示空值,即使某些字段允许只包含空格的字符串也是如此。
如需引用列表中包含的字段,您可以使用列表中的字段索引,或者,在大多数情况下,您可以使用引用 ID。可通过 ID 引用的列表中的项都具有 .id
字段。我们建议您在可行的情况下使用引用 ID,而不是字段索引。
下面的示例展示了如何引用列表中包含的字段。
object.imageModulesData[0].id = my-first-id
object.imageModulesData[1].id = my-second-id
class.detailsTemplateOverride.detailsItemInfos[0].item.firstValue.fields[0].fieldPath = object.imageModulesData[‘my-second-id’]
class.detailsTemplateOverride.detailsItemInfos[1].item.firstValue.fields[0].fieldPath = object.imageModulesData[0]
在此示例中,卡券的详细信息部分中的第一项是在对象中声明的第二张图片。与此同时,卡券的详细信息部分中的第二项是在对象中声明的第一张图片。
默认模板
|
|
对于图片模块字段,我们在类和对象中只能显示一个图片模块字段。如果您在任一级别需要多个图片模块字段,请替换默认模板。
对于文本模块字段,我们在类和对象中最多只能显示 20 个文本模块字段。这些字段的显示顺序与在数组中定义它们的顺序相同。如果您在任一级别需要 20 个以上文本模块字段,请替换默认模板。
对于消息,我们在类和对象中最多只能显示 20 条消息。我们不保证消息的顺序。如果您在任一级别需要 20 条以上消息,或需要对任何订单提供保证,请替换默认模板。
对于链接模块字段,您可以定义的 URI 数量没有限制。对于每个级别(类或对象),URI 按以下顺序进行显示和分组:
- 地图坐标
- 电话号码
- 电子邮件地址
- 网页
对于每个组,URI 的显示顺序与在数组中定义它们的顺序相同。如果您需要不同的顺序,请替换默认模板。
|