@getkoala/edge-api-client

Koala Edge API

Koala’s Edge API is a powerful personalization and qualification engine available at the edge – in browser clients or edge servers (Cloudflare Workers, for example). It gives you access to your visitor/user profiles at the Edge, allowing you to customize your website based on your visitors’ behavior, traits, and profile data.

It gives you access to your entire customer profile in a performant and privacy-conscious way. We don’t directly expose the visitor’s traits, company or history, but rather give you the ability to ask yes/no questions from an anonymized data structure.

The headless nature of the Edge API enables engineers and marketers to go beyond basic copy changes, but to drive entire custom experiences for each individual visitor.

You can use the Edge API in browsers or in browser-like environments like Cloudflare Workers or Vercel Edge Functions. Keep in mind that use in a Cloudflare Worker or Vercel Edge Function requires reading and setting profile id cookies, otherwise every request will look like a new visitor and be slower.

Getting Started

There are two ways that you can start using the Koala Edge API.

1. Install the Koala snippet on your website using the instructions provided in the Koala App: https://app.getkoala.com/goto/settings/install

   💡 The Koala Snippet is a quick way to get started with the Koala Edge API, and is the recommended approach for use in browsers. There are several ways to install the snippet, you can learn more in our docs: https://getkoala.com/docs/sdk/quick-start

   Once installed, you can use ko.edge after the client is ready. Koala automatically loads the anonymous profile and hydrates the Edge API:

   await ko.ready()
   console.log(ko.edge.company.isB2B())
   

2. Or, install the Koala Edge API client via NPM:

   $ yarn add @getkoala/edge-api-client
   

   import { build } from '@getkoala/edge-api-client'
   
   // You need to hydrate the profile manually
   // This is typically done by fetching the profile for an existing profile id (read from browser storage / cookie) or generating a new one
   // You can see an example implementation of fetching the profile here:
   // https://github.com/koala-live/examples/blob/4d9d1bd6276e0c70dbb1825fb17a41aa129cc384/vercel-edge-functions/pages/_middleware.ts#L5
   const anonProfile = await fetchProfile(request)
   
   const edge = await build(anonProfile)
   console.log(edge.company.isB2B())
   

Queries

There are a variety of yes/no queries you can ask the Edge API about the current visitor.

Boolean + existence

ko.identify({ plan: 'pro', trialing: true })

edge.traits.has('plan') // true
edge.traits.is('trialing', true) // true
edge.traits.includesAnyOf('plan', ['enterprise', 'pro']) // true

Numeric traits

ko.identify({ seats: 20 })

edge.traits.greaterThanOrEqual('seats', 20) // true
edge.traits.greaterThan('seats', 20) // false
edge.traits.lessThanOrEqual('seats', 20) // true
edge.traits.lessThan('seats', 20) // false
edge.traits.is('seats', 20) // true

Nested traits can be accesses through dot notation . similar to lodash's get api

ko.identify({
  name: {
    first: 'Edson',
    last: 'Nascimento',
    nickname: 'Pelé'
  }
})

edge.traits.has('name.first') // true
edge.traits.is('name.first', 'Edson') // true
edge.traits.has('name.nickname') // true

You can also partial match objects

edge.traits.matchesObject({
  name: {
    first: 'Edson'
  }
}) // true

Arrays

ko.identify({ favoriteEmojis: ['⚽️', '🥅', '🇧🇷'] })

edge.traits.has('favoriteEmojis.[]') // true
edge.traits.includes('favoriteEmojis', '⚽️') // true
edge.traits.includes('favoriteEmojis', '🇦🇷') // false
edge.traits.includesAnyOf('favoriteEmojis', ['🇧🇷', '🇦🇷']) // true
edge.traits.includesAllOf('favoriteEmojis', ['🇧🇷', '🇦🇷']) // false

Types of traits and data you can query

First-party traits

Via ko.identify or from Segment's analytics.identify if you are using that)

edge.traits

// see examples above for querying traits

Events

edge.events.performed('Signed Up') // true

// Pass a count for number of times the event was performed
edge.events.performed('Viewed Dashboard', 2) // true

edge.events.performedAnyOf('Signed Up', 'Viewed Dashboard') // true
edge.events.performedAtLeast('Teammate Invited', 1) // true

Pageviews

edge.page.seen('/pricing') // true
edge.page.viewed('/pricing') // same as `seen`

// Currently viewing?
edge.page.viewing('/home')

Company data

If you are using any integrations that help enrich and identify what company a visitor is from, you can query company data. Because this data isn't always immediately available when a visitor first shows up, it's best to use these for non-blocking experiments.

edge.company.industry.includesAnyOf('Internet Software & Services', 'Media')
edge.company.employeeCount.greaterThanOrEqual(100)
edge.company.isB2B()

Available company traits:

• edge.company.name
• edge.company.type
• edge.company.domain
• edge.company.sector
• edge.company.industryGroup
• edge.company.subIndustry
• edge.company.foundedYear
• edge.company.timezone
• edge.company.city
• edge.company.state
• edge.company.stateCode
• edge.company.country
• edge.company.countryCode
• edge.company.employeeCount
• edge.company.employeeRange
• edge.company.marketCap
• edge.company.amountRaised
• edge.company.annualRevenue
• edge.company.estimatedAnnualRevenue
• edge.company.tech
• edge.company.techCategories
• edge.company.tags
• edge.company.isB2B()
• edge.company.isB2C()
• edge.company.isEnterprise()
• edge.company.isEcommerce()
• edge.company.isSAAS()

Person data

Similarly, if you are using the Clearbit integration for enrichment in Koala, you can query person traits. Refer to Clearbit's attributes docs for the full list of possible values.

edge.person.title.is('CEO')
edge.person.countryCode.includesAnyOf('US', 'FR')
edge.person.seniority.is('manager')

Available person traits:

• edge.person.timezone
• edge.person.city
• edge.person.state
• edge.person.stateCode
• edge.person.country
• edge.person.countryCode
• edge.person.company
• edge.person.title
• edge.person.role
• edge.person.subRole
• edge.person.seniority
• edge.person.emailType
• edge.person.identifiedWorkEmail()
• edge.person.identifiedPersonalEmail()
• edge.person.identifiedAcademicEmail()
• edge.person.isIdentified()

Adding traits to visitors

You can add even more traits about your visitors by leveraging ko.identify.

ko.identify({
  is_vip: true,
  plan: 'premium',
  is_trialing: false,
  is_free_account: false,
  seats: 20,
  name: {
    nickname: 'Pelé',
    first: 'Edson',
    last: 'Nascimento',
  },
  geo: {
    country: 'Brazil',
    state: 'RJ',
  },
  favoriteEmojis: ['⚽️', '🥅', '🇧🇷']
})

These will become available to query via the Edge API's traits namespace:

const pele = ko.edge.traits

// Verify the existence of a trait
pele.has('plan') // true
pele.has('is_trialing') // true
pele.is('is_trialing', true) // false

// Verify trait + value checks
pele.is('plan', 'premium') // true
pele.is('plan', 'enterprise') // false
pele.includesAnyOf('plan', ['enterprise', 'premium']) // true for premium

Accessing Raw Data

You can request the inclusion of raw company data for the cases where you would like to see the actual data behind a company, and aren't interested in the strong privacy guarantees of the Edge API.

Reach out to the Koala team, and we enable a flag to return the raw company data in the Edge API.

FAQ

Where is this data stored?

Koala stores raw logs of activity and traits in our system of record. Intent data is stored based on your plan's data retention policy. All data is encrypted at rest and in transit.

The Edge API uses specialized algorithms and data structures that are optimized for privacy and performance.

Are there storage limits for the Edge API?

Anonymous profiles can support up to 2,000 unique traits, events, and event properties.

How fast is this?

Koala uses multi-tiered caching and persistence to bring you the Edge API with minimal latency. We leverage browser storage → Edge CDN Cache → Application Cache → Systems of Record + Third Party APIs.

Events and traits collected in-browser are instantly available to query. Anything coming from the network is delivered via a low-latency websocket connection as soon as it is available and will update the Edge API automatically.

Why isn't the raw profile available?

Privacy and performance are two core priniciples of Koala and the Edge API. We use specialized algorithms and data structures that are optimized to answer questions about your visitors without revealing the raw data directly. Yes/No questions are much faster to process and more privacy-friendly ☺️!