ktad - 快投广告SDK

简介

ktad 是 kuaitouad.com 提供的广告归因与事件追踪 SDK，专为小程序/小游戏场景设计。开发者集成后可实现：

• 广告归因：追踪用户来源，匹配广告投放信息
• 事件埋点：上报自定义业务事件，用于投放效果分析
• 用户画像：设置用户属性，辅助精准营销
• AB实验：获取后台配置的AB测试分组

支持平台

| 平台 | 运行时标识 | 适配文件 | |------|-----------|---------| | 抖音小程序 | tt | core/comfortable/tt.js | | 快手小程序 | ks | core/comfortable/ks.js | | 微信小程序 | wx | core/comfortable/wx.js | | 哔哩哔哩小程序 | bl | core/comfortable/bi.js | | OPPO小游戏 | qg | core/comfortable/qg.js |

SDK 在运行时会自动检测宿主环境，加载对应平台的 API 适配，无需手动指定。

安装

将 SDK 代码引入小程序项目：

import ktad from "./path/to/ktsdk-microapp/index.js"

注意：本项目使用 ES Module，请确保构建工具支持 import 语法。

快速开始

1. 初始化 SDK

在小程序启动时调用 initAsync，传入应用凭证和启动参数：

// 以抖音小程序为例
(async () => {
    const launchOption = tt.getLaunchOptionsSync()

    const matchInfo = await ktad.initAsync(
        "your_app_id",       // 快投后台分配的应用ID
        "your_app_secret",   // 快投后台分配的应用密钥
        launchOption,        // 小程序启动参数（必须包含 query、path 等）
        {
            distinct_id: "user_123",   // 可选：自定义用户唯一标识
            user_properties: {         // 可选：初始化时携带的用户属性
                vip_level: 1
            }
        }
    )

    console.log("归因信息:", matchInfo)
})()

参数说明：

| 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | app_id | string | 是 | 快投平台分配的应用ID | | app_secret | string | 是 | 快投平台分配的应用密钥 | | launch_option | object | 是 | 小程序启动参数（建议直接使用平台提供的 getLaunchOptionsSync） | | other_options | object | 否 | 扩展选项，见下表 |

other_options 说明：

| 字段 | 类型 | 说明 | |------|------|------| | distinct_id | string | 自定义用户唯一标识，长度不能超过64字符；不传则由 SDK 自动生成 | | user_properties | object | 初始化时同步上报的用户属性 |

返回值：

• 返回 match_info（归因匹配信息），包含用户对应的广告渠道、计划、单元等数据。
• SDK 内部会缓存初始化结果，重复调用 initAsync 不会重复请求。

2. 事件埋点

上报业务事件，用于追踪用户行为路径和转化效果：

await ktad.trackAsync("purchase", {
    product_id: "SKU_001",
    amount: 99.9,
    currency: "CNY"
})

参数说明：

| 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | event_name | string | 是 | 事件名称 | | properties | object | 否 | 事件属性集 |

属性类型限制：

• 仅支持 boolean、number、string、null
• 其他类型会被自动移除并在控制台输出警告
• string 类型值长度超过 10240 会被自动截断

3. 设置用户属性

将用户特征上报至平台，用于用户分群和精准投放：

await ktad.setUserPropertiesAsync({
    age: 25,
    gender: "male",
    city: "Beijing",
    is_vip: true
})

属性类型限制与 trackAsync 一致。

4. 注册动态公共属性

如果每次事件都需要携带一些动态变化的公共字段（例如当前关卡、金币数），可以注册一个回调函数：

ktad.registerDynamicProperties(() => {
    return {
        current_level: getCurrentLevel(),
        coin_count: getCoinCount()
    }
})

• 该回调每次调用 trackAsync 时都会执行
• 返回的属性会与 trackAsync 传入的属性合并，后者优先级更高
• 同样需要遵守属性类型限制

5. 获取AB实验配置

根据用户属性和自定义参数，拉取后台配置的AB分组：

const abConfig = await ktad.getABConfigAsync({
    scene: "homepage",    // 自定义参数，平铺结构，不能嵌套
    client_version: "1.2.0"
})

console.log(abConfig)
// {
//     title: "实验组A",
//     description: "新按钮样式",
//     config: { ... }
// }

完整示例

import ktad from "./ktsdk-microapp/index.js"

async function initKtAd() {
    try {
        // 1. 初始化
        const launchOption = tt.getLaunchOptionsSync()
        const matchInfo = await ktad.initAsync(
            "app_id_xxx",
            "app_secret_xxx",
            launchOption,
            { distinct_id: "user_001" }
        )

        // 2. 注册公共属性
        ktad.registerDynamicProperties(() => ({
            timestamp: Date.now()
        }))

        // 3. 设置用户属性
        await ktad.setUserPropertiesAsync({ channel: "douyin" })

        // 4. 上报事件
        await ktad.trackAsync("app_launch", { from: "splash" })

        // 5. 获取AB配置
        const ab = await ktad.getABConfigAsync({ page: "home" })

    } catch (err) {
        console.error("SDK初始化失败:", err)
    }
}

initKtAd()

API一览

| API | 说明 | 是否需要先初始化 | |-----|------|----------------| | ktad.initAsync(app_id, app_secret, launch_option, other_options) | 初始化SDK并获取归因信息 | — | | ktad.trackAsync(event_name, properties) | 上报事件 | 是 | | ktad.setUserPropertiesAsync(properties) | 设置用户属性 | 是 | | ktad.registerDynamicProperties(callback) | 注册动态公共属性回调 | 是 | | ktad.getABConfigAsync(params) | 获取AB实验配置 | 是 |

技术架构

index.js
    └── ktad (单例入口)
        └── KtSDKCore (core/index.js)
            ├── comfortable (core/comfortable/)   ← 多平台API适配层
            │   ├── tt.js   抖音/头条
            │   ├── ks.js   快手
            │   ├── wx.js   微信
            │   ├── bi.js   哔哩哔哩
            │   └── qg.js   OPPO
            ├── http.js     网络请求封装
            ├── sign.js     请求签名 (MD5)
            └── md5.js      MD5算法实现

核心机制

1. 平台自动识别：运行时检测全局对象（tt / ks / wx / bl / qg），自动选择对应适配器
2. 请求签名：所有接口请求使用 MD5 对参数+密钥进行签名，保证数据安全
3. 用户标识：distinct_id 首次自动生成并持久化到本地存储，后续复用
4. 数据校验：属性类型和长度自动过滤，非法数据在控制台输出警告
5. 归因缓存：初始化结果缓存，避免重复网络请求

注意事项

1. 必须先初始化：除 initAsync 外，所有 API 都依赖初始化完成，未初始化时会在控制台报错并返回空值
2. 同一应用只初始化一次：如果重复调用 initAsync 且 app_id / app_secret 不一致，会抛出错误
3. 启动参数勿遗漏：launch_option 是归因关键数据来源，应完整传递平台返回的原始启动参数
4. 属性类型合规：事件属性和用户属性只能是基本类型，嵌套对象会被过滤

版本信息

• 当前版本：1.3.3
• 包名：ktad
• 维护方：kuaitouad.com