Parfait SDK是APMPlus PC监控平台的官方SDK，提供跨平台C++ API，是动态库，可监控应用线上稳定性问题。

步骤一：接入SDK

Native App接入

1. 下载SDK。

   平台	架构	产物
   Windows (MSVC)	MT： x86 x64	parfait-win_1.4.3.1.zip 未知大小
   	MD (VS2019) ： x86 x64 说明 所有的业务都能接入MT，MD只有>=VS2019的业务方可接入。 MD抓的崩溃类型更多，如果能接入就优先选择接入MD。	parfait-win_1.4.3.1.zip 未知大小
   macOS (Clang)	x86_64 arm64 fat binray(x86_64+arm64)	parfait-mac_1.4.3.1.zip 未知大小

   SDK说明：

   • 支持平台：Windows(32/64）、macOS(x86_64/arm64)

     说明

     • 所有的业务都能接入MT，MD只有VS2019的业务方能接入。
     • MD支持监控更多的崩溃类型，如果可以建议优先选择接入MD。
   • 支持功能：PV/UV统计、埋点、Alog日志、Crash监控、自定义文件上报
   • 产物形式：mac为Framework动态库，Windows为/MT和 /MD(VS2019)动态库

2. 初始化SDK。

   1. 链接动态库。

   2. 添加头文件依赖。

      // Windows直接引入头文件
      #include "header/ParfaitConstants.h"
      #include "header/ParfaitEnvBase.h"
      #include "header/ParfaitInstance.h"
      #include "header/ParfaitRecorderBase.h"
      #include "header/ParfaitWrapperBase.h"
      #include "header/ParfaitLogRecorderBase.h"
      
      // mac以framework形式引入
      #include <Parfait/ParfaitConstants.h>
      #include <Parfait/ParfaitEnvBase.h>
      #include <Parfait/ParfaitInstance.h>
      #include <Parfait/ParfaitRecorderBase.h>
      #include <Parfait/ParfaitLogRecorderBase.h>
      #include <Parfait/ParfaitWrapperBase.h>
      

   3. 开启调试。
      接入初期可以先打开调试模式，Parfait debug log会输出在控制台。上线后请务必关闭调试模式。

      /**
       * （可选）是否输出parfait内部的debug log，未设置默认为不输出
       * @param  is_debug true输出，false不输出
       */
      static void ParfaitGlobalEnvBuilderBase::SetIsDebug(bool is_debug);
      

   4. 创建并初始化Wrapper。
      Wrapper代表一个Parfait实例，初始化之后才能接入功能。一般情况下，持有一个单例wrapper指针即可。

      // 创建parfait wrapper
      ParfaitWrapperBase* CreateParfaitWrapper();
      
      示例代码：
      static parfait::ParfaitWrapperBase* parfait_wrapper_ptr = nullptr;
      

   5. 设置Wrapper所需Global Env。
      创建Global Env builder，填写参数；初始化Global Env；销毁Global Env builder。
      单进程内同aid下的所有wrapper共享Global Env中的参数。

      // 创建全局环境变量builder
      ParfaitGlobalEnvBuilderBase* CreateParfaitGlobalEnvBuilder(int64_t aid);
      
      // 基于全局环境变量builder初始化全局环境变量
      void ParfaitWrapperBase::InitGlobalEnv(ParfaitGlobalEnvBuilderBase &global_env_builder);
      
      // 销毁全局环境变量builder
      void DestroyParfaitGlobalEnvBuilder(ParfaitGlobalEnvBuilderBase* &builder);
      

      Global Env参数说明：

      参数	是否必填	含义	默认值
      RootPathName	必填	绝对路径。自定义日志、自定义事件、alog数据存储的根目录。UTF8编码。	-
      Did	必填	设备ID。	-
      Uid	必填	用户ID。	-
      Host	必填	Host域名。	https://apmplus.volces.com
      AppToken	必填	APMPlus平台项目详情中显示的Token。1.4.3.0版本后支持。 未设置，数据不会上传。设置错误，上报返回401。	-
      AppVersion	必填	App版本号。	-
      AppMiniorVersion	选填	App小版本号。	-
      Channel	必填	应用渠道。	-
      BuildID	选填	编译ID。	-
      SessionID	选填	Session ID。	-
      ReportInterval	选填	单位ms，自定义日志、自定义事件、性能监控、网络监控的循环上报间隔时间，不得低于10s。	60s
      InterruptUploadIfExit	选填	SDK destroy时是否中断自定义事件、日志、性能数据、网络监控数据上传。默认中断，如果为'false'，SDK将会把当前正在上传的任务执行完后再退出。	true
      UploadCrashImmediately	选填	发生崩溃后是否立即上传崩溃。默认立即上传，如果设置为禁止立即上传后，应用重启后再上传。	true
      UseMainProcessParamAsChildProcessExceptionUploadParam	选填	允许已接入崩溃监控，但未初始化Parfait SDK的子进程使用主进程的参数上报崩溃。一旦子进程初始化Parfait SDK，将会使用他们自己的参数。必须在主进程初始化崩溃监控前设置。子进程调用此API无效。	子进程使用自己的参数上报报告
      IrreplaceableExceptionMonitor	选填	调用后，崩溃监控不可被其他模块的崩溃监控顶替。默认可被顶替。必须在主进程初始化崩溃监控前设置。子进程调用此API无效。1.4.2.0及之后的版本支持此参数。	崩溃监控可被顶替
      IgnoreExceptionInChildProcess	选填	调用后，子进程崩溃不生成崩溃报告。默认生成崩溃报告。此接口仅在mac平台上生效，必须在主进程初始化崩溃监控前设置。子进程调用此API无效。1.4.2.0及之后版本支持此参数。	mac子进程生成崩溃报告
      AllowExceptionMonitorToBeReplaced	废弃	1.4.2.0及之后的版本废弃此参数。	-

      注意

      如果不注入Host和AppToken信息，SDK不能正常初始化，数据无法上报。AppToken信息，详情请参见如何查询AppID和AppToken？。

   6. 设置Wrapper所需Instance Env。
      创建Instance Env builder，填写参数；初始化Instance Env；销毁Instance Env builder。
      Instance Env是每个Wrapper独有的参数。

      // 创建实例环境变量builder
      ParfaitEnvBuilderBase* CreateParfaitEnvBuilder(int64_t aid, const char* instance_name);
      
      // 基于builder初始化实例环境变量
      void ParfaitWrapperBase::InitInstanceEnv(parfait::ParfaitEnvBuilder &env_builder)
      
      // 销毁实例环境变量builder
      void DestroyParfaitEnvBuilder(ParfaitEnvBuilderBase* &builder);
      

      Instance Env说明：

      参数	是否必填	含义	默认值
      Pid	必填	进程ID。	-
      ProcessName	必填	进程名，支持中文，用于平台各类数据筛选（“进程类型”）。	-
      RecordContext	选填	自定义日志、自定义事件的Context信息，用于单点展示以及事件过滤，初始化后不可更改。	-
      CrashContext	选填	崩溃的Context信息，用于崩溃列表页面的过滤，初始化后可更改。	-

      示例代码：

      #define AID 4444
      #define ROOT_PATH_NAME "C:\\Users\\Admin\\Documents\\"
      
      static parfait::ParfaitWrapperBase* parfait_wrapper_ptr = nullptr;
      //static parfait::ParfaitWrapperBase* parfait_wrapper_ptr2 = nullptr;
      
      void InitParfaitGlobalEnv() {
          // 创建全局环境变量builder
          auto global_env_builder = parfait::CreateParfaitGlobalEnvBuilder(AID);
          // 设置全局环境参数值
          global_env_builder 
              ->SetRootPathName(ROOT_PATH_NAME) // UTF8编码
              .SetHost("https://apmplus.volces.com") 
              .SetAppToken("488e*********f55b") // 请查看平台项目信息获取
              .SetDid("12345") 
              .SetUid("1234")
              .SetAppVersion("1.0.0") 
              .SetChannel("app_store");
          // 初始化全局环境变量
          parfait_wrapper_ptr->InitGlobalEnv(*global_env_builder);
          // 参数已注入，销毁全局环境变量
          parfait::DestroyParfaitGlobalEnvBuilder(global_env_builder); 
      }
      void InitParfaitInstanceEnv(parfait::ParfaitWrapperBase* wrapper, const char* instance_name) {
          // 创建实例环境变量builder
          auto instance_env_builder = CreateParfaitEnvBuilder(AID, instance_name);
          // 设置实例环境参数值
          instance_env_builder->SetProcessName("main") //进程名，平台上可用“进程类型”筛选数据
                      .SetPid(std::to_string(getpid()).c_str()); // 必填
                      //.AddRecordContext("record_key", "record_value")//可选，注入额外信息
                      //.AddCrashContext("crash_key", "crash_value");//可选，注入额外信息
          // 初始化实例环境变量
          wrapper->InitInstanceEnv(*instance_env_builder);
          // 参数已注入，销毁实例环境变量
          parfait::DestroyParfaitEnvBuilder(instance_env_builder); 
      }
      
      void InitParfait() {
          // 输出parfait调试日志，默认不开启, 线上不要开启！
          parfait::ParfaitGlobalEnvBuilderBase::SetIsDebug(true);
          parfait_wrapper_ptr = parfait::CreateParfaitWrapper();
          InitParfaitGlobalEnv();
          InitParfaitInstanceEnv(parfait_wrapper_ptr, "instance1");
          //InitParfaitInstanceEnv(parfait_wrapper_ptr2, "instance1");
      }
      

Non-Native App接入

由于PC技术栈繁杂，为了更好的支持Electron、Flutter等业务接入Parfait SDK，Parfait提供了C Wrapper Demo，封装了主要功能，如初始化、崩溃监控、自定义事件、自定义日志、Alog日志和自定义文件上传功能，供业务接入参考。后续更新需要业务自行维护。

1. 下载安装CMake。

2. 下载Wrapper包parfait_c_wrapper.zip。
   

   

   parfait_c_wrapper.zip

   未知大小

   

3. 执行以下命令，解压后编译wrapper库。

   cd parfait_c_wrapper
   cmake -B"./output" && cmake --build "./output" --config Release
   

   说明

   mac产物为output目录下的libparfait_wrapper.dylib，win产物为output/Release目录下的parfait_wrapper.dll。

4. 同时链接wrapper库和Parfait SDK，通过wrapper库封装的C API去调用Parfait SDK接口。

   注意

   • 如果需要新增功能或者可更改的参数，直接修改parfait_wrapper.h和parfait_wrapper.cpp，再执行一次编译命令。
   • 如果仅需要升级SDK版本，不需要更改接口，可以将SDK二进制直接替换为最新版本，不需要重新编译，Parfait SDK ABI兼容。

步骤二：接入基础功能

PV/UV统计

• 功能介绍
  对应APMPlus上的PV/UV统计大盘展示，同时用于计算崩溃的影响用户率、影响用户数。注意，PV指的是Process View，进程的启动次数；UV指的是Unique Vistor，访问用户数。
• 使用场景
  初始化Parfait后，即可进行PV和UV的统计与上报。

/**
 * 启动pv/uv数据上报，用于统计pv/uv以及崩溃影响用户数，初始化完成后立即上报数据
 */
void ParfaitWrapperBase::LaunchReport();

// 调用例子：
// 1. sdk初始化完毕，得到本实例的wrapper
parfait_wrapper_ptr->LaunchReport();

（可选）启动间隔循环上传

• 功能介绍
  调用后Parfait会依据全局环境变量的Report Interval值开始间隔循环上报自定义日志/自定义事件/网络监控/性能监控数据。
• 使用场景
  如果有使用网络监控/性能监控这两个功能，或者写入了大量的自定义日志/自定义事件数据，那么业务方一定要调用这个接口，防止数据堆积在本地。
• 注意事项
  Parfait采用单进程单实例上报模式，因此只需要上报进程的上报实例调用一次即可，初始化完成后即可调用。此间隔循环上报除非Parfait退出，不然不会停止。

void ParfaitWrapperBase::Upload();
示例代码：
parfait_wrapper_ptr->Upload();

步骤三：接入其他功能

除了常用的功能外，SDK还支持一些增强功能。您可以根据业务需求，按照以下操作使用这些功能。

• 崩溃趋势
• 自定义事件/自定义日志
• 辅助文件上传
• Alog日志

步骤四：退出SDK

调用此接口后，所有Parfait实例都会销毁。

如果需要停止Parfait所有功能并回收内存，可以直接调用：

void DestroyParfaitWrapper(ParfaitWrapperBase* &wrapper);

示例代码：
parfait_wrapper_ptr->DestroyParfaitWrapper(parfait_wrapper_ptr);

步骤五：多进程接入

绝大部分情况下，一个wrapper以满足单进程所有需求。如多进程需要接入，可选择任选一个方案：

• 子进程像主进程一样接入Parfait SDK。
• 主进程再初始化一个用于代表子进程的wrapper。主进程和子进程通过IPC通信，传递数据。主进程往wrapper里面写数据。
• 更多复杂情况，可以在控制台发起工单。