Cloud Monitor:SDK configuration reference

Set endpoint address

Each app must be associated with a corresponding endpoint address. This method must be called before calling start:.

@objc
public static func setEndpoint(_ endpoint: String)

Set workspace address

Each app must be associated with a corresponding workspace. This method must be called before calling start:.

@objc
public static func setWorkspace(_ workspace: String)

Start API

Call the start: method to initialize the SDK.

@objc(start:)
public static func start(_ serviceId: String)

Set custom device ID

Call this method to set a custom device ID. After a custom device ID is set, the SDK uses this ID instead of the default, automatically acquired ID.

@objc
public static func setDeviceID(_ deviceID: String)

Set custom app version

The SDK reports the app version you set with this method instead of the default, auto-detected version.

@objc
public static func setAppVersion(_ appVersion: String)

Set channel ID

This method specifies the application's distribution channel.

@objc
public static func setChannelID(_ channelID: String)

Exclude specific classes

This method adds the specified class name to a swizzling exclusion set. The SDK then skips automatic analysis and instrumentation for any class whose name contains the specified substring. Call this method to exclude a class if you do not want to collect its data or if you encounter compatibility issues. You can call this method multiple times.

Note: This method must be called before SDK initialization. Use the exclusion keyword with caution to avoid unintentionally excluding classes that match the substring.

@objc(excludeClassFromTracking:)
public static func excludeClassFromTracking(_ className: String)

Example:

// Excludes all classes whose names contain StoreKit2ViewController.
[AlibabaCloudRUM excludeClassFromTracking:@"StoreKit2ViewController"];
// Excludes all classes whose names contain BTDemoStoreKit2MixedBridge.
[AlibabaCloudRUM excludeClassFromTracking:@"BTDemoStoreKit2MixedBridge"];

Disable or enable modules

These methods disable or enable specific data collection modules. Local configurations take precedence over remote configurations. The settings are cumulative across multiple calls.

Note: These methods must be called before SDK initialization. Local configurations take precedence over remote configurations, so use these settings with caution.

@objc(disableModule:)
public static func disableModule(_ module: AlibabaCloudModule)

@objc(enableModule:)
public static func enableModule(_ module: AlibabaCloudModule)

@objc(AlibabaCloudModule)
public enum AlibabaCloudModule: Int {
    case crash        = 0
    case network      = 1
    case view         = 2
    case action       = 3
    case webView      = 4
    case longTask     = 5
    case appLaunch    = 6
    case appState     = 7
    case netState     = 8
    case customEvent  = 9
    case customLog    = 10
    case customMetric = 11
    case oom          = 12
    case sessionReplay = 13
}

Objective-C example:

// Enables the OOM data collection module.
[AlibabaCloudRUM enableModule:AlibabaCloudModuleOOM];

// Disables the network data collection module.
[AlibabaCloudRUM disableModule:AlibabaCloudModuleNetwork];

// Session Replay depends on the View module. We recommend that you explicitly enable both.
[AlibabaCloudRUM enableModule:AlibabaCloudModuleView];
[AlibabaCloudRUM enableModule:AlibabaCloudModuleSessionReplay];

Swift example:

// Session Replay depends on the View module. We recommend that you explicitly enable both.
AlibabaCloudRUM.enableModule(.view)
AlibabaCloudRUM.enableModule(.sessionReplay)

Disable or enable self-monitoring

The SDK collects self-monitoring data to continuously improve SDK performance and user experience. By default, the SDK collects self-monitoring data. Use this toggle to disable or re-enable this capability.

Note: This method must be called before SDK initialization.

+ (void)setSelfMonitorEnabled:(BOOL)enabled NS_SWIFT_NAME(setSelfMonitorEnabled(_:));

Example:

// Enable SDK self-monitoring data collection.
[AlibabaCloudRUM setSelfMonitorEnabled:YES];

Set app environment

This method specifies the application environment, such as LOCAL, DAILY, or PROD.

@objc
public static func setEnvironment(_ env: Env)

Enable session replay

Enable the session replay module before the RUM SDK is initialized, and start session replay after initialization is complete.

AlibabaCloudRUM.enableModule(.sessionReplay)
AlibabaCloudRUM.start(serviceId)
AlibabaCloudSessionReplay.start()

[AlibabaCloudRUM enableModule:AlibabaCloudModuleSessionReplay];
[AlibabaCloudRUM start:serviceId];
[AlibabaCloudSessionReplay start];

Configure session replay

In most cases, call AlibabaCloudSessionReplay.start() to use the default configurations. By default, the sample rate is 100%, all text and images are masked, and touch positions are hidden.

To adjust the sample rate or the privacy policy, use AlibabaCloudSessionReplayConfiguration. This class contains the following read-only configuration items, all of which must be specified during initialization.

Custom configuration example:

let configuration = AlibabaCloudSessionReplayConfiguration(
    sampleRate: 10,
    textAndInputPrivacy: .maskAll,
    imagePrivacy: .maskAll,
    touchPrivacy: .hide
)

AlibabaCloudSessionReplay.start(configuration)

Stop session replay

Call stop() to stop session replay. This method stops the SDK from receiving new replay data. Data that has already been received is still processed and reported asynchronously as usual.

AlibabaCloudSessionReplay.stop()

[AlibabaCloudSessionReplay stop];

Privacy compliance notes

• (Recommended) Keep .maskAll for text and images and .hide for touch positions, and relax these settings only after you complete a privacy assessment.

• .maskSensitiveInputs relies on system information such as secureTextEntry and UITextContentType to identify sensitive fields. It is not a substitute for your own privacy review of page content and input fields.

• imagePrivacy: .maskNone disables image masking. For a capturable UIImageView.image (backed by a CGImage), the SDK encodes the actual image as a replay resource and reports it, instead of recording only the image area. As a result, content such as avatars, order images, or business screenshots may be included in the replay data.

• touchPrivacy: .show records the touch positions of users. Assess the associated risks before you enable this option.

• Disclose the collection purpose, data scope, usage, and retention of session replay in your app privacy policy and App Store privacy labels, and obtain user consent in accordance with applicable laws and regulations.

Set user ID

Associate monitoring data with a user ID to enable filtering and analysis by user.

@objc
public static func setUserName(_ userID: String)

Set user metadata

Attach key-value metadata to the current user to support per-user analysis.

@objc(setUserExtraInfo:)
public static func setUserExtraInfo(_ extraInfo: [String: AnyObject])

Set custom global properties

Once set, custom global properties are automatically attached to all subsequent data. Use these business properties to segment and analyze your data.

// Replaces all existing global properties
@objc(setExtraInfo:)
public static func setExtraInfo(_ extraInfo: [String: AnyObject])

// Appends to existing global properties
@objc(addExtraInfo:)
public static func addExtraInfo(_ extraInfo: [String: AnyObject])

Custom exception

Call this interface to report custom exception data.

@objc(setCustomException:causeBy:errorDump:)
public static func setCustomException(_ exceptionType: String, _ causeBy: String, _ errorDump: String)

Custom event

The SDK lets you report custom events. Call the appropriate method with its parameters to collect the data.

@objc(setCustomEvent:)
public static func setCustomEvent(_ name: String)

@objc(setCustomEvent:group:)
public static func setCustomEvent(_ name: String, group: String? = nil)

@objc(setCustomEvent:group:snapshots:)
public static func setCustomEvent(_ name: String, group: String? = nil, snapshots: String? = nil)

@objc(setCustomEvent:group:value:)
public static func setCustomEvent(_ name: String, group: String? = nil, value: Double = 0)

@objc(setCustomEvent:group:info:)
public static func setCustomEvent(_ name: String, group: String? = nil, info: [String: String]? = nil)

@objc(setCustomEvent:group:snapshots:value:)
public static func setCustomEvent(_ name: String, group: String? = nil, snapshots: String? = nil, value: Double = 0) 

@objc(setCustomEvent:group:snapshots:info:)
public static func setCustomEvent(_ name: String, group: String? = nil, snapshots: String? = nil, info: [String: String]? = nil)

@objc(setCustomEvent:group:value:info:)
public static func setCustomEvent(_ name: String, group: String? = nil, value: Double = 0, info: [String: String]? = nil) 

@objc(setCustomEvent:group:snapshots:value:info:)
public static func setCustomEvent(_ name: String, group: String? = nil, snapshots: String? = nil, value: Double = 0, info: [String: String]? = nil)

Custom log

The SDK lets you report custom logs. To record a log, call the appropriate method with the required parameters.

@objc(setCustomLog:)
public static func setCustomLog(_ logInfo: String)

@objc(setCustomLog:name:)
public static func setCustomLog(_ logInfo: String, name: String? = nil) 

@objc(setCustomLog:name:snapshots:)
public static func setCustomLog(_ logInfo: String, name: String? = nil, snapshots: String? = "") 

@objc(setCustomLog:name:snapshots:level:info:)
public static func setCustomLog(_ logInfo: String, name: String? = nil, snapshots: String? = "", level: String? = "INFO", info: [String: String]? = nil)

Basic scenario

@objc(setCustomResource:success:url:method:statusCode:errorMessage:)
public static func setCustomResource(_ type: String, success: Bool, url: String, method: String, statusCode: Int, errorMessage: String?) -> Bool

Return value: Bool - A boolean value that indicates whether the API call succeeded. true is returned on success, and false is returned on failure (for example, if the SDK is not initialized or the parameters are invalid).

Example

// Swift - Successful GET request
let result = AlibabaCloudRUM.setCustomResource(
    "API",
    success: true,
    url: "https://api.example.com/users",
    method: "GET",
    statusCode: 200,
    errorMessage: nil
)

// Swift - Failed POST request
let result2 = AlibabaCloudRUM.setCustomResource(
    "API",
    success: false,
    url: "https://api.example.com/login",
    method: "POST",
    statusCode: 401,
    errorMessage: "Unauthorized access"
)

// Objective-C - Successful GET request
BOOL result = [AlibabaCloudRUM setCustomResource:@"API"
                                         success:YES
                                             url:@"https://api.example.com/users"
                                          method:@"GET"
                                      statusCode:200
                                    errorMessage:nil];

// Objective-C - Failed POST request
BOOL result2 = [AlibabaCloudRUM setCustomResource:@"API"
                                          success:NO
                                              url:@"https://api.example.com/login"
                                           method:@"POST"
                                       statusCode:401
                                     errorMessage:@"Unauthorized access"];

Advanced scenario

For advanced scenarios, this method overload lets you report detailed performance metrics and tracing data.

    @objc(setCustomResource:success:url:method:statusCode:errorMessage:provider:tracing:measure:)
    public static func setCustomResource(_ type: String, success: Bool, url: String, method: String, statusCode: Int, errorMessage: String?, provider: String?, tracing: AlibabaCloudTracingContext?, measure: AlibabaCloudResourceMeasure?) -> Bool

Return value: Bool - Indicates whether the API call was successful. true indicates success, and false indicates failure.

Example:

// Swift - Create a resource performance metric object
let measure = AlibabaCloudResourceMeasure.measure()
measure.duration = 850
measure.size = 10240
measure.dnsDuration = 30
measure.connectDuration = 80
measure.sslDuration = 120
measure.firstByteDuration = 250
measure.downloadDuration = 370

// Create a tracing context
let traceId = AlibabaCloudTraceGenerator.generateTraceId(.SkywalkingV3)
let spanId = AlibabaCloudTraceGenerator.generateTraceId(.SkywalkingV3)
let tracing = AlibabaCloudTracingContext(traceId: traceId, spanId: spanId, tracingProtocol: .SkywalkingV3)

// Report the complete resource data
let result = AlibabaCloudRUM.setCustomResource(
  "HTTPS",
  success: true,
  url: "https://api.example.com/v2/data",
  method: "POST",
  statusCode: 200,
  errorMessage: nil,
  provider: "Aliyun",
  tracing: tracing,
  measure: measure
)

// Objective-C - Create a resource performance metric object
AlibabaCloudResourceMeasure *measure = [AlibabaCloudResourceMeasure measure];
measure.duration = 850;
measure.size = 10240;
measure.dnsDuration = 30;
measure.connectDuration = 80;
measure.sslDuration = 120;
measure.firstByteDuration = 250;
measure.downloadDuration = 370;

// Create a tracing context
NSString *traceId = [AlibabaCloudTracingGenerator generateTraceId:AlibabaCloudTracingProtocolW3C];
NSString *spanId = [AlibabaCloudTracingGenerator generateSpanId:AlibabaCloudTracingProtocolW3C];
AlibabaCloudTracingContext *tracing = [AlibabaCloudTracingContext contextWithTraceId:traceId
                                                                              spanId:spanId
                                                                            protocol:AlibabaCloudTracingProtocolW3C
];

// Report the complete resource data
BOOL result = [AlibabaCloudRUM setCustomResource:@"HTTPS"
                                         success:YES
                                             url:@"https://api.example.com/v2/data"
                                          method:@"POST"
                                      statusCode:200
                                    errorMessage:nil
                                        provider:@"Aliyun"
                                         tracing:tracing
                                         measure:measure];

Helper types

// Swift - Generate a TraceId and SpanId
let traceId = AlibabaCloudTracingGenerator.generateTraceId(.SkywalkingV3)
let spanId = AlibabaCloudTracingGenerator.generateSpanId(.SkywalkingV3)

// Swift - Create a tracing context
let tracingContext = AlibabaCloudTracingContext(traceId: traceId, spanId: spanId, protocol: .SkywalkingV3)

// Objective-C - Generate a TraceId and SpanId
NSString *traceId = [AlibabaCloudTracingGenerator generateTraceId:AlibabaCloudTracingProtocolW3C];
NSString *spanId = [AlibabaCloudTracingGenerator generateSpanId:AlibabaCloudTracingProtocolW3C];

// Objective-C - Create a context
AlibabaCloudTracingContext *context = [AlibabaCloudTracingContext contextWithTraceId:traceId
                                                                              spanId:spanId
                                                                     tracingProtocol:AlibabaCloudTracingProtocolW3C
];

// Swift
let measure = AlibabaCloudResourceMeasure.measure()
measure.duration = 1200
measure.size = 5120
measure.dnsDuration = 50
measure.connectDuration = 100
measure.sslDuration = 150
measure.firstByteDuration = 300
measure.downloadDuration = 600

// Objective-C
AlibabaCloudResourceMeasure *measure = [AlibabaCloudResourceMeasure measure];
measure.duration = 1200;
measure.size = 5120;
measure.dnsDuration = 50;
measure.connectDuration = 100;
measure.sslDuration = 150;
measure.firstByteDuration = 300;
measure.downloadDuration = 600;