Documentation

Documentation about the Koala pixel, integrations, and more.

Koala SDK

Koala.js (for Browsers)

Koala.js enables you to automatically collect first-party events, pageviews, active session time, form fills, right from your browser.

Configuration Koala.js is designed to be completely configurable, so you have very granular control over what behavior you’d like it to have. You can configure it directly from the website UI (we’ll generate snippets that can be copied into a tag manager) or you can can control it programmatically yourself (COMING SOON).

You can configure which types of events Koala should automatically detect:

  • Page views: detect a page view event each time a page loads or browser history changes
  • Active session time: detect engagement time when a visitor actively interacts with your site
  • Form submissions: detect a form submission event when a visitor interacts and submits a form on your site
  • Outbound clicks (COMING SOON): detect when a visitor clicks a link that leads them away from your domain(s).

Soon you’ll be able to manually/programmatically configure events in JavaScript in the browser, which can override your configuration settings from the Koala app:

    <script>
      // window.ko is available after installing the snippet
      ko.configure({
        trackPageViews: true,
        trackSessionTime: true,
        trackFormSubmissions: true,
        trackOutboundClicks: true,
        useSegmentMiddleware: true
      });
    </script>

Identifying visitors (client-side) When you have a known user or want to add traits to a visitor, you can use the identify method. Koala uses the email trait for identity merging and it also unlocks enrichment (like domain-to-company attributes).

    ko.identify({
      email: '[email protected]'
    });

You can pass any traits you want Koala to associate with the visitor:

    ko.identify({
      is_trial_account: true
    });

Note: if you have enabled automatic detection for form submits, Koala will evaluate inputs (including email) as traits.

Note: if you have enabled automatically hooking into Segment, Koala will detect identify events from Segment. No further code is necessary to instrument Koala when you are already using Segment’s identify method.

Tracking custom events (client-side) You can also track custom events in Koala if you want to associate interesting events with your site visitors. You can provide any properties you want to associate with the event, too.

    ko.track('Signed Up', {
      plan_tier: 'Pro',
      referral_link: 'af39lUbz'
    });

Note: if you have enabled automatically hooking into Segment, Koala will detect track events from Segment. No further code is necessary to instrument Koala when you are already using Segment’s track method to detect custom events.

Koala Node (for server-side code)

The Koala Node.js SDK is a tiny library used for identity linking and sending Koala custom events from your backend/server-side application.

Installation (COMING SOON) You can download and install the package from npm (or via Yarn):

    npm install --save @koala-live/node

This will add our Node.js module to your package.json. To use the module, you will need to initialize the Koala constructor with your project identifier:

    const Koala = require('@koala-live/node');
    const ko = new Koala({ project: 'your-project' })

Koala’s Server SDK does nothing upon initial import and all features are opt-in through programmatic use. This module uses an efficient queue to make identify and track calls non-blocking and fast. It sends events in batches to Koala’s servers. It supports identify and track methods.

Identifying visitors (server-side) identify lets you tie a visitor to a known email and record other traits about them. You should call identify whenever a user first creates an account, when they log in, and whenever their traits change.

Email is used as the primary identifier for both enrichment and identity merging in Koala, so be sure to pass that in identify if you have it.

    ko.identify({
      // optional, but must have one of `email` or `id`
      id: 'koala anonymous profile id', 
      // optional, but must have one of `email` or `id`
      email: '[email protected]', 
      name: 'Tido Carriero'
    })

Tracking custom events (server-side)

    ko.track({
      id: '',
      email: '[email protected]',
      event: 'Account Created',
      properties: {
        plan_tier: 'Pro'
      }
    })

Identity merging The most common use-case for the Koala Server SDK is to link client-side identifiers to email addresses to shine a light on previously-anonymous traffic.

This module also provides middleware you can use to detect those identifiers from web requests and make it available for you to pass in identify calls. Here’s an example in Express.js (or other connect-based Node servers):

    const express = require('express')
    const Koala = require('@koala-live/node')
    
    var app = express()
    app.use(Koala.identityMiddleware())
    
    app.post('/login', function(req, res, next) {
      // do login stuff
      const user = doLogin(req)
    
      if (user && req.koalaId) {
        ko.identify({
          id: req.koalaId, 
          email: '[email protected]', 
          name: 'Tido Carriero'
        })
      }
    })

Koala Ruby

	Email [email protected] for early access.

Koala Py

	Email [email protected] for early access.

Koala Go

	Email [email protected] for early access.