com.vaadin.pro.licensechecker.dau

Class DauIntegration

java.lang.Object

com.vaadin.pro.licensechecker.dau.DauIntegration

public final class DauIntegration
extends Object

API to integrate an application with Daily Active User (DAU) tracking.

A Daily Active User represents a human end-user using applications a customer built with Vaadin during a 24h period. This component provides an API to track and synchronize daily active user data with Vaadin License Server.

DAU requires a valid subscription key, to be provided either as system property, environment variable or file in Vaadin home folder. See LocalSubscriptionKey javadoc for details.

See Also:

LocalSubscriptionKey

Constructor Summary

Constructors

Constructor and Description
DauIntegration()

Method Summary

Modifier and Type	Method and Description
static void	checkSubscriptionKey() Checks if a valid subscription key is available.
static String	newTrackingHash() Creates a new hashed identifier to track a potential Daily Active User of the application.
static boolean	shouldEnforce() Tells whether new user, i.e.
static void	startTracking(String applicationName) Starts Daily Active User tracking for the calling application.
static void	stopTracking() Stops Daily Active User tracking for the calling application.
static void	trackUser(String trackingHash) Registers the user identified by the provided hash as a Daily Active User, adding it to the DAU tracking data set.
static void	trackUser(String trackingHash, String userIdentity) Registers the user identified by the provided tracking hash and user identity as a Daily Active User, adding it to the DAU tracking data set, or assigns the identity to an existing "anonymous" tracked user.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

DauIntegration

public DauIntegration()

Method Detail

startTracking

public static void startTracking(String applicationName)

Starts Daily Active User tracking for the calling application.

On start, License Server is queried to verify subscription key validity and enforcement status. If checks are passed, a background Job is started to synchronize DAU data and get updated enforcement information at regular intervals (24 hours).

This method is usually called once at application startup. Subsequent calls to the method have no effects, unless tracking has been stopped calling stopTracking() method; in this case an exception will be thrown.

Parameters:

applicationName - name of the application associated to the subscription key.

Throws:

LicenseException - if subscription key is not available or invalid.

IllegalStateException - if invoked after a call to stopTracking()

stopTracking

public static void stopTracking()

Stops Daily Active User tracking for the calling application.

On stop, a last synchronization with License Server is attempted, to flush remaining DAU data.

This method is usually called once at application shutdown. Subsequent calls to the method have no effects. After tracking is stopped it cannot be restarted.

newTrackingHash

public static String newTrackingHash()

Creates a new hashed identifier to track a potential Daily Active User of the application.

The returned value is hashed with the SubscriptionKey and must be used for subsequent interactions with DAU tracking API. Creating a new tracking hash user does not imply a tracking entry to be added to DAU data collection. To add the user to the tracking data set, the application must call trackUser(String) )}, providing the tracking hash.

Returns:

a unique identifier to be used for DAU tracking API interaction.

Throws:

LicenseException - if subscription key is invalid or expired

trackUser

public static void trackUser(String trackingHash)
                      throws EnforcementException

Registers the user identified by the provided hash as a Daily Active User, adding it to the DAU tracking data set.

When a user is tracked, the enforcement rule is evaluated and a EnforcementException is thrown if enforcement is required and the number of new users exceeds the limit.

Calling this method multiple times with the same trackingHash has no effect, unless the DAU data set has been flushed or enforcement is already applied to the user.

Parameters:

trackingHash - the user tracking identifier

Throws:

EnforcementException - if enforcement should be applied by the client.

trackUser

public static void trackUser(String trackingHash,
                             String userIdentity)

Registers the user identified by the provided tracking hash and user identity as a Daily Active User, adding it to the DAU tracking data set, or assigns the identity to an existing "anonymous" tracked user.

A tracking hash can potentially be associated to different user identities, for example if during the same browser session a user accesses the application with different credentials.

The userIdentity value is never stored as is, but it is hashed with the SubscriptionKey in order to prevent sensible information to be kept in memory or sent to the License Server.

It the user was previously tracked without a user identity, the linked entry will replace the anonymous one. However, if the tracked user is already linked to different identities, it will be counted as a new user. null or blank are intended as "anonymous" users and a new tracking entry is created only if the tracking hash is not know to the system.

Parameters:

trackingHash - the user tracking identifier

userIdentity - a string that allow to identify an application authenticated user

Throws:

EnforcementException - if enforcement should be applied by the client.

checkSubscriptionKey

public static void checkSubscriptionKey()

Checks if a valid subscription key is available.

Throws:

LicenseException - if subscription key is not available or invalid.

shouldEnforce

public static boolean shouldEnforce()

Tells whether new user, i.e. not yet tracked and not yet counted, should be blocked immediately.

Returns:

true if the current request/user should be blocked, false otherwise.