H5&小程序 SDK API文档

1 初始化启动接口

接口描述:

使用统计功能以前，需要先启动 SDK，该接口用于在 App Launch 时启动数据统计 SDK。

接口定义:

/**
 * 初始化统计SDK
 * @param gsAppid 统计sdk appid
 */
function init(appInfo: {
    gsAppid: string;
}): void;

接口说明:

接口示例:

import GsIdo from './lib/gsido-min.js'
App({
    globalData: {},
    onLaunch: function () {

        //打开/关闭调试模式,调试模式下sdk将会在控制台打印运行日志
        //GsIdo.setDebugEnable(true)

        //初始化统计sdk
        GsIdo.init({
            //统计sdk appid
            gsAppid: 'xXmjbbab3b5F1m7wAYZoG2'
        });
        console.log(GsIdo.getVersion())
    },
});

2 获取gtcid

接口描述:

您可通过下面的方法获取gtcid，gtcid可用于用户画像标签的查询。

接口定义:

/*
* gtcid可用于用户画像标签的查询,需要在sdk启动后调用
*/
function gtcid(): string;

接口示例:

console.log("gtcid=",GsIdo.gtcid())

3 活跃事件

• sdk初始化后，会自动生成和上传应用的活跃事件，用于统计应用的启动次数和活跃时长。

• 一次完整的启动包括以下几种情况：
  1. 从启动应用到关闭应用；
  2. 应用从前台退至后台，且在后台运行时间超过30秒（可通过setSessionTimeoutMillis修改该值)；
  3. 为了准确地统计应用活跃时长，应用在前台时sdk会定时地更新应用活跃时间，定时器触发时间间隔为5秒

# 在调试模式下sdk通常会在控制打印如下日志

#应用到前台触发活跃时长更新
[GsIdo][Info] ["session new"]
[GsIdo][Info] ["session update end time"]
# 活跃事件上传成功
[GsIdo][Info] ["upload type8 1709709218881|0|1709709148766#1709709218881"] 

4 自定义事件

计数事件

• 计数事件一般用于统计行为被触发的次数。
• 在事件触发时调用onEvent方法，SDK 会根据事件id ，统计该事件的触发次数。
• 在生成计数事件时，调用方可以设置一些自定义的属性，sdk也会自动为事件补充一些预置属性，这些预置属性以$符开头。

//事件触发时调用onEvent计数
GsIdo.onEvent({
  //事件id
  id: 'id000',
  //自定义属性，注意value的类型只能是string|number|Date|boolean
  attrs: new Map([
    ['key_string', 'this is a string'],
    ['key_number', 111],
    ['key_date', new Date()],
    ['key_boolean', true]])
})

计时事件

• 计时事件一般用于统计行为消耗的时间。
• 在事件开始时调用onBeginEvent方法，在结束时调用onEndEvent方法，sdk会根据事件id，统计改事件从begin到end的耗时。
• 使用计时事件时，onBeginEvent的id必须要onEndEvent的id保持一致才会生效。
• 在计时事件结束时，调用方可以设置一些自定义的属性，sdk也会自动为事件补充一些预置属性，这些预置属性以$符开头。

//事件开始时调用onBeginEvent开始计时
GsIdo.onBeginEvent({
  //事件id
  id: 'id111'
})

//...

//事件结束时调用onEndEvent结束计时
GsIdo.onEndEvent({
    //注意onBeginEvent和onEndEvent中的id要保持一致
  id: 'id111'
  //自定义属性时，注意value的类型只能是string|number|Date|boolean
  attrs: new Map([['key_string', 'this is a string'],
                  ['key_number', 111],
                  ['key_date', new Date()],
                  ['key_boolean', false]])
})

API说明文件

GsIdo.d.ts⽂件如下

declare namespace GsIdo {
    /**
     * 初始化统计SDK
     * @param gsAppid 统计sdk appid
     */
    function init(appInfo: {
        gsAppid: string;
    }): void;

    /*
     * gtcid可用于用户画像标签的查询,需要在sdk启动后调用
     */
    function gtcid(): string;

    /**
     * 计时事件开始
     * @param id 事件id
     * @param attrs 事件自定义属性，（注意：不能以$开头）
     * @param ext 用户扩展信息，不纳入统计
     */
    function onBeginEvent(event: {
        id: string;
        attrs?: Map<string, string | number | Date | boolean>;
        ext?: string;
    }): void;
    /**
     * 计时事件结束
     * @param id 事件id
     * @param attrs 事件自定义属性，（注意：不能以$开头）
     * @param ext 用户扩展信息，不纳入统计
     */
    function onEndEvent(event: {
        id: string;
        attrs?: Map<string, string | number | Date | boolean>;
        ext?: string;
    }): void;
    /**
     * 事件触发
     * @param id 事件id
     * @param attrs 事件自定义属性，（注意：不能以$开头）
     * @param ext 用户扩展信息，不纳入统计
     */
    function onEvent(event: {
        id: string;
        attrs?: Map<string, string | number | Date | boolean>;
        ext?: string;
    }): void;

    /**
     * 设置用户Id，用于区分是否是游客. 需要在sdk启动后调用
     * @param userid 用户id
     */
    function setUserId(userid: string): void;

    /**
     * 用户属性事件触发
     * @param attrs 用户属性，（注意：不能以$开头）
     */
    function setProfile(profile: {
        attrs: Map<string, string | number | Date | boolean>;
        ext?: string;
    }): void;
    /**
     * 开启/关闭调试模式，开启后将在控制台输出sdk相关日志
     * @param enable 是否开启
     */
    function setDebugEnable(enable: boolean): void;

    /**
     * 设置最小活跃时长
     * 设置有效活跃时长，活跃时长满足[minActiveMillis, maxActiveMillis]的才会上报服务器记录
     * @param minActiveMillis 最小活跃时长, 默认1000ms, 需要设置小于MaxActiveMillis
     */
    function setMinActiveMillis(minActiveMillis: number): void;
    /**
     * 获取最小活跃时长
     */
    function getMinActiveMillis(): number;

    /**
     * 设置最大活跃时长，活跃时长满足[minActiveMillis, maxActiveMillis]的才会上报服务器记录
     * @param maxActiveMillis 最大活跃时长, 默认 12*3600*1000 ms， 需要设置大于MinActiveMillis
     */
    function setMaxActiveMillis(maxActiveMillis: number): void;

    /**
     * 获取最大活跃时长
     */
    function getMaxActiveMillis(): number;

     /**
     * 设置会话超时时长，进入后台后开始计时，超过该时长后再回到前台则认为是两次会话，每次会话都会产生一条活跃记录
     * @param timeoutMillis 会话超时时长，单位毫秒, 需要设置大于等于30 * 1000
     */
    export function setSessionTimeoutMillis(timeoutMillis: number): void;

   /**
     * 获取当前会话超时时长
     */
    function getSessionTimeoutMillis(): number;

    // 累计条数到达ForceUploadSize 或 距离上一次汇报时间间隔超过UploadInterval后，将触发上传流程

    // onEvent的上报间隔， 默认10000毫秒，即10秒。
    // 传入的参数如果小于默认值，则按照默认值生效。
    export function setEventUploadInterval(interval: number): void;

    // onEvent的上报条数阈值，默认30
    // 需要设置大于等于1
    export function setEventForceUploadSize(size: number): void;

    // Profile上报间隔， 默认5000毫秒，即5秒
    // 传入的参数如果小于默认值，则按照默认值生效。
    export function setProfileUploadInterval(interval: number): void;

    // Profile上报条数阈值，默认5
    // 需要设置大于等于1
    export function setProfileForceUploadSize(size: number): void;
    /**
     * 获取当前SDK版本
     */
    function getVersion(): string;

}