@xiaonoodles/uniapp-gio-sdk

CDP Growing-Collector SDK 3.0 for UniApp - 用于埋点事件行为数据上传

简介

这是一个专为 UniApp 开发的 GrowingIO CDP 数据采集 SDK，支持埋点事件上传、用户变量上传和物品模型上传等功能。

安装

npm install @xiaonoodles/uniapp-gio-sdk

或

yarn add @xiaonoodles/uniapp-gio-sdk

快速开始

1. 引入 SDK

import cdpSdk from '@xiaonoodles/uniapp-gio-sdk'

2. 初始化

// 在 App.vue 的 onLaunch 中初始化
cdpSdk.init({
  accountId: 'your-account-id',        // 必传：项目ID
  dataSourceId: 'your-datasource-id',   // 必传：数据源ID（也可以后续通过 setDataSourceId 设置）
  domain: 'https://napi.growingio.com', // 可选：API服务地址
  userId: 'user-123'                    // 可选：登录用户ID（也可以后续通过 setUserId 设置）
})

3. 使用示例

埋点事件上传

// 基础用法
await cdpSdk.collect({
  eventName: 'button_click',
  attributes: {
    button_name: '购买按钮',
    page_name: '商品详情页'
  }
})

// 带资源项的用法
await cdpSdk.collect({
  eventName: 'product_view',
  attributes: {
    product_name: 'iPhone 15'
  },
  resourceItem: {
    id: 'product_001',
    key: 'products'
  }
})

// 批量上传
await cdpSdk.collectBatch([
  { eventName: 'event1', attributes: { key: 'value1' } },
  { eventName: 'event2', attributes: { key: 'value2' } }
])

用户变量上传

await cdpSdk.uploadUserAttributes({
  attributes: {
    user_level: 'VIP',
    user_age: 25,
    user_city: '北京'
  }
})

物品模型上传

// 单个上传
await cdpSdk.uploadItem({
  id: 'product_001',
  key: 'products',
  attributes: {
    product_name: 'iPhone 15',
    product_price: 5999,
    product_category: '手机'
  }
})

// 批量上传
await cdpSdk.uploadItemBatch([
  {
    id: 'product_001',
    key: 'products',
    attributes: { product_name: 'iPhone 15' }
  },
  {
    id: 'product_002',
    key: 'products',
    attributes: { product_name: 'iPad Pro' }
  }
])

API 文档

init(options)

初始化 SDK

参数：

| 参数名 | 类型 | 必填 | 说明 | |--------|------|------|------| | accountId | string | 是 | 项目ID | | dataSourceId | string | 是* | 数据源ID（*可在 init 时不传，但必须在调用其他方法前通过 setDataSourceId() 设置） | | domain | string | 否 | API服务地址，默认：https://napi.growingio.com | | userId | string | 否 | 登录用户ID，可后续通过 setUserId() 设置 |

返回值： SDK 实例（支持链式调用）

setUserId(userId)

设置用户ID

参数：

• userId (string): 登录用户ID

返回值： SDK 实例（支持链式调用）

setDataSourceId(dataSourceId)

设置数据源ID

参数：

• dataSourceId (string): 数据源ID

返回值： SDK 实例（支持链式调用）

collect(eventData)

上传埋点事件

参数：

| 参数名 | 类型 | 必填 | 说明 | |--------|------|------|------| | eventName | string | 是 | 自定义事件的标识 | | userId | string | 是* | 登录用户ID（优先使用传入值，否则使用全局配置，必须有值） | | dataSourceId | string | 是 | 数据源ID（*优先使用传入值，否则使用全局配置，必须有值） | | attributes | object | 否 | 自定义事件属性 | | resourceItem | object | 否 | 资源项，格式：{ id: string, key: string } |

返回值： Promise

collectBatch(events)

批量上传埋点事件

参数：

• events (Array): 事件数组，每个元素的格式同 collect() 方法

返回值： Promise

uploadUserAttributes(userData)

上传用户变量

参数：

| 参数名 | 类型 | 必填 | 说明 | |--------|------|------|------| | userId | string | 是* | 登录用户ID（优先使用传入值，否则使用全局配置，必须有值） | | dataSourceId | string | 是 | 数据源ID（*优先使用传入值，否则使用全局配置，必须有值） | | attributes | object | 否 | 自定义用户属性 |

返回值： Promise

uploadItem(itemData)

上传物品模型

参数：

| 参数名 | 类型 | 必填 | 说明 | |--------|------|------|------| | id | string | 是 | 物品模型id | | key | string | 是 | 物品模型标识 | | dataSourceId | string | 是* | 数据源ID（*优先使用传入值，否则使用全局配置，必须有值） | | attributes | object | 否 | 物品模型变量 |

返回值： Promise

uploadItemBatch(items)

批量上传物品模型

参数：

• items (Array): 物品数组，每个元素的格式同 uploadItem() 方法

返回值： Promise

注意事项

1. 初始化顺序：建议在 App.vue 的 onLaunch 生命周期中初始化 SDK
2. 必传参数：
   • accountId 是初始化时的必传参数
   • dataSourceId 是必需的，必须在调用 collect()、uploadUserAttributes() 或 uploadItem() 之前设置（可以在 init() 时传入，或后续通过 setDataSourceId() 设置，或在方法调用时传入）
   • userId 在调用 collect() 和 uploadUserAttributes() 时必需（可以在 init() 时传入，或后续通过 setUserId() 设置，或在方法调用时传入）
3. 参数优先级：方法调用时传入的参数优先级高于全局配置
4. 错误处理：所有方法都会抛出错误，建议使用 try-catch 进行错误处理

完整示例

// main.js 或 App.vue
import cdpSdk from '@xiaonoodles/uniapp-gio-sdk'

export default {
  onLaunch() {
    // 初始化 SDK
    cdpSdk.init({
      accountId: 'your-account-id',
      dataSourceId: 'your-datasource-id'
    })
    
    // 用户登录后设置用户ID
    cdpSdk.setUserId('user-123')
  },
  
  methods: {
    async trackEvent() {
      try {
        await cdpSdk.collect({
          eventName: 'page_view',
          attributes: {
            page_name: '首页',
            page_url: '/pages/index/index'
          }
        })
        console.log('埋点上传成功')
      } catch (error) {
        console.error('埋点上传失败', error)
      }
    }
  }
}

许可证

MIT

问题反馈

如有问题或建议，请提交 Issue

更新日志

详见 CHANGELOG.md