com.webtrends.mobile.analytics.rim
Class WebtrendsDataCollector

The WebtrendsDataCollector class manages all the data collection methods. WebtrendsDataCollector
follows a singleton design pattern, meaning that an application can only create one instance of the class. Before you invoke
any of the data collection methods, you must create an instance of WebtrendsDataCollector,
and invoke Initialize().

When you invoke one of the data collection methods, your application sends information about the event to the data
collection server, which displays the data on the web portal for you to view.
All of the data collection methods include a customData argument, which is a Hashtable object that
is designed to contain custom parameters that describe an event. Some of the methods require this argument
to be able to populate reports effectively, and some of the methods do not support this argument.

For more information about the parameters that your application sends, and the reports that you can view, see the
BlackBerry Analytics Service Development Guide at
www.blackberry.com/go/analyticsdocs.

getInstance

Creates a singleton instance of WebtrendsDataCollector. If an instance of WebtrendsDataCollector
has already been created, getInstance() returns a reference to the object.

Returns:

A singleton instance of WebtrendsDataCollector.

setConfigured

public static void setConfigured(boolean configured)

Turns on or turns off data collection in an application. The default value is true. This setting
is not persisted after the application closes, so you must make sure to save this setting to the file system if necessary.

Parameters:

configured - Specify to turn on data collection, and specify to turn off data collection.

The following code sample demonstrates how to manually track instances that an application starts,
or moves to the foreground.

//Flag that is used to check whether the application is starting for the first time,
//or if it's a move from the background to foreground.
private boolean AppStartHappened = false;
public void activate()
{
//Executed if this is a transition from background to foreground
if(AppStartHappened)
{
try
{
WebtrendsDataCollector.getInstance().onApplicationForeground("Analytics Demo", null);
}
catch (IllegalWebtrendsParameterValueException err)
{
WebtrendsDataCollector.getLog().e(err.getMessage());
}
}
//Executed if this is the application starting up
else
{
try
{
WebtrendsDataCollector.getInstance().onApplicationStart("Analytics Demo", null);
}
catch (IllegalWebtrendsParameterValueException err)
{
WebtrendsDataCollector.getLog().e(err.getMessage());
}
AppStartHappened=true;
}
super.activate();
}

This method sends data to the following reports in the Analytics Service Web Portal: Events, Screens, App System Events . Events receives the following parameters: WT.ev, WT.sys, WT.ti. Screens receives the following parameters: WT.pi, WT.ti. App System Events receives the following parameters: WT.sys.

Parameters:

applicationName - The name of your application. If you don't provide a name, the application uses the application name specified in the config file.

customData - A hashtable containing custom metadata. Custom metadata is not supported for this method, so specify null.

This method sends data to the following reports in the Analytics Service Web Portal: Events, Screens, App System Events . Events receives the following parameters: WT.ev, WT.sys, WT.ti. Screens receives the following parameters: WT.pi, WT.ti. App System Events receives the following parameters: WT.sys.

Parameters:

applicationName - The name of your application. If you don't provide a name, the application uses the application name specified in the config file.

customData - A hashtable containing custom metadata. Custom metadata is not supported for this method, so specify null.

This method sends data to the following reports in the Analytics Service Web Portal: Events, Screens, App System Events . Events receives the following parameters: WT.ev, WT.sys, WT.ti. Screens receives the following parameters: WT.pi, WT.ti. App System Events receives the following parameters: WT.sys.

Parameters:

applicationName - The name of your application. If you don't provide a name, the application uses the application name specified in the config file.

customData - A hashtable containing custom metadata. Custom metadata is not supported for this method, so specify null.

The following code sample demonstrates how to manually track instances that an application starts,
or moves to the foreground.

//Flag that is used to check whether the application is starting for the first time,
//or if it's a move from the background to foreground
private boolean AppStartHappened = false;
public void activate()
{
//Executed if this is a transition from background to foreground
if(AppStartHappened)
{
try
{
WebtrendsDataCollector.getInstance().onApplicationForeground("Analytics Demo", null);
}
catch (IllegalWebtrendsParameterValueException err)
{
WebtrendsDataCollector.getLog().e(err.getMessage());
}
}
//Executed if this is the application starting up
else
{
try
{
WebtrendsDataCollector.getInstance().onApplicationStart("Analytics Demo", null);
}
catch (IllegalWebtrendsParameterValueException err)
{
WebtrendsDataCollector.getLog().e(err.getMessage());
}
AppStartHappened=true;
}
super.activate();
}

This method sends data to the following reports in the Analytics Service Web Portal: Events, Screens, App System Events . Events receives the following parameters: WT.ev, WT.sys, WT.ti. Screens receives the following parameters: WT.pi, WT.ti. App System Events receives the following parameters: WT.sys.

Parameters:

applicationName - The name of your application. If you don't provide a name, the application uses the application name specified in the config file.

customData - A hashtable containing custom metadata. Custom metadata is not supported for this method, so specify null.

onApplicationError

Tracks instances that errors occur in an application. This method requires that you pass
in the WT.er parameter by using a Hashtable object. The following code sample demonstrates
how to invoke onApplicationError().

This method sends data to the following reports in the Analytics Service Web Portal: Screens, App System Events, Errors. Screens receives the following parameters: WT.pi, WT.ti. App System Events receives the following parameters: WT.sys. Errors receives the following parameters: WT.er, WT.sys.

Parameters:

applicationName - The name of your application. If you don't provide a name, the application uses the application name specified in the config file.

This method sends data to the following reports in the Analytics Service Web Portal: Categories, Events, Screens, App System Events . Categories receives the following parameters: WT.cg_n. Events receives the following parameters: WT.ev, WT.sys, WT.ti. Screens receives the following parameters: WT.pi, WT.ti. App System Events receives the following parameters: WT.sys.

Parameters:

eventPath - The hierarchical location of where an object or screen is located in an application (for example, "mainscreen/optionscreen/samplemedia").

eventDesc - The name of the screen where the event occurs.

eventType - The event type.

customData - A hashtable containing custom metadata. Custom metadata is not supported for this method, so specify null.

contentGroup - A category name for the screen (for example, "sports" or "music").

This method sends data to the following reports in the Analytics Service Web Portal: Events, Screens, App System Events, In-App Ad Performance. Events receives the following parameters: WT.ev, WT.sys, WT.ti. Screens receives the following parameters: WT.pi, WT.ti. App System Events receives the following parameters: WT.sys. In-App Search receives the following parameters: WT.oss, WT.oss_r.

Parameters:

eventPath - The hierarchical location of where an object or content is located in an application
(for example, "mainscreen/optionscreen/samplemedia").

eventDesc - The name of the screen where the event occurs.

eventType - The event type.

customData - A hashtable containing custom metadata. Custom metadata is not supported for this method,
so specify null.

searchPhrase - The search phrase that the user specifies.

searchResult - A String containing a number that represents the number of search results returned.

Tracks instances that a user views a product that an application offers. This method requires that you pass
in the WT.tx_e and WT.tx_u parameters by using a Hashtable object.
Set the value of WT.tx_e to "v", and the value of WT.tx_u to number of product views. The following code sample demonstrates
how to invoke onProductView().

This method sends data to the following reports in the Analytics Service Web Portal: Categories, Events, Screens, App System Events, Media Plays by Media Title, Media Plays by Media Type. Categories receives the following parameters: WT.cg_n. Events receives the following parameters: WT.ev, WT.sys, WT.ti. Screens receives the following parameters: WT.pi, WT.ti. App System Events receives the following parameters: WT.sys. Media Plays by Media Title receives the following parameters: WT.clip_ev, WT.clip_n. Media Plays by Media Type receives the following parameters: WT.clip_ev, WT.clip_t.

Parameters:

eventPath - The hierarchical location of where an object or content is located in an application (for example, "mainscreen/optionscreen/samplemedia").

eventDesc - The name of the screen where the event occurs.

eventType - The event type.

customData - A hashtable containing custom metadata. Custom metadata is not supported for this method, so specify null.

contentGroup - A category name for the content (for example, "sports" or "music").

This method sends data to the following reports in the Analytics Service Web Portal: Categories, Events, Screens, App System Events, Conversion Events. Categories receives the following parameters: WT.cg_n. Events receives the following parameters: WT.ev, WT.sys, WT.ti. Screens receives the following parameters: WT.pi, WT.ti. App System Events receives the following parameters: WT.sys. Conversion Events receives the following parameters: WT.conv.

Parameters:

eventPath - The hierarchical location of where an object or content is located in an application (for example, "mainscreen/optionscreen/samplemedia").

eventDesc - The name of the screen where the event occurs.

eventType - The event type.

customData - A hashtable containing custom metadata. Custom metadata is not supported for this method, so specify null.

contentGroup - A category name for the content (for example, "sports" or "music").

This method sends data to the following reports in the Analytics Service Web Portal: Events, App System Events . Events receives the following parameters: WT.ev, WT.sys, WT.ti. App System Events receives the following parameters: WT.sys.

Parameters:

eventPath - The hierarchical location of where an object or content is located in an application (for example, "mainscreen/optionscreen/samplemedia").

eventDesc - The name of the screen where the event occurs.

eventType - The event type.

customData - A hashtable containing custom metadata. Custom metadata is not supported for this method, so specify null.

onCustomEvent

Tracks instances that custom events occur in an application. This method requires that you pass
in the WT.ev parameter by using a Hashtable object. The WT.ev
parameter represents the event type, and you can specify any String as the value.
The following code sample demonstrates how to invoke onCustomEvent().

This method sends data to the following reports in the Analytics Service Web Portal: Events, Screens, App System Events . Events receives the following parameters: WT.ev, WT.sys, WT.ti. Screens receives the following parameters: WT.pi, WT.ti. App System Events receives the following parameters: WT.sys. Outbound Links receives the following parameters: WT.ev, WT.ti.

Parameters:

eventPath - The hierarchical location of where an object or content is located in an application (for example, "mainscreen/optionscreen/samplemedia").

eventDesc - The name of the screen where the event occurs.

customData - A hashtable containing custom metadata. Custom metadata is not currently supported, so specify null.