> ## 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.

# 应用内消息 JavaScript API 参考

> OneSignal 中交互式 HTML 应用内消息的 JavaScript 方法。

本指南介绍了使用 [OneSignal HTML 编辑器](./design-your-in-app-message-with-html) 创建的 HTML 应用内消息的 **JavaScript API**。

如果您正在寻找设置触发器、处理应用内点击事件或管理应用内消息生命周期的 **SDK 方法**，请参阅 [移动端 SDK 参考](./mobile-sdk-reference#in-app-messages)。

***

## 要求

### 1. 使用 `data-onesignal-unique-label` 进行点击跟踪

所有可点击元素都必须具有带有 **唯一** 值的 `data-onesignal-unique-label` 属性。这使 OneSignal 能够：

* 跟踪点击分析
* 正确触发关联的操作

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

<Warning> 如果两个元素共享相同的 `data-onesignal-unique-label`，点击可能会被错误记录或操作可能不会触发。 </Warning>

### 2. 附加事件监听器

您必须显式附加 JavaScript 事件监听器来触发 OneSignal 应用内操作。

```javascript JavaScript theme={null}
document.getElementById("tag-user-button")
  .addEventListener("click", function(e) {
    OneSignalIamApi.tagUser(e, { fiz: "baz" });
  });
```

**示例:**

```html HTML theme={null}
<button id="tag-user-button" data-onesignal-unique-label="my-tag-user-button">
  Tag User
</button>
<script>
  document.getElementById("tag-user-button").addEventListener("click", function(e) {
    OneSignalIamApi.tagUser(e, { fiz: "baz" });
  });
</script>
```

***

## 可用函数

[块编辑器](./design-your-in-app-message) 中的所有 [点击操作](./iam-click-actions) 也适用于 HTML 应用内消息。

### 推送权限提示

显示原生推送通知权限提示。点击事件会自动跟踪。

请参阅 [推送权限提示](./prompt-for-push-permissions)。

```html HTML theme={null}
<button id="push-prompt-button" data-onesignal-unique-label="push-permission">
  Enable Push
</button>
<script>
  document.getElementById("push-prompt-button").addEventListener("click", function(e) {
    OneSignalIamApi.triggerPushPrompt(e);
  });
</script>
```

### 位置权限提示

显示原生位置权限提示。点击事件会自动跟踪。

请参阅 [位置权限提示](./location-opt-in-prompt)。

```html HTML theme={null}
<button id="location-prompt-button" data-onesignal-unique-label="location-permission">
  Enable Location
</button>
<script>
  document.getElementById("location-prompt-button").addEventListener("click", function(e) {
    OneSignalIamApi.triggerLocationPrompt(e);
  });
</script>
```

### 关闭应用内消息

关闭当前应用内消息。点击事件会自动跟踪。

```html html theme={null}
<button id="close-button" data-onesignal-unique-label="close-message">
  Close
</button>
<script>
  document.getElementById("close-button").addEventListener("click", function(e) {
    OneSignalIamApi.close(e);
  });
</script>
```

### 标记用户

设置 [标签](./add-user-data-tags)。点击事件会自动跟踪。

```html HTML theme={null}
<button id="tag-user-button" data-onesignal-unique-label="tag-user">
  Tag User
</button>
<script>
  document.getElementById("tag-user-button").addEventListener("click", function(e) {
    OneSignalIamApi.tagUser(e, { fiz: "baz" });
  });
</script>
```

### 打开 URL

在设备浏览器中打开 URL 并关闭应用内消息。点击事件会自动跟踪。

支持 [深度链接](./deep-linking)。

```html HTML theme={null}
<button id="open-url-button" data-onesignal-unique-label="open-website">
  Visit Site
</button>
<script>
  document.getElementById("open-url-button").addEventListener("click", function(e) {
    OneSignalIamApi.openUrl(e, "https://example.com");
  });
</script>
```

### 点击名称

分配一个可以在 [应用内消息点击监听器](./mobile-sdk-reference#addclicklistener-in-app) 中读取的点击名称。点击事件会自动跟踪。

支持 [深度链接](./deep-linking)。

```html HTML theme={null}
<button id="click-name-button" data-onesignal-unique-label="named-click">
  Click Me
</button>
<script>
  document.getElementById("click-name-button").addEventListener("click", function(e) {
    OneSignalIamApi.addClickName(e, "test_click_name");
  });
</script>
```

### 跟踪点击

在您不使用其他可点击 API 方法时跟踪点击事件。

```html html theme={null}
<button id="track-click-button" data-onesignal-unique-label="custom-track">
  Track Click
</button>
<script>
  document.getElementById("track-click-button").addEventListener("click", function(e) {
    OneSignalIamApi.trackClick(e);
  });
</script>
```

### 发送结果

跟踪 [自定义结果](./custom-outcomes)。点击事件会自动跟踪。

```html html theme={null}
<button id="send-outcome-button" data-onesignal-unique-label="bonus-claim">
  Claim Bonus
</button>
<script>
  document.getElementById("send-outcome-button").addEventListener("click", function(e) {
    OneSignalIamApi.sendOutcome(e, "bonus_claimed");
  });
</script>
```

***

## 个性化 HTML 应用内消息

您可以在 HTML 应用内消息中使用标签替换，就像在块编辑器中一样。

<Warning> 标签替换 **不适用于** `<script>` 标签内。 </Warning>

标签替换适用于：

* 内联文本（`<h1>`、`<p>`、`<li>` 等）
* `<style>` 规则：
  ```css CSS theme={null}
  body { background-color: "{{ favorite_color | default: '#fff' }}"; }
  ```
* 带 URL 的属性：
  * `href`
  * `src`
  * `<form action>`
  * `<object data>`

### 在 `openUrl()` 和 `addClickName()` 中使用标签

由于 `<script>` 标签不支持替换，请使用以下方法之一：

**1. 使用 `liquidPlayerTags` 访问所有标签**

此全局对象在 `DOMContentLoaded` 后可用。

```html HTML theme={null}
<div class="my-tags">--test checking all tags--</div>
<button id="open-url-button" data-onesignal-unique-label="promo-link">
  Personalized Offer
</button>
<script>
  document.addEventListener("DOMContentLoaded", function() {
    if (liquidPlayerTags) {
      // liquidPlayerTags becomes available afterthe DOMContentLoaded event confirm
      // by checking that the div with --replace with all tags-- is replaced with JSON
      document.querySelector(".my-tags").innerHTML = JSON.stringify(liquidPlayerTags);
    }
  });
  document.addEventListener("DOMContentLoaded", function() {
    document.getElementById("open-url-button").addEventListener("click", function(e) {
      OneSignalIamApi.openUrl(e, "https://shop.com?coupon=" + liquidPlayerTags["coupon"]);
    });
  });
</script>
```

**2. 在 `href` 属性中存储标签**

```html HTML theme={null}
<a
  id="open-url-button"
  href="app://deeplink?code={{ coupon | default: '10OFF' }}"
  data-onesignal-unique-label="promo-link"
>
  Redeem Offer
</a>
<script>
  document.getElementById("open-url-button").addEventListener("click", function(e) {
    e.preventDefault();
    OneSignalIamApi.openUrl(e, e.currentTarget.href);
  });
</script>
```

***

## 后续步骤

* 了解更多关于 [使用 Liquid 语法进行标签替换](./using-liquid-syntax) 的信息
* 探索 [深度链接](./deep-linking) 的 URL 处理
* [使用 HTML 设计应用内消息](./design-your-in-app-message-with-html)

***