@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',
  dataSourceId: 'your-datasource-id',
  userId: 'user-123',
  domain: 'https://napi.growingio.com', // 可选，默认值
  autoTrackPage: true,                  // 可选，默认 true
  storeInfo: {
    store_id: 'store_001',
    store_name: '旗舰店'
  },
  miniprogramInfo: {
    miniprogram_identifier: 'xmzg_001',
    miniprogram_name: '小面掌柜'
  }
})

初始化后，SDK 会自动采集以下三个页面事件（autoTrackPage 为 true 时）：

| 事件 | 标识 | 触发时机 | |------|------|---------| | 页面浏览 | miniprogram_page_view | 页面加载、路由跳转成功后、App 从后台恢复 | | 页面跳转 | miniprogram_page_navigate | navigateTo / redirectTo / switchTab / reLaunch / navigateBack | | 页面退出 | miniprogram_page_exit | App 切到后台 |

3. 切换门店

用户切换门店时调用，后续所有埋点事件会自动带上新门店信息：

cdpSdk.setStore({
  store_id: 'store_002',
  store_name: '新店'
})

自动埋点事件属性

miniprogram_page_view（页面浏览）

| 属性名 | 类型 | 说明 | |--------|------|------| | store_id | string | 门店ID | | store_name | string | 门店名称 | | miniprogram_name | string | 小程序名称 | | miniprogram_identifier | string | 小程序标识 | | page_path | string | 页面路径 |

miniprogram_page_navigate（页面跳转）

| 属性名 | 类型 | 说明 | |--------|------|------| | store_id | string | 门店ID | | store_name | string | 门店名称 | | miniprogram_name | string | 小程序名称 | | miniprogram_identifier | string | 小程序标识 | | page_path | string | 当前页面路径 | | stay_duration | string | 当前页面停留时长（秒） | | navigate_page_path | string | 跳转目标页面路径 |

miniprogram_page_exit（页面退出）

| 属性名 | 类型 | 说明 | |--------|------|------| | store_id | string | 门店ID | | store_name | string | 门店名称 | | miniprogram_name | string | 小程序名称 | | miniprogram_identifier | string | 小程序标识 | | page_path | string | 退出时所在页面路径 | | stay_duration | string | App 使用总时长（秒），从打开/恢复到切后台 |

自定义埋点

除了自动采集，仍可手动上传自定义事件：

埋点事件上传

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（*可后续通过 setDataSourceId() 设置） | | userId | string | 否 | 登录用户ID，可后续通过 setUserId() 设置 | | domain | string | 否 | API服务地址，默认 https://napi.growingio.com | | autoTrackPage | boolean | 否 | 是否自动追踪页面，默认 true | | storeInfo | object | 否 | 门店信息 { store_id, store_name } | | miniprogramInfo | object | 否 | 小程序信息 { miniprogram_identifier, miniprogram_name } |

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

setUserId(userId)

设置用户ID

• userId (string): 登录用户ID

setDataSourceId(dataSourceId)

设置数据源ID

• dataSourceId (string): 数据源ID

setStore(storeInfo)

设置/切换门店信息，切换后所有埋点自动带上新门店信息

• storeInfo (object): { store_id, store_name }

collect(eventData)

上传自定义埋点事件

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

返回值： Promise

collectBatch(events)

批量上传埋点事件

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

uploadUserAttributes(userData)

上传用户变量

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

uploadItem(itemData)

上传物品模型

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

uploadItemBatch(items)

批量上传物品模型

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

注意事项

1. 初始化顺序：建议在 App.vue 的 onLaunch 生命周期中初始化 SDK
2. 必传参数：accountId 初始化必传；dataSourceId 和 userId 必须在调用业务方法前设置
3. 参数优先级：方法调用时传入的参数优先级高于全局配置
4. 门店切换：调用 setStore() 后，后续所有自动埋点和手动埋点都会使用新的门店信息
5. 页面退出：通过 uni.onAppHide() 触发，覆盖 App 切后台场景；进程被系统杀死时无法触发
6. Vue2 兼容：SDK 已兼容 UniApp Vue2 项目，无需额外 loader 配置

完整示例

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

export default {
  onLaunch() {
    // 初始化 SDK，自动开启页面追踪
    cdpSdk.init({
      accountId: 'your-account-id',
      dataSourceId: 'your-datasource-id',
      userId: 'user-123',
      storeInfo: {
        store_id: 'store_001',
        store_name: '旗舰店'
      },
      miniprogramInfo: {
        miniprogram_identifier: 'xmzg_001',
        miniprogram_name: '小面掌柜'
      }
    })
  }
}

// 页面中 - 切换门店
cdpSdk.setStore({
  store_id: 'store_002',
  store_name: '新店'
})

// 页面中 - 自定义事件（自动埋点之外的业务埋点）
await cdpSdk.collect({
  eventName: 'order_submit',
  attributes: { order_id: 'ORD_001', amount: 99.9 }
})

许可证

MIT

问题反馈

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

更新日志

详见 CHANGELOG.md