调试模式

1. 适用场景

为了更加方便使用者调试代码和调整数据格式，我们为各个语言的 SDK 以及 LogAgent、BatchImporter 等导入工具，增加了调试模式的选项，主要用于：

1. 在开发人员调试代码和数据时使用；

2. 以同步、阻塞的方式，向后端发送数据；部分语言由于语言特性，这一机制可能略有不同；

3. 实时地展示服务端的校验结果，当校验失败时，不仅仅会展示具体的错误原因，并且会以抛异常等形式（具体实现取决于具体语言），显示地提醒使用者；

4. 对于校验成功的数据，在导入辅助工具中，可以实时看到最终入库的的各条数据的各个字段的值与类型。

请注意，不要在生产环境或正式发布的 App 中使用 Debug 模式。

2. 使用

2.1 SDK 使用调试模式

各个语言的 SDK 使用调试模式，主要是在初始化时，加上相关的参数。由于不同语言的实现机制不同，我们分别进行说明。

2.1.1 Python SDK

在 Python SDK 中，使用调试模式，需要初始化一个专门的 DebugConsumer 对象，然后用这个 DebugConsumer 对象来初始化对应的 SensorsAnalytics 对象。

DebugConsumer 的构造函数的定义如下：

def __init__(self, url_prefix, write_data=True, request_timeout=None):
        """
        初始化Consumer
        :param url_prefix: 神策分析用于数据接收的 URL
        :param write_data: 发送过去的数据是真正写入，还是仅仅进行检查
        :param request_timeout:请求的超时时间,单位毫秒
        :return:
        """

各个参数含义在注释上已经写明了。特别需要强调几点：

1. url_prefix：该参数与其他 Consumer 一样，为神策分析用于数据接收的 URL

2. write_data：这个参数默认为 True，也即发送过去的数据会真正地写入后端；如果这个参数设置为 False，则说明数据只发送过去进行校验，不会真正地写入。

2.1.2 PHP SDK

PHP SDK 的调试模式的使用方式和 Python SDK 类似，也是构造一个 DebugConsumer 的对象，然后用它来初始化 SensorsAnalytics 对象。

DebugConsumer 的构造函数如下：

    /**
     * DebugConsumer constructor,用于调试模式.
     * 具体说明可以参照: http://www.sensorsdata.cn/manual/debug_mode.html
     * 
     * @param string $url_prefix 神策分析用于数据接收的 URL
     * @param bool $write_data 是否把发送的数据真正写入
     * @param int $request_timeout 请求服务器的超时时间,单位毫秒.
     * @throws SensorsAnalyticsDebugException
     */
    public function __construct($url_prefix, $write_data = True, $request_timeout = 1000)

各个参数的含义与 Phthon SDK 基本一致，不再赘述。

2.1.3 Java SDK

在 Java SDK 中使用调试模式，需要初始化一个专门的 DebugConsumer 对象，然后用这个 DebugConsumer 对象来初始化对应的 SensorsAnalytics 对象。DebugConsumer 的构造函数的定义如下：

    /**
     * DebugConsumer，用于调试模式
     *
     * @param serverUrl 神策分析采集数据的 URL
     * @param writeData 是否把发送的数据真正写入神策分析
     */
    public DebugConsumer(final String serverUrl, final boolean writeData)

各个参数的含义与 Phthon SDK 基本一致，不再赘述。

2.1.4 iOS SDK

iOS SDK 提供 Debug 模式，用于校验数据导入，用户使用时，请小心该设置，不要带到正式发布的 App 中。它将可能影响用户体验。

使用 SDK 版本高于 1.10.22 用户，可以使用「调试模式动态配置」进行调试模式的配置 查看使用说明

iOS SDK 中通过 SensorsAnalyticsSDK 的参数初始化，指定 Debug 模式:

/**
 * @abstract
 * 根据传入的所部署的 SensorsAnalytics 服务器的 URL，返回一个<code>SensorsAnalyticsSDK</code>的单例
 *
 * @param serverURL 神策分析用数据接收的 URL
 * @param launchOptions launchOptions
 * @param debugMode 是否打开 Debug 模式
 *
 * @return 返回的单例
 */
+ (SensorsAnalyticsSDK *)sharedInstanceWithServerURL:(nonnull NSString *)serverURL
                                        andLaunchOptions:(NSDictionary * _Nullable)launchOptions
                                        andDebugMode:(SensorsAnalyticsDebugMode)debugMode;

其中 SensorsAnalyticsDebugMode 为枚举类型，定义如下:

/**
 * @abstract
 * Debug 模式，用于检验数据导入是否正确。该模式下，事件会逐条实时发送到 SensorsAnalytics，并根据返回值检查
 * 数据导入是否正确。
 *
 * @discussion
 * Debug 模式的具体使用方式，请参考:
 *  http://www.sensorsdata.cn/manual/debug_mode.html
 *
 * Debug 模式有三种选项:
 *   SensorsAnalyticsDebugModeOff - 关闭 DEBUG 模式
 *   DebugOnly - 打开 DEBUG 模式，但该模式下发送的数据仅用于调试，不进行数据导入
 *   DebugAndTrack - 打开 DEBUG 模式，并将数据导入到 SensorsAnalytics 中
 */
typedef NS_ENUM(NSInteger, SensorsAnalyticsDebugMode) {
    SensorsAnalyticsDebugOff,
    SensorsAnalyticsDebugOnly,
    SensorsAnalyticsDebugAndTrack,
};

SensorsAnalyticsDebugOnly 模式下，数据不会真正写入后端，只用于调试数据导入。 SensorsAnalyticsDebugAndTrack 下，数据不仅用于调试，也会真正导入后端。

一个使用 Debug 模式初始化 SensorsAnalyticsSDK 的样例如下：

    [SensorsAnalyticsSDK sharedInstanceWithServerURL:@"http://sa_host:8006/sa"
                                        andLaunchOptions:launchOptions
                                        andDebugMode:SensorsAnalyticsDebugOnly];

它初始化 SensorsAnalyticsSDK 实例，并定义 Debug 模式为 SensorsAnalyticsDebugOnly，校验埋点的事件，但事件不会真正导入后端。

2.1.5 Android SDK

Android SDK 提供 Debug 模式，用于校验数据导入，用户使用时，请小心该设置，不要带到正式发布的 App 中。它将可能影响用户体验。

使用 SDK 版本高于 3.0.3 用户，可以使用「调试模式动态配置」进行调试模式的配置 查看使用说明

Android SDK 的调试模式在 SensorsDataAPI 实例初始化时设置，SensorsDataAPI初始化有五个参数，最后一个 debugMode 用于指定 Debug 模式的类型，其中 DebugMode 为枚举类型，初始化方法和 DebugMode 的定义如下

public class SensorsDataAPI {

  /**
   * Debug 模式，用于检验数据导入是否正确。该模式下，事件会逐条实时发送到 SensorsAnalytics，并根据返回值检查
   * 数据导入是否正确。
   * <p/>
   * Debug 模式的具体使用方式，请参考:
   * http://www.sensorsdata.cn/manual/debug_mode.html
   * <p/>
   * Debug 模式有三种：
   * DEBUG_OFF - 关闭 DEBUG 模式
   * DEBUG_ONLY - 打开 DEBUG 模式，但该模式下发送的数据仅用于调试，不进行数据导入
   * DEBUG_AND_TRACK - 打开 DEBUG 模式，并将数据导入到 SensorsAnalytics 中
   */
  public enum DebugMode {
    DEBUG_OFF(false, false),
    DEBUG_ONLY(true, false),
    DEBUG_AND_TRACK(true, true);
    // ...
  }

  /**
   * 初始化并获取 SensorsDataAPI 单例
   *
   * @param context App 的Context
   * @param serverURL 神策分析用于收集事件的服务地址
   * @param debugMode Debug 模式
   *
   * @return an instance of SensorsDataAPI associated with your project
   */
  public static SensorsDataAPI sharedInstance(Context context, String serverURL,
      DebugMode debugMode) {
    // ...
  }

  // ...
}

当 Debug 模式设为 DEBUG_ONLY 时，数据不会真正写入后端，只用于调试数据导入。 当 Debug 模式设置为DEBUG_AND_TRACK 时，数据不仅用于调试，也会真正导入后端。

一个使用 Debug 模式初始化 SensorsDataAPI 的样例如下：

SensorsDataAPI sa = SensorsDataAPI.sharedInstance(
          this,
          "http://sa_host:8006/sa",
          SensorsDataAPI.DebugMode.DEBUG_ONLY);

它初始化 SensorsDataAPI 实例，并定义 Debug 模式为 DEBUG_ONLY，校验埋点的事件，但事件不会真正导入后端。

2.2 LogAgent 和 BatchImporter 使用调试模式

LogAgent 和 BatchImporter 的调试模式主要是对数据正确性的校验，详情请参考：

• BatchImporter 使用说明 中 4.2.校验数据模式
• LogAgent 使用说明 中 5.使用 LogAgent 校验数据
• FormatImporter 使用说明 中 4.2.公共参数