npm package: @hashcoop/referral-popup
Description: Loloyal Referral Popup
Author: Loloyal Team
Latest version: 1.1.6

# Loloyal Popup SDK

![版本](https://img.shields.io/badge/版本-1.0.28-alpha.19-blue)
![许可证](https://img.shields.io/badge/许可证-MIT-green)

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

## ✨ 特性

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

## 🚀 快速开始

### 安装

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

### 支持的弹窗类型

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

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

### 在 JavaScript 项目中使用

```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`: 弹窗配置对象<br>`rootEl?`: 可选，指定弹窗挂载的 DOM 元素 | void   |
| `setFirstStepContent(content)`  | 设置第一步内容 | `content`: 包含内容、占位符和按钮文本的对象                        | void   |
| `setSecondStepContent(content)` | 设置第二步内容 | `content`: 包含内容和按钮文本的对象                                | void   |
| `showCouponCode(couponCode)`    | 直接显示优惠码 | `couponCode`: 优惠码字符串                                         | void   |
| `resetState()`                  | 重置弹窗状态   | 无                                                                 | void   |

### 会员弹窗 (Member) 特有方法

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

### 订阅弹窗 (Subscription) 特有方法

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

## 开发

### 启动

首先, 按照 [monorepo 的开发环境配置](../../README.md#开发) 配置好本地开发环境

```bash
cd packages/referral-popup

# 安装依赖
pnpm install

# 启动开发服务器
pnpm dev

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

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

### 构建

```bash
# 构建生产版本
pnpm build

# 监听模式构建
pnpm build:watch

# 预览构建结果
pnpm preview
```

### 测试

```bash
# 运行测试
pnpm test
```

### 发布

```bash
# 更新版本号
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