# Integrating the app-tracker npm package

Use app-tracker to send application events from TypeScript or JavaScript in modern browsers and Node.js 16 or newer. This guide describes the local package implementation; check the installed release's documentation if behaviour differs. Examples are displayed as text and do not run on this website.

## Install and get an API key

```sh
npm install app-tracker
```

Register at https://portal.app-tracker.cloud/register, create your company workspace and an application, then use that application's API key. Use a placeholder in shared code samples and avoid including credentials or personal data in log payloads.

## Browser quick start

```typescript
import { AppTracker, LogType } from 'app-tracker';

const tracker = AppTracker.init('YOUR_API_KEY', {
  userAgentOrOs: navigator.userAgent,
  sendLogsInDevelopment: false,
  logLevel: [LogType.info, LogType.warn, LogType.error, LogType.critical],
  maxLogsCount: 10,
  sendLogsByTypesImmediately: [LogType.error, LogType.critical]
});

tracker.info('Checkout opened', { component: 'checkout' });
tracker.error('Payment request failed', { component: 'checkout', attempt: 2 });
```

Enable sendLogsInDevelopment explicitly if you want to test sending from a development environment. Keep it disabled when development events should stay out of the service. logInConsole controls console output separately.

## Node.js quick start

```javascript
const os = require('node:os');
const { AppTracker, LogType } = require('app-tracker');

const apiKey = process.env.APP_TRACKER_API_KEY;
if (!apiKey) throw new Error('Set APP_TRACKER_API_KEY before starting.');

const tracker = AppTracker.init(apiKey, {
  userAgentOrOs: os,
  sendLogsInDevelopment: false,
  logLevel: [LogType.info, LogType.warn, LogType.error, LogType.critical],
  maxLogsCount: 10,
  sendLogsByTypesImmediately: [LogType.error, LogType.critical]
});

async function runJob() {
  tracker.info('Job started', { component: 'worker' });
  // Perform your application work here.
  tracker.info('Job completed', { component: 'worker' });
  await tracker.flush();
}

runJob().catch(error => {
  console.error(error);
  process.exitCode = 1;
});
```

This example uses CommonJS. In a long-running service, await tracker.flush() as part of your own controlled shutdown sequence. Do not force process.exit() before awaited work completes. Configure NODE_ENV=development for Node development environments where appropriate.

## Log levels and filtering

The package provides debug(), info(), log(), warn(), error() and critical(). Set logLevel explicitly to choose the levels sent to the service. The service implementation defaults to sending error; critical events bypass the log-level filter. Configuring a level for immediate sending does not itself enable an otherwise filtered-out level.

## Batching, retries and timeouts

maxLogsCount controls the batch threshold. sendLogsByTypesImmediately requests immediate sending for selected levels. maxSendTries bounds send attempts; retryDelayMs controls the retry delay and requestTimeoutMs bounds individual HTTP attempts. endpointUrl overrides the destination when explicitly configured.

Network failures can prevent delivery. flush() attempts to send queued logs; after exhausted retries a batch may remain queued for a later flush or log event. A resolved flush() call is not proof of successful delivery, and queued in-memory logs can be lost when a process or page ends.

## Browser correlation

tracker.getCorrelationId() returns the browser correlation ID. It is generated in memory for a page lifetime and accompanies browser log batches. It is not a persistent user ID, cross-tab identity or cross-device session. Node.js payloads do not include a browser correlation ID.

## Redaction and client information

The package sanitizes messages and structured parameters before sending, and the backend sanitizes incoming logs again before storage. Recognized sensitive object keys include passwords, tokens, API keys, email addresses and identity fields. Text patterns include email addresses, IPv4 addresses and common authorization tokens. URL query strings and fragments are removed, and recognized identity path segments are replaced. Stored logs use encryption.

Redaction is pattern-based. It does not guarantee detection of every secret or every kind of personal data. Review payloads before logging and avoid sending unnecessary sensitive information.

userAgentOrOs is used to derive coarse browser/OS categories; the implementation does not transmit the raw user-agent string or the supplied OS module. Browser correlation is separate from landing-page visitor tracking: this informational site does not execute the SDK.

## Plans and data availability

Storage capacity, retention and plan limits depend on the selected plan. Dashboard drill-down depends on underlying raw-log availability. This guide does not advertise a fixed price, free-tier entitlement or guaranteed retention period.

## Further information

- [Package reference](https://www.npmjs.com/package/app-tracker)
- [Machine-readable product facts](product.json)