Advanced instrumentation
Setting up an advanced instrumentation will help you get the most out of Koala!
Product analytics overview
Most customers start by instrumenting their public site properties, including their homepage, technical docs, and blog. However, a lot more can be unlocked with Koala with a full instrumentation. There are two critical pieces to a full instrumentation:
- Sending product analytics from your app
- Sending important account-level traits from your database or warehouse
This will turn an instrumentation that looks like this:
…into a workspace that looks like this:
…with account level traits that look like this (right):
Setting up product analytics
Typically, this is a task that a full-stack engineering team will need to spend 2-4 hrs on, depending on how mature the product analytics stack is and what tools you’re already using.
Koala has similar semantics to most product analytics tools (e.g., Segment, Rudderstack, Heap, Amplitude, Mixpanel, Posthog, etc.). The main difference with Koala and some tools is that Koala does a few things automatically on the client-side, including accurate tracking of session time and automatic pageview detecting (single-page apps supported!). Thus, we recommend installing Koala client-side (we try to keep the SDK as thin as possible — it is about 20kb). However, if you prefer to only install server-side, we have documentation on the server-side API.
Below is a quick guide on how to take an existing analytics tool and convert to work with Koala. In cases where you must implement track
and identify
yourself, please see our developer guide.
Segment
Google Tag Manager
Rudderstack
Heap, Amplitude, Mixpanel, Posthog, and others
The most important things to ensure a successful implementation are as follows:
- ensuring that the Koala pixel is on every page
- ensuring that
identify()
(with an email address!) happens upon sign-up and login - ensuring that key events that map to buying intent are instrumented and sent to Koala
If you are interested in this but need help with this, please get in touch with [email protected]. We have lots of experience getting product analytics stacks spun up and happy to lend our expertise!
Setting up account traits
In order to set triggers on your main consumption metric (e.g., bandwidth used if you’re Vercel, # of licenses consumed if you’re Salesforce, or number of API calls if you’re a usage-based developer tool), you’ll want to send those consumption metrics to Koala. We’ll track the history of the consumption metric and allow you to alert when user-defined thresholds are reached.
There are two primary architectures for doing this:
- Sending data directly to Koala’s API
- Using Reverse ETL (Hightouch, Census, etc.)
Sending data directly to Koala’s API
You can send account traits directly to Koala. This can be done directly on the website, as you do with your other analytics tracking. Alternatively, this can be run in a nightly asynchronous script (e.g., if you have a nightly script that computes billing consumption and sends alerts, that would be a good place to add these calls).
The following script includes a sample identify call that can be issued at any time where user data is available.
/**
* Identify calls can be issued at any time, on any page where the koala
* pixel is instrumented.
*/
// email is how koala ties this user to a specific contact
ko.identify(email, {
// You can send any javascript object here.
// Each field will be associated as a user trait
...userObjectTraits,
$account: {
group_id: 'your-unique-grouping-id',
// You can send any javascript object here.
// Each field will be associated as an Account Trait
...accountObjectTraits
}
})
// Example:
ko.identify('[email protected]', {
// These are user specific traits
vip_user: true,
finished_onboarding: true,
invited_teammate: true,
// These are company specific traits
$account: {
name: 'Koala',
domain: 'getkoala.com',
group_id: 'your-unique-grouping-id'
pricing_plan: 'enterprise',
is_trialing: true,
trial_end_at: '2023-03-03',
num_team_members: 4
}
})
Using Reverse ETL
You can use a Reverse ETL tool to pull data directly from your data warehouse into Koala. Check out our Hightouch and Census integrations.