> ## Documentation Index
> Fetch the complete documentation index at: https://canopy.wnstn.space/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Getting Started with the Cano Analytics JavaScript SDK
> Install and use the Cano JavaScript SDK to track events and identify users from browser or Node.js apps with a lightweight, promise-based API.
The Cano JavaScript SDK lets you track events and identify users from both browser and Node.js environments using a lightweight, promise-based API. Whether you're building a React SPA, a Next.js app, or a server-side Node service, the SDK handles batching, retries, and session management so you can focus on instrumentation.
## Installation
Install the SDK using your preferred package manager.
```bash npm theme={null}
npm install @cano/analytics
```
```bash yarn theme={null}
yarn add @cano/analytics
```
```bash pnpm theme={null}
pnpm add @cano/analytics
```
### CDN (no bundler)
If you're not using a bundler, load the SDK directly from the Cano CDN by adding this tag to your HTML ``:
```html index.html theme={null}
```
After the script loads, the `Cano` constructor is available on `window.Cano`.
## Initialization
Import and instantiate the client once — typically in your app's entry point — then reuse it throughout your codebase.
```javascript app.js theme={null}
import Cano from '@cano/analytics';
const cano = new Cano({
apiKey: 'cano_live_sk_your_key_here',
// Optional settings:
batchSize: 50, // batch events before sending
flushInterval: 5000, // flush every 5 seconds (ms)
debug: false // enable console logging
});
```
Pass `{ autoTrack: true }` in the constructor options to automatically capture page views and click events without any additional code. This is ideal for quick prototypes or content sites where manual instrumentation isn't practical.
## Core Methods
### `cano.track(event, properties?)`
Call `track` every time a user performs a meaningful action. Pass an event name and an optional object of properties that describe the action.
```javascript theme={null}
cano.track('button_clicked', {
button: 'upgrade_cta',
page: '/pricing'
});
```
### `cano.identify(userId, traits?)`
Call `identify` when you know who the current user is — for example, after they log in or sign up. Pass a stable user ID and any traits you want to associate with that profile.
```javascript theme={null}
cano.identify('usr_123', {
name: 'Ada Lovelace',
email: 'ada@example.com',
plan: 'pro'
});
```
### `cano.page(pageName?, properties?)`
Call `page` to record that a user has viewed a page or screen. Supply an optional name and any additional context about the page.
```javascript theme={null}
cano.page('Pricing Page', {
url: window.location.href,
referrer: document.referrer
});
```
### `cano.setSuperProperties(properties)`
Super properties are key-value pairs that are automatically merged into every subsequent `track` call. Use them for attributes that apply across all events — like app version or environment.
```javascript theme={null}
cano.setSuperProperties({
app_version: '2.1.0',
environment: 'production'
});
```
### `cano.alias(newId, previousId)`
Call `alias` to merge two user identities — for example, when an anonymous visitor signs up and you want to connect their pre-signup activity to their new account.
```javascript theme={null}
cano.alias('usr_123', 'anon_abc987');
```
### `cano.reset()`
Call `reset` to clear the current user's identity and super properties from the SDK — typically on logout. Subsequent events will be attributed to a new anonymous session.
```javascript theme={null}
cano.reset();
```
### `cano.flush()`
`flush` forces the SDK to immediately send any events queued in memory, bypassing the normal `batchSize` and `flushInterval` thresholds. It returns a `Promise` that resolves when the flush completes.
```javascript theme={null}
await cano.flush();
```
## Error Handling
Wrap `flush()` calls in a `try/catch` (or `.catch`) to handle network errors and API rejections gracefully.
```javascript error-handling.js theme={null}
async function safeSend() {
try {
await cano.flush();
console.log('Events flushed successfully');
} catch (err) {
// err.status contains the HTTP status code (e.g. 429, 500)
// err.message contains a human-readable description
console.error(`Failed to flush events: ${err.message} (status ${err.status})`);
// Optionally re-queue or alert your monitoring system here
}
}
```
Individual `track`, `identify`, and `page` calls are buffered in memory and do not throw on their own. Errors surface when the buffer is flushed — either automatically by the SDK or manually via `cano.flush()`.
## TypeScript Support
The SDK ships with first-class TypeScript definitions — no `@types` package needed. All constructor options, method signatures, and event property maps are fully typed.
```typescript app.ts theme={null}
import Cano, { CanoOptions, TrackProperties } from '@cano/analytics';
const options: CanoOptions = {
apiKey: 'cano_live_sk_your_key_here',
batchSize: 50,
flushInterval: 5000,
debug: false
};
const cano = new Cano(options);
const props: TrackProperties = {
button: 'upgrade_cta',
page: '/pricing'
};
cano.track('button_clicked', props);
```