Web SDK 接入指南

在推广落地页集成 XXinstall Web SDK，实现指纹采集、归因存储和剪贴板暗水印。

概述

Web SDK 用于推广落地页场景。当用户通过推广链接访问你的落地页时，SDK 会自动采集设备指纹、上报归因参数，并写入零宽字符剪贴板暗水印。

整个流程对用户完全透明，不影响页面体验。

安装

方式一：CDN 引入

适合纯 HTML 落地页，通过 <script> 标签直接引入，SDK 挂载到 window.XXinstall。

<script src="https://cdn.jsdelivr.net/npm/@xxinstall/sdk@2.0.2/dist/xxinstall.global.js"></script>

方式二：npm 安装

适合 Vue / React 等前端工程化项目，支持 TypeScript 类型和 tree-shaking。

npm install @xxinstall/sdk

import { XXinstall } from '@xxinstall/sdk';
import type { AttributionResult } from '@xxinstall/sdk'; // TypeScript 可选

接入示例

示例一：CDN 引入（纯 HTML 落地页）

<!DOCTYPE html>
<html>
<head>
  <meta charset="UTF-8">
  <title>推广落地页</title>
</head>
<body>
  <h1>下载 App</h1>
  <button id="downloadBtn">立即下载</button>

  <script src="https://cdn.jsdelivr.net/npm/@xxinstall/sdk@2.0.2/dist/xxinstall.global.js"></script>
  <script>
    // 读取 URL 推广参数
    var params = new URLSearchParams(location.search);
    var inviteCode = params.get('inviteCode') || '';
    var channel = params.get('channel') || '';

    // 页面加载后自动采集指纹 & 存储归因
    XXinstall.store({
      baseUrl: 'https://your-api-domain.com',
      appKey: 'YOUR_APP_KEY',
      appSecret: 'YOUR_APP_SECRET',
      inviteCode: inviteCode,
      channel: channel,
      onSuccess: function(result) {
        console.log('归因存储成功:', result);
        // result = { recordId, clipCode }
      },
      onError: function(err) {
        console.error('归因存储失败:', err);
      },
    });
  </script>
</body>
</html>

示例二：npm 引入（Vue 3 落地页）

<template>
  <div>
    <h1>下载 App</h1>
    <button @click="doStore">采集指纹 & 存储归因</button>
    <p v-if="msg">{{ msg }}</p>
  </div>
</template>

<script setup lang="ts">
import { ref, onMounted } from 'vue'
import { XXinstall } from '@xxinstall/sdk'

const msg = ref('')

onMounted(() => {
  const params = new URLSearchParams(location.search)
  const inviteCode = params.get('inviteCode') || ''
  const channel = params.get('channel') || ''

  XXinstall.store({
    baseUrl: 'https://your-api-domain.com',
    appKey: 'YOUR_APP_KEY',
    appSecret: 'YOUR_APP_SECRET',
    inviteCode,
    channel,
    onSuccess(result) {
      msg.value = '归因存储成功: ' + JSON.stringify(result)
    },
    onError(err) {
      msg.value = '归因存储失败: ' + err.message
    },
  })
})
</script>

npm 方式的优势：

TypeScript 类型支持，AttributionResult 等接口可直接 import
Vite / Webpack tree-shaking，只打包用到的代码
版本锁定在 package.json，不依赖 CDN 可用性

API

`XXinstall.setHost(url)`

设置全局 API 服务器地址。设置后 store() / resolve() 可省略 baseUrl 参数。

XXinstall.setHost('https://your-api-domain.com');
XXinstall.store({ appKey: '...', appSecret: '...' }); // 无需再传 baseUrl

`XXinstall.store(options)`

采集指纹并上报归因数据。

参数	类型	必填	说明
`baseUrl`	string	否	API 地址，已调用 `setHost()` 时可省略
`appKey`	string	是	应用 Key，在管理后台创建
`appSecret`	string	是	应用 Secret，用于签名
`inviteCode`	string	否	邀请码 / 推广码
`channel`	string	否	渠道标识
`extraParams`	object	否	自定义扩展参数
`onSuccess`	function	否	上报成功回调，参数为 `{ recordId, clipCode }`
`onError`	function	否	上报失败回调，参数为 `Error`