iOS SDK configuration reference - Application Real-Time Monitoring Service

The Real User Monitoring software development kit (SDK) provides several configuration items that you can set to meet your specific needs. This topic describes common SDK configurations for iOS applications.

Startup configuration

Set the Endpoint address

You must associate each application with an Endpoint address. Call this method before you call the start: method.

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

Parameter	Description	Parameter limits	Result if failed
endpoint	The Endpoint address.	The string length must be greater than 0 and less than 2083.	The method call fails and the SDK stops.

Set the Workspace address

You must associate each application with a Workspace. Call this method before you call the start: method.

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

Parameter	Description	Parameter limits	Result if failed
workspace	The Workspace address.	The string length must be greater than 0 and less than 2083.	The method call fails and the SDK stops.

Startup method

You can call the start: method to initialize the SDK.

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

Parameter	Description	Parameter limits	Result if failed
serviceId	ServiceId	The unique ID of the application that is generated on the Real User Monitoring platform.	The method call fails and the SDK stops.

Set a custom device ID

You can use this method to set a custom device ID. After the ID is set, the SDK no longer uses the default device ID.

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

Parameter	Description	Parameter limits	Result if failed
deviceID	The custom device ID.	The string must be 1 to 255 characters in length and cannot contain special characters. Only letters, digits, colons (:), spaces, underscores (_), hyphens (-), periods (.), and at signs (@) are supported.	The method call fails. The current setting is invalid.

Set a custom app version number

If you use this method to set a custom app version number, the SDK reports this version number instead of the default version number.

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

Parameter	Description	Parameter limits	Result if failed
appVersion	The custom app version number.	The string must be 1 to 63 characters in length.	The method call fails. The current setting is invalid.

Set a user channel ID

You can use this method to distinguish the channels where the application is published.

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

Parameter	Description	Parameter limits	Result if failed
channelID	The custom channel ID.	The string must be 1 to 255 characters in length.	The method call fails. The current setting is invalid.

Set the application environment

You can use this method to distinguish and specify the application environment, such as LOCAL, DAILY, or PROD.

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

Parameter

Description

Parameter limits

Result if failed

env

The enumeration value of the application environment. Call this method after the setConfigAddress method and before the start method.

Env enumeration values:

LOCAL: Local environment
Daily
PRE: Pre-release environment
GRAY: Grayscale environment
PROD (default): Production environment
None

The method call fails. The current setting is invalid.

Custom information

Set a custom username

The SDK lets you set user-related information. This helps you associate data analytics with actual users.

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

Parameter

Description

Parameter limits

Result if failed

userID

The username identity.

The string can be null or empty.

The string must be 256 or fewer characters in length and cannot contain special characters. Only digits, letters, colons (:), spaces, forward slashes (/), underscores (_), hyphens (-), periods (.), and at signs (@) are supported.

The method call fails. The current setting is invalid.

Set custom user extension information

The SDK lets you set user-related information. This helps you associate data analytics with actual users.

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

Parameter

Description

Parameter limits

Result if failed

extraInfo

The user extension information.

The Map can be null or empty.

The JSON string cannot exceed 7,000 characters, or the API call will fail.

The method call fails. The current setting is invalid.

Set custom global properties

After you set custom global properties, all new data automatically includes these properties. This lets you perform analysis related to business properties.

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

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

Parameter	Description	Parameter limits	Result if failed
extraInfo	The property information.	The map can be null or empty. After conversion to JSON, the length must be within 7,000 characters. Otherwise, the method call fails.	The method call fails. The current setting is invalid.

Note

Calling the setExtraInfo method clears all previously set properties. To append new properties, use the addExtraInfo method.

Custom exception

You can call the custom exception method and pass the corresponding parameters to collect statistics on custom exceptions.

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

Parameter	Description	Parameter limits	Result if failed
exceptionType	The exception type. This parameter is required.	The string must be 1 to 256 characters in length.	The method call fails. The current setting is invalid.
causeBy	The cause of the exception.	The string can be null or empty. The string can be up to 512 characters in length. If the string exceeds the limit, it is truncated.	N/A
errorDump	The exception information.	The string can be null or empty. The string can be up to 10,000 characters in length. If the string exceeds the limit, it is truncated.	N/A

Custom events

The SDK supports reporting custom events. You can call the corresponding methods and pass the required parameters to collect statistics on custom events.

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

Parameter	Description	Parameter limits	Result if failed
name	The event name. This parameter is required.	The string must be 1 to 256 characters in length.	The method call fails. The current setting is invalid.

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

Parameter

Description

Parameter limits

Result if failed

name

The event name. This parameter is required.

The string must be 1 to 256 characters in length.

The method call fails. The current setting is invalid.

group

The event group.

The string can be nil or an empty string.

The string can be up to 256 characters in length. If the string exceeds the limit, it is truncated.

N/A

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

Parameter	Description	Parameter limits	Result if failed
name	The event name. This parameter is required.	The string must be 1 to 256 characters in length.	The method call fails. The current setting is invalid.
group	The event group.	The string can be `nil` or an `empty string`. The string can be up to 256 characters in length. If the string exceeds the limit, it is truncated.	N/A
snapshots	The event snapshot.	The string can be `nil` or an `empty string`. The string can be up to 7,000 characters in length. If the string exceeds the limit, it is truncated.	N/A

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

Parameter	Description	Parameter limits	Result if failed
name	The event name. This parameter is required.	The string must be 1 to 256 characters in length.	The method call fails. The current setting is invalid.
group	The event group.	The string can be `nil` or an `empty string`. The string can be up to 256 characters in length. If the string exceeds the limit, it is truncated.	N/A
value	The event value.	The data type is double.	N/A

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

Parameter	Description	Parameter limits	Result if failed
name	The event name. This parameter is required.	The string must be 1 to 256 characters in length.	The method call fails. The current setting is invalid.
group	The event group.	The string can be `nil` or an `empty string`. The string can be up to 256 characters in length. If the string exceeds the limit, it is truncated.	N/A
info	Additional information for the event.	The map can be null or empty. After conversion to JSON, the length must be within 7,000 characters. Otherwise, the method call fails.	N/A

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

Parameter	Description	Parameter limits	Result if failed
name	The event name. This parameter is required.	The string must be 1 to 256 characters in length.	The method call fails. The current setting is invalid.
group	The event group.	The string can be `nil` or an `empty string`. The string can be up to 256 characters in length. If the string exceeds the limit, it is truncated.	N/A
snapshots	The event snapshot.	The string can be `nil` or an `empty string`. The string can be up to 7,000 characters in length. If the string exceeds the limit, it is truncated.	N/A
value	The event value.	The data type is double.	N/A

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

Parameter	Description	Parameter limits	Result if failed
name	The event name. This parameter is required.	The string must be 1 to 256 characters in length.	The method call fails. The current setting is invalid.
group	The event group.	The string can be `nil` or an `empty string`. The string can be up to 256 characters in length. If the string exceeds the limit, it is truncated.	N/A
snapshots	The event snapshot.	The string can be `nil` or `empty`. The string can be up to 7,000 characters in length. If the string exceeds the limit, it is truncated.	N/A
info	Additional information for the event.	The map can be null or empty. After conversion to JSON, the length must be within 7,000 characters. Otherwise, the method call fails.	N/A

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

Parameter	Description	Parameter limits	Result if failed
name	The event name. This parameter is required.	The string must be 1 to 256 characters in length.	The method call fails. The current setting is invalid.
group	The event group.	The string can be `nil` or an `empty string`. The string can be up to 256 characters in length. If the string exceeds the limit, it is truncated.	N/A
value	The event value.	The data type is double.	N/A
info	Additional information for the event.	The map can be null or empty. After conversion to JSON, the length must be within 7,000 characters. Otherwise, the method call fails.	N/A

@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)

Parameter	Description	Parameter limits	Result if failed
name	The event name. This parameter is required.	The string must be 1 to 256 characters in length.	The method call fails. The current setting is invalid.
group	The event group.	The string can be `nil` or an `empty string`. The string can be up to 256 characters in length. If the string exceeds the limit, it is truncated.	N/A
snapshots	The event snapshot.	The string can be `nil` or an `empty string`. The string can be up to 7,000 characters in length. If the string exceeds the limit, it is truncated.	N/A
value	The event value.	The data type is double.	N/A
info	Additional information for the event.	The map can be null or empty. After conversion to JSON, the length must be within 7,000 characters. Otherwise, the method call fails.	N/A

Custom logs

The SDK supports reporting custom logs. You can call the corresponding methods and pass the required parameters to collect statistics on custom logs.

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

Parameter	Description	Parameter limits	Result if failed
logInfo	The log information. This parameter is required.	The string must be 1 to 10,000 characters in length. If the string exceeds the limit, it is truncated.	The method call fails. The current setting is invalid.

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

Parameter	Description	Parameter limits	Result if failed
logInfo	The log information. This parameter is required.	The string must be 1 to 10,000 characters in length. If the string exceeds the limit, it is truncated.	The method call fails. The current setting is invalid.
name	The log name.	The string must be 1 to 256 characters in length.	N/A

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

Parameter	Description	Parameter limits	Result if failed
logInfo	The log information. This parameter is required.	The string must be 1 to 10,000 characters in length. If the string exceeds the limit, it is truncated.	The method call fails. The current setting is invalid.
name	The log name.	The string must be 1 to 256 characters in length.	N/A
snapshots	The log snapshot.	The string can be null or empty. The string can be up to 7,000 characters in length. If the string exceeds the limit, it is truncated.	N/A

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

Parameter	Description	Parameter limits	Result if failed
logInfo	The log information. This parameter is required.	The string must be 1 to 10,000 characters in length. If the string exceeds the limit, it is truncated.	The method call fails. The current setting is invalid.
name	The log name.	The string must be 1 to 256 characters in length.	N/A
snapshots	The log snapshot.	The string can be null or empty. The string can be up to 7,000 characters in length. If the string exceeds the limit, it is truncated.	N/A
level	The log level.	The string must be 1 to 256 characters in length. The default value is INFO.	N/A
info	Additional information for the log.	The map can be null or empty. After conversion to JSON, the string length is counted towards the total size of logInfo. Otherwise, the API call will fail.	N/A