HomeSetup and Product ManualAPI and SDK ReferenceWoopra
API and SDK Reference

Intro: HTTP Tracking API

The most basic way to get data into the Woopra system

The HTTP tracking API is the most fundamental way to track events and visitor properties into Woopra. All of the tracking SDKs use this API. It is also fairly simple. If you have any issues with one of the SDK's and its compatibility or anything else, it is quite trivial to use the HTTP Tracking API instead, and gain full control of the tracking requests that you are sending to Woopra.

Types of Tracking Data

Custom Events and Event Properties

One of the key features of Woopra is the ability to track Custom Events. Understanding custom events and custom event properties is crucial to getting a good tracking implementation, and to realizing the full power of Woopra. Custom events are tracked using the /track/ce endpoint. These properties are sent with the key prefix: ce_

Custom Visitor Data

Woopra allows you to store custom visitor data on the profiles of your visitors. You can add and set visitor properties on the visitor who performs the action you are tracking. This can be done when tracking a custom event via /track/ce , or without tracking an event by calling /track/identify. These properties are sent with the key prefix: cv_

Custom Visit Data

Woopra also allows you to set metadata that span multiple events, but are not saved on the visitor's profile. This is session or visit data. Examples of this would be device_type, browser, user-agent, etc. While these properties are built-in and thus are not prefixed, and in some cases are in fact generated from http headers, etc., you can also create custom session/visit properties by using the prefix. These properties are sent with the key prefix: cs_

Custom Data Property Prefixes: ce_, cv_, and cs_

In order to allow for fast encoding, and a flat data structure, the GET request parameters are prefixed with cX_ to denote if the item is a custom event property, a custom visitor property, or a custom session property. We do try to respond to track requests within 300ms after all.

  • Custom Event properties are prefixed with ce_
  • Custom Visitor properties are prefixed with cv_
  • Custom Session properties are prefixed with cs_

Special Fields

Parameters that do not have these prefixes are non-custom, built-in or required event metadata such as the event name itself, the timeout (how long before the session is considered over before another event occurs), the project you want to send this event to, the event timestamp, the referer, etc. For legacy reasons, the cookie (aka device id) is also sent without a prefix.

Conventional Fields

Some fields can be sent as custom event properties but will be treated specially by the woopra system. The clearest example of this is the campaign data fields. Sending ce_campaign_name will actually cause the Woopra system to recognize and display the campaign data for that event in a special way. It will also use this data in attribution reports.

Another example is the url property of a pageview event. Woopra will use this to look for utm_ tags and treat them the same as campaign_name and campaign_source event properties. Click here to learn more about campaign tags.

🚧

URL Encoding

Don't forget to url encode your property keys and values.
Note: all examples omit encoding for legibility!

Example:

Consider these request query parameters:

?project=myproject.com
  &event=bark
  &timestamp= 1492030800000
  &cv_name=Rio
  &ce_campaign_name=Teach+Speak+Command
  &ce_bark_volume=loud
  &cs_is_post_nap=true

The project, event and timestamp parameters all cary necessary or overriding event metadata. The event name, the destination project, the event timestamp to use instead of the time of receipt, etc.

The cv_name will turn into a property on the visitor's profile. That property will be called "name", and will have the value on this visitor profile of "Rio". The prefix is removed before it is actually put into your data.

The ce_bark_volume on the other hand, will be a property of this particular bark event. It will show up when you expand the event in a visitor's event timeline as "bark_volume", and will have the value set as: "loud." Similarly, the ce_campaign_name will also show up as an event property, but additionally, it will be used to report on attribution and for some UI conveniences in the Woopra app.

Event and Session Timeout

The timeout parameter (not prefixed), represents the elapsed time, starting from when this event is tracked, after which the visitor's session or visit should be considered over if no further events are tracked. It takes an integer value in milliseconds. You can prevent a session from ending without tracking another event if you send a /ping request for the same visitor.

Responses

Response Codes

You will get a 2xx as a response code immediately unless your request is dropped for one of the three reasons in the "Dropped Requests" section below.

  • 200 -- Processed. Request has been received and logged
  • 202 -- Queued. Request could not be processed within 300 ms due to load, so it has been queued.
  • 401 -- Unauthorized: you have secure tracking enabled, but the request is not authenticated
  • 402 -- Over Quota: Your project has reached its quota for number of actions tracked. Tracking data is logged, but triggers are not run, and interface is locked out. Upgrade to see your data.
  • 403 -- Forbidden: Your project is not registered, or you have defined exclusions for this visitor
  • 5XX -- There has been a server error. Please double check your request format, then report to [email protected].

Response Bodies

The tracking servers will usually respond with a string of javascript to be run on the browser of the visitor if possible. The Javascript client-side API, for example runs this string of code, which can invoke trigger actions from the system or AppConnect apps, as well as set metadata on the tracker object itself for access by these triggers, such as the visitors's label membership information.

Dropped Requests

Woopra's tracking servers are as forgiving as they can possibly be. There are very few reasons for which a request sent to a tracking server will be dropped and not tracked. Here they are:

  1. If there is no project in the request, or the project does not exist, the Woopra Tracking servers do no know on which Woopra instance to apply the data. In this case, the request will be dropped. The preferred parameter to send your project name in a tracking request is project, but for legacy and flexibility reasons, it will also check these parameters for a project title: domain, website, host, and alias. The Server will return a 403.

  2. If Secure Tracking is enabled and the tracking request is not secure, the tracking servers will refuse to track the event in the request. The Server will return a 401.

  3. If the visitor is excluded for instance by ip or by user-agent in your settings, Woopra will drop the request. See Excluding Visitors. The server will return a code 403.

❗️

Missing Visitor Identifiers

If there are no Visitor Identifiers for the visitor, the tracking servers do not know on which visitor profile to apply this action. Identifiers include but are not limited to: id, email, and cookie. See Woopra's Profile ID System for more-in depth discussion on visitor identifiers, and the id hierarchy.

In this case, the tracking server will usually accept the request, but will generate a random value and place it in the cookie field of the visitor. (Woopra cookies are the lowest level of id in the id hierarchy. Think of woopra cookies as a device_id).

If this happens, you will never be able to identify the user who performed the action, nor will you be able to assign more actions or visitor properties to this user.

Sending Event Timestamps

Historical Events

You may send any timestamp in the past with your event. Sending future timestamps will not work reliably. Sending old timestamps will work, and the data will be considered in it's true place in time. However, please note that sending events older than your data retention window will result in an apparent loss of those events.

Future Events

Sending events with timestamps in the future can work, but can also cause unexpected behavior. The event will be logged in the log file of the time of receipt. The data will not show up in the Woopra UI until the timestamp has passed, ie: until the event "happens."

In both cases, the larger the difference between the timestamp of the event itself and the date of the transactional db log file in which it was recorded, the more likely the event will be missed in analytics, and segment reporting. This generally happens because certain time constraints of a report cause the system to only evaluate log files of that date range. If you think you may be missing out on data when you run certain reports, reach out to [email protected] to get more details on this with regards to your specific situation.

🚧

Old Events

Note, that while the tracking servers will accept a well-formed request in which the timestamp is older than your data retention policy limit, you will likely never see those events in the interface.

Tid Bits

  • There is no limit on the number of the parameters, as long as your browser can handle the size of the resulting GET request.
  • It is recommended to use non-blocking http clients, especially for high volume traffic.
  • The Http client used to start the tracking requests should be able to handle 301, 302 redirects, and should preferably handle cookies.