Instabug automatically captures any UI hangs happening in your app. A hang is when the app isn't responding to the user's input for more than 250 ms.

The SDK automatically groups and aggregates data based on the screen name, which is the name of your UIViewController class. A visit starts when your viewDidAppear is called and ends when viewWillDisapear is called. Screen visits are referred to as Auto UI Traces. You can create Custom UI Traces as explained here.

For every screen visit, the SDK reports the duration percentage during which the user encountered UI hangs. Let's take an example:

• A user visits your home screen and stays there for 10000 ms.
• During this screen visit, they encountered three hang incidents. The first one lasted 250 ms, the second one lasted 300 ms, and the last one lasted 400 ms. Tho accumulative hang duration for this screen visit is 250+300+400=950 ms. That means the hang % is 950 / 10000 = 9.5%.

Custom UI Traces

In case you are looking for more control over how occurrences are grouped, you can create your own groups with custom names by leveraging the relevant start and stop APIs. It is worth mention that:

• You can run only one custom UI trace at a given time; a trace must be ended before a new one can be started.
• The SDK will end any occurrence that wasn't explicitly ended via the end API.

Start Custom UI Trace

You can use the API below to mark the start of a UI trace occurrence. It takes as input a trace name that we use to aggregate the data of relevant occurrences together on your dashboard. Please note the following:

• Trace name can be up to 150 characters. Any extra characters are truncated.
• Trace name can't be nil or an empty string.
• Avoid adding any of these special characters [, (, ), =, {, }, <, >, /, , ] (commas not included) as they will be replaced with _.
• Starting a new trace has to be done after initializing the SDK.

APM.startUITrace(withName: "name")

[IBGAPM startUITraceWithName:@"name"];

End Custom UI Trace

Use the API below to end the trace occurrence that you have already started:

APM.endUITrace()

[IBGAPM endUITrace];

📘

Please note that Custom UI Traces do not interfere with Automatic UI Traces, both can run in parallel.

UI Hangs Apdex

Instabug calculates an apdex score for any UI trace in your app, whether it is an automatically detected screen or a custom UI trace that you defined. Apdex score ranges between 0 and 1. The higher the value, the closer you are to satisfying user experience:

• Apdex score ≥ 0.94 equates to Excellent performance.
• Apdex score ≥ 0.85 and < 0.94 equates to Good performance.
• Apdex score ≥ 0.7 and < 0.85 equates to Fair performance.
• Apdex score ≥ 0.5 and < 0.7 equates to Poor performance.
• Apdex score < 0.5 is considered Unacceptable.

How Is the UI Trace Apdex Calculated?

When a screen visit or custom UI trace occurrence is collected, it is flagged based as follows:

• Satisfying: if its hang% ≤ 2%
• Tolerable: if its hang% > 2 and ≤ 5%
• Frustrating: its hang% > 5%

Then based on the bucketing explained above, the apdex is calculated:

• Total occurrences = Satisfying occurrences + Tolerable occurrences + Frustrating occurrences
• Apdex score = (Satisfying occurrences + 0.5 * Tolerable occurrences) / Total occurrences

Disabling/Enabling Automatic UI Traces

When APM is enabled in your account, Instabug collects UI hangs out of the box. If needed, you can disable it by calling the following API after initializing the SDK.

APM.UIHangsEnabled = false

IBGAPM.UIHangsEnabled = NO;

📘

Please note that this API does not control Custom UI Traces that you have created, it only toggles Automatic UI Traces on/off.