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:

Tracking API Endpoint
https://api2.getkoala.com/web/projects/<your public api key>/batch

Here’s an example request:

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:

Node.js Express Example
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.

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",
    "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 the ko_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.
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]",
    "identifies": [{
      "type": "identify",
      "traits": {
        "billing_plan": "pro",
        "vip": true,
        "is_current_customer": true
      },
    }]
  }' \
  https://api2.getkoala.com/web/projects/my-public-api-key/batch