UI Event Transactions
We recommend implementing this feature for mobile and desktop SDKs.
UI event transactions aim to capture transactions based on user interactions, such as clicks, scroll events, pinches, etc. The UI events the SDK can hook into might vary depending on the platform. UI event transactions are an expansion to transactions generated automatically by the SDK, which are referred to as auto-generated transactions in this document.
Creating transactions for a single UI event without any spans would be fruitless. Instead, the SDK shall use a UI event as the entry point to a possibly meaningful transaction. It should wait to see if it can add any auto-generated spans to the transaction. If it can, it shall keep and send the transaction. If not, the SDK should discard the empty transaction. A combination of two concepts is needed to implement the wait-and-see logic: idle transactions and wait-for-children. Check out the specification below to see how those two concepts work together with covering multiple edge cases. The following description is drastically simplified:
- Idle-transactions: The SDK starts an idle timeout for the transaction when starting it. When the transaction or any of its spans starts a new span, it resets the timeout. The SDK finishes the transaction when the timeout succeeds.
- Wait-for-children: A transaction waits for all its child spans to finish before finishing itself.
Before diving into the specification with all the edge cases, let's look at two simple examples:
- The user clicks a button that triggers some requests to the backend and stores data in the local database. The SDK can create a meaningful transaction in that case.
- The user clicks a button that solely validates some form data and triggers nothing that the SDK can automatically instrument. The SDK could only create a transaction without any spans, which would be valueless.
Specification
Users can change the idleTimeout via the SDK config options. The default is 3.0 seconds.
The specification is written in the Gherkin syntax.
1. Starting UI Event transactions
Given an instrumentable UI event
Then the SDK starts a UI event transaction
And starts the idle timeout with idleTimeout of the options5. Wait for children when starting span
Given a UI event transaction
When the SDK starts a child span
Then the SDK cancels the idle timeout
And waits for the child to finish4. Start timeout when the last span finishes
Given a UI event transaction
And the transaction has one or multiple running child spans
And the transaction is waiting for its children to finish
When the SDK finishes the last child span
Then the SDK starts the idle timeout3. Don't reset timeout when the second last span finishes
Given a UI event transaction
And the transaction has two running child spans
When the SDK finishes the first child span
Then the SDK doesn't reset the idle timeout
And waits for the children to finish2. Discard UI event transactions without child spans
Given a UI event transaction
And the transaction has no child spans
When the idleTimeout times out
Then the SDK discards the transaction 3. Set time to last finished child span
Given a UI event transaction
And the transaction has one finished child span
And the transaction has one running child span
When the running child span finishes
Then the SDK finishes the transaction
And trims the end time of the transaction to the one of the last finished child span6. Same UI element with same event
Given an ongoing UI event transaction
When the user triggers the same UI event with the same type for the same UI element
Then the SDK resets the timeout
And doesn't create a new transaction10. Same UI element with different event If your SDK binds transactions to the scope see 11.
Given an ongoing UI event transaction
When the user triggers the same UI element with a different event
Or the user triggers a different UI element
Then the SDK finishes the ongoing transaction
And sets the status to OK
And waits for the children to finish
And cancels the timeout
And starts a new transactionBinding to scope
11. Same UI element with different event
Given an ongoing UI event transaction
When the user triggers the same UI element with a different event
Or the user triggers a different UI element
Then the SDK finishes the ongoing transaction
And sets the status to OK
And waits for the children to finish
And cancels the timeout
And removes the ongoing transaction from the scope
And starts a new transaction
And puts the new transaction on the scope11. UI event triggered but transaction ended
Given an auto-generated transaction from a any event
And the transaction finished
When the user triggers the same event
Then the SDK starts a new transaction6. Ongoing screen load transaction
Given an ongoing screen load transaction
When the SDK starts a new UI event transaction
Then the SDK doesn't bind the new UI event transaction to the scope7. Ongoing UI event transaction
Given an ongoing UI event transaction
When the SDK creates a new screen load transaction
Then the SDK finishes the ongoing UI event transaction
And removes it from the scope
And sets the status to canceled
And waits for its children to finish8. Manually created transaction on the scope
Given an ongoing manually transaction bound to the scope by the user
When the SDK creates a new auto-generated transaction
Then the SDK doesn't add the new auto-generated transaction to the scope Transaction name
12. Transaction name
When the user clicks a button
Then the SDK starts a transaction
And the transaction name is the [[screen.name](http://screen.name/)](http://screen.name) + [[view.id](http://view.id/)](http://view.id) or the accessibility identifier of the view (e.g. `LoginActivity.login_button`)13. Transaction name [view.id](http://view.id/) or accessibility identifier not specified
When the user clicks a button
And the button has no [[view.id](http://view.id/)](http://view.id) or accessibility identifier
Then the SDK doesn't start a transaction
And prints a warning to the console