Getting Started with the Data Collection API

The Webtrends Data Collection API allows application developers of non-browser based applications to feed interaction data to Webtrends data collection servers.

Benefits

The Webtrends Data Collection API provides an alternative to JavaScript/image request collection by providing programmatic access to Webtrends data collection servers. You can use the API to submit data to collection servers using standard HTTP techniques.

How Does It Work?

The Data Collection API supports sending data in a POST body to a standard URI that is a Webtrends data collection server. The POST body contains ampersand-delimited key/value pairs. This method of data transmission is also known as form encoding. It supports both Webtrends parameters and custom parameters, so you can report on any application-collected information that can be passed in a parameter.

Code Samples

This site provides sample client code for a variety of platforms. For more information, see Code Samples.

Testing Your Code Against the Data Collection Server

To receive detailed debugging information, use the dcsverbose parameter. This is the primary method of testing code written against the Data Collection API. For more information, see Debugging Requests to the Data Collection Server.

Base URI

All URIs used to contact the data collection server use the following base:
https://dc.webtrends.com/v1/dcsxxxxxxxxxxxxxxxxxxxxx_xxxx
(where the current API version is followed by the unique data source ID associated with a Webtrends data source).
URIs can use the http or https protocol (https is preferred to ensure secure data transfer).

Methods

Post Event Data
Get Visitor Identifier

Required Parameters

Effective data collection with best performance requires the following parameters:

• dcsuri uniquely identifies the type of event that occurred within your application.
• WT.ti identifies the page title associated with a request. In a non-web page application, you can use this parameter to provide information about the event. Even though your application may not use web pages, you should always specify a value for this parameter to avoid creating more performance overhead by requesting the title of an invalid page. For more information about WT.ti, see the Webtrends Query Parameter Reference.
• WT.co_f identifies the unique visitor associated with an event in Webtrends Analytics. Visitor Data Mart data collection requires additional visitor session information. For more information about how Visitor ID parameters are used for the Data Collection API, see Identifying Visitors.

Optional Parameters

The following parameters can be placed either in the URI or in the request body.

• dcsformat specifies the format of any response to your request.
• dcsverbose specifies a verbose response to your request for debugging purposes.

Any additional Webtrends or custom parameters are used to pass data to the data collection server. For more information about parameters supported by the Data Collection API, see the Parameter Quick Reference. Parameters that Webtrends auto-generates, such as some of the Visitor History parameters, are not supported.

About REST

This API uses a RESTful interface to enforce simple, straightforward communication. For more information about REST Web Services, we recommend the O'Reilly title RESTful Web Services.

Recommended Process and Considerations

1. Create a data source in Webtrends Administration. The dcsid associated with your data source is the dcsid you will use in your requests to the data collection server.
2. Begin developing your application code.
3. Based on the goals of your application, determine what kind of events you want to track. For example, you may want to track the beginning and ending of each user's interactions with your application as an event.
4. Determine which parameters you will use to track these events. The Data Collection API supports a large number of parameters already in use by Webtrends. You can also pass key-value pairs already in use by your application code, or create your own custom parameters to pass event information.
5. Use the sample code provided on this developer site as an example of how to embed URI requests containing these parameters and their values into your application code. The sample code contains detailed comments to assist you.
6. If you want Webtrends to generate a unique visitor ID for each application user, use the Get Visitor ID request to retrieve an ID. Then pass that ID in the wt.co_f parameter when you post data for that visitor.
7. Using the dcsverbose parameter, you may validate your requests against the data collection server. dcsverbose returns detailed information about the success or failure of each request in the response body. The response body of a successful request contains the contents of the SDC logfile line that would have been written. The response body of a bad request contains error detail information. In this way, the response body can be used to validate the request. Use the dcsformat parameter to specify the format of the response body as plain text or XML.
8. When your code validation is complete, you should remove dcsverbose from your requests to conserve bandwidth.
9. Create a profile based on the data source you create in Step 1. You should also create custom reports for any parameters not covered by standard reports. This profile will collect and analyze the data you passed to the data collection server.