• SDK版本：当前SDK版本在不断迭代发布中，您可前往Git开源页面查看各端的SDK版本情况，推荐使用最新版本SDK。本文中的代码示例以一个版本号作为示例，您实际使用时，需根据使用的实际SDK版本修改其中的版本号。
• 下载SDK包：集成SDK时，如果您需要手动引入SDK，需前往Git开源页面下载对应版本的SDK包。

1.1 版本支持须知

目前仅支持32位和64位的Windows平台。

1.2 获取appid

在开始集成前，首先需要在集团中拥有一个应用，进行SDK集成前，您需要获取对应应用的appid信息。

• SaaS-云原生场景下，您可以在「项目中心」->「项目管理」->「项目详情」-> 接入应用的「详情」->「应用ID」中可查看您的appid，详情请参见项目管理。
  
• SaaS-非云原生场景下，您可以在「应用列表」-> 接入应用的「详情」->「应用ID」中可查看您的appid，详情请参见应用列表。
  

1.3 获取数据上送地址

进行数据接入上报时，您需要根据当前的环境类型和端类型确认您的数据上报地址，如果上报地址设置错误，后续会导致您无法查询到上报的数据。

SaaS-云原生 & SaaS-非云原生

私有化环境

私有化部署场景下，您需要获取部署私有化环境时，自行规划配置的数据上送地址。如您不清楚此地址，请联系您的项目经理或客户成功经理。

2.1 下载SDK

请前往Windows SDK包下载页面获取对应版本的SDK包。

2.2 SDK文件说明

请下载对应平台的SDK文件压缩包，解压后会出现applogrs.hpp、applogrs.dll、applogrs.dll.lib三个文件：

• applogrs.hpp：公开的接口头文件。
• applogrs.dll：动态链接库的运行时加载的dll文件。
• applogrs.dll.lib：applogrs.dll文件对应的函数导出声明文件。

2.3 集成场景1：C++版本

将下载的SDK文件复制到项目中，需要注意平台架构的文件放在项目的对应平台构建目录中。

2.3.1添加附加库目录

修改项目属性-配置属性-连接器-常规-附加库目录，增加applogrs.dll文件所在的目录。

2.3.2 添加函数导出文件

修改项目属性-配置属性-连接器-常规-附加依赖项，增加文本内容applogrs.dll.lib。

2.3.3 添加头文件

修改项目属性-配置属性-C/C++-附加包含目录，增加applogrs.hpp文件所在的目录。

2.3.4 代码中引入头文件

在需要调用SDK的代码文件头部，显示的引入applogrs.hpp头文件：

#include "applogrs.hpp"

2.4 集成场景2： C# 版本

2.4.1 添加目录

将applogrs.dll添加至项目可访问的路径下，比如放在项目的输出目录（'bin/'）文件夹下。

2.4.2 添加动态导入

在项目中，使用DllImport的方法，引入dll文件，并定义需要使用的方法，dll文件里导出的方法，具体可查看applogrs.hpp文件。

using System;
using System.Runtime.InteropServices;

// 这里只展示其中一个方法，其他方法类似。
[DllImport("applogrs.dll", CharSet = CharSet.Ansi, CallingConvention = CallingConvention.Cdecl)] 
public static extern void AppLog_init_rangers(string appid, string channel);

说明：
初始化SDK后会采集系统的部分设备信息，包括设备序列号、操作系统软件版本等。

3.1 初始化SDK

SDK会缓存埋点等数据，为保障数据不丢失，需要将数据持久化到本地磁盘中。需要提前准备可以写入数据的文件目录（SDK不会自动创建目录）。

• C++:

  // 1. 设置数据缓存目录，需要已经存在的有访问和写入数据权限的文件目录
  applog::AppLog_setDbDir("/xx/xx");
  // 2. 设置域名，支持私有化部署
  char* domain = "https://xxx.xxx.xxx";
  applog::AppLog_setCustomDomain(domain); // 服务域名
  // 3. 初始化SDK，需要提前准备好appId和appChannel（appChannel一般为发布的渠道名）
  applog::AppLog_init_rangers(appId, appChannel);
  

• C#:

  [DllImport("applogrs.dll", CallingConvention = CallingConvention.Cdecl, CharSet = CharSet.Ansi)]
   public static extern void AppLog_setDbDir(string path);
   [DllImport("applogrs.dll", CallingConvention = CallingConvention.Cdecl, CharSet = CharSet.Ansi)]
   public static extern void AppLog_setCustomDomain(string host);
   [DllImport("applogrs.dll", CharSet = CharSet.Ansi, CallingConvention = CallingConvention.Cdecl)] 
   public static extern void AppLog_init_rangers(string appid, string channel);
   
  // 1. 设置数据缓存目录，需要已经存在的有访问和写入数据权限的文件目录
  AppLog_setDbDir("/xx/xx");
  // 2. 设置域名，支持私有化部署
  string domain = "https://xxx.xxx.xxx";
  AppLog_setCustomDomain(domain); // 服务域名
  // 3. 初始化SDK，需要提前准备好appId和appChannel（appChannel一般为发布的渠道名）
  AppLog_init_rangers(appId, appChannel);
  

4.1 统计日活

在应用打开和应用即将被关闭时，需要手动触发SDK的应用启动接口和SDK的应用退出接口。只有触发了应用启动和应用退出才会上报日活数据。

• 在应用打开后调用：

  • C++:

    applog::AppLog_launch(); // 应用启动
    

  • C#:

    [DllImport("applogrs.dll", CallingConvention = CallingConvention.Cdecl)]
    public static extern void AppLog_launch();
    AppLog_launch(); // 应用启动
    

• 在应用关闭时调用：

  • C++:

    applog::AppLog_terminate(); // 应用退出
    

  • C#:

    [DllImport("applogrs.dll", CallingConvention = CallingConvention.Cdecl)]
    public static extern void AppLog_terminate();
    AppLog_terminate(); // 应用退出
    

4.2 上报埋点

支持在任意位置采集埋点，埋点内容包含埋点名称和埋点参数两部分，接口示例：

• C++:

  // 这里采集一个埋点
  // 参数说明：
  // 参数1：埋点名称，不能为空
  // 参数2：参数的json字符串，不能为空，且必须为合法的json字符串
  applog::AppLog_onEvent("my_click", "{\"my_param\": 1}");
  

• C#:

  using Newtonsoft.Json;
  [DllImport("appLogrs.dll", CallingConvention = CallingConvention.Cdecl, CharSet = CharSet.Ansi)]
  public static extern void AppLog_onEvent(string event, string params);
  
  public class Person 
   { 
       public string Name { get; set; } 
       public int Age { get; set; } 
   }
   Person person = new Person 
   { 
       Name = "John Doe", 
       Age = 30, 
   };
   string jsonString = JsonConvert.SerializeObject(person);
  // 这里采集一个埋点
  // 参数说明：
  // 参数1：埋点名称，不能为空
  // 参数2：参数的json字符串，不能为空，且必须为合法的json字符串
  // 上面创建对象的方法只是示例，任何创建对象并转为json字符串的方法都可以。
   AppLog_onEvent("my_click", jsonString)
  
  

4.3 公共属性

如需在每个事件中都包括某属性，可通过公共属性设置，无需在每个事件中重复设置。公共属性只需设置一次，即可包括在所有代码埋点事件中。

• 设置公共属性：

  • C++:

    // 添加公共属性
    // 参数说明：
    // 参数1：属性名
    // 参数2：属性值（仅支持字符串）
    applog::AppLog_addCustomHeader("header", "value");
    

  • C#：

    [DllImport("applogrs.dll", CallingConvention = CallingConvention.Cdecl, CharSet = CharSet.Ansi)]
    public static extern void AppLog_addCustomHeader(string key, string value);
    // 添加公共属性
    // 参数说明：
    // 参数1：属性名
    // 参数2：属性值（仅支持字符串）
    AppLog_addCustomHeader("header", "value");
    

• 移除公共属性：

  • C++:

    // 移除公共属性
    // 参数说明：
    // 参数1：属性名
    applog::AppLog_removeCustomHeader("header");
    

  • C#:

    [DllImport("applogrs.dll", CallingConvention = CallingConvention.Cdecl, CharSet = CharSet.Ansi)]
    public static extern void AppLog_removeCustomHeader(string key);
    // 移除公共属性
    // 参数说明：
    // 参数1：属性名
    AppLog_removeCustomHeader("header");
    

如您的产品中有账户体系，请在用户登录后立即设置 uuid，以保证用户登录前后口径一致性。从v1.5.2开始，切换uuid的时候默认会重新发起设备注册请求获取新的设备ID。

• C++:

  // 设置用户的uuid
  applog::AppLog_setUserUniqueId("your_user_unique_id");
  
  // 用户多口径配置
  applog::AppLog_setUserUniqueIdAndType("your_user_unique_id", "your_user_type");
  

• C#:

  [DllImport("applogrs.dll", CallingConvention = CallingConvention.Cdecl, CharSet = CharSet.Ansi)]
  public static extern void AppLog_setUserUniqueId(string key);
  [DllImport("applogrs.dll", CallingConvention = CallingConvention.Cdecl, CharSet = CharSet.Ansi)]
  public static extern void AppLog_setUserUniqueIdAndType(string key, string type);
  // 设置用户的uuid
  AppLog_setUserUniqueId("your_user_unique_id");
  // 用户多口径配置
  AppLog_setUserUniqueIdAndType("your_user_unique_id", "your_user_type");
  

6.1 打印日志

如果需要查看SDK内部运行日志，需要调用日志开关接口切换日志打印：

• C++:

  // 配置日志开关
  // 参数说明：
  // 参数1：1-开启日志打印 0-关闭日志打印
  applog::AppLog_setLogEnabled(1);
  

• C#:

  [DllImport("applogrs.dll", CallingConvention = CallingConvention.Cdecl)]
   public static extern void AppLog_setLogEnabled(uint enabled);
   
  // 配置日志开关
  // 参数说明：
  // 参数1：1-开启日志打印 0-关闭日志打印
  AppLog_setLogEnabled(1);
  

默认会使用系统的OutputDebugStringW接口打印日志，如果需要自定义配置日志打印，可以参考下面的接口提供日志打印回调：

v1.5.2+支持

• C++:

  void onPrintLog(char *message) {
       cout << "applog sdk log: " << message << "" << endl;
  }
  applog::AppLog_setLogger(onPrintLog);
  

• C#:

  [DllImport("appLogrs.dll", CallingConvention = CallingConvention.Cdecl)]
  public static extern void AppLog_setLogger(LogFunction logger);
  
  public delegate void LogFunction(IntPtr message);
  
  static void onPrintLog(IntPtr messagePtr)
  {
      string message = Marshal.PtrToStringAnsi(messagePtr);
      Console.WriteLine("applog log:" + message);
  }
  
  LogFunction logDelegate = new LogFunction(onPrintLog);
  AppLog_setLogger(logDelegate);