# 在通行证构建器中设计 Google Wallet 通行证

Google Wallet 通行证构建器是控制面板中的一个可视化设计器。您可以选择通行证类型，填写品牌、字段和条形码，观看实时预览，然后创建通行证。当您生成通行证时，Pushwoosh 会在 Google Wallet 中创建通行证对象，并返回一个“添加到 Google Wallet”的保存链接。

## 创建通行证

<Aside type="note" title="需先进行配置">
只有在为应用程序配置了 Google Wallet（发行人 ID 和服务帐户密钥）后，构建器才可用。如果尚未配置，请先进行设置：[适用于 Android 的 Google Wallet 通行证配置](/zh/developer/first-steps/connect-messaging-services/android-configuration/android-google-wallet-configuration/)。
</Aside> 

在控制面板中，转到 **Campaigns → Wallet Passes**，打开 **Google Wallet** 选项卡，然后点击 **Create pass**。

<img src="/google-wallet-passes-pass-builder-1.webp" alt="Wallet Passes 页面，其中 Google Wallet 选项卡已打开，Create pass 按钮可见"/>


## 配置通行证

*   **从头开始：** 从一个空的通行证开始。选择一个通行证类型，然后在下面的部分中自行设置字段、外观、条形码和其他选项。

*   **从模板开始：** 点击 **Load template**，在 **Select Template** 中选择一个内置通行证（通用、优惠、会员、活动门票、礼品卡、航班或公交），然后确认。表单会预先填充通行证类型、字段、颜色和条形码。根据需要编辑任何值或更改类型。

### 选择通行证类型

在 **PASS TYPE** 下，选择七种 Google Wallet 通行证类型之一。该类型控制卡片布局和可用字段。类型化的通行证使用 Google 的原生布局。通用通行证是自由格式的。

*   **通用：** 使用您自己的字段自由格式的卡片。
*   **优惠：** 优惠券和折扣。
*   **会员卡：** 会员卡和会籍卡。
*   **活动门票：** 活动门票。
*   **礼品卡：** 礼品卡和预付卡。
*   **航班：** 登机牌。
*   **公交：** 火车、巴士、电车和渡轮票。



### 填写通行证字段

您看到的字段取决于通行证类型。必填字段已标记。每种类型的常见字段：

| 通行证类型 <div style="width:140px"></div> | 关键字段 |
| :---- | :---- |
| **通用** | 卡片标题*、页眉*、副页眉、卡片字段 |
| **优惠** | 标题*、提供商*、详情、细则、兑换渠道（店内/在线/两者）、发行人名称 |
| **会员** | 计划名称*、会员姓名、会员 ID、积分余额、积分标签、奖励等级、等级标签、发行人名称 |
| **活动门票** | 活动名称*、场馆、地址、开始/结束日期和时间、持票人、票号、类型、区域、排、座位、登机口 |
| **礼品卡** | 商户名称*、卡号*、PIN、余额 + 货币 |
| **航班** | 承运人 IATA 代码*、航班号*、始发地*、目的地*、出发时间*、乘客姓名*、登机时间、座位、舱位、登机组、确认码 |
| **公交** | 公交类型*（巴士/火车/电车/渡轮/其他）、运营商*、乘客*、行程类型、行程段（始发地*、目的地*、时间、站台、车厢、座位） |

\* Google 要求。

<Aside type="note" title="日期和时间">
大多数通行证类型使用带 UTC 偏移量的 ISO 8601（例如，`2026-07-01T19:30:00+02:00`）。航班通行证是个例外：Google 要求出发、登机和到达时间使用机场的**本地**时间，**不带**偏移量（例如，`2026-09-01T06:30:00`）。
</Aside>

#### 个性化通行证内容

每个通行证都与一个 [User ID](/zh/product/pushwoosh-knowledge-hub/users-userids/) 相关联。使用标签占位符来显示该用户独有的数据，例如会员卡上的积分余额或礼品卡上的收件人姓名。为每个 User ID 发行一个通行证，以便每个收件人都能获得自己的值。

要插入标签占位符：

1.  在支持的文本字段（例如，**Merchant**、**Card title** 或 **Header**）旁边，点击 `{}` 插入标签。
2.  在 **TAG** 中，选择要插入字段的[标签](/zh/product/audience-data-and-segmentation/user-data-tags/tags/)。
3.  在 **FORMAT** 中，选择如何显示标签值：**As is**（使用存储的值）、**Integer**（四舍五入为整数）、**Price (0.00)**（显示两位小数）或 **Capitalize first letter**（首字母大写）。
4.  在 **FALLBACK** 中，（可选）输入当收件人没有该标签值时要显示的文本。
5.  点击 **Insert**。

<img src="/google-wallet-passes-pass-builder-2.webp" alt="通行证字段，其中“插入标签”对话框已打开，显示“标签”、“格式”和“备用”选项"/>

Pushwoosh 在您创建通行证时填充标签值，并在每次更新时刷新它们。


### 设置外观

在 **APPEARANCE** 下，配置颜色、图片、谁可以保存通行证以及有效期。

#### 颜色

在 **Background color** 中输入十六进制代码，例如 `#FFFFFF` 表示白色。包括前导的 `#` 和六个字符。

#### 图片

<Aside type="caution" title="在公共 HTTPS URL 上托管图片">
Google Wallet 不存储您的徽标或主图。请将每个文件托管在一个保持在线且可访问的**公共 HTTPS URL** 上，然后将链接粘贴到通行证构建器中。如果 URL 损坏或文件被删除，图片将停止在通行证上加载。
</Aside>

在 **Logo URL** 中粘贴一个公共 HTTPS 链接。会员卡和公交通行证需要此项。

（可选）在 **Hero image URL** 中粘贴一个链接，用于在通行证正面的卡片详情下方显示一个宽幅横幅。推荐尺寸为 1032×336 像素。

<img src="/google-wallet-passes-pass-builder-3.webp" alt="外观部分，包含背景颜色、徽标 URL、主图 URL、谁可以保存通行证和到期日期字段"/>

<Aside type="tip" title="媒体库 URL">
您可以从[媒体库](/zh/product/content/media-store/)粘贴一个公共图片 URL，包括一个为该位置调整大小的[变体](/zh/product/content/media-store/#create-image-variants)。

**注意：** 如果您在媒体库中删除该图片，它将停止在通行证上加载。
</Aside>

#### 谁可以保存通行证

在 **Who can save the pass** 中，选择谁可以将通行证添加到 Google Wallet：

*   **One user, all their devices**（默认）：通行证与一个 Google 帐户关联，并在该帐户的设备之间同步。
*   **One user, one device：** 通行证仅保存在单个设备上。
*   **Anyone with the link：** 每个打开保存链接的 Google 帐户都会获得相同的共享通行证对象。当您更新通行证时，Google 会自动将更改分发给所有持有者。

<Aside type="note" title="任何持有链接的人">
对于所有持有者看到相同内容的通行证，请使用此选项，例如全店优惠或没有指定座位的公共活动门票。避免将其用于会员卡、礼品卡或任何内容必须为每个用户个性化的通行证。Pushwoosh 仅跟踪共享对象的一个设备，因此无法看到单个持有者，也无法单独定位他们。
</Aside>

#### 有效期

设置 **Expiration date**，即 Google 应使通行证到期的日期，或留空表示无有效期。

### 添加条形码

在 **BARCODE** 下，选择一种格式并输入要编码的值：

1.  **Format：** 选择条形码的外观以及可以读取它的扫描仪类型。
    *   **QR_CODE：** 大多数手机和扫描仪都能轻松读取的方形码。最适合大多数通行证。
    *   **PDF_417：** 由多行线条组成的宽条形码。登机牌通常需要此格式。
    *   **AZTEC：** 紧凑的方形码，类似于 QR 码。常见于活动和公交票据。
    *   **CODE_128** / **EAN_13：** 一维条形码。仅当您的扫描仪或 POS 系统需要时才选择这些。
2.  **Value：** 条形码中编码的数据（例如，票号或会员号）。要为每个用户使用唯一值，请点击字段旁边的 `{}` 并插入[标签占位符](#personalize-pass-content)。
3.  **Alt Text：** 显示在通行证上条形码下方的文本。

<img src="/google-wallet-passes-pass-builder-5.webp" alt="条形码部分，包含格式、值和替代文本字段"/>

### 添加详情字段和链接

在通行证的正面，用户会看到主卡。当他们打开通行证详情（背面）时，他们可以阅读额外的部分并点击您在此处添加的链接。

*   **Text modules：** 通行证背面的额外文本块。设置一个 **header**（部分标题）和一个 **body**（文本）。用于条款、说明或其他不适合放在正面的信息。
*   **Links：** 通行证背面的可点击链接。设置一个 **URL** 和一个简短的 **description**（例如，“商店定位器”或“条款和条件”）。

<img src="/google-wallet-passes-pass-builder-6.webp" alt="文本模块和链接部分，包含标题、正文、URL 和描述字段"/>

### 添加应用链接*（可选）*

在 **APP LINK** 下，在通行证正面添加一个按钮，点击后可打开网页或您的 Android 应用。您可以设置一个 **URL**、一个 **Android package name**，或两者都设置。

如果您只设置 URL，该按钮将在任何设备上打开该网址。如果您只设置包名，该按钮将在已安装该应用的 Android 设备上工作，没有网页备用方案。

<img src="/google-wallet-passes-pass-builder-4.webp" alt="应用链接部分，包含 URL 和 Android 包名字段"/>

### 添加位置*（可选）*

在 **Location-based relevance** 下，添加兴趣点。当用户靠近您添加的位置时，Google 会显示一个地理围栏通知。例如，在您的商店附近显示会员卡，在场馆附近显示活动门票，或在机场附近显示登机牌。

您最多可以添加 **10** 个位置，每个位置都由纬度和经度设置。

<img
  src="/google-wallet-passes-pass-builder-7.webp"
  alt="位置部分，包含用于添加兴趣点的纬度和经度字段"
  style={{ maxWidth: "480px", width: "100%", height: "auto" }}
/>

<Aside type="note" title="Google Wallet 上的位置">
Google 控制地理围栏的半径，并决定何时显示通知。您不能为每个位置设置最大距离。
</Aside>

### 输入 User ID

输入将收到此通行证的人的 Pushwoosh [User ID](/zh/product/pushwoosh-knowledge-hub/users-userids/#how-are-users-and-devices-related)。

Pushwoosh 会向该用户发行通行证，并在 [**All passes**](/zh/product/messaging-channels/google-wallet-passes/#view-and-manage-existing-passes) 的 **USER** 下列出。

### 预览和验证

**实时预览**会在您编辑时更新，因此您可以大致了解通行证在 Google Wallet 中的外观。

<Aside type="note" title="预览在设备上可能有所不同">
预览是一个近似值。类型化的通行证使用 Google 的原生布局，因此通行证在真实设备上可能看起来不同。显示的条形码是占位符。
</Aside>

要在不创建通行证的情况下根据 Google 的要求检查它，请点击 **Validate**。构建器会标记缺失的必填字段和其他问题。

## 生成通行证

点击 **Generate**。Pushwoosh 会检查通行证并在 Google Wallet 中创建它。您会得到一个**添加到 Google Wallet** 的保存链接，可以与用户分享。几秒钟内，该通行证会出现在 [**All passes**](/zh/product/messaging-channels/google-wallet-passes/#view-and-manage-existing-passes) 中。

有关创建后编辑、获取保存链接、作废和删除通行证的信息，请参阅[管理现有通行证](/zh/product/messaging-channels/google-wallet-passes/#view-and-manage-existing-passes)。

## 通过 API 管理通行证

通行证构建器所做的一切也都可以通过 [Google Wallet API](/zh/developer/api-reference/google-wallet-api/) 实现：创建、更新、列出、获取保存链接、设置状态和删除通行证。

<LinkCard title="Google Wallet API" href="/developer/api-reference/google-wallet-api/" />