Server Side Tracking
Sometimes you’ll need to send events from your backend application in addition to or instead of using Koala’s client-side SDK. This guide will show you how to do that.
What can it do?
- ❌ Autocapture (pageviews, forms, active session time)
- ❌ Sessions
- ✅ Custom Events
- ✅ Visitor Identification
- ✅ Account Traits
Identifying visitors
If you’ve already got the Koala snippet installed client-side on the same top domain as your server you can identify visitors with known email addresses server-side. For example, if your website (www.example.com) has the JavaScript snippet installed, and your app (app.example.com) does not, you can enrich the data Koala is collecting across both.
Whenever users do something identifiable in your app, like logging in, you can identify them manually. This enables you to:
- Track a visitor across browsers or devices
- Differentiate truly anonymous visitors from known users
- Combine all activity from a visitor before and after they’ve logged in
- Associate visitors with company data
To identify anonymous visitors with an email, send a request to your workspace’s public API for collection:
https://api2.getkoala.com/web/projects/<your public api key>/batch
Here’s an example request:
curl -X POST \
-H "Content-Type: application/json" \
-H "User-Agent: your-company-name/1.0.0" \
-d '{ "profile_id": "3e6a2c18-3b02-40c4-b8d2-1842c193d3ba", "email": "[email protected]" }' \
https://api2.getkoala.com/web/projects/my-public-api-key/batch
You should ensure all websites sharing the same top domain also share the Koala anonymous profile_id
by respecting one if it’s already there, or setting it yourself if it isn’t there. You can read and modify the ko_id
cookie value in the request to do this.
Note: when setting your own randomly generated profile_id
, you should use a UUID v4 format.
Here’s an example of parsing the Koala cookie for a profile_id
using Express in Node.js:
const cookieParser = require('cookie-parser')
const express = require('express')
const app = express();
app.use(cookieParser())
app.get('/', (req, res) => {
// use `profile_id` from cookie, else send a randomly generated one
// and set it in the cookie yourself
let profile_id = req.cookies.ko_id
if (!profile_id) {
profile_id = uuid.v4()
res.cookie('ko_id', profile_id, { domain: '.example.com' })
}
// send http request to Koala with the `profile_id`
})
Sending events
You can also send custom events to Koala using the same /batch
endpoint for your workspace.
curl -X POST \
-H "Content-Type: application/json" \
-H "User-Agent: your-company-name/1.0.0" \
-d '{
"profile_id": "3e6a2c18-3b02-40c4-b8d2-1842c193d3ba",
"events": [{
"message_id": "any idempotent id (can be a uuid or anything unique)",
"type": "track",
"event": "Created Account",
"properties": {},
"sent_at": "2022-11-09T23:57:14.776Z"
}]
}' \
https://api2.getkoala.com/web/projects/my-public-api-key/batch
You can send multiple events at once. You can omit the message_id
if you do not require it, but note that the event could potentially be captured more than once (if retries are needed). The message_id
acts as an idempotency key to dedupe replayed/retried events.
Sending Traits
You can send custom traits that can be attached to a Koala visitor using the /batch
endpoint for your workspace.
You must either pass a profile_id
or email
key in the body of a request in order for it to be attached to an existing visitor in Koala.
- You can find the
profile_id
for a visitor by reading theko_id
cookie that is set by the Koala pixel client side. - Alternatively, you can attach an
email
field to your/batch
call, and Koala will associate the traits to an existing user that has been previously identified using the same email.
curl -X POST \
-H "Content-Type: application/json" \
-H "User-Agent: your-company-name/1.0.0" \
-d '{
"profile_id": "3e6a2c18-3b02-40c4-b8d2-1842c193d3ba",
"email": "[email protected]",
"identifies": [{
"type": "identify",
"traits": {
"billing_plan": "pro",
"vip": true,
"is_current_customer": true
},
}]
}' \
https://api2.getkoala.com/web/projects/my-public-api-key/batch