---
title: "自定义标签"
description: "将应用中的值传递给流程，并在文本元素中显示。"
---

> **AI agents**: to search Adapty docs faster and with fewer tokens, install the Adapty skill. Claude Code (self-updating via plugin): `claude plugin marketplace add adaptyteam/adapty-skills && claude plugin install adapty-skills@adapty` — other tools: `npx skills add adaptyteam/adapty-skills --all`

自定义标签是一种[自定义变量](onboarding-variables#custom-variables)，其值来自你的应用。在变量设置中选择 **Value comes from outside the app** 后，你的应用即可通过 Adapty SDK 为其赋值。例如，某个文本元素包含"Coins:"和一个自定义标签。如果应用传入"120"，用户看到的就是"Coins: 120"。

自定义标签适用于展示：

- **用户身份**：问候语中的用户名，例如"欢迎回来，DragonSlayer42！"
- **用户拥有的内容**：连续签到的天数，或玩家的等级。
- **应用计算的内容**：大容量套餐的折扣，或根据用户在早期流程中填写的答案计算出的 [BMI](ios-flow-custom-tags#example-show-a-bmi-from-onboarding-answers)。

## 值与备用值 \{#values-and-fallbacks\}

您的应用通过自定义标签的名称来识别每个值。值始终为字符串类型，Adapty 不会对字符串进行格式化或翻译，因此您的应用必须在值显示于流程之前将其处理为可读格式。例如，请传入 "1,250"，而非 "1250.0"。

在以下情况下，用户会看到自定义标签的**初始值**作为备用内容：

- 您的应用未为该标签传递任何值。
- 用户尚未将应用更新到能传递该值的版本。
- 应用代码中的名称与标签的完整名称不匹配，包括字母大小写。
- 同一文本元素中的另一个自定义标签没有值。此时该文本元素中的每个自定义标签都会显示其初始值。

如需在标签位置不显示任何内容，请传入空字符串。Adapty 将空字符串视为有效值，因此不会显示备用内容。

## 1. 创建自定义标签 \{#create-a-custom-tag\}

1. 在流程编辑器中打开 Variables Variables 面板。
2. 添加新变量——点击 Plus。
3. 配置变量的 **Name**。你的应用代码必须完全匹配该名称，包括大小写。
   - **Characters**：使用拉丁字母（A–Z 和 a–z）、数字、`_` 和 `-`。如需将标签归入某个分组，以分组名加点号开头，例如 `user.streak`。
   - **Reserved names**：无论大小写，不能使用保留名称，例如 `PRICE`、`TITLE`、`VALUE`，或以 `TIMER_` 开头的名称。
   - **Uniqueness**：名称在当前流程中必须唯一。
4. （可选）如需区分不同变量，可填写 **Description** 字段。在编辑器中将鼠标悬停在变量名称上时，即可查看该描述。
5. 在 **Initial value** 字段中，输入当应用未传递值时用户看到的备用内容：
   - **适用于所有用户的通用词**：对于问候语中的 `username` 标签，可输入 `friend`。未登录用户将看到"Welcome back, friend!"。请注意，初始值不支持本地化。
   - **余额或计数的占位符**：为避免未登录用户看到错误的余额数值，可输入破折号（`—`）。

6. （仅限 **String** 变量）勾选 **Value comes from outside the app** 复选框。此操作不可撤销，并会锁定 **Value Type**。
7. 点击 **Create variable**。

变量仅对当前流程有效。若要在其他流程中使用自定义标签，请在对应流程中创建一个同名变量。

### 用自定义标签替换变量 \{#replace-a-variable-with-a-custom-tag\}

只有在创建变量时，才能勾选 **Value comes from outside the app** 复选框。如果需要在流程中用应用内的实际值替换普通自定义变量（例如来自[已转换付费墙](convert-paywall-to-flow)的变量），请用自定义标签替换该变量：

1. 删除该变量及其在流程中的所有引用。
2. [创建一个同名的自定义标签](#create-a-custom-tag)。
3. 将自定义标签[插入](#add-a-custom-tag-to-a-text-element)到所有曾使用该变量的文本元素中。

## 2. 为文本元素添加自定义标签 \{#add-a-custom-tag-to-a-text-element\}

选择文本元素。在 **Content** 区域中，点击 Variables **Add variable**，然后在 **Custom** 标签页中选择该标签。

你可以将自定义标签插入[条件文本](onboarding-text#add-conditional-text)的每个分支，但无法在其 **if** 条件中选择它们。

## 3. 在应用中传入对应的值 \{#pass-the-values-from-your-app\}

你的应用代码必须使用每个自定义标签的完整名称，包括其所属分组。例如，如果 `user` 分组中有一个 `streak` 标签，则该标签的完整名称为 `user.streak`。

具体的配置代码取决于你使用的平台：

- [iOS](ios-flow-custom-tags)
- [Android](android-flow-custom-tags)
- [React Native](react-native-flow-custom-tags)
- [Flutter](flutter-flow-custom-tags)
- [Unity](unity-flow-custom-tags)
- [Kotlin Multiplatform](kmp-flow-custom-tags)
- [Capacitor](capacitor-flow-custom-tags)

要测试自定义标签，请在添加设置其值的代码后，在应用中打开流程。编辑工具画布和[在设备上预览](paywall-device-compatibility-preview#preview-on-devices)只显示初始值：Adapty 移动应用不会设置自定义标签的值。

## 限制 \{#limitations\}

- **仅限文本元素**：自定义标签只能插入文本元素中，不能插入以下内容：
  - **Set variable** 操作
  - **Show alert** 操作
  - **Open URL** 操作
  - 输入框占位文本
- **自定义标签不支持条件判断**：你无法在条件或条件显示中选择自定义标签。如需根据应用传入的值决定用户看到哪些句子、元素和页面，可以这样做：
  - **句子**：在应用代码中构建句子，然后将其作为标签的值传入。例如，对于 `coins_message` 标签，向有金币的玩家传入"You have 120 coins"，向其他玩家传入"Get your first coins"。
  - **元素和页面**：[将该值设置为自定义属性](setting-user-attributes)，然后基于该属性创建[目标受众](audience)，为其展示独立的流程。
- **流程打开后无法通过 SDK 方法更新值**：若要根据用户在流程中的输入展示结果，请将结果传递给下一个流程，具体可参考 [BMI 示例](ios-flow-custom-tags#example-show-a-bmi-from-onboarding-answers)。

The input is a comment block with no translatable prose (it is an unclosed MDX comment fragment). Returning it byte-for-byte unchanged.