HTTP Tracking API

Our SDKs use this HTTP Tracking API. If you want to build your own, read below.

Update Log

11/17/2014 The request property “cv_email” maximum allowed length has been increased to 140 characters. Woopra will trim the first 140 characters of the value if it is longer than the maximum allowed length.

11/17/2014 The request property “cv_id” maximum allowed length has been increased to 140 characters. Woopra will trim the first 140 characters of the value if it is longer than the maximum allowed length.

11/01/2014 The request property “cookie” maximum allowed length is 24 characters. Woopra will trim the first 24 characters of the cookie if it is longer than the maximum allowed length.

05/09/2014 The request property “id” has been deprecated. Woopra will merge visitors only by the visitor’s email property (cv_email) .

05/09/2014 It is strongly recommended to avoid using the custom visitor property “id” as it could cause conflicts if not used properly.

Endpoint

To track events in Woopra, send Http GET requests to:

http(s)://www.woopra.com/track/ce

GET Request Parameters

Parameter Required Description
host required Domain as registered in Woopra; identifies which project environment to receive the tracking request
cookie required A device identifier (24-char max, ~12-chars recommended). This can be a randomly generated cookie on the browser. Also the hash of the visitor email/id can be used as a device ID
cv_email (and/or cv_id) optional (but highly recommended) Visitor’s email, serves as a unique ID to track individuals across multiple devices. It is recommended to use a valid email address as the unique ID to enable easier integration with external services- maximum allowed email length is 128 characters. cv_id will be used as the unique ID if both cv_email and cv_id exist.
cv_{visitor property} optional Custom visitor data parameters. e.g. cv_name, cv_address etc…
event required Custom event type. e.g. event=purchase, event=signup etc…
ce_{event property} optional Custom event data parameters. e.g. ce_name, ce_amount etc…
referer optional Visit’s referring URL, Woopra servers will match the URL against a database of referrers and will generate a referrer type and search terms when applicable. The referrers data will be automatically accessible from the Woopra clients
ip optional IP address of the visitor. If defined, it overrides the physical IP address of the connection.
timeout optional In milliseconds, defaults to 30000 (equivalent to 30 seconds) after which the event will expire and the visit will be marked as offline.
browser optional User’s browser. If defined, it overrides the auto-detected browser from the user-agent. You can also build your custom user-agent
os optional User’s operating system. If defined, it overrides the auto-detected operating system from user-agent.
device optional User’s device type. If defined, it overrides the auto-detected device type from user-agent. Common values are mobile, tablet and desktop.

Tracking Request Example


http://www.woopra.com/track/ce/

?host=mywebsite.com
&response=json
&cookie=AH47DHS5SF182DIQZJD
&timeout=300000
&cv_name=John+Smith
&cv_email=john@mail.com
&event=purchase
&ce_item=Coffee+Machine
&ce_category=Electric+Appliances
&ce_sku=K5236532

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.
  • Values in the GET request are not escaped in the example above to make it better readable, make sure to escape them in production mode.
  • 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.

Custom Visitor Data

Woopra allows you to store custom visitor data of your choice; custom parameters have to be prefixed by cv_ to be tracked correctly.

For example, to log a John Smith, email being john@mail.com you will have to issue the following request:


http://www.woopra.com/track/ce

?host=mywebsite.com
&response=json
&cookie=AH47DHS5SF182DIQZJD
&timeout=300000
&cv_name=John+Smith
&cv_email=john@mail.com
...

Custom Event Data

In addition to custom visitor data, Woopra allows tracking custom events; the event properties have to be prefixed by ce_ to be tracked correctly. It is highly advised to define the ‘event’ in the request, and as many related properties as possible to unlock the reporting capabilities.

For example, to track a payment by John Smith of $149.95 for a Titanium package, you should issue a tracking request similar to the following


http://www.woopra.com/track/ce/

?host=mywebsite.com
&response=json
&cookie=AH47DHS5SF182DIQZJD
&timeout=300000
&cv_username=John+Smith
&cv_email=john@mail.com
&event=payment
&ce_amount=149.95
&ce_type=blog
&ce_package=Titanium
 

Pageviews

For pageview-based tracking, it is recommended that ce_url is used for the page path, and ce_title is used for the page title. This will integrate seamlessly with the Woopra clients. If the variable names are defined otherwise, then custom analytics should be created to collect the corresponding data.

Timestamps

It is possible to override the default action’s timestamp by sending a timestamp parameter (previously ce_timestamp) in the GET request; timestamp is the Unix time in milliseconds. This is particularly useful for importing data.

Identify requests

Identify requests can be used to ID a visitor and/or add properties to that visitor. The endpoint for identify is:
http(s)://www.woopra.com/track/identify
and the parameters are the same as a regular tracking request (the event and event data parameters will be ignored)


http://www.woopra.com/track/identify

?host=mywebsite.com
&cv_email=tigi@brembo.com
&cv_name=Tigi
&cv_age=31

Ping requests

Optionally, ping requests can be periodically sent to Woopra servers to refresh the visitor timeout counter. This is used if it’s important to keep a visitor status ‘online’ when she’s inactive for a long time (for cases such as watching a long video).


http://www.woopra.com/track/ping

?host=mywebsite.com
&response=json
&cookie=AH47DHS5SF182DIQZJD
&timeout=300000
  • There is no need to have custom parameters in the ping request.
  • It is recommend to send ping requests at intervals slightly less than the timeout value. If the timeout is 60 seconds, consider pinging the servers every 55 seconds, otherwise you will be sending unnecessary requests.

Updating the profile email (Experimental)

When visitors update their email addresses, or when the internal tracking IDs change, it is possible to apply the changes to Woopra by issuing a re-id call. The call will save the profile under the new ID and will permanently delete the old profile. If the new profile ID already exists, the old profile data will be merged with the new profile.


http://www.woopra.com/track/re-id?

?host=mywebsite.com
&old=johnnie_666@mail.com
&new=john@doe.com

Do you know what your customers are doing?
Find out in 5 minutes.

Start your 30-day free trial. No credit cards. No obligations.

Try it out