@gravity-ui/登上飞机

基于登入方案创建提示, 并管理您服务的促销活动 . 与React、任何其他框架或香草JS一起使用.
- 小型. 登机~4Kb,宣传-管理~8kb. 零依赖关系
- 测试的很好. ~80%的测试覆盖率
- 小代码脚印。创建登入情景配置,并用几行代码连接每个步骤.
- 没有UI。使用自己的组件
- 良好的类型脚本支持
目录
安装
npm i @gravity-ui/onboarding
软件包内容
此包包含两个工具 :
-
入职 - 基于入职为服务用户创建提示的工具. 创建带有步骤的预设,绑定元素和调用方法. 登入会保持用户的进步并计算下一条提示以显示.
-
Promo管理器 - 管理您向用户推入的任何促销活动的工具:横幅,告密者,新功能的广告,UX调查,教育弹出. 将所有 promos 配置并指定条件 。 Promo管理器会保持用户进度并计算出下一个显示的Promo.
登入指南
你可以试试看 游乐场
如何使用登机
基本反应示例
// onboarding/lib.ts
import {createOnboarding, createPreset} from '@gravity-ui/onboarding';
export const {
useOnboardingStep,
useOnboardingPreset,
useOnboardingHint,
useOnboarding,
controller,
} = createOnboarding({
config: {
presets: {
// createPreset - wrapper for better type inference
todoListFirstUsage: createPreset({
name: '',
steps: [
createStep({
slug: 'createTodoList',
name: 'create-todo-list',
description: 'Click button to create todo list',
}),
/* other scanario steps */
],
}),
},
},
// onboarding state from backend
baseState: () => {/* ... */},
getProgressState: () => {/* ... */},
// save new onboarding state to backend
onSave: {
state: (state) => {/* ... */},
progress: (progress) => {/* ... */},
},
});
// Hint.tsx
import { useCallback } from 'react';
import { Popup } from '@gravity-ui/uikit';
import { useOnboardingHint } from './lib.ts';
export const OnboardingHint = () => {
const { anchorRef, hint, open, onClose } = useOnboardingHint();
const handleClose = useCallback(() => {
onClose();
}, [onClose]);
return (
<>
<Popup
anchorElement={anchorRef.current}
open={open}
onOpenChange={handleClose}
>
<h3>{hint?.step.name}</h3>
{hint?.step.description}
</Popup>
</>
);
};
// todo-list.tsx
import { useOnboardingStep } from './onboarding/lib';
export const SomeFeature = () => {
const { pass, ref } = useOnboardingStep('createTodoList');
return (
<Button
onClick={() => {
pass();
handleAddTodoList();
}}
ref={ref}
// ...
>
"Add new list"
</Button>
);
};
如果无法访问目标元素,则可以使用 useOnboardingStepBySelector
// todo-list.tsx
import {useOnboardingStepBySelector} from '../todo-list-onboarding.ts';
const ref = useRef()
useOnboardingStepBySelector({
element: ref.current,
selector: '.deep_nested_element',
step: 'createFirstIssue'
});
return (
<Button
onClick={() => {
pass();
handleAddTodoList();
}}
ref={ref}
// ...
>
"Add new list"
</Button>
);
登入配置
登入选项
您可以配置登入
const onboardingOptions = {
config: {
presets: {/**/},
},
globalSwitch: 'off', // optional. turn off onboarding globally. For example in some entire env
ignoreUnknownPresets: true, // optional. will not thorow error for unknown presets
baseState: {/**/}, // initial state for current user
getProgressState: () => {/**/}, // function to load user progress
customDefaultState: {/**/}, // optional. will apply this value for user with no base state
onSave: {
// functions to save user state
state: (state) => {/**/},
progress: (progress) => {/**/},
},
showHint: (state) => {}, // optional. function to show hint. Only for vanilla js usage
logger: { // optional. you can specify custom logger
level: 'error' as const,
logger: {
debug: () => {/**/},
error: () => {/**/},
},
},
debugMode: true, // optional. true will show a lot of debug messages. Recommended for dev environment
plugins: [/**/], // optional. you can use existing plugins or write your own
// optional. you can subscribe to onboarding events
hooks: {
showHint: ({preset, step}) => {/**/},
stepPass: ({preset, step}) => {/**/},
addPreset: ({preset}) => {/**/},
beforeRunPreset: ({preset}) => {/**/},
runPreset: ({preset}) => {/**/},
finishPreset: ({preset}) => {/**/},
beforeSuggestPreset: ({preset}) => {/**/},
beforeShowHint: ({stepData}) => {/**/},
stateChange: ({state}) => {/**/},
hintDataChanged: ({state}) => {/**/},
closeHint: ({hint, eventSource}) => {/**/},
closeHintByUser: ({hint, eventSource}) => {/**/},
init: () => {/**/},
wizardStateChanged: ({wizardState}) => {/**/},
applyDefaultState: ({wizardState}) => {/**/},
},
};
常见的预设配置
对于默认的预设,您可以指定属性 :
const onboardingOptions = {
config: {
presets: {
// you can use goPrevStep and goNextStep in steps
createProject: createPreset(({goPrevStep, goNextStep}) => ({
// preset name should be unique
name: 'Creating project', // text for user
type: 'default', // optional. 'default'(default value) | 'interlal' | 'combined'
visibility: 'visible', // optional. 'visible'(defaule value) | 'initialHidden' | 'alwaysHidden';
description: '', // optional, text for user
steps: [
{
slug: 'openBoard', // step slug must be unique across all presets
name: '', // text to show in popup
description: '', // text to show in popup
placement: 'top', // optional. Hint placement for step
passMode: 'onAction', // optional. 'onAction'(default value) | 'onShowHint' - trigger step pass on hint show
hintParams: {
// you can use theese actions in Hint component to display buttons
actions: [
{
children: 'Go back',
view: 'action' as const,
onClick: () => {
goNextStep()
},
},
{
children: 'Go next',
view: 'action' as const,
onClick: () => {
goNextStep()
},
},
],
}, // optional. any custom properties for hint
closeOnElementUnmount: false, // optional. default valeue - false. Will close hint when element umnounts. 'True' not reccomended in general^ but may me helpful for some corners
passRestriction: 'afterPrevious', // optional. afterPrevious will block pass step is previous not passed
hooks: {
// optional
onStepPass: () => {/**/},
onCloseHint: () => {/**/},
onCloseHintByUser: () => {/**/},
},
},
],
hooks: {
// optional
onBeforeStart: () => {/**/},
onStart: () => {/**/},
onEnd: () => {/**/},
},
})),
},
},
};
合并预设
对于合并预设,您需要在配置中添加内部预设并指定 pickPreset 函数.
import {createInternalPreset, createCombinedPreset, createOnboarding} from '@gravity-ui/onboarding';
createOnboarding({
config: {
presets: {
// you need to add internal presets. Here it is internal1 and internal2
internal1: createInternalPreset({
name: 'Internal2',
type: 'internal' as const,
steps: [/* ... */]
}),
internal2: createInternalPreset({
name: 'Internal2',
type: 'internal' as const,
steps: [/* ... */],
}),
// combined preset has no steps
combined: createCombinedPreset({
name: 'combined',
type: 'combined' as const,
// pickPreset calls on preset start and resolve combined preset to specific internal preset
pickPreset: () => {
if(someCondition) {
return 'internal1'
}
return 'internal2'
},
internalPresets: ['internal1', 'internal2'],
}),
},
},
});
您可以在 测试数据
Async 预设
对于大型登入,在用户实际达到一步之前,可能不需要将文本和i18n捆绑入预设. 您可以使用 config.asyncPresets数字 :
// heavy-presets.ts — lives in its own chunk, pulls i18n with it
import {createAsyncPresets, createPreset} from '@gravity-ui/onboarding';
import {i18n} from './i18n';
export default createAsyncPresets({
createProject: createPreset({
name: i18n('createProject.name'),
steps: [/* ... */],
}),
viewReports: createPreset({
name: i18n('viewReports.name'),
steps: [/* ... */],
}),
});
将同步地图包入 createAsyncPresets ——此身份帮助保留了字面地图类型如此 Presets 财务报告和审定财务报表 Steps 工会的推定是正确的 createOnboarding 电话站.
// lib.ts
import {createOnboarding, createPreset} from '@gravity-ui/onboarding';
createOnboarding({
config: {
presets: {
// sync presets stay inlined
quickTour: createPreset({ /* ... */ }),
},
// single loader — one import = one code-split chunk = one request
asyncPresets: () => import('./heavy-presets').then((m) => m.default),
},
// ...rest unchanged
});
语义:
- 装入器被引用 最多一次 每个控制器生命周期,第一次使用任何预设的身体-触摸方法(
runPreset, (中文(简体) ),addPreset, (中文(简体) ),suggestPresetOnce, (中文(简体) ),passStep, (中文(简体) ),stepElementReached, (中文(简体) ),finishPreset, (中文(简体) ),resetPresetProgress,向导打开,读取userPresets) (中文(简体) ). 被禁用的控制器从不触发加载器. - 虽然装载机在飞行中,但同时通话也有同样的承诺——没有重复请求.
- 如果加载器拒绝,则错误会被记录并泡出至呼叫器,拒绝被缓存——随后的调用会浮出相同的错误而无需再取加载器. 要在持续失败后重试(例如用户点击"再试"),重新创建控制器.
- 仍然静态地推断出Aync地图上的淤泥——
useOnboardingStep('slugFromAsyncPreset')保持类型安全. - 如果一个同步密钥与同步密钥相撞,同步预设获胜并被记录出错.
- 结构分解的消费者
controller.options.config.presets在模块级别上,只看到同步子集,直到加载器解决。 通过控制器方法或userPresets获取( 重生成)stateChange而不是决心.
活动
您可以使用事件系统 。 可用事件 : showHint, (中文(简体) ), stepPass, (中文(简体) ), addPreset, (中文(简体) ), beforeRunPreset, (中文(简体) ), runPreset, (中文(简体) ), finishPreset, (中文(简体) ), beforeSuggestPreset, (中文(简体) ), stepElementReached, (中文(简体) ), beforeShowHint, (中文(简体) ), stateChange, (中文(简体) ), hintDataChanged, (中文(简体) ), closeHint, (中文(简体) ), init, (中文(简体) ), wizardStateChange
controller.events.subscribe('beforeShowHint', callback);
召回可作同声. 有些事件可以取消目标动作 : stepElementReached, (中文(简体) ), beforeShowHint, (中文(简体) ), beforeSuggestPreset
controller.events.subscribe('stepElementReached', async () => {
/* ... */
if(someCondition) {
// forbid show hint
return false
}
});
登入插件
您可以使用插件
- 多标签同步插件 - 同步关闭提示和状态(试验在标签之间). 如果用户在多个分页中打开页面,则无需多次黑入一个提示. 状态同步还同步完成/未完成的情景状态和向导,但 可能导致内存漏出。默认已禁用,可自行冒险启用
- 向导缓冲 - 如果你有一个向导, 用户可以看见他的情景并启动它们, 则有用 。 插件
- 如果打开向导, 在启动时加载进度
- 如果显示向导元素可见时显示提示
- 关闭向导时关闭提示
- 启动预设时关闭提示并删除未完成预设的进度
- 预设完成时扩展向导
- 推进预设插件 - 在预设周围添加逻辑
visibility: 'alwaysHidden'。这些预设被认为是促发预设,并附加附加逻辑.- 打开向导时不显示宣传预设提示
- 隐藏向导时不显示正则预设提示
- 如果需要显示提示, 则在用户状态下切换启用状态( 可选)
- (可选)在发布(建议PresetOce)预设时切换启用的用户状态
示例
import {createOnboarding} from '@gravity-ui/onboarding';
import {
MultiTabSyncPlugin,
PromoPresetsPlugin,
WizardPlugin,
} from '@gravity-ui/onboarding/dist/plugins';
const {controller} = createOnboarding({
/* ... */
plugins: [
new MultiTabSyncPlugin({
enableStateSync: false, // Experimantal. Default - false(recommended). Sync all onboarding state.
enableCloseHintSync: true, // closes hont in all browser tabs,
changeStateLSKey: 'onboarding.plugin-sync.changeState', // localStorage key for state sync
closeHintLSKey: 'onboarding.plugin-sync.closeHint', // localStorage key for close hint in all tabs
}),
new PromoPresetsPlugin({
turnOnWhenShowHint: true, // Default - true. Force to turn on onboarding, when promo hint should be shown
turnOnWhenSuggestPromoPreset: true, // Default - true. Force to turn on onboarding, when promo preset suggested
}),
new WizardPlugin(),
],
});
你可以自己写插件
import {createOnboarding} from '@gravity-ui/onboarding';
import {WizardPlugin} from '@gravity-ui/onboarding/dist/plugins';
const myPlugin = {
apply: (onboarding) => {
/**
* Do something with onboarding controller
* For exampe subscribe on event
* onboarding.events.subscribe('init', () => {});
*/
},
};
const {controller} = createOnboarding({
/**/
plugins: [new WizardPlugin(), myPlugin],
});
宣传管理器
如何使用宣传管理器
1. 启动促销管理器并安排进度更新
// promo-manager.ts
import { createPromoManager } from '@gravity-ui/onboarding/dist/promo-manager';
import { ShowOnceForPeriod } from '@gravity-ui/onboarding/dist/promo-manager/helpers';
export const { controller, usePromoManager, useActivePromo } = createPromoManager({
config: {
promoGroups: [{
slug: 'poll',
conditions: [ShowOnceForPeriod({month: 1})],
promos: [
{
slug: 'issuePoll',
conditions: [ShowOncePerMonths(6)],
meta: {...}
},
],
}],
},
progressState: () => {/* ... */},
getProgressState: () => {/* ... */},
onSave: {
progress: (state) => () => {/* ... */},
},
});
2. 在您组件中的触发促进
// TriggerExample.tsx
import { usePromoManager } from './promo-manager';
const { status, requestStart, skipPromo } = usePromoManager('issuePoll');
useMount(() => {
requestStart();
});
useUnmount(() => {
skipPromo();
});
if(status === 'active') {
// allowed to run. Do something
}
条件和制约因素
您可以为每个促销项目使用条件。 或利用约束来设定相隔相间的限制.
只有
- 所有宣传条件都回归真实
- 所有 promo 组条件返回为真
- 所有限制都通过
import {
ShowOnceForSession,
ShowOnceForPeriod,
MatchUrl,
LimitFrequency
} from '@gravity-ui/onboarding/dist/promo-manager/helpers';
const groupOfPolls = {
slug: 'groupOfPolls',
promos: [
{slug: 'somePoll', conditions: [ShowOnceForPeriod({month: 1})]},
{slug: 'pollForPageWithparam', conditions: [
MatchUrl('param=value'),
ShowOnceForPeriod({month: 5})
]}
],
}
const groupOfHints = {
slug: 'groupOfHints',
conditions: [ShowOnceForSession()],
promos: [
{slug: 'someHint'},
{slug: 'hintForSpecificPage', conditions: [
MatchUrl('/folder/\\w{5}/page$'),
]},
],
}
const {controller} = createPromoManager({
config: {
constraints: [
LimitFrequency({
slugs: ['somePoll', 'groupOfHints'], // can use promos slugs and group slugs
interval: {days: 1},
})
],
promoGroups: [groupOfHints, groupOfPolls]
},
});
你可以写你自己的条件.
const user = {/**/} // get user from state
const usersWithLanguage = (language) => user.language = language;
const promo = {slug: 'somePoll', conditions: [usersWithLanguage('english')]};
宣传管理器事件
Promo管理器可以对事件进行推介.
const promo = {
slug: 'promo1',
conditions: [],
trigger: {on: 'someCustomEvent', timeout: 1000}
}
const {controller} = createPromoManager({
config: {
promoGroups: [{
slug: 'group',
conditions: [],
promos: [promo],
}]
},
});
controller.sendEvent('someCustomEvent')
您还可以使用 UrlEventPlugin 运行 promos 在特定的url。 当用户打开页面时, Promo 会运行 .
const {controller} = createPromoManager({
config: {
promoGroups: [
{
slug: '1',
promos: [
{
slug: 'promo1',
conditions: [MatchUrl('/folder/\\w{5}/page$'),],
trigger: {on: 'pageOpened', timeout: 2000},
},
],
},
],
},
plugins: [new UrlEventsPlugin({eventName: 'pageOpened'})],
})
JSON 配置
您可以定义条件,限制为JSON可序列对象. 这样你就可以从json中取出配置,分析并使用. 它可以用于编辑配置而不重建工程和发布.
const usersWithLanguage = (language) => user.language = language;
const {controller} = createPromoManager({
config: { // config section now can be parsed from json
constraints: [
{
helper: 'LimitFrequency',
args: [{
slugs: ['somePoll', 'groupOfHints'], // can use promos slugs and group slugs
interval: {days: 1},
}],
},
],
promoGroups: [{
slug: 'groupOfPolls',
promos: [
{
slug: 'somePoll',
conditions: [{
helper: 'ShowOnceForPeriod',
args: [{month: 1}]
}]
},
{
slug: 'pollForPageWithparam',
conditions: [
{
helper: 'MatchUrl',
args: ['param=value']
},
{
helper: 'usersWithLanguage',
args: ['English']
},
]
}
],
}]
},
conditionHelpers: {
usersWithLanguage,
},
});
入职一体化
您可以使用登入 PromoPresetsPlugin 显示广告和教育提示。 您可以使用promo管理器限制频率,并与其他在役的promo设置约束.
import {
createOnboarding
} from "./index";
const {controller: onboardingController} = createOnboarding({
config: {
presets: {
coolNewFeature: {
name: 'Cool feature',
visibility: 'alwaysHidden',
steps: [/**/]
},
coolNewFeature2: {
name: 'Cool feature2',
visibility: 'alwaysHidden',
steps: [/**/],
}
}
},
plugins: [new PromoPresetsPlugin(),]
/**/
})
const {controller} = createPromoManager({
...testOptions,
config: {
promoGroups: [
{
slug: 'hintPromos',
conditions: [ShowOnceForSession()], // only 1 promo hint for session
promos: [
{
slug: 'coolNewFeature', // slug = onboarding preset name
conditions: [/**/], // you can add additional conditions
},
],
},
],
},
onboarding: {
getInstance: () => onboardingController,
groupSlug: 'hintPromos',
},
});