官网SDK技术文档

FsYxt Web SDK 是一款面向营销官网的 JavaScript SDK,提供访客追踪、事件埋点、表单管理、会员体系等核心功能,帮助企业实现精准的营销数据采集与用户行为分析。

步骤1: 引入SDK

<script>
    (function () {
        var s = document.createElement("script");
        s.type = "text/javascript";
        s.charset = "utf-8";
        s.src = "https://www.fxiaoke.com/ec/kemai/release/static/marketing-website-access.js?id=" + Math.random();
        document.getElementsByTagName("head")[0].appendChild(s);
    })();
</script>

步骤2: 初始化配置

window.addEventListener('load', function() {
    FsYxt.configure({
        ea: "your-enterprise-ea",     // 企业ea(必填)
        websiteId: "your-website-id", // 网站ID(必填)
        host: "your-host.com",        // API HOST地址(必填)
        enableSpaTracking: false      // 是否启用SPA单页应用埋点(可选)
    });
});

注意: 此方式已过时，仅为兼容旧项目保留，新项目请使用方式一。

引入SDK并初始化配置（一步完成）

<script>
    (function () {
        var config = {
            ea: 'your-enterprise-ea',
            websiteId: 'your-website-id',
            host: 'your-host.com'
        };
        var s = document.createElement("script");
        s.type = "text/javascript";
        s.charset = "utf-8";
        s.src = "https://www.fxiaoke.com/ec/kemai/release/static/marketing-website-access.js?id=" + Math.random();
        s.id = "fsMarketingWebsiteScript";
        s.innerHTML = [
            "FSscriptArgs.WebsiteEa='" + config.ea + "'",
            "FSscriptArgs.WebsiteId='" + config.websiteId + "'",
            "FSscriptArgs.host='" + config.host + "'"
        ].join(';');
        window.FsYxtWebsiteEa = config.ea;
        window.FsYxtWebsiteId = config.websiteId;
        window.FsYxtHost = config.host;
        document.getElementsByTagName("head")[0].appendChild(s);
    })();
</script>

使用旧方式时，配置已在脚本加载时完成，无需再调用FsYxt.configure()。

window.addEventListener('load', function() {
    // SDK初始化成功
    FsYxt.on('onReady', function() {
        console.log('SDK已准备就绪');
    });

    // SDK初始化失败
    FsYxt.on('onError', function(error) {
        console.error('SDK初始化失败:', error);
    });
});

初始化SDK配置,必须在使用其他功能前调用。

参数名	类型	必填	说明
ea	String	是	应用源ID
websiteId	String	是	网站ID
host	String	是	主机地址
enableSpaTracking	Boolean	否	是否启用单页应用(SPA)埋点,默认false

FsYxt.configure({
    ea: "88146",
    websiteId: "8b28bec67afc42c281f078ff9bea7fec",
    host: "crm.example.com",
    enableSpaTracking: true
});

上报自定义事件埋点,用于追踪用户行为。

参数名	类型	必填	说明
eventId	String	是	事件ID
attributesId	String/Array	否	事件属性ID(传数组时取第一个)
marketingEventId	String	否	市场活动ID
eventDescription	String	否	事件描述
success	Function	否	成功回调函数
fail	Function	否	失败回调函数

FsYxt.track({
    eventId: 'button_click',
    attributesId: 'header_download_btn',
    eventDescription: '点击下载按钮',
    marketingEventId: 'xxx',
    success: function(data) {
        console.log('埋点上报成功', data);
    },
    fail: function(error) {
        console.error('埋点上报失败', error);
    }
});

动态创建表单iframe,用于在页面中嵌入营销表单。

参数名	类型	必填	说明
id	String	是	表单容器元素的ID
src	String	是	表单页面URL
style	String	否	iframe样式(CSS字符串)
autoheight	Boolean	否	是否自动适应高度

FsYxt.createForm({
    id: 'form-container',
    src: 'https://crm.example.com/proj/page/marketing-page?id=xxx',
    style: 'width:100%;height:600px;border:none;',
    autoheight: true
});

<!-- 在页面中预留表单容器 -->
<div id="form-container"></div>

生成营销推广二维码(支持公众号/企业微信)。

参数名	类型	必填	说明
type	String	是	二维码类型: "gzh"(公众号) 或 "qw"(企业微信)
fanQrCodeId	String	是	场景ID或粉丝码ID
options	Object	否	配置选项
options.renderType	String	否	渲染类型: "auto"(自动渲染) 或 "manual"(手动渲染),默认"auto"
options.success	Function	否	成功回调函数
options.fail	Function	否	失败回调函数

// 自动渲染模式
FsYxt.generateQrcode('gzh', 'xxx', {
    renderType: 'auto',
    success: function(result) {
        console.log('二维码容器:', result.container);
        console.log('二维码URL:', result.qrUrl);
    },
    fail: function(error) {
        console.error('生成失败:', error);
    }
});

// 手动渲染模式
FsYxt.generateQrcode('qw', 'xxx', {
    renderType: 'manual',
    success: function(result) {
        // 自行处理二维码URL
        document.getElementById('my-qrcode').src = result.qrUrl;
    }
});

会员操作拦截,限制非会员访问特定功能。

参数名	类型	必填	说明
className	String	是	需要拦截的元素类名
onFormSubmit	Function	否	表单提交回调函数
expires	Number	否	会员登录态过期时间(毫秒)

FsYxt.memberOperationIntercept({
    className: 'premium-download-btn',
    expires: 24 * 60 * 60 * 1000, // 24小时
    onFormSubmit: function(result) {
        if (result.status === 'ok') {
            console.log('会员登录成功');
        }
    }
});

<!-- 需要拦截的元素 -->
<a href="download.zip" class="premium-download-btn">下载资源</a>

嵌入式会员登录表单(仅PC端)。

参数名	类型	必填	说明
className	String	是	登录表单容器元素类名
onFormSubmit	Function	否	表单提交回调函数
expires	Number	否	会员登录态过期时间(毫秒)

FsYxt.memberSignIn({
    className: 'member-login-container',
    expires: 7 * 24 * 60 * 60 * 1000, // 7天
    onFormSubmit: function(result) {
        if (result.status === 'ok') {
            console.log('登录成功');
            // 跳转或刷新页面
            location.reload();
        }
    }
});

<div class="member-login-container"></div>

为单页应用(SPA)启用路由变化埋点追踪。

注意: 使用 configure() 初始化时,推荐通过 enableSpaTracking: true 参数启用,无需单独调用此方法。

// 方式一: 推荐
FsYxt.configure({
    ea: "88146",
    websiteId: "xxx",
    host: "crm.example.com",
    enableSpaTracking: true  // 启用SPA埋点
});

// 方式二: 手动调用
FsYxt.trackSinglePage();

获取SDK当前配置信息,包含访客ID、UTM参数等。

返回一个包含以下字段的对象:

字段名	类型	说明
visitorId	String	访客唯一标识
fsWebsiteUid	String	网站访客ID
websiteId	String	网站ID
host	String	主机地址
ea	String	应用源ID
utmSource	String	UTM来源
utmMedium	String	UTM媒介
utmCampaign	String	UTM活动
utmContent	String	UTM内容
utmTerm	String	UTM关键词
...	...	其他扩展参数

var config = FsYxt.getConfig();
console.log('访客ID:', config.visitorId);
console.log('UTM来源:', config.utmSource);
console.log('完整配置:', config);

绑定SDK事件回调。

事件名	触发时机	回调参数
onReady	SDK初始化完成	无
onError	SDK初始化失败	(errorMessage: String)
onFormSubmit	表单提交完成	(result: Object)

// SDK就绪事件
FsYxt.on('onReady', function() {
    console.log('SDK已准备就绪');
});

// 错误事件
FsYxt.on('onError', function(error) {
    console.error('初始化错误:', error);
});

// 表单提交事件
FsYxt.on('onFormSubmit', function(result) {
    console.log('提交状态:', result.status); // 'ok' 或 'fail'
    console.log('表单数据:', result.formData);
    console.log('服务器响应:', result.response);
});

FsYxt.FormSDK 提供表单相关的高级功能,适用于自定义表单场景。

获取表单字段配置信息。

参数名	类型	必填	说明
formId	String	是	表单ID
extendParams	Object	否	扩展参数
success	Function	否	成功回调函数
fail	Function	否	失败回调函数

{
//...
}

FsYxt.FormSDK.getFieldDescriptions({
    formId: 'xxx',
    success: function(data) {
        console.log('表单信息:', data);
    },
    fail: function(error) {
        console.error('获取失败:', error);
    }
});

提交自定义表单数据。

参数名	类型	必填	说明
formId	String	是	表单ID
enrollId	String	否	报名ID(用于更新已有报名)
sceneType	Number	否	场景类型: 0-当前页为转化页, 2-上一页为转化页
data	Object	是	表单数据
extendParams	Object	否	扩展参数
success	Function	否	成功回调函数
fail	Function	否	失败回调函数

注意: 请根据管理后台表单设置字段apiName为准，以下数据仅为参考示例。

字段前缀	字段类型	示例
text5_	单行文本	text5_1: "张三"
text6_	多行文本	text6_1: "这是一段描述"
text7_	单选	text7_1: "选项A"
texts1_	多选	texts1_1: ["选项A", "选项B"]
num1_	数字	num1_1: 100
num2_	日期	num2_1: "2025-01-01"
picMap_	图片	picMap_1: "http://..."
name	姓名	name: "张三"
phone	手机号	phone: "13800138000"
email	邮箱	email: "test@example.com"
company	公司	company: "XX科技有限公司"
position	职位	position: "产品经理"

FsYxt.FormSDK.submitForm({
    formId: 'form_123456',
    sceneType: 0,
    data: {
        name: '张三',
        phone: '13800138000',
        email: 'zhangsan@example.com',
        company: 'XX科技有限公司',
        position: '产品经理',
    },
    success: function(result) {
        console.log('提交成功:', result);
        alert('提交成功!');
    },
    fail: function(error) {
        console.error('提交失败:', error);
        alert('提交失败,请重试');
    }
});

发送短信验证码。

参数名	类型	必填	说明
formId	String	是	表单ID
mobile	String	是	手机号码
extendParams	Object	否	扩展参数
success	Function	否	成功回调函数
fail	Function	否	失败回调函数

FsYxt.FormSDK.sendSMCode({
    formId: 'xxx',
    mobile: '13800138000',
    success: function(data) {
        console.log('验证码发送成功');
        alert('验证码已发送');
    },
    fail: function(error) {
        console.error('验证码发送失败:', error);
        alert('发送失败,请稍后重试');
    }
});

获取省市区三级联动数据。

参数名	类型	必填	说明
extendParams	Object	否	扩展参数
success	Function	否	成功回调函数
fail	Function	否	失败回调函数

FsYxt.FormSDK.getAreaData({
    success: function(data) {
        console.log('省市区数据:', data);
    },
    fail: function(error) {
        console.error('获取失败:', error);
    }
});

<!DOCTYPE html>
<html>
<head>
    <title>产品活动页</title>
    <script>
        (function () {
            var s = document.createElement("script");
            s.type = "text/javascript";
            s.charset = "utf-8";
            s.src = "https://www.fxiaoke.com/ec/kemai/release/static/marketing-website-access.js?id=" + Math.random();
            document.getElementsByTagName("head")[0].appendChild(s);
        })();
    </script>
</head>
<body>
    <!-- 页面内容 -->
    <button id="downloadBtn" class="premium-content">下载白皮书</button>
    
    <!-- 表单容器 -->
    <div id="marketing-form"></div>
    
    <!-- 二维码容器 -->
    <div id="qrcode"></div>

    <script>
        // 1. 初始化SDK
        window.addEventListener('load', function() {
            FsYxt.configure({
                ea: "88146",
                websiteId: "8b28bec67afc42c281f078ff9bea7fec",
                host: "crm.example.com",
                enableSpaTracking: false
            });
            // 2. 监听SDK就绪
            FsYxt.on('onReady', function() {
                console.log('SDK初始化完成');
                
                // 3. 上报页面访问埋点
                FsYxt.track({
                    eventId: 'page_view',
                    attributesId: 'landing_page',
                    eventDescription: '访问活动落地页'
                });
                
                // 4. 创建营销表单
                FsYxt.createForm({
                    id: 'marketing-form',
                    src: 'https://crm.example.com/form/xxxxx',
                    style: 'width:100%;height:600px;',
                    autoheight: true
                });
                
                // 5. 生成推广二维码
                FsYxt.generateQrcode('gzh', 'xxx', {
                    renderType: 'auto',
                    success: function(result) {
                        console.log('二维码已生成');
                    }
                });
                
                // 6. 设置会员拦截
                FsYxt.memberOperationIntercept({
                    className: 'premium-content',
                    expires: 7 * 24 * 60 * 60 * 1000 // 7天
                });
            });

            // 7. 监听表单提交
            FsYxt.on('onFormSubmit', function(result) {
                if (result.status === 'ok') {
                    // 上报转化埋点
                    FsYxt.track({
                        eventId: 'form_submit',
                        attributesId: 'marketing_form',
                        eventDescription: '提交营销表单'
                    });
                    alert('提交成功!');
                }
            });

            // 8. 按钮点击埋点
            document.getElementById('downloadBtn').addEventListener('click', function() {
                FsYxt.track({
                    eventId: 'button_click',
                    attributesId: 'download_whitepaper',
                    eventDescription: '点击下载白皮书'
                });
            });
        });
    </script>
</body>
</html>

<!DOCTYPE html>
<html>
<head>
    <title>自定义表单</title>
    <script>
        (function () {
            var s = document.createElement("script");
            s.type = "text/javascript";
            s.charset = "utf-8";
            s.src = "https://www.fxiaoke.com/ec/kemai/release/static/marketing-website-access.js?id=" + Math.random();
            document.getElementsByTagName("head")[0].appendChild(s);
        })();
    </script>
</head>
<body>
    <form id="customForm">
        <input type="text" id="name" placeholder="姓名" required>
        <input type="tel" id="phone" placeholder="手机号" required>
        <input type="text" id="smscode" placeholder="验证码" required>
        <button type="button" id="sendCodeBtn">发送验证码</button>
        <input type="email" id="email" placeholder="邮箱">
        <input type="text" id="company" placeholder="公司">
        <button type="submit">提交</button>
    </form>

    <script>
        var formId = 'form_123456';
        var countdown = 0;

        // 初始化SDK
        window.addEventListener('load', function() {
            FsYxt.configure({
                ea: "88146",
                websiteId: "8b28bec67afc42c281f078ff9bea7fec",
                host: "crm.example.com"
            });
        });

        // 发送验证码
        document.getElementById('sendCodeBtn').addEventListener('click', function() {
            if (countdown > 0) return;
            
            var phone = document.getElementById('phone').value;
            if (!phone) {
                alert('请输入手机号');
                return;
            }
            
            FsYxt.FormSDK.sendSMCode({
                formId: formId,
                mobile: phone,
                success: function() {
                    alert('验证码已发送');
                    countdown = 60;
                    var timer = setInterval(function() {
                        countdown--;
                        document.getElementById('sendCodeBtn').innerText = countdown + 's';
                        if (countdown <= 0) {
                            clearInterval(timer);
                            document.getElementById('sendCodeBtn').innerText = '发送验证码';
                        }
                    }, 1000);
                },
                fail: function(error) {
                    alert('发送失败:' + error.errMsg);
                }
            });
        });

        // 提交表单
        document.getElementById('customForm').addEventListener('submit', function(e) {
            e.preventDefault();
            
            var formData = {
                name: document.getElementById('name').value,
                phone: document.getElementById('phone').value,
                smscode: document.getElementById('smscode').value,
                email: document.getElementById('email').value,
                company: document.getElementById('company').value
            };
            
            FsYxt.FormSDK.submitForm({
                formId: formId,
                sceneType: 0,
                data: formData,
                success: function(result) {
                    alert('提交成功!');
                    document.getElementById('customForm').reset();
                },
                fail: function(error) {
                    alert('提交失败:' + error.errMsg);
                }
            });
        });
    </script>
</body>
</html>

import React, { useEffect } from 'react';

function App() {
    useEffect(() => {
        // 初始化SDK
        if (window.FsYxt) {
            window.FsYxt.configure({
                ea: "88146",
                websiteId: "8b28bec67afc42c281f078ff9bea7fec",
                host: "crm.example.com",
                enableSpaTracking: true // 启用SPA路由埋点
            });

            // 监听SDK就绪
            window.FsYxt.on('onReady', () => {
                console.log('FsYxt SDK Ready');
            });

            // 监听表单提交
            window.FsYxt.on('onFormSubmit', (result) => {
                if (result.status === 'ok') {
                    console.log('Form submitted successfully');
                }
            });
        }
    }, []);

    const handleButtonClick = () => {
        // 上报点击事件
        window.FsYxt.track({
            eventId: 'button_click',
            attributesId: 'cta_button',
            eventDescription: 'CTA按钮点击'
        });
    };

    return (
        <div className="App">
            <h1>React应用示例</h1>
            <button onClick={handleButtonClick}>立即咨询</button>
        </div>
    );
}

export default App;

建议在 window.onload 或 DOMContentLoaded 事件后初始化
确保DOM元素已加载完成再调用相关方法

FsYxt.on('onError', function(error) {
    // 记录错误日志
    console.error('SDK Error:', error);
    // 可选: 上报到监控系统
});

使用清晰的事件ID命名规则,如 page_view、button_click、form_submit
事件描述应简洁明了,便于后续数据分析
关键业务节点务必添加埋点

function validateFormData(data) {
    if (!data.name || !data.phone) {
        alert('姓名和手机号不能为空');
        return false;
    }
    if (!/^1[3-9]\d{9}$/.test(data.phone)) {
        alert('手机号格式不正确');
        return false;
    }
    return true;
}

// 使用
if (validateFormData(formData)) {
    FsYxt.FormSDK.submitForm({ ... });
}

避免频繁调用 track() 方法,建议对高频事件进行节流或防抖处理
使用 createForm() 时,合理设置 iframe 尺寸,避免影响页面性能

A: 检查以下几点:

确认 ea、websiteId、host 参数正确
检查网络连接是否正常
查看浏览器控制台是否有报错信息
监听 onError 事件获取详细错误信息

A: 在 configure() 时设置 enableSpaTracking: true:

FsYxt.configure({
    ea: "88146",
    websiteId: "xxx",
    host: "crm.example.com",
    enableSpaTracking: true  // 关键配置
});

A: 使用 getConfig() 方法:

var config = FsYxt.getConfig();
var visitorId = config.visitorId; // 或 config.fsWebsiteUid

确认 formId 是否正确
检查表单数据格式是否符合要求
查看 fail 回调中的错误信息
确认SDK已成功初始化(监听 onReady 事件)

确认元素类名设置正确
检查会员登录态是否已过期
确认后台会员配置是否正确

A: 请确保SDK已完成加载后再执行相关方法:

// 推荐做法:在 window.onload 事件后执行
window.addEventListener('load', function() {
    FsYxt.configure({
        ea: "88146",
        websiteId: "xxx",
        host: "crm.example.com"
    });
    
    // 等待SDK初始化完成
    FsYxt.on('onReady', function() {
        // 在此处调用其他SDK方法
        FsYxt.track({ ... });
    });
});

常见错误场景:

❌ 在SDK脚本加载前就调用 FsYxt 对象
❌ 在 <head> 中直接执行SDK方法
✅ 使用 window.onload 或 DOMContentLoaded 事件
✅ 监听 onReady 事件确保SDK初始化完成

如有其他问题,请联系技术支持团队。

2025-11-26

官网SDK技术文档

概述

快速开始

方式一：推荐方式

方式二：旧方式(不推荐)

监听初始化状态

核心API

1. configure(config)

参数说明

使用示例

2. track(params)

参数说明

使用示例

3. createForm(params)

参数说明

使用示例

4. generateQrcode(type, fanQrCodeId, options)

参数说明

使用示例

5. memberOperationIntercept(params)

参数说明

使用示例

6. memberSignIn(params)

参数说明

使用示例

7. trackSinglePage()

使用示例

8. getConfig()

返回值

使用示例

9. on(eventName, handler)

支持的事件

使用示例

FormSDK API

1. FormSDK.getFieldDescriptions(params)

参数说明

返回数据结构

使用示例

2. FormSDK.submitForm(params)

参数说明

表单数据字段说明

使用示例

3. FormSDK.sendSMCode(params)

参数说明

使用示例

4. FormSDK.getAreaData(params)

参数说明

使用示例

完整示例

场景一: 营销活动落地页

场景二: 自定义表单提交

场景三: React单页应用集成

最佳实践

1. 初始化时机

2. 错误处理

3. 事件埋点规范

4. 表单数据验证

5. 性能优化

常见问题

Q1: SDK初始化失败怎么办?

Q2: 单页应用如何启用路由埋点?

Q3: 如何获取访客ID?

Q4: 表单提交失败如何排查?

Q5: 会员拦截功能不生效?

Q6: FsYxt报错 "FsYxt is not defined" 或方法调用失败?

技术支持

本页目录