Skip to main content

Others

Custom App Version Name​

By default, the Tingyun App SDK uses the application's "versionName" as the version number for upload. If you need to customize the version number, you can configure it by calling this interface during SDK initialization.

  • Related interface
/**
 *@param versionName Up to 64 characters, supports Chinese, English, numbers, and underscores
 */ 
NBSAppAgent.setVersionName(String versionName);
  • Code example
public class MyApplication extends Application {
    @Override
    public void onCreate() {  
        NBSAppAgent.setLicenseKey("AppKey")
        .setVersionName("v2.11.1") // Set version name during SDK initialization
        .start(this.getApplicationContext());
    }
}

Custom Channel​

Developers can set a custom channel name when initializing the Tingyun App SDK.

  • Related interface
/**
 * @param channelID Channel ID.
 * Can consist of letters, numbers, underscores, hyphens, spaces, parentheses, and other visible characters. Chinese characters are allowed but not recommended due to possible encoding issues.
 * Leading and trailing spaces are not allowed. Do not use all numbers as the channel ID. Up to 256 characters.
 */
NBSAppAgent.setChannelID(String channelID);
  • Code example
public class MyApplication extends Application {
    @Override
    public void onCreate() {  
        NBSAppAgent.setLicenseKey("AppKey")
        .setChannelID("AppStore") // Set channel during SDK initialization
        .start(this.getApplicationContext());
    }
}

Set Geolocation Information​

You can set latitude and longitude via the interface to accurately obtain the device's geolocation.

  • Related interface
/**
 * @param lat Latitude
 * @param lng Longitude
 */
NBSAppAgent.setLatLng(double lat, double lng);
  • Code example
public class MyApplication extends Application {
    @Override
    public void onCreate() {  
        NBSAppAgent.setLatLng(39.936846, 116.39277); // Set latitude and longitude
    }
}

Enable SDK Log​

After calling the interface, SDK INFO logs can be printed.

  • Related interface
/**
 * @param enable Defaults to false. Set to true to output logs
 */
NBSAppAgent.setLogEnable(boolean enable);
  • Code example
public class MyApplication extends Application {
    @Override
    public void onCreate() {  
        NBSAppAgent.setLicenseKey("AppKey")
        .start(this.getApplicationContext());
    
        NBSAppAgent.setLogEnable(true); // Set to true to output logs
    }
}

Collect Data Only in Main Process​

By default, the App SDK collects data from all processes during Application initialization. You can also set it to collect data only from the main process.

  • Related interface
/**
 * @param enable Defaults to false. Set to true to collect data only from the main process
 */
NBSAppAgent.withOnlyMainProcEnabled(boolean enable);
  • Code example
public class MyApplication extends Application {
    @Override
    public void onCreate() {  
        NBSAppAgent.setLicenseKey("AppKey")
        .withOnlyMainProcEnabled(true) // Set to true to collect data only from the main process
        .start(this.getApplicationContext());
    }
}

Enable Module Function Switches on First Launch​

For compatibility reasons, on first launch the SDK only enables all function modules in debug mode, and only enables the crash module in non-debug mode. You can enable the SDK's module switches through the following interface.

  • Related interface
/**
 * @param option Switch status value
 * The SDK defines the following switches:
 * Network data collection
 * NBSAppAgent.HTTP_NETWORK_ENABLED = 1;
 * UI data collection (startup, page, operation data)
 * NBSAppAgent.UI_ENABLED = 2;
 * Crash data collection
 * NBSAppAgent.CRASH_ENABLED = 4;
 * WebView data collection
 * NBSAppAgent.WEBVIEW_ENABLED = 8;
 * Socket Hook
 * NBSAppAgent.SOCKET_DATA_ENABLED = 16;
 * Cross-app functionality
 * NBSAppAgent.CROSS_APP_ENABLED = 32;
 * ANR data collection
 * NBSAppAgent.ANR_ENABLED = 64;
 * User action data collection
 * NBSAppAgent.USER_ACTION_ENABLED = 128;
 * CDN data collection
 * NBSAppAgent.CDN_ENDBLED = 256;
 * Video recording collection
 * NBSAppAgent.RECORD_ENDBLED = 512;
 * Full Trace collection
 * NBSAppAgent.ALL_TRACE_COLLECT_ENDBLED = 1024;
 * Violent click collection
 * NBSAppAgent.VIOLENCE_ENDBLED = 2048;
 * Log recall
 * NBSAppAgent.LOG_MODULE_ENABLED = 4096;
 * OOM collection
 * NBSAppAgent.OOM_MODULE_ENABLED = 8192;
 * Battery consumption collection
 * NBSAppAgent.BATTERY_MODULE_ENABLED  = 16384;
 * Battery error collection
 * NBSAppAgent.BATTERY_ERROR_ENABLED = 32768;
 * Network content collection
 * NBSAppAgent.RECORD_NETWORK_ENABLE = 65536;
 * CPU metrics and exception collection
 * NBSAppAgent.CPU_MODULE_ENABLED = 131072;
 * FPS collection
 * NBSAppAgent.FPS_MODULE_ENABLED = 262144;
 */  
NBSAppAgent.setStartOption(int option);
  • Code example
public void onCreate() {  
    NBSAppAgent.setLicenseKey("AppKey")
    .setStartOption(NBSAppAgent.HTTP_NETWORK_ENABLED | NBSAppAgent.UI_ENABLED | NBSAppAgent.CRASH_ENABLED)
    // Enable network, UI, and crash data collection on first launch
    .start(this.getApplicationContext());
}

Get Tingyun Device ID​

When the application is launched for the first time, the Tingyun server will issue a deviceId to identify the device. You can obtain the Tingyun deviceId value through the interface.

  • Related interface
/**
 * @return Returns the Tingyun device ID
 */
NBSAppAgent.getTingyunDeviceId()
  • Code example
public void onCreate() {  
  String tingYunDid = NBSAppAgent.getTingyunDeviceId();
  if(!TextUtils.isEmpty(tingYunDid)){
    // If deviceId does not exist, returns null. It is recommended to check for null before use
    ...
  }
}

Ignore Tingyun Scheme Configuration​

The Tingyun Scheme is used for visual naming of pages and operations collected by the SDK, which may trigger a popup requesting floating window permission. For scheme-based app activation, we recommend defining a separate scheme. If other apps use the Tingyun scheme to launch your app, you can use setIngoreScheme() to specify the scheme to be ignored by the SDK for visual configuration.

  • Related interface
/**
 * @param scheme The scheme value to ignore
 */
NBSAppAgent.setIngoreScheme(String scheme);
  • Code example
public class MyApplication extends Application {
    @Override
    public void onCreate() {  
        NBSAppAgent.setLicenseKey("AppKey")
        .setIngoreScheme("tingyun.1234") // Set the scheme to ignore during SDK initialization
        .start(this.getApplicationContext());
    }
}

Set okhttp3.EventListener Switch​

If your project integrates OkHttp 3.11.0 or above, the Tingyun SDK will use EventListener to collect data. If your project also sets an EventListener, the Tingyun SDK will record the previous EventListener when replacing it. When the SDK receives related callbacks, it will call back to your project's EventListener, so it will not affect your own EventListener receiving callbacks. If you do not want the Tingyun SDK to set EventListener, you can disable it using setOkhttpTcpListener().

  • Related interface
/**
 * @param isSetListener Defaults to true. Set to false to disable EventListener
 */
NBSAppAgent.setOkhttpTcpListener(boolean isSetListener);
  • Code example
public class MyApplication extends Application {
    @Override
    public void onCreate() {  
        NBSAppAgent.setLicenseKey("AppKey")
        .setOkhttpTcpListener(false) // Disable EventListener during SDK initialization
        .start(this.getApplicationContext());
    }
}

Get Project's EventListener​

If your project integrates OkHttp 3.11.0 or above, the Tingyun SDK will use EventListener to collect data. If your project also sets an EventListener, the Tingyun SDK will record the previous EventListener when replacing it. If you use reflection to get the EventListener in your code, it will return Tingyun's EventListener. You can get your own EventListener using NBSHttpTcpListener.getListener().

  • Related interface
/**
 * @return Returns the EventListener replaced by the SDK
 */
NBSHttpTcpListener.getListener()
  • Code example
// HttpEventListener represents the project's own EventListener
HttpEventListener listener = null;
try {
    if (mEventListenerField == null) {
        synchronized (this) {
            if (mEventListenerField == null) {
                Class<?> realCallClass = call.getClass();
                mEventListenerField = realCallClass.getDeclaredField("eventListener");
                mEventListenerField.setAccessible(true);
            }
        }
    }
    // listener = (HttpEventListener) mEventListenerField.get(call); // Directly casting to your own listener after instrumentation will throw an exception
    EventListener eventListener = (EventListener) mEventListenerField.get(call); // Get EventListener via reflection
    if (eventListener instanceof HttpEventListener) { // Check if eventListener is your own or Tingyun's
        listener = (HttpEventListener) eventListener; // If it's your own listener, cast to your own
    } else if (eventListener instanceof NBSHttpTcpListener) {
        NBSHttpTcpListener nbsHttpTcpListener = (NBSHttpTcpListener) eventListener; // If it's Tingyun's listener, cast to Tingyun
        listener = (HttpEventListener) nbsHttpTcpListener.getListener(); // Use Tingyun's getListener() to return your own listener
    }
} catch (Exception e) {
}

Set OAID​

If your project integrates the OAID SDK, you can pass the obtained OAID to the Tingyun SDK to generate a device ID.

Note: On some devices, due to privacy issues, OAID may return a fixed value such as 00000000-0000-0000-0000-000000000000 or 0000000000000000000000000000000000000000000000000000000000000000. Do not pass such fixed values to the SDK.

  • Related interface
/**
 * @param oaid The OAID to pass in
 */
NBSAppAgent.setOaidData(String oaid)
  • Code example
NBSAppAgent.setOaidData("e6ee0f4b6b67cf8b")

Filter okhttp3.ResponseBody Instrumentation​

To collect download byte counts, the Tingyun SDK replaces okhttp3.ResponseBody. If your code performs type conversion on response.body(), it may trigger an exception. You can filter okhttp.ResponseBody instrumentation using setOkhttpResponseBodyFilter().

  • Related interface
/**
 * @param className The full class name of the ResponseBody to filter. This class must not be obfuscated.
 */
NBSAppAgent.setOkhttpResponseBodyFilter(String className)
  • Code example
NBSAppAgent.setOkhttpResponseBodyFilter("com.xxx.okhttptest.util.ProgressResponseBody") // Pass the full class name of the ResponseBody to filter

Disable HarmonyOS Device Recognition​

On HarmonyOS devices, the SDK sets the operating system to "HarmonyOS" during initialization. You can disable HarmonyOS recognition using this interface, after which the SDK will set the OS to "Android".

If you are using a private platform, confirm whether the platform supports HarmonyOS device recognition. If not, call isHarmonyOs(false).

  • Related interface
/**
 * @param isHarmonyOS Whether to enable HarmonyOS device recognition, defaults to true
 */
NBSAppAgent.isHarmonyOs(boolean isHarmonyOS)
  • Code example
NBSAppAgent.setLicenseKey("AppKey").setRedirectHost("Host")
.isHarmonyOs(false) // Disable HarmonyOS device recognition
.start(getApplicationContext());

Get User Identifier​

By adding a "user identifier", you can search for specific users' performance issues on the Tingyun reporting platform.

  • Related interface
/**
 * @param userIdentifier Up to 256 characters, supports Chinese, English, numbers, and underscores, but cannot contain spaces or other escape characters
 */
NBSAppAgent.setUserIdentifier(String userIdentifier);
  • Code example
public class MainActivity extends Activity {  
    public void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        String userIdentifier = getUserID();
        NBSAppAgent.setLicenseKey("AppKey")
        .start(this.getApplicationContext());
        // The user identifier can be an email, phone number, or any information that identifies the user, e.g., xxx@tingyun.com
        NBSAppAgent.setUserIdentifier(userIdentifier);
      }
}

SDK Data Transmission Using SM Encryption​

The SDK supports SM (Chinese National Standard) encryption for data transmission. Call this interface to enable SM encryption.

Note:

  • SM encryption is only supported on Android 6.0 and above. After enabling SM encryption, SDKs on Android 5.x and below will not collect data.

  • To enable SM encryption, you must integrate bcpkix-jdk15to18-version.jar and bcprov-jdk15to18-version.jar.

  • The server must also enable SM encryption.

  • Related interface
/**
 * param isEncryptionRequired Defaults to false. Set to true to enable SM encryption
 */
NBSAppAgent.encryptionRequired(boolean isEncryptionRequired)
  • Code example
NBSAppAgent.setLicenseKey("AppKey").setRedirectHost("Host")
.encryptionRequired(true) // Enable SM encryption
.start(this.getApplicationContext());

Disable Mobile Operator Collection​

The SDK collects mobile network operator information via TelephonyManager.getSimOperator(). You can control whether to collect this information by calling isOperatorCollect() during SDK initialization.

  • Related interface
/**
 * @param isCollect Defaults to true. Set to false to disable operator collection
 */
NBSAppAgent.isOperatorCollect(boolean isCollect)
  • Code example
NBSAppAgent.setLicenseKey("AppKey").setRedirectHost("Host")
.isOperatorCollect(false) // Disable operator collection
.start(this.getApplicationContext());

Set Cell Data Collection Switch​

You can control whether to enable cell data collection via setCellCollectEnabled(). This interface must be called before SDK initialization.

As of version 2.17.4, cell data collection is disabled by default.

  • Related interface
/**
 * @param enable Cell data collection switch, defaults to true. Set to false to disable collection
 */
NBSAppAgent.setCellCollectEnabled(boolean enable);
  • Code example
NBSAppAgent.setCellCollectEnabled(false); // Disable cell data collection

Set Business Line Name​

Use the "set business line" interface to distinguish crashes, ANRs, and network errors by business line for more granular performance data.

  • Related interface
/**
 * @param key: Fixed as bname
 * @param value: The business line name to set
 */
NBSAppArent.setBusinessLine(String key, String value);
  • Code example
public class MyApplication extends Application {
    @Override
    public void onCreate() {
        NBSAppArent.setBusinessLine("bname", "ShoppingCart");
    }
}