Ask users logo
Ask users
BETA
开始

小部件集成指南

将在线调查和反馈小部件集成到您的网站的完整说明。

小部件文档

小部件配置

了解显示模式、定位、大小、动画和行为设置

了解更多

显示规则

使用定向规则和行为触发器控制向谁以及何时显示小部件

了解更多

小部件触发器

配置按钮、图标和基于条件的触发器以及频率控制

了解更多

小部件样式

自定义图标、按钮、颜色并创建美丽的小部件设计

了解更多

Security and CSP

Configure Content Security Policy headers for widget integration

了解更多

Web Components

使用 Shadow DOM 在第三方网站嵌入时实现完全的 CSS 隔离

了解更多

docs.widgets.cards.reactLibrary.title

docs.widgets.cards.reactLibrary.description

了解更多
1

创建您的帐户

注册 Ask Users 并选择适合您需求的计划。您将获得一个 API 密钥，用于验证您的小部件。

立即注册

向您的网站添加脚本

将这些脚本标签添加到 HTML 的 <head> 部分。将 YOUR_API_KEY 替换为您从仪表板获得的实际 API 密钥。

<!-- Add these to your <head> section -->
<script src="https://askusers.org/widget/widget-common.js"></script>

<!-- For survey widgets -->
<script src="https://askusers.org/widget/survey-widget.js?api-key=YOUR_API_KEY"></script>

<!-- For form widgets (waitlist, feedback, contact forms, feature requests, etc.) -->
<script src="https://askusers.org/widget/form-widget.js?api-key=YOUR_API_KEY"></script>

注意： 仅包含您计划使用的小部件类型的脚本。

添加小部件 HTML

将小部件 HTML 放置在您希望小部件出现在页面上的位置。

在线调查小部件

<div class="askusers-survey-widget"
     data-survey-id="YOUR_SURVEY_ID"
     data-context-id="product-feedback"
     data-context-type="survey">
</div>

表单小部件（候补名单、联系、反馈）

<div class="askusers-form-widget"
     data-form-id="YOUR_FORM_ID"
     data-context-id="product-launch"
     data-context-type="product">
</div>

在仪表板中创建您的表单，并使用模板如"候补名单/电子邮件注册"、"快速反馈（竖起大拇指）"、"联系表单"或"功能请求"。将 YOUR_FORM_ID 替换为您的表单 ID。

测试您的集成

添加脚本和 HTML 后，测试您的小部件以确保它们正常工作：

  • 检查小部件是否正确加载和显示
  • 测试表单提交（它们将出现在您的仪表板中）
  • 验证样式是否与您的网站设计匹配
  • 在不同设备和屏幕尺寸上测试

高级配置

自定义样式

使用 CSS 自定义属性自定义小部件外观。将它们添加到小部件元素的 style 属性中。

示例：自定义品牌颜色

<div class="askusers-form-widget"
     data-form-id="YOUR_FORM_ID"
     data-context-id="my-product"
     data-context-type="launch"
     style="
       --askusers-color-primary: #8b5cf6;
       --askusers-color-background: #ffffff;
       --askusers-color-text: #1f2937;
       --askusers-color-success: #10b981;
     ">
</div>

一页上的多个小部件

您可以通过为每个小部件提供唯一的 context-id 来在同一页面上使用多个小部件。

<!-- Survey widget -->
<div class="askusers-survey-widget"
     data-survey-id="YOUR_SURVEY_ID"
     data-context-id="product-feedback"
     data-context-type="survey">
</div>

<!-- Form widget for feedback -->
<div class="askusers-form-widget"
     data-form-id="YOUR_FEEDBACK_FORM_ID"
     data-context-id="article-123"
     data-context-type="article">
</div>

<!-- Form widget for feature requests -->
<div class="askusers-form-widget"
     data-form-id="YOUR_FEATURE_REQUEST_FORM_ID"
     data-context-id="product-roadmap"
     data-context-type="roadmap">
</div>

框架集成

对于单页应用程序（React、Vue、Angular 等），当组件挂载或路由更改时，您需要手动初始化小部件，因为自动初始化仅在页面加载时发生。

React

function MyComponent() {
  useEffect(() => {
    // Manual initialization required for SPAs
    if (window.AskUsersWidget) {
      // Initialize survey widgets
      window.AskUsersWidget.initializeSurveyWidgets?.();
      // Initialize form widgets (handles all form types)
      window.AskUsersWidget.initializeFormWidgets?.();
    }
  }, []);

  return (
    <div
      className="askusers-form-widget"
      data-form-id="YOUR_FORM_ID"
      data-context-id="my-component"
      data-context-type="feedback"
    />
  );
}

Vue.js

<template>
  <div
    class="askusers-form-widget"
    data-form-id="YOUR_FORM_ID"
    data-context-id="my-component"
    data-context-type="feedback"
  />
</template>

<script>
export default {
  mounted() {
    // Manual initialization required for SPAs
    if (window.AskUsersWidget) {
      window.AskUsersWidget.initializeSurveyWidgets?.();
      window.AskUsersWidget.initializeFormWidgets?.();
    }
  }
}
</script>

Angular

@Component({
  selector: 'app-my-component',
  template: `
    <div
      class="askusers-form-widget"
      data-form-id="YOUR_FORM_ID"
      data-context-id="my-component"
      data-context-type="feedback">
    </div>
  `
})
export class MyComponent implements OnInit {
  ngOnInit() {
    // Manual initialization required for SPAs
    if ((window as any).AskUsersWidget) {
      (window as any).AskUsersWidget.initializeSurveyWidgets?.();
      (window as any).AskUsersWidget.initializeFormWidgets?.();
    }
  }
}

Svelte

<script>
  import { onMount } from 'svelte';

  onMount(() => {
    // Manual initialization required for SPAs
    if (window.AskUsersWidget) {
      window.AskUsersWidget.initializeSurveyWidgets?.();
      window.AskUsersWidget.initializeFormWidgets?.();
    }
  });
</script>

<div
  class="askusers-form-widget"
  data-form-id="YOUR_FORM_ID"
  data-context-id="my-component"
  data-context-type="feedback"
/>

重要： 每次渲染小部件组件时调用适当的 init 方法。小部件优雅地处理多次初始化，只会初始化尚未处理的新小部件。

Web Components（Shadow DOM）

在第三方网站嵌入小部件时要实现完全的 CSS 隔离，请使用我们的 Web Component 自定义元素。它们使用 Shadow DOM 来防止宿主网站样式影响小部件外观。

何时使用 Web Components

在以下情况使用 Web Components：

  • 在您无法控制 CSS 的第三方网站上嵌入
  • 宿主网站的全局样式与小部件冲突
  • 您需要在不同网站上保证视觉一致性

在以下情况使用标准 div 嵌入：

  • 在您可以控制样式的自己网站上嵌入
  • 您希望小部件继承一些宿主网站样式
  • 您更喜欢 data-* 属性语法

Web Component 用法

Web Components 使用简洁的 HTML 属性而不是 data-* 属性：

表单小部件

<askusers-form
  form-id="YOUR_FORM_ID"
  display-mode="inline"
  prefill-email="user@example.com"
  prefill-name="John Doe"
></askusers-form>

调查小部件

<askusers-survey
  survey-id="YOUR_SURVEY_ID"
  display-mode="popup"
  trigger-style="icon"
  position="bottom-right"
></askusers-survey>

属性映射

Web Component 属性等效的 data-* 属性
form-iddata-form-id
survey-iddata-survey-id
display-modedata-display-mode
prefill-emaildata-prefill-email
trigger-styledata-trigger-style

TypeScript 支持

如果您使用 TypeScript 与 React/JSX 并遇到类型错误，如：

Property 'askusers-form' does not exist on type 'JSX.IntrinsicElements'

下载我们的类型声明文件并添加到您的项目中：

// Download from: https://askusers.org/widget/askusers-widget.d.ts
// Then add to your project:
/// <reference path="path/to/askusers-widget.d.ts" />

类型声明包含 askusers-form 和 askusers-survey 自定义元素的所有支持属性。

在预览中启用 Web Components

  1. 进入表单/调查预览页面
  2. 滚动到小部件显示配置
  3. 找到嵌入选项部分
  4. 勾选使用 Web Component 进行 CSS 隔离
  5. 生成的嵌入代码将使用 Web Component 语法

需要帮助吗？

如果您在设置过程中遇到任何问题，我们随时为您提供帮助。查看我们的文档或联系支持。

查看示例联系支持