applytics-js

JavaScript/TypeScript client library for Applytics CDP. Works with React, Next.js, and other JavaScript projects.

Installation

npm install applytics-js
# or
yarn add applytics-js

Quick Start

Next.js

1. Add keys to .env.local

NEXT_PUBLIC_APPLYTICS_URL=https://api.applytics.com
NEXT_PUBLIC_APPLYTICS_APP_KEY=app_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

2. Create a singleton client

// lib/applytics.ts
'use client'

import { ApplyticsClient } from 'applytics-js'

export const applytics = new ApplyticsClient({
  applyticsUrl: process.env.NEXT_PUBLIC_APPLYTICS_URL!,
  appKey: process.env.NEXT_PUBLIC_APPLYTICS_APP_KEY!,
})

The 'use client' directive is required. ApplyticsClient uses browser APIs (localStorage, setInterval) and cannot run in Server Components.

3. Use inside a component

// components/MusicPlayer.tsx
'use client'

import { applytics } from '@/lib/applytics'

export function MusicPlayer() {
  const handlePlay = (song: Song) => {
    applytics.track('Song Played', {
      songId: song.id,
      title: song.title,
      duration: song.duration,
      genre: song.genre,
    })
  }

  return <button onClick={() => handlePlay(song)}>Play</button>
}

React (CRA / Vite)

// src/applytics.ts
import { ApplyticsClient } from 'applytics-js'

export const applytics = new ApplyticsClient({
  applyticsUrl: import.meta.env.VITE_APPLYTICS_URL,
  appKey: import.meta.env.VITE_APPLYTICS_APP_KEY,
})

Methods

identify(userId, traits?)

Records who the user is. Typically called after the user logs in. After identify is called, all subsequent track, page, and screen calls automatically include the userId.

applytics.identify('user_123', {
  name: 'Ali Yilmaz',
  email: '[email protected]',
  age: 25,
  city: 'Istanbul',
  plan: 'premium',
})

alias(anonymousId)

Links the anonymous identity to the logged-in user. Call this after identify(). All events recorded before login are attributed to the real user.

// After the user logs in
applytics.identify('user_123', { name: 'Ali' })
applytics.alias('anon_abc')  // anonymousId from before login

group(groupId, traits?)

Associates the user with a group (club, community, team). Call once per membership.

applytics.group('group_foto_istanbul', {
  name: 'Istanbul Photography Club',
  memberCount: 340,
  category: 'hobby',
})

track(event, properties?)

Records an action the user performed. The "Object Action" naming convention is recommended: Song Played, Button Clicked, Profile Viewed.

// Music
applytics.track('Song Played', { songId: 'xyz', duration: 180, genre: 'pop' })
applytics.track('Song Skipped', { songId: 'xyz', at: 45 })
applytics.track('Playlist Created', { playlistId: 'abc', trackCount: 12 })

// Interaction
applytics.track('Button Clicked', { buttonId: 'cta-signup', page: '/home' })
applytics.track('Form Submitted', { formId: 'contact' })

// Matching
applytics.track('Profile Swiped', { direction: 'right', targetUserId: 'user_456' })
applytics.track('Match Created', { matchId: 'match_789' })

page(name?, properties?)

Records which page the user is viewing. url, path, and referrer are automatically collected from the browser.

applytics.page('Home')
applytics.page('Artist Detail', { artistId: 'artist_123', artistName: 'Tarkan' })
applytics.page('Search Results', { query: 'pop music', resultCount: 42 })

screen(name?, properties?)

Used for tracking mobile app screens.

applytics.screen('Player', { songId: 'xyz' })
applytics.screen('Profile', { userId: 'user_123' })

flush()

Immediately sends all buffered events. Automatic flushing is usually sufficient.

await applytics.flush()

destroy()

Stops the automatic flush timer. Can be called when a component unmounts.

useEffect(() => {
  return () => applytics.destroy()
}, [])

Charts

Render any chart widget you built in the Applytics dashboard. Charts are computed server-side (aggregate data only — no raw events leave your infrastructure) and rendered with Chart.js, which is loaded lazily — it only downloads when you actually render a chart, so tracking-only apps stay lightweight.

chart(widgetId, options)

Render a widget into a container:

applytics.chart('abc123def456', {
  container: '#analytics',  // CSS selector or HTMLElement
  height: 320,              // optional, default 300
  width: 600,               // optional, defaults to the container width
})

mountCharts()

Auto-render every element that has a data-applytics-chart attribute — handy for embedding without writing any JavaScript per chart:

<div data-applytics-chart="abc123def456"></div>
<div data-applytics-chart="789ghi012jkl"></div>

applytics.mountCharts()

Both use the same appKey you initialized the client with; the widget's app must match that key.

Configuration

| Parameter | Type | Default | Description | |-----------------|----------|---------|----------------------------------------------| | applyticsUrl | string | — | Applytics API URL | | appKey | string | — | Application key (starts with app_) | | flushInterval | number | 5000 | Automatic flush interval in milliseconds | | maxBatchSize | number | 20 | Flushes immediately when this count is hit |

const applytics = new ApplyticsClient({
  applyticsUrl: 'https://api.applytics.com',
  appKey: 'app_xxx',
  flushInterval: 3000,
  maxBatchSize: 10,
})

How It Works

identify() / alias() / group() / track() / page() / screen()
    → Event added to buffer
    → When buffer reaches maxBatchSize or flushInterval elapses
    → POST /v1/batch  (X-App-Key: app_xxx)
    → Applytics enqueues → 202 Accepted
    → RabbitMQ consumer writes to DB + updates user profile

Authentication

Every request is sent with the X-App-Key header:

X-App-Key: app_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Anonymous ID & Identity Stitching

A persistent anonymousId is created in localStorage for users who are not logged in. When identify() is called followed by alias(), the anonymous identity is merged with the userId — all events recorded before login are attributed to the real user.

Context

The following information is automatically collected from the browser and attached to every event:

{
  "context": {
    "userAgent": "Mozilla/5.0 ...",
    "locale": "en-US",
    "page": {
      "url": "https://app.example.com/home",
      "path": "/home",
      "referrer": "https://google.com"
    }
  }
}

Where to Get Your Key

Create an application in the Applytics dashboard → it will be provided in app_xxx format.

TypeScript Support

The package ships with type definitions — no separate @types package needed.

import { ApplyticsClient, ApplyticsConfig, EventType } from 'applytics-js'