Loloyal Popup SDK

Loloyal Popup SDK 是一个轻量级、高度可定制的弹窗组件库，支持多种弹窗类型，专为电商和会员系统设计。通过简单的 API，快速为您的网站添加精美的弹窗功能。

✨ 特性

• 🎨 高度可定制 - 自定义外观、布局和内容
• 📱 响应式设计 - 完美适配移动端和桌面端
• 🔌 易于集成 - 支持多种集成方式，适合各类网站和应用
• 🔄 状态管理 - 内置 Jotai 状态管理，处理各种交互场景
• 🛡️ 类型安全 - 使用 TypeScript 开发，提供类型定义
• 🧩 多种弹窗类型 - 支持推荐好友、会员注册和订阅等多种业务场景

🚀 快速开始

安装

npm install @hashcoop/referral-popup
# 或
yarn add @hashcoop/referral-popup

支持的弹窗类型

SDK 目前支持以下三种弹窗类型：

1. referral - 推荐好友弹窗，适用于邀请好友注册、领取优惠码等场景
2. member - 会员弹窗，适用于会员注册、权益展示等场景
3. subscription - 订阅弹窗，适用于邮件订阅、newsletter 等场景

在 JavaScript 项目中使用

// 引入 SDK
import createPopupSDK, {
  PopupType,
  ReferralConfig,
  MemberConfig,
  SubscriptionConfig
} from '@hashcoop/referral-popup';

// -------- 创建推荐好友弹窗 --------
const referralPopup = createPopupSDK(PopupType.REFERRAL);
referralPopup.init({
  button_color: '#4a90e2',
  button_text_color: '#FFFFFF',
  background_layout: 'left',
  banner_url: 'https://example.com/banner.jpg',
  shape: 16,
  custom_css: '',
  first_step: {
    content: '邀请好友，双方都可获得优惠',
    placeholder: '请输入您的邮箱',
    button_text: '获取优惠码'
  },
  second_step: {
    content: '您已获得10元优惠券',
    button_text: '立即使用'
  }
});

// 自定义推荐好友弹窗样式
referralPopup.setStyles({
  button_color: '#f85555',
  background_layout: 'right',
  shape: 25
});

// 自定义推荐好友弹窗内容
referralPopup.setFirstStepContent({
  content: '邀请好友，双方都可获得优惠',
  placeholder: '请输入您的邮箱',
  button_text: '获取优惠码'
});
SDK.setSecondStepContent({
  content: '推荐成功！您已获得 $20 奖励',
  button_text: '查看奖励'
});

// 显示推荐好友弹窗优惠码
referralPopup.showCouponCode('SAVE20');

// 重置弹窗状态
referralPopup.resetState();

// 设置移动端样式
referralPopup.setMobileStyle(true);

// -------- 创建会员弹窗 --------
const memberPopup = createPopupSDK(PopupType.MEMBER);
memberPopup.init({
  button_color: '#4a90e2',
  button_text_color: '#FFFFFF',
  background_layout: 'right',
  banner_url: 'https://example.com/banner.jpg',
  shape: 16,
  custom_css: '',
  content: '注册成为会员，享受专属优惠',
  button_text: '立即注册',
  setting: {
    shape: 16
  }
});

// 自定义会员弹窗样式
memberPopup.setStyles({
  button_color: '#28a745',
  button_text_color: '#ffffff',
  background_layout: 'left',
  shape: 20,
  custom_css: `
    .member-popup-content {
      background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
    }
    .member-popup-title {
      color: #fff;
      font-weight: bold;
    }
  `
});

// 自定义会员弹窗内容
memberPopup.setContent({
  content: '🎉 加入会员，立享专属权益！<br/>✓ 专属折扣<br/>✓ 积分奖励<br/>✓ 生日特权',
  button_text: '立即加入'
});

// 设置移动端样式
memberPopup.setMobileStyle(true);

// 销毁会员弹窗
memberPopup.destroy();

// -------- 创建订阅弹窗 --------
const subscriptionPopup = createPopupSDK(PopupType.SUBSCRIPTION);
subscriptionPopup.init({
  button_color: '#4a90e2',
  button_text_color: '#FFFFFF',
  background_layout: 'top',
  banner_url: 'https://example.com/banner.jpg',
  shape: 16,
  custom_css: '',
  first_step: {
    content: '订阅我们的通讯',
    placeholder: '请输入您的邮箱',
    button_text: '订阅',
    program_disabled: '订阅规则未开启',
    account_excluded: '该账号被排除'
  },
  second_step: {
    content: '感谢您的订阅',
    button_text: '确定'
  },
  setting: {
    shape: 16
  }
});

// 自定义订阅弹窗样式
subscriptionPopup.setStyles({
  button_color: '#ff6b35',
  button_text_color: '#ffffff',
  background_layout: 'right',
  shape: 12,
  custom_css: `
    .subscription-popup-content {
      background: linear-gradient(45deg, #ff9a9e 0%, #fecfef 50%, #fecfef 100%);
      border: 2px solid #ff6b35;
    }
    .subscription-popup-input {
      border-radius: 25px;
      padding: 12px 20px;
      border: 1px solid #ddd;
    }
  `
});

// 自定义订阅弹窗第一步内容
subscriptionPopup.setFirstStepContent({
  content: '📧 订阅我们的新闻通讯<br/>获取最新优惠信息和产品动态',
  placeholder: '输入您的邮箱地址',
  button_text: '立即订阅'
});

// 自定义订阅弹窗第二步内容
subscriptionPopup.setSecondStepContent({
  content: '🎉 订阅成功！<br/>感谢您的订阅，我们会定期为您推送精彩内容',
  button_text: '完成'
});

// 重置订阅弹窗状态
subscriptionPopup.resetState();

// 设置移动端样式
subscriptionPopup.setMobileStyle(true);

// 销毁订阅弹窗
subscriptionPopup.destroy();

📖 API 文档

通用 SDK 方法

以下方法适用于所有类型的弹窗：

| 方法 | 描述 | 参数 | 返回值 | | -------------------------- | ---------------------- | ---------------------- | ------ | | setStyles(styles) | 设置弹窗样式 | styles: 样式配置对象 | void | | setMobileStyle(isMobile) | 设置是否使用移动端样式 | isMobile: 布尔值 | void | | destroy() | 销毁弹窗 | 无 | void |

推荐好友弹窗 (Referral) 特有方法

| 方法 | 描述 | 参数 | 返回值 | | ------------------------------- | -------------- | ------------------------------------------------------------------ | ------ | | init(config, rootEl?) | 初始化弹窗 | config: 弹窗配置对象rootEl?: 可选，指定弹窗挂载的 DOM 元素 | void | | setFirstStepContent(content) | 设置第一步内容 | content: 包含内容、占位符和按钮文本的对象 | void | | setSecondStepContent(content) | 设置第二步内容 | content: 包含内容和按钮文本的对象 | void | | showCouponCode(couponCode) | 直接显示优惠码 | couponCode: 优惠码字符串 | void | | resetState() | 重置弹窗状态 | 无 | void |

会员弹窗 (Member) 特有方法

| 方法 | 描述 | 参数 | 返回值 | | ----------------------- | ---------- | ------------------------------------------------------------------ | ------ | | init(config, rootEl?) | 初始化弹窗 | config: 弹窗配置对象rootEl?: 可选，指定弹窗挂载的 DOM 元素 | void | | setContent(content) | 设置内容 | content: 包含内容和按钮文本的对象 | void |

订阅弹窗 (Subscription) 特有方法

| 方法 | 描述 | 参数 | 返回值 | | ------------------------------- | -------------- | ------------------------------------------------------------------ | ------ | | init(config, rootEl?) | 初始化弹窗 | config: 弹窗配置对象rootEl?: 可选，指定弹窗挂载的 DOM 元素 | void | | setFirstStepContent(content) | 设置第一步内容 | content: 包含内容、占位符和按钮文本的对象 | void | | setSecondStepContent(content) | 设置第二步内容 | content: 包含内容和按钮文本的对象 | void | | openSecondStep() | 开启第二步内容 | 无 | void | | resetState() | 重置弹窗状态 | 无 | void |

开发

启动

首先, 按照 monorepo 的开发环境配置 配置好本地开发环境

cd packages/referral-popup

# 安装依赖
pnpm install

# 启动开发服务器
pnpm dev

# 配置店铺和顾客信息
./playground/index.html

# 访问测试页面
# http://localhost:3200
# http://localhost:3200?loloyal_referral_code=code - 推荐弹窗

构建

# 构建生产版本
pnpm build

# 监听模式构建
pnpm build:watch

# 预览构建结果
pnpm preview

测试

# 运行测试
pnpm test

发布

# 更新版本号
pnpm version patch --no-git-tag-version

# 构建
pnpm build

# 发布到npm
pnpm publish

📁 项目结构

packages/referral-popup/
├── src/
│   ├── sdk.ts              # SDK 主入口
│   ├── App.tsx             # 主应用组件
│   ├── store/              # 状态管理 (Jotai)
│   ├── components/         # React 组件
│   │   ├── ReferralPopup/  # 推荐弹窗
│   │   ├── MemberPopup/    # 会员弹窗
│   │   ├── SubscriptionPopup/ # 订阅弹窗
│   │   └── CorePopup/      # 核心弹窗
│   ├── hooks/              # React Hooks
│   ├── utils/              # 工具函数
│   ├── types/              # TypeScript 类型定义
│   └── styles/             # 样式文件
├── playground/             # 开发测试页面
├── dist/                   # 构建输出
└── 配置文件

👥 贡献指南

我们欢迎任何形式的贡献！请在提交 PR 前先开一个 issue 讨论您的想法。

📄 许可证

MIT