> ## Documentation Index
> Fetch the complete documentation index at: https://documentation.onesignal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 使用 HTML 设计应用内消息

> 使用 OneSignal 的 HTML 编辑器设计和自定义应用内消息，实现最大的灵活性、响应式设计和品牌化效果。

## 概述

OneSignal 提供两种应用内消息编辑器：

* [拖放编辑器](./design-your-in-app-message) GUI 适合非技术创作者
* HTML 编辑器适合希望对布局、行为和响应式设计进行像素级精确控制的开发人员。

<Frame caption="展示应用内代码和渲染效果的图片">
  <img src="https://mintcdn.com/onesignal/Xl2NHJvxakrK4JbL/images/docs/f33b4e3-iam-html-2.png?fit=max&auto=format&n=Xl2NHJvxakrK4JbL&q=85&s=0a0527678d2d094109186fea726918be" width="1700" height="1000" data-path="images/docs/f33b4e3-iam-html-2.png" />
</Frame>

**HTML 编辑器的功能：**

* **布局：** 构建复杂的响应式布局（例如，并排的 CTA 按钮）。
* **表单：** 内联收集输入信息（邮箱、反馈、调查）。
* **字体和品牌：** 使用自定义网络字体和 CSS 变量。
* **JS 操作：** 跟踪点击、标记用户、发送结果等。

### 需求

* **iOS：** 3.9.0+
* **Android：** 4.6.3+
  * 如果您的应用使用较旧的 SDK，应用内消息将以中心模态布局进行渲染。

***

## 创建和预览 HTML 应用内消息

转到**消息 > 新建应用内消息**来创建、编辑、测试、暂停、复制或删除您的应用内消息。

<Columns cols={2}>
  <Card title="HTML 模板" href="./in-app-html-templates" arrow={true}>
    使用预建模板快速开始。
  </Card>

  <Card title="应用内 JavaScript 库" href="./in-app-message-api" arrow={true}>
    使用我们的 JavaScript 库跟踪交互和触发应用内行为。
  </Card>
</Columns>

在左侧输入您的 HTML 代码并实时预览。使用**发送测试应用内消息**来测试响应式设计和效果。

<Frame caption="显示 HTML 编辑器和预览的图片">
  <img src="https://mintcdn.com/onesignal/6v_cVPknFpo5qSVB/images/docs/04df3a9-Screenshot_2023-04-15_at_11.54.11_AM.png?fit=max&auto=format&n=6v_cVPknFpo5qSVB&q=85&s=db3ac070e794e0c594850a61b2f95927" width="1770" height="1198" data-path="images/docs/04df3a9-Screenshot_2023-04-15_at_11.54.11_AM.png" />
</Frame>

### 添加可跟踪标签

在交互元素上添加 `data-onesignal-unique-label`，以便跟踪和处理点击。

```html theme={null}
<button class="tag-user" data-onesignal-unique-label="my-tag-user-button">Tag User</button>
```

### 使用 JavaScript 绑定点击操作

```js theme={null}
// Tag the user when they click a button
document.querySelector(".tag-user").onclick = (e) => {
  OneSignalIamApi.tagUser(e, { fiz: "baz" });
};
```

<Note>
  在[应用内 JS 库文档](./in-app-message-api)中了解更多。
</Note>

### 资源支持

资源在渲染时从您提供的 URL 加载。

```html theme={null}
<img src="https://media.onesignal.com/iam/default_image_20200320.png" alt="Promo" />
```

### 个性化

使用 [Liquid 语法](./using-liquid-syntax)动态插入用户数据值：

```html theme={null}
<div>Hi there {{ name | default: 'you' }}!</div>
```

**支持的上下文：**

* 元素内的文本，如 `div`、`p`、`li`
* `<style>` 块内
* 在属性 `href`、`src`、`action` 和 `data` 中

**不支持在：**

* `<script>` 标签内
* 跨复杂嵌套内容，其中解析会变得模糊，例如：

```html theme={null}
<div>
  Hi {{name}}
  <span>Here's your coupon!</span>
</div>
```

***

## 可访问性和响应式设计

使用 CSS 媒体查询和平台字体来适应设备尺寸和操作系统文本设置。

```css theme={null}
@media only screen and (max-width: 620px) {
  .btn-primary { width: 100% !important; }
}
/* Respect dynamic text sizes on iOS */
:root { font: -apple-system-body; }
```

### 安全区域（刘海、主页栏）

现代设备具有安全区域（如刘海或主页栏）。使用 `safe-area-inset-*` 变量来为您的布局添加内边距：

```css theme={null}
body {
  padding-top: var(--safe-area-inset-top);
  padding-right: var(--safe-area-inset-right);
  padding-bottom: calc(var(--safe-area-inset-bottom) + 20px);
  padding-left: var(--safe-area-inset-left);
  margin: 0;
}
```

### 嵌入视频

您可以使用 `<iframe>` 在应用内消息中直接嵌入视频（例如 YouTube、Vimeo）。
这对于演示、宣传或入门流程非常有用。

大多数浏览器只允许**在视频静音开始时自动播放**，所以始终在嵌入 URL 中包含 `&mute=1`。

<Note>
  自动播放视频可能影响性能。保持视频简短，并避免在单个应用内消息中嵌入多个自动播放的视频。
</Note>

#### 示例：自动播放 YouTube 嵌入

下面的代码片段展示了如何在应用内消息中将 YouTube 视频居中显示，并设置固定尺寸（560×315）：

```html theme={null}
<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <style>
      body {
        margin: 0;
        height: 100vh;
        display: flex;
        justify-content: center; /* center horizontally */
        align-items: center;     /* center vertically */
        background: #f0f0f0;     /* optional background */
      }
      .video-box {
        width: 560px;  /* fixed width */
        height: 315px; /* fixed height (16:9 ratio) */
        box-shadow: 0 4px 12px rgba(0,0,0,0.2);
        border-radius: 8px;
        overflow: hidden;
        background: #000;
      }
      .video-box iframe {
        width: 100%;
        height: 100%;
        border: none;
      }
    </style>
  </head>
  <body>
    <div class="video-box">
      <iframe src="https://www.youtube.com/embed/bH60T1PZg1c?autoplay=1&mute=1"
        allow="autoplay; encrypted-media"
        allowfullscreen>
      </iframe>
    </div>
  </body>
</html>
```

#### 理解自动播放行为

* 嵌入 URL（/embed/VIDEO\_ID）是自动播放所必需的——正常的 watch?v= 链接不会生效。

* 添加 ?autoplay=1\&mute=1 确保视频自动播放并符合浏览器的自动播放规则。

* allow="autoplay; encrypted-media" 属性授予自动播放权限。

* .video-box 使用固定的 560×315px 尺寸（YouTube 默认的 16:9 比例），使视频显示为包含式而不是全屏拉伸。

* body 设置为 flex 容器，使用 justify-content: center 和 align-items: center 将视频框精确地定位在屏幕中央。

***

## 性能提示

* 优先使用内联关键 CSS；延迟加载繁重脚本。
* 优化图片（使用带有 `object-fit` 的尺寸化 `<img>`），尽可能使用现代格式。
* 保持 HTML 载荷简洁；避免大型 base64 数据。
* 使用系统字体或使用 `font-display: swap` 的高性能网络字体。
* 减小文件大小并使用适当的分辨率：
  * [Apple 图片指南](https://developer.apple.com/design/human-interface-guidelines/ios/icons-and-images/image-size-and-resolution/)
  * [Android 图片概览](https://developer.android.com/guide/topics/graphics)
  * OneSignal 与 [imagekit.io](https://imagekit.io/) 无关联，但它是一个有用的优化工具。

### 跨设备测试

经常发送测试消息以确认不同设备类型上的行为和布局。请参见[查找和设置测试订阅](./test-users)。

***

## 常见问题

### 我可以移除横幅样式应用内消息的灰色背景或阴影吗？

可以。对于顶部/底部横幅，请更新您的 SDK 并设置：

**iOS 5.1.5+**

```xml theme={null}
<key>OneSignal_in_app_message_hide_drop_shadow</key>
<true/>
<key>OneSignal_in_app_message_hide_gray_overlay</key>
<true/>
```

**Android 5.1.9+**

```xml theme={null}
<meta-data android:name="com.onesignal.inAppMessageHideGrayOverlay" android:value="true"/>
<meta-data android:name="com.onesignal.inAppMessageHideDropShadow" android:value="true"/>
```

### 我可以重复使用来自其他提供商的应用内模板吗？

可以。将您的 HTML 粘贴到编辑器中，并用 OneSignal 应用内 JS 方法替换分析/操作。

### 我没有模板。如何开始？

使用提供的启动模板或[浏览可用模板](./in-app-html-templates)。建议具备一些 HTML/CSS 经验。

### 需要什么 SDK 版本？

* **iOS：** 3.9.0+
* **Android：** 4.6.3+

较旧的 SDK 将回退到中心模态渲染。

### 应用内消息在离线时能工作吗？

不能。消息需要活跃的互联网连接来获取和渲染内容。

***
