Analytics

Glossary Item Box

Analytics adds pre-built application usage tracking, exception reporting, binary tamper detection, and application expiration to your applications without requiring any additional code. Dotfuscator and Analytics injects the required code for you. You can define injection points either via custom attributes in your source code or via extended attributes specified within the Dotfuscator and Analytics user interface.

The Analytics editor allows you to add, edit, and review custom and extended attributes.  In Dotfuscator and Analytics CE, the Analytics editor displays three configuration tabs: the Getting Started tab, the Attributes tab and the Options tab.  The Getting Started tab describes the various analytics options available and how to configure them.  The Attributes tab is where you add new extended attributes to methods or modify custom attributes that are already present. The Options tab is where you select which types of messages - application analytics, shelf life notification, and tamper alert - you want to send to the Runtime Intelligence Service.

Assembly Attributes

Assembly attributes are attributes that may be applied at the assembly level.  Assembly attributes are used by the code injection process to add unique identification data to an assembly, such as company information, or to track exceptions across the entire assembly.

Required Assembly Attributes

To instrument your application for Runtime Intelligence Services, there are two required assembly attributes.  These attributes are added to the application by right clicking on an assembly node in the Select the attribute to modify: tree.

BusinessAttribute

The BusinessAttribute is required and contains values that are used to identify the company that owns the application being instrumented.  This attribute consists of a CompanyKey, which should be set to "7d2b02e0-064d-49a0-bc1b-4be4381c62d3" for use with the Free Runtime Intelligence Services Portal.  For your convenience, the CompanyKey is set to this GUID by default. If you target a different endpoint, please use the CompanyKey provided by PreEmptive Solutions or generate a new unique identifier by pressing the "..." button associated with the CompanyKey entry area. The CompanyName may be left empty; however, you are encouraged to enter the name of the company for Runtime Intelligence Services Portal personalization.

ApplicationAttribute

The ApplicationAttribute is required and contains values that are used to identify the instrumented application:

• ApplicationType. This identifies the type of application being instrumented such as a Windows application. 
• GUID. This is a unique identifier for the application that is generated by clicking the "..." in this field. 
• Name. This is the name of the application.  If you leave this blank, the name will be filled in via reflection (if allowed at runtime). Only fill it in if you want a name in the portal that is different from the name in the assembly, or if reflection can't be used by your application at runtime (e.g. it is a Silverlight application).
• Version.This is the version of the application. If you leave this blank, the name will be filled in via reflection (if allowed at runtime). Only fill it in if you want a version in the portal that is different from the version in the assembly, or if reflection can't be used by your application at runtime (e.g. it is a Silverlight application).

BinaryAttribute

The BinaryAttribute contains a value that is used to identify the specific assemblies that make up the instrumented application. The GUID is the unique identifier for the assembly and is used to specify which assembly was altered when tampering was detected. Although this attribute is not required, if you are using tamper detection, you should set a binary attribute on each assembly so the notifications can include the assembly information.

ExceptionTrackAttribute (Assembly level)

The ExceptionTrackAttribute is used to track unhandled exceptions at both the assembly and method level. The assembly level ExceptionTrackAttribute can be used to detect exceptions that occur anywhere in an assembly.  When Dotfuscator and Analytics encounters an ExceptionTrackAttribute, it adds code that detects unhandled exceptions by registering an UnhandledException event handler on the current AppDomain (for .NET Framework applications) or current Application (for Silverlight applications). A explicit exception report opt-in can be set through a built-in or custom-built exception dialog, which can also present a privacy policy URI and collect end user contact information or information about the context in which the exception happened as written by the end user.

Functional Attributes

Functional Attributes can be used to track application stability, feature usage, tampering attempts, and the frequency of an application's use. They may also be used to make an application cease to function after a specified date.

SetupAttribute

The SetupAttribute is used to track when an application has started. Dotfuscator and Analytics injects startup code for message sending and sends the startup message. There must be one or more methods with this attribute in an assembly or application that uses Runtime Intelligence. This attribute should be placed as closely as possible to the normal application startup logic. At runtime, the functionality generated by this attribute will begin sending usage data back to the Runtime Intelligence Services Portal. Optionally, you may specify the location in your code of functionality that controls the transmission of messages (opt-in or opt-out behavior). Dotfuscator and Analytics will use this information when generating the initialization code.

When you add the SetupAttribute, you may set the Custom Endpoint destination of the messages.The endpoint options include the free Runtime Intelligence Services Portal as a default, the commercially available Runtime Intelligence Services Portal, or a custom endpoint of your own choosing.

The SetupAttribute also provides the ability to implement either opt-in or opt-out functionality within your application. This functionality enables your users to elect to provide their usage data or not. To provide the setting determining if execution and usage data will be collected and sent to the Runtime Intelligence Services Portal, you can specify either a method, method argument, field, or property containing or returning a boolean value. If the value is true then the application will transmit usage data as configured. If the value is false then no usage data will be transmitted by the application.

To configure the opt-in/opt-out behavior you must configure the OptInSourceElement property with the appropriate type of code element that will contain the Boolean value. The OptInSourceName must be the name of the element that contains the Boolean value to be used to determine if Runtime Intelligence data will be collected and transmitted. At runtime, the source value should be set by your application code before the setup method is called. The OptInSourceOwner property may be left off if the element is defined in the same class as the method attributed with the SetupAttribute. If the OptInSourceElement is a method argument then it must correspond to a method parameter on the method that is annotated with the SetupAttribute.

TeardownAttribute

The TeardownAttribute is used to track when an application has successfully stopped.  Dotfuscator and Analytics injects teardown code for message sending and sends the shutdown message. There must be one or more methods with this attribute in an assembly or application that uses Runtime Intelligence analytics. The teardown method does not necessarily have to be the last method called, but it should have the property that it is executed exactly once when the application shuts down, as close as possible to exit.

FeatureAttribute

The FeatureAttribute is for tagging features you wish to track using the Runtime Intelligence Service. This attribute may be placed on any method or property. Runtime Intelligence tracks features using the name provided in this property. Multiple methods can be given the same name which will cause the same usage indicator on the Runtime Intelligence Services Portal to be updated. A feature can be either an atomic event or the execution duration can be measured.  To simply track that a feature has been executed, use a FeatureEventType of 'Tick.' To measure the execution duration of the feature, use two feature attributes with the same name, one with a FeatureEventType of 'Start' and the second with a FeatureEventType of 'Stop.' In the Feature Scorecard report on the Portal, you will see the minimum, maximum, and average durations for each feature execution. 

InsertShelfLifeAttribute

Add an InsertShelfLifeAttribute to any property or method where you would like an application expiration check to occur. At runtime, your application can send an expiration notification message to the Runtime Intelligence Services Portal if the application is executed after the expiration date has occurred. Upon expiration, the default behavior is to send the expiration notification message; however, you may set the ExpirationNotificationSinkElement property to DefaultAction, which will optionally send an expiration message to the Runtime Intelligence Services Portal and cause the application to immediately exit. In order for the expiration notification messages to be sent, the application must contain methods marked with a Setup and Teardown attribute.

A Shelf Life Activation Key (SLAK) is required to instrument your application with this feature. To obtain a SLAK, please go to our Support site: https://www.preemptive.com/support/index.html.

InsertSignofLifeAttribute

The InsertSignofLifeAttribute sends a message each time the method tagged with this attribute is called. At runtime, the sign of life code sends a message indicating that the application has been executed.  In order to use this attribute, the application must contain methods marked with a Setup and Teardown attribute.

A Shelf Life Activation Key (SLAK) is required to instrument your application with this feature. To obtain a SLAK, please go to our Support site: https://www.preemptive.com/support/index.html.

InsertTamperCheckAttribute

The InsertTamperCheckAttribute injects code that detects if a user has modified your assemblies. If it detects that the assemblies have been altered, it can send a tamper notification message to the Runtime Intelligence Services Portal. Upon detection, the default behavior is to send the tamper notification message and exit the application; however, you may set the ApplicationNotificationSinkElement property to DefaultAction, which will cause the application to immediately exit. If you wish to send Runtime Intelligence tamper messages, do not put this attribute on the same method containing the Setup Attribute. Also, ensure that any methods marked with the tamper check attribute are executed after the method containing the setup attribute.

ExceptionTrackAttribute (Method level)

The method level ExceptionTrackAttribute can be used to detect locally unhandled exceptions that pass through a particular method. When Dotfuscator and Analytics encounters a method level ExceptionTrackAttribute, it adds code that wraps the method in a try/catch block and re-throws the exception. Method-level ExceptionTrackAttributes can collect the same opt-in and extra information as assembly level ExceptionTrackAttributes. 

Analytics Options

The Analytics Options tab is where you may configure the behavior of your instrumented applications. Instrumentation (code injection) of your applications may be enabled or disabled for your current project by either un-checking the Process PreEmptive analytics attributes check box, or by right clicking on Analytics in the navigation tree and un-checking the Enable option. If this option is unchecked, Dotfuscator will not perform code injection when your project is built.

The Runtime Intelligence configuration section of this tab is where you may select which message types will be sent to the Runtime Intelligence Services Portal.  The Send application analytics messages option enables the sending of messages related to feature usage. The Send shelf life notification messages option enables the sending of shelf life expiration and sign of life messages. The Send tamper alert messages option enables the sending of tamper notification messages.  Un-checking either the Shelf Life or Tamper message options will only affect the transmission of those messages; if you have selected the DefaultAction to occur, your application will still exit as expected.

See Also

PreEmptive Solutions Support

© 2002-2012 PreEmptive Solutions. All rights reserved.