服务端集成 · 事件采集 · Csharp SDK

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

概述

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

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

1. 环境要求

.NET：10+

2. 安装集成

资源下载：下载地址

自动集成

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net10.0</TargetFramework>
    <ImplicitUsings>enable</ImplicitUsings>
    <Nullable>enable</Nullable>
  </PropertyGroup>
  <ItemGroup>
    <PackageReference Include="Newtonsoft.Json" Version="13.0.3" />
  </ItemGroup>
</Project>

手动集成

导入文件：

using GEData.Analytics;

3. 初始化配置

基础配置

using GEData.Analytics;

namespace DemoNamespace
{
    class Program
    {
        static void Main(string[] args)
        {
            GELog.Enable = true;

            String serverUrl = "https://backend.gravity-engine.com/event_center/api/v1/event/collect/?access_token=___XXX___";
            // GEAnalytics ge = new(new GEBatchConsumer(serverUrl, 200, 2, true, false));
            GEAnalytics ge = new(new GEDebugConsumer(serverUrl));
        }
    }
}

核心功能

1. 事件追踪

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

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

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

for (int i = 0; i < 3; i = i + 1)
{
    Dictionary<string, Object> dic2 = new Dictionary<string, object>();
    dic2.Add("idx", i);
    dic2.Add("create_date", Convert.ToDateTime("2019-7-8 20:23:22"));
    dic2.Add("group_no", "T22514");
    dic2.Add("group_title", "title");
    dic2.Add("group_purchase_id", 438);
    dic2.Add("group_order_is_vip", 3);
    dic2.Add("service_id", 0);
    ge.Track(client_id, "$AdClick", dic2);
}

事件的名称是字符串类型。
Key 为该属性的名称，为字符串类型。
Value 为该属性的值，支持字符串、数字、布尔、时间、对象、对象组、数组。

2. 用户属性管理

设置用户属性（覆盖）

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

Dictionary<string, Object> dic3 = new Dictionary<string, object>();
dic3.Add("user_name", "xxx");
ge.UserSet(client_id, dic3);

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

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

Dictionary<string, Object> dic5 = new Dictionary<string, object>();
dic5.Add("prop_set_once", "xxx");
ge.UserSetOnce(client_id, dic5);

累加用户属性

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

Dictionary<string, Object> dic4 = new Dictionary<string, object>();
dic4.Add("TotalRevenue", 648);
ge.UserIncrement(client_id, dic4);

用户属性取最大值

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

Dictionary<string, Object> dic4_2 = new Dictionary<string, object>();
dic4_2.Add("TotalRevenue", 1000);
ge.UserMax(client_id, dic4_2);

用户属性取最小值

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

Dictionary<string, Object> dic4_1 = new Dictionary<string, object>();
dic4_1.Add("TotalRevenue", 1);
ge.UserMin(client_id, dic4_1);

用户属性追加

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

Dictionary<string, object> dictionary = new Dictionary<string, object>();
List<string> list6 = new List<string>();
list6.Add("a");
list6.Add("b");
list6.Add("a");
dictionary.Add("prop_list_type", list6);
ge.UserAppend(client_id, dictionary);

用户属性去重追加

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

Dictionary<string, object> dictionary = new Dictionary<string, object>();
List<string> list6 = new List<string>();
list6.Add("a");
list6.Add("b");
list6.Add("a");
dictionary.Add("prop_list_type", list6);

ge.UserUniqAppend(client_id, dictionary);

重置用户属性

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

List<string> list = new List<string>();
list.Add("user_name");
ge.UserUnSet(client_id, list);

清空用户属性

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

ge.UserDelete(client_id);

3. 数据管理

立即上报数据

ge.Flush();

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

关闭 SDK

ge.Close();

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

完整示例

using GEData.Analytics;

namespace DemoNamespace
{
    class Program
    {
        static void Main(string[] args)
        {
            GELog.Enable = true;

            String serverUrl = "https://backend.gravity-engine.com/event_center/api/v1/event/collect/?access_token=___XXX___";
            // GEAnalytics ge = new(new GEBatchConsumer(serverUrl, 200, 2, true, false));

            GEAnalytics ge = new(new GEDebugConsumer(serverUrl));

            String client_id = "_test_client_id_0";

            for (int i = 0; i < 30; i = i + 1)
            {
                Dictionary<string, Object> dic2 = new Dictionary<string, object>();
                dic2.Add("idx", i);
                dic2.Add("create_date", Convert.ToDateTime("2019-7-8 20:23:22"));
                dic2.Add("group_no", "T22514");
                dic2.Add("group_title", "title");
                dic2.Add("group_purchase_id", 438);
                dic2.Add("group_order_is_vip", 3);
                dic2.Add("service_id", 0);
                ge.Track(client_id, "$AdClick", dic2);
            }

            Dictionary<string, Object> dic3 = new Dictionary<string, object>();
            dic3.Add("user_name", "xxx");
            ge.UserSet(client_id, dic3);

            Dictionary<string, Object> dic4 = new Dictionary<string, object>();
            dic4.Add("TotalRevenue", 648);
            ge.UserIncrement(client_id, dic4);

            Dictionary<string, Object> dic4_1 = new Dictionary<string, object>();
            dic4_1.Add("TotalRevenue", 1);
            ge.UserMin(client_id, dic4_1);

            Dictionary<string, Object> dic4_2 = new Dictionary<string, object>();
            dic4_2.Add("TotalRevenue", 1000);
            ge.UserMax(client_id, dic4_2);

            Dictionary<string, Object> dic5 = new Dictionary<string, object>();
            dic5.Add("prop_set_once", "xxx");
            ge.UserSetOnce(client_id, dic5);

            List<string> list2 = new List<string>();
            list2.Add("user_name");
            ge.UserUnSet(client_id, list2);

            Dictionary<string, object> dictionary = new Dictionary<string, object>();
            List<string> list6 = new List<string>();
            list6.Add("a");
            list6.Add("b");
            list6.Add("a");
            dictionary.Add("prop_list_type", list6);
            ge.UserAppend(client_id, dictionary);

            ge.UserUniqAppend(client_id, dictionary);

            ge.UserDelete(client_id);

            ge.Flush();
            ge.Close();

        }
    }
}

Csharp SDK

概述