---
metadata:
  - name: generator
    content: Diplodoc Platform v5.66.1
alternate:
  - https://appmetrica.yandex.by/docs/en/data-collection/custom-events.md
  - https://appmetrica.yandex.by/docs/ru/data-collection/custom-events.md
  - https://appmetrica.yandex.by/docs/zh/data-collection/custom-events.md
  - href: https://appmetrica.yandex.by/docs/zh/data-collection/custom-events.md
    type: text/markdown
    title: Markdown version
  - href: https://appmetrica.yandex.by/docs/zh/llms.txt?revision=r22076204
    rel: describedby
---
> **Documentation Index:** Fetch the complete configuration index at https://appmetrica.yandex.by/docs/zh/llms.txt?revision=r22076204

# 自定义事件

{% note info %}

自定义事件在每月 1 亿次以内免费。 更大的限额需要额外付费。

该限额适用于组织内所有应用。 [选择套餐并增加限额](https://appmetrica.yandex.by/docs/zh/common/pricing/ru-currency.md)。

{% endnote %}

自定义事件是您为应用中特定的操作创建的事件。 它们也被称为客户端或用户事件。 例如，您可以用它们来研究功能的使用、按钮点击或跳转到特定屏幕。

AppMetrica 不会自动确定此类操作的含义。 您需要选择事件名称、参数和发送时机，然后将收集任务交给开发者。

## 如何配置自定义事件收集 {#setup}

分析师或产品经理描述需要衡量的操作，将任务交给开发者，并在配置后检查结果。

![配置自定义事件收集的步骤](../../_images/custom-events-steps-horizontal-zh.png){style="border: solid 1px #cccccc; max-width: 100%;"}

### 1. 确定任务 {#step-task}

提出您想通过事件回答的问题。 例如：用户最常将哪些类别的商品加入收藏？ 选择有助于获得答案的操作。

### 2. 描述事件和参数 {#step-describe}

创建标记 — 包含发送规则的事件列表。 对于每个事件，请指定：

- **名称和用途**。 事件记录什么操作，以及用于什么分析。
- **发送时机**。 在什么条件下操作被视为完成：例如，当商品成功加入收藏时。
- **参数**。 报告中需要哪些操作详情。 对于每个参数，请指定名称、值类型和可能的值。
- **预期发送次数**。 例如，每次成功将商品加入收藏发送一个事件。

{% cut "网上商店的标记示例" %}

**任务**：找出最常被加入收藏的商品类别。

**事件**：`product_added_to_favorites`。

**何时发送**：在商品成功加入收藏后发送一次。 如果添加失败或商品已在收藏中，则不发送事件。

**参数**：

- `product_id` — 商品标识符，字符串。 例如，`sneakers_042`。
- `category` — 商品类别，字符串。 例如，`shoes`、`clothing` 或 `accessories`。
- `source` — 商品添加来源，字符串：`catalog` — 从目录或 `product_card` — 从商品卡片。

**如何检查**：从商品卡片将运动鞋加入收藏。 预期结果是一个 `product_added_to_favorites` 事件，参数为 `product_id: sneakers_042`、`category: shoes` 和 `source: product_card`。

{% endcut %}

这是标记示例：您为自己的应用选择事件、参数及其值的名称。

### 3. 将任务交给开发者 {#step-developer}

将标记和用于验证的操作示例交给开发者。 商定每个操作在哪里记录 — 在应用中还是在服务器上 — 以及在哪个版本的应用或服务器服务中会出现发送。 请开发者在可以检查配置时通知您。

开发者的技术说明收集在下面。

{% note info %}

标记描述了需要记录什么操作以及在什么时机记录。 开发者在应用或服务器中添加发送，并按商定的规则传输参数。

{% endnote %}

{% cut "给开发者：配置发送和事件参数" %}

{% file src="../../_assets/instructions/custom-developer-zh.txt" name="custom-developer-zh.txt" type="text/plain; charset=utf-8" %}

#### 如何通过 SDK 发送 {#send-via-sdk}

开发者在发生所选操作的代码位置添加 SDK 方法调用。 使用平台的说明：

- [Android](https://appmetrica.yandex.by/docs/zh/sdk/android/analytics/android-operations.md#report-event)
- [iOS](https://appmetrica.yandex.by/docs/zh/sdk/ios/analytics/ios-operations.md#report-event)
- [Flutter](https://appmetrica.yandex.by/docs/zh/sdk/flutter/analytics/flutter-operations.md#report-event)
- [React Native](https://appmetrica.yandex.by/docs/zh/sdk/react-native/analytics/react-native-operations.md#report-event)
- [Unity](https://appmetrica.yandex.by/docs/zh/sdk/unity/analytics/unity-operations.md#report-event)

#### 如何从服务器发送 {#send-from-server}

如果操作信息在服务器上可用，请使用[通过 Post API 上传事件](https://appmetrica.yandex.by/docs/zh/mobile-api/post/post-import-events.md)。 数据通过 HTTP 请求传输，并与之前通过 SDK 传输的个人资料或设备标识符关联。

在配置之前，请检查[上传限制](https://appmetrica.yandex.by/docs/zh/mobile-api/post/restrictions.md)。 Post API 数据每四小时同步一次 — 检查时请考虑这一点。

#### 事件嵌套级别 {#level}

要发送包含嵌套参数的事件，请传递 `key:value` 对。 在界面中，`key` 和 `value` 被视为嵌套级别。

![键值对](../../_images/levels.png){style="border: solid 1px #cccccc; max-width: 800px;"}

{% note info %}

AppMetrica 允许在事件中传递可以有多级的嵌套参数。

{% endnote %}

以 JSON 格式传递参数时，值中的每个新对象表示一个新的嵌套级别，例如：

```
{
"param1":"1",  // 嵌套级别 1
"param2":"abc",
"param3": { 
	"paramLevel2": "2", // 嵌套级别 2
	"param2Level2": {
		"paramLevel3": "3", // 嵌套级别 3
		"param2Level3":{
			"level": "4" // 嵌套级别 4
      }
    }
  }
}
```

AppMetrica 网页界面显示事件最多五级嵌套。 如果事件有六级或更高级别，报告中只显示前五级。

{% note info %}

您可以使用[报告 API](https://appmetrica.yandex.by/docs/zh/mobile-api/stat/intro.md)获取最多十级事件嵌套。

{% endnote %}

#### 数值和字符串值的解释 {#value}

在AppMetrica界面中，值`{"count" : 3}`和`{"count" : "3"}`被以相同方式解释。 但是，在使用[报告 API](https://appmetrica.yandex.by/docs/zh/mobile-api/stat/intro.md)或[日志 API](https://appmetrica.yandex.by/docs/zh/mobile-api/logs/about.md)导出数据时，参数会以发送到服务器时的相同形式导出。

如果同一个事件多次传递不同的数值参数，网页界面不会对参数值进行聚合。 每个值都单独记录和计算。

{% note info %}

您可以使用[报告 API](https://appmetrica.yandex.by/docs/zh/mobile-api/stat/intro.md)导出额外字段：所有数值的总和和平均值。

{% endnote %}

#### 部分匹配的嵌套事件 {#similar}

您可以为同一事件传递不同的参数值。

如果服务器接收到具有重复参数的事件，其值会被累积，报告中会显示每个传递变体的数量。

如果服务器接收到参数重复但嵌套深度不同的事件，则会根据重复的参数将它们的值相加。

例如，第一个事件有两个嵌套级别：

```
{
    "param1": "param2"
}
```

第二个有三级嵌套：

```
{
    "param1": {
        "param2": "value"
    }
}
```

在网页界面中，这些事件以树形结构显示：

![树形视图](../../_images/example.png){style="border: solid 1px #cccccc; max-width: 800px;"}

事件按以下算法进行计数：

1. 事件已被记录，包括其两个子级。 每个参数都加上1。
1. 事件名称和其三个子级别中添加了1。

{% endcut %}

### 4. 检查事件收集 {#step-check}

配置后，在商定的应用版本中执行准备好的测试操作。 打开[事件](https://appmetrica.yandex.by/docs/zh/mobile-reports/events-report.md)报告并检查：

- 是否出现了标记中名称的事件。
- 是否传输了所需的参数，以及它们的值是否与执行的操作匹配。
- 事件数量是否与预期发送次数匹配。

使用其他参数值重复检查。 如果结果与标记不同，请向开发者描述操作、预期结果以及您在报告中看到的内容。 修复后重复检查。 通过 Post API 发送时，请记住事件每四小时同步一次。

### 5. 在分析中使用事件 {#step-analyze}

检查后，在事件报告中使用事件及其参数。 要分析操作序列并找到用户停止的阶段，请配置[漏斗](https://appmetrica.yandex.by/docs/zh/mobile-reports/funnels-report.md)。

## 事件如何计数 {#accounting}

自定义事件消耗组织的配额。 带参数发送计为一个事件，无论参数数量和嵌套深度如何。 当前条件见[限额说明](https://appmetrica.yandex.by/docs/zh/troubleshooting/limit-events.md)，优化建议见文章[如何节省事件](https://appmetrica.yandex.by/docs/zh/data-collection/save-on-events.md)。

<!-- source: zh/_includes/feedback-button.md -->
如果您没有找到所需答案，可以通过反馈表单提交您的问题。 请尽可能详细地描述问题。 如果可能，请附上截图。

<a href="../troubleshooting/feedback-new">
  <span class="button">联系支持</span>
</a>

<a href="../troubleshooting/feedback-docs">
  <span class="button">为文档提出改进建议</span>
</a>
<!-- endsource: zh/_includes/feedback-button.md -->