HTTP Tracking API

Our SDKs use this HTTP Tracking API. You can use this document as a reference If you want to build your own SDK.

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). Ex: for web tracking, a 12-char cookie is used as a pseudo device ID – for mobile, the device serial number is used as a device ID.
cv_id optional (but highly recommended) Visitor’s unique ID, serves as an identifier to track individuals across multiple devices.
cv_email optional (but highly recommended) Visitor’s email, serves as an identifier to track individuals across multiple devices as well. It also enables easier integration with external services.
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…
passive optional Possible values:

passive=0 (default), Woopra will tag the event as regular event

passive=1 : Woopra will tag the event as passive – done on behalf of the user such as: ‘Email Delivered’
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.
timestamp optional Event timestamp – time in milliseconds since the UNIX epoch – for example: 1488403086000

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 more 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.

Identify requests

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

GET Request Parameters

Parameter Required Description
host required
cookie required
cv_id optional (but highly recommended)
cv_email optional (but highly recommended)
cv_{visitor property} optional Custom visitor data parameters. e.g. cv_name, cv_address etc…
http://www.woopra.com/track/identify
?host=mywebsite.com
&cookie=AH47DHS5SF182DIQZJD
&cv_email=tigi@brembo.com
&cv_name=Tigi
&cv_age=31

Event update requests

It is possible to add/modify an event property after the event has been tracked. This can be useful when tracking ongoing activity such as watching a video.

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

GET Request Parameters

Parameter Required Description
event_id required The unique ID of the event to be updated
ce_{event property} optional Custom event data parameters. e.g. ce_duration, ce_comment etc…
http://www.woopra.com/track/update
?host=mywebsite.com
&event_id=aq3IUy7489d
&ce_duration=32
&ce_unit=seconds

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.

A day of setup. A lifetime of insights.

Try Woopra for free. No credit cards. No obligations.