Uni-app Vite Plugin User Guide

The Tingyun uni-app Vue3 user-action collection plugin—used in conjunction with the Tingyun App SDK or Mini Program SDK—provides descriptive names for user actions occurring within page and component templates.

Scope

This plugin applies to uni-app Vue3 projects built using Vite:

• App: Vue/nvue templates (targeting app or app-harmony).
• Mini Programs: WeChat, Baidu, Alipay, DingTalk, JD.com, and Feishu.

The plugin processes explicitly bound click and tap events within templates. click is enabled by default, while tap must be explicitly enabled via action.events.

• App Vue: Supports built-in component nodes recognized by the framework, such as view, text, and button.
• App nvue: Supports nodes including view, text, image, and button. Certain built-in components (e.g., picker, checkbox, slider) are not currently instrumented. For HarmonyOS, .nvue files processed via the Vue compilation path follow the same rules as "App Vue."
• Events bound to custom component tags are not instrumented; however, nodes within a custom component's internal template that meet the aforementioned criteria can be instrumented.

Note that the target platform must support and actually trigger the corresponding events. The plugin does not add new business-logic event listeners, nor does it process events such as change or input. Vue2, uni-app x, and standard Vue/Vite projects are outside the scope of this plugin.

Installation Guide

1. Install the Plugin

Run the following command in your project's root directory:

npm install --save-dev @tingyun-common/vite-plugin-uniapp

2. Configure the Plugin

Follow the integration steps below based on how your project was created. Projects created via CLI (Command Line Interface) should be treated as CLI projects, even if opened within HBuilderX.

Projects Created via HBuilderX (No Existing Vite Configuration)

Create a vite.config.js or vite.config.ts file in the same directory as manifest.json (choose one). The following example uses vite.config.js:

import { defineConfig } from 'vite'
import uni from '@dcloudio/vite-plugin-uni'
import { createTingyunUniAppPlugin } from '@tingyun-common/vite-plugin-uniapp'

export default defineConfig({
  plugins: [
    uni(),
    createTingyunUniAppPlugin(),
  ],
})

The project structure is as follows:

Project Root Directory/
├── manifest.json
├── pages.json
├── main.js
├── package.json
└── vite.config.js

Keep uni() in the example, as it handles the compilation of the uni-app project. The dependencies for Vite and uni-app compilation are provided by HBuilderX; no additional installation is required.

After saving the configuration, simply re-run the project in HBuilderX. For details on Vite configuration, please refer to the DCloud documentation.

Projects Created in HBuilderX: With Existing Vite Configuration

Open the vite.config.js or vite.config.ts file located at the same level as manifest.json. Add the two lines marked with + below, while leaving the rest of your existing configuration unchanged (the + symbols are for indication only and should not be copied):

 import { defineConfig } from 'vite'
 import uni from '@dcloudio/vite-plugin-uni'
+import { createTingyunUniAppPlugin } from '@tingyun-common/vite-plugin-uniapp'

 export default defineConfig({
   plugins: [
     uni(),
+    createTingyunUniAppPlugin(),
     // ...other existing plugins
   ],
 })

After saving, re-run the project in HBuilderX.

Projects Created via CLI

Open vite.config.js or vite.config.ts (located at the same level as package.json) and add the two lines marked with + below. Keep all other configurations as they are (the + symbol is used only to indicate new additions and should not be copied):

 import { defineConfig } from 'vite'
 import uni from '@dcloudio/vite-plugin-uni'
+import { createTingyunUniAppPlugin } from '@tingyun-common/vite-plugin-uniapp'

 export default defineConfig({
   plugins: [
     uni(),
+    createTingyunUniAppPlugin(),
     // ...other existing plugins
   ],
 })

After saving, execute your project's existing npm run or build command.

3. Integrating the Target Platform SDK

The build-time plugin injects code to capture user interactions, while the actual data collection and reporting are handled by the runtime SDK. Please integrate the appropriate SDK for your target platform:

• App: Integrate @tingyun-sdk/uniapp-app. Refer to the SDK's README for details.
• Mini Program: Integrate the Tingyun Mini Program SDK for your specific platform. Refer to the Tingyun uni-app integration documentation for that platform.

4. Verifying the Integration

1. Recompile your project and check the [build_end] log for [tingyun-uniapp-plugin] in the HBuilderX build console or your CLI terminal. If result=completed and the injected value within counts is greater than 0, the instrumentation of user interactions has been successfully completed.
2. Run the project, trigger an existing @click event on a page, and—once the data has been reported—check the Tingyun Web Console to view the corresponding interaction. For naming conventions, please refer to Event and Interaction Names below.

Configuration Details

The following type definition outlines the available configuration options and their default values. You can import TingyunUniAppPluginOptions from the package in your project to enable type hints.

type MiniProgramPlatform =
  | 'mp-weixin' | 'mp-baidu' | 'mp-alipay'
  | 'mp-dingtalk' | 'mp-jd' | 'mp-lark'

type LogLevel = 'error' | 'warn' | 'info' | 'debug'

interface TingyunUniAppPluginOptions {
  action?: {
    enabled?: boolean // 默认 true
    events?: readonly ('click' | 'tap')[] // 默认 ['click']，至少一项
    exclude?: readonly string[] // 默认 []，相对于源码根的 glob
    miniProgram?: {
      enabled?: boolean // 默认 true
      platforms?: readonly MiniProgramPlatform[] // 默认全部六端，至少一项
    }
    app?: {
      enabled?: boolean // 默认 true
      renderers?: readonly ('vue' | 'nvue')[] // 默认两者，至少一项
    }
  }
  failureMode?: 'continue' | 'throw' // 默认 continue，控制节点处理失败
  logging?: {
    console?: {
      enabled?: boolean // 默认 true
      level?: LogLevel // 默认 info
    }
    file?: {
      enabled?: boolean // 默认 false
      level?: LogLevel // 默认 debug
      directory?: string // 默认 .tingyun/logs，相对项目根或绝对路径
      maxFileSize?: number // 默认 5242880 字节，至少 65536
      maxBuilds?: number // 默认 10，保留的非活动构建轮数
    }
  }
}

For JavaScript projects, simply pass the configuration object. TypeScript Project Example:

import {
  createTingyunUniAppPlugin,
  type TingyunUniAppPluginOptions,
} from '@tingyun-common/vite-plugin-uniapp'

const options: TingyunUniAppPluginOptions = {
  action: {
    events: ['click', 'tap'],
    exclude: ['pages/legacy/**'],
  },
  logging: {
    file: { enabled: true },
  },
}

// Use createTingyunUniAppPlugin(options) within your existing plugins array

action.enabled controls the handling of actions by the compilation plugin; sub-options for "App" and "Mini Program" allow for platform-specific configuration. app.renderers distinguishes between different template compilation phases; .vue sub-components referenced during the nvue compilation phase are also governed by the nvue configuration.

Setting failureMode to 'continue' allows the build process to proceed even if processing at a specific node fails, whereas 'throw' passes the exception to the build tool. If configuration or plugin installation fails, a diagnostic message is issued and the plugin ceases operation; build errors originating from the host environment itself will continue to be reported by the host.

Events and Action Names

Use action.events to select the template events you wish to capture. By default, @click is captured; if set to ['click', 'tap'], @tap will also be captured.

If both events are bound to the same node and both are enabled, the App platform handles them separately, while Mini Programs prioritize the action name associated with click. The actual number of times a business event is triggered is determined by the platform.

Action names are derived from the template syntax:

Template Syntax	Action Name
@click="save"	save
@click="form.save(item)"	form.save
Static data-ty-action="Purchase Item"	Purchase Item
Anonymous expression in a page	e.g., pages/home/index.vue#f0
Anonymous expression in a component	e.g., components/BuyButton.vue#f0

Template paths are relative to the source code root and retain their .vue or .nvue extensions. Identifiers are assigned based on the order in which the source code triggers the event; if the same component is reused across different pages, it retains the same name. Path unavailable or exceeded.

For both App and Mini Program SDKs, the maximum length for an action name is 1,024 characters. If a name exceeds this limit, it will be truncated, and data collection will continue; note that identical prefixes may result in duplicate names.

It is recommended to specify names using static attributes:

<button data-ty-action="Submit Order" @click="submit">Submit</button>

In the App environment, dynamic bindings (e.g., :data-ty-action) are ignored for action tracking; in the Mini Program environment, the runtime SDK reads these values from the dataset.

Excluding Files and Nodes

File exclusion paths are relative to the source code root—typically src/ for CLI-based projects, or the project root directory for projects created via HBuilderX. Use forward slashes (/) as separators and specify relative paths (e.g., pages/legacy/**, components/DebugButton.vue).

Rules are case-sensitive and support *, **, ?, character classes, curly braces, and extglob patterns; for directories, use the dir/** format. Rules must be relative paths; backslashes, standalone . or .. path segments, and leading ! characters are not supported. Excluding a page applies only to that specific file; any components referenced within it are evaluated based on their own individual paths.

To exclude nodes, use a static attribute:

<view data-ty-action-ignore="true" @click="parentClick">
  <button @click="childClick">Child nodes are still tracked</button>
</view>

This attribute applies only to the current node, and its value must be the string "true". Existing data-ty-action attributes in Mini Programs remain unaffected, and the runtime SDK will continue to collect data based on those attributes.

Compatibility

Build verification has been completed for uni-app CLI compiler version 4.75 and HBuilderX version 5.24. For Node.js environment requirements regarding CLI-based projects, please refer to the official uni-app documentation.

Verification and Troubleshooting

For integration verification, please refer to the Installation Wizard. If no operations are captured, verify that the platform, event type, and rendering type are enabled, and ensure that the target platform SDK has been initialized and configured to capture operations.

To examine the template processing workflow in detail, set logging.console.level: 'debug'. Common diagnostic messages:

Diagnostic	What to Check
installed	The plugin is correctly integrated into the build chain; proceed to check the runtime SDK.
host_unsupported	Confirm that the project is a uni-app Vue3/Vite project.
vue_entry_unavailable / compiler_unavailable	Check the uni() configuration, compiler version, and ensure there are no duplicate Vue plugins.
config_invalid	Verify the configuration types and values against the provided prompts.
duplicate_plugin	Only the first registration per build is kept; the initial configuration takes precedence.
init_failed / node_failed	Identify the failure based on the stage, file, and location.
template_path	Verify the template path; specify a static name if necessary.

Saving Build Logs

createTingyunUniAppPlugin({
  logging: {
    console: { level: 'info' },
    file: { enabled: true, level: 'debug' },
  },
})

By default, the console outputs a basic build summary; setting the level to debug provides additional details on template processing. The log format is YYYY-MM-DD HH:mm:ss.SSS ±HH:MM [tingyun-uniapp-plugin] [LEVEL] [code] message, which includes the local timestamp and UTC offset, with log levels in uppercase and diagnostic codes in lowercase. Logs are saved by default in the .tingyun/logs directory; the initial summary provides the buildId and the actual file path. It is recommended to add this directory to your .gitignore file.

Each build cycle generates a separate log file, which is split if it exceeds the maxFileSize limit. The maxBuilds setting governs the cleanup of logs from inactive build cycles. Rebuilds triggered by "watch" mode are logged separately, and builds for Vue and nvue (in App mode) are recorded individually. The plugin’s final summary indicates the conclusion of the compilation stage; the ultimate build outcome is determined by the uni-app output.