Skip to main content

Debug mode

Last updated 10/03/2026

Debug mode is designed to help developers debug data reporting and is intended only for data validation during the integration phase. Note that Debug mode may affect data collection quality and app stability. Don't use it in the production environment.

1. Enable Debug mode​

（1）Android SDK

Android SDK instances support three run modes, defined in TDConfig. Use the DEBUG or DEBUG_ONLY mode:

/**
 * Instance run mode. Defaults to NORMAL mode.
 */
public enum ModeEnum {
    /* Normal mode: data is stored in the cache and reported according to a caching strategy */
    NORMAL,
    /* Debug mode: data is reported one record at a time. When a problem occurs, the user is notified through logs and exceptions */
    DEBUG,
    /* Debug Only mode: data is only validated and isn't stored */
    DEBUG_ONLY
}

For example, the following code initializes the SDK in Debug mode:

// Get the TDConfig instance
TDConfig config = TDConfig.getInstance(mContext, TA_APP_ID, TA_SERVER_URL);
// Set the run mode to Debug mode
config.setMode(TDConfig.ModeEnum.DEBUG);
// Initialize the SDK
instance = ThinkingAnalyticsSDK.sharedInstance(config);

（2）iOS SDK

iOS SDK instances support three run modes, defined in TDConfig. Use the DEBUG or DEBUG_ONLY mode:

/**
Debug mode

- ThinkingAnalyticsDebugOff : Default. Debug mode is off
*/
typedef NS_OPTIONS(NSInteger, ThinkingAnalyticsDebugMode) {
    /**
     Default. Debug mode is off
     */
    ThinkingAnalyticsDebugOff      = 0,

    /**
     Enables Debug_only mode: data is only validated and isn't stored
     */
    ThinkingAnalyticsDebugOnly     = 1 << 0,

    /**
     Debug mode: data is reported one record at a time. When a problem occurs, the user is notified through logs and exceptions
     */
    ThinkingAnalyticsDebug         = 1 << 1
};

For example, the following code initializes the SDK in Debug mode:

// Get the TDConfig instance
TDConfig *config = [[TDConfig alloc] init];
// Set the run mode to Debug mode
config.debugMode = ThinkingAnalyticsDebug;
// Initialize the SDK
ThinkingAnalyticsSDK *instance = [ThinkingAnalyticsSDK startWithAppId:@"YOUR_APPID" withUrl:@"YOUR_SERVER_URL" withConfig:config];

(3) Other clients

2. Add a Debug device​

To prevent Debug mode from going live in the production environment, Debug mode can only be enabled on specified devices. Only devices that have Debug mode enabled on the client and are configured in Tracking - Debugger can use Debug mode.

You can get the device ID in either of the following two ways:

  • Client logs: after the SDK finishes initializing, it prints the device DeviceId
  • Call getDeviceId to get the device ID

4. Instructions​

After a device is connected, the data it reports is displayed in the data list in real time. For data that fails validation, the specific error reason is shown to help you troubleshoot.

  1. Settings: Click to switch the currently connected device or add a new device.
  2. Pause loading: If you want to stay on a specific event during testing for further handling, click Pause loading. Data generated while paused (such as configured auto-collected events) is indicated above the data table. Click Start loading to switch back to real-time loading.
  3. Search event: Search and filter to display only specified events or user properties.
  4. Clear list: Click Clear list to clear the current data list. Cleared data is no longer displayed. Clearing only clears the logs and doesn't delete events that have already been stored.
  5. Tracking-plan comparison: If you maintained tracking plan information in the Tracking - Tracking Plan module before testing data, you can turn on Tracking-plan comparison to see the differences between your test data and the tracking plan during testing, so you can adjust your tracking code in time.

After you turn on tracking-plan comparison, the error reasons also include error information based on the comparison with the tracking plan (preset properties are not compared). Possible errors include:

  • The event isn't in the tracking plan
  • Some properties are reported but aren't in the tracking plan
  • Some properties are missing, that is, they're in the tracking plan but aren't reported
  • The type of a reported property doesn't match the property type in the tracking plan

4. Best practices​

4.1 Use Debug mode to debug tracking​

Debug mode is ideal for verifying that tracking is correct when you add new tracking events. Before testing, get the device's device ID #device_id in the AE SDK and add the device in Debug mode. Then trigger the tracking events in the IDE or on your own device, and watch the data displayed in Debug mode, focusing mainly on whether the data is uploaded and whether it is correct.

4.2 Enable tracking-plan comparison​

After you upload a plan on the Tracking Plan page, you can turn on Tracking-plan comparison to see the differences between your test data and the tracking plan during testing, so you can adjust your tracking code in time. Note that the validation results of this feature don't include validation of preset properties.

Was this page helpful?
On this page