WhatsApp 按钮集成示例

💡 概述

WhatsApp 按钮组件会自动从 KaloCash 后台获取最新的 WhatsApp 号码，并在页面上显示一个可点击的按钮。点击按钮后会自动打开 WhatsApp 应用或网页版。

🚀 快速开始

1 引入脚本

在您的 HTML 页面中，添加以下代码（推荐放在 <head> 标签中）：

<!-- 从 KaloCash 服务器加载 -->
<script src="https://web.kolacash.com/static/web/js/whatsapp-button.js"></script>
                

2 初始化按钮

在引入脚本后，添加初始化代码：

<script>
    // 等待页面加载完成后初始化
    document.addEventListener('DOMContentLoaded', function() {
        if (typeof WhatsAppButton !== 'undefined') {
            WhatsAppButton.init({
                // ⚠️ 重要：配置 API 服务器地址（必须）
                apiBaseUrl: 'https://your-kalocash-domain.com',
                
                // 可选配置
                buttonText: 'WhatsApp',  // 按钮文字
                buttonIcon: '💬',  // 按钮图标
                position: 'bottom-right',  // 位置：bottom-right, bottom-left, top-right, top-left
                debug: false  // 调试模式
            });
        }
    });
</script>
                

📝 完整集成示例

<!DOCTYPE html>
<html lang="zh-CN">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>我的网站</title>
    
    <!-- 引入 WhatsApp 按钮脚本 -->
    <script src="https://your-kalocash-domain.com/static/web/js/whatsapp-button.js"></script>
    
    <script>
        document.addEventListener('DOMContentLoaded', function() {
            if (typeof WhatsAppButton !== 'undefined') {
                WhatsAppButton.init({
                    apiBaseUrl: 'https://your-kalocash-domain.com',
                    fallbackNumber: '85262760329',  // 备用号码（推荐配置）
                    buttonText: '联系我们',
                    position: 'bottom-right',
                    debug: false
                });
            }
        });
    </script>
</head>
<body>
    <h1>欢迎访问我的网站</h1>
    <p>页面右下角会显示 WhatsApp 按钮</p>
</body>
</html>
            

⚡ 使用 data 属性自动初始化（最简单方式）

最简单的方式

只需在 script 标签上添加 data 属性，脚本会自动初始化：

<script 
    src="https://your-kalocash-domain.com/static/web/js/whatsapp-button.js"
    data-whatsapp-button
    data-api-base-url="https://your-kalocash-domain.com"
    data-button-text="联系我们"
    data-position="bottom-right"
    data-debug="false"
></script>
            

使用这种方式，您不需要编写任何 JavaScript 代码，脚本会自动初始化并显示按钮。

⚙️ 配置选项

配置项	类型	默认值	说明
`apiBaseUrl`	String	null	必须：KaloCash 服务器地址（例如：'https://your-domain.com'）
`apiEndpoint`	String	'/api/contact-info'	API 端点路径
`fallbackNumber`	String	null	推荐：备用 WhatsApp 号码（API 失败时使用，例如：'85262760329'）
`buttonText`	String	'WhatsApp'	按钮显示的文字
`buttonIcon`	String	'💬'	按钮图标（可以使用 emoji 或 HTML）
`position`	String	'bottom-right'	按钮位置：'bottom-right', 'bottom-left', 'top-right', 'top-left'
`fixed`	Boolean	true	是否固定定位（悬浮按钮）
`zIndex`	Number	9999	按钮的 z-index 值
`showOnLoad`	Boolean	true	是否在加载后立即显示按钮
`debug`	Boolean	false	是否开启调试模式（在控制台输出日志）
`style`	Object	{...}	自定义按钮样式（CSS 属性对象）

🎨 自定义样式示例

WhatsAppButton.init({
    apiBaseUrl: 'https://your-kalocash-domain.com',
    buttonText: '联系我们',
    position: 'bottom-right',
    // 自定义样式
    style: {
        backgroundColor: '#25D366',  // WhatsApp 绿色
        color: '#FFFFFF',
        fontSize: '18px',
        padding: '15px 25px',
        borderRadius: '30px',
        boxShadow: '0 4px 12px rgba(37, 211, 102, 0.3)'
    },
    // 悬停样式
    hoverStyle: {
        transform: 'scale(1.1)',
        boxShadow: '0 6px 16px rgba(37, 211, 102, 0.4)'
    }
});
            

🔧 API 方法

刷新 WhatsApp 号码

// 手动刷新 WhatsApp 号码（从服务器重新获取）
await WhatsAppButton.refresh();
                

更新按钮文字

WhatsAppButton.updateButtonText('联系客服');

更新按钮图标

WhatsAppButton.updateButtonIcon('📱');

显示/隐藏按钮

// 显示按钮
WhatsAppButton.showButton();

// 隐藏按钮
WhatsAppButton.hideButton();
                

⚠️ 重要提示

必须配置 apiBaseUrl

当在其他网站中使用 WhatsApp 按钮时，必须配置 apiBaseUrl 参数，指定 KaloCash 服务器的完整地址（包含协议和域名）。

示例：

apiBaseUrl: 'https://www.kalocash.com'
apiBaseUrl: 'https://api.example.com'
apiBaseUrl: 'http://localhost:8080' （仅用于开发测试）

💡 推荐配置备用号码（fallbackNumber）

如果 API 请求失败（如 404、CORS 问题等），按钮将无法显示。 强烈建议配置 fallbackNumber 作为备用方案，确保按钮始终可用。

示例：

WhatsAppButton.init({
    apiBaseUrl: 'https://your-domain.com',
    fallbackNumber: '85262760329',  // 备用号码
    buttonText: '联系我们'
});
                

CORS 跨域支持

如果您的网站和 KaloCash 服务器不在同一个域名下，需要确保 KaloCash 服务器已配置 CORS 支持。请联系服务器管理员确认 CORS 配置。

🧪 实时测试

当前页面已加载 WhatsApp 按钮

如果您已经配置了正确的 apiBaseUrl，页面右下角应该会显示 WhatsApp 按钮。

❓ 常见问题

Q: 为什么按钮没有显示？

A: 请检查以下几点：

是否配置了正确的 apiBaseUrl？
服务器是否支持 CORS 跨域请求？
打开浏览器开发者工具，查看控制台是否有错误信息
开启 debug: true 查看详细日志
检查 API 是否返回了有效的 WhatsApp 号码

Q: 如何验证按钮是否正常工作？

A: 可以：

开启 debug: true，在浏览器控制台查看日志
打开浏览器开发者工具的 Network 标签，查看是否有发送到 /api/contact-info 的请求
点击按钮，检查是否能正确打开 WhatsApp

Q: WhatsApp 号码会自动更新吗？

A: 不会自动更新。按钮在初始化时获取一次号码。如果需要更新，可以调用 WhatsAppButton.refresh() 方法。

📞 需要帮助？

如果您在集成过程中遇到问题，请：

查看浏览器控制台的错误信息
确认服务器 CORS 配置正确
联系 KaloCash 技术支持团队

💬 WhatsApp 按钮集成指南