com.webtrends.mobile.analytics.rim
Class WebtrendsDataCollector

java.lang.Object
  extended by com.webtrends.mobile.analytics.rim.WebtrendsDataCollector

public class WebtrendsDataCollector
extends java.lang.Object

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().

 WebtrendsDataCollector wtDC = WebtrendsDataCollector.getInstance();
 wtDC.Initialize();
 
Each time you invoke one of the data collection methods, you must invoke getInstance() to retrieve a reference to the WebtrendsDataCollector object that you created.
 
 WebtrendsDataCollector.getInstance().onButtonClick("/AnalyticsDemo/Main/", "MainScreen", "click", null);
 
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.


Field Summary
static java.lang.String BUILD_VERSION
           
 
Method Summary
static WebtrendsDataCollector getInstance()
          Creates a singleton instance of WebtrendsDataCollector.
static WebtrendsLogger getLog()
          Retrieves an instance of WebtrendsLogger, which contains information that the application has logged, such as warnings, exceptions, and debug information.
 void Initialize()
          Must be invoked on a WebtrendsDataCollector object before an application can call any of the data collection methods.
 void onActivityEnd(java.lang.String activityName, java.util.Hashtable customData)
          Deprecated. Not for public use.
 void onActivityPause(java.lang.String activityName, java.util.Hashtable customData)
          Deprecated. Not for public use.
 void onActivityStart(java.lang.String activityName, java.util.Hashtable customData)
          Deprecated. Not for public use.
 void onAdClickEvent(java.lang.String eventPath, java.lang.String eventDesc, java.lang.String eventType, java.util.Hashtable customData, java.lang.String adName)
          Tracks instances that a user clicks on an ad in an application.
 void onAdImpressionEvent(java.lang.String eventPath, java.lang.String eventDesc, java.lang.String eventType, java.util.Hashtable customData, java.lang.String[] adNames)
          Tracks instances that a user views an ad in an application.
 void onApplicationBackground(java.lang.String applicationName, java.util.Hashtable customData)
          Invoke this method to track instances that an application moves to the background.
 void onApplicationError(java.lang.String applicationName, java.util.Hashtable customData)
          Tracks instances that errors occur in an application.
 void onApplicationForeground(java.lang.String applicationName, java.util.Hashtable customData)
          Invoke this method to track instances that an application moves to the foreground.
 void onApplicationStart(java.lang.String applicationName, java.util.Hashtable customData)
          Invoke this method to track instances that an application starts.
 void onApplicationTerminate(java.lang.String applicationName, java.util.Hashtable customData)
          Invoke this method to track instances that an application terminates.
 void onButtonClick(java.lang.String eventPath, java.lang.String eventDesc, java.lang.String eventType, java.util.Hashtable customData)
          Tracks instances that a user clicks a button in an application.
 void onContentView(java.lang.String eventPath, java.lang.String eventDesc, java.lang.String eventType, java.util.Hashtable customData, java.lang.String contentGroup)
          Tracks instances that a user views content in an application.
 void onConversionEvent(java.lang.String eventPath, java.lang.String eventDesc, java.lang.String eventType, java.util.Hashtable customData, java.lang.String contentGroup, java.lang.String conversionName)
          Tracks instances that a conversion event occurs in an application.
 void onCustomEvent(java.lang.String eventPath, java.lang.String eventDesc, java.util.Hashtable customData)
          Tracks instances that custom events occur in an application.
 void onMediaEvent(java.lang.String eventPath, java.lang.String eventDesc, java.lang.String eventType, java.util.Hashtable customData, java.lang.String contentGroup, java.lang.String mediaName, java.lang.String mediaType, java.lang.String mediaEventType)
          Tracks instances that media events occur in an application.
 void onProductView(java.lang.String eventPath, java.lang.String eventDesc, java.lang.String eventType, java.util.Hashtable customData, java.lang.String contentGroup, java.lang.String productId, java.lang.String productSku)
          Tracks instances that a user views a product that an application offers.
 void onSearchEvent(java.lang.String eventPath, java.lang.String eventDesc, java.lang.String eventType, java.util.Hashtable customData, java.lang.String searchPhrase, java.lang.String searchResult)
          Tracks instances that a user performs a search in an application.
static void setConfigured(boolean configured)
          Turns on or turns off data collection in an application.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

BUILD_VERSION

public static final java.lang.String BUILD_VERSION
See Also:
Constant Field Values
Method Detail

Initialize

public void Initialize()
Must be invoked on a WebtrendsDataCollector object before an application can call any of the data collection methods.


getInstance

public static WebtrendsDataCollector 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.

getLog

public static WebtrendsLogger getLog()
Retrieves an instance of WebtrendsLogger, which contains information that the application has logged, such as warnings, exceptions, and debug information.


onApplicationStart

public void onApplicationStart(java.lang.String applicationName,
                               java.util.Hashtable customData)
                        throws IllegalWebtrendsParameterValueException
Invoke this method to track instances that an application starts. If you extend your application using WebtrendsUiApplication or WebtrendsApplication, the system invokes this method automatically when an application starts. To invoke this method manually, you must override WebtrendsUiApplication.activate() or WebtrendsApplication.activate().

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();
 }
 

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.
Throws:
IllegalWebtrendsParameterValueException - if an invalid argument is passed to the method.

onApplicationTerminate

public void onApplicationTerminate(java.lang.String applicationName,
                                   java.util.Hashtable customData)
                            throws IllegalWebtrendsParameterValueException
Invoke this method to track instances that an application terminates. To invoke this method, you must override onClose() in a screen for your application.

The following code sample demonstrates how to manually track instances that an application terminates.

 public class AnalyticsDemoScreen extends MainScreen 
 {
     public boolean onClose()
     {
         try 
         {
             WebtrendsDataCollector.getInstance().onApplicationTerminate("Analytics Demo", null);
         } 
         catch (IllegalWebtrendsParameterValueException err) 
         {
             WebtrendsDataCollector.getLog().e(err.getMessage());
         }
         System.exit(0);
         return true;
     }
 }
 

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.
Throws:
IllegalWebtrendsParameterValueException - if an invalid argument is passed to the method.

onApplicationBackground

public void onApplicationBackground(java.lang.String applicationName,
                                    java.util.Hashtable customData)
                             throws IllegalWebtrendsParameterValueException
Invoke this method to track instances that an application moves to the background. If you extend your application using WebtrendsUiApplication or WebtrendsApplication, the system invokes this method automatically when an application moves to the background. To invoke this method manually, you must override WebtrendsUiApplication.deactivate() or WebtrendsApplication.deactivate().

The following code sample demonstrates how to override deactivate() to track instances that an application moves to the background.


 public void deactivate()
 {
     try 
     {
         WebtrendsDataCollector.getInstance().onApplicationBackground("Analytics Demo", null);
     } 
     catch (IllegalWebtrendsParameterValueException err) 
     {
         WebtrendsDataCollector.getLog().e(err.getMessage());
     }
     super.deactivate();
 }
     //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;
     }
     
 }
 

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.
Throws:
IllegalWebtrendsParameterValueException - if an invalid argument is passed to the method.

onApplicationForeground

public void onApplicationForeground(java.lang.String applicationName,
                                    java.util.Hashtable customData)
                             throws IllegalWebtrendsParameterValueException
Invoke this method to track instances that an application moves to the foreground. If you extend your application using WebtrendsUiApplication or WebtrendsApplication, the system invokes this method automatically when an application moves to the foreground. To invoke this method manually, you must override WebtrendsUiApplication.activate() or WebtrendsApplication.activate().

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();
 }
 

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.
Throws:
IllegalWebtrendsParameterValueException - if an invalid argument is passed to the method.

onApplicationError

public void onApplicationError(java.lang.String applicationName,
                               java.util.Hashtable customData)
                        throws IllegalWebtrendsParameterValueException
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().
 try
 {
     //Code that the application is attempting to run.
 }
 catch (Exception e)
 {
     //Creates a Hashtable object containing the exception that is thrown by the application
     Hashtable customParams = new Hashtable();
     customParams.put("WT.er", e.getMessage());    
     
     try
     {
         WebtrendsDataCollector.getInstance().onApplicationError("Analytics Demo", customParams);
     }
     catch (IllegalWebtrendsParameterValueException err)
     {
         WebtrendsDataCollector.getLog().e(err.getMessage());
     }
 }
 

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 required for this method.
Throws:
IllegalWebtrendsParameterValueException - if an invalid argument is passed to the method.

onActivityStart

public void onActivityStart(java.lang.String activityName,
                            java.util.Hashtable customData)
                     throws IllegalWebtrendsParameterValueException
Deprecated. Not for public use.

Invoke this method to track instances that an activity starts.

Parameters:
activityName - - activity name associated with start
customData - - collection of customer defined name/value pairs (optional)
Throws:
IllegalWebtrendsParameterValueException
java.lang.IllegalArgumentException - - in case of malformed arguments

onActivityEnd

public void onActivityEnd(java.lang.String activityName,
                          java.util.Hashtable customData)
                   throws IllegalWebtrendsParameterValueException
Deprecated. Not for public use.

Invoke this method to track instances that an activity ends.

Parameters:
activityName - - activity name associated with end
customData - - collection of customer defined name/value pairs (optional)
Throws:
IllegalWebtrendsParameterValueException
java.lang.IllegalArgumentException - - in case of malformed arguments

onActivityPause

public void onActivityPause(java.lang.String activityName,
                            java.util.Hashtable customData)
                     throws IllegalWebtrendsParameterValueException
Deprecated. Not for public use.

Invoke this method to track instances that an activity pauses.

Parameters:
activityName - - activity name associated with pause
customData - - collection of customer defined name/value pairs (optional)
Throws:
IllegalWebtrendsParameterValueException
java.lang.IllegalArgumentException - - in case of malformed arguments

onContentView

public void onContentView(java.lang.String eventPath,
                          java.lang.String eventDesc,
                          java.lang.String eventType,
                          java.util.Hashtable customData,
                          java.lang.String contentGroup)
                   throws IllegalWebtrendsParameterValueException
Tracks instances that a user views content in an application. The following code sample demonstrates how to invoke onContentView().
 try
 {
     WebtrendsDataCollector.getInstance().onContentView("/eBooksApp/newbook/details", 
             "Book viewer screen", "book view", null, "fiction");
 }
 catch (IllegalWebtrendsParameterValueException err)
 {
     WebtrendsDataCollector.getLog().e(err.getMessage());
 }
 

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").
Throws:
IllegalWebtrendsParameterValueException - if an invalid argument is passed to the method.

onAdClickEvent

public void onAdClickEvent(java.lang.String eventPath,
                           java.lang.String eventDesc,
                           java.lang.String eventType,
                           java.util.Hashtable customData,
                           java.lang.String adName)
                    throws IllegalWebtrendsParameterValueException
Tracks instances that a user clicks on an ad in an application. The following code sample demonstrates how to invoke onAdClickEvent().
 try
 {
     WebtrendsDataCollector.getInstance().onAdClickEvent("/mainscreen/classifieds", "AdClickEvent01", 
             "click", null, "car ad");
 }
 catch (IllegalWebtrendsParameterValueException err)
 {
     WebtrendsDataCollector.getLog().e(err.getMessage());
 }
 

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.
adName - The name of the ad placement.
Throws:
IllegalWebtrendsParameterValueException - if an invalid argument is passed to the method.

onAdImpressionEvent

public void onAdImpressionEvent(java.lang.String eventPath,
                                java.lang.String eventDesc,
                                java.lang.String eventType,
                                java.util.Hashtable customData,
                                java.lang.String[] adNames)
                         throws IllegalWebtrendsParameterValueException
Tracks instances that a user views an ad in an application. The following code sample demonstrates how to invoke onAdImpressionEvent().
 String[] adNames = {"sports ad1", sports ad2", "sports ad3"};
 try
 {
     WebtrendsDataCollector.getInstance().onAdImpressionEvent("/newsapp/topstories",
             "Headline screen", "ad view", null, adNames);
 }
 catch (IllegalWebtrendsParameterValueException err)
 {
     WebtrendsDataCollector.getLog().e(err.getMessage());
 }
 

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.
adNames - An array of ad names.
Throws:
IllegalWebtrendsParameterValueException - if an invalid argument is passed to the method.

onSearchEvent

public void onSearchEvent(java.lang.String eventPath,
                          java.lang.String eventDesc,
                          java.lang.String eventType,
                          java.util.Hashtable customData,
                          java.lang.String searchPhrase,
                          java.lang.String searchResult)
                   throws IllegalWebtrendsParameterValueException
Tracks instances that a user performs a search in an application. The following code sample demonstrates how to invoke onSearchEvent().
 try
 {
     WebtrendsDataCollector.getInstance().onSearchEvent("/GPSapp/newlocation",
             "Navigation screen", "search", null, "Waterloo", "1");
 }
 catch (IllegalWebtrendsParameterValueException err)
 {
     WebtrendsDataCollector.getLog().e(err.getMessage());
 }
 

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.
Throws:
IllegalWebtrendsParameterValueException - if an invalid argument is passed to the method.

onProductView

public void onProductView(java.lang.String eventPath,
                          java.lang.String eventDesc,
                          java.lang.String eventType,
                          java.util.Hashtable customData,
                          java.lang.String contentGroup,
                          java.lang.String productId,
                          java.lang.String productSku)
                   throws IllegalWebtrendsParameterValueException
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().
 Hashtable customParams = new Hashtable();
 customParams.put("WT.tx_e", "v");
 customParams.put("WT.tx_u", "4");

 try
 {
     WebtrendsDataCollector.getInstance().onProductView("/eBooksApp/newbook/details",
             "Details Screen", "eBook view", customParams, "Sports", "12345", "abc123");
 }
 catch (IllegalWebtrendsParameterValueException err)
 {
     WebtrendsDataCollector.getLog().e(err.getMessage());
 }
 

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 required for this method.
contentGroup - A category name for the content (for example, "sports" or "music").
productId - An ID for the product.
productSku - A SKU for the product.
Throws:
IllegalWebtrendsParameterValueException - if an invalid argument is passed to the method.

onMediaEvent

public void onMediaEvent(java.lang.String eventPath,
                         java.lang.String eventDesc,
                         java.lang.String eventType,
                         java.util.Hashtable customData,
                         java.lang.String contentGroup,
                         java.lang.String mediaName,
                         java.lang.String mediaType,
                         java.lang.String mediaEventType)
                  throws IllegalWebtrendsParameterValueException
Tracks instances that media events occur in an application. The following code sample demonstrates how to invoke onMediaEvent().
 try
 {
     WebtrendsDataCollector.getInstance().onMediaEvent("/MyMusic/catalog",
             "Media player screen", "play song", null, "Music", "newsong.mp3", "mp3", "75");
 }
 catch (IllegalWebtrendsParameterValueException err)
 {
     WebtrendsDataCollector.getLog().e(err.getMessage());
 }
 

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").
mediaName - The name of the piece of media.
mediaType - The type of media.
mediaEventType - The status of the media event. Valid values include p (play), 25 (25% complete), 50 (50% complete), 75 (75% complete), and f (finished).
Throws:
IllegalWebtrendsParameterValueException - if an invalid argument is passed to the method.

onConversionEvent

public void onConversionEvent(java.lang.String eventPath,
                              java.lang.String eventDesc,
                              java.lang.String eventType,
                              java.util.Hashtable customData,
                              java.lang.String contentGroup,
                              java.lang.String conversionName)
                       throws IllegalWebtrendsParameterValueException
Tracks instances that a conversion event occurs in an application. The following code sample demonstrates how to invoke onConversionEvent().
 try
 {
     WebtrendsDataCollector.getInstance().onConversionEvent("/musicapp/preview",
             "Upgrade version screen", "upgrade", "music", null, "full version");
 }
 catch (IllegalWebtrendsParameterValueException err)
 {
     WebtrendsDataCollector.getLog().e(err.getMessage());
 }
 

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").
conversionName - A name for the conversion.
Throws:
IllegalWebtrendsParameterValueException - if an invalid argument is passed to the method.

onButtonClick

public void onButtonClick(java.lang.String eventPath,
                          java.lang.String eventDesc,
                          java.lang.String eventType,
                          java.util.Hashtable customData)
                   throws IllegalWebtrendsParameterValueException
Tracks instances that a user clicks a button in an application. The following code sample demonstrates how to invoke onButtonClickEvent().

 try
 {
     WebtrendsDataCollector.getInstance().onButtonClick("/chatapp/newuser",
             "Signup screen", "sign up click", null);
 }
 catch (IllegalWebtrendsParameterValueException err)
 {
     WebtrendsDataCollector.getLog().e(err.getMessage());
 }
 

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.
Throws:
IllegalWebtrendsParameterValueException - if an invalid argument is passed to the method.

onCustomEvent

public void onCustomEvent(java.lang.String eventPath,
                          java.lang.String eventDesc,
                          java.util.Hashtable customData)
                   throws IllegalWebtrendsParameterValueException
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().
 Hashtable customParams = new Hashtable();
 customParams.put("WT.ev", "Level cleared");
 
 try
 {
     WebtrendsDataCollector.getInstance().onCustomEvent("ActionGame/main", "Level 3",
             customParams);
 }
 catch (IllegalWebtrendsParameterValueException err)
 {
     WebtrendsDataCollector.getLog().e(err.getMessage());
 }
 

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.
Throws:
IllegalWebtrendsParameterValueException - if an invalid argument is passed to the method.