@opengovsg /糖果

可嵌入的React调查小部件，用于收集用户反馈。

安装

# npm
npm install @opengovsg/confetti

# yarn
yarn add @opengovsg/confetti

# pnpm
pnpm add @opengovsg/confetti

同行依赖性

此包需要React 18.2.0+或React 19：

npm install react@^18.2.0

快速入门

1. 将小部件添加到您的页面：

import { PopoverConfetti } from '@opengovsg/confetti'

function App() {
  return (
    <div style={{ position: 'fixed', bottom: '1rem', right: '1rem' }}>
      <PopoverConfetti
        surveyId="your-survey-id"
        publishableKey="your-publishable-key"
        metadata={{}}
      />
    </div>
  )
}

模板组件加载脚本包和样式表 运行时的CDN，这是 没有CSS要导入 -包括 主机渲染触发器按钮，其中 TriggerPopoverConfetti 风格本身。( 较低级别的 @opengovsg/confetti/components 原语和 这个 @opengovsg/confetti/static 选择退出表面渲染在你自己的bundle和 仍然需要 import '@opengovsg/confetti/confetti.css'.）

注意： 您将需要调查ID和可发布密钥从您的五彩纸屑仪表板。确保在团队设置中将您的域列入白名单。

分析元数据

默认情况下，禁用Analytics元数据收集。集 autoInjectAnalyticsMetadata 来 true 公开的标识符 在主机页面上发布每个响应的thog和Datadog RUM：

<PopoverConfetti
  surveyId="your-survey-id"
  publishableKey="your-publishable-key"
  autoInjectAnalyticsMetadata
/>

小部件从中读取这些sdk window.posthog 和 window.DD_RUM，而它 从不捆绑任何一个SDK。 @datadog/browser-rum 分配 window.DD_RUM 用于 一旦导入，您就可以使用它，所以Datadog不需要额外的设置。

postthog是不同的——你必须自己曝光。 它 文档 这是大多数现代应用程序所不具备的 window.posthog，所以把它分配到你的任何地方 预置PostHog:

import posthog from 'posthog-js'

posthog.init('<your-project-token>', { api_host: '<your-api-host>' })

window.posthog = posthog

缺少SDK的任何标识符都将被跳过，因此仍然是部分设置 提交其余部分。这些键在可用时收集：

传递的显式值 metadata 总是优先于 自动收集值。

使用Datadog会话ID在Datadog会话浏览器中查找会话 与 @session.id:<datadog_rum_session_id>.

2. 在CSP标题中添加五彩纸屑。小部件从CDN加载它的脚本和样式表并调用API，所以allowlist全部三个：

script-src https://confetti.gov.sg;
style-src https://confetti.gov.sg;
connect-src https://confetti.gov.sg;

代理请求

每个模板组件都接受一个可选的 proxyUrl。设置后，小部件 将其API请求发送到 {proxyUrl}/api/v1/cfti/... 而不是 https://confetti.gov.sg，而cdn支持的shell也会加载它们的脚本 和样式表 {proxyUrl}/widget/v1/...。使用这个来路由小部件 通过您自己的来源的流量，例如当您的CSP拒绝第三方 方主机。

contfetti Cloud团队可以从 团队设置. 创建此处显示的仅限dns的CNAME，并等待它变为活动状态，然后通过 生成的URL。如果主机名在Cloudflare DNS中，禁用橙色 云所以 代理地位 是 DNS只 -参见 托管代理指南.

<PopoverConfetti
  proxyUrl="https://c.example.gov.sg"
  surveyId="..."
  publishableKey="cfti_pk_..."
/>

当使用托管代理时，请为所示的所有三个CSP指令使用该源 上面而不是 https://confetti.gov.sg.

模板组件

选择最适合您用例的组件：

语言环境

需要 @opengovsg/confetti 0.8.2 或更高版本。旧版本保留 英语调查-他们不会失败加载。

通过 locale 显示翻译后的调查。作者翻译在纸屑 英语永远是来源，汉语、马来语和泰米尔语也是 可选)。未翻译的字段返回到英语。

小部件本身并不读取浏览器语言。使用 useResolveLocale 来映射BCP-47标记（或浏览器的语言） 偏好) 'en' | 'zh' | 'ms' | 'ta'：

import { PopoverConfetti, useResolveLocale } from '@opengovsg/confetti'

function Feedback() {
  const locale = useResolveLocale()

  return (
    <PopoverConfetti
      surveyId="your-survey-id"
      publishableKey="your-publishable-key"
      locale={locale}
    />
  )
}

通过 preferred 当宿主应用程序已经知道区域设置时(例如 next-intl)。通过 explicit 即使失败了，也能赢得胜利 匹配一个conffetti区域设置—包括一个空字符串，它返回到 用英语代替 preferred：

const locale = useResolveLocale({
  preferred: i18n.locale,
  explicit: searchParams.get('locale'),
})

要始终显示一种语言，通过 locale 直接跳过钩子：

<PopoverConfetti
  surveyId="your-survey-id"
  publishableKey="your-publishable-key"
  locale="zh"
/>

插件chrome你没有自定义-跳过，下一步，提交，返回，关闭，其他， 占位符和验证错误-仍然针对给定的语言环境进行本地化。 省略 locale，或通过 'en'，以保持英语调查。

同样的道具在 静态 组件和 在 积木 原语。进口 useResolveLocale 从 @opengovsg/confetti 在这些设置中也是如此。看到 翻译指南.

静态组件

这个 @opengovsg/confetti/static 子路径船的独立构建 相同的模板组件(EmbeddedConfetti， ModalConfetti， PopoverConfetti， StepperConfetti)加上 ConfettiTrigger 作文 帮手。它们完全从你自己的包中呈现，没有运行时CDN 依赖，因此调查呈现更新仅在升级时到达您的站点 包。

import '@opengovsg/confetti/confetti.css'

import { PopoverConfetti } from '@opengovsg/confetti/static'

与支持cdn的shell不同，静态组件需要样式表 如上所示的导入。

能见度钩子

控制你的调查何时出现与这些挂钩：

useVisibleAfterDelay

延迟后显示调查结果：

import { useVisibleAfterDelay } from '@opengovsg/confetti'

const { isVisible } = useVisibleAfterDelay({ delay: 5000 }) // 5 seconds

useVisibleAfterScroll

滚动一定距离后显示调查结果：

import { useVisibleAfterScroll } from '@opengovsg/confetti'

const { isVisible } = useVisibleAfterScroll({ threshold: 500 }) // 500px

useVisibleAfterPageVisits

一旦访问者加载了给定次数的当前页面（跨会话持续），就显示调查 localStorage):

import { useVisibleAfterPageVisits } from '@opengovsg/confetti'

const { isVisible, reset } = useVisibleAfterPageVisits({
  visits: 3,
  respondent: 'optional-respondent-identifier',
})

useVisibleAfterSessionPageVisits

如上所述，但访问计数的范围是通过当前浏览器会话 sessionStorage：

import { useVisibleAfterSessionPageVisits } from '@opengovsg/confetti'

const { isVisible, reset } = useVisibleAfterSessionPageVisits({ visits: 3 })

useRespondentState

在没有模板的情况下，阅读应答者的回复和解雇时间。 respondent （此钩子不会生成匿名id）。

import { useRespondentState } from '@opengovsg/confetti'

const respondentState = useRespondentState({
  surveyId: '<your-survey-id>',
  publishableKey: '<your-publishable-key>',
  respondent: '<user-id>',
})

构建块

的底层原语 模板组件 都是从 @opengovsg/confetti/components 子路径。利用这些来组成你自己的调查UI。

import {
  ConfettiController,
  ConfettiProvider,
  SurveyContext,
  useSurvey,
} from '@opengovsg/confetti/components'

与模板组件不同，这些原语在您自己的包中呈现 在你的应用入口点导入一次样式表：

import '@opengovsg/confetti/confetti.css'