WebClip / WAP SDK 接入指南

在 WebClip 或移动网页中集成 SDK，实现三级归因匹配。

概述

WAP SDK 用于 WebClip（iOS 桌面快捷方式） 和 移动网页 场景。当用户通过 WebClip 或浏览器打开你的应用时，SDK 会执行三级归因匹配。

归因优先级

优先级	方式	置信度	说明
1	URL `_attr` 参数	100%	mobileconfig 动态注入的 base64 参数
2	剪贴板暗水印	99%	读取零宽字符解码出 clipCode
3	指纹匹配	65-95%	采集指纹调用 resolve API 匹配

安装

方式一：CDN 引入

适合纯 HTML 页面，通过 <script> 标签直接引入。

<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">
  <meta name="apple-mobile-web-app-capable" content="yes">
  <title>我的 WebClip 应用</title>
</head>
<body>
  <div id="result">归因匹配中...</div>

  <script src="https://cdn.jsdelivr.net/npm/@xxinstall/sdk@2.0.2/dist/xxinstall.global.js"></script>
  <script>
    XXinstall.resolve({
      baseUrl: 'https://your-api-domain.com',
      appKey: 'YOUR_APP_KEY',
      appSecret: 'YOUR_APP_SECRET',
      onResult: function(result) {
        if (result && result.matchType !== 'none') {
          document.getElementById('result').textContent =
            '归因成功: ' + result.inviteCode + ' (' + result.matchType + ')';
        } else {
          document.getElementById('result').textContent = '未匹配到归因数据';
        }
      },
      onError: function(err) {
        console.error('归因失败:', err);
      },
    });
  </script>
</body>
</html>

示例二：npm 引入（Vue 3 项目）

<template>
  <div>
    <p v-if="loading">归因匹配中...</p>
    <div v-else-if="result">
      <p>inviteCode: {{ result.inviteCode }}</p>
      <p>channel: {{ result.channel }}</p>
      <p>matchType: {{ result.matchType }}</p>
      <p>confidence: {{ (result.confidence * 100).toFixed(1) }}%</p>
    </div>
    <p v-else>未匹配到归因数据</p>
  </div>
</template>

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

const loading = ref(true)
const result = ref<AttributionResult | null>(null)

onMounted(() => {
  XXinstall.resolve({
    baseUrl: 'https://your-api-domain.com',
    appKey: 'YOUR_APP_KEY',
    appSecret: 'YOUR_APP_SECRET',
    onResult(data) {
      result.value = data?.matchType !== 'none' ? data : null
      loading.value = false
    },
    onError(err) {
      console.error('归因失败:', err)
      loading.value = false
    },
  })
})
</script>

npm 方式的优势：

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

配置参数

参数	类型	必填	说明
`baseUrl`	string	否	API 地址，已调用 `setHost()` 时可省略
`appKey`	string	是	应用 Key
`appSecret`	string	是	应用 Secret
`deviceId`	string	否	设备 ID（有则传，用于缓存归因）
`forceRefresh`	boolean	否	跳过本地缓存强制重新归因
`onResult`	function	是	归因结果回调
`onError`	function	否	错误回调

归因结果

interface AttributionResult {
  inviteCode: string | null; // 邀请码
  channel: string;           // 渠道
  confidence: number;        // 置信度 (0-1)
  matchType: string;         // 匹配方式：direct / clipboard / fingerprint / ipua / none
  scene: string;             // 匹配场景
}

缓存 API

// 获取缓存的归因结果（localStorage，180 天有效）
const cached = XXinstall.getAttribution();

// 清除归因缓存（强制下次重新匹配）
XXinstall.clearCache();

mobileconfig 集成

对于 iOS WebClip 场景，推荐使用 mobileconfig 动态配置文件实现 100% 准确归因：

GET /api/v1/mobileconfig/generate?appKey=xxx&inviteCode=abc&channel=wechat

该接口返回 .mobileconfig 文件，自动将归因参数编码到 WebClip 的 URL 中。

用户安装 WebClip 后，SDK 会自动从 URL 的 _attr 参数中解码出归因信息。

缓存机制

归因成功后，结果会缓存到 localStorage，有效期 180 天。后续访问不再重复归因。

可通过 forceRefresh: true 跳过缓存，或调用 XXinstall.clearCache() 手动清除。