Class AnalyticsSystem

• Defined in File AnalyticsSystem.h

Inheritance Relationships

Base Type

• public csp::systems::SystemBase (Class SystemBase)

Class Documentation

class AnalyticsSystem : public csp::systems::SystemBase

Public facing system that allows AnalyticsRecords to be sent to the backend services.

Invariant

Users must be logged in to send AnalyticsRecords to the backend services.

Public Functions

void QueueAnalyticsEvent(const csp::common::String &ProductContextSection, const csp::common::String &Category, const csp::common::String &InteractionType, const csp::common::Optional<csp::common::String> &SubCategory, const csp::common::Optional<csp::common::Map<csp::common::String, csp::common::String>> &Metadata)

Constructs an Analytics Record which is added to a queue to be sent to the backend services in a single batch.

The queue will be sent when one of the following conditions are met:

1. The time since the last batch was sent reaches the AnalyticsQueueSendRate (default 60 seconds).

2. The number of events in the queue reaches the MaxQueueSize threshhold (default 25 events).

3. The client application calls FlushAnalyticsEventsQueue(). Clients should call this as part of their log out or shut down procedure to force the queue to be sent. For more information about flushing events see the method documentation AnalyticsSystem::FlushAnalyticsEventsQueue().

Example: Consider the following user action that is to be captured as an analytics event:

• A [web client] user [clicks] on a [menu] item in the [UI].

In this example:

• [web client] is captured internally.

• [clicks] is the InteractionType.

• [menu] is the Category.

• [UI] is the ProductContextSection.

Note

The following data is captured internally and included in the analytics record:

• tenant name, client sku, client version and client build environment.

Parameters

• ProductContextSection – const csp::common::String& : The specific, high-level functional area or context within the product where the event occurred. This field acts as a primary identifier for the part of the application or system the user is interacting with.

• Category – const csp::common::String& : Categorization field which acts as a namespace for the InteractionType. It provides a means of grouping similar events, which makes it easier to analyze and filter analytics data.

• InteractionType – const csp::common::String& : Describes the precise and specific interaction that is being tracked. This field identifies what the user did or what happened within the product at a specific moment in time.

• SubCategory – const csp::common::Optional<csp::common::String>& : Optional sub-category field to provide additional context if required.

• Metadata – const csp::common::Optional<csp::common::Map<csp::common::String, csp::common::String>>& : Optional analytics event metadata. Metadata is the event payload. It may be used to store such information as the space the user is in, their geographical region, as well as relevant device specs.

Pre

The user must be logged in to send Analytics Records to the backend services.

void SendAnalyticsEvent(const csp::common::String &ProductContextSection, const csp::common::String &Category, const csp::common::String &InteractionType, const csp::common::Optional<csp::common::String> &SubCategory, const csp::common::Optional<csp::common::Map<csp::common::String, csp::common::String>> &Metadata, NullResultCallback Callback)

Constructs an Analytics Record which is immediately sent to the backend services.

For more information about how the Analytics Record is constructed, see the documentation for AnalyticsSystem::QueueAnalyticsEvent().

Note

The QueueAnalyticsEvent method should be used by default as it will queue events before sending them. This method will immediately send the analytics event and should therefore only be used when this behaviour is required.

Parameters

• ProductContextSection – const csp::common::String& : The specific, high-level functional area or context within the product where the event occurred. This field acts as a primary identifier for the part of the application or system the user is interacting with.

• Category – const csp::common::String& : Categorization field which acts as a namespace for the InteractionType. It provides a means of grouping similar events, which makes it easier to analyze and filter analytics data.

• InteractionType – const csp::common::String& : Describes the precise and specific interaction that is being tracked. This field identifies what the user did or what happened within the product at a specific moment in time.

• SubCategory – const csp::common::Optional<csp::common::String>& : Optional sub-category field to provide additional context if required.

• Metadata – const csp::common::Optional<csp::common::Map<csp::common::String, csp::common::String>>& : Optional analytics event metadata. Metadata is the event payload. It may be used to store such information as the space the user is in, their geographical region, as well as relevant device specs.

• Callback – NullResultCallback : the callback to execute on completion of the send operation.

Pre

The user must be logged in to send Analytics Records to the backend services.

void FlushAnalyticsEventsQueue(NullResultCallback Callback)

Trigger immediate dispatch of the Analytics Records queue to the backend services.

Note

This method should be called as part of client log out or shut down procedure to ensure that any queued analytics records are flushed and sent to the backend services before the user is logged out or the application is shut down.

Parameters

Callback – NullResultCallback : the callback to execute on completion of the flush operation.

Pre

The user must be logged in to send an Analytics Record to the backend services.

inline std::chrono::milliseconds GetTimeSinceLastQueueSend() const

Retrieves the time since the queue was last sent.

Returns

std::chrono::milliseconds : time since epoch in milliseconds.

inline std::chrono::milliseconds GetQueueSendRate() const

Retrieves the rate at which the queued Analytics Records are sent.

Returns

std::chrono::milliseconds : send rate in milliseconds.

inline size_t GetCurrentQueueSize() const

Retrieves the current size of the Analytics Records queue.

Returns

size_t : the queue size.

inline size_t GetMaxQueueSize() const

Retrieves the max permitted size of the Analytics Records queue.

If the queue size reaches this value, the queue will be sent as a single batch to the backend services.

Returns

size_t : the queue size at which a batch will be sent.