Skip to main content
Version: 3.7.0

SDK API

I. Startup Configuration Interface​

Please obtain the <#Config Address#> and <#AppID#> from the platform. For the method to obtain them, refer to How to Query AppID and Config Address?. Please contact technical support if you have any questions.

BonreeSDK Startup Interface​

/// Start BonreeSDK
+ (void)startWithAppID:(NSString *)appID;
  • Interface Description
Parameter NameTypeDescription
appIDNSStringThe unique application ID generated by the Bonree SDK platform

  • Example

    Objective-C

    [BRSAgent startWithAppID:@"<#AppID#>"];

    Swift

    BRSAgent.startWithAppID("<#AppID#>")

Set Config Address​

Used by private cloud customers to set the config address for private deployment. This interface must be set before calling + startWithAppID:.

/// Set the Config address (Please set before starting BonreeSDK)
+ (void)setConfigAddress:(NSString *)configAddress;
  • Interface Description
Parameter NameTypeDescriptionParameter Constraints
configAddressNSStringPrivate cloud config addressString length must be greater than 0 and less than or equal to 2083, otherwise the interface call fails.

  • Example

    Objective-C

    [BRSAgent setConfigAddress:@"<#Config Address#>"];

    Swift

    BRSAgent.setConfigAddress("<#Config Address#>")

Set App Version​

The App version is obtained from the configuration file by default. If there is a need for active configuration, call the following interface to set the version information before calling + startWithAppID:.

/// Set the app version (Please set before starting BonreeSDK) Default gets the application's CFBundleShortVersionString
+ (void)setAppVersion:(NSString *)appVersion;
  • Interface Description
Parameter NameTypeDescriptionParameter Constraints
appVersionNSStringThe version information to be setString length must be greater than 0 and less than or equal to 64, otherwise the interface call fails.

  • Example

    Objective-C

    [BRSAgent setAppVersion:@"3.2.1"];

    Swift

    BRSAgent.setAppVersion("3.2.1")

Set Application Environment​

Use this interface to set the current application environment. This interface must be called before calling + startWithAppID:.

/// Set the application environment (Please set before starting BonreeSDK)
/// @param environment Application environment
+ (void)setAppEnvironment:(NSString *)environment;
  • Interface Description
Parameter NameTypeDescriptionParameter Constraints
environmentNSStringThe application environment to be setString cannot be empty or nil, otherwise the interface call is invalid.
String length must be greater than 0 and less than or equal to 256, otherwise the call is invalid. Allows Chinese characters, numbers, letters, colons, spaces, slashes, underscores, hyphens, periods, @, #, *, !

  • Example

    Objective-C

    [BRSAgent setAppEnvironment:@"xxx"];

    Swift

    BRSAgent.setAppEnvironment("xxxx")

Set Download Channel Name​

The channel name defaults to apple. If there is a need for active configuration, call the following interface to set the channel name before calling + startWithAppID:.

/// Set the channel identifier (Please set before starting BonreeSDK)
+ (void)setChannelID:(NSString *)channelID;
  • Interface Description
Parameter NameTypeDescriptionParameter Constraints
channelIDNSStringThe channel name to be setString length must be greater than 0 and less than or equal to 256, otherwise the interface call fails.

  • Example

    Objective-C

    [BRSAgent setChannelID:@"AppStore"];

    Swift

    BRSAgent.setChannelID("AppStore")

Set Custom Device ID​

The device ID (deviceID) is generated by the SDK by default and saved in the Keychain. If there is a need for active configuration, call the following interface to set the device ID before calling + startWithAppID:.

/// Configure a custom device deviceID (Please set before starting BonreeSDK)
+ (void)setDeviceID:(NSString *)deviceID;
  • Interface Description
Parameter NameTypeDescriptionParameter Constraints
deviceIDNSStringThe device ID to be setString length must be greater than 0 and less than or equal to 256, otherwise the call fails. Allows numbers, letters, colons, spaces, slashes, underscores, hyphens, periods, @

  • Example

    Objective-C

    [BRSAgent setDeviceID:@"0123456789"];

    Swift

    BRSAgent.setDeviceID("0123456789")

Set Continuous Frame Drop Time​

Set the continuous frame drop time required to determine stuttering. Call the following interface to set it before calling + startWithAppID:.

/// Set the continuous frame drop monitoring time (Please set before starting BonreeSDK)
+ (void)setDropFrameTime:(NSInteger)time;
  • Interface Description
Parameter NameTypeDescription
timeNSIntegerContinuous frame drop time (s), setting range (0, 30], default is 5s if not set)

  • Example

    Objective-C

    [BRSAgent setDropFrameTime:5];

    Swift

    BRSAgent.setDropFrameTime(5)

Set mPaaS Framework Usage Status​

Data acquisition and processing under the Ali mPaaS framework require special configuration. If this framework is used, set it to YES before calling + startWithAppID:. If not used, there is no need to call this setting interface.

/// Whether the mPaaS framework is used (Please set before starting BonreeSDK)
+ (void)useMpaas:(BOOL)used;
  • Interface Description
Parameter NameTypeDescription
usedBOOLWhether the mPaaS framework is used

  • Example

    Objective-C

    [BRSAgent useMpaas:YES];

    Swift

    BRSAgent.useMpaas(true)

Set Custom Business Fields in Request Headers​

If you need to obtain the values of custom fields related to business in the Http request headers, you can configure these fields to the SDK by calling this interface in the form of a string array. The relevant data will be displayed together with the corresponding network performance data for business differentiation by the customer. Call this setting interface before + startWithAppID:.

Usage scenario example: For the mobile gateway function under the mPaaS framework, business requests are distinguished by the Operation-Type field in the request header. Setting this field allows distinguishing performance data for different business requests.

/// Set custom business fields in the request headers
+ (void)setCustomBusinessHeaders:(NSArray<NSString *> *)headerArr;
  • Interface Description
Parameter NameTypeDescription
headerArrNSArrayArray of custom business fields in the request headers to be obtained (maximum 64 can be set)

  • Example

    Objective-C

    [BRSAgent setCustomBusinessHeaders:@[@"Operation-Type"]];

    Swift

    BRSAgent.setCustomBusinessHeaders(["Operation-Type"])

Custom Cold Launch End Time​

If you need to customize the end timing of a cold launch, you can use the following two interfaces to complete the custom functionality. The specific usage is as follows:

  1. Call the custom cold launch switch interface to enable the custom cold launch function. (This interface must be set before BonreeSDK starts.)
  2. Call the cold launch end interface at the desired timing to record the end of the cold launch.
/// Flag to use a custom cold launch end time (Must be set before BonreeSDK starts)
+ (void)useCustomLaunch:(BOOL)used;
/// Record the end of the cold launch
+ (void)recordCustomLaunchEnd;
  • Interface Description
Parameter NameTypeDescription
usedBOOLWhether to use a custom cold launch end time

  • Example

    Objective-C

    // Must be set before BonreeSDK starts
    [BRSAgent useCustomLaunch:YES];

    // ...

    // Call at the desired timing location
    [BRSAgent recordCustomLaunchEnd];

    Swift

    // Must be set before BonreeSDK starts
    BRSAgent.useCustomLaunch(true)

    // ...

    // Call at the desired timing location
    BRSAgent.recordCustomLaunchEnd()

Note: After enabling the custom cold launch function, if the record cold launch end interface is not called within 30 seconds, the cold launch monitoring process will be forcibly terminated.

Set SDK's Own Request Headers​

Call this interface to add information to the request headers of requests initiated by the SDK itself. This interface must be set before calling + startWithAppID:.

/// Set the Headers for requests within the SDK (Must be set before BonreeSDK starts)
+ (void)setSDKRequestHeaders:(NSDictionary<NSString *, NSString *> *)headers;
  • Interface Description
Parameter NameTypeDescription
headersNSDictionary<NSString *, NSString *>The key-value pairs of the request headers to be set (maximum 64 can be set, key length limit 256 characters, value length limit 512 characters)

  • Example

    Objective-C

    [BRSAgent setSDKRequestHeaders:@{
        @"headerKey0":@"headerValue0",
        @"headerKey1":@"headerValue1"
    }];

    Swift

    BRSAgent.setSDKRequestHeaders([
        "headerKey0":"headerValue0",
        "headerKey1":"headerValue1"
    ])

    Note: To use the interface for setting custom request information, the iOS client must be upgraded to version 7.3.2 or above.

Set Authentication Challenge Handler for Requests within the Probe​

+ (void)setAuthenticationChallengeHandler:(id (^)(NSURLSession *session, NSURLSessionTask *task, NSURLAuthenticationChallenge *challenge, void (^completionHandler)(NSURLSessionAuthChallengeDisposition , NSURLCredential * _Nullable)))authenticationChallengeHandler;
  • Interface Description
Parameter NameTypeDescription
authenticationChallengeHandlerid (^)(NSURLSession *session, NSURLSessionTask *task, NSURLAuthenticationChallenge *challenge, void (^completionHandler)(NSURLSessionAuthChallengeDisposition , NSURLCredential * _Nullable))Authentication challenge handler

Note: This interface must be called before the probe starts.

Sets a block that is used to handle authentication challenges for requests actively initiated within the probe.

When implementing the authentication challenge handler, you should first check the authentication method (challenge.protectionSpace.authenticationMethod) to decide whether to handle the authentication challenge yourself or let the probe handle it by default. If you want the probe to handle the authentication challenge, return @(NSURLSessionAuthChallengePerformDefaultHandling). For example, when the authentication method is NSURLAuthenticationMethodServerTrust, you might want the probe to handle certificate verification based on the security policy.

If you want to handle the challenge yourself, you have four options:

  1. Return nil, meaning you must call the completionHandler yourself.
  2. Return an NSError object. You must not call the completionHandler; the returned error object will be reflected in the task's completionHandler.
  3. Return an NSURLCredential. You must not call the completionHandler; the returned credential is used to satisfy the challenge.
  4. Return an NSNumber object wrapping an NSURLSessionAuthChallengeDisposition. Supported values are @(NSURLSessionAuthChallengePerformDefaultHandling), @(NSURLSessionAuthChallengeCancelAuthenticationChallenge), and @(NSURLSessionAuthChallengeRejectProtectionSpace). You must not call the completionHandler.

If you return anything else, an exception will be thrown.

  • Example

Objective-C

[BRSAgent setAuthenticationChallengeHandler:^id _Nonnull(NSURLSession * _Nonnull session,
NSURLSessionTask * _Nonnull task, NSURLAuthenticationChallenge * _Nonnull challenge, void
(^ _Nonnull completionHandler)(NSURLSessionAuthChallengeDisposition, NSURLCredential *
_Nullable)) {
    return @(NSURLSessionAuthChallengePerformDefaultHandling);
}];

Swift

BRSAgent.setAuthenticationChallengeHandler { _, _, _, _ in
    return URLSession.AuthChallengeDisposition.performDefaultHandling
}

Set Security Policy​

Note: This interface must be called before the probe starts.

Sets a security policy used to evaluate the server trust for secure connections of requests initiated by the probe. The probe uses the defaultPolicy by default.

+ (void)setSecurityPolicy:(BRSSecurityPolicy *)securityPolicy;
  • Interface Description
Parameter NameTypeDescription
keyBRSSecurityPolicySecurity policy
  • Example

Objective-C

BRSSecurityPolicy *policy = [BRSSecurityPolicy policyWithPinningMode:BRSSSLPinningModeCertificate];
policy.pinnedCertificates = [NSSet setWithObject:yourCerData]; // Replace yourCerData with your own certificate
[BRSAgent setSecurityPolicy:policy];

Swift

let policy = BRSSecurityPolicy(pinningMode: .certificate)
policy.pinnedCertificates = [yourCerData] // Replace yourCerData with your own certificate
BRSAgent.setSecurityPolicy(policy)

Enable Encryption and Set Encryption Information​

Call this interface to enable GM encryption for requests initiated by the SDK itself. This interface must be set before calling + startWithAppID:.

The encryption feature currently only supports the One platform. Before using this feature, please be sure to communicate with technical support or implementation to obtain the encryption Key, ensuring it is consistent with the platform configuration. Otherwise, it may cause exceptions in SDK data requests.

/// Set the key and identifier for the GM SM4 algorithm encryption/decryption
/// @param key          Key
/// @param identifier   Unique identifier corresponding to the key
+ (BOOL)enableGMSM4EncryptWithKey:(NSString *)key identifier:(NSString *)identifier;
  • Interface Description
Parameter NameTypeDescription
keyNSStringKey for GM encryption (Must be 16 bytes long. Do not use special characters < > & ' " %)
identifierNSStringUnique identifier corresponding to the key (Length limit 1-256 characters, only letters, numbers, underscore _, and hyphen - are allowed)

  • Example

    Objective-C

    [BRSAgent enableGMSM4EncryptWithKey:@"A key that meets the above restrictions" identifier:@"An identifier that meets the above restrictions"];

    Swift

    BRSAgent.enableGMSM4Encrypt(withKey: "A key that meets the above restrictions", identifier: "An identifier that meets the above restrictions")

    Note: To use the GM encryption interface, the iOS client must be upgraded to version 8.3.0 or above.

Set Ignore SIGPIPE​

Note: This interface must be called before the probe starts.

Set to ignore SIGPIPE.

By default, the probe captures SIGPIPE crashes.

After setting to ignore SIGPIPE, the probe will actively set the SIGPIPE handling method to SIG_IGN. You must check the return values of send() and write() in your code and handle the disconnection error properly when errno is EPIPE.

At the same time, you should be aware that the signal handler may be overwritten.

+ (void)ignoreSIGPIPE;

  • Example

    Objective-C

    [BRSAgent ignoreSIGPIPE];

    Swift

    BRSAgent.ignoreSIGPIPE()

Crash Callback Interface​

Set up a crash callback interface to retrieve crash information when the application crashes, in conjunction with the summaryOfCrashReportWithEventID: interface.

Note: When a crash occurs, the application is in an unstable and fragile state. Theoretically, the code executed should be async-safe. Avoid calling this method unless necessary.

+ (void)setCrashCallback:(void(^)(NSString *eventID))crashCallback;

  • Example Objective-C

    [BRSAgent setCrashCallback:^(NSString * _Nonnull eventID) {
      NSDictionary *summary = [BRSAgent summaryOfCrashReportWithEventID:eventID];
      // ...
    }];

    Swift

    BRSAgent.setCrashCallback { eventID in
      let summary = BRSAgent.summaryOfCrashReport(withEventID: eventID);
      // ...
    }

Start Session Replay Upload​

When the session replay module is enabled, the probe initiates session replay data upload based on the configuration by default. When the probe has not started uploading session replay data, calling this interface can immediately enable the session replay data upload function.

Note: For the same session, this interface only needs to be called once.

+ (void)startSessionReplayUpload;

  • Example Objective-C

    [BRSAgent startSessionReplayUpload];

    Swift

    BRSAgent.startSessionReplayUpload()

II. Data Acquisition Interface​

Get Device ID​

By default, the device's unique ID is generated and persistently maintained internally by BonreeSDK, used to identify the device that generated various performance data. We provide an interface to obtain this device ID to support requirement scenarios such as autonomous correlation of monitoring data at the device dimension.

/// Get the device's deviceID
+ (NSString *)deviceID;
  • Interface Description
Return TypeDescription
NSStringThe device ID generated in the SDK. If set beforehand, returns the set value.

  • Example

    Objective-C

    NSString *deviceID = [BRSAgent deviceID];

    Swift

    let deviceID = BRSAgent.deviceID()

Get SDK Version​

/// Get the SDK's version number
+ (NSString *)SDKVersion;
  • Interface Description
Return TypeDescription
NSStringThe SDK's version number

  • Example

    Objective-C

    NSString *version = [BRSAgent SDKVersion];

    Swift

    let version = BRSAgent.sdkVersion()

III. Custom Functionality Interface​

Custom User Information​

BonreeSDK supports setting user-related information to fulfill requirement scenarios where performance data needs to be associated with actual users.

There are two ways to set user information:

1. Set User ID, identifying the user with a string. Interface as follows:​

/// Set User ID
+ (void)setUserID:(nullable NSString *)userID;
  • Interface Description
Parameter NameTypeDescriptionParameter Constraints
userIDNSStringUser IDCan be empty or nil.
String length less than or equal to 256, call is invalid if exceeded. Allows Chinese characters, numbers, letters, colons, spaces, slashes, underscores, hyphens, periods, @, #, *, !

  • Example

    Objective-C

    [BRSAgent setUserID:@"user-id"];

    Swift

    BRSAgent.setUserID("user-id")

2. Set user additional information in Key-Value form.​

This interface is deprecated, please use the setUserExtraInfo: interface.

/// Set additional information
+ (void)setExtraInfo:(nullable NSDictionary <NSString *, id>*)extraInfo __attribute__((deprecated(" Use setUserExtraInfo: instead.")));
  • Interface Description
Parameter NameTypeDescriptionParameter Constraints
extraInfoNSDictionaryUser additional information. Value restricted to NSString or NSNumber types.Map can be empty or an empty collection.
Length after converting to JSON must be within 7000 characters, otherwise the interface call fails.

  • Example

    Objective-C

    [BRSAgent setExtraInfo:@{@"id":@"123456", @"name":@"Tom"}];

    Swift

    BRSAgent.setExtraInfo(["id":"123456", "name":"Tom"])

3. Set User Additional Information​

+ (void)setUserExtraInfo:(NSDictionary<NSString *, id>*)extraInfo;

  • Interface Description

    Parameter NameTypeDescriptionParameter Constraints
    extraInfoNSDictionaryUser additional informationThe number of valid key-value pairs is limited to 64; if exceeded, only 64 are taken.
    Key is limited to a string with length (0, 256].
    Value is restricted to non-empty strings, NSNumber, NSDate. String length exceeding 512 will be truncated.

  • Example

    Objective-C

    [BRSAgent setUserExtraInfo:@{@"name": @"Jack"}];

    Swift

    BRSAgent.setUserExtraInfo(["name": "Jack"])

4. Add User Additional Information​

+ (void)addUserExtraInfoWithKey:(NSString *)key value:(id)value;

  • Interface Description

    The constraints for key and value in this interface are the same as those in the setUserExtraInfo: interface.

  • Example

    Objective-C

    [BRSAgent addUserExtraInfoWithKey:@"height" value:@(17)];

    Swift

    BRSAgent.addUserExtraInfo(withKey: "age", value: 23)
    BRSAgent.addUserExtraInfo(withKey: "location", value: "earth")

5. Remove User Additional Information​

+ (void)removeUserExtraInfoWithKey:(NSString *)key;

  • Interface Description

    The constraint for key in this interface is the same as that in the setUserExtraInfo: interface.

  • Example

    Objective-C

    [BRSAgent removeUserExtraInfoWithKey:@"name"];

    Swift

    BRSAgent.removeUserExtraInfo(withKey: "location")

6. Accumulate User Additional Information​

+ (void)increaseUserExtraInfoWithKey:(NSString *)key value:(NSNumber *)value;

  • Interface Description

    Parameter NameTypeDescriptionParameter Constraints
    keyNSStringKeyConstraints are the same as those in the setUserExtraInfo: interface
    valueNSNumberValueRestricted to NSNumber type

  • Example

    Objective-C

    [BRSAgent increaseUserExtraInfoWithKey:@"height" value:@(3)];

    Swift

    BRSAgent.increaseUserExtraInfo(withKey: "age", value: 1)

Custom Event Attributes​

1. Add Event Common Attributes (a set)​

+ (void)addEventAttributes:(NSDictionary<NSString *, id> *)attributes local:(BOOL)local;

  • Interface Description

    Parameter NameTypeDescriptionParameter Constraints
    attributesNSDictionaryEvent common attributesThe number of valid key-value pairs is limited to 64; if exceeded, only 64 are taken.
    Key is limited to a string with length (0, 256].
    Value is restricted to non-empty strings, NSNumber, NSDate. String length exceeding 512 will be truncated.
    localBOOLWhether to persist to local storageAttributes persisted to local storage will take effect automatically upon the next application startup. Attributes not persisted are only valid in the current process.

  • Example

    Objective-C

    [BRSAgent addEventAttributes:@{@"a": @1} local:YES];

    Swift

    BRSAgent.addEventAttributes(["a": 1], local: false)

Add Event Common Attribute (single)​

+ (void)addEventAttributeWithKey:(NSString *)key value:(id)value local:(BOOL)local;

Calling this interface is equivalent to calling addEventAttributes:local:.

The constraints for key and value, and the role of local in this interface are the same as those in the addEventAttributes:local: interface.

  • Example

    Objective-C

    [BRSAgent addEventAttributeWithKey:@"b" value:@2 local:NO];

    Swift

    BRSAgent.addEventAttribute(withKey: "b", value: 2, local: false)

2. Remove Event Common Attributes​

+ (void)removeEventAttributeWithKeys:(NSArray<NSString *> *)keys;

  • Interface Description

    Parameter NameTypeDescriptionParameter Constraints
    keysNSArrayArray elements are the keys of the event common attributes to be removedThe constraints for elements in the array are the same as those for the key in the addEventAttributes:local: interface

    Calling this interface will remove event common attributes from both memory and local storage (if present).

  • Example

    Objective-C

    [BRSAgent removeEventAttributeWithKeys:@[@"b"]];

    Swift

    BRSAgent.removeEventAttribute(withKeys: ["b"])

3. Remove All Event Common Attributes​

+ (void)removeAllEventAttributes;

Remove all event common attributes (including local ones).

  • Example

    Objective-C

    [BRSAgent removeAllEventAttributes];

    Swift

    BRSAgent.removeAllEventAttributes()

Custom Exception​

Call the interface and pass the corresponding parameters to complete the statistical function for custom exception data.

/// Custom exception collection
+ (void)setCustomExceptionWithType:(NSString *)exceptionType
                           causeBy:(NSString * _Nullable)causedBy
                         errorDump:(NSString * _Nullable)errorDump;
  • Interface Description
Parameter NameTypeDescriptionParameter Constraints
exceptionTypeNSStringException type. Required parameter, call is invalid if empty or nil.String length must be greater than 0 and less than or equal to 256, otherwise the interface call fails.
causedByNSStringException causeCan be empty or nil.
String length less than or equal to 512, excess truncated.
errorDumpNSStringException stack traceWill be truncated if exceeding 10000 characters

  • Example

    Objective-C

    [BRSAgent setCustomExceptionWithType:@"Custom exception type"
                                 causeBy:@"Caused by customer."
                               errorDump:@"Custom error dump 0\nCustom error dump 1"];

    Swift

    BRSAgent.setCustomExceptionWithExceptionType("Custom exception type",
                                                 causeBy: "Caused by customer.",
                                                 errorDump: "Custom error dump 0\nCustom error dump 1")

Note: Even if the correct crash stack trace is passed in the custom exception interface, the platform will not perform symbol resolution for the crash stack trace.

Custom View​

Call the interface and pass the corresponding parameters to complete the statistical function for custom view data.

/// Custom View - Mark view start (called in pair with the view end method)
///     General calling location: viewWillAppear or viewDidAppear
+ (void)setCustomPageStartWithName:(NSString *)pageName
                         pageAlias:(nullable NSString *)pageAlias;
/// Custom View - Mark view end (called in pair with the view start method)
///     General calling location: viewWillDisappear or viewDidDisappear
+ (void)setCustomPageEndWithName:(NSString *)pageName
                       pageAlias:(nullable NSString *)pageAlias;
  • Interface Description
Parameter NameTypeDescriptionParameter Constraints
pageNameNSStringPage name. Required parameter, call is invalid if empty or nil.String length must be greater than 0 and less than or equal to 256, otherwise the interface call fails.
pageAliasNSStringPage aliasCan be empty or nil.
String length less than or equal to 256, excess truncated.

  • Example

    Objective-C

    - (void)viewWillAppear:(BOOL)animated {
        [super viewWillAppear:animated];

        [BRSAgent setCustomPageStartWithName:@"page01" pageAlias:@"Home Page"];
    }

    - (void)viewWillDisappear:(BOOL)animated {
        [super viewWillDisappear:animated];
        
        [BRSAgent setCustomPageEndWithName:@"page01" pageAlias:@"Home Page"];
    }

    Swift

    override func viewWillAppear(_ animated: Bool) {
        super.viewWillAppear(animated)
        
        BRSAgent.setCustomPageStartWithName("page01", pageAlias: "Home Page")
    }
      
    override func viewWillDisappear(_ animated: Bool) {
        super.viewWillDisappear(animated)
        
        BRSAgent.setCustomPageEndWithName("page01", pageAlias: "Home Page")
    }

Note: The start and end recording interfaces for custom views must be called in pairs, and the pageName for the same view must be consistent, in order to correctly count and report a complete custom view data.

Custom View Title​

Custom titles require the controller to conform to the protocol and implement the method in the protocol to complete the custom view title functionality.

@protocol BRSViewControllerCustomizable <NSObject>

@optional
/// Custom page title [Controller implements the protocol]
/// @return Custom page title
- (NSString *)brsViewTitle;

@end
  • Protocol Description
Method NameReturn TypeDescriptionParameter Constraints
brsViewTitleNSStringPage title name.Type must be NSString, other types are invalid.

  • Example

    Objective-C

    @interface Controller()<BRSViewControllerCustomizable>
    ...

    - (NSString *)brsViewTitle {
        return @"Title";
    }

    ...
    @end

    Swift

    extension Controller: BRSViewControllerCustomizable {
        func brsViewTitle() -> String? {
            return "Title"
        }
    }

Note: If the controller conforms to the protocol and implements the protocol method, the return value of the method will be used as the view title. Even if the method returns empty content, it will be used.

Custom Event (Full Version)​

Call the start and end interfaces respectively and pass the corresponding parameters to complete the statistical function for custom event data and event duration.

/// Custom event start
+ (void)setCustomEventStartWithID:(NSString *)eventID
                             name:(nullable NSString *)eventName;

+ (void)setCustomEventStartWithID:(NSString *)eventID
                             name:(nullable NSString *)eventName
                            label:(nullable NSString *)eventLabel;

+ (void)setCustomEventStartWithID:(NSString *)eventID
                             name:(nullable NSString *)eventName
                            label:(nullable NSString *)eventLabel
                            param:(nullable NSString *)param;

+ (void)setCustomEventStartWithID:(NSString *)eventID
                             name:(nullable NSString *)eventName
                            label:(nullable NSString *)eventLabel
                            param:(nullable NSString *)param
                             info:(nullable NSDictionary<NSString *, NSString *> *)info;
/// Custom event end
+ (void)setCustomEventEndWithID:(NSString *)eventID
                           name:(nullable NSString *)eventName;

+ (void)setCustomEventEndWithID:(NSString *)eventID
                           name:(nullable NSString *)eventName
                          label:(nullable NSString *)eventLabel;

+ (void)setCustomEventEndWithID:(NSString *)eventID
                           name:(nullable NSString *)eventName
                          label:(nullable NSString *)eventLabel
                          param:(nullable NSString *)param;

+ (void)setCustomEventEndWithID:(NSString *)eventID
                           name:(nullable NSString *)eventName
                          label:(nullable NSString *)eventLabel
                          param:(nullable NSString *)param
                           info:(nullable NSDictionary<NSString *, NSString *> *)info;
  • Interface Description
Parameter NameTypeDescriptionParameter Constraints
eventIDNSStringEvent ID. Required parameter, call is invalid if empty or nil.String length must be greater than 0 and less than or equal to 256, otherwise the interface call fails.
eventNameNSStringEvent nameCan be empty or nil.
String length less than or equal to 256, excess truncated.
eventLabelNSStringEvent labelCan be empty or nil.
String length less than or equal to 256, excess truncated.
paramNSStringEvent additional informationCan be empty or nil.
String length less than or equal to 7000, excess truncated.
infoNSDictionaryEvent business informationDictionary can be empty.
Length after converting to JSON must be within 7000 characters, otherwise the interface call fails.

  • Example

    Objective-C

    [BRSAgent setCustomEventStartWithID:@"001" name:@"User Login" label:@"Login"];
    // Some code...
    [BRSAgent setCustomEventEndWithID:@"001" name:@"User Login" label:@"Login"];

    Swift

    BRSAgent.setCustomEventStartWithID("001", name: "User Login", label: "Login")
    // Some code...
    BRSAgent.setCustomEventEndWithID("001", name: "User Login", label: "Login")

Note: The start and end of custom events are matched uniquely by eventID. Please ensure the uniqueness of the event ID for unfinished events when using.

Using the full version custom event interface requires upgrading the iOS client to version 7.6.0 or above.

Custom Event (Simplified Version)​

Call the interface and pass the corresponding parameters to complete the statistical function for custom event data.

/// Custom event
+ (void)setCustomEventWithID:(NSString *)eventID
                        name:(nullable NSString *)eventName;
                        
+ (void)setCustomEventWithID:(NSString *)eventID
                        name:(nullable NSString *)eventName
                       param:(nullable NSString *)param;

+ (void)setCustomEventWithID:(NSString *)eventID
                        name:(nullable NSString *)eventName
                       label:(nullable NSString *)eventLabel;

+ (void)setCustomEventWithID:(NSString *)eventID
                        name:(nullable NSString *)eventName
                       label:(nullable NSString *)eventLabel
                       param:(nullable NSString *)param;

+ (void)setCustomEventWithID:(NSString *)eventID
                        name:(nullable NSString *)eventName
                       label:(nullable NSString *)eventLabel
                       param:(nullable NSString *)param
                        info:(nullable NSDictionary<NSString *, NSString *> *)info;
  • Interface Description
Parameter NameTypeDescriptionParameter Constraints
eventIDNSStringEvent ID. Required parameter, call is invalid if empty or nil.String length must be greater than 0 and less than or equal to 256, otherwise the interface call fails.
eventNameNSStringEvent nameCan be empty or nil.
String length less than or equal to 256, excess truncated.
eventLabelNSStringEvent labelCan be empty or nil.
String length less than or equal to 256, excess truncated.
paramNSStringEvent additional informationCan be empty or nil.
String length less than or equal to 7000, excess truncated.
infoNSDictionaryEvent business informationDictionary can be empty.
Length after converting to JSON must be within 7000 characters, otherwise the interface call fails.

  • Example

    Objective-C

    [BRSAgent setCustomEventWithID:@"001" name:@"User Login" label:@"Login"];

    Swift

    BRSAgent.setCustomEventWithID("001", name: "User Login", label: "Login")

Note: Using the Label field in custom events requires upgrading the iOS client to version 7.6.0 or above.

Custom Log​

Call the interface and pass the corresponding parameters to complete the statistical function for custom log data.

/// Custom log
+ (void)setCustomLog:(NSString *)logInfo;

+ (void)setCustomLog:(NSString *)logInfo
               param:(nullable NSString *)param;
  • Interface Description
Parameter NameTypeDescriptionParameter Constraints
logInfoNSStringLog information. Required parameter, call is invalid if empty or nil.String length must be greater than 0, otherwise the interface call fails.
String length less than or equal to 10000, excess truncated.
paramNSStringAdditional information (reserved field, no current usage scenario)-

  • Example

    Objective-C

    [BRSAgent setCustomLog:@"2020-01-01 08:30:00 Print log info."];

    Swift

    BRSAgent.setCustomLog("2020-01-01 08:30:00 Print log info.")

Custom Metric​

Call the interface and pass the corresponding parameters to complete the statistical function for custom metric data.

/// Custom metric
+ (void)setCustomMetricWithName:(NSString *)metricName
                          value:(NSInteger)metricValue;
                          
+ (void)setCustomMetricWithName:(NSString *)metricName
                          value:(NSInteger)metricValue
                          param:(nullable NSString *)param;
  • Interface Description
Parameter NameTypeDescriptionParameter Constraints
metricNameNSStringMetric name. Required parameter, call is invalid if empty or nil.String length must be greater than 0 and less than or equal to 256, otherwise the interface call fails.
metricValueNSIntegerMetric value. Required parameter, call is invalid if metric is empty.-
paramNSStringAdditional information (reserved field, no current usage scenario)-

  • Example

    Objective-C

    [BRSAgent setCustomMetricWithName:@"Test Metric 01" value:1];

    Swift

    BRSAgent.setCustomMetricWithName("Test Metric 01", value: 1)

Custom Method​

Call the interface and pass the corresponding parameters to complete the statistical function for custom method data.

/// Custom method start
+ (void)setCustomMethodStartWithName:(NSString *)methodName;

+ (void)setCustomMethodStartWithName:(NSString *)methodName
                               param:(nullable NSString *)param;

/// Custom method end
+ (void)setCustomMethodEndWithName:(NSString *)methodName;

+ (void)setCustomMethodEndWithName:(NSString *)methodName
                             param:(nullable NSString *)param;
  • Interface Description
Parameter NameTypeDescriptionParameter Constraints
methodNameNSStringMethod name. Required parameter, call is invalid if empty or nil.String length must be greater than 0 and less than or equal to 256, otherwise the interface call fails.
paramNSStringAdditional information (reserved field, no current usage scenario)-

  • Example

    Objective-C

    - (void)testCustomMethod {
        [BRSAgent setCustomMethodStartWithName:@"testCustomMethod"];
         
        // Do something...
       
        [BRSAgent setCustomMethodStartWithName:@"testCustomMethod"];
    }

    Swift

    func testCustomMethod() -> Void {
        BRSAgent.setCustomMethodStartWithName("testCustomMethod")
        
        // Do something...
        
        BRSAgent.setCustomMethodEndWithName("testCustomMethod")
    }

Note: Custom methods use the method name parameter to match the front and back calls of the same method. Ensure the method name is unique during execution.

Custom Network​

Call the interface and pass the corresponding parameters to complete the statistical function for custom network data.

/// Custom network interface
+ (void)setCustomNetwork:(BRSNetworkModel *)networkModel;
  • Interface Description
Parameter NameTypeDescription
networkModelBRSNetworkModelMetric name. Required parameter, call is invalid if passed empty.
// Custom network data model definition
@interface BRSNetworkModel : NSObject

@property (nonatomic, copy)   NSString *requestUrl; // Request URL 「Required」
@property (nonatomic, assign) uint32_t protocolType;// Protocol type 「0:Other, 1:h1, 2:h1s, 3:h2, 5:ws, 6:wss, 7:tcp, 10:udp, 11:quic」
@property (nonatomic, copy, nullable) NSString *targetIpV6; // Target IP (supports IPv4, IPv6)
@property (nonatomic, assign) uint32_t targetPort;  // Target port

@property (nonatomic, strong, nullable) NSDictionary<NSString *, id> *requestHeader; // Request header
@property (nonatomic, strong, nullable) NSDictionary<NSString *, id> *responseHeader;// Response header

@property (nonatomic, copy, nullable)   NSString *method;       // Request method [Uppercase]
@property (nonatomic, copy, nullable)   NSString *resourceType; // Resource type 「Response header Content-Type eg: image/jpeg, text/html」
@property (nonatomic, strong, nullable) NSArray<NSString *> *cnames;// Array of cnames

@property (nonatomic, assign) uint64_t dnsTimeUs;       // DNS query time 「Unit: us」
@property (nonatomic, assign) uint64_t connectTimeUs;   // TCP connection establishment time 「Unit: us」
@property (nonatomic, assign) uint64_t ssltimeUs;       // SSL handshake time 「Unit: us」
@property (nonatomic, assign) uint64_t requestTimeUs;   // Request time 「Unit: us」
@property (nonatomic, assign) uint64_t responseTimeUs;  // Response time 「Unit: us」
@property (nonatomic, assign) uint64_t downloadTimeUs;  // Download time 「Unit: us」
@property (nonatomic, assign) int64_t requestDataSize;  // Request size 「Unit: byte」
@property (nonatomic, assign) int64_t responseDataSize; // Response data size 「Unit: byte」

/// Custom network errors are not supported in the current version. Please do not assign values to the following fields.
@property (nonatomic, strong, nullable) NSNumber *errorCode;    // Error code
@property (nonatomic, copy, nullable)   NSString *errorMessage; // Error message 「Do not assign for non-error requests」
@property (nonatomic, strong, nullable) NSNumber *errorOccurrentprocess;// Error process 「1:SSL process, 2:DNS process, 3:TCP process, 4:Other process」

@end

Fields marked nullable in the properties are not required.

  • Example

    Objective-C

    BRSNetworkModel *model = [[BRSNetworkModel alloc] init];
    model.requestUrl = @"https://www.bonree.com/";
    // ...
    // Set all properties of BRSNetworkModel one by one

    [BRSAgent setCustomNetwork:model];

    Swift

    let model = BRSNetworkModel()
    model.requestUrl = "https://www.bonree.com/"
    // ...
    // Set all properties of BRSNetworkModel one by one

    BRSAgent.setCustomNetwork(model)

Set Custom Request Information Interface​

Call the interface and pass the corresponding parameters to associate custom string information with matched network data.

/// Set request information interface
/// @param headerKey The corresponding key in the request header
/// @param value The value to match
/// @param info The request information to set
+ (void)setRquestExtraInfoWithHeaderKey:(nonnull NSString *)headerKey value:(nonnull NSString *)value info:(nullable NSString *)info;
  • Interface Description
Parameter NameTypeDescriptionParameter Constraints
headerKeyNSStringThe request header Key to match. Required parameter, call is invalid if empty or nil.String length must be greater than 0 and less than or equal to 256, otherwise the interface call fails.
valueNSStringThe request header Value to match. Required parameter, call is invalid if empty or nil.String length must be greater than 0 and less than or equal to 256, otherwise the interface call fails.
infoNSStringAssociated custom information. If empty, clears the information cached for the corresponding key-value.String length must be greater than 0 and less than or equal to 256; if empty, clears the information cached for the corresponding key-value.

  • Example

    Objective-C

    [BRSAgent setRquestExtraInfoWithHeaderKey:@"brkey" value:@"30F032AA-7837-479E-971D-E382B0F90D9B" info:@"name=TOM&age=12"];

    Swift

    BRSAgent.setRquestExtraInfoWithHeaderKey("brkey", value: "30F032AA-7837-479E-971D-E382B0F90D9B", info: "name=TOM&age=12")

Before using this interface, ensure that the target request's header has a unique identifier. For example, a request header might look like:

POST /upload HTTP/1.1
Host: sdkupload.bonree.com
Content-Type: application/json
Content-Length: 781
Connection: keep-alive
Br-Content-Encoding: gzip
brkey: 30F032AA-7837-479E-971D-E382B0F90D9B

Here, brkey is the unique identifier field for this request. To associate information

name=TOM&age=12

with this request, you need to call, before the request is sent,

[BRSAgent setRquestExtraInfoWithHeaderKey:@"brkey" value:@"30F032AA-7837-479E-971D-E382B0F90D9B" info:@"name=TOM&age=12"];

Note: Using the set custom request information interface requires upgrading the iOS client to version 7.6.0 or above.

Set Online Debugging Function Authorization​

The online debugging function requires the application to grant authorization to the client in advance, so that it can execute commands issued by the platform.

The authorization process provides the following two interfaces:

/// Online debugging authorization
/// @param isAuthorized Whether to authorize
+ (void)authorizeOnlineTracking:(BOOL)isAuthorized;
/**
 The authorization interface can be called at any time to enable or disable authorization.
 The authorization status is only valid within a single application lifecycle.
*/

/// Set online debugging function authorization callback
/// @param authHandler Callback Block
+ (void)setOnlineTrackingAuthorizationCallback:(nullable void (^)(void))authHandler;
/**
 If authorization is not granted during a single tracking process, it will be asked once and only once.
 authHandler is executed on the main thread.
*/

The online debugging authorization interface can be used alone to control the authorization status within the current application lifecycle at any time. The default is closed if the interface is not called.

The online debugging function authorization callback setting interface provides the ability to dynamically authorize the client. When this interface is used to set the callback block, and when the platform requests client debugging permissions, the callback block will be executed. Developers can design their own permission handling methods in the callback block, such as popping up a window for permission inquiry. This interface is not mandatory; you can directly use the online debugging authorization interface for permission control without setting the authorization callback.

  • Example

    Objective-C

    [BRSAgent setOnlineTrackingAuthorizationCallback:^{
        
        // Do something...
        
        [BRSAgent authorizeOnlineTracking:YES];
    }];

    Swift

    BRSAgent.setOnlineTrackingAuthorizationCallback {
        
        // Do something...
        
        BRSAgent.authorizeOnlineTracking(true)
    }

Note: Using the online debugging function authorization series interfaces requires upgrading the iOS client to version 7.8.0 or above.

Custom Action End​

Call this interface to end the operation matched based on the call stack. This method must be called directly or indirectly by the operation-related method, otherwise the call is invalid.

  • Usage Scenario

Take a login scenario as an example,

  1. Click the login button, triggering the login method;
  2. In the login method, send a login request;
  3. After the login request succeeds, persist user information and jump to the home page;
  4. Execute other business logic in the home page's controller;

If we define the end point of the login operation as the appearance of the home page's controller, then we can call the custom action end interface in the viewDidAppear(_:) method.

// Login
@objc func login() {
    // some code
    
    // Login request
    URLSession.shared
        .dataTask(with: request) { data, response, _ in
            // Persist user information
            
            DispatchQueue.main.async {
                self.present(FeedListViewController(), animated: true)
            }
        }
        .resume()
    
    // some code
}
// Home page controller

override func viewDidAppear(_ animated: Bool) {
    super.viewDidAppear(animated)

    BRSAgent.recordCustomActionEnd()
    
    // some code
}
  • Interface Definition
+ (void)recordCustomActionEnd;
  • Example

Objective-C

[BRSAgent recordCustomActionEnd];

Swift

BRSAgent.recordCustomActionEnd()

ReactNative Bundle Startup Interface​

This interface is for the start of Bundle loading, passing in the Bundle name and Module name.

This interface must be called in pair with the Bundle JS Loading End Interface.

/// React Native Bundle start loading
+ (void)reportBundleStartLoadWithBundle:(NSString *)bundleName
                             moduleName:(NSString *)moduleName;
  • Interface Description
Parameter NameTypeDescription
bundleNameNSStringBundle name. Required parameter.
moduleNameNSStringModule name. Required parameter.

  • Example

    Objective-C

    [BRSAgent reportBundleStartLoadWithBundle:@"BundleName" moduleName:@"ModuleName"];

    Swift

    BRSAgent.reportBundleStartLoad(withBundle: "BundleName", moduleName: "ModuleName")

ReactNative Bundle JS Loading End Interface​

This interface is for the end of JS loading in the Bundle, passing in the Bundle name.

This interface must be called in pair with the Bundle Startup Interface.

/// React Native Bundle JS finish loading
+ (void)reportBundleJSFinishLoadWithBundle:(NSString *)bundleName;
  • Interface Description
Parameter NameTypeDescription
bundleNameNSStringBundle name. Required parameter.

  • Example

    Objective-C

    [BRSAgent reportBundleJSFinishLoadWithBundle:@"BundleName"];

    Swift

    BRSAgent.reportBundleJSFinishLoad(withBundle: "BundleName")

Set Control Instance Desensitization​

This interface can set a certain control (instance object) to be desensitized, then the SDK will not collect sensitive information from this control.

/// Whether the UIView instance is sensitive
@property (nonatomic, assign) BOOL brsSensitive;

Need to import the header file before use, #import <BonreeRUM/UIView+BRSSensitive.h>

  • Property Description
Property NameTypeDescription
brsSensitiveBOOLYES: Sensitive [filter text and other information] NO: Not sensitive [normal collection]

  • Example

    Objective-C

    aView.brsSensitive = YES;

    Swift

    aView.brsSensitive = true

Set Sensitive Control Types​

This interface can set a control type to be desensitized, then all instances of that type will be desensitized, and the SDK will not collect sensitive information from these controls.

Setting a control type will also treat its subclasses as sensitive. For example, if the UIControl type is set, then UIButton, a subclass of UIControl, will also be considered sensitive.

/// Set sensitive control types
+ (void)setViewSensitiveClasses:(NSArray<Class> *)classes;
  • Property Description
Property NameTypeDescription
classesNSArray<Class>Control types to be set as sensitive, e.g., UILabel.class, UIControl.class

  • Example

    Objective-C

    [BRSAgent setViewSensitiveClasses:@[UIButton.class, UILabel.class]];

    Swift

    BRSAgent.setViewSensitiveClasses([UIButton.self, UILabel.self])

Set Custom Control Title​

This interface sets a custom title for a control. The SDK will prioritize using the custom title when collecting click behavior for this control.

Import #import <BonreeRUM/UIView+BRSExternalExt.h> before use. Supported control types: UIView and UIBarItem.

/// Custom title, takes effect when clicked
@property (nonatomic, copy) NSString *brsActionControlTitle;
  • Property Description
Property NameTypeDescription
brsActionControlTitleNSStringCustom title for the control

  • Example

    Objective-C

    //UIView
    UIView *view = xxx;
    view.brsActionControlTitle = @"CustomTitle";
    //UIBarItem
    UIBarItem *item = xxx;
    item.brsActionControlTitle = @"CustomTitle";

    Swift

    //UIView
    let view: UIView = xxx;
    view.brsActionControlTitle = "CustomTitle"
    //UIBarItem
    let item: UIBarItem = xxx;
    item.brsActionControlTitle = "CustomTitle"

Set Whether PDF Exists in WebView​

Call this interface to inform the SDK whether to perform PDF WebView detection during session replay screenshots.

/// Set whether PDF exists in WebView [Session Replay]
+ (void)setHavePDFWebView:(BOOL)isPDFWebView;
  • Property Description
Property NameTypeDescription
isPDFWebViewBOOLWhether the WebView contains PDF. YES: Contains PDF, session replay will search for PDF content, record if found NO: Ignore PDF content

  • Example

    Objective-C

    [BRSAgent setHavePDFWebView:YES];

    Swift

    BRSAgent.setHavePDFWebView(true)

This interface is used for WebView session replay that contains PDF.

Set WebView Instance Containing PDF​

During WebView session replay screenshots, the WebView instance set by this interface will be prioritized for detection.

/// Set WebView containing PDF [Session Replay]
+ (void)setPDFWebView:(WKWebView *)webView;
  • Property Description
Property NameTypeDescriptionParameter Constraints
webViewWKWebView *WebView instance containing PDF. If multiple WebViews exist, specify the one containing PDF, otherwise the correct content cannot be captured.WKWebView instance, null value is invalid.

  • Example

    Objective-C

    [BRSAgent setPDFWebView:webView];

    Swift

    BRSAgent.setPDFWebView(webView)

This interface is used for WebView session replay that contains PDF.

IV. Protocol Extension Interfaces​

This chapter introduces the usage and description of interfaces related to custom execution units.

Create Execution Unit​

Call the creation interface to return an instance that implements the BRSSpan protocol.

/// Create span
/// - Parameters:
///   - name: span name
///   - type: span type
+ (nullable id<BRSSpan>)startSpanWithName:(NSString *)name type:(NSString *)type;
  • Interface Description
Parameter NameTypeDescriptionParameter Constraints
nameNSStringThe name of the execution unit. Required parameter, call is invalid if empty or nil.String length must be greater than 0 and less than or equal to 256, excess truncated. Allows numbers, letters, colons, spaces, slashes, underscores, hyphens, periods, @
typeNSStringThe type of the execution unit. Required parameter, call is invalid if empty or nil.String length must be greater than 0 and less than or equal to 256, excess truncated. Allows numbers, letters, colons, spaces, slashes, underscores, hyphens, periods, @
Return TypeDescription
id<BRSSpan>An object conforming to the BRSSpan protocol. Returns nil if creation fails.

  • Example

    Objective-C

    id<BRSSpan> span = [BRSAgent startSpanWithName:@"name"
                                              type:@"type"];

    Swift

    let span = BRSAgent.startSpan(withName: "name",
                                      type: "type")

Note: The creation interface, i.e., startSpanWithName:type:, must be called in pair with the completion interface, i.e., finish or finishWithStatus:.

The following interfaces are all instance methods of the execution unit (implementing the BRSSpan protocol).

Complete Execution Unit​

Complete this execution unit. Calling other instance methods after completion is invalid.

/// Finish span
/// - Note If `-setStatus:` is not called to set the span status, the span status will be success.
- (void)finish;

/// Finish span and set the span status to status.
- (void)finishWithStatus:(BRSSpanStatus)status;
  • Interface Description
Parameter NameTypeDescription
statusBRSSpanStatusExecution unit status, values: BRSSpanStatusUnknown, BRSSpanStatusSuccess, BRSSpanStatusFailed

  • Example

    Objective-C

    [span finish];
    //or
    [span finishWithStatus:BRSSpanStatusSuccess];

    Swift

    span.finish()
    //or
    span.finish(with: .success)

Note: The creation interface, i.e., startSpanWithName:type:, must be called in pair with the completion interface, i.e., finish or finishWithStatus:.

Create Child Execution Unit​

Create a child execution unit on an execution unit, returning an instance implementing the BRSSpan protocol.

/// Create a child span
/// - Parameters:
///   - name: span name
///   - type: span type
- (nullable id<BRSSpan>)startChildWithName:(NSString *)name type:(NSString *)type;
  • Interface Description
Parameter NameTypeDescriptionParameter Constraints
nameNSStringThe name of the execution unit. Required parameter, call is invalid if empty or nil.String length must be greater than 0 and less than or equal to 256, excess truncated. Allows numbers, letters, colons, spaces, slashes, underscores, hyphens, periods, @
typeNSStringThe type of the execution unit. Required parameter, call is invalid if empty or nil. (Should be consistent with the parent span type, otherwise the parent span type is used)String length must be greater than 0 and less than or equal to 256, excess truncated. Allows numbers, letters, colons, spaces, slashes, underscores, hyphens, periods, @
Return TypeDescription
id<BRSSpan>An object conforming to the BRSSpan protocol. Returns nil if creation fails.

  • Example

    Objective-C

    id<BRSSpan> subSpan = [span startChildWithName:@"name"
                                              type:@"type"];

    Swift

    let subSpan = span.startChild(withName: "name",
                                      type: "type")

Note: When finishing a parent execution unit, all its child execution units will be automatically finished (if their status hasn't been set, it defaults to success).

Currently, only single-level child execution units are supported, meaning top-level Spans can create child Spans, but child Spans cannot create further child Spans.

When the Span type is one of the two reserved types, socket or websocket, creating child Spans under it is temporarily not supported.

Set Data​

Set the Data within the execution unit.

/// Set data
/// - Parameters:
///   - value: data value
///   - key: key value
- (void)setDataValue:(NSString *)value forKey:(NSString *)key;
  • Interface Description
Parameter NameTypeDescriptionParameter Constraints
valueNSStringData value.String length must be greater than 0 and less than or equal to 7000, excess truncated.
keyNSStringThe key corresponding to the Data. Case-insensitive. Required parameter, call is invalid if empty or nil.String length must be greater than 0 and less than or equal to 200, call is invalid if exceeded. Allows letters, underscores, hyphens, periods, and must start and end with a letter.

  • Example

    Objective-C

    [span setDataValue:@"value" forKey:@"key"];

    Swift

    span.setDataValue("value", forKey: "key")

Set Tag​

Set the Tag within the execution unit.

/// Set tags
/// - Parameters:
///   - value: tag value
///   - key: key value
- (void)setTagValue:(NSString *)value forKey:(NSString *)key;
  • Interface Description
Parameter NameTypeDescriptionParameter Constraints
valueNSStringTag value.String length must be greater than 0 and less than or equal to 7000, excess truncated.
keyNSStringThe key corresponding to the Tag. Case-insensitive. Required parameter, call is invalid if empty or nil.String length must be greater than 0 and less than or equal to 200, call is invalid if exceeded. Allows letters, underscores, hyphens, periods, and must start and end with a letter.

  • Example

    Objective-C

    [span setTagValue:@"tag" forKey:@"key"];

    Swift

    span.setTagValue("tag", forKey: "key")

Set Metric​

1. Set Metric within the execution unit (without unit)​

/// Set metrics
/// - Parameters:
///   - value: metric value
///   - key: key value
- (void)setMetricValue:(long long)value forKey:(NSString *)key;
  • Interface Description
Parameter NameTypeDescriptionParameter Constraints
valuelong longMetric value.None
keyNSStringThe key corresponding to the Metric. Case-insensitive. Required parameter, call is invalid if empty or nil.String length must be greater than 0 and less than or equal to 200, call is invalid if exceeded. Allows letters, underscores, hyphens, periods, and must start and end with a letter.

  • Example

    Objective-C

    [span setMetricValue:100 forKey:@"ms"];

    Swift

    span.setMetricValue(100, forKey: "tcp")

2. Set Metric within the execution unit (with unit)​

/// Set metrics
/// - Parameters:
///   - value: metric value
///   - unit: unit name for the value
///   - key: key value
- (void)setMetricValue:(long long)value unit:(NSString *)unit forKey:(NSString *)key;
  • Interface Description
Parameter NameTypeDescriptionParameter Constraints
valuelong longMetric value.None
unitNSStringUnit name for the Metric.String length must be greater than 0 and less than or equal to 256, only the unit setting is invalid if exceeded. Allows numbers, letters, colons, spaces, slashes, underscores, hyphens, periods, @
keyNSStringThe key corresponding to the Metric. Case-insensitive. Required parameter, call is invalid if empty or nil.String length must be greater than 0 and less than or equal to 200, call is invalid if exceeded. Allows letters, underscores, hyphens, periods, and must start and end with a letter.

  • Example

    Objective-C

    [span setMetricValue:100 unit:@"ms" forKey:@"tcp"];

    Swift

    span.setMetricValue(100, unit: "ms", forKey: "tcp")

Note: The SDK has built-in units. The built-in unit types are in BRSSpan.h's BRSSpanMetricUnitNames[ ]. Custom units are supported.

Remove Data​

Remove the Data within the execution unit.

/// Remove specified data
- (void)removeDataForKey:(NSString *)key;
  • Interface Description
Parameter NameTypeDescription
keyNSStringThe key of the Data to be deleted

  • Example

    Objective-C

    [span removeDataForKey:@"key"];

    Swift

    span.removeData(forKey: "key")

Remove Tag​

Remove the Tag within the execution unit.

/// Remove specified tag
- (void)removeTagForKey:(NSString *)key;
  • Interface Description
Parameter NameTypeDescription
keyNSStringThe key of the Tag to be deleted

  • Example

    Objective-C

    [span removeTagForKey:@"key"];

    Swift

    span.removeTag(forKey: "key")

Remove Metric​

Remove the Metric within the execution unit.

/// Remove specified metric
- (void)removeMetricForKey:(NSString *)key;
  • Interface Description
Parameter NameTypeDescription
keyNSStringThe key of the Metric to be deleted

  • Example

    Objective-C

    [span removeMetricForKey:@"key"];

    Swift

    span.removeMetric(forKey: "key")

Set Status​

Set the status of the execution unit.

/// Set the status of the span
- (void)setStatus:(BRSSpanStatus)status;
  • Interface Description
Parameter NameTypeDescription
statusBRSSpanStatusExecution unit status, values: BRSSpanStatusUnknown, BRSSpanStatusSuccess, BRSSpanStatusFailed

  • Example

    Objective-C

    [span setStatus:BRSSpanStatusSuccess];

    Swift

    span.setStatus(.success)

Set Duration​

Actively set the span duration. If this method is not actively called, the span duration is the time from start to finish.

/// Set the duration of the span
/// - Parameter duration: Duration (unit: us)
- (void)setDuration:(long long)duration;
  • Interface Description
Parameter NameTypeDescription
durationlong longExecution unit duration, unit: microseconds (us).

  • Example

    Objective-C

    [span setDuration:100];

    Swift

    span.setDuration(100)

Set Status Code​

Set the status code of the execution unit.

/// Set the status code of the span
/// - Parameter statusCode: Status code
- (void)setStatusCode:(NSString *)statusCode;
  • Interface Description
Parameter NameTypeDescriptionParameter Constraints
statusCodeNSStringStatus code value.String length must be greater than 0 and less than or equal to 7000, call is invalid if exceeded.

  • Example

    Objective-C

    [span setStatusCode:@"200"];

    Swift

    span.setStatusCode("200")