跳到主要内容
进入后台
当前模块服务端集成
事件采集
AI-ready documentation

Node SDK

介绍 Gravity Engine Node SDK 的环境要求、安装初始化、事件追踪和用户属性管理，并提供参数说明与代码示例。

查看 Markdown

概述

Gravity Engine Node SDK 是一个用于数据采集和上报的工具，帮助开发者轻松集成事件追踪和用户行为分析功能。在接入前，请先阅读 接入前准备。服务端接入 Node SDK，完成事件的服务端报送功能，您需要注意以下几点：

  • 服务端 SDK仅负责事件的收集上报，不负责用户的注册，用户注册需要调用客户端 SDK 的 initialize 方法完成；
  • 客户端和服务端 SDK使用的用户 client id 需要保持一致；
  • 在客户端完成 initialize 方法调用之后，服务端 SDK才能开始做事件采集上报，否则上报不成功；
  • 服务端 SDK接入事件上报时，请参考 元事件页面 下关于事件的详情属性；
  • 请尽量上报事件的公共属性，引力不做强制要求，但是上报足够多属性，可以方便您后续在引力平台使用数据分析功能（$city、$province、$country、$browser、$browser_version 属性可以不上报，引力后端会自动采集）；
  • 关于属性的更多信息，请您参考 事件属性页面。

1. 安装集成

npm 地址：gravity-engine-sdk

npm i gravity-engine-sdk

2. 初始化配置

基础配置

const GEData = require("gravity-engine-sdk");

GEData.enableLog(true);
const access_token = "your_access_token";
const SERVER_URL = `https://backend.gravity-engine.com/event_center/api/v1/event/collect/?access_token=${access_token}`;
const clientId = "your_client_id";

const geSDK = GEData.initWithDebugMode(SERVER_URL, {});

// const geSDK = GEData.initWithBatchMode(SERVER_URL, {
//     batchSize: 20,
//     compress: true // enable compress or not, default true
// });
//
// const geSDK = GEData.initWithAsyncBatchMode(SERVER_URL, {
//     batchSize: 20,
//     compress: true // enable compress or not, default true
// });

核心功能

1. 事件追踪

如需上报自定义事件，您必须先在 元事件 中添加，否则会上报失败！

您可以调用 track 方法，记录用户自定义事件。

您需要先在 元事件 中添加自定义事件，然后调用 track 方法上报自定义事件。

for (let i = 0; i < 100; i++) {
    const eventName = "$AdClick";
    const properties = {
        idx: i,
        prop_double: 134.1,
        product_list: ['a', 'a', 'b'],
    };
    geSDK.track(eventName, clientId, properties, function (e) {
        console.log('in cb');
        if (e) {
            console.log("exception: ", e);
        }
    });
}
  • 事件的名称是字符串类型。
  • Key 为该属性的名称，为字符串类型。
  • Value 为该属性的值，支持字符串、数字、布尔、时间、对象、对象组、数组。

2. 用户属性管理

设置用户属性（覆盖）

对于一般的用户属性，您可以调用 userSet 进行设置，使用该接口上传的属性将会覆盖原有的属性值。

geSDK.userSet(clientId, {
    user_name: 'xxx',
}, function (e) {
    console.log('in cb');
    if (e) {
        console.log("exception: ", e);
    }
});

初始化用户属性（仅首次设置有效）

对于只在首次设置时有效的属性，我们可以使用 userSetOnce 记录这些属性。与 userSet 方法不同的是，如果被设置的用户属性已存在，则这条记录会被忽略而不会覆盖已有数据。因此，userSetOnce 适用于为用户设置首次激活时间、首次注册时间等属性。

geSDK.userSetOnce(clientId, {
    prop_set_once: 'once',
}, function (e) {
    console.log('in cb');
    if (e) {
        console.log("exception: ", e);
    }
});

累加用户属性

对于数值型的用户属性，可以使用 userIncrement 对属性值进行累加。常用于记录用户付费次数、付费额度、积分等属性。

geSDK.userIncrement(clientId, {
    TotalRevenue: 100,
}, function (e) {
    console.log('in cb');
    if (e) {
        console.log("exception: ", e);
    }
});

用户属性取最大值

对于数值型的用户属性，可以使用 userMax 比较数值大小，保存较大的值。

geSDK.userMax(clientId, {
    TotalRevenue: 1000,
}, function (e) {
    console.log('in cb');
    if (e) {
        console.log("exception: ", e);
    }
});

用户属性取最小值

对于数值型的用户属性，可以使用 userMin 比较数值大小，保存较小的值。

geSDK.userMin(clientId, {
    TotalRevenue: 1,
}, function (e) {
    console.log('in cb');
    if (e) {
        console.log("exception: ", e);
    }
});

用户属性追加

对用户喜爱的电影、用户点评过的餐厅等属性，可以调用 userAppend 记录列表型属性。

geSDK.userAppend(clientId, {
    prop_list_type: ['a', 'a', 'b']
}, function (e) {
    console.log('in cb');
    if (e) {
        console.log("exception: ", e);
    }
});

用户属性去重追加

调用 userUniqAppend 对 Array 类型的用户数据去重追加元素。

geSDK.userUniqAppend(clientId, {
    prop_list_type: ['a', 'a', 'b', 'c']
}, function (e) {
    console.log('in cb');
    if (e) {
        console.log("exception: ", e);
    }
});

重置用户属性

如果需要重置已设置的某个用户属性，可以调用 userUnset 进行重置。

geSDK.userUnset(clientId, {
    user_name: '',
}, function (e) {
    console.log('in cb');
    if (e) {
        console.log("exception: ", e);
    }
});

清空用户属性

调用 userDel 方法，将把当前用户属性清空，您将无法再查询该名用户的用户属性，但该用户产生的事件仍然可以被查询到。

geSDK.userDel(clientId, function (e) {
    console.log('in cb');
    if (e) {
        console.log("exception: ", e);
    }
});

3. 数据管理

立即上报数据

geSDK.flush();

注意：频繁调用 flush() 会影响性能，建议在重要操作后调用。

关闭 SDK

geSDK.close();

在应用关闭前调用，确保缓存数据不会丢失。

完整示例

const GEData = require("gravity-engine-sdk");

GEData.enableLog(true);

const access_token = "your_access_token";
const SERVER_URL = `https://backend.gravity-engine.com/event_center/api/v1/event/collect/?access_token=${access_token}`;
const clientId = "your_client_id";

const geSDK = GEData.initWithDebugMode(SERVER_URL, {});

// const geSDK = GEData.initWithBatchMode(SERVER_URL, {
//     batchSize: 20,
//     compress: true // enable compress or not, default true
// });
//
// const geSDK = GEData.initWithAsyncBatchMode(SERVER_URL, {
//     batchSize: 20,
//     compress: true // enable compress or not, default true
// });

(function () {
    for (let i = 0; i < 100; i++) {
        const eventName = "$AdClick";
        let properties = {
            idx: i,
            prop_double: 134.1,
            product_list: ['a', 'a', 'b'],
        };
        geSDK.track(eventName, clientId, properties, function (e) {
            console.log('in cb');
            if (e) {
                console.log("exception: ", e);
            }
        });
    }

})();

(function () {
    geSDK.userSetOnce(clientId, {
        prop_set_once: 'once',
    }, function (e) {
        console.log('in cb');
        if (e) {
            console.log("exception: ", e);
        }
    });

    geSDK.userSet(clientId, {
        user_name: 'xxx',
    }, function (e) {
        console.log('in cb');
        if (e) {
            console.log("exception: ", e);
        }
    });

    geSDK.userUnset(clientId, {
        user_name: '',
    }, function (e) {
        console.log('in cb');
        if (e) {
            console.log("exception: ", e);
        }
    });

    geSDK.userIncrement(clientId, {
        TotalRevenue: 100,
    }, function (e) {
        console.log('in cb');
        if (e) {
            console.log("exception: ", e);
        }
    });

    geSDK.userAppend(clientId, {
        prop_list_type: ['a', 'a', 'b']
    }, function (e) {
        console.log('in cb');
        if (e) {
            console.log("exception: ", e);
        }
    });

    geSDK.userUniqAppend(clientId, {
        prop_list_type: ['a', 'a', 'b', 'c']
    }, function (e) {
        console.log('in cb');
        if (e) {
            console.log("exception: ", e);
        }
    });

    geSDK.userMax(clientId, {
        TotalRevenue: 1000,
    }, function (e) {
        console.log('in cb');
        if (e) {
            console.log("exception: ", e);
        }
    });

    geSDK.userMin(clientId, {
        TotalRevenue: 1,
    }, function (e) {
        console.log('in cb');
        if (e) {
            console.log("exception: ", e);
        }
    });

    geSDK.userDel(clientId, function (e) {
        console.log('in cb');
        if (e) {
            console.log("exception: ", e);
        }
    });

})();

geSDK.flush();
geSDK.close();

最佳实践

  1. 异常处理：对所有 SDK 调用进行异常捕获。
  2. 资源清理：在应用关闭前调用 close() 方法。
  3. 属性命名：使用有意义的属性名称，保持一致性。
  4. 数据类型：确保属性值类型符合预期，避免类型错误。

故障排除

常见问题

  1. 初始化问题：检查 ACCESS_TOKEN 和服务器地址是否正确
  2. 数据格式：验证事件属性数据类型是否符合要求
  3. 性能问题：避免频繁调用 flush() 方法

Lua SDK

介绍 Gravity Engine Lua SDK 的环境要求、安装初始化、事件追踪和用户属性管理，并提供参数说明与代码示例。

PHP SDK

介绍 Gravity Engine PHP SDK 的环境要求、安装初始化、事件追踪和用户属性管理，并提供参数说明与代码示例。

本页内容

概述1. 安装集成2. 初始化配置基础配置核心功能1. 事件追踪2. 用户属性管理设置用户属性（覆盖）初始化用户属性（仅首次设置有效）累加用户属性用户属性取最大值用户属性取最小值用户属性追加用户属性去重追加重置用户属性清空用户属性3. 数据管理立即上报数据关闭 SDK完整示例最佳实践故障排除常见问题