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:
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:
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:
Custom Data Property Prefixes:
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
- Custom Visitor properties are prefixed with
- Custom Session properties are prefixed with
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.
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_source event properties. Click here to learn more about campaign tags.
Don't forget to url encode your property keys and values.
Note: all examples omit encoding for legibility!
Consider these request query parameters:
?project=myproject.com &event=bark ×tamp= 1492030800000 &cv_name=Rio &ce_campaign_name=Teach+Speak+Command &ce_bark_volume=loud &cs_is_post_nap=true
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.
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.
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
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.
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]
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:
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:
alias. The Server will return a
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
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
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:
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
cookiefield 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
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.
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.
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.
- 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.