# Abrova docs (en)

https://abrova.ir — backend services for app developers in Iran.

## Abrova Trace

- Flutter SDK: https://abrova.ir/en/docs/trace/flutter-sdk

<BestPracticeList columns={2} items={[
  ['Simple Setup', 'Initialize with just a few lines of code'],
  ['Multi-Platform', 'Works on Web, Android, iOS, and Chrome Extensions'],
  ['Automatic Error Capture', 'Catches uncaught errors automatically'],
  ['Manual Error Reporting', 'Capture custom errors and messages'],
  ['Platform Detection', 'Automatically detects the running platform'],
  ['Configurable', 'Flexible configuration options'],
  ['Rich Context', 'Add custom data, tags, and user context to errors'],
  ['Breadcrumbs', 'Track user actions and events before errors'],
  ['Logging', 'Structured log ingestion with batching and levels'],
  ['Performance Tracking', 'Track HTTP requests and custom operations'],
  ['Native Crash Detection', 'Captures native crashes on iOS and Android and reports them on next app launch'],
]} />

Using an AI assistant? Use **Copy page for AI** at the top of this page and paste it into the chat. See [AI assistants](/docs/trace/ai-assistants).

### Supported Platforms

- **Flutter Web** — Full support with JS error catching
- **Chrome Extension** — Optimized for extension environment
- **Android** — Dart errors plus native crash capture (bundled native Abrova Trace SDK)
- **iOS** — Dart errors plus native crash capture (bundled native Abrova Trace SDK)
- **Desktop** — Windows, macOS, Linux (Dart errors only; no native crash capture)

<H2 id="installation" step={1}>Installation</H2>

The package comes from Abrova Center, so you do not need access to any other package registry. Two steps: point your project at the Abrova registry, then install.

**1. Add the package from the Abrova registry** in `pubspec.yaml`:

```yaml
# pubspec.yaml
dependencies:
  abrova_trace_flutter_sdk:
    hosted: https://center.abrova.ir/api/packages/abrova/pub
    version: ^0.2.6
```

**2. Add the native SDKs' sources.** The plugin uses the native Android and iOS SDKs for crash capture.

Android: add the Abrova Maven repository in `android/build.gradle` (or `android/settings.gradle`, wherever your project lists repositories):

```groovy
allprojects {
    repositories {
        google()
        mavenCentral()
        maven { url "https://center.abrova.ir/api/packages/abrova/maven" }
    }
}
```

iOS: add this inside the app target in `ios/Podfile`:

```ruby
pod 'AbrovaTrace', :git => 'https://center.abrova.ir/abrova/abrova-trace-ios-sdk.git', :tag => '0.2.4'
```

Then install:

```bash
flutter pub get
```

**Requirements**: Dart SDK 3.8.1 or newer. Android: API 19 (Android 4.4) or newer. iOS: 12.0 or newer, built with Xcode 15.3+ (Swift 5.10). On web, Dart errors, messages, logs and performance work; native crash capture is Android and iOS only.

<Callout kind="note" title="Which key?">
  Use your project's public key `ab_live_…` from Abrova Console. It is safe inside your app. Never put the server secret `ab_srv_…` in an app.
</Callout>

<H2 id="quick-start" step={2}>Quick Start</H2>

#### Basic Initialization

```dart
import 'package:flutter/material.dart';
import 'package:abrova_trace_flutter_sdk/abrova_trace_flutter_sdk.dart';

void main() async {
  WidgetsFlutterBinding.ensureInitialized();

  // Initialize AbrovaTrace
  await AbrovaTrace.init(AbrovaTraceConfig(
    apiKey: 'ab_live_your_api_key',
    environment: 'production',
    release: '1.0.0',
  ));

  runApp(MyApp());
}
```

#### Recommended: Initialize with Zone (Better Error Catching)

<Callout kind="note" title="Recommended">
  Using initWithZone catches async errors that would otherwise be missed. This is the recommended approach for production apps.
</Callout>

```dart
import 'package:flutter/material.dart';
import 'package:abrova_trace_flutter_sdk/abrova_trace_flutter_sdk.dart';

void main() async {
  // IMPORTANT: Initialize AbrovaTrace FIRST, before WidgetsFlutterBinding
  await AbrovaTrace.initWithZone(
    AbrovaTraceConfig(
      apiKey: 'ab_live_your_api_key',
      environment: 'production',
      release: '1.0.0',
      captureUncaughtErrors: true,
    ),
    () async {
      // Move all initialization inside this callback
      WidgetsFlutterBinding.ensureInitialized();

      // Any other async initialization goes here
      // await Firebase.initializeApp();
      // await setupDatabase();

      runApp(MyApp());
    },
  );
}
```

<H2 id="capture-errors" step={3}>Capture Errors</H2>

#### Capture Exceptions

```dart
try {
  riskyOperation();
} catch (e, stackTrace) {
  await AbrovaTrace.captureException(
    e,
    stackTrace: stackTrace,
    message: 'Failed to perform risky operation',
    extra: {'user_id': 'user123'},
  );
}
```

#### Capture Messages

```dart
await AbrovaTrace.captureMessage(
  'User completed onboarding',
  extra: {'step': 'welcome_screen'},
);

// With a level and tags
await AbrovaTrace.captureMessage(
  'API rate limit approaching',
  level: MessageLevel.warning,
  tags: {'feature': 'sync'},
);
```

<Callout kind="note" title="Where messages show up">
Messages appear in the Console under **Abrova Trace → Messages**, with their level, platform, extra data and breadcrumbs. They never create an issue. Levels: `MessageLevel.debug`, `info` (default), `warning`, `error`. Use messages for things your app reports on purpose ("checkout started", "sync finished"); for high-volume diagnostics use Logs.
</Callout>

#### Custom Error Context

```dart
await AbrovaTrace.captureException(
  exception,
  extra: {
    'user_id': 'user123',
    'feature': 'shopping_cart',
    'action': 'checkout',
    'cart_items': 5,
    'total_amount': 99.99,
  },
);
```

<H2 id="user-context" step={4}>User Context</H2>

Associate errors and logs with specific users and add custom metadata. If you use [Abrova Auth](/docs/auth/flutter), pass the signed-in user's id.

#### Set User ID

```dart
// Set after user login
AbrovaTrace.setUserId('user_123');

// Get current user ID
final userId = AbrovaTrace.getUserId();
```

#### Custom Extra Data

```dart
// Set individual extra
AbrovaTrace.setExtra('subscription', 'premium');

// Set multiple extras at once
AbrovaTrace.setExtras({
  'subscription': 'premium',
  'feature_flags': 'dark_mode,beta',
});

// Read extra data
final sub = AbrovaTrace.getExtra('subscription');
final allExtras = AbrovaTrace.getExtras();

// Clear all extras
AbrovaTrace.clearExtras();
```

#### Tags

```dart
// Set individual tag
AbrovaTrace.setTag('team', 'checkout');

// Set multiple tags at once
AbrovaTrace.setTags({
  'team': 'checkout',
  'module': 'payments',
});

// Read tags
final team = AbrovaTrace.getTag('team');
final allTags = AbrovaTrace.getTags();

// Clear all tags
AbrovaTrace.clearTags();
```

<H2 id="breadcrumbs" step={5}>Breadcrumbs</H2>

Breadcrumbs track user actions and events leading up to an error, helping you understand what happened before the crash.

```dart
import 'package:abrova_trace_flutter_sdk/abrova_trace_flutter_sdk.dart';

// User action breadcrumb
AbrovaTrace.addUserBreadcrumb('Added item to cart', data: {
  'product_id': 'abc',
  'quantity': 2,
});

// Navigation breadcrumb
AbrovaTrace.addNavigationBreadcrumb('HomeScreen', 'ProductDetail');

// HTTP request breadcrumb
AbrovaTrace.addHttpBreadcrumb('POST', 'https://api.example.com/orders', statusCode: 201);

// Generic breadcrumb
AbrovaTrace.addBreadcrumb(
  'Order placed',
  type: BreadcrumbType.info,
  data: {'order_id': '12345', 'total': 99.99},
);

// Clear all breadcrumbs
AbrovaTrace.clearBreadcrumbs();
```

<H2 id="auto-capture-taps-gesture-breadcrumbs" step={6}>Auto-Capture Taps (Gesture Breadcrumbs)</H2>

Automatically log every user tap as a breadcrumb. Works on every Flutter target — Web, Android, iOS, macOS, Windows, Linux — because it hooks into the framework's pointer router, not platform code.

When an error fires, the issue detail shows the widget the user tapped just before — usually enough to reproduce a bug without a perfect stack trace. This is especially useful on Flutter Web, where production stack traces can be partially symbolicated due to dart2js inlining.

#### Enable

Call once after init, after `WidgetsFlutterBinding.ensureInitialized()`. Idempotent — safe to call multiple times.

```dart
await AbrovaTrace.initWithZone(
  AbrovaTraceConfig(apiKey: 'ab_live_...'),
  () async {
    WidgetsFlutterBinding.ensureInitialized();

    // Enable automatic tap breadcrumbs
    AbrovaTrace.enableGestureBreadcrumbs();

    runApp(MyApp());
  },
);
```

#### What gets captured

Every tap on a recognized interactive widget produces a breadcrumb like:

```json
{
  "message": "Tap on ElevatedButton: \"Pay\"",
  "type": "user",
  "timestamp": "2026-05-15T14:32:18.421Z",
  "data": {
    "action": "tap",
    "widget": "ElevatedButton",
    "label": "Pay",
    "key": "checkout-pay-button",
    "path": "CheckoutPage > Scaffold",
    "route": "/checkout",
    "position": { "x": 187, "y": 614 }
  }
}
```

The `route` field is filled when you add `AbrovaTraceNavigatorObserver()` to your app's `navigatorObservers` (it also records navigation breadcrumbs automatically).

#### Recognized widgets

The tracker classifies these widget types out of the box (more specific types take priority):

- ElevatedButton
- TextButton
- OutlinedButton
- FilledButton
- IconButton
- FloatingActionButton
- Switch
- Checkbox
- Radio
- Slider
- PopupMenuButton
- DropdownButton
- InkWell
- InkResponse
- GestureDetector
- CupertinoButton

#### Tip: Add ValueKey to important widgets

The breadcrumb tries to find a label in this order: `Text` child → `Semantics.label` → `Tooltip.message` → `Icon.semanticLabel`.

For widgets without text (e.g. `IconButton`), add a `ValueKey` so you can grep for it in your code:

```dart
IconButton(
  key: const ValueKey('cart-remove-row-2'),  // ← surfaces in breadcrumb
  icon: const Icon(Icons.delete),
  onPressed: _removeItem,
)
```

#### Disable

```dart
AbrovaTrace.disableGestureBreadcrumbs();
```

<Callout kind="note" title="Privacy">
  The tracker captures the visible widget label — typically a button caption like "Pay" or "Add to Cart". It does not capture form input values, text-field contents, or anything entered by the user. A `ValueKey` is reported in addition to the label, not instead of it, so keep sensitive text out of the labels of tappable widgets.
</Callout>

<H2 id="logging" step={7}>Logging</H2>

Structured log ingestion with automatic batching and mobile lifecycle awareness. Enable it once, then use the level helpers from anywhere in your app:

```dart
// Enable logging after AbrovaTrace.init()
AbrovaTrace.enableLogging(sourceId: 'my-flutter-app');

AbrovaTrace.info('User login successful', metadata: {'user_id': 'user_123'});
```

See [Flutter SDK Logging](/docs/trace/flutter-logging) for the full pipeline — batching, log levels, background flushing, manual flush, and configuration.

<H2 id="performance-tracking" step={8}>Performance Tracking</H2>

Track HTTP request latency and custom operations for APM.

#### Automatic HTTP Client

```dart
// Create an HTTP client that automatically tracks all requests
final client = AbrovaTrace.createPerformanceClient();

final response = await client.get(Uri.parse('https://api.example.com/users'));
// Duration, status code, and errors are automatically reported
```

`createPerformanceClient()` takes the same options as `PerformanceHttpClient` (below) and fills in your API key, API URL, environment, release and platform from the config: `inner`, `addBreadcrumbs` (default `true`), `excludedHosts`, `minDurationMs` (default `0`).

#### PerformanceHttpClient

`PerformanceHttpClient` is an `http.BaseClient` (from `package:http`) that times every request and reports it as an `http` span. Use it directly when you want to wrap an existing client or construct it yourself:

```dart
import 'package:http/http.dart' as http;
import 'package:abrova_trace_flutter_sdk/abrova_trace_flutter_sdk.dart';

final client = PerformanceHttpClient(
  apiKey: 'ab_live_...',              // Required
  environment: 'production',
  releaseVersion: '1.0.0',
  inner: http.Client(),                // Default: a new http.Client()
  addBreadcrumbs: true,                // Also add HTTP breadcrumbs (default: true)
  excludedHosts: {'analytics.example.com'}, // Hosts to skip
  minDurationMs: 50,                   // Skip requests faster than this (default: 0)
);

final response = await client.get(Uri.parse('https://api.example.com/users'));

// Or wrap an existing client
final tracked = http.Client().withPerformanceTracking(apiKey: 'ab_live_...');

// Send buffered spans now, and stop the client when done
await client.flush();
client.close();
```

Spans are buffered and sent in batches of 10, or every 10 seconds. Requests to Abrova hosts are never tracked. Breadcrumb URLs have sensitive query parameters (token, password, api_key, ...) replaced with `[REDACTED]`. Spans show up under **Abrova Trace → Performance**.

#### Track Custom Operations

```dart
final result = await AbrovaTrace.trackOperation(
  'load_user_profile',
  () async {
    final user = await fetchUser();
    await cacheUser(user);
    return user;
  },
  operationType: 'custom',
);
```

#### Manual Span Reporting

```dart
final start = DateTime.now();

// Report a single performance span
await AbrovaTrace.reportPerformanceSpan(
  PerformanceSpan.fromHttpRequest(
    method: 'GET',
    url: 'https://api.example.com/products',
    statusCode: 200,
    startTime: start,
    durationMs: 245,
  ),
);

// Report a batch of spans
await AbrovaTrace.reportPerformanceSpanBatch([
  PerformanceSpan.fromHttpRequest(
    method: 'GET',
    url: '/api/users',
    statusCode: 200,
    startTime: start,
    durationMs: 150,
  ),
  PerformanceSpan.custom(
    operation: 'image_processing',
    startTime: start,
    durationMs: 800,
  ),
]);
```

<H2 id="platform-specific-usage" step={9}>Platform-Specific Usage</H2>

#### Chrome Extension

```dart
void main() async {
  await AbrovaTrace.init(AbrovaTraceConfig(
    apiKey: 'ab_live_your_api_key',
    environment: 'production',
    debug: false, // Disable in production extensions
  ));

  runApp(MyExtensionApp());
}
```

#### Mobile App

```dart
void main() async {
  // Required before init() on Android and iOS
  WidgetsFlutterBinding.ensureInitialized();

  await AbrovaTrace.init(AbrovaTraceConfig(
    apiKey: 'ab_live_your_api_key',
    environment: 'production',
    captureUncaughtErrors: true, // Recommended for mobile
  ));

  runApp(MyMobileApp());
}
```

#### Web App

```dart
void main() async {
  await AbrovaTrace.init(AbrovaTraceConfig(
    apiKey: 'ab_live_your_api_key',
    environment: 'production',
    debug: kDebugMode, // Enable debug in development
  ));

  runApp(MyWebApp());
}
```

<H2 id="crash-detection" step={10}>Crash Detection</H2>

AbrovaTrace provides comprehensive error detection for any Flutter app, regardless of what libraries or native code you use.

- **Dart Exceptions** — Captured in real-time
- **Async Errors** — Captured in real-time (with initWithZone)
- **Platform Exceptions** — Captured in real-time
- **Native Crashes** — iOS and Android only; reported on next app launch

#### How Native Crash Detection Works

The plugin bundles the native Abrova Trace SDKs for iOS and Android and starts them during `init()` / `initWithZone()`:

1. **iOS** — PLCrashReporter records signal and Mach exception crashes to disk
2. **Android** — an uncaught exception handler, plus `ApplicationExitInfo` (Android 11 / API 30+) for native crashes and ANRs
3. On the next launch, the native SDK reads the saved report and sends it to Abrova Trace as an issue

No extra code is needed. Crashes are sent on the *next* launch, so a crash appears after the user reopens the app.

<Callout kind="note" title="Shutting down">
  `AbrovaTrace.close()` flushes pending logs and releases the SDK. It is not needed for crash detection. After `close()`, calls such as `captureException()` throw until you call `init()` again, so only call it when your app is really shutting down.
</Callout>

<H2 id="configuration-options" step={11}>Configuration Options</H2>

```dart
AbrovaTraceConfig(
  apiKey: 'ab_live_your_api_key',          // Required
  environment: 'production',             // Default: 'production'
  release: '1.0.0',                      // Optional
  captureUncaughtErrors: true,           // Default: true
  enabled: true,                         // Default: true
  debug: false,                          // Default: false
  timeout: 30,                           // Default: 30 seconds
  sampleRate: 1.0,                       // 0.0 to 1.0
  maxBreadcrumbs: 20,                    // Default: 20
  enableOfflineStorage: true,            // Default: true
  collectDeviceInfo: true,               // Default: true
  logHandler: (level, message, error, stackTrace) {}, // Optional
)
```

<ConfigTable rows={[
  ['apiKey', 'String', 'Yes', 'Your project API Key'],
  ['environment', 'String', 'No', 'Environment name (default: "production")'],
  ['release', 'String', 'No', 'App version identifier'],
  ['captureUncaughtErrors', 'bool', 'No', 'Catch uncaught errors automatically (default: true)'],
  ['enabled', 'bool', 'No', 'Enable/disable SDK (default: true)'],
  ['debug', 'bool', 'No', 'Enable debug logging (default: false)'],
  ['timeout', 'int', 'No', 'HTTP request timeout in seconds (default: 30)'],
  ['sampleRate', 'double', 'No', 'Error capture sample rate 0.0-1.0 (default: 1.0)'],
  ['maxBreadcrumbs', 'int', 'No', 'Max breadcrumbs to keep (default: 20)'],
  ['enableOfflineStorage', 'bool', 'No', 'Keep errors that cannot be sent while the device is offline and send them later (default: true; not on web). See Offline Storage below'],
  ['collectDeviceInfo', 'bool', 'No', 'Attach device, OS and app context to errors and messages (default: true)'],
  ['apiUrl', 'String', 'No', 'Override the API URL (default: https://trace.abrova.ir)'],
  ['logHandler', 'AbrovaTraceLogCallback', 'No', 'Receive the SDK internal log lines (level, message, error, stackTrace)'],
]} />

#### Offline Storage

With `enableOfflineStorage` on (the default), errors that cannot be sent because the device is offline are kept on the device and sent later. Only errors are kept — messages, logs and performance data are not saved to disk.

- **Native errors (Android, iOS)** — the option is passed to the bundled native SDKs, which keep up to 100 unsent errors and send them later. Requires version 0.2.5 or newer.
- **Dart errors** — when a send fails with a network error or timeout, the error is saved to a file (up to 100; the oldest are dropped first) and re-sent the next time the app starts, with `AbrovaTrace.init()` and with `AbrovaTrace.initWithZone()` alike (`initWithZone()` needs version 0.2.5 or newer). A stored error the server refuses for good is dropped instead of being retried at every start; it is kept when the server asks to try again later (HTTP 408, 429) or has a problem (5xx).
- **Web** — nothing is stored.

Before 0.2.6 the SDK could print `AbrovaTrace: Failed to initialize offline storage: Binding has not yet been initialized` at start when you used `initWithZone()` with `WidgetsFlutterBinding.ensureInitialized()` inside the app function. It was harmless, and 0.2.6 no longer prints it: offline storage sets itself up once the app has started.

<H2 id="error-information-captured" step={12}>Error Information Captured</H2>

The SDK automatically captures the following information with every error:

- **Error Message** — Exception message or custom message
- **Stack Trace** — Full stack trace for debugging
- **Platform** — Detected platform (flutter_web, flutter_android, etc.)
- **Environment** — Environment name (production, development, etc.)
- **Release** — App version/release identifier
- **Timestamp** — When the error occurred
- **User ID, session ID, extras, tags and breadcrumbs** — Whatever you set on the SDK
- **Device context** — Device model, OS and version, app version and build (when `collectDeviceInfo` is on; on web only locale and time zone)
- **User Agent** — SDK version, platform and release (on web, the browser's user agent)
- **URL** — Current page URL (web only)

### Complete Example

```dart
import 'package:flutter/material.dart';
import 'package:abrova_trace_flutter_sdk/abrova_trace_flutter_sdk.dart';

void main() async {
  await AbrovaTrace.initWithZone(
    AbrovaTraceConfig(
      apiKey: 'ab_live_your_api_key',
      environment: const String.fromEnvironment('ENV', defaultValue: 'development'),
      release: '1.0.0',
      captureUncaughtErrors: true,
      sampleRate: 1.0,
      maxBreadcrumbs: 20,
      enableOfflineStorage: true,
      debug: true,
    ),
    () async {
      WidgetsFlutterBinding.ensureInitialized();

      // Auto-capture taps as breadcrumbs (all platforms)
      AbrovaTrace.enableGestureBreadcrumbs();

      // Enable logging
      AbrovaTrace.enableLogging(
        sourceId: 'my-flutter-app',
        sourceName: 'My Flutter App',
      );

      runApp(MyApp());
    },
  );
}

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      home: HomeScreen(),
    );
  }
}

class HomeScreen extends StatefulWidget {
  const HomeScreen({super.key});

  @override
  State<HomeScreen> createState() => _HomeScreenState();
}

class _HomeScreenState extends State<HomeScreen> {
  @override
  void initState() {
    super.initState();
    AbrovaTrace.setUserId('user_123');
    AbrovaTrace.setTag('screen', 'HomeScreen');
    AbrovaTrace.addNavigationBreadcrumb('Launch', 'HomeScreen');
  }

  Future<void> _handlePurchase() async {
    AbrovaTrace.addUserBreadcrumb('Initiated purchase', data: {'product': 'Premium'});

    try {
      await AbrovaTrace.trackOperation('process_purchase', () async {
        await processPurchase();
      });
      AbrovaTrace.info('Purchase successful', metadata: {'amount': 99.99});
    } catch (e, stackTrace) {
      await AbrovaTrace.captureException(
        e,
        stackTrace: stackTrace,
        message: 'Purchase failed',
        extra: {'user_id': 'user_123', 'screen': 'HomeScreen'},
      );
    }
  }

  Future<void> processPurchase() async {
    // ... purchase logic
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('My App')),
      body: Center(
        child: ElevatedButton(
          onPressed: _handlePurchase,
          child: const Text('Purchase'),
        ),
      ),
    );
  }
}
```

### Best Practices

<BestPracticeList items={[
  ['Initialize Early', 'Initialize AbrovaTrace before runApp() to catch all errors from app start'],
  ['Use initWithZone', 'Use initWithZone for better async error catching in production apps'],
  ['Call close() Only on Shutdown', 'close() flushes logs and tears the SDK down; native crash detection does not depend on it'],
  ['Set User ID After Auth', 'Call setUserId() after login to associate errors with users'],
  ['Add Breadcrumbs', 'Add breadcrumbs for important user actions (purchases, navigation, form submissions)'],
  ['Enable Gesture Breadcrumbs', 'Call enableGestureBreadcrumbs() to auto-capture taps. Critical for Flutter Web where stack traces can be partial'],
  ['Add ValueKey to Important Widgets', 'Tag checkout buttons, payment fields, and key actions with ValueKey so they are identifiable in tap breadcrumbs'],
  ['Use Tags for Filtering', 'Set tags like team, module, or feature for easy error filtering in the dashboard'],
  ['Enable Logging Early', 'Enable logging right after init() to capture all events from app start'],
  ['Use Different Environments', 'Separate production, staging, and development errors using the environment config'],
  ['Enable Debug Mode in Development', 'Set debug: true during development to see SDK logs and verify integration'],
]} />

- Node.js SDK: https://abrova.ir/en/docs/trace/nodejs-sdk

<BestPracticeList columns={2} items={[
  ['Server-Side Error Tracking', 'Comprehensive error monitoring for Node.js applications'],
  ['Automatic Error Capture', 'Catches uncaught exceptions and unhandled promise rejections'],
  ['Express.js Middleware', 'Built-in middleware for Express.js request/error handling'],
  ['Breadcrumbs', 'Track events leading up to an error for better context'],
  ['Scoped Context', 'Temporarily set context for a block of code with withScope'],
  ['User Context', 'Associate errors with user information'],
  ['Error Filtering', 'Filter and modify events with beforeSend, ignoredExceptions and ignoredPaths'],
  ['TypeScript Support', 'Full TypeScript definitions included'],
]} />

<H2 id="installation" step={1}>Installation</H2>

Packages come from Abrova Center. Two steps:

**1. Add the Abrova registry** to `.npmrc` in your project root (npm, yarn and pnpm all read it):

```
# .npmrc
@abrova-trace:registry=https://center.abrova.ir/api/packages/abrova/npm/
```

**2. Install the package:**

```bash
npm install @abrova-trace/nodejs-sdk
# or
yarn add @abrova-trace/nodejs-sdk
# or
pnpm add @abrova-trace/nodejs-sdk
```

<H2 id="quick-start" step={2}>Quick Start</H2>

```javascript
const AbrovaTrace = require('@abrova-trace/nodejs-sdk');

// Initialize AbrovaTrace
AbrovaTrace.init({
  apiKey: 'ab_live_your_api_key',            // project API key
  serverSecret: process.env.ABROVA_SERVER_SECRET, // ab_srv_... (required)
  environment: 'production',
  release: '1.0.0'
});

// Capture exceptions
try {
  throw new Error('Something went wrong!');
} catch (error) {
  AbrovaTrace.captureException(error);
}

// Capture messages
AbrovaTrace.captureMessage('User completed checkout');
```

<H2 id="capture-errors" step={3}>Capture Errors</H2>

#### Capture Exceptions

```javascript
AbrovaTrace.captureException(error, {
  extra: {
    userId: 123,
    feature: 'checkout'
  }
});
```

#### Capture Messages

```javascript
AbrovaTrace.captureMessage('Something happened', {
  level: 'warning',                   // 'debug' | 'info' (default) | 'warning' | 'error'
  extra: { context: 'additional info' },
  tags: { feature: 'checkout' }
});
```

<Callout kind="note" title="Where messages show up">
Messages appear in the Console under **Abrova Trace → Messages**, with their level, platform, extra data and breadcrumbs. They never create an issue. `'warn'` is sent as `warning`, `'fatal'` as `error` and `'trace'` as `debug`; anything else as `info`. Use messages for things your app reports on purpose ("checkout started", "sync finished"); for high-volume diagnostics use Logs.
</Callout>

<H2 id="breadcrumbs" step={4}>Breadcrumbs</H2>

Breadcrumbs track events leading up to an error, helping you understand what happened before the error occurred.

#### Manual Breadcrumbs

```javascript
AbrovaTrace.addBreadcrumb({
  message: 'User clicked checkout',
  category: 'user-action',
  level: 'info',
  data: { cartTotal: 99.99 }
});
```

#### Breadcrumb Helpers

```javascript
const { Breadcrumb } = require('@abrova-trace/nodejs-sdk');

// HTTP request breadcrumb
AbrovaTrace.addBreadcrumb(Breadcrumb.http('POST', '/api/order', 200, 150));

// Database query breadcrumb
AbrovaTrace.addBreadcrumb(Breadcrumb.database('SELECT * FROM users', 25));

// User action breadcrumb
AbrovaTrace.addBreadcrumb(Breadcrumb.user('clicked_button', { buttonId: 'submit' }));
```

<H2 id="user-context" step={5}>User Context</H2>

```javascript
AbrovaTrace.setUser({
  id: 123,
  email: 'user@example.com',
  username: 'john_doe'
});
```

<H2 id="scoped-context" step={6}>Scoped Context</H2>

Use scoped context to set a user and extra values for one synchronous block of code. The user and extra values are restored when the callback returns; breadcrumbs added inside the block are kept.

```javascript
AbrovaTrace.withScope((scope) => {
  scope.setUser({ id: 456 });
  scope.setExtra('operation', 'bulk_import');
  scope.addBreadcrumb({ message: 'Starting import' });

  // Errors captured here include this context
  AbrovaTrace.captureException(new Error('Import failed'));
});
// Context is restored after the block
```

<H2 id="express-js-integration" step={7}>Express.js Integration</H2>

Built-in middleware for automatic request tracking and error handling in Express.js applications.

```javascript
const express = require('express');
const AbrovaTrace = require('@abrova-trace/nodejs-sdk');

const app = express();

// Initialize
AbrovaTrace.init({
  apiKey: 'ab_live_your_api_key',
  serverSecret: process.env.ABROVA_SERVER_SECRET,
  environment: process.env.NODE_ENV
});

// Add middleware
const middleware = AbrovaTrace.expressMiddleware();
app.use(middleware.requestHandler());

// Your routes
app.get('/api/users/:id', async (req, res) => {
  // Your route logic
});

// Error handler (must be last)
app.use(middleware.errorHandler());

app.listen(3000);
```

<Callout kind="note" title="Important: Error Handler Placement">
  The error handler middleware must be added after all routes. Express requires error-handling middleware to be defined last. Call `AbrovaTrace.init()` before `AbrovaTrace.expressMiddleware()`: middleware created before `init()` does nothing.
</Callout>

Errors reported by `errorHandler()` include the request method, URL, path, matched route (for example `/api/users/:id`), query and route parameters, user agent, IP address and the response status (`err.status` / `err.statusCode` when it is 4xx or 5xx, otherwise 500). Request headers and the request body are never sent. Query and route parameters whose name looks sensitive (password, token, secret, auth, API key, session, cookie, signature, OTP, code) are sent as `[REDACTED]`. The same applies to the request address sent with errors and breadcrumbs: the values of sensitive query parameters in it are replaced with `[REDACTED]` (for example `/reset?token=[REDACTED]&page=2`), while parameter names and other values are kept (since 0.2.3).

<H2 id="database-query-tracking" step={8}>Database Query Tracking</H2>

```javascript
const AbrovaTrace = require('@abrova-trace/nodejs-sdk');

async function executeQuery(sql, params) {
  const startTime = Date.now();

  try {
    AbrovaTrace.addBreadcrumb({
      message: 'Executing query',
      category: 'database',
      data: { sql: sql.substring(0, 100) }
    });

    const results = await db.query(sql, params);

    AbrovaTrace.addBreadcrumb({
      message: 'Query completed',
      category: 'database',
      data: { duration_ms: Date.now() - startTime }
    });

    return results;
  } catch (error) {
    AbrovaTrace.captureException(error, {
      extra: { sql, duration_ms: Date.now() - startTime }
    });
    throw error;
  }
}
```

<H2 id="error-filtering" step={9}>Error Filtering</H2>

Use the beforeSend hook to filter or modify events before they are sent to AbrovaTrace. It runs for exceptions and for `captureMessage()` events; return `null` to drop one. To skip whole exception classes or request paths, use the `ignoredExceptions` and `ignoredPaths` options instead.

```javascript
AbrovaTrace.init({
  apiKey: 'ab_live_your_api_key',
  serverSecret: process.env.ABROVA_SERVER_SECRET,
  beforeSend(event) {
    // Don't send network errors
    if (event.message.includes('ECONNREFUSED')) {
      return null;
    }

    // Add custom data (errors are AbrovaTraceError objects; messages from
    // captureMessage() arrive as plain objects without setExtra)
    if (typeof event.setExtra === 'function') {
      event.setExtra('server_id', process.env.SERVER_ID);
    }

    return event;
  }
});
```

<H2 id="graceful-shutdown" step={10}>Graceful Shutdown</H2>

Errors, messages, logs and performance spans are sent in the background. `flush()` sends everything that is still waiting, so call it before the process exits: before `process.exit()`, at the end of a serverless handler, and in your shutdown handlers.

```javascript
process.on('SIGTERM', async () => {
  console.log('Shutting down...');
  const sent = await AbrovaTrace.flush(2000); // false if 2 seconds pass before everything is sent
  await AbrovaTrace.close();                  // Sends buffered logs and performance spans, then resets the SDK
  process.exit(0);
});
```

`flush(timeout)` takes a timeout in milliseconds (default: 5000) and returns a `Promise<boolean>`: `true` when sending finished within the timeout, `false` when the timeout passed first. It never rejects. `close()` also returns a Promise; it sends buffered logs and performance spans but does not wait for errors and messages that are still being sent, so call `flush()` first. After `close()`, call `init()` again before you use the SDK.

In a serverless function, flush before the handler returns:

```javascript
exports.handler = async (event) => {
  try {
    return await processEvent(event);
  } catch (error) {
    AbrovaTrace.captureException(error);
    throw error;
  } finally {
    await AbrovaTrace.flush();
  }
};
```

<H2 id="source-maps" step={11}>Source Maps</H2>

If you're using TypeScript, bundlers (webpack, esbuild), or Babel, enable source maps for accurate stack traces:

```bash
node --enable-source-maps app.js
```

Or programmatically in your app:

```javascript
process.setSourceMapsEnabled(true);
```

<H2 id="logging" step={12}>Logging</H2>

Structured server-side logging, batched with exponential backoff and zero dependencies. Logs go to **Abrova Trace → Logs** and are separate from `captureMessage()` (Messages). After `init()`, enable logging once and log from anywhere:

```javascript
AbrovaTrace.enableLogging({ sourceId: 'api-server' });

AbrovaTrace.info('Server started on port 3000');
AbrovaTrace.warn('Database connection slow', { latency: 2500 });
AbrovaTrace.logError('Failed to process payment', { orderId: '12345' });
```

See [Node.js SDK Logging](/docs/trace/nodejs-logging) for the full pipeline — log levels, Express integration, batching, and graceful shutdown.

<H2 id="configuration-options" step={13}>Configuration Options</H2>

```javascript
AbrovaTrace.init({
  apiKey: 'ab_live_your_api_key',        // Required
  serverSecret: 'ab_srv_your_secret',     // Required
  environment: 'production',              // Default: NODE_ENV or 'development'
  release: '1.0.0',                       // Default: npm_package_version or '1.0.0'
  enabled: true,                          // Default: true
  debug: false,                           // Default: false
  timeout: 5000,                          // Default: 5000ms
  captureUncaughtExceptions: true,        // Default: true
  captureUnhandledRejections: true,       // Default: true
  maxBreadcrumbs: 50,                     // Default: 50 (max 100)
  sampleRate: 1.0,                        // Default: 1.0 (captureException and captureMessage)
  ignoredExceptions: ['ValidationError'], // Error class, error.name, or RegExp
  ignoredPaths: ['/health*'],             // Express paths not reported
  beforeSend: (event) => event,           // Filter/modify events
});
```

<ConfigTable rows={[
  ['apiKey', 'string', 'Yes', 'Your project API key (ab_live_xxx)'],
  ['serverSecret', 'string', 'Yes', 'Your server secret (ab_srv_xxx); keep it on the server'],
  ['environment', 'string', 'No', 'Environment name (default: NODE_ENV or "development")'],
  ['release', 'string', 'No', 'App version (default: npm_package_version or "1.0.0")'],
  ['enabled', 'boolean', 'No', 'Enable/disable tracking (default: true)'],
  ['debug', 'boolean', 'No', 'Enable debug logging (default: false)'],
  ['timeout', 'number', 'No', 'HTTP timeout in milliseconds, 1000-30000 (default: 5000)'],
  ['captureUncaughtExceptions', 'boolean', 'No', 'Auto-capture uncaught exceptions (default: true)'],
  ['captureUnhandledRejections', 'boolean', 'No', 'Auto-capture unhandled rejections (default: true)'],
  ['maxBreadcrumbs', 'number', 'No', 'Max breadcrumbs to keep, up to 100 (default: 50). The 10 most recent are sent with each event'],
  ['sampleRate', 'number', 'No', 'Fraction of captureException() and captureMessage() events sent, 0.0-1.0 (default: 1.0)'],
  ['ignoredExceptions', 'array', 'No', 'Exceptions that captureException() and the Express error handler do not report: an error class (matched with instanceof), a string equal to error.name, or a RegExp tested against error.name. Uncaught exceptions and unhandled rejections are always reported'],
  ['ignoredPaths', 'array', 'No', 'Request paths the Express middleware skips: glob, exact path, or RegExp'],
  ['beforeSend', 'function', 'No', 'Hook to filter/modify errors and messages before sending; return null to drop'],
]} />

### SDK Stats

```javascript
const stats = AbrovaTrace.getStats();
console.log(stats);
// {
//   isEnabled: true,
//   breadcrumbCount: 5,
//   rateLimiter: { totalErrorsInWindow: 3, uniqueErrorsInWindow: 2, totalLimit: 100, errorLimit: 10, windowMs: 60000 },
//   config: { environment: 'production', release: '1.0.0', apiKey: 'ab_live_abc1234...' }
// }
```

### TypeScript Support

The SDK includes full TypeScript definitions. Import types as needed:

```typescript
import AbrovaTrace, {
  AbrovaTraceInitOptions,
  AbrovaTraceError,
  Breadcrumb,
  BreadcrumbOptions,
  UserContext
} from '@abrova-trace/nodejs-sdk';
```

### Requirements

- **Node.js** — >= 14.0.0
- **Express (optional)** — >= 4.0.0

### API Reference

#### AbrovaTrace

- `init(config)` — Initialize SDK
- `captureException(error, options?)` — Capture an error
- `captureMessage(message, options?)` — Send a message to Abrova Trace → Messages (`options`: `level`, `extra`, `tags`)
- `addBreadcrumb(breadcrumb)` — Add a breadcrumb
- `setUser(user)` — Set user context
- `setRequestContext(context)` — Set request context attached to captured events
- `withScope(callback)` — Run code with isolated scope
- `expressMiddleware()` — Get Express.js middleware
- `flush(timeout?)` — Send pending errors, messages, logs and performance spans; `timeout` in milliseconds (default: 5000). Returns `Promise<boolean>`: `false` if the timeout passes first
- `close()` — Flush logs and performance spans, then clean up (returns a Promise)
- `getStats()` — Get SDK statistics
- `enableLogging(options?)`, `log()`, `trace()`, `logDebug()`, `info()`, `warn()`, `logError()`, `fatal()`, `flushLogs()` — Logging (see [Node.js SDK Logging](/docs/trace/nodejs-logging))
- `trackOperation(name, fn, options?)`, `reportPerformanceSpan(span)`, `reportPerformanceSpanBatch(spans)`, `flushPerformance()` — Performance spans

#### Breadcrumb Helpers

- `Breadcrumb.http(method, url, status?, duration?)` — HTTP request breadcrumb
- `Breadcrumb.database(query, duration, error?)` — Database query breadcrumb
- `Breadcrumb.user(action, data?)` — User action breadcrumb
- `Breadcrumb.console(level, message, ...args)` — Console output breadcrumb
- `Breadcrumb.navigation(from, to, method?)` — Navigation breadcrumb
- `Breadcrumb.custom(message, category, data?)` — Breadcrumb with your own category

#### Express Middleware

- `requestHandler()` — Returns request tracking middleware
- `errorHandler()` — Returns error handling middleware
- `userMiddleware()` — Sets user context from `req.user` (id, email, username)
- `transactionMiddleware(name)` — Adds start and completion breadcrumbs (duration, status) for a named route

### Complete Example

```javascript
const express = require('express');
const AbrovaTrace = require('@abrova-trace/nodejs-sdk');
const { Breadcrumb } = require('@abrova-trace/nodejs-sdk');

// Initialize AbrovaTrace
AbrovaTrace.init({
  apiKey: 'ab_live_your_api_key',
  serverSecret: process.env.ABROVA_SERVER_SECRET,
  environment: process.env.NODE_ENV || 'development',
  release: '1.0.0',
  captureUncaughtExceptions: true,
  captureUnhandledRejections: true,
  maxBreadcrumbs: 50,
  debug: process.env.NODE_ENV === 'development',
});

const app = express();

// Add AbrovaTrace middleware
const middleware = AbrovaTrace.expressMiddleware();
app.use(middleware.requestHandler());

app.use(express.json());

// Set user context from auth
app.use((req, res, next) => {
  if (req.user) {
    AbrovaTrace.setUser({
      id: req.user.id,
      email: req.user.email,
    });
  }
  next();
});

app.get('/api/users/:id', async (req, res) => {
  AbrovaTrace.addBreadcrumb(Breadcrumb.user('view_user', {
    userId: req.params.id,
  }));

  try {
    const user = await db.query('SELECT * FROM users WHERE id = ?', [req.params.id]);
    AbrovaTrace.addBreadcrumb(Breadcrumb.database('SELECT * FROM users', 15));
    res.json(user);
  } catch (error) {
    AbrovaTrace.captureException(error, {
      extra: { userId: req.params.id },
    });
    res.status(500).json({ error: 'Internal Server Error' });
  }
});

// Error handler (must be last)
app.use(middleware.errorHandler());

// Graceful shutdown
process.on('SIGTERM', async () => {
  await AbrovaTrace.flush(2000);
  await AbrovaTrace.close();
  process.exit(0);
});

app.listen(3000, () => console.log('Server running on port 3000'));
```

### Best Practices

<BestPracticeList items={[
  ['Initialize Early', 'Initialize AbrovaTrace at the top of your application entry point to catch all errors'],
  ['Use Express Middleware', 'Add the request handler first and error handler last for comprehensive Express.js tracking'],
  ['Set User Context', 'Associate errors with user information for easier debugging'],
  ['Use Scoped Context', 'Use withScope to set temporary context for a synchronous block; the SDK context is process-wide, so it is restored when the callback returns'],
  ['Add Breadcrumbs', 'Track important operations (DB queries, HTTP calls, user actions) as breadcrumbs'],
  ['Graceful Shutdown', 'Await flush() and close() on SIGTERM/SIGINT so pending errors, logs and spans are sent'],
  ['Enable Source Maps', 'Use --enable-source-maps for accurate stack traces in TypeScript/bundled apps'],
  ['Use beforeSend', 'Filter out noisy errors and enrich error data with custom context'],
]} />

- Next.js SDK: https://abrova.ir/en/docs/trace/nextjs-sdk

<BestPracticeList columns={2} items={[
  ['Error Tracking', 'Automatic capture of uncaught errors, promise rejections, and React errors'],
  ['Crash Detection', 'Browser tab crash and unresponsiveness detection'],
  ['Breadcrumbs', 'Track user actions and events for error context'],
  ['Source Maps', 'Automatic source map support for readable stack traces'],
  ['Next.js Optimized', 'Built for App Router and Pages Router'],
  ['React Integration', 'Error boundaries, hooks, and components'],
  ['Universal', 'Works in browser and Node.js (API routes, server components)'],
  ['Rich Context', 'Navigation tracking, user sessions, custom metadata'],
  ['Configurable', 'Sampling, filtering, and hooks'],
]} />

<H2 id="installation" step={1}>Installation</H2>

Packages come from Abrova Center. Two steps:

**1. Add the Abrova registry** to `.npmrc` in your project root (npm, yarn and pnpm all read it):

```
# .npmrc
@abrova-trace:registry=https://center.abrova.ir/api/packages/abrova/npm/
```

**2. Install the package:**

```bash
npm install @abrova-trace/nextjs-sdk
# or
yarn add @abrova-trace/nextjs-sdk
# or
pnpm add @abrova-trace/nextjs-sdk
```

<H2 id="quick-start" step={2}>Quick Start</H2>

#### App Router (Next.js 13+)

Create `app/providers.tsx`:

```tsx
'use client';

import { useEffect } from 'react';
import { AbrovaTrace } from '@abrova-trace/nextjs-sdk';
import { useAbrovaTraceNavigation } from '@abrova-trace/nextjs-sdk/react';

export function Providers({ children }: { children: React.ReactNode }) {
  useEffect(() => {
    AbrovaTrace.init({
      apiKey: 'ab_live_your_api_key',
      environment: process.env.NODE_ENV,
      release: process.env.NEXT_PUBLIC_APP_VERSION,
      debug: process.env.NODE_ENV === 'development',
    });
  }, []);

  // Track navigation
  useAbrovaTraceNavigation();

  return <>{children}</>;
}
```

`useAbrovaTraceNavigation()` reads `useSearchParams()`. If `next build` complains about a missing Suspense boundary, call it from a small component wrapped in `<Suspense>` instead (see the `NavigationTracker` in Navigation Tracking below).

Update `app/layout.tsx`:

```tsx
import { Providers } from './providers';

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        <Providers>{children}</Providers>
      </body>
    </html>
  );
}
```

#### Pages Router (Next.js 12 and earlier)

Update `pages/_app.tsx`:

```tsx
import { useEffect } from 'react';
import type { AppProps } from 'next/app';
import { AbrovaTrace } from '@abrova-trace/nextjs-sdk';
import { useAbrovaTracePagesRouter } from '@abrova-trace/nextjs-sdk/react';

function MyApp({ Component, pageProps }: AppProps) {
  useEffect(() => {
    AbrovaTrace.init({
      apiKey: 'ab_live_your_api_key',
      environment: process.env.NODE_ENV,
      release: process.env.NEXT_PUBLIC_APP_VERSION,
    });
  }, []);

  // Track navigation
  useAbrovaTracePagesRouter();

  return <Component {...pageProps} />;
}

export default MyApp;
```

<H2 id="error-boundary" step={3}>Error Boundary</H2>

Wrap your components with the error boundary to automatically catch and report React errors:

#### Basic Usage

```tsx
import { ErrorBoundary } from '@abrova-trace/nextjs-sdk/react';

export default function Page() {
  return (
    <ErrorBoundary fallback={<div>Something went wrong!</div>}>
      <YourComponent />
    </ErrorBoundary>
  );
}
```

#### With Reset Function

```tsx
<ErrorBoundary
  fallback={(error, errorInfo, resetError) => (
    <div>
      <h1>Error: {error.message}</h1>
      <button onClick={resetError}>Try again</button>
    </div>
  )}
>
  <YourComponent />
</ErrorBoundary>
```

#### With Error Handler

```tsx
<ErrorBoundary
  onError={(error, errorInfo) => {
    console.log('Error occurred:', error);
    // Custom error handling
  }}
>
  <YourComponent />
</ErrorBoundary>
```

#### Default Fallback

Without a `fallback`, the boundary renders a built-in panel: a "Something went wrong" heading, a short message, and a **Try again** button that resets the boundary. Since 0.1.8 the error message, stack trace and component stack are no longer shown in production: they appear in a collapsible "Error details" block only when `showErrorDetails` is `true`, and it defaults to `process.env.NODE_ENV !== 'production'` (shown in development, hidden in production builds). A custom `fallback` is rendered as you wrote it and is not affected by `showErrorDetails`.

```tsx
<ErrorBoundary
  fallbackMessage="We could not load this section."
  showErrorDetails={false}
>
  <YourComponent />
</ErrorBoundary>
```

#### Props

<ConfigTable rows={[
  ['children', 'ReactNode', 'Yes', 'The components to protect'],
  ['fallback', 'ReactNode | function', 'No', 'Custom UI shown after an error: an element, or a function (error, errorInfo, resetError) that returns one. Replaces the default fallback'],
  ['onError', 'function', 'No', 'Called with (error, errorInfo) after the error has been reported'],
  ['showDefaultFallback', 'boolean', 'No', 'Render the built-in fallback when no fallback is given (default: true). With false, nothing is rendered'],
  ['fallbackMessage', 'string', 'No', 'Message in the built-in fallback (default: "An unexpected error occurred. Our team has been notified.")'],
  ['showErrorDetails', 'boolean', 'No', 'Show the error message and stack trace in the built-in fallback (default: true in development, false in production)'],
]} />

<H2 id="manual-error-capture" step={4}>Manual Error Capture</H2>

#### Using Hooks

```tsx
import { useAbrovaTrace } from '@abrova-trace/nextjs-sdk/react';

function MyComponent() {
  const { captureException, captureMessage, setUserId } = useAbrovaTrace();

  const handleClick = async () => {
    try {
      await riskyOperation();
    } catch (error) {
      captureException(error as Error, 'Failed to complete operation', {
        userId: user.id,
        action: 'button_click',
      });
    }
  };

  return <button onClick={handleClick}>Click me</button>;
}
```

#### Direct API Usage

```typescript
import { AbrovaTrace } from '@abrova-trace/nextjs-sdk';

// Capture exception
try {
  throw new Error('Something broke');
} catch (error) {
  AbrovaTrace.getInstance()?.captureException(error as Error, 'Custom context', {
    userId: '123',
    customData: 'value',
  });
}

// Capture a message (level: 'debug' | 'info' | 'warning' | 'error')
AbrovaTrace.getInstance()?.captureMessage(
  'User completed checkout',
  'info',
  { orderId: '456' }
);
```

<Callout kind="note" title="Where messages show up">
Messages appear in the Console under **Abrova Trace → Messages**, with their level, platform, extra data and breadcrumbs. They never create an issue. Levels: `'debug'`, `'info'` (default), `'warning'`, `'error'`. Use messages for things your app reports on purpose ("checkout started", "sync finished"); for high-volume diagnostics use Logs.
</Callout>

<H2 id="breadcrumbs" step={5}>Breadcrumbs</H2>

Breadcrumbs track user actions and provide context for errors. Navigation changes (once you use a navigation hook) and `console.error` / `console.warn` calls are recorded automatically.

#### Manual Breadcrumbs

```typescript
import { BreadcrumbService, BreadcrumbType } from '@abrova-trace/nextjs-sdk';

// Generic breadcrumb
BreadcrumbService.add('User action', BreadcrumbType.User, { button: 'submit' });

// Specific types
BreadcrumbService.addUser('Clicked checkout button');
BreadcrumbService.addHttp('POST', '/api/orders', 200);
BreadcrumbService.addState('Cart updated', { items: 3 });
BreadcrumbService.addNavigation('/cart', '/checkout');
```

#### Using Hooks

```tsx
import { useBreadcrumbs } from '@abrova-trace/nextjs-sdk/react';

function Component() {
  const { addBreadcrumb, addHttp, addState } = useBreadcrumbs();

  const handleSubmit = async (data) => {
    addBreadcrumb('Form submitted', { formName: 'contact' });

    const response = await fetch('/api/contact', {
      method: 'POST',
      body: JSON.stringify(data),
    });

    addHttp('POST', '/api/contact', response.status);
  };

  return <form onSubmit={handleSubmit}>...</form>;
}
```

<H2 id="crash-detection" step={6}>Crash Detection</H2>

The SDK detects browser tab crashes and unresponsiveness using a localStorage-based heartbeat system.

- **Tab Crashes** — Detects browser tab crashes
- **Unresponsive Tabs** — Detects frozen/hung tabs
- **Force-Close** — Detects force-close scenarios
- **Post-Mortem** — Reporting on next launch

#### How It Works

1. App starts — Crash marker created in localStorage
2. Heartbeat runs every 5 seconds
3. App closes normally — Marker removed
4. App crashes — Marker remains
5. Next session — Crash detected and reported

<H2 id="api-routes-server-components" step={7}>API Routes & Server Components</H2>

The `init()` call in `Providers` / `_app.tsx` runs in the browser only, so on the server `AbrovaTrace.getInstance()` returns `null` until you initialize the SDK there too. Create a small server helper (`init()` returns the existing instance if one is already set up):

```typescript
// lib/abrova-trace-server.ts
import { AbrovaTrace } from '@abrova-trace/nextjs-sdk';

export const trace =
  AbrovaTrace.getInstance() ??
  AbrovaTrace.init({
    apiKey: process.env.ABROVA_TRACE_API_KEY!,
    environment: process.env.NODE_ENV,
  });
```

#### API Routes

```typescript
// pages/api/example.ts
import type { NextApiRequest, NextApiResponse } from 'next';
import { trace } from '@/lib/abrova-trace-server';

export default async function handler(req: NextApiRequest, res: NextApiResponse) {
  try {
    // Your API logic
  } catch (error) {
    trace.captureException(error as Error, 'API Error', {
      endpoint: '/api/example',
      method: req.method,
    });
    res.status(500).json({ error: 'Internal Server Error' });
  }
}
```

#### Server Components (App Router)

```tsx
// app/page.tsx
import { trace } from '@/lib/abrova-trace-server';

export default async function Page() {
  try {
    const data = await fetchData();
    return <div>{data}</div>;
  } catch (error) {
    trace.captureException(error as Error, 'Server Component Error');
    return <div>Error loading data</div>;
  }
}
```

<H2 id="source-maps" step={8}>Source Maps</H2>

Enable production source maps for readable stack traces in your `next.config.js`:

```javascript
// next.config.js
module.exports = {
  productionBrowserSourceMaps: true,
};
```

After building your app, upload the `.map` files with the [Abrova Trace CLI](/docs/trace/upload-source-maps), using the same `release` you pass to `AbrovaTrace.init()`:

```bash
npx @abrova-trace/cli sourcemaps upload .next/static --release 1.0.0 --project YOUR_PROJECT_ID --token ab_pat_xxx
```

<H2 id="configuration-options" step={9}>Configuration Options</H2>

<CodeBlock language="typescript" code={`AbrovaTrace.init({
  apiKey: 'ab_live_your_api_key',           // Required
  environment: 'production',              // Default: 'production'
  release: '1.0.0',                       // Optional
  captureUncaughtErrors: true,            // Default: true
  enabled: true,                          // Default: true
  debug: false,                           // Default: false
  timeout: 10,                            // Default: 10 seconds
  enableServerSide: true,                 // Default: true
  enableClientSide: true,                 // Default: true
  enableCrashDetection: true,             // Default: true
  maxBreadcrumbs: 20,                     // Default: 20
  sampleRate: 1.0,                        // 0.0 to 1.0
  tags: { team: 'frontend' },            // Custom tags
  ignoreErrors: ['ResizeObserver loop limit exceeded'],
  ignoreUrls: [/chrome-extension:\\/\\//],   // matched against the stack trace
  beforeSend: (error) => error,           // Filter/modify errors
});`} />

<ConfigTable rows={[
  ['apiKey', 'string', 'Yes', 'Your project API Key'],
  ['environment', 'string', 'No', 'Environment name (default: "production")'],
  ['release', 'string', 'No', 'App version identifier'],
  ['captureUncaughtErrors', 'boolean', 'No', 'Catch uncaught errors automatically (default: true)'],
  ['enabled', 'boolean', 'No', 'Enable/disable SDK (default: true)'],
  ['debug', 'boolean', 'No', 'Enable debug logging (default: false)'],
  ['timeout', 'number', 'No', 'HTTP request timeout in seconds (default: 10)'],
  ['enableServerSide', 'boolean', 'No', 'Capture uncaught errors and unhandled rejections automatically on the server (default: true)'],
  ['enableClientSide', 'boolean', 'No', 'Capture uncaught errors and unhandled rejections automatically in the browser (default: true)'],
  ['enableCrashDetection', 'boolean', 'No', 'Enable crash detection (default: true)'],
  ['maxBreadcrumbs', 'number', 'No', 'Max breadcrumbs to keep (default: 20)'],
  ['sampleRate', 'number', 'No', 'Sample rate for errors and messages, 0.0-1.0 (default: 1.0)'],
  ['tags', 'object', 'No', 'Custom tags to attach to all errors'],
  ['ignoreErrors', 'array', 'No', 'Error messages to ignore (strings or RegExp)'],
  ['ignoreUrls', 'array', 'No', 'Strings or RegExp matched against the error stack trace; a match drops the error'],
  ['beforeSend', 'function', 'No', 'Hook to modify/filter errors before sending; return null or false to drop the error'],
  ['apiUrl', 'string', 'No', 'Base URL of the Trace API (default: "https://trace.abrova.ir"). Set it only for self-hosted'],
]} />

<H2 id="user-identification" step={10}>User Identification</H2>

```typescript
import { AbrovaTrace } from '@abrova-trace/nextjs-sdk';

// Set user ID after authentication
AbrovaTrace.getInstance()?.setUserId('user-123');

// Get user ID
const userId = AbrovaTrace.getInstance()?.getUserId();
```

<H2 id="navigation-tracking" step={11}>Navigation Tracking</H2>

#### App Router (Next.js 13+)

```tsx
'use client';

import { useAbrovaTraceNavigation } from '@abrova-trace/nextjs-sdk/react';

export function NavigationTracker() {
  useAbrovaTraceNavigation();
  return null;
}
```

#### Pages Router

```tsx
import { useAbrovaTracePagesRouter } from '@abrova-trace/nextjs-sdk/react';

function MyApp({ Component, pageProps }) {
  useAbrovaTracePagesRouter();
  return <Component {...pageProps} />;
}
```

#### Manual Tracking

```typescript
import { RouterIntegration } from '@abrova-trace/nextjs-sdk';

RouterIntegration.setCurrentRoute('/custom-route');
```

<H2 id="context-tags" step={12}>Context & Tags</H2>

Attach persistent metadata to every error and message. Tags are categorical filters; extras are richer per-event payloads. (Logs, spans and Web Vitals do not carry them.)

#### Global extras

```typescript
const sdk = AbrovaTrace.getInstance();

sdk?.setExtra('organizationId', 'org-123');
sdk?.setExtra('feature', 'checkout-v2');

sdk?.setExtras({
  organizationId: 'org-123',
  feature: 'checkout-v2',
  experiment: 'new-flow',
});

const orgId = sdk?.getExtra('organizationId');
const allExtras = sdk?.getExtras();

sdk?.clearExtras();
```

#### Tags

```typescript
const sdk = AbrovaTrace.getInstance();

sdk?.setTag('team', 'payments');
sdk?.setTag('region', 'us-east');

sdk?.setTags({ team: 'payments', version: '2.1' });

const team = sdk?.getTag('team');
const allTags = sdk?.getTags();

sdk?.clearTags();
```

#### Session ID

A unique session ID is auto-generated when the SDK initializes (16 random hex bytes) and attached to every error and message for session grouping in Abrova Console:

```typescript
const sessionId = AbrovaTrace.getInstance()?.getSessionId();
```

<H2 id="web-vitals" step={13}>Web Vitals</H2>

Track Core Web Vitals using Google's official `web-vitals` library (browser only). Metrics show up in Abrova Console under **Abrova Trace → Performance** alongside HTTP spans.

```typescript
const sdk = AbrovaTrace.getInstance();

sdk?.enableWebVitals({
  reportAllChanges: false, // Only report final values (default)
  batchInterval: 5000,     // Send 5 s after the last metric (default); also sent when the page is hidden
});
```

**Tracked metrics:**

<ConfigTable rows={[
  ['LCP', '-', '-', 'Largest Contentful Paint'],
  ['CLS', '-', '-', 'Cumulative Layout Shift'],
  ['INP', '-', '-', 'Interaction to Next Paint'],
  ['TTFB', '-', '-', 'Time to First Byte'],
  ['FCP', '-', '-', 'First Contentful Paint'],
]} />

Web Vitals events automatically include device type (mobile/tablet/desktop), connection type, page URL, and route information.

<H2 id="typescript" step={14}>TypeScript</H2>

The SDK is written in TypeScript and ships with full type definitions. Import the types when you need explicit annotations on config objects or event payloads:

```typescript
import type {
  AbrovaTraceConfig,
  AbrovaTraceError,
  Breadcrumb,
} from '@abrova-trace/nextjs-sdk';

import type {
  PerformanceSpan,
  WebVitalsData,
  LogEntry,
  LogLevel,
  LogServiceConfig,
} from '@abrova-trace/nextjs-sdk';
```

<H2 id="logging" step={15}>Logging</H2>

Structured server-side logging that works in App Router, Pages Router, and API Routes. Logging uses a dedicated `LogService` instance — create one in `lib/logger.ts` and import it from anywhere:

```typescript
import { LogService } from '@abrova-trace/nextjs-sdk';

export const logger = new LogService({
  apiKey: process.env.ABROVA_TRACE_API_KEY!,
  sourceId: 'nextjs-app',
  platform: 'nextjs',
  environment: process.env.NODE_ENV,
});

logger.log('Users fetched', 'info', { count: 42 });
```

You can also log through the SDK instance, which reuses the `init()` config: `AbrovaTrace.getInstance()?.info('Users fetched', { count: 42 })` (see the Logging table in the API Reference below). Logs are separate from `captureMessage()`: they are batched and appear under **Abrova Trace → Logs**.

See [Next.js SDK Logging](/docs/trace/nextjs-logging) for the full pipeline — App Router, Pages Router, API Routes, log levels, and request middleware.

### API Reference

#### `AbrovaTrace` — Initialization & lifecycle

<ConfigTable rows={[
  ['init(config)', '-', '-', 'Initialize SDK'],
  ['getInstance()', '-', '-', 'Get the singleton SDK instance'],
  ['close()', '-', '-', 'Cleanup SDK, flush pending data'],
]} />

#### Error capture

<ConfigTable rows={[
  ['captureException(error, message?, extra?, level?, callback?)', '-', '-', 'Capture an error / exception'],
  ['captureMessage(message, level?, extra?, callback?)', '-', '-', 'Send a message to Abrova Trace → Messages (not an issue)'],
]} />

#### User & session

<ConfigTable rows={[
  ['setUserId(userId)', '-', '-', 'Set the current user identifier'],
  ['getUserId()', '-', '-', 'Get the current user identifier'],
  ['getSessionId()', '-', '-', 'Get the auto-generated session ID'],
]} />

#### Global context (extras)

<ConfigTable rows={[
  ['setExtra(key, value)', '-', '-', 'Set a single extra'],
  ['setExtras(extras)', '-', '-', 'Set multiple extras at once'],
  ['getExtra(key)', '-', '-', 'Get a single extra value'],
  ['getExtras()', '-', '-', 'Get all extras'],
  ['clearExtras()', '-', '-', 'Clear all extras'],
]} />

#### Tags

<ConfigTable rows={[
  ['setTag(key, value)', '-', '-', 'Set a single tag'],
  ['setTags(tags)', '-', '-', 'Set multiple tags at once'],
  ['getTag(key)', '-', '-', 'Get a single tag value'],
  ['getTags()', '-', '-', 'Get all tags'],
  ['clearTags()', '-', '-', 'Clear all tags'],
]} />

#### Performance monitoring

<ConfigTable rows={[
  ['enablePerformanceTracking(options?)', '-', '-', 'Turn on performance reporting; in the browser this also tracks every fetch call. Options: batchSize (default: 5), flushInterval in ms (default: 5000)'],
  ['enableWebVitals(options?)', '-', '-', 'Turn on Web Vitals tracking'],
  ['reportPerformanceSpan(span)', '-', '-', 'Report a single span'],
  ['reportPerformanceSpanBatch(spans)', '-', '-', 'Report multiple spans at once'],
  ['trackOperation(operation, fn, options?)', '-', '-', 'Time and report an async operation'],
  ['createPerformanceFetch()', '-', '-', 'Build a fetch wrapper that reports a span per request. It reports only after enablePerformanceTracking(), trackOperation() or reportPerformanceSpan() has been called'],
  ['flushPerformance()', '-', '-', 'Flush buffered performance data immediately'],
]} />

#### Logging

<ConfigTable rows={[
  ['enableLogging(options?)', '-', '-', 'Turn on the log pipeline'],
  ['log(message, level?, metadata?)', '-', '-', 'Log at an explicit level'],
  ['trace(message, metadata?)', '-', '-', 'Log at trace level'],
  ['logDebug(message, metadata?)', '-', '-', 'Log at debug level'],
  ['info(message, metadata?)', '-', '-', 'Log at info level'],
  ['warn(message, metadata?)', '-', '-', 'Log at warn level'],
  ['logError(message, metadata?)', '-', '-', 'Log at error level'],
  ['fatal(message, metadata?)', '-', '-', 'Log at fatal level'],
  ['flushLogs()', '-', '-', 'Flush buffered logs immediately'],
  ['pendingLogCount', '-', '-', 'Number of logs still in the buffer'],
]} />

#### `BreadcrumbService`

<ConfigTable rows={[
  ['add(message, type, data?, level?)', '-', '-', 'Add a generic breadcrumb'],
  ['addNavigation(from, to, data?)', '-', '-', 'Add a navigation breadcrumb'],
  ['addUser(action, data?)', '-', '-', 'Add a user-action breadcrumb'],
  ['addHttp(method, url, status?, data?)', '-', '-', 'Add an HTTP breadcrumb'],
  ['addState(message, data?)', '-', '-', 'Add a state-change breadcrumb'],
  ['getAll()', '-', '-', 'Get all breadcrumbs'],
  ['clear()', '-', '-', 'Clear all breadcrumbs'],
]} />

#### `RouterIntegration`

<ConfigTable rows={[
  ['trackAppRouterNavigation(pathname, searchParams?)', '-', '-', 'Track App Router navigation manually'],
  ['initializePagesRouter(router)', '-', '-', 'Initialize Pages Router tracking'],
  ['setCurrentRoute(route)', '-', '-', 'Override the current route'],
  ['getCurrentRoute()', '-', '-', 'Get the current route'],
  ['getNavigationContext()', '-', '-', 'Get the active navigation context'],
]} />

#### `CrashDetector`

<ConfigTable rows={[
  ['enable()', '-', '-', 'Turn on crash detection'],
  ['disable()', '-', '-', 'Turn off crash detection'],
  ['didCrashLastSession()', '-', '-', 'True if the previous session ended in a crash'],
  ['getCrashReport()', '-', '-', 'Get details of the previous crash'],
]} />

#### React hooks

<ConfigTable rows={[
  ['useAbrovaTrace()', '-', '-', 'Returns { captureException, captureMessage, setUserId, setExtra, setExtras, setTag, setTags }'],
  ['useAbrovaTraceNavigation()', '-', '-', 'Track App Router navigation automatically'],
  ['useAbrovaTracePagesRouter()', '-', '-', 'Track Pages Router navigation automatically'],
  ['useBreadcrumbs()', '-', '-', 'Returns { addBreadcrumb, addNavigation, addHttp, addState }'],
]} />

#### React components

<ConfigTable rows={[
  ['ErrorBoundary', '-', '-', 'React error boundary with automatic error reporting (alias: AbrovaTraceErrorBoundary)'],
]} />

### Best Practices

<BestPracticeList items={[
  ['Initialize Early', 'Initialize AbrovaTrace as early as possible in your app lifecycle to catch all errors'],
  ['Set User ID', 'Set user ID after authentication to associate errors with users'],
  ['Use Error Boundaries', 'Wrap major sections of your app with error boundaries for automatic React error capture'],
  ['Add Context to Errors', 'Include user IDs, amounts, and relevant data when capturing errors'],
  ['Use Breadcrumbs', 'Add breadcrumbs for important user actions to provide error context'],
  ['Environment-Specific Config', 'Use different configs for production vs development (debug mode, sample rate)'],
  ['Cleanup on Unmount', 'Call AbrovaTrace.getInstance()?.close() when cleaning up for proper crash detection'],
]} />

- Android SDK: https://abrova.ir/en/docs/trace/android-sdk

<BestPracticeList columns={2} items={[
  ['Native Kotlin SDK', 'Built with Kotlin, supports API 19+ (Android 4.4+)'],
  ['Automatic Crash Detection', 'Catches uncaught exceptions, plus native crashes on Android 11+'],
  ['ANR Detection', 'Detects Application Not Responding issues'],
  ['Breadcrumbs & Navigation', 'Track user journey before errors'],
  ['OkHttp Interceptor', 'Automatic HTTP request tracking'],
  ['Performance Monitoring', 'Track API latency with OkHttp interceptors'],
  ['Rich Device Context', 'Automatic device, OS, and app info collection'],
]} />

<H2 id="installation" step={1}>Installation</H2>

The SDK comes from Abrova Center. Two steps:

**1. Add the Abrova repository** in `settings.gradle.kts` (or `settings.gradle`):

```kotlin
dependencyResolutionManagement {
    repositories {
        google()
        mavenCentral()
        maven { url = uri("https://center.abrova.ir/api/packages/abrova/maven") }
    }
}
```

Groovy: `maven { url "https://center.abrova.ir/api/packages/abrova/maven" }`

**2. Add the dependency** to your app's `build.gradle.kts`:

```kotlin
dependencies {
    implementation("ir.abrova.trace:abrova-trace-android-sdk:0.2.3")
}
```

Then sync your project with Gradle files. Requirements: Android 4.4 (API 19) or later; native crash reports need Android 11 (API 30) or later.

<H2 id="quick-start" step={2}>Quick Start</H2>

Initialize AbrovaTrace in your `Application` class:

```kotlin
import android.app.Application
import ir.abrova.trace.sdk.AbrovaTrace
import ir.abrova.trace.sdk.AbrovaTraceConfig

class MyApp : Application() {

    override fun onCreate() {
        super.onCreate()

        val config = AbrovaTraceConfig.Builder("ab_live_YOUR_API_KEY")
            .environment(if (BuildConfig.DEBUG) "development" else "production")
            .release(BuildConfig.VERSION_NAME)
            .debug(BuildConfig.DEBUG)
            .captureUncaughtExceptions(true)
            .captureSignalCrashes(true)
            .captureAnr(true)
            .anrTimeoutMs(5000L)
            .build()

        AbrovaTrace.init(this, config)
    }

    override fun onTerminate() {
        AbrovaTrace.close()
        super.onTerminate()
    }
}
```

<Callout kind="note" title="Graceful Shutdown">
  `onTerminate()` is never called on real devices, so also call close() in your main Activity. close() flushes buffered logs, stops the ANR watchdog and shuts down the network client. The API key must start with `ab_live_` — the config throws otherwise.
</Callout>

```kotlin
class MainActivity : AppCompatActivity() {
    override fun onDestroy() {
        if (isFinishing) {
            AbrovaTrace.close()  // Flush logs, stop the ANR watchdog
        }
        super.onDestroy()
    }
}
```

<H2 id="capture-errors" step={3}>Capture Errors</H2>

#### Capture Exceptions

```kotlin
try {
    someRiskyOperation()
} catch (e: Exception) {
    AbrovaTrace.captureException(e)
}
```

#### Capture with Extra Context

```kotlin
AbrovaTrace.captureException(
    throwable = exception,
    message = "Failed to load user profile",
    extra = mapOf("user_id" to userId, "screen" to "ProfileActivity"),
    tags = mapOf("feature" to "user_profile")
)
```

#### Capture Messages

```kotlin
import ir.abrova.trace.sdk.models.MessageLevel

// Info message
AbrovaTrace.captureMessage("User completed onboarding", MessageLevel.INFO)

// Warning message
AbrovaTrace.captureMessage("API rate limit approaching", MessageLevel.WARNING)

// Error message with extra data
AbrovaTrace.captureMessage(
    message = "Payment failed",
    level = MessageLevel.ERROR,
    extra = mapOf("amount" to 99.99)
)
```

<Callout kind="note" title="Where messages show up">
Messages appear in the Console under **Abrova Trace → Messages**, with their level, platform, extra data and breadcrumbs. They never create an issue. Levels: `MessageLevel.DEBUG`, `INFO` (default), `WARNING`, `ERROR`. `FATAL` is accepted and stored as `error`. Use messages for things your app reports on purpose ("checkout started", "sync finished"); for high-volume diagnostics use Logs.
</Callout>

<H2 id="breadcrumbs" step={4}>Breadcrumbs</H2>

Breadcrumbs help you understand what happened before an error occurred. They are automatically added for Activity navigation, app foreground/background, and system events.

```kotlin
import ir.abrova.trace.sdk.models.BreadcrumbType

// User action
AbrovaTrace.addUserBreadcrumb("Added item to cart", mapOf("product_id" to "abc"))

// Navigation
AbrovaTrace.addNavigationBreadcrumb(from = "MainActivity", to = "ProductDetailActivity")

// HTTP request
AbrovaTrace.addHttpBreadcrumb(
    method = "POST",
    url = "https://api.example.com/orders",
    statusCode = 201,
    duration = 342L
)

// Custom breadcrumb
AbrovaTrace.addBreadcrumb("Order placed", BreadcrumbType.INFO, mapOf(
    "order_id" to "12345",
    "total" to 99.99
))
```

<H2 id="okhttp-integration" step={5}>OkHttp Integration</H2>

Automatically track HTTP requests as breadcrumbs and capture HTTP errors:

#### Basic Setup

```kotlin
import ir.abrova.trace.sdk.network.AbrovaTraceInterceptor
import okhttp3.OkHttpClient

val client = OkHttpClient.Builder()
    .addInterceptor(AbrovaTraceInterceptor())
    .build()
```

#### With Error Capturing

```kotlin
import ir.abrova.trace.sdk.network.AbrovaTraceInterceptor
import ir.abrova.trace.sdk.network.AbrovaTraceErrorInterceptor
import okhttp3.OkHttpClient

val client = OkHttpClient.Builder()
    .addInterceptor(AbrovaTraceInterceptor())       // Adds breadcrumbs
    .addInterceptor(AbrovaTraceErrorInterceptor())  // Captures HTTP errors
    .build()
```

`AbrovaTraceErrorInterceptor` sends each 5xx response as a **message** at `error` level (Abrova Trace → Messages). 4xx responses are off by default — turn them on with `AbrovaTraceErrorInterceptor(captureClientErrors = true)` (sent at `warning`). Network failures (no response) are captured as exceptions.

<H2 id="crash-detection" step={6}>Crash Detection</H2>

AbrovaTrace detects crashes in-process and, on Android 11+, from the system's own exit records.

- **Java/Kotlin Exceptions** — Captured in real-time by an uncaught exception handler (`captureUncaughtExceptions`). The report is sent before the app closes, on any thread including the main thread; if the server does not accept it within 2 seconds it is kept on the device and sent on the next launch. Requires version 0.2.2 or newer.
- **ANR Events** — A watchdog thread detects the main thread being blocked longer than `anrTimeoutMs` (`captureAnr`)
- **Native Crashes** — SIGSEGV, SIGABRT, etc., reported on the next launch (Android 11 / API 30+ only, `captureSignalCrashes`)

#### How It Works

1. On each launch (API 30+), AbrovaTrace reads Android's `ApplicationExitInfo` records for your app
2. Exits since the last launch with reason JVM crash, native crash or ANR are converted into crash reports, including the tombstone for native crashes
3. The timestamp of the last sent record is saved, so each crash is reported once; a failed send is retried on the next launch. A Java/Kotlin crash the in-process handler already reported is skipped here
4. On Android 10 and below this step does nothing — JVM crashes are still captured by the in-process handler

<H2 id="performance-monitoring-apm" step={7}>Performance Monitoring (APM)</H2>

Track API latency and HTTP request performance automatically.

#### Automatic HTTP Performance Tracking with OkHttp

```kotlin
import ir.abrova.trace.sdk.network.AbrovaTraceInterceptor
import ir.abrova.trace.sdk.network.AbrovaTracePerformanceInterceptor
import okhttp3.OkHttpClient
import okhttp3.Request

val client = OkHttpClient.Builder()
    .addInterceptor(AbrovaTraceInterceptor())              // Breadcrumbs
    .addInterceptor(AbrovaTracePerformanceInterceptor())   // APM tracking
    .build()

// All API calls are automatically tracked!
val request = Request.Builder()
    .url("https://api.example.com/users")
    .build()

client.newCall(request).execute().use { response ->
    // Duration, status code, and errors are automatically reported
    val users = response.body?.string()
}
```

#### Using with Retrofit

```kotlin
import ir.abrova.trace.sdk.network.AbrovaTraceInterceptor
import ir.abrova.trace.sdk.network.AbrovaTracePerformanceInterceptor
import okhttp3.OkHttpClient
import retrofit2.Retrofit
import retrofit2.converter.gson.GsonConverterFactory

val okHttpClient = OkHttpClient.Builder()
    .addInterceptor(AbrovaTraceInterceptor())
    .addInterceptor(AbrovaTracePerformanceInterceptor())
    .build()

val retrofit = Retrofit.Builder()
    .baseUrl("https://api.example.com/")
    .client(okHttpClient)
    .addConverterFactory(GsonConverterFactory.create())
    .build()

val api = retrofit.create(MyApiService::class.java)
// All API calls through this Retrofit instance are automatically tracked
```

#### Track Custom Operations

```kotlin
import ir.abrova.trace.sdk.AbrovaTrace

val result = AbrovaTrace.trackOperation("load_user_profile") {
    val user = fetchUserFromApi()
    cacheUserLocally(user)
    user
}
```

#### Manual Span Reporting

```kotlin
import ir.abrova.trace.sdk.models.PerformanceSpan

// HTTP request span
AbrovaTrace.reportPerformanceSpan(
    PerformanceSpan.fromHttpRequest(
        method = "GET",
        url = "https://api.example.com/products",
        statusCode = 200,
        durationMs = 245L,
        startTime = System.currentTimeMillis() - 245
    )
)

// Database query span
AbrovaTrace.reportPerformanceSpan(
    PerformanceSpan.forDbQuery(
        queryType = "SELECT",
        tableName = "products",
        durationMs = 15L,
        startTime = System.currentTimeMillis() - 15,
        rowsAffected = 50
    )
)

// Custom operation span
AbrovaTrace.reportPerformanceSpan(
    PerformanceSpan.custom(
        operation = "image_processing",
        durationMs = 1250L,
        startTime = System.currentTimeMillis() - 1250,
        tags = mapOf("format" to "png")
    )
)
```

<H2 id="logging" step={8}>Logging</H2>

Structured log ingestion with automatic batching and retry. Enable it once, then use the level helpers from anywhere in your app:

```kotlin
// Enable logging after AbrovaTrace.init()
AbrovaTrace.enableLogging(sourceId = "my-android-app")

AbrovaTrace.info("User login successful", mapOf("user_id" to "user_123"))
```

See [Android SDK Logging](/docs/trace/android-logging) for the full pipeline — batching, log levels, lifecycle handling, manual flush, and configuration.

<H2 id="configuration-options" step={9}>Configuration Options</H2>

```kotlin
val config = AbrovaTraceConfig.Builder("ab_live_YOUR_API_KEY")
    .environment("production")        // Environment name
    .release("1.0.0")                 // App version
    .debug(false)                     // Enable debug logging
    .enabled(true)                    // Enable/disable SDK
    .sampleRate(1.0f)                 // Error sample rate (0.0 - 1.0)
    .maxBreadcrumbs(20)               // Max breadcrumbs to keep
    .httpTimeout(30)                  // HTTP request timeout (seconds)
    .enableOfflineStorage(true)       // Keep unsent errors on the device while offline
    .captureUncaughtExceptions(true)  // Catch uncaught exceptions
    .captureSignalCrashes(true)       // Detect native signal crashes
    .captureAnr(true)                 // Detect ANR issues
    .anrTimeoutMs(5000L)              // ANR detection timeout
    .apiUrl("https://trace.abrova.ir") // Server URL (self-hosted override)
    .build()
```

<ConfigTable rows={[
  ['apiKey', 'String', 'Yes', 'Your project API Key (must start with ab_live_)'],
  ['environment', 'String', 'No', 'Environment name (default: "production")'],
  ['release', 'String', 'No', 'App version identifier'],
  ['debug', 'Boolean', 'No', 'Enable debug logging (default: false)'],
  ['enabled', 'Boolean', 'No', 'Enable/disable SDK (default: true)'],
  ['sampleRate', 'Float', 'No', 'Sample rate 0.0-1.0 for captureException (default: 1.0)'],
  ['maxBreadcrumbs', 'Int', 'No', 'Max breadcrumbs to keep (default: 20)'],
  ['httpTimeout', 'Int', 'No', 'HTTP request timeout in seconds (default: 30)'],
  ['enableOfflineStorage', 'Boolean', 'No', 'Keep errors that could not be sent while the device is offline (up to 100) and send them later (default: true)'],
  ['captureUncaughtExceptions', 'Boolean', 'No', 'Catch uncaught exceptions (default: true)'],
  ['captureSignalCrashes', 'Boolean', 'No', 'Report native crashes, and other crashes and ANRs recorded by the system, on next launch, API 30+ (default: true)'],
  ['captureAnr', 'Boolean', 'No', 'Detect ANR events (default: true)'],
  ['anrTimeoutMs', 'Long', 'No', 'ANR detection timeout in ms (default: 5000)'],
  ['apiUrl', 'String', 'No', 'Trace server URL (default: "https://trace.abrova.ir")'],
]} />

<Callout kind="note" title="Offline storage">
When an error cannot be sent because the device has no connection, the SDK keeps it in the app's private storage and sends it later: on the next launch, and as soon as another error is sent successfully. Up to 100 errors are kept; when the limit is reached, the oldest are dropped. This covers errors only — `captureException`, uncaught exceptions and ANR reports. Messages, logs and performance data are not stored. Set `enableOfflineStorage(false)` to keep nothing on the device.
</Callout>

<H2 id="proguard-r8" step={10}>ProGuard / R8</H2>

The SDK includes ProGuard rules automatically. If you need custom rules, add to `proguard-rules.pro`:

```text
-keep class ir.abrova.trace.sdk.** { *; }
-keepattributes SourceFile,LineNumberTable
-keepattributes *Annotation*
```

<H2 id="device-compatibility" step={11}>Device Compatibility</H2>

- **Android 4.4 KitKat** — API 19
- **Android 5.0 Lollipop** — API 21
- **Android 8.0 Oreo** — API 26
- **Android 10** — API 29
- **Android 12** — API 31
- **Android 14** — API 34

<H2 id="context-tags" step={12}>Context & Tags</H2>

Attach persistent metadata to every error and message captured by the SDK (tags are also added to performance spans). Useful for filtering by team, region, feature flag, or experiment cohort in the Abrova Console. ANR reports and crash reports read from the system on the next launch do not carry them.

#### Global extras

Extras are arbitrary key/value pairs (string keys, any serializable value) automatically merged into every event:

```kotlin
// Set individual extras
AbrovaTrace.setExtra("organizationId", "org-123")
AbrovaTrace.setExtra("feature", "checkout-v2")

// Set multiple at once
AbrovaTrace.setExtras(mapOf(
    "organizationId" to "org-123",
    "feature" to "checkout-v2",
    "experiment" to "new-flow"
))

// Clear when no longer needed (e.g. on logout)
AbrovaTrace.clearExtras()
```

#### Tags

Tags are string-only key/value pairs that are attached to every error and message:

```kotlin
AbrovaTrace.setTag("team", "payments")
AbrovaTrace.setTag("region", "us-east")

AbrovaTrace.setTags(mapOf("team" to "payments", "version" to "2.1"))

AbrovaTrace.clearTags()
```

<Callout kind="note" title="Tags vs Extras">
Use **tags** for low-cardinality categorical filters (team, region, build flavor). Use **extras** for richer per-event context (user IDs, request bodies, computed values).
</Callout>

### API Reference

Full method surface of `AbrovaTrace` and `PerformanceSpan`. Method signatures use the Kotlin convention; optional parameters are marked with `?`.

#### `AbrovaTrace` — Initialization & Lifecycle

<ConfigTable rows={[
  ['init(context, config)', '-', '-', 'Initialize SDK with a full AbrovaTraceConfig'],
  ['init(context, apiKey)', '-', '-', 'Initialize SDK with just an API key (uses defaults)'],
  ['isInitialized()', '-', '-', 'Returns true if the SDK is initialized'],
  ['close()', '-', '-', 'Flush logs, stop the ANR watchdog and shut down the network client'],
]} />

#### Error capture

<ConfigTable rows={[
  ['captureException(throwable, message?, extra?, tags?, callback?)', '-', '-', 'Capture an exception with optional metadata'],
  ['captureMessage(message, level?, extra?, tags?, callback?)', '-', '-', 'Send a message to Abrova Trace → Messages at a given level (not an issue)'],
]} />

#### User & session

<ConfigTable rows={[
  ['setUserId(id)', '-', '-', 'Set the current user identifier'],
  ['getUserId()', '-', '-', 'Get the current user identifier'],
]} />

#### Global context (extras)

<ConfigTable rows={[
  ['setExtra(key, value)', '-', '-', 'Set a single extra'],
  ['setExtras(extras)', '-', '-', 'Set multiple extras at once'],
  ['clearExtras()', '-', '-', 'Clear all extras'],
]} />

#### Tags

<ConfigTable rows={[
  ['setTag(key, value)', '-', '-', 'Set a single tag'],
  ['setTags(tags)', '-', '-', 'Set multiple tags at once'],
  ['clearTags()', '-', '-', 'Clear all tags'],
]} />

#### Breadcrumbs

<ConfigTable rows={[
  ['addBreadcrumb(message, type?, data?)', '-', '-', 'Add a generic breadcrumb'],
  ['addNavigationBreadcrumb(from, to)', '-', '-', 'Add a navigation breadcrumb'],
  ['addUserBreadcrumb(action, data?)', '-', '-', 'Add a user-action breadcrumb'],
  ['addHttpBreadcrumb(method, url, statusCode?, duration?)', '-', '-', 'Add an HTTP breadcrumb'],
  ['clearBreadcrumbs()', '-', '-', 'Clear all breadcrumbs'],
]} />

#### Performance monitoring

<ConfigTable rows={[
  ['reportPerformanceSpan(method, url, statusCode, durationMs, startTime, errorMessage?, tags?)', '-', '-', 'Report a single HTTP span'],
  ['reportPerformanceSpan(span, callback?)', '-', '-', 'Report a constructed PerformanceSpan'],
  ['reportPerformanceSpanBatch(spans, callback?)', '-', '-', 'Report multiple spans at once'],
  ['trackOperation(operation, operationType?, tags?, block)', '-', '-', 'Time a block and report it as a span'],
  ['performanceInterceptor(minDurationMs?)', '-', '-', 'Build an OkHttp interceptor for HTTP timings'],
]} />

#### Logging

<ConfigTable rows={[
  ['enableLogging(sourceId?, sourceName?, batchSize?, flushIntervalMs?)', '-', '-', 'Turn on the log pipeline'],
  ['log(message, level?, metadata?)', '-', '-', 'Log at an explicit level'],
  ['trace(message, metadata?)', '-', '-', 'Log at trace level'],
  ['logDebug(message, metadata?)', '-', '-', 'Log at debug level'],
  ['info(message, metadata?)', '-', '-', 'Log at info level'],
  ['warn(message, metadata?)', '-', '-', 'Log at warn level'],
  ['logError(message, metadata?)', '-', '-', 'Log at error level'],
  ['fatal(message, metadata?)', '-', '-', 'Log at fatal level'],
  ['flushLogs(callback?)', '-', '-', 'Flush buffered logs immediately'],
  ['getPendingLogCount()', '-', '-', 'Number of logs still in the buffer'],
]} />

#### `PerformanceSpan` factories

<ConfigTable rows={[
  ['PerformanceSpan.fromHttpRequest(...)', '-', '-', 'Construct a span from an HTTP request/response'],
  ['PerformanceSpan.forDbQuery(...)', '-', '-', 'Construct a span for a database query'],
  ['PerformanceSpan.custom(...)', '-', '-', 'Construct a fully custom span'],
  ['PerformanceSpan.generateTraceId()', '-', '-', 'Generate a random trace ID'],
  ['PerformanceSpan.generateSpanId()', '-', '-', 'Generate a random span ID'],
]} />

### Complete Example

```kotlin
import android.app.Application
import android.os.Bundle
import androidx.appcompat.app.AppCompatActivity
import ir.abrova.trace.sdk.AbrovaTrace
import ir.abrova.trace.sdk.AbrovaTraceConfig
import ir.abrova.trace.sdk.models.MessageLevel
import ir.abrova.trace.sdk.network.AbrovaTraceInterceptor
import okhttp3.OkHttpClient

class MyApp : Application() {
    override fun onCreate() {
        super.onCreate()

        val config = AbrovaTraceConfig.Builder("ab_live_YOUR_API_KEY")
            .environment(if (BuildConfig.DEBUG) "development" else "production")
            .release(BuildConfig.VERSION_NAME)
            .debug(BuildConfig.DEBUG)
            .captureUncaughtExceptions(true)
            .captureSignalCrashes(true)
            .captureAnr(true)
            .anrTimeoutMs(5000L)
            .maxBreadcrumbs(20)
            .enableOfflineStorage(true)
            .build()

        AbrovaTrace.init(this, config)
    }

    override fun onTerminate() {
        AbrovaTrace.close()
        super.onTerminate()
    }
}

class MainActivity : AppCompatActivity() {

    private val httpClient = OkHttpClient.Builder()
        .addInterceptor(AbrovaTraceInterceptor())
        .build()

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        AbrovaTrace.setUserId("user_123")
        AbrovaTrace.addUserBreadcrumb("Viewed home screen")
    }

    private fun handlePurchase() {
        try {
            processPurchase()
            AbrovaTrace.captureMessage(
                message = "Purchase successful",
                level = MessageLevel.INFO,
                extra = mapOf("amount" to 99.99)
            )
        } catch (e: Exception) {
            AbrovaTrace.captureException(
                throwable = e,
                message = "Purchase failed",
                extra = mapOf("user_id" to "user_123", "screen" to "MainActivity")
            )
        }
    }

    override fun onDestroy() {
        if (isFinishing) {
            AbrovaTrace.close()
        }
        super.onDestroy()
    }

    private fun processPurchase() { /* ... */ }
}
```

### Best Practices

<BestPracticeList items={[
  ['Initialize in Application Class', 'Initialize AbrovaTrace in your Application class onCreate() to catch all errors from app start'],
  ['Call close() on App Exit', 'Flushes buffered logs and stops the ANR watchdog'],
  ['Add Context to Errors', 'Include user IDs, screen names, and relevant data in the extra parameter'],
  ['Use Different Environments', 'Separate production, staging, and development errors using the environment config'],
  ['Enable Debug Mode in Development', 'Set debug(true) during development to see SDK logs and verify integration'],
  ['Use OkHttp Interceptors', 'Add AbrovaTraceInterceptor for HTTP breadcrumbs and AbrovaTraceErrorInterceptor for HTTP error reporting'],
  ['Enable Logging Early', 'Call enableLogging() right after init() to capture all application events'],
]} />

- iOS SDK: https://abrova.ir/en/docs/trace/ios-sdk

<BestPracticeList columns={2} items={[
  ['Native Swift SDK', 'Built with Swift, supports iOS 12+, macOS 10.14+, tvOS 12+ (tvOS via Swift Package Manager only)'],
  ['Automatic Crash Detection', 'Catches uncaught exceptions, plus native signal crashes (SIGSEGV, SIGABRT, etc.) and Mach exceptions via PLCrashReporter'],
  ['ANR Detection', 'Detect Application Not Responding events (main thread blocked)'],
  ['Breadcrumbs & Navigation', 'Track user journey before errors'],
  ['HTTP Tracking', 'Automatic HTTP performance spans and breadcrumbs'],
  ['Custom Messages', 'Send debug, info, warning, and error messages'],
  ['Performance Monitoring', 'Track API latency with URLSession and Alamofire'],
  ['Rich Device Context', 'Automatic device, OS, and app info collection'],
]} />

<H2 id="installation" step={1}>Installation</H2>

#### Swift Package Manager (Recommended)

In Xcode: **File → Add Packages** → enter the Abrova Center address:

```text
https://center.abrova.ir/abrova/abrova-trace-ios-sdk.git
```

Select version `0.2.4` or later.

Or add to your `Package.swift`:

```swift
dependencies: [
    .package(url: "https://center.abrova.ir/abrova/abrova-trace-ios-sdk.git", from: "0.2.4")
]
```

#### CocoaPods

Add to your `Podfile`:

```ruby
pod 'AbrovaTrace', :git => 'https://center.abrova.ir/abrova/abrova-trace-ios-sdk.git', :tag => '0.2.4'
```

Then run:

```bash
pod install
```

<Callout kind="note" title="Abrova Center and GitHub">
Releases are installed from Abrova Center, which works inside Iran. The source code is on GitHub ([Abrova-co/abrova-trace-ios-sdk](https://github.com/Abrova-co/abrova-trace-ios-sdk)) with the same version tags, so `https://github.com/Abrova-co/abrova-trace-ios-sdk.git` also works where GitHub is reachable.
</Callout>

<H2 id="quick-start" step={2}>Quick Start</H2>

#### UIKit Initialization

Initialize AbrovaTrace in your `AppDelegate`:

```swift
import UIKit
import AbrovaTrace

@main
class AppDelegate: UIResponder, UIApplicationDelegate {

    func application(_ application: UIApplication,
                     didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {

        let config = AbrovaTraceConfigBuilder(apiKey: "ab_live_YOUR_API_KEY")
            .environment("production")
            .release(Bundle.main.infoDictionary?["CFBundleShortVersionString"] as? String)
            .debug(false)
            .captureUncaughtExceptions(true)
            .captureSignalCrashes(true)
            .captureAnr(true)
            .anrTimeoutMs(5000)
            .build()

        AbrovaTrace.shared.initialize(config: config)

        return true
    }

    func applicationWillTerminate(_ application: UIApplication) {
        AbrovaTrace.shared.close()  // Optional: the SDK also does this on terminate
    }
}
```

#### SwiftUI Initialization

```swift
import SwiftUI
import AbrovaTrace

@main
struct MyApp: App {
    init() {
        let config = AbrovaTraceConfigBuilder(apiKey: "ab_live_YOUR_API_KEY")
            .environment("production")
            .release(Bundle.main.infoDictionary?["CFBundleShortVersionString"] as? String)
            .debug(false)
            .captureUncaughtExceptions(true)
            .captureSignalCrashes(true)
            .build()

        AbrovaTrace.shared.initialize(config: config)
    }

    var body: some Scene {
        WindowGroup {
            ContentView()
        }
    }
}
```

<H2 id="capture-errors" step={3}>Capture Errors</H2>

#### Capture Swift Errors

```swift
do {
    try riskyOperation()
} catch {
    AbrovaTrace.shared.captureError(error)
}
```

Use `captureError(_:)` for Swift `Error` values and `captureException(_:)` for an `NSException`.

#### Capture with Context

```swift
AbrovaTrace.shared.captureError(
    error,
    message: "Failed to load user profile",
    extra: ["user_id": userId, "screen": "ProfileView"],
    tags: ["feature": "user_profile"]
)
```

#### Capture Messages

```swift
// Info message
AbrovaTrace.shared.captureMessage("User completed onboarding", level: .info)

// Warning message
AbrovaTrace.shared.captureMessage("API rate limit approaching", level: .warning)

// Error message with extra data
AbrovaTrace.shared.captureMessage(
    "Payment failed",
    level: .error,
    extra: ["amount": 99.99]
)
```

<Callout kind="note" title="Where messages show up">
Messages appear in the Console under **Abrova Trace → Messages**, with their level, platform, extra data and breadcrumbs. They never create an issue. Levels: `.debug`, `.info` (default), `.warning`, `.error`. `.fatal` is accepted and stored as `error`. Use messages for things your app reports on purpose ("checkout started", "sync finished"); for high-volume diagnostics use Logs.
</Callout>

<H2 id="breadcrumbs" step={4}>Breadcrumbs</H2>

```swift
// User action
AbrovaTrace.shared.addUserBreadcrumb("Added item to cart", data: ["product_id": "abc"])

// Navigation
AbrovaTrace.shared.addNavigationBreadcrumb(from: "HomeView", to: "ProductDetailView")

// HTTP request
AbrovaTrace.shared.addHttpBreadcrumb(
    method: "POST",
    url: "https://api.example.com/orders",
    statusCode: 201,
    duration: 0.342  // seconds (TimeInterval)
)

// Custom breadcrumb
AbrovaTrace.shared.addBreadcrumb("Order placed", type: .info, data: [
    "order_id": "12345",
    "total": 99.99
])
```

<H2 id="automatic-http-tracking" step={5}>Automatic HTTP Tracking</H2>

#### Global HTTP Tracking

Enable automatic tracking for URLSession requests. Each request is reported as a performance span and added as an HTTP breadcrumb:

```swift
// Registers AbrovaTraceURLProtocol globally (URLSession.shared and default-configured sessions)
AbrovaTrace.shared.enablePerformanceTracking()

// Requests are now tracked automatically
let (data, response) = try await URLSession.shared.data(from: url)
```

#### Session-Based Tracking

```swift
// Create a tracked URLSession
let config = AbrovaTrace.shared.performanceSessionConfiguration()
// Equivalent to:
// config.protocolClasses = [AbrovaTraceURLProtocol.self] + (config.protocolClasses ?? [])
let session = URLSession(configuration: config)

// Requests through this session are tracked
let task = session.dataTask(with: url) { data, response, error in
    // Handle response
}
task.resume()
```

<Callout kind="note" title="Privacy">
  Performance spans from <code>enablePerformanceTracking()</code> record the full request URL, including query strings, so avoid putting secrets in URLs or exclude those hosts with <code>setPerformanceExcludedHosts(_:)</code>. The separate <code>AbrovaTraceHttpBreadcrumbProtocol.enable()</code> adds HTTP breadcrumbs with sensitive query parameters (token, api_key, apikey, key, secret, password, pwd, auth, authorization, access_token, refresh_token, session) redacted, and reports 5xx responses and failed requests as messages.
</Callout>

<H2 id="crash-detection" step={6}>Crash Detection</H2>

AbrovaTrace captures crashes with a vendored copy of PLCrashReporter:

- **Uncaught NSExceptions** — Sent immediately, before the app exits (`captureUncaughtExceptions`)
- **ANR Events** — Main thread blocked longer than `anrTimeoutMs` (`captureAnr`)
- **Native Crashes** — POSIX signals (SIGSEGV, SIGABRT, SIGBUS, SIGILL, SIGFPE, SIGTRAP) and Mach exceptions (`captureSignalCrashes`)

1. On initialization, AbrovaTrace installs PLCrashReporter's async-signal-safe handlers
2. When the app crashes, a crash report is written to disk inside the app sandbox
3. On the next launch, `initialize` reads the pending report and sends it to Abrova Trace in the background, so app launch never waits for the network. The report is removed only after it was delivered; if the server or the network fails it is kept and sent on a later launch. Requires version 0.2.3 or newer.

<Callout kind="note" title="Important">
  Native crashes are reported on the <em>next</em> launch, so they only arrive once the user opens the app again. The SDK calls <code>AbrovaTrace.shared.close()</code> itself when it receives the app's will-terminate notification; calling it yourself is optional and flushes buffered logs.
</Callout>

<H2 id="performance-monitoring-apm" step={7}>Performance Monitoring (APM)</H2>

Track API latency and HTTP request performance.

#### Automatic HTTP Tracking with URLSession

```swift
// Enable performance tracking globally
AbrovaTrace.shared.enablePerformanceTracking()

// All URLSession requests are now tracked with timing data
let (data, response) = try await URLSession.shared.data(from: url)
// Method, URL, status code, and duration are automatically reported
```

#### Using with Alamofire

```swift
import Alamofire

// Create a session with AbrovaTrace tracking
let configuration = URLSessionConfiguration.default
configuration.protocolClasses = [AbrovaTraceURLProtocol.self] + (configuration.protocolClasses ?? [])

let session = Session(configuration: configuration)

// All requests through this session are tracked
session.request("https://api.example.com/users").response { response in
    // Handle response
}
```

#### Track Custom Operations

```swift
// Async (iOS 13+); use PerformanceTracker.track(_:) for synchronous work
let result = try await PerformanceTracker.trackAsync("load_user_profile") {
    let user = try await fetchUser()
    try await cacheUser(user)
    return user
}

// Or time it manually
let tracker = PerformanceTracker(operation: "image_processing")
// ... do work
tracker.finish(status: .ok)
```

#### Manual Span Reporting

```swift
// HTTP request span
AbrovaTrace.shared.reportPerformanceSpan(
    PerformanceSpan.fromHttpRequest(
        method: "GET",
        url: "https://api.example.com/products",
        statusCode: 200,
        durationMs: 245,
        startTime: Date().addingTimeInterval(-0.245)
    )
)

// Database query span
AbrovaTrace.shared.reportPerformanceSpan(
    PerformanceSpan.forDbQuery(
        queryType: "SELECT",
        tableName: "products",
        durationMs: 15,
        startTime: Date().addingTimeInterval(-0.015),
        rowsAffected: 50
    )
)

// Custom operation span
AbrovaTrace.shared.reportPerformanceSpan(
    PerformanceSpan.custom(
        operation: "image_processing",
        durationMs: 1250,
        startTime: Date().addingTimeInterval(-1.25),
        tags: ["format": "png"]
    )
)
```

<H2 id="logging" step={8}>Logging</H2>

Structured log ingestion with automatic batching and retry. Enable it once, then use the level helpers from anywhere in your app:

```swift
// Enable logging after initialization
AbrovaTrace.shared.enableLogging(sourceId: "my-ios-app")

AbrovaTrace.shared.info("User login successful", metadata: ["user_id": "user_123"])
```

See [iOS SDK Logging](/docs/trace/ios-logging) for the full pipeline — batching, log levels, lifecycle handling, manual flush, and configuration.

<H2 id="configuration-options" step={9}>Configuration Options</H2>

<ConfigTable rows={[
  ['apiKey', 'String', 'Yes', 'Your project API key (must start with ab_live_)'],
  ['environment', 'String', 'No', 'Environment name (default: "production")'],
  ['release', 'String?', 'No', 'App version identifier (default: CFBundleShortVersionString)'],
  ['debug', 'Bool', 'No', 'Enable debug logging (default: false)'],
  ['enabled', 'Bool', 'No', 'Enable/disable SDK (default: true)'],
  ['sampleRate', 'Double', 'No', 'Error capture sample rate 0.0-1.0 (default: 1.0)'],
  ['maxBreadcrumbs', 'Int', 'No', 'Max breadcrumbs to keep (default: 20)'],
  ['httpTimeout', 'TimeInterval', 'No', 'HTTP request timeout in seconds (default: 30)'],
  ['enableOfflineStorage', 'Bool', 'No', 'Keep errors that could not be sent because the device is offline on disk (up to 100, oldest dropped first) and send them on the next launch or as soon as another error is sent successfully. Errors only: messages, logs and performance data are not stored. Set to false to keep nothing on disk (default: true)'],
  ['captureUncaughtExceptions', 'Bool', 'No', 'Catch uncaught exceptions (default: true)'],
  ['captureSignalCrashes', 'Bool', 'No', 'Detect signal crashes (default: true)'],
  ['captureAnr', 'Bool', 'No', 'Detect main thread hangs (default: true)'],
  ['anrTimeoutMs', 'Int64', 'No', 'ANR detection timeout in ms (default: 5000)'],
  ['apiUrl', 'String', 'No', 'API base URL, for self-hosted deployments (default: "https://trace.abrova.ir")'],
]} />

<H2 id="upload-debug-symbols-dsym" step={10}>Upload Debug Symbols (dSYM)</H2>

To see file names and line numbers in your iOS stack traces, upload your app's dSYM files. Each build produces unique dSYMs — upload a new one for every release version.

#### 1. Find your dSYM files

After building your app in Xcode, dSYMs are located in your build products:

```bash
# For debug builds (simulator)
~/Library/Developer/Xcode/DerivedData/YourApp-*/Build/Products/Debug-iphonesimulator/YourApp.app.dSYM

# For release/archive builds
~/Library/Developer/Xcode/Archives/*.xcarchive/dSYMs/
```

#### 2. Zip the dSYM bundle

```bash
# Zip the .dSYM bundle
cd ~/Library/Developer/Xcode/DerivedData/YourApp-*/Build/Products/Debug-iphonesimulator/
zip -r YourApp.dSYM.zip YourApp.app.dSYM
```

#### 3. Upload via Dashboard

In the Abrova Console, go to **Abrova Trace → Source maps** and open the **iOS dSYMs** tab. Drop the .zip file, optionally enter the release version, and click Upload. Uploading needs the member role or higher; deleting uploaded dSYMs needs admin or owner — see [Roles & Permissions](/docs/trace/error-dashboard#roles).

The dSYM upload endpoint accepts only a Console login session (no API key or personal access token), and `@abrova-trace/cli` uploads source maps only, so upload dSYMs from the Console.

<Callout kind="note" title="Important">
  Each time you rebuild your app, the dSYM UUIDs change. If stack traces show function names but no file/line info, you need to upload the dSYM matching that build.
</Callout>

<H2 id="platform-support" step={11}>Platform Support</H2>

- **iOS** — 12.0+
- **macOS** — 10.14+
- **tvOS** — 12.0+ (Swift Package Manager only; the CocoaPods spec covers iOS and macOS)

watchOS is not supported. Building the SDK requires Swift 5.10 or later (Xcode 15.3+).

<H2 id="context-tags" step={12}>Context & Tags</H2>

Attach persistent metadata to every error and message captured by the SDK (native crash and ANR reports, logs and performance spans do not carry them). Useful for filtering by team, region, feature flag, or experiment cohort in the Abrova Console.

#### Global extras

Extras are arbitrary key/value pairs (string keys, any serializable value) automatically merged into every event:

```swift
// Set individual extras
AbrovaTrace.shared.setExtra("organizationId", value: "org-123")
AbrovaTrace.shared.setExtra("feature", value: "checkout-v2")

// Set multiple at once
AbrovaTrace.shared.setExtras([
    "organizationId": "org-123",
    "feature": "checkout-v2",
    "experiment": "new-flow"
])

// Clear when no longer needed (e.g. on logout)
AbrovaTrace.shared.clearExtras()
```

#### Tags

Tags are string-only key/value pairs for categorizing events:

```swift
AbrovaTrace.shared.setTag("team", value: "payments")
AbrovaTrace.shared.setTag("region", value: "us-east")

AbrovaTrace.shared.setTags(["team": "payments", "version": "2.1"])

AbrovaTrace.shared.clearTags()
```

<Callout kind="note" title="Tags vs Extras">
Use **tags** for low-cardinality categorical filters (team, region, build flavor). Use **extras** for richer per-event context (user IDs, request bodies, computed values).
</Callout>

<H2 id="swiftui-integration" step={13}>SwiftUI Integration</H2>

The SDK works seamlessly with the SwiftUI `@main` app entry point. Initialize from the `App` struct's `init()` so errors are captured from the moment your view hierarchy is constructed:

```swift
import SwiftUI
import AbrovaTrace

@main
struct MyApp: App {

    init() {
        let config = AbrovaTraceConfigBuilder(apiKey: "ab_live_your_api_key")
            .environment("production")
            .build()
        AbrovaTrace.shared.initialize(config: config)
    }

    var body: some Scene {
        WindowGroup {
            ContentView()
        }
    }
}
```

<Callout kind="note" title="UIKit?">
For UIKit apps, initialize from `application(_:didFinishLaunchingWithOptions:)` in your `AppDelegate` — see the Complete Example below.
</Callout>

### API Reference

Full method surface of `AbrovaTrace.shared` and `PerformanceSpan`. Selectors use the Swift convention; optional parameters end with `?` in the description.

#### `AbrovaTrace.shared` — Initialization & lifecycle

<ConfigTable rows={[
  ['initialize(config:)', '-', '-', 'Initialize SDK with a full AbrovaTraceConfig'],
  ['initialize(apiKey:)', '-', '-', 'Initialize SDK with just an API key (uses defaults)'],
  ['isReady', '-', '-', 'True once the SDK is initialized'],
  ['close()', '-', '-', 'Cleanup SDK, flush pending data'],
]} />

#### Error capture

<ConfigTable rows={[
  ['captureError(_:message:extra:tags:completion:)', '-', '-', 'Capture a Swift Error'],
  ['captureException(_:message:extra:tags:completion:)', '-', '-', 'Capture an NSException'],
  ['captureMessage(_:level:extra:tags:completion:)', '-', '-', 'Send a message to Abrova Trace → Messages (not an issue)'],
]} />

#### User & session

<ConfigTable rows={[
  ['setUserId(_:)', '-', '-', 'Set the current user identifier'],
  ['getUserId()', '-', '-', 'Get the current user identifier'],
]} />

#### Global context (extras)

<ConfigTable rows={[
  ['setExtra(_:value:)', '-', '-', 'Set a single extra'],
  ['setExtras(_:)', '-', '-', 'Set multiple extras at once'],
  ['clearExtras()', '-', '-', 'Clear all extras'],
]} />

#### Tags

<ConfigTable rows={[
  ['setTag(_:value:)', '-', '-', 'Set a single tag'],
  ['setTags(_:)', '-', '-', 'Set multiple tags at once'],
  ['clearTags()', '-', '-', 'Clear all tags'],
]} />

#### Breadcrumbs

<ConfigTable rows={[
  ['addBreadcrumb(_:type:data:)', '-', '-', 'Add a generic breadcrumb'],
  ['addNavigationBreadcrumb(from:to:)', '-', '-', 'Add a navigation breadcrumb'],
  ['addUserBreadcrumb(_:data:)', '-', '-', 'Add a user-action breadcrumb'],
  ['addHttpBreadcrumb(method:url:statusCode:duration:)', '-', '-', 'Add an HTTP breadcrumb'],
  ['clearBreadcrumbs()', '-', '-', 'Clear all breadcrumbs'],
]} />

#### Performance monitoring

<ConfigTable rows={[
  ['reportPerformanceSpan(_:completion:)', '-', '-', 'Report a constructed PerformanceSpan'],
  ['reportPerformanceSpanBatch(_:completion:)', '-', '-', 'Report multiple spans at once'],
  ['trackHttpRequest(request:response:startTime:error:)', '-', '-', 'Track a one-off HTTP request'],
  ['enablePerformanceTracking()', '-', '-', 'Turn on automatic HTTP tracking'],
  ['disablePerformanceTracking()', '-', '-', 'Turn off automatic HTTP tracking'],
  ['performanceSessionConfiguration(baseConfiguration:)', '-', '-', 'Return a URLSessionConfiguration with tracking attached'],
  ['setPerformanceExcludedHosts(_:)', '-', '-', 'Exclude hosts from automatic tracking'],
  ['setPerformanceMinDuration(_:)', '-', '-', 'Set minimum span duration threshold'],
]} />

#### Logging

<ConfigTable rows={[
  ['enableLogging(sourceId:sourceName:batchSize:flushInterval:)', '-', '-', 'Turn on the log pipeline'],
  ['log(_:level:metadata:)', '-', '-', 'Log at an explicit level'],
  ['trace(_:metadata:)', '-', '-', 'Log at trace level'],
  ['logDebugMessage(_:metadata:)', '-', '-', 'Log at debug level'],
  ['info(_:metadata:)', '-', '-', 'Log at info level'],
  ['warn(_:metadata:)', '-', '-', 'Log at warn level'],
  ['logErrorMessage(_:metadata:)', '-', '-', 'Log at error level'],
  ['fatal(_:metadata:)', '-', '-', 'Log at fatal level'],
  ['flushLogs(completion:)', '-', '-', 'Flush buffered logs immediately'],
  ['pendingLogCount', '-', '-', 'Number of logs still in the buffer'],
]} />

#### `PerformanceSpan` factories

<ConfigTable rows={[
  ['PerformanceSpan.fromHttpRequest(...)', '-', '-', 'Construct a span from an HTTP request/response'],
  ['PerformanceSpan.forDbQuery(...)', '-', '-', 'Construct a span for a database query'],
  ['PerformanceSpan.custom(...)', '-', '-', 'Construct a fully custom span'],
  ['PerformanceSpan.generateTraceId()', '-', '-', 'Generate a random trace ID'],
  ['PerformanceSpan.generateSpanId()', '-', '-', 'Generate a random span ID'],
]} />

### Complete Example

```swift
import UIKit
import AbrovaTrace

@main
class AppDelegate: UIResponder, UIApplicationDelegate {

    func application(_ application: UIApplication,
                     didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {

        let config = AbrovaTraceConfigBuilder(apiKey: "ab_live_YOUR_API_KEY")
            .environment("production")
            .release(Bundle.main.infoDictionary?["CFBundleShortVersionString"] as? String)
            .debug(false)
            .captureUncaughtExceptions(true)
            .captureSignalCrashes(true)
            .captureAnr(true)
            .build()

        AbrovaTrace.shared.initialize(config: config)
        AbrovaTrace.shared.enablePerformanceTracking()

        return true
    }

    func applicationWillTerminate(_ application: UIApplication) {
        AbrovaTrace.shared.close()
    }
}

class ViewController: UIViewController {

    override func viewDidLoad() {
        super.viewDidLoad()
        AbrovaTrace.shared.setUserId("user_123")
        AbrovaTrace.shared.addNavigationBreadcrumb(from: "Launch", to: "HomeView")
    }

    func handlePurchase() {
        AbrovaTrace.shared.addUserBreadcrumb("Initiated purchase", data: ["product": "Premium"])

        do {
            try processPurchase()
            AbrovaTrace.shared.captureMessage("Purchase successful", level: .info, extra: [
                "amount": 99.99
            ])
        } catch {
            AbrovaTrace.shared.captureError(
                error,
                message: "Purchase failed",
                extra: ["user_id": "user_123", "screen": "HomeView"]
            )
        }
    }

    func processPurchase() throws { /* ... */ }
}
```

### Best Practices

<BestPracticeList items={[
  ['Initialize in AppDelegate or App init', 'Initialize AbrovaTrace as early as possible to catch all errors from app start'],
  ['close() on App Termination', 'The SDK calls close() on the will-terminate notification to flush logs; call it yourself only for custom shutdown paths'],
  ['Enable HTTP Tracking', 'Call enablePerformanceTracking() for automatic HTTP breadcrumbs and performance monitoring'],
  ['Add Context to Errors', 'Include user IDs, screen names, and relevant data in the extra parameter'],
  ['Use Different Environments', 'Separate production, staging, and development errors using the environment config'],
  ['Enable Debug Mode in Development', 'Set debug: true during development to see SDK logs and verify integration'],
  ['Enable Logging Early', 'Call enableLogging() right after initialization to capture all application events'],
]} />

- Laravel SDK: https://abrova.ir/en/docs/trace/laravel-sdk

<BestPracticeList columns={2} items={[
  ['Server-Side Error Tracking', 'Comprehensive error monitoring for Laravel applications'],
  ['Automatic Exception Capture', 'Integrates with Laravel exception handler via reportable()'],
  ['Laravel Middleware', 'Built-in HTTP middleware for request/response tracking'],
  ['Breadcrumbs', 'Track events leading up to an error for better context'],
  ['Database Query Tracking', 'Automatic breadcrumbs and slow query detection via QueryExecuted'],
  ['User Context', 'Associate errors with authenticated Laravel users automatically'],
  ['Monolog Integration', "Use Log::channel('abrovatrace') for structured logging"],
  ['Performance Monitoring', 'Track HTTP requests, DB queries, and custom operations'],
]} />

<H2 id="installation" step={1}>Installation</H2>

The package comes from Abrova Center. Two steps:

**1. Add the Abrova repository** to your `composer.json`:

```json
"repositories": [
    { "type": "composer", "url": "https://center.abrova.ir/api/packages/abrova/composer" }
]
```

**2. Install the package:**

```bash
composer require abrova-trace/laravel-sdk
```

Publish the configuration file:

```bash
php artisan vendor:publish --tag=abrovatrace-config
```

<H2 id="quick-start" step={2}>Quick Start</H2>

Add your credentials to `.env`:

```bash
ABROVATRACE_API_KEY=ab_live_your_api_key_here
ABROVATRACE_SERVER_SECRET=ab_srv_your_server_secret_here
ABROVATRACE_ENVIRONMENT=production
ABROVATRACE_RELEASE=1.0.0
```

<Callout kind="note" title="Auto-Discovery">
  The SDK uses Laravel package auto-discovery. No manual registration of service providers or facades is needed. The facade is `AbrovaTrace\Laravel\AbrovaTraceFacade` (auto-aliased as `AbrovaTrace`). The SDK stays inactive until both `ABROVATRACE_API_KEY` and `ABROVATRACE_SERVER_SECRET` are set.
</Callout>

<H2 id="capture-errors" step={3}>Capture Errors</H2>

#### Automatic Capture

All unhandled exceptions are automatically captured via Laravel's exception handler. No code changes needed.

The exception is still written to your application's own log (`laravel.log` or your configured log channels), so you do not need to change your logging setup. Versions before 0.2.3 stopped Laravel's default logging for captured exceptions.

#### Manual Capture

```php
use AbrovaTrace\Laravel\AbrovaTraceFacade as AbrovaTrace;

// Capture an exception
try {
    riskyOperation();
} catch (\Throwable $e) {
    AbrovaTrace::captureException($e, [
        'extra' => ['userId' => 123, 'feature' => 'checkout'],
    ]);
}

// Capture a message
AbrovaTrace::captureMessage('User completed checkout', [
    'extra' => ['orderId' => 'ORD-456'],
]);

// With a level and tags ('debug', 'info' (default), 'warning', 'error')
AbrovaTrace::captureMessage('Payment retried', [
    'level' => 'warning',
    'tags' => ['feature' => 'checkout'],
]);
```

The same exception is reported once. If you capture it with `captureException()` and then rethrow it, the automatic capture does not send it a second time (since 0.2.3).

<Callout kind="note" title="Where messages show up">
Messages appear in the Console under **Abrova Trace → Messages**, with their level, platform, extra data and breadcrumbs. They never create an issue. `'warn'` is sent as `warning`; `'fatal'`, `'critical'`, `'alert'` and `'emergency'` as `error`; `'trace'` as `debug`; anything else as `info`. Use messages for things your app reports on purpose ("checkout started", "sync finished"); for high-volume diagnostics use Logs.
</Callout>

<H2 id="breadcrumbs" step={4}>Breadcrumbs</H2>

Breadcrumbs track events leading up to an error. HTTP requests and database queries are tracked automatically.

#### Manual Breadcrumbs

```php
use AbrovaTrace\Laravel\AbrovaTraceFacade as AbrovaTrace;
use AbrovaTrace\Laravel\Models\Breadcrumb;

// HTTP breadcrumb
AbrovaTrace::addBreadcrumb(Breadcrumb::http('POST', '/api/orders', 201, 150.5));

// Database breadcrumb
AbrovaTrace::addBreadcrumb(Breadcrumb::database('SELECT * FROM users WHERE id = ?', 12.5));

// User action breadcrumb
AbrovaTrace::addBreadcrumb(Breadcrumb::user('clicked_checkout', ['cartTotal' => 99.99]));

// Custom breadcrumb
AbrovaTrace::addBreadcrumb(Breadcrumb::custom('Cache cleared', 'cache', ['keys' => 15]));
```

<Callout kind="note" title="Automatic Breadcrumbs">
  The SDK automatically records HTTP request/response breadcrumbs via middleware and database query breadcrumbs via the QueryExecuted event listener. No manual setup required.
</Callout>

<H2 id="user-context" step={5}>User Context</H2>

User context is automatically extracted from authenticated users via middleware. You can also set it manually:

```php
AbrovaTrace::setUser([
    'id' => 123,
    'email' => 'user@example.com',
    'username' => 'john_doe',
]);
```

<H2 id="scoped-context" step={6}>Scoped Context</H2>

Use scoped context to isolate user and request context per operation. Both are automatically restored afterward (breadcrumbs added inside the closure are kept). The closure receives the SDK instance.

```php
AbrovaTrace::withScope(function ($scope) {
    $scope->setUser(['id' => 456]);
    $scope->setRequestContext(['operation' => 'bulk_import']);
    $scope->addBreadcrumb(Breadcrumb::custom('Starting import', 'import'));

    // Errors captured here include this context
    AbrovaTrace::captureException(new \RuntimeException('Import failed'));
});
// Context is restored after the closure
```

<H2 id="laravel-middleware" step={7}>Laravel Middleware</H2>

The middleware is automatically registered on web and api groups. It provides:

- **Request Tracking** — Records the incoming request as a breadcrumb (method and path) and sets request context (method, URL, path, route, IP, user agent)
- **Response Tracking** — Records response breadcrumb with status code and duration
- **User Extraction** — Automatically sets user context (id, email, name) from the authenticated user (`middleware.track_user`)
- **Performance Spans** — Creates an HTTP performance span for every request (when `performance.enabled` is true)

To customize ignored paths, edit `config/abrovatrace.php`:

```php
'middleware' => [
    'enabled' => true,
    'ignored_paths' => [
        'health',
        'api/health',
        '_debugbar/*',
        'telescope/*',
    ],
],
```

<H2 id="database-query-tracking" step={8}>Database Query Tracking</H2>

Database queries are automatically tracked via Laravel's QueryExecuted event (`performance.track_db_queries`). Every query becomes a breadcrumb; queries at or above the threshold (default 500ms) also generate performance spans.

```php
// config/abrovatrace.php
'performance' => [
    'enabled' => true,
    'track_db_queries' => true,
    'slow_query_threshold_ms' => 100,  // Span for queries taking 100ms or more
],
```

<H2 id="monolog-log-channel" step={9}>Monolog Log Channel</H2>

Send logs to AbrovaTrace using Laravel's built-in logging system:

```php
// config/logging.php
'channels' => [
    'abrovatrace' => [
        'driver' => 'custom',
        'via' => AbrovaTrace\Laravel\Logging\AbrovaTraceLogChannel::class,
    ],
],
```

```php
use Illuminate\Support\Facades\Log;

Log::channel('abrovatrace')->info('User signed up', ['userId' => 123]);
Log::channel('abrovatrace')->error('Payment failed', ['orderId' => 'ORD-456']);
Log::channel('abrovatrace')->warning('Rate limit approaching', ['remaining' => 5]);
```

<Callout kind="note" title="Stack Channel">
  You can add abrovatrace to a stack channel to send logs to multiple destinations simultaneously.
</Callout>

See [Laravel SDK Logging](/docs/trace/laravel-logging) for batching behavior, log levels, and manual flush.

<H2 id="performance-tracking" step={10}>Performance Tracking</H2>

```php
use AbrovaTrace\Laravel\AbrovaTraceFacade as AbrovaTrace;
use AbrovaTrace\Laravel\Performance\PerformanceSpan;

// Track a custom operation with automatic timing
$result = AbrovaTrace::trackOperation('cache.rebuild', function () {
    return rebuildCache();
}, ['tags' => ['cache' => 'products']]);

// Manual performance span
AbrovaTrace::reportPerformanceSpan(PerformanceSpan::custom([
    'operation' => 'email.send',
    'durationMs' => 250.5,
    'startTime' => now()->subMilliseconds(250),
    'tags' => ['mailer' => 'smtp'],
]));
```

<H2 id="configuration-options" step={11}>Configuration Options</H2>

```php
// config/abrovatrace.php
return [
    'api_key' => env('ABROVATRACE_API_KEY', ''),
    'server_secret' => env('ABROVATRACE_SERVER_SECRET', ''),
    'enabled' => env('ABROVATRACE_ENABLED', true),
    'environment' => env('ABROVATRACE_ENVIRONMENT', env('APP_ENV', 'production')),
    'release' => env('ABROVATRACE_RELEASE', '0.1.0'),
    'sample_rate' => env('ABROVATRACE_SAMPLE_RATE', 1.0),
    'before_send' => null, // set a closure from a service provider
    'debug' => env('ABROVATRACE_DEBUG', false),
    'timeout' => env('ABROVATRACE_TIMEOUT', 5),
    'max_breadcrumbs' => 50,
];
```

<ConfigTable rows={[
  ['api_key', 'string', 'Yes', 'Your project API key (ab_live_xxx)'],
  ['server_secret', 'string', 'Yes', 'Your server secret (ab_srv_xxx)'],
  ['enabled', 'boolean', 'No', 'Enable/disable tracking (default: true)'],
  ['environment', 'string', 'No', 'Environment name (default: APP_ENV, else "production")'],
  ['release', 'string', 'No', 'App version identifier (default: "0.1.0")'],
  ['sample_rate', 'float', 'No', 'Sample rate for errors and messages, 0.0-1.0 (default: 1.0)'],
  ['before_send', 'callable', 'No', 'Receives each error (AbrovaTraceError) or message (AbrovaTraceMessage); return it (or a modified one) to send, null to drop. Set it from a service provider, since a closure cannot live in a cached config'],
  ['debug', 'boolean', 'No', 'Enable debug logging (default: false)'],
  ['timeout', 'integer', 'No', 'HTTP timeout in seconds (default: 5, max: 30)'],
  ['max_breadcrumbs', 'integer', 'No', 'Max breadcrumbs to keep, 0-100 (default: 50)'],
]} />

<H2 id="ignored-exceptions" step={12}>Ignored Exceptions</H2>

The SDK ships with sensible defaults for exceptions Laravel apps typically don't want as errors. By default these are **not** reported:

- `AuthenticationException` — unauthenticated requests
- `ValidationException` — form validation failures
- `NotFoundHttpException` — 404s
- All 4xx HTTP exceptions

Customize via `config/abrovatrace.php`:

```php
'exception_handler' => [
    'ignored_exceptions' => [
        \App\Exceptions\BusinessException::class,
    ],
    'report_4xx' => true,
],
```

The `ignored_exceptions` list you set replaces the default one, so keep the default entries you still want ignored.

<Callout kind="note" title="Why exclude 4xx by default">
4xx responses are client errors — duplicating them as exceptions makes the error feed noisy. Flip `report_4xx` to `true` if you genuinely want them captured (e.g. for analytics).
</Callout>

### API Reference

#### AbrovaTrace Facade

- `captureException($e, $options?)` — Capture an exception
- `captureMessage($msg, $options?)` — Send a message to Abrova Trace → Messages (`$options`: `level`, `extra`, `tags`)
- `addBreadcrumb($breadcrumb)` — Add a breadcrumb
- `setUser($user)` — Set user context
- `setRequestContext($context)` — Set request context
- `withScope($callback)` — Run code with isolated user/request context
- `log($message, $level?, $metadata?)` — Send a log entry (user id comes from `setUser()`)
- `trace()`, `logDebug()`, `info()`, `warn()`, `logError()`, `fatal()` — Log at a level (`$message, $metadata?`)
- `trackOperation($name, $callback, $options?)` — Track operation with auto-timing (`$options`: `operationType`, `tags`)
- `reportPerformanceSpan($span)` — Report a performance span
- `flush()` — Flush buffered logs and performance spans (also runs automatically at shutdown)
- `isEnabled()` — Check if SDK is enabled
- `getStats()` — Get SDK statistics

#### Breadcrumb Helpers

- `Breadcrumb::http($method, $url, $status?, $duration?)` — HTTP request breadcrumb
- `Breadcrumb::database($query, $duration, $error?)` — Database query breadcrumb
- `Breadcrumb::user($action, $data?)` — User action breadcrumb
- `Breadcrumb::navigation($from, $to, $method?)` — Navigation breadcrumb
- `Breadcrumb::custom($message, $category, $data?)` — Custom breadcrumb

### Requirements

- **PHP** — >= 8.1
- **Laravel** — 10.x / 11.x / 12.x
- **Guzzle** — >= 7.0 (ships with Laravel)

### Complete Example

```php
// routes/api.php
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Route;
use Illuminate\Support\Facades\Log;
use AbrovaTrace\Laravel\AbrovaTraceFacade as AbrovaTrace;
use AbrovaTrace\Laravel\Models\Breadcrumb;

Route::get('/users/{id}', function ($id) {
    // Add a breadcrumb (DB queries are tracked automatically)
    AbrovaTrace::addBreadcrumb(Breadcrumb::user('view_user', [
        'userId' => $id,
    ]));

    try {
        $user = User::findOrFail($id);
        return response()->json($user);
    } catch (\Throwable $e) {
        AbrovaTrace::captureException($e, [
            'extra' => ['userId' => $id],
        ]);
        return response()->json(['error' => 'User not found'], 404);
    }
});

// Log via Monolog channel
Route::post('/orders', function (Request $request) {
    $order = Order::create($request->validate([
        'total' => 'required|numeric',
    ]));

    Log::channel('abrovatrace')->info('Order created', [
        'orderId' => $order->id,
        'amount' => $order->total,
    ]);

    // Track performance of external API call
    $result = AbrovaTrace::trackOperation('payment.process', function () use ($order) {
        return PaymentGateway::charge($order);
    });

    return response()->json($result);
});
```

### Best Practices

<BestPracticeList items={[
  ['Use Environment Variables', 'Store API key and server secret in .env, never commit credentials'],
  ['Leverage Auto-Discovery', 'The service provider registers automatically — no manual provider registration needed'],
  ['Use the Monolog Channel', "Send structured logs via Log::channel('abrovatrace') for centralized logging"],
  ['Set User Context', 'User context is auto-extracted from Auth, but set it manually for API token auth'],
  ['Add Breadcrumbs', 'HTTP and DB breadcrumbs are automatic — add custom breadcrumbs for business logic'],
  ['Configure Ignored Paths', 'Exclude health checks and debug routes from middleware tracking'],
  ['Track Slow Queries', 'Set slow_query_threshold_ms to catch performance regressions early'],
  ['Use trackOperation()', 'Wrap external API calls and expensive operations for performance monitoring'],
]} />

- Installing inside Iran: https://abrova.ir/en/docs/trace/install-in-iran

The Abrova SDKs install from [Abrova Center](https://center.abrova.ir), which is inside Iran. Each SDK also needs a few common packages (for example AndroidX, OkHttp or `http` for Dart). Those come from the public registries, and some of them refuse Iranian addresses or stop answering when the international internet is cut. This page shows how to get them from mirrors inside Iran.

<Callout kind="note" title="Tested from Iran">
  Every address on this page was checked from a server inside Iran on 27 October 2026, with the exact packages the Abrova SDKs need. The mirrors are run by other Iranian companies, not by Abrova, so their addresses can change.
</Callout>

| Platform | Abrova SDK | Its dependencies, inside Iran |
|---|---|---|
| Android | Abrova Center | Myket Maven mirror: Google and Maven Central packages, and the Android Gradle plugin |
| iOS | Abrova Center | None needed: the SDK has no other dependencies |
| Node.js, Next.js, CLI | Abrova Center | Runflare npm mirror |
| Flutter | Abrova Center | No mirror inside Iran: pub.dev refuses Iranian addresses (see below) |
| Laravel / PHP | Abrova Center | No mirror inside Iran: Packagist works from Iran today |

<H2 id="android" step={1}>Android (Gradle)</H2>

In `settings.gradle`, list the Iranian mirror before Google and Maven Central, for both plugins and libraries:

```groovy
pluginManagement {
    repositories {
        maven { url "https://maven.myket.ir" }
        gradlePluginPortal()
        google()
        mavenCentral()
    }
}

dependencyResolutionManagement {
    repositories {
        maven { url "https://center.abrova.ir/api/packages/abrova/maven" }
        maven { url "https://maven.myket.ir" }
        google()
        mavenCentral()
    }
}
```

Gradle tries the repositories in this order, so `google()` and `mavenCentral()` are only used for a package the mirror does not have.

Gradle itself is downloaded once per version from `services.gradle.org` (the `distributionUrl` in `gradle/wrapper/gradle-wrapper.properties`). Keep that download on your machine, or put the file on a server you control and point `distributionUrl` at it.

<H2 id="ios" step={2}>iOS</H2>

Nothing extra: the iOS SDK installs from Abrova Center and brings everything it needs. See [iOS SDK](/docs/trace/ios-sdk) for the Swift Package Manager and CocoaPods lines.

<H2 id="nodejs" step={3}>Node.js, Next.js and the CLI</H2>

In the project's `.npmrc`, use the Iranian npm mirror for everything and Abrova Center for the Abrova packages:

```ini
registry=https://mirror-npm.runflare.com/
@abrova-trace:registry=https://center.abrova.ir/api/packages/abrova/npm/
```

Then install as usual (`npm install`, `pnpm install` or `yarn`).

<H2 id="flutter" step={4}>Flutter</H2>

The Abrova Flutter package comes from Abrova Center. Its dependencies (`http`, `path_provider`, `device_info_plus` and a few more) come from pub.dev, and **pub.dev refuses Iranian addresses**. We found no pub mirror inside Iran. What works:

- Run `flutter pub get` once through a connection that reaches pub.dev. The packages stay in your pub cache, and later builds work without pub.dev.
- Commit `pubspec.lock`, so every machine and your CI resolve the same versions from that cache.
- Or set `PUB_HOSTED_URL=https://pub.flutter-io.cn` (a public mirror run by the Flutter community in China). It answers from Iran, but it is outside Iran, so it stops working when the international internet is cut.

<H2 id="php" step={5}>Laravel and PHP</H2>

The Abrova package comes from Abrova Center. Its dependencies (`guzzlehttp/guzzle`, `illuminate/*`) come from Packagist, which answers from Iran today; we found no Packagist mirror inside Iran. Composer keeps what it downloads in its cache, and `composer.lock` pins the versions.

<H2 id="when-the-internet-is-cut" step={6}>When the international internet is cut</H2>

- **Keeps working:** Abrova Center, the Myket and Runflare mirrors, and everything already in your local caches.
- **Stops:** pub.dev, Packagist, CocoaPods trunk, GitHub and `services.gradle.org`.

Keep your lock files (`pubspec.lock`, `package-lock.json`, `composer.lock`, `Package.resolved`, `Podfile.lock`) in git, so a fresh checkout needs as few downloads as possible.

- AI assistants (coming soon): https://abrova.ir/en/docs/trace/ai-assistants

<Callout kind="soon" title="Coming soon">
Abrova does not have a docs server for AI assistants yet. This page describes how it will work and what you can use today.
</Callout>

When it is ready, you connect your AI assistant (any tool that supports MCP, the open standard AI tools use to connect to outside sources) once. Then, when you ask it to add Abrova Trace to your project, it looks up the current SDK version, install lines and setup steps from these docs instead of answering from memory.

### What works today

- **Copy page for AI.** Every docs page has a **Copy page for AI** link. Paste the page into your assistant's chat before you ask it to write code.
- **Plain-text docs.** Give your assistant the address `https://abrova.ir/docs/llms.txt`. It lists every docs page as plain text that assistants read well.

Tell your assistant to follow the page you gave it, to install the SDK from Abrova Center as the page shows, and to use the placeholder keys from the docs.

### What it will do

The docs server will have read-only tools. Your assistant chooses them by itself; you do not call them by hand.

<ConfigTable headers={['Tool', 'What it will do']} rows={[
  ['list_products', 'Lists the Abrova products, with the platforms that have an SDK and the docs link.'],
  ['search_docs', 'Searches the docs for a few words or a short question and returns the best pages.'],
  ['read_doc', 'Returns one docs page as text, with its link and last-updated date.'],
  ['get_sdk_info', 'Returns the SDK package for a product and platform: name, current version and install lines.'],
  ['get_setup_guide', 'Returns the ordered setup steps for a product and platform: install, keys, initialization and how to test.'],
]} />

Examples of what you will be able to ask:

- **"Set up Abrova Trace in this Next.js project and upload source maps."** It would answer from the [Next.js SDK](/docs/trace/nextjs-sdk) and [Upload source maps](/docs/trace/upload-source-maps) pages.
- **"Add Abrova Trace to my Laravel app and record a breadcrumb before the payment call."** It would answer from the [Laravel SDK](/docs/trace/laravel-sdk) and [Breadcrumbs](/docs/trace/breadcrumbs) pages.
- **"Add a check-in to my nightly cron job and send Abrova Trace alerts to Telegram."** It would answer from [Cron monitoring](/docs/trace/cron-monitoring) and [Telegram](/docs/trace/telegram).
- **"Stream the logs of every Docker container on my server to Abrova Trace."** It would answer from [Abrova Trace agent](/docs/trace/agent).
- **"Which Abrova key goes in the app and which one stays on the server?"** It would answer from [Server secret & server routes](/docs/trace/server-secret).

### Privacy

- **What it reads:** the public Abrova docs, the current SDK versions, and the words your assistant sends (the search words, the page it wants, the product and platform names).
- **What it never sees:** your code, your files, your Abrova project, your keys or your users. The tools have no input for them, and they cannot change any setting.

<Callout kind="warn" title="Keep your keys out of the chat">
Never paste a key into a chat with an AI assistant. Your assistant writes the placeholder from the docs (`ab_live_your_api_key`); you put the real value in your project's configuration yourself. The server secret (`ab_srv_...`) belongs only on your server, in an environment variable.
</Callout>

More about AI assistants and Abrova: [AI assistants](/ai-assistants). Questions? [Contact us](/contact).

- APM overview: https://abrova.ir/en/docs/trace/apm

AbrovaTrace APM provides real-time performance monitoring across all your applications. Track HTTP request latency, database queries, and custom operations with p50/p95/p99 percentile metrics. For web apps, monitor Core Web Vitals (LCP, INP, CLS, plus TTFB and FCP).

<BestPracticeList columns={2} items={[
  ['API Latency Tracking', 'Monitor HTTP request/response times with p50, p95, p99 percentiles'],
  ['Core Web Vitals', 'LCP, INP, CLS, TTFB and FCP metrics for web platforms'],
  ['Custom Operations', 'Track any async operation with automatic duration measurement'],
  ['Percentile Analysis', 'p50, p95, p99 latency metrics for accurate insights'],
  ['Batch Reporting', 'Efficient batched span uploads to minimize network overhead'],
  ['Multi-Platform', 'Works across Next.js, Flutter, Android, iOS, Node.js, and Laravel'],
]} />

<Callout kind="wallet" title="Included">
  APM is included in Abrova Trace at no extra cost. Spans and Web Vitals are not counted as new issues, so they do not use your free monthly allowance or your wallet.
</Callout>

### Data Retention

Spans and Web Vitals are kept for your project's data retention period: 7 days free, or 30 days for +50,000 Toman per project a month from your wallet — see [Pricing](/pricing).

### Performance Span Structure

Each tracked operation creates a Performance Span with the following fields:

```typescript
interface PerformanceSpan {
  operation: string;        // e.g., "GET /api/users"
  operationType: 'http' | 'db' | 'custom';
  httpMethod?: string;      // GET, POST, PUT, DELETE
  httpUrl?: string;         // Full request URL
  httpStatusCode?: number;  // 200, 404, 500, etc.
  httpHost?: string;        // api.example.com
  durationMs: number;       // Request duration
  startTime: string;        // ISO timestamp
  endTime?: string;         // ISO timestamp
  traceId?: string;         // Distributed trace ID
  spanId?: string;          // Unique span ID
  parentSpanId?: string;    // Parent span for nesting
  platform: string;         // nextjs, flutter, web, android, ios, nodejs, laravel
  environment?: string;     // production, staging, dev
  releaseVersion?: string;  // App version
  tags?: Record<string, string>;  // Custom tags
  metadata?: Record<string, any>; // Additional data
  status: 'ok' | 'error';
  errorMessage?: string;
}
```

### Quick Start by SDK

#### Next.js / React

```typescript
import { AbrovaTrace } from '@abrova-trace/nextjs-sdk';

AbrovaTrace.init({
  apiKey: 'ab_live_your_api_key',
  environment: 'production',
});

// Enable automatic HTTP tracking (intercepts fetch)
AbrovaTrace.getInstance()?.enablePerformanceTracking();

// Enable Web Vitals (LCP, INP, CLS, TTFB, FCP)
AbrovaTrace.getInstance()?.enableWebVitals();
```

#### Flutter

```dart
import 'package:abrova_trace_flutter_sdk/abrova_trace_flutter_sdk.dart';

// Create a performance-tracking HTTP client
final client = PerformanceHttpClient(
  apiKey: 'ab_live_your_api_key',
  environment: 'production',
);

// All requests are automatically tracked
final response = await client.get(
  Uri.parse('https://api.example.com/users'),
);
```

#### Android (Kotlin)

```kotlin
import ir.abrova.trace.sdk.network.AbrovaTracePerformanceInterceptor
import okhttp3.OkHttpClient

val client = OkHttpClient.Builder()
    .addInterceptor(AbrovaTracePerformanceInterceptor())
    .build()

// All requests through this client are automatically tracked
```

#### iOS (Swift)

```swift
import AbrovaTrace

// Enable automatic URLSession tracking
AbrovaTrace.shared.enablePerformanceTracking()

// Or use a custom session with tracking
let config = AbrovaTrace.shared.performanceSessionConfiguration()
let session = URLSession(configuration: config)
```

#### Node.js

```javascript
const AbrovaTrace = require('@abrova-trace/nodejs-sdk');

// Time any async operation and report it as a span
const users = await AbrovaTrace.trackOperation(
  'fetch-users',
  () => db.query('SELECT * FROM users'),
  { operationType: 'db' }
);
```

### Viewing Data in Dashboard

Once tracking is enabled, open **Trace &rarr; Performance** in Abrova Console to see:

- **Overview Stats** — Requests, error rate, p50, p95 and p99 latency
- **Latency** — p50, p95, p99 over time, plus requests over time with errors stacked
- **Operations** — Each operation with its type, request count, latency percentiles and errors
- **Status codes, Web Vitals and Failed requests** cards
- **Filtering** — Time range (1h, 24h, 7d, 30d or custom), platform, environment, release

### API Endpoints

SDKs report spans to these endpoints:

<div>
  <table>
    <thead>
      <tr>
        {['Endpoint', 'Method', 'Description'].map((h) => (
          <th key={h}>{h}</th>
        ))}
      </tr>
    </thead>
    <tbody>
      {[
        ['/api/performance/spans', 'POST', 'Report single span'],
        ['/api/performance/spans/batch', 'POST', 'Report batch (max 50)'],
        ['/api/performance/web-vitals', 'POST', 'Report Web Vitals data'],
      ].map(([endpoint, method, desc]) => (
        <tr key={endpoint}>
          <td>{endpoint}</td>
          <td>{method}</td>
          <td>{desc}</td>
        </tr>
      ))}
    </tbody>
  </table>
</div>

### Best Practices

<BestPracticeList items={[
  ['Use Meaningful Operation Names', 'Use descriptive names like "GET /api/users" instead of generic names for easier identification'],
  ['Add Custom Tags', 'Add tags like user ID, tenant ID, or feature flags to filter and segment data'],
  ['Set Environment Correctly', 'Always set environment (production, staging, development) to separate data'],
  ['Monitor p95/p99 Not Just Average', 'Average latency hides outliers — focus on p95 and p99 for worst-case experience'],
  ['Use Batch Reporting', 'SDKs batch spans by default — avoid reporting individual spans when possible'],
  ['Exclude Health Check Endpoints', 'Filter out noisy endpoints like /health or /ping from tracking'],
]} />

- API latency tracking: https://abrova.ir/en/docs/trace/api-latency

API Latency Tracking captures timing data for all HTTP requests made by your application. The SDK automatically instruments HTTP clients to measure request duration and reports this data to AbrovaTrace for analysis with p50, p95, and p99 percentile metrics.

<BestPracticeList columns={2} items={[
  ['HTTP Method', 'GET, POST, PUT, DELETE, PATCH, etc.'],
  ['Request URL & Host', 'Full URL and host for grouping'],
  ['Response Status Code', '200, 404, 500, etc.'],
  ['Duration', 'Request duration in milliseconds'],
  ['Error Messages', 'Error details if request fails'],
  ['Custom Tags', 'Any additional metadata you attach'],
]} />

<H2 id="next-js-react" step={1}>Next.js / React</H2>

#### Automatic Tracking

Enable automatic fetch interception to track all HTTP requests:

```typescript
import { AbrovaTrace } from '@abrova-trace/nextjs-sdk';

AbrovaTrace.init({
  apiKey: 'ab_live_your_api_key',
  environment: 'production',
});

// Enable automatic HTTP tracking
// This intercepts window.fetch and reports timing
AbrovaTrace.getInstance()?.enablePerformanceTracking({
  batchSize: 5,        // Send spans in batches of 5 (default)
  flushInterval: 5000, // Flush at most 5 seconds after a span is buffered (default)
});
```

#### Manual Operation Tracking

```typescript
const sdk = AbrovaTrace.getInstance();

// Track an async operation
const result = await sdk?.trackOperation(
  'fetchUserProfile',
  async () => {
    const response = await fetch('/api/users/123');
    return response.json();
  },
  {
    operationType: 'http',
    tags: { userId: '123' }
  }
);
```

#### Performance Fetch Wrapper

```typescript
const sdk = AbrovaTrace.getInstance();

// Create a tracked fetch function
const performanceFetch = sdk?.createPerformanceFetch() ?? fetch;

// Use it like regular fetch — timing is automatically captured
const response = await performanceFetch('/api/users');
const data = await response.json();
```

The wrapper reports spans only after `enablePerformanceTracking()`, `trackOperation()` or `reportPerformanceSpan()` has been called. In the browser, `enablePerformanceTracking()` already tracks every `fetch`, so use the wrapper on the server.

#### Manual Span Reporting

```typescript
import { createHttpSpan, PerformanceSpanFactory } from '@abrova-trace/nextjs-sdk';

// Create and report an HTTP span
const span = createHttpSpan({
  method: 'GET',
  url: 'https://api.example.com/users',
  statusCode: 200,
  durationMs: 245,
  startTime: new Date(),
});
AbrovaTrace.getInstance()?.reportPerformanceSpan(span);

// Or use the factory for other span types
const dbSpan = PerformanceSpanFactory.forDbQuery({
  queryType: 'SELECT',
  tableName: 'users',
  durationMs: 15,
  startTime: new Date(),
});
AbrovaTrace.getInstance()?.reportPerformanceSpan(dbSpan);
```

<H2 id="flutter" step={2}>Flutter</H2>

#### Performance HTTP Client

Use the PerformanceHttpClient to automatically track all HTTP requests:

```dart
import 'package:abrova_trace_flutter_sdk/abrova_trace_flutter_sdk.dart';

// Create a performance-tracking HTTP client
final client = PerformanceHttpClient(
  apiKey: 'ab_live_your_api_key',
  environment: 'production',
  releaseVersion: '1.0.0',
  addBreadcrumbs: true,      // Also add HTTP breadcrumbs
  excludedHosts: {'analytics.example.com'},  // Hosts to skip (Abrova's own API is always skipped)
  minDurationMs: 0,          // Track all requests (set higher to filter fast ones)
);

// All requests are automatically tracked
final response = await client.get(
  Uri.parse('https://api.example.com/users'),
);

// Don't forget to flush and close
await client.flush();
client.close();
```

#### Custom Operation Tracking

```dart
import 'package:abrova_trace_flutter_sdk/abrova_trace_flutter_sdk.dart';

// Automatic tracking with closure
final result = await PerformanceTracker.track(
  operation: 'processOrder',
  apiKey: 'ab_live_your_api_key',
  block: () async => await orderService.process(orderId),
);

// Manual tracking
final tracker = PerformanceTracker(
  operation: 'processPayment',
  apiKey: 'ab_live_your_api_key',
  operationType: 'custom',
  environment: 'production',
);
// ... perform operation
await tracker.finish(status: SpanStatus.ok);
```

<H2 id="android-kotlin" step={3}>Android (Kotlin)</H2>

#### OkHttp Performance Interceptor

```kotlin
import ir.abrova.trace.sdk.network.AbrovaTracePerformanceInterceptor
import okhttp3.OkHttpClient
import okhttp3.Request

val client = OkHttpClient.Builder()
    .addInterceptor(AbrovaTracePerformanceInterceptor())  // APM tracking
    .build()

// All API calls are automatically tracked
val request = Request.Builder()
    .url("https://api.example.com/users")
    .build()

client.newCall(request).execute().use { response ->
    // Duration, status code, and errors are automatically reported
    val users = response.body?.string()
}
```

#### With Retrofit

```kotlin
import retrofit2.Retrofit
import retrofit2.converter.gson.GsonConverterFactory

val okHttpClient = OkHttpClient.Builder()
    .addInterceptor(AbrovaTracePerformanceInterceptor())
    .build()

val retrofit = Retrofit.Builder()
    .baseUrl("https://api.example.com/")
    .client(okHttpClient)
    .addConverterFactory(GsonConverterFactory.create())
    .build()

// All API calls through this Retrofit instance are automatically tracked
```

#### Manual Span Reporting

```kotlin
import ir.abrova.trace.sdk.AbrovaTrace
import ir.abrova.trace.sdk.models.PerformanceSpan

// Track a custom operation
val result = AbrovaTrace.trackOperation("load_user_profile") {
    val user = fetchUserFromApi()
    cacheUserLocally(user)
    user
}

// Manual span
AbrovaTrace.reportPerformanceSpan(
    PerformanceSpan.fromHttpRequest(
        method = "GET",
        url = "https://api.example.com/products",
        statusCode = 200,
        durationMs = 245L,
        startTime = System.currentTimeMillis() - 245
    )
)

// Database query span
AbrovaTrace.reportPerformanceSpan(
    PerformanceSpan.forDbQuery(
        queryType = "SELECT",
        tableName = "products",
        durationMs = 15L,
        startTime = System.currentTimeMillis() - 15,
        rowsAffected = 50
    )
)
```

<H2 id="ios-swift" step={4}>iOS (Swift)</H2>

#### Automatic URLSession Tracking

```swift
import AbrovaTrace

// Enable automatic tracking for all URLSession requests
AbrovaTrace.shared.enablePerformanceTracking()

// Or create a custom session with tracking
let config = AbrovaTrace.shared.performanceSessionConfiguration()
let session = URLSession(configuration: config)

// All requests through this session are automatically tracked
let (data, response) = try await session.data(from: url)
```

#### Configuration

```swift
// Exclude specific hosts from tracking
// (Abrova Trace's own API is always excluded)
AbrovaTrace.shared.setPerformanceExcludedHosts(["analytics.example.com"])

// Set minimum duration to track (filter very fast requests)
AbrovaTrace.shared.setPerformanceMinDuration(10) // Skip requests shorter than 10ms
```

#### Manual Tracking

```swift
import AbrovaTrace

// Track with closure
let profile = try await PerformanceTracker.trackAsync("fetchProfile") {
    await api.fetchProfile()
}

// Manual tracker
let tracker = PerformanceTracker(operation: "processOrder")
tracker.setTag("orderId", value: "12345")
// ... perform operation
tracker.finish(status: .ok)
```

<H2 id="node-js" step={5}>Node.js</H2>

#### Operation Tracking

The Node.js SDK has no automatic HTTP span capture. Wrap the work you want timed with `trackOperation`, or send spans yourself with `reportPerformanceSpan`:

```javascript
const AbrovaTrace = require('@abrova-trace/nodejs-sdk');

app.get('/api/users/:id', async (req, res) => {
  const user = await AbrovaTrace.trackOperation(
    'GET /api/users/:id',
    () => db.users.findById(req.params.id),
    { operationType: 'db', tags: { route: '/api/users/:id' } }
  );
  res.json(user);
});
```

#### Express.js Middleware

The Express middleware records each request (method, URL, status, duration) as an HTTP **breadcrumb** attached to errors — not as a Performance span:

```javascript
const middleware = AbrovaTrace.expressMiddleware();
app.use(middleware.requestHandler());

// Your routes

// Error handler (must be last)
app.use(middleware.errorHandler());
```

#### Database Query Tracking

```javascript
const { Breadcrumb } = require('@abrova-trace/nodejs-sdk');

async function executeQuery(sql, params) {
  const startTime = Date.now();

  try {
    AbrovaTrace.addBreadcrumb(Breadcrumb.database(sql.substring(0, 100), 0));

    const results = await db.query(sql, params);

    AbrovaTrace.addBreadcrumb(Breadcrumb.database(
      'Query completed',
      Date.now() - startTime
    ));

    return results;
  } catch (error) {
    AbrovaTrace.captureException(error, {
      extra: { sql, duration_ms: Date.now() - startTime }
    });
    throw error;
  }
}
```

### Dashboard View

The Performance dashboard shows latency data with the following views:

<div>
  {[
    ['Overview Stats', ['Requests', 'Error rate', 'p50 latency', 'p95 / p99 latency']],
    ['Latency', ['p50, p95, p99 over time', 'Requests over time, errors stacked']],
    ['Operations', ['Operation name and type', 'Request count and latency percentiles', 'Error count', 'Status codes, Web Vitals and failed requests cards']],
    ['Filtering', ['Time range (1h, 24h, 7d, 30d or custom)', 'Platform', 'Environment', 'Release']],
  ].map(([title, items]) => (
    <div key={title}>
      <h4>{title}</h4>
      <ul>
        {items.map((item) => (
          <li key={item}>&#8226; {item}</li>
        ))}
      </ul>
    </div>
  ))}
</div>

### Best Practices

<BestPracticeList items={[
  ['Use Meaningful Operation Names', 'Use descriptive names like "GET /api/users" instead of generic names for easier identification'],
  ['Add Custom Tags', 'Add tags like user ID, tenant ID, or feature flags to filter and segment data in the dashboard'],
  ['Set Environment Correctly', 'Always set environment (production, staging, development) to separate data from different deployments'],
  ['Monitor p95/p99 Not Just Average', 'Average latency hides outliers — focus on p95 and p99 for worst-case user experience'],
  ['Exclude Noise', 'Filter out health check endpoints and internal SDK calls from tracking'],
  ['Use Batch Reporting', 'Let the SDK batch spans — use reportPerformanceSpanBatch when you report many spans yourself'],
]} />

- Core Web Vitals: https://abrova.ir/en/docs/trace/web-vitals

Core Web Vitals are a set of metrics defined by Google that measure real-world user experience for loading performance, interactivity, and visual stability. These metrics directly impact SEO rankings and user satisfaction. AbrovaTrace uses Google's official **web-vitals** library for accurate measurement.

<Callout kind="note" title="Browser Only">
  Web Vitals are browser-specific metrics. Today only the Next.js SDK (`@abrova-trace/nextjs-sdk`) reports them. For mobile apps (iOS, Android, Flutter), use API Latency Tracking instead.
</Callout>

### Metrics Explained

<div>
  <div>
    <div>
      <div>
        <h4>LCP &mdash; Largest Contentful Paint</h4>
        <p>
          Measures loading performance. Marks when the largest content element (image, video, or text block) becomes visible.
        </p>
      </div>
    </div>
    <div>
      <div>
        <div></div>
        <div>Good</div>
        <div>&le;2.5s</div>
      </div>
      <div>
        <div></div>
        <div>Needs improvement</div>
        <div>2.5&ndash;4s</div>
      </div>
      <div>
        <div></div>
        <div>Poor</div>
        <div>&gt;4s</div>
      </div>
    </div>
  </div>

  <div>
    <div>
      <div>
        <h4>INP &mdash; Interaction to Next Paint</h4>
        <p>
          Measures overall responsiveness. Observes all interactions and reports the worst latency.
        </p>
      </div>
    </div>
    <div>
      <div>
        <div></div>
        <div>Good</div>
        <div>&le;200ms</div>
      </div>
      <div>
        <div></div>
        <div>Needs improvement</div>
        <div>200&ndash;500ms</div>
      </div>
      <div>
        <div></div>
        <div>Poor</div>
        <div>&gt;500ms</div>
      </div>
    </div>
  </div>

  <div>
    <div>
      <div>
        <h4>CLS &mdash; Cumulative Layout Shift</h4>
        <p>
          Measures visual stability. Sum of all unexpected layout shifts during the page's lifecycle.
        </p>
      </div>
    </div>
    <div>
      <div>
        <div></div>
        <div>Good</div>
        <div>&le;0.1</div>
      </div>
      <div>
        <div></div>
        <div>Needs improvement</div>
        <div>0.1&ndash;0.25</div>
      </div>
      <div>
        <div></div>
        <div>Poor</div>
        <div>&gt;0.25</div>
      </div>
    </div>
  </div>

  <div>
    {[
      ['TTFB', 'Time to First Byte', 'Server response time', '≤800ms'],
      ['FCP', 'First Contentful Paint', 'Perceived load speed', '≤1.8s'],
    ].map(([abbr, name, desc, good]) => (
      <div key={abbr}>
        <h4>{abbr}</h4>
        <p>{name}</p>
        <p>{desc}</p>
        <p>Good: {good}</p>
      </div>
    ))}
  </div>
</div>

<H2 id="next-js" step={1}>Next.js</H2>

#### Basic Setup

```typescript
import { AbrovaTrace } from '@abrova-trace/nextjs-sdk';

AbrovaTrace.init({
  apiKey: 'ab_live_your_api_key',
  environment: 'production',
  release: '1.0.0',
});

// Enable Web Vitals tracking
// Automatically captures LCP, INP, CLS, TTFB, FCP
AbrovaTrace.getInstance()?.enableWebVitals();
```

#### App Router (Next.js 13+)

```tsx
// app/providers.tsx
'use client';

import { useEffect } from 'react';
import { AbrovaTrace } from '@abrova-trace/nextjs-sdk';

export function Providers({ children }: { children: React.ReactNode }) {
  useEffect(() => {
    AbrovaTrace.init({
      apiKey: process.env.NEXT_PUBLIC_ABROVA_TRACE_KEY!,
      environment: process.env.NODE_ENV,
    });

    // Enable Web Vitals tracking
    AbrovaTrace.getInstance()?.enableWebVitals();

    // Enable HTTP performance tracking
    AbrovaTrace.getInstance()?.enablePerformanceTracking();

    return () => AbrovaTrace.getInstance()?.close();
  }, []);

  return <>{children}</>;
}
```

#### Pages Router

```tsx
// pages/_app.tsx
import { useEffect } from 'react';
import { AbrovaTrace } from '@abrova-trace/nextjs-sdk';

function MyApp({ Component, pageProps }) {
  useEffect(() => {
    AbrovaTrace.init({
      apiKey: process.env.NEXT_PUBLIC_ABROVA_TRACE_KEY!,
      environment: process.env.NODE_ENV,
    });

    AbrovaTrace.getInstance()?.enableWebVitals();
    AbrovaTrace.getInstance()?.enablePerformanceTracking();

    return () => AbrovaTrace.getInstance()?.close();
  }, []);

  return <Component {...pageProps} />;
}

export default MyApp;
```

#### Advanced Options

```typescript
// Report all metric changes (not just final values)
AbrovaTrace.getInstance()?.enableWebVitals({
  reportAllChanges: true,
});

// Custom batch interval (default: 5000ms): vitals are sent this long after
// the last metric arrives, and also when the page is hidden or unloaded
AbrovaTrace.getInstance()?.enableWebVitals({
  batchInterval: 10000, // 10 seconds
});
```

<H2 id="data-structure" step={2}>Data Structure</H2>

Web Vitals data is reported with the following structure:

```typescript
interface WebVitalsData {
  pageUrl: string;           // Full page URL
  pageRoute?: string;        // Route path (e.g., /dashboard)

  // Core Web Vitals
  lcpMs?: number;            // Largest Contentful Paint
  cls?: number;              // Cumulative Layout Shift
  inpMs?: number;            // Interaction to Next Paint
  ttfbMs?: number;           // Time to First Byte
  fcpMs?: number;            // First Contentful Paint

  // Context
  deviceType?: string;       // 'mobile' | 'tablet' | 'desktop'
  connectionType?: string;   // from Navigator API (4g, 3g, etc.)
  sessionId?: string;        // Per page-load ID from the Web Vitals tracker (not getSessionId())
  platform: 'nextjs';
  environment?: string;      // production, staging
  releaseVersion?: string;   // App version
}
```

<H2 id="dashboard-view" step={3}>Dashboard View</H2>

In Abrova Console, **Abrova Trace → Performance** shows Web Vitals in a dedicated card: the 75th percentile (p75) of each metric over the selected period, rated Good / Needs improvement / Poor with the thresholds above.

<div>
  <h4>Core Web Vitals Card</h4>
  <div>
    {[
      ['LCP', '1.8s', 'Good', 'green'],
      ['INP', '120ms', 'Good', 'green'],
      ['CLS', '0.15', 'Needs improvement', 'yellow'],
      ['FCP', '1.2s', 'Good', 'green'],
    ].map(([name, value, status, color]) => (
      <div key={name}>
        <div>{name}</div>
        <div>{value}</div>
        <div>{status}</div>
      </div>
    ))}
  </div>
</div>

<H2 id="improving-your-scores" step={4}>Improving Your Scores</H2>

<div>
  <div>
    <h4>Improve LCP</h4>
    <ul>
      <li>&#8226; Optimize and compress images</li>
      <li>&#8226; Use a CDN for static assets</li>
      <li>&#8226; Preload critical resources</li>
      <li>&#8226; Minimize render-blocking JavaScript</li>
    </ul>
  </div>
  <div>
    <h4>Improve INP</h4>
    <ul>
      <li>&#8226; Break up long JavaScript tasks</li>
      <li>&#8226; Use web workers for heavy computation</li>
      <li>&#8226; Optimize event handlers</li>
      <li>&#8226; Defer non-critical JavaScript</li>
    </ul>
  </div>
  <div>
    <h4>Improve CLS</h4>
    <ul>
      <li>&#8226; Always include size attributes on images</li>
      <li>&#8226; Reserve space for dynamic content</li>
      <li>&#8226; Avoid inserting content above existing content</li>
      <li>&#8226; Use transform animations instead of layout changes</li>
    </ul>
  </div>
</div>

### Best Practices

<BestPracticeList items={[
  ['Enable Early', 'Enable Web Vitals tracking as early as possible in your app lifecycle for accurate measurements'],
  ['Use Production Data', 'Web Vitals are most meaningful from real production users — development data may be skewed'],
  ['Monitor by Route', 'Track Web Vitals per route/page to identify which pages need optimization'],
  ['Track Over Time', 'Use the dashboard trends to see how deployments affect performance'],
  ['Focus on INP', 'INP is the Core Web Vital for interactivity — prioritize improving responsiveness'],
  ['Set Realistic Goals', 'Aim for "Good" thresholds on 75th percentile of page loads'],
]} />

- Performance score: https://abrova.ir/en/docs/trace/performance-score

Your application's Core Web Vitals health is shown in the **Web Vitals** card on **Trace → Performance**. Each vital is summarised by its **p75** across the selected time range and rated **Good**, **Needs improvement** or **Poor** against Google's standard thresholds, so you can spot regressions at a glance.

<Callout kind="note" title="No Single Combined Score">
  Abrova Console does not currently combine the vitals into one 0–100 score. Read the per-vital ratings instead — the worst-rated vital is where to start.
</Callout>

<Callout kind="note" title="Browser Only">
  Web Vitals are browser-specific and come from the browser SDK (call `enableWebVitals()` in the Next.js / web SDK). Mobile and backend SDKs report request latency only, so for non-web projects the card shows "Web Vitals need the browser SDK".
</Callout>

### How Vitals Are Rated

Each vital's p75 is compared with Google's standard thresholds: at or below **Good** is Good, above **Poor** is Poor, anything in between is Needs improvement.

<div>
  <table>
    <thead>
      <tr>
        {['Metric', 'Name', 'Good', 'Poor'].map((h) => (
          <th key={h}>{h}</th>
        ))}
      </tr>
    </thead>
    <tbody>
      {[
        ['LCP', 'Largest Contentful Paint', '≤2.5s', '>4s'],
        ['INP', 'Interaction to Next Paint', '≤200ms', '>500ms'],
        ['CLS', 'Cumulative Layout Shift', '≤0.1', '>0.25'],
        ['FCP', 'First Contentful Paint', '≤1.8s', '>3s'],
        ['TTFB', 'Time to First Byte', '≤800ms', '>1.8s'],
      ].map(([metric, weight, good, poor]) => (
        <tr key={metric}>
          <td>{metric}</td>
          <td>{weight}</td>
          <td>{good}</td>
          <td>{poor}</td>
        </tr>
      ))}
    </tbody>
  </table>
</div>

Vitals that haven't reported yet are not shown.

### Rating Bands

<BestPracticeList columns={3} items={[
  ['Good', 'Healthy. Most page loads meet the threshold'],
  ['Needs Improvement', 'Mixed. Investigate this vital and ship a targeted fix'],
  ['Poor', 'Many page loads fail this vital. SEO + retention at risk'],
]} />

### What You See in the Dashboard

The Web Vitals card on the Performance page shows:

- **Header** — "p75 · N page loads · browser SDK only"
- **Per-metric breakdown** — every reported vital with its p75 value, rating icon and label
- **Good / Needs improvement / Poor split** — how the individual page loads for each vital were rated

### Reading the Breakdown

The breakdown rows tell you *what* is off. Rows look like:

```
LCP   2840ms   ● Needs improvement
INP   190ms    ● Good
CLS   0.08     ● Good
FCP   1650ms   ● Good
TTFB  720ms    ● Good
```

Scan the rating icons: fix Poor rows first, then Needs improvement.

### Best Practices

<BestPracticeList items={[
  ['Track Vitals Over Time', 'Use the time-range selector to compare 1h vs 24h vs 7d — a sudden change usually pins down to a deploy'],
  ['Fix the Worst Vital First', 'Moving one Poor vital to Good helps users more than polishing a vital that is already Good'],
  ['Compare by Release', 'Set a release version in your SDK init and use the Release filter so you can attribute regressions to specific deploys'],
  ['Pair With Request Latency', 'Web Vitals cover frontend rendering. The Latency and Operations cards cover request latency. Together they give a full UX picture'],
]} />

- Apdex score: https://abrova.ir/en/docs/trace/apdex

Apdex (**Application Performance Index**) is an industry-standard KPI that condenses latency into a single number between **0.00 and 1.00**. Unlike percentiles, it tells you what fraction of your users were actually *happy* with response times — not just how slow the slow tail was. AbrovaTrace calculates it across every performance span in the selected time range.

<Callout kind="note" title="Backend Latency, Not Web Vitals">
  Apdex measures request duration, complementary to Web Vitals (which measure frontend rendering). Use both side-by-side for a full UX picture.
</Callout>

### How It's Calculated

Every span is bucketed against a target latency **T** (`T = 500ms`):

<div>
  <table>
    <thead>
      <tr>
        {['Bucket', 'Range', 'Weight', 'Meaning'].map((h) => (
          <th key={h}>{h}</th>
        ))}
      </tr>
    </thead>
    <tbody>
      {[
        ['Satisfied', 'duration ≤ T (≤500ms)', '1.0', 'User got an instant response'],
        ['Tolerating', 'T < duration ≤ 4T (500ms-2s)', '0.5', 'Slow but usable'],
        ['Frustrated', 'duration > 4T (>2s)', '0.0', 'User likely abandoned or retried'],
      ].map(([bucket, range, weight, meaning]) => (
        <tr key={bucket}>
          <td>{bucket}</td>
          <td>{range}</td>
          <td>{weight}</td>
          <td>{meaning}</td>
        </tr>
      ))}
    </tbody>
  </table>
</div>

The score is then:

```
Apdex = (satisfied + tolerating × 0.5) / total
```

### Score Bands (Guidance)

<BestPracticeList columns={4} items={[
  ['0.94-1.00 Excellent', 'Industry-grade. Users barely notice latency'],
  ['0.85-0.94 Good', 'Healthy. Most teams target this band as a baseline'],
  ['0.70-0.85 Fair', 'Visible friction. Tail latency needs work'],
  ['<0.70 Poor', 'Significant share of requests frustrating users — investigate now'],
]} />

### Why Apdex (Not Just p95)?

Percentiles answer "how slow is the slow tail?" — Apdex answers "how many users had a bad experience?" Two examples:

- **Service A** — p95 = 1.8s but p50 = 50ms. Apdex ≈ 0.93. Most users are happy; a slow tail exists.
- **Service B** — p95 = 1.8s and p50 = 1.7s. Apdex ≈ 0.51. *Half* the users are frustrated.

Same p95, very different user reality. Apdex catches the second case immediately.

### Reading the Score

Apdex follows the same time range, platform, environment and release filters as the rest of **Trace → Performance**. Alongside the score you get the satisfied, tolerating and frustrated request counts behind it. When there are no spans in the selected range, there is no score.

### Adjusting the Threshold

T is fixed at **500ms** because it matches the industry-standard web SLA for "feels instant." It can't be configured per project. If your workload is genuinely slower (e.g. ML inference, video transcode), the score will look pessimistic — focus on the **trend** of the score rather than its absolute value.

### Best Practices

<BestPracticeList items={[
  ['Watch the Score, Not the Threshold', 'Even with T=500ms not matching your SLA, the score trend is meaningful — a dropping Apdex means user experience is degrading'],
  ['Compare With Error Rate', 'High Apdex + high error rate = fast failures. Low Apdex + low error rate = slow successes. Both hurt UX differently'],
  ['Watch for Apdex Drops', 'Apdex moving from 0.94 to 0.85 is a smaller-looking change than p95 doubling, but it represents the same user pain. For alerting, use a p95 latency alert rule under Trace → Alerts'],
  ['Look at Operation-Level Latency', 'A site-wide Apdex of 0.92 can hide one endpoint stuck at 0.40. The Operations card on the Performance page shows per-operation p95 to drill in'],
]} />

- Platform breakdown: https://abrova.ir/en/docs/trace/platform-breakdown

Platform Breakdown shows how your performance data splits across SDKs — iOS, Android, web, Node, Flutter, Laravel — so you can quickly see *which* platform is driving traffic and *how it's performing relative to the rest*. AbrovaTrace groups every span by the `platform` field each SDK sets on its spans.

<Callout kind="note" title="Identifying Platform Regressions">
  If your app's overall p95 jumps after a release, Platform Breakdown is the fastest way to find whether it's the iOS update, the Android rollout, or the new web build dragging the number up.
</Callout>

### What You See in the Dashboard

On **Trace &rarr; Performance** in Abrova Console, use the **Platform** filter in the toolbar to narrow every card (stats, latency, operations, status codes, failed requests) to one platform. Switch between platforms to compare their request counts, latency and error rate side by side.

### How Platform Is Detected

The `platform` field is set by the SDK on every span it reports:

<div>
  <table>
    <thead>
      <tr>
        {['SDK', 'Reported Platform', 'Source'].map((h) => (
          <th key={h}>{h}</th>
        ))}
      </tr>
    </thead>
    <tbody>
      {[
        ['Next.js / Web', 'nextjs', 'Fixed by the SDK'],
        ['Flutter', 'flutter_android / flutter_ios / flutter_web_* …', 'Detected at runtime via AbrovaTrace.createPerformanceClient / trackOperation; a standalone PerformanceHttpClient reports flutter (or web) unless you pass platform, and spans you build yourself for reportPerformanceSpan carry only the platform you set'],
        ['Android', 'android', 'Fixed by the SDK'],
        ['iOS', 'ios', 'Fixed by the SDK'],
        ['Node.js', 'nodejs', 'Fixed by the SDK'],
        ['Laravel', 'laravel', 'Fixed by the SDK'],
      ].map(([sdk, platform, source]) => (
        <tr key={sdk}>
          <td>{sdk}</td>
          <td>{platform}</td>
          <td>{source}</td>
        </tr>
      ))}
    </tbody>
  </table>
</div>

If a span arrives without a platform tag (custom span, legacy SDK, etc.), it falls into the **"unknown"** bucket.

### Separating Products

There is no init option to override the platform. If one project ingests both your customer web app and your admin panel, tell them apart with a distinct `environment` (a Performance filter), or with tags on the spans you report yourself:

```typescript
AbrovaTrace.init({
  apiKey: 'ab_live_your_api_key',
  environment: 'production-admin',
});

await AbrovaTrace.getInstance()?.trackOperation('loadReport', loadReport, {
  tags: { app: 'web-admin' },
});
```

### Best Practices

<BestPracticeList items={[
  ['Watch the Largest Slice', 'The biggest slice is usually where regressions hide simply because it has the most samples. Compare its p95 to the others'],
  ['Tag Multi-Product Projects', 'If one project ingests an admin tool + a customer app, give each its own environment so you can filter them apart'],
  ['Look at "unknown" Spikes', 'A sudden growth in the unknown bucket usually means a new SDK version is missing a platform tag — worth investigating'],
  ['Compare Mobile vs Web', 'Mobile traffic is typically chattier (background sync) while web traffic is bursty. The ratio is healthy when it matches your active-user mix'],
]} />

- Top hosts: https://abrova.ir/en/docs/trace/top-hosts

Top Hosts shows which external hostnames your app talks to most frequently — your own APIs, third-party services such as payment gateways and SMS providers, CDNs, analytics endpoints. Each host is ranked by request volume and shows p95 latency + error count so you can instantly spot a misbehaving third-party that's silently dragging your UX down.

<Callout kind="note" title="Outbound HTTP Only">
  Only outbound HTTP requests appear here. Database queries, custom operations, and cache spans don't appear here.
</Callout>

### What You See

For each host:

- **Host** — e.g. `api.payments.example.com`, `cdn.example.com`
- **Requests** — total for the selected time range (hosts are ranked by this)
- **Average** and **p95** latency, in milliseconds
- **Errors** — requests that returned HTTP 400 or higher

To drill into slow or failing outbound calls, use the **Operations** and **Failed requests** cards on **Trace → Performance** in Abrova Console.

### What Counts as a Host

The host is automatically extracted from the request URL by every official SDK. For example, a request to `https://api.payments.example.com/v1/charges` is bucketed under `api.payments.example.com`. Path differences don't matter at this level — that's what [URL Performance](/docs/trace/url-performance) is for.

### Common Patterns to Watch

<BestPracticeList columns={2} items={[
  ['One Host Dominates', 'Healthy if it\'s your own API. Suspicious if it\'s a third-party — could mean retry storm or over-eager polling'],
  ['Slow Third-Party Host', 'A 1.5s p95 from a payments or auth host means your checkout / login is gated on it. Cache or async if possible'],
  ['Sudden New Host Appears', 'Usually a new feature shipped that calls an unfamiliar service. Verify it\'s expected — could be a misconfigured SDK'],
  ['CDN Has Errors', 'A small error count from your CDN often signals regional outages users will report before you notice from logs'],
]} />

### Real-World Use Case

A common scenario: your app's overall p95 spikes from 300ms to 1.1s overnight. The latency chart confirms it, but the Operations card looks normal — every operation is similarly slow. Top Hosts immediately reveals the culprit: `api.thirdparty.com` p95 jumped from 200ms to 2.4s. *Their* incident is now *your* incident — but at least you know it's not your code, and you can mitigate (cache, async, fallback) rather than chase a ghost.

### Best Practices

<BestPracticeList items={[
  ['Treat Third-Party Hosts as SLOs', 'Track their p95 like you track your own. A slow payment gateway or SMS provider is your problem the moment users notice'],
  ['Cross-Reference with Failed Requests', 'Top Hosts shows aggregate health; Failed Requests shows specific failures. Use both together'],
  ['Pre-Connect to Slow Hosts', 'For hosts with consistent high TTFB but low p95, a <link rel="preconnect"> can save 100-200ms on the first call'],
  ['Watch for New Hosts', 'A brand-new host appearing near the top of the list is usually either a planned launch or an exfiltration risk — verify either way'],
]} />

- URL performance: https://abrova.ir/en/docs/trace/url-performance

URL Performance is a per-URL latency table that groups requests by their **full HTTP URL** (not by logical operation name). It complements the **Operations** card ([API Latency](/docs/trace/api-latency)) — operations aggregate by operation (`GET /users/:id`), URLs aggregate by what the user's browser actually fetched (`/users/4710`). Use this when you need to know *which specific pages* are slow, not just which routes.

<Callout kind="note" title="When to Use This vs Operations">
  Use Operations when looking at backend routes (parameterised paths). Use URL Performance when looking at per-page client-side calls or when you don't have a route template at all (e.g. static assets, third-party calls).
</Callout>

### What the Data Contains

Each row has:

<div>
  <table>
    <thead>
      <tr>
        {['Column', 'Description'].map((h) => (
          <th key={h}>{h}</th>
        ))}
      </tr>
    </thead>
    <tbody>
      {[
        ['method', 'HTTP method (GET, POST, PUT, PATCH, DELETE…)'],
        ['url', 'The full request URL'],
        ['request_count', 'Total request count for this URL in the selected time range'],
        ['avg_duration', 'Mean duration (ms) — coarse but useful when paired with p95'],
        ['p50', 'Median — what a typical user experienced'],
        ['p95', 'Slow tail — the 5% slowest. Most user-facing pain lives here'],
        ['max_duration', 'The single slowest request in the window — outlier detection'],
        ['error_count', 'Number of responses with HTTP status 400 or higher'],
      ].map(([col, desc]) => (
        <tr key={col}>
          <td>{col}</td>
          <td>{desc}</td>
        </tr>
      ))}
    </tbody>
  </table>
</div>

Rows are sorted by **p95 descending** — the slowest tails surface to the top.

### URL vs Operation Explained

The distinction matters when reading the table:

- **Operation** is a logical route template — `GET /api/users/:id` is one row in Operations regardless of which user ID was hit.
- **URL** is the literal string the SDK saw — `https://api.example.com/users/4710` and `/users/4711` are two different rows here.

If your backend has high-cardinality URLs (every user ID is its own row), URL Performance can get noisy fast. That's by design — it tells you *which specific users / records / pages* are slow. For aggregate route-level monitoring, prefer Operations.

### Common Patterns to Watch

<BestPracticeList columns={2} items={[
  ['One URL Dominates the Tail', 'A single hot URL with p95 well above the rest is usually a specific record causing an N+1 query or a hot row'],
  ['Many URLs, Same Pattern', 'If GET /users/4710, /users/4711, /users/4712 all show up slow, the route itself is slow — drop to the Operations card'],
  ['High Max, Low p95', 'One catastrophic request hidden in healthy traffic — usually a runaway query or a rare cache miss. Worth tracing'],
  ['Static Asset URLs Slow', 'If .js / .css / .png URLs show high p95, your CDN cache hit rate is dropping. Check origin shielding'],
]} />

### Best Practices

<BestPracticeList items={[
  ['Pair With Operations', 'Operations answers "is this route slow on average?" URL Performance answers "which specific request was the slowest?"'],
  ['Normalise High-Cardinality URLs', 'If every user ID is its own URL the table gets long. When you report spans yourself, give them a route-template operation name (e.g. GET /users/:id) so Operations aggregates them — http_url still keeps the raw path'],
  ['Cross-Check Failed Requests', 'Look up a slow URL in the Failed requests card to see specific failure cases'],
  ['Use Max as a Trace Trigger', 'A single Max of 8+ seconds is worth tracing in detail — often surfaces a bug that p95 alone would miss'],
  ['Sort Mentally by Volume × p95', 'A URL with 10,000 requests at 300ms p95 affects users more than one at 50 requests with 1.5s p95. Both matter — weigh by reach'],
]} />

- Error dashboard: https://abrova.ir/en/docs/trace/error-dashboard

The AbrovaTrace error dashboard is the **Trace → Issues** page in Abrova Console. It shows grouped errors from every platform of your project, with powerful filtering, status management, and detailed error context.

<div>
  {[['Real-time Tracking', 'Errors are grouped into issues as soon as they arrive'], ['Powerful Filtering', 'Filter by status, frequency, time range, platform, environment, release and text'], ['Status Management', 'Track errors from discovery to resolution']].map(([t, d]) => (
    <div key={t}>
      <strong>{t}</strong>
      <p>{d}</p>
    </div>
  ))}
</div>

### Dashboard Components

#### Status Tabs

Each status tab shows how many issues it holds:

<div>
  {[
    { label: 'Open', value: '12', color: 'text-red-600' },
    { label: 'In progress', value: '3', color: 'text-zinc-50' },
    { label: 'Resolved', value: '15', color: 'text-emerald-400' },
    { label: 'All', value: '247', color: 'text-zinc-50' },
  ].map((s) => (
    <div key={s.label}>
      <p>{s.value}</p>
      <p>{s.label}</p>
    </div>
  ))}
</div>

#### Filters

- **Status:** Open (default), In progress, Resolved, Ignored, Archived, All
- **Frequency:** 1–10, 11–50, 51–100, 100+ events
- **Time Range:** 1 hour, 24 hours, 7 days, 30 days (default), or a custom range
- **Platform, Environment, Release**

#### Error List

Each issue in the list shows its platform, error message, status, event count and when it was last seen. Switch between the **list** and **timeline** views.

### Error Detail View

Click any error to see its full details:

- **Error Message & Stack Trace** — Full stack trace (deobfuscated when source maps or dSYMs are uploaded)
- **Breadcrumbs Timeline** — Sequence of events leading to the error
- **Extra Context Data** — Custom data attached via the extra parameter
- **Environment Information** — Platform, OS, browser, release version
- **Occurrence Statistics** — First seen, last seen, total count, and status history

### Status Management

<div>
  {[
    ['Open', 'New error needing attention', 'bg-blue-900/20 text-blue-300'],
    ['In Progress', 'Being investigated or fixed', 'bg-yellow-900/20 text-yellow-300'],
    ['Resolved', 'Fix deployed', 'bg-green-900/20 text-green-300'],
    ['Archived', 'Closed, no longer active', 'bg-zinc-800 bg-zinc-700 text-zinc-400'],
    ['Ignored', "Known issue, won't fix", 'bg-zinc-800 bg-zinc-700 text-zinc-400'],
  ].map(([status, desc, cls]) => (
    <div key={status}>
      <span>{status}</span>
      <span>{desc}</span>
    </div>
  ))}
</div>

**Bulk Updates:** Select multiple issues to resolve, mark in progress, ignore, archive or reopen them at once, or resolve every open issue from the **⋯** menu. Changing status needs the member role or higher; deleting issues needs admin or owner — see [Roles & Permissions](/docs/trace/error-dashboard#roles).

<div id="roles" />

### Roles & Permissions

What you can do in Abrova Trace depends on your role. Roles are given in Abrova Console (organisation and project settings); Abrova Trace has no separate role list. Each role includes everything of the one above it.

<ConfigTable headers={['Role', 'Level', 'What it can do in Abrova Trace']} rows={[
  ['Viewer', 'Read', 'See everything in the project: issues and their history, messages, logs and saved searches, performance, ignore rules, alert rules and their events, cron monitors and check-ins, containers and their stats, integrations and their delivery log, uploaded source maps and debug symbols'],
  ['Member', 'Triage', 'Change issue status (one issue, several at once, or "Resolve all open issues"); acknowledge, mute and unmute alerts; save log searches and edit or delete the ones they saved; upload source maps and debug symbols (dSYM)'],
  ['Admin', 'Manage', 'Delete data (issues, messages, logs and log sources, deploy markers, performance data, uploaded source maps and debug symbols); create, edit, switch on/off and delete ignore rules, alert rules and cron monitors; add, edit, switch on/off, delete and test integrations; start, stop, restart and remove containers; edit or delete any saved log search; project-level changes'],
  ['Owner', 'Manage', 'Everything an admin can. The Danger zone in Trace → Settings (delete all data of one kind) is shown to owners only'],
]} />

- **You only see your projects.** Members and viewers see the projects they are assigned to; other projects of the organisation do not appear in Abrova Trace for them.
- **Added to one project only?** Someone added to a single project without a role in the organisation is read-only there, like a viewer.
- **Refused actions.** Controls you cannot use are shown disabled. If a request needs a higher role, the API answers `403` with `"code": "forbidden_role"`.
- **Apps and servers are separate.** Roles apply to people using the dashboard. SDKs, the log agent and cron check-ins authenticate with the project's keys — see [Server Secret & Server Routes](/docs/trace/server-secret).

### Free Allowance and Wallet

Abrova Trace counts **error events per month** for your organisation: every error it receives, repeats of a known issue included. On screen, the events of one cause are grouped into one issue, so the list stays readable.

Every month **50,000 error events are free**. Above that, each started **1,000 events costs 3,000 Toman**, deducted once a day from your organisation's prepaid wallet — see [Pricing](/pricing). There is no subscription. On the free plan, up to **1,000 new issues** a month are also stored.

When the free amount is used up and the wallet has no balance (pay as you go stays on for 3 more days after the balance reaches zero):

- **New events are not stored** until the free amount resets at the start of the next month, or until you top up the wallet.
- **Nothing already stored is deleted.**
- **Your apps are never disturbed.** The API still answers success (`200`), with a body that says the event was not stored, so no SDK retries, queues or logs an error:

```json
{
  "status": "dropped",
  "code": "plan_limit_reached",
  "metric": "error_events_monthly",
  "limit": 50000,
  "used": 50000,
  "resets_at": "2026-11-01T00:00:00.000Z"
}
```

(`limit` and `used` are example values; they show your organisation's free amount and use this month.)

Performance monitoring (spans and Web Vitals) is part of pay as you go and does not count as error events.

### Search & Filtering

- **Text Search** — Search across error messages, platform, and environment
- **Combined Filters** — Combine status, frequency, time range, platform, environment, release and text search
- **Pagination** — Navigate through large error lists efficiently

### Best Practices

<BestPracticeList items={[
  ['Check Daily', 'Review new errors at least once a day to catch issues early'],
  ['Prioritize by Frequency', 'Focus on issues with the most events (100+ and 51–100) first'],
  ['Update Status Regularly', 'Keep error statuses up to date for team visibility'],
  ['Monitor Trends', 'Use the timeline view and the Overview page to spot spikes or patterns'],
  ['Use Breadcrumbs', 'Review breadcrumbs to understand the user journey before the error'],
]} />

- Stack traces & source maps: https://abrova.ir/en/docs/trace/stack-traces

Stack traces show the exact sequence of function calls leading to an error — revealing **WHERE** it happened, **HOW** the code got there, and **WHAT** functions were called.

### Automatic Stack Trace Capture

No additional configuration needed. AbrovaTrace automatically captures stack traces from:

- Uncaught exceptions (with `captureUncaughtErrors: true`)
- Manual exception captures (with `captureException()`)
- Async errors (with `initWithZone()`)
- Platform exceptions from native code

```dart
try {
  await riskyOperation();
} catch (e, stackTrace) {
  await AbrovaTrace.captureException(
    e,
    stackTrace: stackTrace, // Always include this!
    message: 'Operation failed',
    extra: {'user_id': 'user_123'},
  );
}
```

### Reading Stack Traces

<div>
  <p>Exception: FormatException: Invalid input</p>
  <p>{"  "}at Parser.parse (lib/parser.dart:42:15) {'←'} <span>where error occurred</span></p>
  <p>{"  "}at DataService.process (lib/data_service.dart:108:8)</p>
  <p>{"  "}at HomeScreen.loadData (lib/screens/home.dart:55:12)</p>
  <p>{"  "}at _HomeScreenState.initState (lib/screens/home.dart:23:5)</p>
</div>

- **Top line:** Where the error occurred
- **Following lines:** The call stack (how the code got there)
- **File paths & line numbers:** Help locate the exact issue

### Platform-Specific Stack Traces

<div>
  {[
    ['Flutter Mobile', 'Full Dart stacks with line numbers and method names preserved'],
    ['Flutter Web', 'JavaScript error stacks with browser info — may need source maps for readability'],
    ['Flutter Desktop', 'Full debug info with complete stacks and platform details'],
    ['Chrome Extension', 'Extension context info with Chrome version, background/popup context'],
  ].map(([platform, desc]) => (
    <div key={platform}>
      <strong>{platform}</strong>
      <p>{desc}</p>
    </div>
  ))}
</div>

### Adding Context to Stack Traces

```dart
try {
  await processPayment(orderId, amount);
} catch (e, stackTrace) {
  await AbrovaTrace.captureException(
    e,
    stackTrace: stackTrace,
    message: 'Payment processing failed',
    extra: {
      'order_id': orderId,
      'amount': amount,
      'payment_method': paymentMethod,
    },
  );
}
```

### Native Crash Stack Traces

Native crashes are detected on the next app launch. When a crash kills the app, it can't report in real-time — so AbrovaTrace detects it on restart.

<Callout kind="note" title="Important">Native crash capture is installed when you initialize the SDK (<code>AbrovaTrace.initWithZone()</code> or <code>AbrovaTrace.init()</code>) — no extra call is needed. <code>AbrovaTrace.close()</code> only flushes pending data and shuts the SDK down.</Callout>

### Uploading Source Maps

For web platforms (Next.js, Flutter Web), upload `.map` files so production stack traces resolve to your original source files and line numbers.

#### Where to upload

- **Abrova Console** — at `console.abrova.ir` &rarr; your project &rarr; **Trace &rarr; Source maps &amp; symbols**. Set the release version and upload your `.map` files (several in one go).
- **Abrova CLI** — upload from your build or CI with `abrova-trace sourcemaps upload`. See [Upload Source Maps](/docs/trace/upload-source-maps).
- The Abrova [desktop app](/desktop) will offer the same upload when it launches (coming soon).

The release version must match the `release` field you pass to the SDK at init — that's how the backend pairs the right map with each error.

Uploading needs the member role or higher; deleting uploaded files needs admin or owner. See [Roles & Permissions](/docs/trace/error-dashboard#roles).

#### Next.js

```javascript
// next.config.js
module.exports = {
  productionBrowserSourceMaps: true,
};
```

After `next build`, you'll find the `.map` files next to the chunks under `.next/static/chunks/`. Up to 500 `.map` files are accepted per upload, so you can drop them all at once (non-`.map` files are skipped).

#### Flutter Web

Build with source maps enabled, then upload the single `main.dart.js.map`:

```bash
flutter build web --source-maps
```

The map will be at `build/web/main.dart.js.map`.

<Callout kind="note" title="Flutter Web — what to expect from resolved traces">
  <p>
    dart2js (the compiler that turns Dart into JavaScript) inlines aggressively in <code>--release</code> builds. Some frames will resolve cleanly to your <code>.dart</code> files. Others will resolve to framework internals (<code>js_helper.dart</code>, <code>dart:async</code>) or stay minified (<code>a3v.$0</code>) because the <code>.map</code> simply contains no mapping for those JS bytes.
  </p>
  <p>
    This is a property of dart2js output — not the resolver. We tell you up front because most teams hit it in production and assume their setup is broken. It isn't.
  </p>
  <p>
    <strong>Where Abrova pulls ahead is context.</strong> Enable gesture breadcrumbs (<code>AbrovaTrace.enableGestureBreadcrumbs()</code>) so every issue shows the widget the user tapped right before the error, plus the route, last HTTP call, and any custom breadcrumbs. Combined with the partially-resolved trace, you get a reproducible bug report.
  </p>
  <p><strong>For QA / staging only</strong>, you can force less aggressive optimization to get fully resolved traces:</p>
  <CodeBlock language="bash" code={`flutter build web --source-maps --dart2js-optimization=O1`} />
  <p>Bundle size grows ~30% — fine for staging, not recommended for production.</p>
</Callout>

### Best Practices

<BestPracticeList items={[
  ['Always Include Stack Traces', 'Pass the stackTrace parameter when manually capturing exceptions'],
  ['Add Meaningful Context', 'Include user IDs, screen names, and relevant data in the extra field'],
  ['Use Release Versions', 'Set the release version to correlate errors with deployments'],
  ['Combine with Breadcrumbs', 'Breadcrumbs show what user did, stack traces show where code failed'],
  ['Test in Development', 'Enable debug: true to see stack traces in console during development'],
]} />

- Upload source maps (CLI): https://abrova.ir/en/docs/trace/upload-source-maps

The `@abrova-trace/cli` uploads sourcemaps from your CI/CD pipeline to Abrova Trace. Any error captured **after** the upload will be shown with real source file names and line numbers in the dashboard — no more minified `4d240bf7.js:1:16945` stacks.

<Callout kind="note" title="When do you need this?">
  <p>
    Anytime you ship a production build with minification (Next.js, Vite, webpack, Rollup).
    Without uploaded sourcemaps, every error in the Abrova Trace dashboard shows the minified stack — useless for debugging.
  </p>
</Callout>

<H2 id="prerequisites" step={1}>Prerequisites</H2>

You need three things:

- **Node.js 18+** on the machine that runs the upload (your CI runner or local dev machine)
- **A personal access token** with the `sourcemaps:write` scope
- **Your project DSN** from Trace → Source maps & symbols in Abrova Console

<H2 id="install-the-cli" step={2}>Install the CLI</H2>

The CLI comes from Abrova Center. Add the registry once, then install it as a dev dependency:

```bash
# .npmrc (in your project root)
@abrova-trace:registry=https://center.abrova.ir/api/packages/abrova/npm/
```

```bash
npm install --save-dev @abrova-trace/cli
```

Run it from your project with `npx abrova-trace` (for example `npx abrova-trace --help`). The command name is `abrova-trace`.

<H2 id="create-a-personal-access-token" step={3}>Create a Personal Access Token</H2>

Personal Access Tokens (PATs) are user-scoped, long-lived credentials — the same pattern many developer CLIs use. They replace user session tokens for automated workflows.

1. Open the Abrova Console: **[Account → Personal Access Tokens](https://console.abrova.ir/dashboard/account/tokens)**
2. Click **New Token**
3. Give it a name (e.g. `CI upload — production`)
4. Enable the **`sourcemaps:write`** scope
5. Choose an expiration (no expiration is fine for CI; 90 days is a common compromise)
6. Click **Create Token**
7. **Copy the `ab_pat_xxx` value immediately** — it will only be shown once

Store this in your CI environment as a secret named `ABROVA_TRACE_TOKEN`.

<Callout kind="note" title="Token security">
  <ul>
    <li>Tokens are stored hashed on our side — we cannot recover a lost token, only revoke and reissue.</li>
    <li>The token IS the credential — anyone with it can upload sourcemaps to any of your projects.</li>
    <li>Revoke instantly from the same page if it leaks. All CLI/CI jobs using it stop working immediately.</li>
    <li>Never commit tokens to git. Use your CI provider's secrets (GitHub Actions Secrets, GitLab CI variables, etc.).</li>
  </ul>
</Callout>

<H2 id="find-your-project-id" step={4}>Find Your Project ID</H2>

The CLI's "project ID" is the **project DSN** of the web platform the maps belong to (each platform of an Abrova project has its own DSN).

1. Open Abrova Console and select your project
2. Go to **Trace → Source maps & symbols** (the **Source maps** tab)
3. In the **Upload from CI** card, pick the web platform if your project has more than one, then copy **Project DSN for the CLI**

Store this as `ABROVA_TRACE_PROJECT` in your CI environment (the CLI also still reads the legacy `ABROVA_TRACE_DSN` variable).

<H2 id="upload-from-ci" step={5}>Upload from CI</H2>

Add these two lines to your build pipeline **right after your production build** creates the sourcemap files:

```bash
export ABROVA_TRACE_TOKEN=ab_pat_xxx
export ABROVA_TRACE_PROJECT=<your-project-id>

npx abrova-trace sourcemaps upload ./path/to/your/sourcemaps \
  --release "1.2.3"
```

That's it. The CLI recursively finds every `.map` file under the given directory, uploads them all in a single request, and tags them with the release version so Abrova Trace can match them to errors from that version.

<H2 id="example-upload-next-js-source-maps" step={6}>Example: Upload Next.js Source Maps</H2>

For Next.js, enable sourcemap generation in `next.config.js`:

```js
module.exports = {
  productionBrowserSourceMaps: true,
};
```

Then in your CI script:

```bash
#!/bin/bash
set -e

# 1. Build with sourcemaps
npm run build

# 2. Copy sourcemaps into a dedicated folder
mkdir -p ./sourcemaps
find .next/static/chunks -name "*.js.map" -exec cp {} ./sourcemaps \;

# 3. Upload to Abrova Trace tagged with the release version
npx abrova-trace sourcemaps upload \
  --release "$NEXT_PUBLIC_APP_VERSION" \
  ./sourcemaps

# 4. Remove sourcemaps from the deployed build so browsers can't download them
#    (source stays private — Abrova keeps the maps server-side)
find .next/static/chunks -name "*.js.map" -delete
find .next/static/chunks -name "*.js" -exec \
  sed -i '/^\/\/# sourceMappingURL=/d' {} +
```

<H2 id="match-the-release-version" step={7}>Match the Release Version</H2>

The `--release` flag must match the version your SDK sends when reporting errors. If your Next.js SDK is initialised with:

```typescript
AbrovaTrace.init({
  apiKey: process.env.NEXT_PUBLIC_ABROVA_TRACE_API_KEY!,
  release: process.env.NEXT_PUBLIC_APP_VERSION, // e.g. "1.2.3"
});
```

Then upload with:

```bash
npx abrova-trace sourcemaps upload \
  --release "$NEXT_PUBLIC_APP_VERSION" \
  ./sourcemaps
```

If the release strings don't match, Abrova Trace won't find the sourcemap for the error and will fall back to showing the minified stack.

<Callout kind="note" title="Common cause of unresolved stacks">
  <p>
    "I uploaded sourcemaps but errors still show minified stacks."
  </p>
  <p>
    Usually the release string in the upload doesn't match what the SDK is sending. Check the Abrova Trace dashboard's error detail page for the release version, then re-upload with that exact string.
  </p>
</Callout>

<H2 id="cli-options" step={8}>CLI Options</H2>

<BestPracticeList columns={1} items={[
  ['--project <id>', 'Project DSN (or set ABROVA_TRACE_PROJECT env var). --dsn <id> is an alias'],
  ['--release <version>', 'Required. Release version this bundle belongs to'],
  ['--token <token>', 'Personal access token (or set ABROVA_TRACE_TOKEN env var)'],
  ['--api-url <url>', 'Base URL of the Trace API (or set ABROVA_TRACE_API_URL env var). Default: https://trace.abrova.ir'],
  ['--dry-run', 'Preview which files would be uploaded without sending them'],
]} />

A flag takes precedence over its environment variable. A project API key (`ab_live_…`) does not work here — the CLI needs a personal access token.

<H2 id="self-hosted-abrova-trace" step={9}>Self-Hosted Abrova Trace</H2>

<Callout kind="soon">Self-hosted Abrova Trace is coming soon. See [Self-Hosted](/docs/trace/self-hosted).</Callout>

When you run Abrova Trace on your own infrastructure, point the CLI at your API:

```bash
export ABROVA_TRACE_API_URL=https://trace.mycompany.com

npx abrova-trace sourcemaps upload \
  --release "1.2.3" \
  ./sourcemaps
```

The CLI does exactly the same thing against a self-hosted instance — no code changes, just the URL.

<H2 id="exit-codes" step={10}>Exit Codes</H2>

- **`0`** — success
- **`1`** — any error (invalid token, network failure, upload rejected, etc.)

Suitable for gating a deploy on successful upload:

```yaml
# .github/workflows/deploy.yml
- name: Upload sourcemaps
  run: npx abrova-trace sourcemaps upload --release "$GITHUB_SHA" ./sourcemaps
  env:
    ABROVA_TRACE_TOKEN: ${{ secrets.ABROVA_TRACE_TOKEN }}
    ABROVA_TRACE_PROJECT: ${{ secrets.ABROVA_TRACE_PROJECT }}

- name: Deploy
  run: ./deploy.sh
  # Deploy only runs if sourcemap upload succeeded
```

<H2 id="upload-limits" step={11}>Upload Limits</H2>

- **Max bundle size:** 110 MB per upload (whole multipart request)
- **Max file size:** 50 MB per individual `.map` file
- **Max files per upload:** 500

These are generous defaults that fit typical Next.js, Vite, and webpack builds. Larger files are rejected with HTTP 413. If your bundle exceeds 110 MB, split it into several uploads with the same `--release` (for example one folder at a time), or [contact us](/contact).

<H2 id="ios-dsyms" step={12}>iOS dSYMs</H2>

The CLI uploads JavaScript source maps only. iOS debug symbols (dSYMs) are uploaded in Abrova Console:

1. In Xcode, open **Organizer › Archives › Download Debug Symbols**, then zip the `.dSYM` folder
2. Open **Trace → Source maps & symbols** and choose the **iOS dSYMs** tab
3. Pick the release and drop the `.zip` file (one `.zip` per upload, up to 10 MB)

Uploading needs the member role or higher; deleting uploaded files needs admin or owner — see [Roles & Permissions](/docs/trace/error-dashboard#roles).

<H2 id="troubleshooting" step={13}>Troubleshooting</H2>

<BestPracticeList columns={1} items={[
  ['HTTP 401: Invalid token', 'Token missing, expired, revoked, or missing the sourcemaps:write scope. Create a new one at Account → Personal Access Tokens.'],
  ['HTTP 404: Project not found', 'The project ID does not exist or your token owner does not have access to it. Copy it again from Trace → Source maps & symbols (Project DSN for the CLI).'],
  ['HTTP 413: Content Too Large', 'Bundle exceeds 110 MB, or one .map file exceeds 50 MB. Split into smaller uploads or contact us.'],
  ['Errors still show minified stacks', 'Release string mismatch. The --release value must match what your SDK sends. Check the error detail page in the dashboard.'],
  ['No .map files found', 'Sourcemaps were not generated by the build. For Next.js, set productionBrowserSourceMaps: true in next.config.js.'],
]} />

- Error grouping: https://abrova.ir/en/docs/trace/error-grouping

Error grouping automatically combines identical errors into single groups — instead of seeing 1,000 individual errors for the same bug, you see one error with a count of 1,000. This reduces noise and helps you focus on unique issues.

<div>
  {[['Reduces Noise', 'Identical errors grouped together'], ['Tracks Frequency', 'See occurrence count and trends'], ['Automatic', 'No configuration needed']].map(([t, d]) => (
    <div key={t}>
      <strong>{t}</strong>
      <p>{d}</p>
    </div>
  ))}
</div>

### How errors are grouped

Errors with the same message, stack trace and platform are grouped into one issue. Any difference in the message or stack trace text starts a new issue.

### When Errors Are Grouped

<div>
  <div>
    <strong>Grouped Together</strong>
    <ul>
      <li>Same error in different user sessions</li>
      <li>Repeated error from same user</li>
      <li>Same error across environments and releases (if same platform)</li>
    </ul>
  </div>
  <div>
    <strong>NOT Grouped</strong>
    <ul>
      <li>Different error messages</li>
      <li>Different stack traces (even a changed line number)</li>
      <li>Different platforms (flutter_web vs flutter_android)</li>
    </ul>
  </div>
</div>

### Understanding Error Groups

Each group tracks:

<div>
  {[
    { label: 'Occurrences', value: '1,247' },
    { label: 'First Seen', value: '2025-11-10' },
    { label: 'Last Seen', value: '2025-11-12' },
    { label: 'Status', value: 'Open' },
  ].map((item) => (
    <div key={item.label}>
      <p>{item.value}</p>
      <p>{item.label}</p>
    </div>
  ))}
</div>

### Frequency Buckets

Each group is placed in a frequency bucket based on its event count (the Issues page's **Frequency** filter; the API calls this `severity`):

<div>
  <table>
    <thead>
      <tr>
        {['Frequency', 'Events', 'Color'].map((h) => (
          <th key={h}>{h}</th>
        ))}
      </tr>
    </thead>
    <tbody>
      {[
        ['Very frequent', '> 100', 'bg-red-900/30 text-red-400'],
        ['Frequent', '51 - 100', 'bg-orange-900/30 text-orange-300'],
        ['Recurring', '11 - 50', 'bg-yellow-900/30 text-yellow-300'],
        ['Rare', '1 - 10', 'bg-blue-900/30 text-blue-300'],
      ].map(([level, count, cls]) => (
        <tr key={level}>
          <td><span>{level}</span></td>
          <td>{count}</td>
          <td><div /></td>
        </tr>
      ))}
    </tbody>
  </table>
</div>

### Managing Error Groups

- **Status Management:** Open, In Progress, Resolved, Archived, Ignored
- **Bulk Operations:** Select several groups to change their status or delete them
- **Filtering:** Filter groups by status, frequency, time range, platform, environment, release, or search text

### Best Practices

<BestPracticeList items={[
  ['Focus on High-Count Errors First', 'Groups with 51+ events usually impact the most users'],
  ['Use Status Management', 'Keep error statuses updated for team coordination'],
  ['Monitor First/Last Seen', 'Track when errors appear and whether they recur after fixes (resolved groups are not reopened automatically)'],
  ['Use Release Versions', 'Correlate error groups with specific deployments'],
  ['Archive Old Errors', 'Archive issues you no longer expect to see to keep the dashboard clean'],
]} />

- Breadcrumbs: https://abrova.ir/en/docs/trace/breadcrumbs

Breadcrumbs are a trail of events that happened before an error occurred. They help you understand what the user was doing when things went wrong.

<div>
  <p><strong>Example journey:</strong></p>
  <div>
    {['User opened app', '→ Navigated to /checkout', '→ Clicked "Pay Now"', '→ \u{1F4A5} Payment failed'].map((step, i) => (
      <span key={i}>{step}</span>
    ))}
  </div>
</div>

### Flutter

#### Track Navigation Automatically

```dart
MaterialApp(
  navigatorObservers: [
    AbrovaTraceNavigatorObserver(), // Tracks all screen changes
  ],
  home: HomePage(),
)
```

#### Track Taps Automatically

One call enables breadcrumbs for every tap on a button, switch, list row, or any interactive widget — across Web, Android, iOS, macOS, Windows, and Linux. Each breadcrumb captures the widget type, label, optional `ValueKey`, current route, and tap coordinates.

```dart
// Call once after AbrovaTrace.init() and WidgetsFlutterBinding.ensureInitialized()
AbrovaTrace.enableGestureBreadcrumbs();
```

See the Flutter SDK page for the full list of recognized widgets, label-extraction order, and privacy notes.

### Add Manual Breadcrumbs

#### Flutter

```dart
// User action
AbrovaTrace.addBreadcrumb(
  'User clicked checkout button',
  type: BreadcrumbType.user,
  data: {'cart_items': 3, 'total': 49.99},
);

// HTTP request
AbrovaTrace.addBreadcrumb(
  'POST /api/orders',
  type: BreadcrumbType.http,
  data: {'status_code': 200, 'duration_ms': 150},
);

// Custom event
AbrovaTrace.addBreadcrumb(
  'Cache miss for user profile',
  type: BreadcrumbType.info,
  data: {'cache_key': 'user_123'},
);
```

#### Node.js

```javascript
const AbrovaTrace = require('@abrova-trace/nodejs-sdk');
const { Breadcrumb } = AbrovaTrace;

AbrovaTrace.addBreadcrumb(
  Breadcrumb.http('POST', '/api/login', 200, 150)
);

AbrovaTrace.addBreadcrumb(
  Breadcrumb.database('SELECT * FROM users WHERE id = ?', 25)
);

AbrovaTrace.addBreadcrumb(
  Breadcrumb.user('clicked_checkout_button', { cart_total: 99.99 })
);
```

#### Next.js

```tsx
import { useBreadcrumbs } from '@abrova-trace/nextjs-sdk/react';

const { addBreadcrumb, addHttp } = useBreadcrumbs();

addBreadcrumb('Form submitted', { formName: 'contact' });
addHttp('GET', '/api/users', 200, { duration_ms: 45 });
```

### Breadcrumb Types

<div>
  <table>
    <thead>
      <tr>
        {['Type', 'Description'].map((h) => (
          <th key={h}>{h}</th>
        ))}
      </tr>
    </thead>
    <tbody>
      {[
        ['BreadcrumbType.user', 'User actions (clicks, taps, swipes)'],
        ['BreadcrumbType.navigation', 'Screen changes (automatic with observer)'],
        ['BreadcrumbType.http', 'API calls and network requests'],
        ['BreadcrumbType.state', 'App state changes'],
        ['BreadcrumbType.info', 'General information events'],
        ['BreadcrumbType.error', 'Error events'],
        ['BreadcrumbType.system', 'SDK and system events'],
      ].map(([type, desc]) => (
        <tr key={type}>
          <td><code>{type}</code></td>
          <td>{desc}</td>
        </tr>
      ))}
    </tbody>
  </table>
</div>

### Complete Example

```dart
class CheckoutPage extends StatelessWidget {
  Future<void> _checkout() async {
    // Track user action
    AbrovaTrace.addBreadcrumb(
      'User initiated checkout',
      type: BreadcrumbType.user,
      data: {'cart_items': 3},
    );

    try {
      // Track HTTP call
      AbrovaTrace.addBreadcrumb(
        'POST /api/orders',
        type: BreadcrumbType.http,
      );

      final order = await api.createOrder();

      AbrovaTrace.addBreadcrumb(
        'Order created successfully',
        type: BreadcrumbType.info,
        data: {'order_id': order.id},
      );
    } catch (e, stackTrace) {
      // Error will include ALL breadcrumbs above
      await AbrovaTrace.captureException(
        e,
        stackTrace: stackTrace,
        message: 'Checkout failed',
      );
    }
  }

  @override
  Widget build(BuildContext context) {
    return ElevatedButton(
      onPressed: _checkout,
      child: Text('Place Order'),
    );
  }
}
```

### Viewing Breadcrumbs

Breadcrumbs appear automatically in the dashboard when viewing an error detail. They show a timeline of: navigation events, user clicks, API requests, and then the error.

### Best Practices

<BestPracticeList items={[
  ['Add Before Important Actions', 'Track breadcrumbs before payments, data mutations, and auth flows'],
  ['Use Descriptive Messages', '"User clicked checkout" is better than "button clicked"'],
  ['Include Relevant Data', 'Add IDs, amounts, and context — but avoid sensitive info'],
  ["Don't Overdo It", 'Too many breadcrumbs can be noisy — focus on meaningful events'],
]} />

- Logs overview: https://abrova.ir/en/docs/trace/logs

Aggregate and analyze logs from Docker containers, SDKs, and direct API ingestion. View, search, and filter logs in real-time.

<BestPracticeList columns={2} items={[
  ['Docker Agent', 'Automatically stream logs from all Docker containers with a single container deployment'],
  ['SDK Logging', 'Native SDKs for Flutter, Node.js, Next.js, Android, iOS, and Laravel with batching and retry logic'],
  ['API Ingestion', 'Send logs directly via REST API from any application, language, or framework'],
  ['Search & Filter', 'Full-text search with level filtering (error, warn, info, debug, trace) and source filtering'],
  ['Real-time Dashboard', 'View logs in real-time with auto-refresh, stats cards, and detailed log viewer'],
  ['Batch Support', 'Efficient batch ingestion for high-volume logging'],
]} />

### Quick Start: Docker Agent

```bash
docker run -d \
  --name abrova-trace-agent \
  --restart=always \
  -v /var/run/docker.sock:/var/run/docker.sock:ro \
  -e ABROVA_TRACE_API_KEY=ab_srv_your_server_secret \
  ghcr.io/abrova-co/abrova-trace-agent:latest
```

Use your project's server secret (`ab_srv_...`) from Abrova Console. Logs from all containers appear under **Abrova Trace → Logs**. Multi-host setup, container management and all options: [Abrova Trace agent](/docs/trace/agent).

### Quick Start: SDK Logging

Use native SDKs for automatic log batching, exponential backoff, and mobile lifecycle awareness.

#### Flutter

```dart
// Enable logging
AbrovaTrace.enableLogging(sourceId: 'my-flutter-app');

// Send logs
AbrovaTrace.info('User login successful', metadata: {'user_id': 'user_123'});
AbrovaTrace.warn('Slow API response', metadata: {'duration_ms': 2500});
AbrovaTrace.logError('Database query failed', metadata: {'query': 'SELECT ...'});
```

#### Node.js

```javascript
const { LogService, LogLevel } = require('@abrova-trace/nodejs-sdk');

const logger = new LogService({
  apiKey: 'ab_live_your_api_key',
  sourceId: 'api-server',
  environment: 'production',
});

logger.log('Server started', LogLevel.INFO);
logger.log('Payment failed', LogLevel.ERROR, { orderId: '12345' });
```

#### Next.js

```typescript
import { LogService } from '@abrova-trace/nextjs-sdk';

const logger = new LogService({
  apiKey: process.env.ABROVA_TRACE_API_KEY!,
  sourceId: 'nextjs-app',
  platform: 'nextjs',
  environment: process.env.NODE_ENV,
});

logger.log('Request received', 'info', { path: '/api/users' });
```

**SDK features:** Retry with exponential backoff (up to 60s between attempts), max buffer (1000 logs), lazy timers (no battery drain when idle), mobile lifecycle hooks (auto-flush on background). Details differ per SDK — see each SDK's logging page.

### Quick Start: API Ingestion

Full field list and examples in other languages: [Logs REST API](/docs/trace/logs-rest-api).

```bash
curl -X POST https://trace.abrova.ir/api/logs/ingest \
  -H "x-api-key: ab_srv_your_server_secret" \
  -H "Content-Type: application/json" \
  -d '{
    "sourceId": "api-server",
    "level": "info",
    "message": "Server started on port 3000"
  }'
```

### Batch Ingestion

```bash
curl -X POST https://trace.abrova.ir/api/logs/ingest/batch \
  -H "x-api-key: ab_srv_your_server_secret" \
  -H "Content-Type: application/json" \
  -d '{
    "sourceId": "api-server",
    "logs": [
      { "level": "info", "message": "Request received" },
      { "level": "debug", "message": "Processing..." },
      { "level": "info", "message": "Response sent in 45ms" }
    ]
  }'
```

### Log Levels

- **fatal** — Critical/unrecoverable errors
- **error** — Errors that need attention
- **warn** — Warnings about potential issues
- **info** — General application information
- **debug** — Detailed debugging information
- **trace** — Very detailed trace-level debugging

### Limits and costs

<Callout kind="wallet">
Free every month: 1 GB of logs. Above that, logs cost 15,000 Toman per GB from your wallet. Logs are kept for 30 days. See [Pricing](/pricing).
</Callout>

Log ingestion has generous rate limits per key and per client address. A client that exceeds them gets HTTP `429` with a `Retry-After` header; batching your logs keeps you far below them.

- Abrova Trace agent (Docker): https://abrova.ir/en/docs/trace/agent

The Abrova Trace agent streams logs from all Docker containers on your server, with real-time container management, multi-host support, and automatic log level detection. Deploy it with a single `docker run` command.

<Callout kind="note" title="What the agent gives you">
  <ul>
    <li>Live Docker logs in Abrova Console — every container, every host, one feed</li>
    <li>Container management from the Console: start, stop, restart, remove</li>
    <li>Live CPU / memory / network stats per container</li>
    <li>Multi-host: one collector aggregates remote agents on additional servers</li>
    <li>Automatic log level detection, multi-line joining (stack traces become one entry) and secret masking before anything leaves the host</li>
  </ul>
</Callout>

<Callout kind="wallet">
Container logs count toward your Abrova Trace logs: 1 GB a month is free, then 15,000 Toman per GB from your wallet. See [Pricing](/pricing).
</Callout>

### How it works

The agent uses a **collector + remote agent** architecture:

1. The **collector** runs on your main server. It watches local containers, connects to remote agents, and sends batched logs to Abrova Trace over HTTPS.
2. **Remote agents** run on additional servers. They stream their container logs to the collector over a WebSocket.
3. All containers (running and stopped) are registered in your project, so you can see and manage them.
4. The connection works both ways, so container commands (start, stop, restart, remove, stats) reach any host.

With a single server you only need the collector; that is the default mode.

<ConfigTable headers={['Mode', 'Command', 'What it does']} rows={[
  ['Default (collector)', '(none)', 'Watches local Docker and connects to remote agents; sends logs to Abrova Trace. Needs the key'],
  ['Agent', 'agent', 'WebSocket server that streams this host\'s container logs to a collector. No key needed'],
  ['Collector only', 'collector', 'Connects to remote agents only, without watching local Docker. Needs the key'],
]} />

<H2 id="deploy-manually-single-server" step={1}>Deploy on a single server</H2>

```bash
docker run -d \
  --name abrova-trace-agent \
  --restart=always \
  -v /var/run/docker.sock:/var/run/docker.sock:ro \
  -v abrova-trace-agent-data:/var/lib/abrova-trace-agent \
  -e ABROVA_TRACE_API_KEY=ab_srv_your_server_secret \
  ghcr.io/abrova-co/abrova-trace-agent:latest
```

<Callout kind="note" title="Where the image comes from">
  The agent image is pulled from `ghcr.io` (GitHub's container registry), so the server needs a connection that can reach it. If it cannot, pull the image on a machine that can, then move it with `docker save ghcr.io/abrova-co/abrova-trace-agent:latest -o agent.tar` and `docker load -i agent.tar`.
</Callout>

The volume keeps the agent's disk buffer and read positions when the container is re-created, so no lines are lost or sent twice.

<Callout kind="secret" title="Which key?">
  Give the agent your project's **server secret** (`ab_srv_...`) in `ABROVA_TRACE_API_KEY`. The app key (`ab_live_...`) also works as long as the project setting **Server routes require the server secret** is off, but it ships inside your apps, so it should not be what runs your agent. See [Server secret & server routes](/docs/trace/server-secret).
</Callout>

The agent registers every running and stopped container in your project within a few seconds. Open **Abrova Trace → Logs** in Abrova Console to watch the logs stream in.

<H2 id="multi-host-setup" step={2}>Multi-host setup</H2>

For multiple servers, deploy a **remote agent** on each additional server and point a single **collector** at them.

#### Remote agent (on each additional server)

```bash
docker run -d \
  --name abrova-trace-agent \
  --restart=always \
  -p 7008:7008 \
  -v /var/run/docker.sock:/var/run/docker.sock:ro \
  -e ABROVA_TRACE_HOSTNAME=server-2 \
  ghcr.io/abrova-co/abrova-trace-agent:latest agent
```

#### Collector (on the main server)

```bash
docker run -d \
  --name abrova-trace-agent \
  --restart=always \
  -v /var/run/docker.sock:/var/run/docker.sock:ro \
  -v abrova-trace-agent-data:/var/lib/abrova-trace-agent \
  -e ABROVA_TRACE_API_KEY=ab_srv_your_server_secret \
  -e ABROVA_TRACE_REMOTE_AGENTS=server2:YOUR_SERVER2_HOST:7008,server3:YOUR_SERVER3_HOST:7008 \
  ghcr.io/abrova-co/abrova-trace-agent:latest
```

The `ABROVA_TRACE_REMOTE_AGENTS` value is a comma-separated list of `name:host:port`. Each remote agent streams logs to the collector over a WebSocket and reconnects by itself after a disconnect (every 5 seconds).

<Callout kind="soon" title="Deploy from the desktop app">
  The [Abrova desktop app](/desktop) (coming soon) will deploy the agent to your servers over SSH for you: add a server, trust its host key, deploy. Until then, use the `docker run` commands on this page.
</Callout>

<H2 id="what-you-can-do-from-the-console" step={3}>Manage containers from the Console</H2>

In Abrova Console, open **Abrova Trace → Logs**. The **Sources** panel lists every host and its containers; the menu next to a container has:

- **View stats** — a live dialog with CPU %, memory used / limit and memory %, and network RX / TX (bytes received and sent across all network interfaces)
- **Start** — start a stopped container
- **Restart** — restart in place
- **Stop** — gracefully stop a running container
- **Delete** — stop and remove the container

Commands travel through Abrova Trace to the agent's WebSocket, so they work the same whether the container is on your main server or on a remote-agent host.

Start, stop, restart and delete need the **admin** or **owner** role; every role can see containers, logs and stats. See [Roles & Permissions](/docs/trace/error-dashboard#roles).

<H2 id="configuration-reference" step={4}>Configuration reference</H2>

#### Collector environment variables

<ConfigTable rows={[
  ['ABROVA_TRACE_API_KEY', 'string', 'Yes', 'Your project server secret (ab_srv_..., recommended). The app key (ab_live_...) works only while the "Server routes require the server secret" setting is off'],
  ['ABROVA_TRACE_URL', 'string', 'No', 'Abrova Trace API URL (default: https://trace.abrova.ir)'],
  ['ABROVA_TRACE_EXCLUDE', 'string', 'No', 'Container names to exclude, comma-separated (default: abrova-trace-agent)'],
  ['ABROVA_TRACE_INCLUDE', 'string', 'No', 'Container names to include, comma-separated (empty = all)'],
  ['ABROVA_TRACE_LABEL_FILTER', 'string', 'No', 'Only watch containers with this label (for example abrova-trace.project=abc123); takes priority over include/exclude'],
  ['ABROVA_TRACE_REMOTE_AGENTS', 'string', 'No', 'Remote agents in name:host:port format, comma-separated'],
  ['ABROVA_TRACE_HOSTNAME', 'string', 'No', 'Name this host is shown under (default: the Docker host name)'],
]} />

#### Remote agent environment variables

<ConfigTable rows={[
  ['ABROVA_TRACE_AGENT_PORT', 'number', 'No', 'WebSocket port for the agent (default: 7008)'],
  ['ABROVA_TRACE_HOSTNAME', 'string', 'No', 'Name this host is shown under (default: the system host name)'],
  ['ABROVA_TRACE_EXCLUDE', 'string', 'No', 'Container names to exclude, comma-separated (default: abrova-trace-agent)'],
  ['ABROVA_TRACE_INCLUDE', 'string', 'No', 'Container names to include, comma-separated (empty = all)'],
  ['ABROVA_TRACE_LABEL_FILTER', 'string', 'No', 'Only watch containers with this label'],
]} />

#### Log processing (all modes)

<ConfigTable rows={[
  ['ABROVA_TRACE_MULTILINE', 'boolean', 'No', 'Join stack traces and multi-line output into one entry (default: true)'],
  ['ABROVA_TRACE_REDACT', 'boolean', 'No', 'Mask secrets: tokens, passwords, API keys, credentials in URLs (default: true)'],
  ['ABROVA_TRACE_REDACT_PII', 'boolean', 'No', 'Mask e-mail addresses and phone numbers (default: true)'],
  ['ABROVA_TRACE_HEALTH_SAMPLE', 'number', 'No', 'Keep 1 in N successful health-check lines; 1 = all, 0 = none (default: 20)'],
  ['ABROVA_TRACE_DROP', 'string', 'No', 'Regular expressions separated by ||; matching entries are not sent'],
  ['ABROVA_TRACE_DATA_DIR', 'string', 'No', 'Disk buffer and read positions (default: /var/lib/abrova-trace-agent; mount a volume to keep them)'],
  ['ABROVA_TRACE_SPOOL_MB', 'number', 'No', 'Disk buffer cap in MB; the oldest unsent batches are dropped beyond it (default: 50)'],
  ['ABROVA_TRACE_CATCHUP_SECONDS', 'number', 'No', 'After a restart, resume from the last line read if it is this recent (default: 900)'],
]} />

<H2 id="log-level-detection" step={5}>Log level detection</H2>

The agent sets a level on every entry so the level filters in the Console work without code changes:

- **Explicit markers win** — `[ERROR]`, `ERROR:`, `level=warn`, `[debug]` and similar at the start of a line use the level written there. `critical` and `panic` count as **fatal**, `notice` as **info**, `verbose` as **trace**.
- **JSON logs** — a `level`, `severity`, `lvl` or `loglevel` field is used, including the numeric levels of pino and bunyan.
- **NestJS lines** (`[Nest] PID - TIMESTAMP LEVEL ...`) use the level NestJS printed.
- **Keywords otherwise** — `fatal` or `panic` → fatal; `error`, `exception`, `failed`, `unhandled`, `uncaught`, `ECONNREFUSED`, `ETIMEDOUT` → error; `warn`, `warning`, `deprecated` → warn; `debug`, `dbg` → debug.
- **info** — the default when nothing matches, so `info: 0 errors found` stays info.

<H2 id="what-an-entry-carries" step={6}>What an entry carries</H2>

Each log entry is one *event*, not one line. Besides the message and level, it carries extra fields in `metadata`:

<ConfigTable headers={['Field', 'Meaning']} rows={[
  ['fingerprint / template', 'The message with ids, numbers and dates replaced by placeholders, and a hash of it, so identical problems group together'],
  ['attributes', 'Fields parsed from JSON logs, key=value pairs and HTTP access lines (method, path, status, durationMs)'],
  ['traceId', 'A request or trace id found in the entry, to follow one request across containers'],
  ['lines', 'Number of raw lines joined (stack traces, printed objects)'],
  ['kind: container_event', 'A Docker lifecycle event (start, exit code, out-of-memory kill, restart, health check) written into the same timeline'],
  ['sampled', 'This health-check line stands for N lines'],
  ['hostname', 'The Docker host'],
]} />

<H2 id="how-log-delivery-works" step={7}>Batching and delivery</H2>

- **Batched** — logs are sent in batches of up to 100 entries, or every 5 seconds, whichever comes first.
- **Retry on failure** — failed batches are re-queued and retried, with up to 5,000 pending entries per source in memory (the oldest are dropped beyond that).
- **Disk buffer** — if Abrova Trace cannot be reached, batches are written to `ABROVA_TRACE_DATA_DIR` and re-sent in order when it is back (up to `ABROVA_TRACE_SPOOL_MB`).
- **Resume after restart** — the agent remembers the last line it read per container and continues from there.
- **Graceful shutdown** — `docker stop abrova-trace-agent` flushes pending batches before exiting.

### Key features

<BestPracticeList items={[
  ['Auto-discovery', 'New containers are detected and watched as they start'],
  ['Container registration', 'All containers (running and stopped) are registered in your project on startup'],
  ['Status reporting', 'Container start, stop, die and kill events are reported as they happen'],
  ['Multi-host support', 'Monitor containers across several servers from one place'],
  ['Auto-reconnect', 'Remote agent connections reconnect by themselves after a disconnect (5 s delay)'],
  ['Secret masking', 'Tokens, passwords, API keys, e-mail addresses and phone numbers are masked before anything leaves the host'],
]} />

### Security model

<BestPracticeList items={[
  ['Docker socket access', 'The agent mounts /var/run/docker.sock. The :ro flag only protects the socket file, not the Docker API, so treat the agent like any container with Docker access. It acts on containers only when a start / stop / restart / remove / stats command arrives from Abrova Trace, which authenticates it with your project credential.'],
  ['Run the agent with the server secret', 'Use the server secret (ab_srv_...) for the agent and switch on "Server routes require the server secret" in Project settings → Products → Abrova Trace. The app key ships inside your apps; with the setting on, it can no longer be used to connect as an agent or to register containers.'],
  ['Keep the key out of files', 'Pass the key with an environment variable or Docker secrets; never hard-code it in a compose file you commit.'],
  ['Role-based command authorization', 'Container commands are made by a signed-in project owner or admin, pass through Abrova Trace, then reach the agent over its WebSocket. The agent never accepts commands from anywhere else.'],
  ['Remote agent port (7008)', 'Should only be reachable from your collector. Configure your firewall so that only the collector\'s address can connect.'],
]} />

### Troubleshooting

<TroubleshootItem title="Agent container keeps restarting">
  Check the agent logs: `docker logs abrova-trace-agent`. Common causes: an invalid key, an unreachable API URL, or the Docker socket not mounted.
</TroubleshootItem>

<TroubleshootItem title="Logs arrive, but containers are missing or can't be controlled">
  If the project setting **Server routes require the server secret** is on and the agent runs with the app key, log lines still arrive but the agent cannot register containers, report their status or receive commands. Redeploy the agent with `ABROVA_TRACE_API_KEY` set to the server secret (`ab_srv_...`). See [Server secret & server routes](/docs/trace/server-secret).
</TroubleshootItem>

<TroubleshootItem title="Containers not showing in the Console">
  The agent registers containers on startup. If you added the agent after containers were running and they still do not show, restart the agent: `docker restart abrova-trace-agent`.
</TroubleshootItem>

<TroubleshootItem title="Stats dialog shows zeros or doesn't update">
  Stats are read from the local Docker daemon of the agent that owns the container. A host that only runs in `agent` mode streams logs to its collector; if stats stay empty for its containers, check that the collector is connected to it (see the next item).
</TroubleshootItem>

<TroubleshootItem title="Remote agent not connecting">
  Make sure port 7008 is reachable from the collector, for example `ufw allow from COLLECTOR_IP to any port 7008`. Double-check the `ABROVA_TRACE_REMOTE_AGENTS` format: `name:host:port`, comma-separated.
</TroubleshootItem>

<TroubleshootItem title="No logs appearing">
  Check that your containers are not in the exclude list (`ABROVA_TRACE_EXCLUDE`) and match `ABROVA_TRACE_INCLUDE` / `ABROVA_TRACE_LABEL_FILTER` if you set them. Verify the key is correct and the agent can reach the API URL. Logs are batched — wait up to 5 seconds for them to appear.
</TroubleshootItem>

<TroubleshootItem title="A line I need is missing">
  Check `ABROVA_TRACE_DROP` (matching entries are not sent) and `ABROVA_TRACE_HEALTH_SAMPLE` (only 1 in 20 successful health-check lines is kept by default; set it to `1` to keep all).
</TroubleshootItem>

- Flutter SDK logging: https://abrova.ir/en/docs/trace/flutter-logging

Battery-efficient logging for Flutter apps with automatic batching, exponential backoff, and mobile lifecycle awareness. Logs are buffered and sent in batches to minimize network usage.

<Callout kind="note" title="Logs vs. messages">
Logs (`AbrovaTrace.info()`, `warn()`, `logError()`, ...) are buffered, batched and shown under **Abrova Trace → Logs**. They are separate from `AbrovaTrace.captureMessage()`, which sends one event right away to **Abrova Trace → Messages**. Neither creates an issue — use `captureException()` for that.
</Callout>

<BestPracticeList columns={2} items={[
  ['Automatic Batching', 'Logs are buffered and sent in batches (default: 50)'],
  ['Exponential Backoff', 'Retries failed batches with increasing delays (2s, 4s, 8s... up to 60s, max 10 retries)'],
  ['Lifecycle Hooks', 'Auto-flushes on app background, pauses when inactive'],
  ['Max Buffer Size', 'Drops oldest logs when buffer exceeds 1000 to prevent memory issues'],
  ['Lazy Timer', 'Timer only runs when buffer has logs — no battery drain when idle'],
  ['User Context', 'Automatically attaches user ID set via AbrovaTrace.setUserId()'],
]} />

<H2 id="enable-logging" step={1}>Enable Logging</H2>

After initializing AbrovaTrace, enable the logging service:

```dart
import 'package:abrova_trace_flutter_sdk/abrova_trace_flutter_sdk.dart';

// Initialize AbrovaTrace first
await AbrovaTrace.init(AbrovaTraceConfig(
  apiKey: 'ab_live_your_api_key',
  environment: 'production',
  release: '1.0.0',
));

// Enable logging with a source identifier
AbrovaTrace.enableLogging(
  sourceId: 'my-flutter-app',
  sourceName: 'My Flutter App',
  batchSize: 50,
  flushInterval: Duration(seconds: 5),
);
```

If you call a log method before `enableLogging()`, logging is enabled automatically with the defaults and no `sourceId`. Logging needs the Flutter binding, so enable it (or send the first log) after `WidgetsFlutterBinding.ensureInitialized()`.

<H2 id="sending-logs" step={2}>Sending Logs</H2>

#### Convenience Methods

```dart
// Info log
AbrovaTrace.info('User login successful', metadata: {
  'user_id': 'user_123',
});

// Warning log
AbrovaTrace.warn('Slow API response', metadata: {
  'endpoint': '/api/users',
  'duration_ms': 2500,
});

// Error log
AbrovaTrace.logError('Database query failed', metadata: {
  'query': 'SELECT * FROM users',
  'error': 'Connection timeout',
});

// Debug log
AbrovaTrace.debug('Cache hit for key: user_123');

// Trace log
AbrovaTrace.trace('Entering function processPayment()');

// Fatal log
AbrovaTrace.fatal('App crashed unexpectedly', metadata: {
  'last_screen': 'checkout',
});
```

#### Generic Log Method

```dart
import 'package:abrova_trace_flutter_sdk/abrova_trace_flutter_sdk.dart';

// Generic log with explicit level
AbrovaTrace.log(
  'Custom event',
  level: LogLevel.info,
  metadata: {'key': 'value'},
);
```

<H2 id="log-levels" step={3}>Log Levels</H2>

- **trace** — `AbrovaTrace.trace()` — Very detailed trace-level debugging
- **debug** — `AbrovaTrace.debug()` — Debug information during development
- **info** — `AbrovaTrace.info()` — General application information
- **warn** — `AbrovaTrace.warn()` — Warnings about potential issues
- **error** — `AbrovaTrace.logError()` — Errors that need attention
- **fatal** — `AbrovaTrace.fatal()` — Critical/unrecoverable errors

<H2 id="mobile-lifecycle-behavior" step={4}>Mobile Lifecycle Behavior</H2>

The logging service automatically handles app lifecycle events:

- **App Paused/Background** — Immediately flushes all buffered logs
- **App Resumed** — Resets retry counter and resumes normal operation
- **App Detached** — Flushes and stops sending
- **Buffer Overflow** — Drops oldest logs when exceeding max buffer (1000)

<H2 id="manual-operations" step={5}>Manual Operations</H2>

<CodeBlock language="dart" code={`// Force flush all buffered logs
await AbrovaTrace.flushLogs();

// Check buffer status
print('Pending logs: \${AbrovaTrace.pendingLogCount}');`} />

<H2 id="configuration" step={6}>Configuration</H2>

<ConfigTable rows={[
  ['sourceId', 'String?', 'No', 'Identifier for this log source (e.g., "my-flutter-app"). Required for batch sending — without it each log is sent in its own request and failed sends are not retried'],
  ['sourceName', 'String?', 'No', 'Human-readable name for this source'],
  ['batchSize', 'int', 'No', 'Flush when buffer reaches this size (default: 50)'],
  ['flushInterval', 'Duration', 'No', 'Max time before flush (default: 5 seconds)'],
]} />

The buffer holds at most 1000 logs (oldest are dropped first). This limit is fixed and cannot be changed through `enableLogging()`.

### Best Practices

<BestPracticeList items={[
  ['Enable Early', 'Enable logging right after AbrovaTrace.init() to capture all events'],
  ['Use Source IDs', 'Set a meaningful sourceId to identify logs from this app in the dashboard'],
  ['Add Metadata', 'Include structured metadata (user ID, screen name, etc.) for easier debugging'],
  ['Use Appropriate Levels', 'Use info for normal events, warn for potential issues, error for failures'],
  ['Flush on Shutdown', 'Call AbrovaTrace.flushLogs() before app close to ensure all logs are sent'],
  ["Don't Over-Log", 'Avoid logging in tight loops — the buffer has a max size and will drop oldest logs'],
]} />

- Android SDK logging: https://abrova.ir/en/docs/trace/android-logging

Structured logging for Android apps with automatic batching, exponential backoff, and lifecycle awareness. Logs are buffered and sent in batches to minimize network usage and battery drain.

<BestPracticeList columns={2} items={[
  ['Automatic Batching', 'Logs are buffered and sent in batches (default: 50)'],
  ['Exponential Backoff', 'Failed batches are retried with increasing delays (2s, 4s, 8s... up to 60s)'],
  ['Max Buffer Size', 'Drops oldest logs when buffer exceeds 1000 to prevent memory issues'],
  ['Lazy Timer', 'Timer only runs when buffer has logs — no battery drain when idle'],
  ['User Context', 'Automatically attaches user ID set via AbrovaTrace.setUserId()'],
  ['Native Kotlin', 'Built with Kotlin, supports API 19+ (Android 4.4+)'],
]} />

<H2 id="enable-logging" step={1}>Enable Logging</H2>

After initializing AbrovaTrace in your `Application` class, enable the logging service:

```kotlin
import android.app.Application
import ir.abrova.trace.sdk.AbrovaTrace
import ir.abrova.trace.sdk.AbrovaTraceConfig

class MyApp : Application() {
    override fun onCreate() {
        super.onCreate()

        // Initialize AbrovaTrace first
        val config = AbrovaTraceConfig.Builder("ab_live_YOUR_API_KEY")
            .environment("production")
            .release(BuildConfig.VERSION_NAME)
            .build()

        AbrovaTrace.init(this, config)

        // Enable logging with a source identifier
        AbrovaTrace.enableLogging(
            sourceId = "my-android-app",
            sourceName = "My Android App",
            batchSize = 50,
            flushIntervalMs = 5000L
        )
    }
}
```

<H2 id="sending-logs" step={2}>Sending Logs</H2>

#### Convenience Methods

```kotlin
import ir.abrova.trace.sdk.AbrovaTrace

// Info log
AbrovaTrace.info("User login successful", mapOf(
    "user_id" to "user_123"
))

// Warning log
AbrovaTrace.warn("Slow API response", mapOf(
    "endpoint" to "/api/users",
    "duration_ms" to 2500
))

// Error log
AbrovaTrace.logError("Database query failed", mapOf(
    "query" to "SELECT * FROM users",
    "error" to "Connection timeout"
))

// Debug log
AbrovaTrace.logDebug("Cache hit for key: user_123")

// Trace log
AbrovaTrace.trace("Entering function processPayment()")

// Fatal log
AbrovaTrace.fatal("App crashed unexpectedly", mapOf(
    "last_screen" to "checkout"
))
```

#### Generic Log Method

```kotlin
import ir.abrova.trace.sdk.models.LogLevel

// Generic log with explicit level
AbrovaTrace.log(
    "Custom event",
    LogLevel.INFO,
    mapOf("key" to "value")
)
```

<H2 id="log-levels" step={3}>Log Levels</H2>

- **trace** — `AbrovaTrace.trace()` — Very detailed trace-level debugging
- **debug** — `AbrovaTrace.logDebug()` — Debug information during development
- **info** — `AbrovaTrace.info()` — General application information
- **warn** — `AbrovaTrace.warn()` — Warnings about potential issues
- **error** — `AbrovaTrace.logError()` — Errors that need attention
- **fatal** — `AbrovaTrace.fatal()` — Critical/unrecoverable errors

<H2 id="usage-with-activities" step={4}>Usage with Activities</H2>

```kotlin
class MainActivity : AppCompatActivity() {

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        AbrovaTrace.info("MainActivity created", mapOf("screen" to "main"))
    }

    private fun handlePurchase() {
        AbrovaTrace.info("Purchase initiated", mapOf(
            "product_id" to "premium_pack",
            "amount" to 99.99
        ))

        try {
            processPurchase()
            AbrovaTrace.info("Purchase completed", mapOf("amount" to 99.99))
        } catch (e: Exception) {
            AbrovaTrace.logError("Purchase failed", mapOf(
                "error" to e.message,
                "product_id" to "premium_pack"
            ))
            AbrovaTrace.captureException(e)
        }
    }

    override fun onDestroy() {
        if (isFinishing) {
            AbrovaTrace.flushLogs()
            AbrovaTrace.close()
        }
        super.onDestroy()
    }
}
```

<H2 id="manual-operations" step={5}>Manual Operations</H2>

<CodeBlock language="kotlin" code={`// Force flush all buffered logs
AbrovaTrace.flushLogs { success ->
    if (success) {
        Log.d("AbrovaTrace", "Logs flushed successfully")
    }
}

// Check buffer status
val pendingCount = AbrovaTrace.getPendingLogCount()
Log.d("AbrovaTrace", "Pending logs: ${'$'}pendingCount")`} />

<H2 id="configuration" step={6}>Configuration</H2>

<ConfigTable rows={[
  ['sourceId', 'String?', 'No', 'Identifier for batch sending (e.g., "my-android-app")'],
  ['sourceName', 'String?', 'No', 'Human-readable name for this source'],
  ['batchSize', 'Int', 'No', 'Flush when buffer reaches this size (default: 50)'],
  ['flushIntervalMs', 'Long', 'No', 'Max time before flush in ms (default: 5000)'],
]} />

If you call a log method before `enableLogging()`, logging is switched on automatically with the defaults above (no `sourceId`). Without a `sourceId`, each log is sent individually to `/api/logs/ingest` and a failed send is not retried; with one, buffered logs go in one request to `/api/logs/ingest/batch` and a failed batch is retried. Logs are also flushed when the app goes to the background. While the app is in the background the flush timer does not run: logs are sent when the batch size is reached or when the app returns to the foreground.

### Best Practices

<BestPracticeList items={[
  ['Enable Early', 'Enable logging right after AbrovaTrace.init() to capture all events'],
  ['Use Source IDs', 'Set a meaningful sourceId to identify logs from this app in the dashboard'],
  ['Add Metadata', 'Include structured metadata (user ID, screen name, etc.) for easier debugging'],
  ['Use Appropriate Levels', 'Use info for normal events, warn for potential issues, error for failures'],
  ['Flush on Shutdown', 'Call AbrovaTrace.flushLogs() before app close to ensure all logs are sent'],
  ["Don't Over-Log", 'Avoid logging in tight loops — the buffer has a max size and will drop oldest logs'],
]} />

- iOS SDK logging: https://abrova.ir/en/docs/trace/ios-logging

Structured logging for iOS apps with automatic batching, exponential backoff, and lifecycle awareness. Logs are buffered and sent in batches to minimize network usage and battery drain.

<BestPracticeList columns={2} items={[
  ['Automatic Batching', 'Logs are buffered and sent in batches (default: 50)'],
  ['Exponential Backoff', 'Failed batches retry with increasing delays (2s, 4s, 8s... up to 60s, max 10 retries)'],
  ['Max Buffer Size', 'Logs are buffered in memory only (enableOfflineStorage covers errors, not logs); the oldest are dropped when the buffer exceeds 1000'],
  ['Lazy Timer', 'Timer only runs when buffer has logs — no battery drain when idle'],
  ['User Context', 'Automatically attaches user ID set via AbrovaTrace.shared.setUserId()'],
  ['Native Swift', 'Built with Swift, supports iOS 12+, macOS 10.14+, tvOS 12+'],
]} />

<H2 id="enable-logging" step={1}>Enable Logging</H2>

After initializing AbrovaTrace, enable the logging service. (If you call a log method without enabling it, logging is turned on automatically with no `sourceId`.) Logs appear in the Console under **Abrova Trace → Logs**; they are separate from `captureMessage`, which goes to **Messages**.

#### UIKit

```swift
import UIKit
import AbrovaTrace

@main
class AppDelegate: UIResponder, UIApplicationDelegate {

    func application(_ application: UIApplication,
                     didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {

        // Initialize AbrovaTrace first
        let config = AbrovaTraceConfigBuilder(apiKey: "ab_live_YOUR_API_KEY")
            .environment("production")
            .release(Bundle.main.infoDictionary?["CFBundleShortVersionString"] as? String)
            .build()

        AbrovaTrace.shared.initialize(config: config)

        // Enable logging with a source identifier
        AbrovaTrace.shared.enableLogging(
            sourceId: "my-ios-app",
            sourceName: "My iOS App",
            batchSize: 50,
            flushInterval: 5.0
        )

        return true
    }
}
```

#### SwiftUI

```swift
import SwiftUI
import AbrovaTrace

@main
struct MyApp: App {
    init() {
        let config = AbrovaTraceConfigBuilder(apiKey: "ab_live_YOUR_API_KEY")
            .environment("production")
            .build()

        AbrovaTrace.shared.initialize(config: config)

        // Enable logging
        AbrovaTrace.shared.enableLogging(
            sourceId: "my-ios-app",
            sourceName: "My iOS App"
        )
    }

    var body: some Scene {
        WindowGroup {
            ContentView()
        }
    }
}
```

<H2 id="sending-logs" step={2}>Sending Logs</H2>

#### Convenience Methods

```swift
// Info log
AbrovaTrace.shared.info("User login successful", metadata: [
    "user_id": "user_123"
])

// Warning log
AbrovaTrace.shared.warn("Slow API response", metadata: [
    "endpoint": "/api/users",
    "duration_ms": 2500
])

// Error log
AbrovaTrace.shared.logErrorMessage("Database query failed", metadata: [
    "query": "SELECT * FROM users",
    "error": "Connection timeout"
])

// Debug log
AbrovaTrace.shared.logDebugMessage("Cache hit for key: user_123")

// Trace log
AbrovaTrace.shared.trace("Entering function processPayment()")

// Fatal log
AbrovaTrace.shared.fatal("App crashed unexpectedly", metadata: [
    "last_screen": "checkout"
])
```

#### Generic Log Method

```swift
// Generic log with explicit level
AbrovaTrace.shared.log("Custom event", level: .info, metadata: ["key": "value"])
```

<H2 id="log-levels" step={3}>Log Levels</H2>

- **trace** — `AbrovaTrace.shared.trace()` — Very detailed trace-level debugging
- **debug** — `AbrovaTrace.shared.logDebugMessage()` — Debug information during development
- **info** — `AbrovaTrace.shared.info()` — General application information
- **warn** — `AbrovaTrace.shared.warn()` — Warnings about potential issues
- **error** — `AbrovaTrace.shared.logErrorMessage()` — Errors that need attention
- **fatal** — `AbrovaTrace.shared.fatal()` — Critical/unrecoverable errors

<H2 id="usage-with-viewcontrollers" step={4}>Usage with ViewControllers</H2>

```swift
class ViewController: UIViewController {

    override func viewDidLoad() {
        super.viewDidLoad()
        AbrovaTrace.shared.info("ViewController loaded", metadata: ["screen": "main"])
    }

    func handlePurchase() {
        AbrovaTrace.shared.info("Purchase initiated", metadata: [
            "product_id": "premium_pack",
            "amount": 99.99
        ])

        do {
            try processPurchase()
            AbrovaTrace.shared.info("Purchase completed", metadata: ["amount": 99.99])
        } catch {
            AbrovaTrace.shared.logErrorMessage("Purchase failed", metadata: [
                "error": error.localizedDescription,
                "product_id": "premium_pack"
            ])
            AbrovaTrace.shared.captureError(error)
        }
    }

    func processPurchase() throws { /* ... */ }
}
```

#### SwiftUI Views

```swift
struct ContentView: View {
    var body: some View {
        Button("Purchase") {
            AbrovaTrace.shared.info("Purchase button tapped")
            handlePurchase()
        }
        .onAppear {
            AbrovaTrace.shared.info("ContentView appeared")
        }
    }

    func handlePurchase() {
        // Purchase logic with logging
    }
}
```

<H2 id="manual-operations" step={5}>Manual Operations</H2>

<CodeBlock language="swift" code={`// Force flush all buffered logs
AbrovaTrace.shared.flushLogs { success in
    if success {
        print("Logs flushed successfully")
    }
}

// Check buffer status
let pendingCount = AbrovaTrace.shared.pendingLogCount
print("Pending logs: \\(pendingCount)")`} />

<H2 id="configuration" step={6}>Configuration</H2>

<ConfigTable rows={[
  ['sourceId', 'String?', 'No', 'Identifier for batch sending (e.g., "my-ios-app"). Without it, buffered logs are sent one request each and failed sends are not retried'],
  ['sourceName', 'String?', 'No', 'Human-readable name for this source'],
  ['batchSize', 'Int', 'No', 'Flush when buffer reaches this size (default: 50)'],
  ['flushInterval', 'TimeInterval', 'No', 'Max time before flush in seconds (default: 5.0)'],
]} />

### Best Practices

<BestPracticeList items={[
  ['Enable Early', 'Enable logging right after AbrovaTrace initialization to capture all events'],
  ['Use Source IDs', 'Set a meaningful sourceId to identify logs from this app in the dashboard'],
  ['Add Metadata', 'Include structured metadata (user ID, screen name, etc.) for easier debugging'],
  ['Use Appropriate Levels', 'Use info for normal events, warn for potential issues, error for failures'],
  ['Flush on Shutdown', 'Logs flush automatically when the app enters the background and on terminate; call AbrovaTrace.shared.flushLogs() for other shutdown paths'],
  ["Don't Over-Log", 'Avoid logging in tight loops — the buffer has a max size and will drop oldest logs'],
]} />

- Laravel SDK logging: https://abrova.ir/en/docs/trace/laravel-logging

Structured logging for Laravel via Monolog channel integration and batched sending with retry. Logs appear under **Abrova Trace → Logs**; they are separate from `AbrovaTrace::captureMessage()`, which goes to Messages.

<BestPracticeList columns={2} items={[
  ['Monolog Channel', "Use Laravel's native Log facade with a custom abrovatrace channel driver."],
  ['Batched Sending', 'Logs are buffered and sent when the buffer reaches batch_size, and at shutdown.'],
  ['Retry with Backoff', 'HTTP client retries connection errors and 5xx responses up to 3 times, waiting 1s, 2s, then 3s.'],
  ['Level Mapping', 'Monolog levels automatically mapped to AbrovaTrace levels (debug, info, warn, error, fatal).'],
]} />

<H2 id="installation" step={1}>Installation</H2>

Add the Abrova repository to `composer.json`, then install (see [Laravel SDK](/docs/trace/laravel-sdk#installation)):

```json
"repositories": [
    { "type": "composer", "url": "https://center.abrova.ir/api/packages/abrova/composer" }
]
```

```bash
composer require abrova-trace/laravel-sdk
```

Add the log channel to `config/logging.php`:

```php
'channels' => [
    // ... other channels

    'abrovatrace' => [
        'driver' => 'custom',
        'via' => AbrovaTrace\Laravel\Logging\AbrovaTraceLogChannel::class,
    ],
],
```

<H2 id="basic-usage" step={2}>Basic Usage</H2>

```php
use Illuminate\Support\Facades\Log;

// Send logs to AbrovaTrace
Log::channel('abrovatrace')->info('User signed up', ['userId' => 123]);
Log::channel('abrovatrace')->warning('Rate limit approaching', ['remaining' => 5]);
Log::channel('abrovatrace')->error('Payment failed', [
    'orderId' => 'ORD-456',
    'reason' => 'insufficient_funds',
]);
```

<H2 id="log-levels" step={3}>Log Levels</H2>

```php
use Illuminate\Support\Facades\Log;

Log::channel('abrovatrace')->debug('Debug information');
Log::channel('abrovatrace')->info('User action completed');
Log::channel('abrovatrace')->notice('Approaching rate limit');   // Maps to 'info'
Log::channel('abrovatrace')->warning('Slow query detected');     // Maps to 'warn'
Log::channel('abrovatrace')->error('Failed to save data');
Log::channel('abrovatrace')->critical('Service unavailable');    // Maps to 'fatal'
Log::channel('abrovatrace')->alert('Database connection lost');  // Maps to 'fatal'
Log::channel('abrovatrace')->emergency('App crashed');           // Maps to 'fatal'
```

<Callout kind="note" title="Level Mapping">
  Monolog levels are mapped to AbrovaTrace levels: DEBUG=debug, INFO/NOTICE=info, WARNING=warn, ERROR=error, CRITICAL/ALERT/EMERGENCY=fatal.
</Callout>

<H2 id="direct-sdk-logging" step={4}>Direct SDK Logging</H2>

You can also log directly via the AbrovaTrace facade:

```php
use AbrovaTrace\Laravel\AbrovaTraceFacade as AbrovaTrace;
use AbrovaTrace\Laravel\Logging\LogLevel;

// Basic log
AbrovaTrace::log('Server started', LogLevel::INFO);

// With metadata
AbrovaTrace::log('Order processed', LogLevel::INFO, [
    'orderId' => 'ORD-123',
    'amount' => 99.99,
]);

// User ID: logs carry the id from setUser() (set automatically by the middleware)
AbrovaTrace::setUser(['id' => 'user_abc123']);
AbrovaTrace::log('Payment declined', LogLevel::ERROR, [
    'reason' => 'card_expired',
]);

// Convenience methods
AbrovaTrace::info('User logged in');
AbrovaTrace::warn('API rate limit at 80%');
AbrovaTrace::logError('Failed to send email');
// also: trace(), logDebug(), fatal()
```

<H2 id="stack-channel" step={5}>Stack Channel</H2>

Send logs to multiple destinations by adding abrovatrace to a stack channel:

```php
// config/logging.php
'channels' => [
    'stack' => [
        'driver' => 'stack',
        'channels' => ['daily', 'abrovatrace'],
        'ignore_exceptions' => false,
    ],

    'abrovatrace' => [
        'driver' => 'custom',
        'via' => AbrovaTrace\Laravel\Logging\AbrovaTraceLogChannel::class,
    ],
],
```

```php
// Now Log::info() sends to both daily file AND AbrovaTrace
Log::info('User action', ['userId' => 123]);
```

Laravel writes reported exceptions to your default log channel, and since 0.2.3 the SDK no longer stops that. If `abrovatrace` is in the default stack, an exception also arrives in Logs as a log entry, in addition to being reported as an error.

<H2 id="metadata-context" step={6}>Metadata & Context</H2>

```php
// Structured metadata
Log::channel('abrovatrace')->info('Order placed', [
    'orderId' => 'ORD-12345',
    'amount' => 4500000,
    'currency' => 'IRR',
    'items' => 3,
]);

// Automatically included with every log:
// - Platform ('laravel'), environment name and release
// - User id, when a user is set (the middleware sets the authenticated user)
```

<H2 id="configuration" step={7}>Configuration</H2>

```php
// config/abrovatrace.php
'logging' => [
    'source_id' => env('ABROVATRACE_LOG_SOURCE_ID', null),     // Groups logs into one source; enables batch sending
    'source_name' => env('ABROVATRACE_LOG_SOURCE_NAME', null), // Display name for the source
    'batch_size' => 50,           // Send when buffer reaches this size
],
```

<ConfigTable rows={[
  ['logging.source_id', 'string', 'No', 'Log source identifier (e.g., "api-server"). With it, a flush is one batch request; without it, one request per log'],
  ['logging.source_name', 'string', 'No', 'Human-readable display name for the source'],
  ['logging.batch_size', 'integer', 'No', 'Flush when buffer reaches this size (default: 50)'],
  ['api_key', 'string', 'Yes', 'Your project API key (ab_live_xxx)'],
  ['server_secret', 'string', 'No', 'Your server secret (ab_srv_xxx). Needed when the project setting "Server routes require the server secret" is on'],
  ['debug', 'boolean', 'No', 'Enable debug output (default: false)'],
]} />

### Best Practices

<BestPracticeList items={[
  ['Use the Monolog Channel', "Use Log::channel('abrovatrace') to integrate with Laravel's native logging"],
  ['Stack for Multiple Destinations', 'Add abrovatrace to a stack channel for local file + cloud logging'],
  ['Structured Metadata', 'Include structured metadata (IDs, durations, counts) for better filtering in the dashboard'],
  ['Associate Users', 'Logs carry the user id from AbrovaTrace::setUser() (set automatically for authenticated requests)'],
  ['Use Appropriate Levels', 'Use info for normal operations, warn for degraded state, error for failures'],
  ['Avoid Logging Sensitive Data', 'Never log passwords, tokens, or PII in metadata'],
]} />

- Node.js SDK logging: https://abrova.ir/en/docs/trace/nodejs-logging

Server-side logging with exponential backoff, zero dependencies, and Express.js integration. Logs appear under **Abrova Trace → Logs**; they are separate from `AbrovaTrace.captureMessage()`, which goes to Messages.

<BestPracticeList columns={2} items={[
  ['Exponential Backoff', 'A failed batch is retried after 2s → 4s → 8s → ... → 60s max. After 10 failed retries the logs stay in the buffer until the next log or flush.'],
  ['Max Buffer Size', 'Default 1000 logs. Oldest dropped when exceeded to prevent memory issues.'],
  ['Lazy Timer', 'setTimeout only runs when buffer has logs. No CPU overhead when idle.'],
  ['Zero Dependencies', 'Uses native Node.js http/https modules. No external packages.'],
]} />

<H2 id="installation" step={1}>Installation</H2>

Add the Abrova registry to `.npmrc`, then install (see [Node.js SDK](/docs/trace/nodejs-sdk#installation)):

```bash
# .npmrc
@abrova-trace:registry=https://center.abrova.ir/api/packages/abrova/npm/
```

```bash
npm install @abrova-trace/nodejs-sdk
```

<H2 id="basic-usage" step={2}>Basic Usage</H2>

```javascript
const { LogService, LogLevel } = require('@abrova-trace/nodejs-sdk');

const logger = new LogService({
  apiKey: 'ab_live_your_api_key',
  sourceId: 'api-server',
  sourceName: 'My API Server',
  environment: 'production',
});

logger.log('Server started on port 3000', LogLevel.INFO);
logger.log('Database connection slow', LogLevel.WARN, { latency: 2500 });
logger.log('Failed to process payment', LogLevel.ERROR, { orderId: '12345' });

// Graceful shutdown
process.on('SIGTERM', async () => {
  await logger.dispose();
  process.exit(0);
});
```

If you already call `AbrovaTrace.init()`, you can log through it instead of creating a `LogService` yourself. It reuses the API key, environment and release from `init()`, and attaches the user set with `setUser()`:

```javascript
const AbrovaTrace = require('@abrova-trace/nodejs-sdk');

AbrovaTrace.enableLogging({ sourceId: 'api-server', sourceName: 'My API Server' }); // flushes every 5s by default

AbrovaTrace.info('Server started on port 3000');
AbrovaTrace.warn('Database connection slow', { latency: 2500 });
AbrovaTrace.logError('Failed to process payment', { orderId: '12345' });
// also: trace(), logDebug(), fatal(), log(message, level, metadata)

await AbrovaTrace.flushLogs();   // sends buffered logs now
```

Before the process exits, call `await AbrovaTrace.flush()`. It sends buffered logs together with pending errors, messages and performance spans, and resolves `false` if its timeout (default: 5000 ms) passes first. `AbrovaTrace.close()` also sends buffered logs, then resets the SDK.

<H2 id="log-levels" step={3}>Log Levels</H2>

```javascript
const { LogLevel } = require('@abrova-trace/nodejs-sdk');

logger.log('Detailed trace info', LogLevel.TRACE);
logger.log('Debug information', LogLevel.DEBUG);
logger.log('User action completed', LogLevel.INFO);
logger.log('Approaching rate limit', LogLevel.WARN);
logger.log('Failed to save data', LogLevel.ERROR);
logger.log('App crashed unexpectedly', LogLevel.FATAL);
```

<H2 id="express-js-integration" step={4}>Express.js Integration</H2>

<CodeBlock language="javascript" code={`const express = require('express');
const { LogService, LogLevel } = require('@abrova-trace/nodejs-sdk');

const app = express();
const logger = new LogService({
  apiKey: 'ab_live_your_api_key',
  sourceId: 'express-api',
  environment: process.env.NODE_ENV || 'development',
});

// Request logging middleware
app.use((req, res, next) => {
  const start = Date.now();
  res.on('finish', () => {
    const duration = Date.now() - start;
    const level = res.statusCode >= 400 ? LogLevel.ERROR : LogLevel.INFO;
    logger.log(\`\${req.method} \${req.path} \${res.statusCode}\`, level, {
      method: req.method,
      path: req.path,
      statusCode: res.statusCode,
      duration,
    });
  });
  next();
});

// Error logging middleware
app.use((err, req, res, next) => {
  logger.log(err.message, LogLevel.ERROR, {
    stack: err.stack,
    path: req.path,
  });
  res.status(500).json({ error: 'Internal Server Error' });
});`} />

<H2 id="metadata-user-context" step={5}>Metadata & User Context</H2>

```javascript
// Structured metadata
logger.log('Order placed', LogLevel.INFO, {
  orderId: 'ORD-12345',
  amount: 4500000,
  currency: 'IRR',
});

// Associate logs with a user (4th parameter)
logger.log('Payment declined', LogLevel.ERROR, {
  reason: 'insufficient_funds',
}, 'user_abc123');
```

<H2 id="manual-operations" step={6}>Manual Operations</H2>

```javascript
// Force flush all buffered logs
await logger.flush();

// Check buffer status
console.log('Pending logs:', logger.bufferSize);

// Dispose when shutting down (flushes remaining logs)
await logger.dispose();
```

<H2 id="configuration" step={7}>Configuration</H2>

```javascript
const logger = new LogService({
  apiKey: 'ab_live_your_api_key',       // Required
  serverSecret: process.env.ABROVA_SERVER_SECRET, // Optional: ab_srv_..., sent with every request
  sourceId: 'api-server',            // Needed for batch sending (without it, logs are sent one by one)
  sourceName: 'My API Server',       // Optional display name
  platform: 'nodejs',                // Default: 'nodejs'
  environment: 'production',         // 'development', 'staging', 'production'
  release: '1.2.3',                  // Optional app version
  batchSize: 50,                     // Flush when buffer reaches this size
  flushIntervalMs: 30000,            // Max time before flush (default: 30000)
  maxBufferSize: 1000,               // Drop oldest logs when exceeded
  debug: false,                      // Enable console debug output
});
```

<ConfigTable rows={[
  ['apiKey', 'string', 'Yes', 'Your project API key'],
  ['serverSecret', 'string', 'No', 'Your server secret (ab_srv_xxx), sent with every log request; keep it on the server'],
  ['apiUrl', 'string', 'No', 'Trace API base URL; set it only for a self-hosted Trace API (default: "https://trace.abrova.ir")'],
  ['sourceId', 'string', 'No', 'Source identifier (e.g., "api-server"). Without it, logs are sent one request each and failed sends are not retried'],
  ['sourceName', 'string', 'No', 'Human-readable display name for this source'],
  ['platform', 'string', 'No', 'Platform identifier (default: "nodejs")'],
  ['environment', 'string', 'No', 'Environment name (default: "production")'],
  ['release', 'string', 'No', 'App version identifier'],
  ['batchSize', 'number', 'No', 'Flush at this buffer size (default: 50)'],
  ['flushIntervalMs', 'number', 'No', 'Max ms before flush (default: 30000)'],
  ['maxBufferSize', 'number', 'No', 'Drop oldest when exceeded (default: 1000)'],
  ['debug', 'boolean', 'No', 'Enable console debug output (default: false)'],
]} />

### Best Practices

<BestPracticeList items={[
  ['Use Source IDs', 'Set meaningful sourceId values to identify log sources in the dashboard'],
  ['Graceful Shutdown', 'Always call dispose() on SIGTERM/SIGINT to flush remaining logs (AbrovaTrace.flush() when you log through AbrovaTrace)'],
  ['Request Logging Middleware', 'Add request logging middleware early in the Express pipeline'],
  ['Error Middleware Last', 'Add error logging middleware after all routes for comprehensive coverage'],
  ['Structured Metadata', 'Include structured metadata (IDs, durations, paths) for better filtering'],
  ['Associate Users', 'Pass user IDs to logs for easier debugging of user-specific issues'],
]} />

- Next.js SDK logging: https://abrova.ir/en/docs/trace/nextjs-logging

Full-stack TypeScript logging for Next.js applications with App Router and Pages Router support.

<H2 id="installation" step={1}>Installation</H2>

Add the Abrova registry to `.npmrc`, then install (see [Next.js SDK](/docs/trace/nextjs-sdk#installation)):

```bash
# .npmrc
@abrova-trace:registry=https://center.abrova.ir/api/packages/abrova/npm/
```

```bash
npm install @abrova-trace/nextjs-sdk
```

<H2 id="initialize-logger" step={2}>Initialize Logger</H2>

Create `lib/logger.ts`:

```typescript
import { LogService } from '@abrova-trace/nextjs-sdk';

export const logger = new LogService({
  apiKey: process.env.ABROVA_TRACE_API_KEY!,
  sourceId: 'nextjs-app',
  sourceName: 'My Next.js App',
  platform: 'nextjs',
  environment: process.env.NODE_ENV,
});
```

<H2 id="app-router-next-js-13" step={3}>App Router (Next.js 13+)</H2>

```typescript
// app/api/users/route.ts
import { NextResponse } from 'next/server';
import { logger } from '@/lib/logger';

export async function GET(request: Request) {
  logger.log('Fetching users', 'info');

  try {
    const users = await db.users.findMany();
    logger.log('Users fetched', 'info', { count: users.length });
    return NextResponse.json(users);
  } catch (error) {
    logger.log('Failed to fetch users', 'error', {
      error: error instanceof Error ? error.message : 'Unknown',
    });
    return NextResponse.json({ error: 'Internal Server Error' }, { status: 500 });
  }
}
```

### Pages Router (API Routes)

```typescript
// pages/api/orders.ts
import { logger } from '@/lib/logger';

export default async function handler(req, res) {
  logger.log('Order request received', 'info', {
    method: req.method,
    path: req.url,
  });

  try {
    const order = await createOrder(req.body);
    logger.log('Order created', 'info', { orderId: order.id });
    res.json(order);
  } catch (error) {
    logger.log('Order creation failed', 'error', {
      error: error.message,
    });
    res.status(500).json({ error: 'Failed to create order' });
  }
}
```

<H2 id="log-levels" step={4}>Log Levels</H2>

```typescript
// LogLevel = 'trace' | 'debug' | 'info' | 'warn' | 'error' | 'fatal'

logger.log('Detailed trace info', 'trace');
logger.log('Debug information', 'debug');
logger.log('User action completed', 'info');
logger.log('Approaching rate limit', 'warn');
logger.log('Failed to save data', 'error');
logger.log('App crashed unexpectedly', 'fatal');
```

<H2 id="middleware-integration" step={5}>Middleware Integration</H2>

```typescript
// middleware.ts
import { NextResponse } from 'next/server';
import type { NextRequest } from 'next/server';
import { logger } from '@/lib/logger';

export function middleware(request: NextRequest) {
  const start = Date.now();

  logger.log('Request received', 'info', {
    method: request.method,
    path: request.nextUrl.pathname,
  });

  const response = NextResponse.next();
  const duration = Date.now() - start;

  logger.log('Request processed', 'info', {
    path: request.nextUrl.pathname,
    duration,
  });

  return response;
}

export const config = { matcher: '/api/:path*' };
```

<H2 id="client-side-logging" step={6}>Client-Side Logging</H2>

<Callout kind="note" title="Two options">In the browser you can log straight through the SDK instance you already initialized, e.g. `AbrovaTrace.getInstance()?.info('Button clicked', { buttonId: 'submit-form' })`. If you would rather validate or filter client logs on your own server first, send them through an API route as below. Logs are buffered (sent after 50 logs or 30 seconds by default) and are not sent automatically when the page closes, so call `AbrovaTrace.getInstance()?.flushLogs()` when a log must go out right away.</Callout>

Create a proxy route:

```typescript
// app/api/log/route.ts
import { NextResponse } from 'next/server';
import { logger } from '@/lib/logger';

export async function POST(request: Request) {
  const { message, level, metadata } = await request.json();

  const validLevels = ['trace', 'debug', 'info', 'warn', 'error', 'fatal'];
  const safeLevel = validLevels.includes(level) ? level : 'info';

  logger.log(message, safeLevel, { ...metadata, source: 'client' });

  return NextResponse.json({ success: true });
}
```

Client component:

```typescript
'use client';

async function logToServer(message: string, level: string, metadata?: object) {
  await fetch('/api/log', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ message, level, metadata }),
  });
}

// Usage
logToServer('Button clicked', 'info', { buttonId: 'submit-form' });
```

<H2 id="configuration" step={7}>Configuration</H2>

<ConfigTable rows={[
  ['apiKey', 'string', 'Yes', 'Your project API key'],
  ['sourceId', 'string', 'No', 'Log source identifier. With it, logs are sent in batches (/api/logs/ingest/batch); without it, each buffered log is sent in its own request'],
  ['sourceName', 'string', 'No', 'Display name for this source'],
  ['platform', 'string', 'Yes', 'Platform identifier, e.g. "nextjs" (no default)'],
  ['environment', 'string', 'Yes', 'Environment name, e.g. "production" (no default)'],
  ['release', 'string', 'No', 'App version attached to each log'],
  ['batchSize', 'number', 'No', 'Flush at this buffer size (default: 50)'],
  ['flushIntervalMs', 'number', 'No', 'Max ms before flush (default: 30000)'],
  ['maxBufferSize', 'number', 'No', 'Drop oldest when exceeded (default: 1000)'],
  ['debug', 'boolean', 'No', 'Print SDK debug output to the console (default: false)'],
  ['apiUrl', 'string', 'No', 'Base URL of the Trace API (default: "https://trace.abrova.ir"). Set it only for self-hosted'],
]} />

### Best Practices

<BestPracticeList items={[
  ['Centralize Logger', 'Create a single logger instance in lib/logger.ts and import it everywhere'],
  ['Filter Client Logs', 'Use a proxy route when you want to validate or filter client logs before they reach Abrova Trace'],
  ['Log API Routes', 'Add logging to all API routes for full request visibility'],
  ['Add Request Context', 'Include method, path, and duration in request logs'],
  ['Validate Client Logs', 'Sanitize and validate log level/message from client-side proxy'],
  ['Use Middleware', 'Add middleware for automatic request/response logging on API routes'],
]} />

- Logs REST API: https://abrova.ir/en/docs/trace/logs-rest-api

Send logs over HTTPS from any application, language or framework. Every request needs a project credential in the `x-api-key` header: the server secret (`ab_srv_...`) when you send from a server, or the app key (`ab_live_...`) when you send from an app.

<Callout kind="secret" title="Which key?">
The app key ships inside mobile and web apps, so treat it as public. On your own servers use the **server secret** from an environment variable and keep it out of client code. Both keys are accepted on the two log endpoints below, whatever the project's settings. See [Server secret & server routes](/docs/trace/server-secret).
</Callout>

<Callout kind="wallet">
Logs are free up to 1 GB a month; above that they cost 15,000 Toman per GB from your wallet. Logs are kept for 30 days. See [Pricing](/pricing).
</Callout>

<H2 id="post-api-logs-ingest-single-log" step={1}>Send one log</H2>

<Endpoint method="POST" url="https://trace.abrova.ir/api/logs/ingest" />

<ConfigTable rows={[
  ['message', 'string', 'Yes', 'The log line (up to 10,000 characters are kept)'],
  ['level', 'string', 'No', 'fatal, error, warn, info, debug or trace (default: info)'],
  ['sourceId', 'string', 'No', 'Identifier for the log source (for example "api-server"). Default: "<platform>-default", or "unknown-default"'],
  ['sourceName', 'string', 'No', 'Human-readable source name'],
  ['timestamp', 'string', 'No', 'ISO 8601 timestamp (default: the time it was received)'],
  ['metadata', 'object', 'No', 'Additional key-value pairs'],
  ['platform', 'string', 'No', 'Platform tag shown in the Logs view'],
  ['environment', 'string', 'No', 'Environment (default: production)'],
  ['release', 'string', 'No', 'Release version'],
  ['userId', 'string', 'No', 'User the log belongs to'],
]} />

```bash
curl -X POST https://trace.abrova.ir/api/logs/ingest \
  -H "x-api-key: $ABROVA_TRACE_SERVER_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "sourceId": "api-server",
    "sourceName": "API Server",
    "level": "info",
    "message": "User login successful",
    "metadata": {
      "userId": "user_123",
      "ip": "192.168.1.1"
    }
  }'
```

Response (`201`): <code>{`{"status": "created", "id": 12345}`}</code>

<H2 id="post-api-logs-ingest-batch-batch-logs" step={2}>Send a batch</H2>

<Endpoint method="POST" url="https://trace.abrova.ir/api/logs/ingest/batch" />

More efficient for high-volume logging: send many entries in one request as a JSON array under `logs`. `sourceId` is **required** here; each entry in `logs` takes the same fields as a single log (except `sourceId` / `sourceName`). Up to 1,000 entries are stored from one request; send more as several batches.

```bash
curl -X POST https://trace.abrova.ir/api/logs/ingest/batch \
  -H "x-api-key: $ABROVA_TRACE_SERVER_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "sourceId": "api-server",
    "logs": [
      { "level": "info", "message": "Request received: GET /api/users" },
      { "level": "debug", "message": "Querying database..." },
      { "level": "info", "message": "Response sent: 200 OK (45ms)" }
    ]
  }'
```

Response (`201`): <code>{`{"status": "created", "count": 3, "projectId": "..."}`}</code>

<H2 id="code-examples" step={3}>Code examples</H2>

#### Node.js

<CodeBlock language="javascript" code={`const ABROVA_TRACE_SERVER_SECRET = process.env.ABROVA_TRACE_SERVER_SECRET; // ab_srv_...
const ABROVA_TRACE_URL = 'https://trace.abrova.ir';

async function sendLog(sourceId, level, message, metadata = {}) {
  await fetch(\`\${ABROVA_TRACE_URL}/api/logs/ingest\`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'x-api-key': ABROVA_TRACE_SERVER_SECRET,
    },
    body: JSON.stringify({ sourceId, level, message, metadata }),
  });
}

// Usage
sendLog('api-server', 'info', 'Server started on port 3000');
sendLog('api-server', 'error', 'Database connection failed', {
  error: 'ECONNREFUSED',
});`} />

For Node.js apps, the [Node.js SDK](/docs/trace/nodejs-logging) batches and retries for you.

#### Python

```python
import os
import requests

ABROVA_TRACE_SERVER_SECRET = os.environ.get('ABROVA_TRACE_SERVER_SECRET')  # ab_srv_...
ABROVA_TRACE_URL = 'https://trace.abrova.ir'

def send_log(source_id, level, message, metadata=None):
    requests.post(
        f'{ABROVA_TRACE_URL}/api/logs/ingest',
        json={
            'sourceId': source_id,
            'level': level,
            'message': message,
            'metadata': metadata or {},
        },
        headers={'x-api-key': ABROVA_TRACE_SERVER_SECRET},
        timeout=5,
    )

# Usage
send_log('worker', 'info', 'Job started')
send_log('worker', 'error', 'Job failed', {'job_id': '123'})
```

#### Go

```go
package main

import (
    "bytes"
    "encoding/json"
    "net/http"
    "os"
)

func sendLog(sourceId, level, message string, metadata map[string]interface{}) error {
    body, _ := json.Marshal(map[string]interface{}{
        "sourceId": sourceId,
        "level":    level,
        "message":  message,
        "metadata": metadata,
    })

    req, _ := http.NewRequest("POST",
        "https://trace.abrova.ir/api/logs/ingest",
        bytes.NewBuffer(body))
    req.Header.Set("Content-Type", "application/json")
    req.Header.Set("x-api-key", os.Getenv("ABROVA_TRACE_SERVER_SECRET"))

    _, err := http.DefaultClient.Do(req)
    return err
}
```

#### PHP

For Laravel apps, use the [Laravel SDK log channel](/docs/trace/laravel-logging). For plain PHP:

```php
$ch = curl_init('https://trace.abrova.ir/api/logs/ingest');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Content-Type: application/json',
        'x-api-key: ' . getenv('ABROVA_TRACE_SERVER_SECRET'),
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'sourceId' => 'shop-backend',
        'level' => 'error',
        'message' => 'payment callback timeout order=ORD-8812',
    ]),
]);
curl_exec($ch);
curl_close($ch);
```

<H2 id="error-codes" step={4}>Response codes</H2>

- **201** — Created
- **400** — Invalid request body (missing `message`; for a batch, empty `logs` or missing `sourceId`)
- **401** — Missing or invalid key, or Abrova Trace is not enabled for the project
- **429** — Too many requests. There are generous limits per key and per client address; a client that exceeds them gets `429` with a `Retry-After` header (seconds). Send batches instead of single logs, and wait before retrying.
- **500** — Server error — retry later.

- Log filtering & search: https://abrova.ir/en/docs/trace/log-search

Find logs quickly with powerful filters on the **Abrova Trace → Logs** page in Abrova Console. Combine log level, source, environment, time range, and text search to drill down to exactly what you need.

### Filter by Log Level

Click the level chips above the log list to show or hide each level; at least one level stays on. Each chip shows how many lines of that level are in the current range.

- **fatal** — Crashes and unrecoverable failures
- **error** — Errors that need immediate attention
- **warning** — Warnings about potential issues (stored as `warn`)
- **info** — General information about application behavior
- **debug** — Detailed debugging information
- **trace** — Very detailed trace logs for deep debugging

### Filter by Source

Pick a source in the **Sources** panel to see only its lines; ⌘/Ctrl-click adds more sources to the selection (on phones, use the **All sources** button). Sources are automatically created when logs are received.

Example sources: `nginx`, `api-server`, `worker`, `database`, `cache`.

### Text Search

Search is case-insensitive and matches any part of the log message, its metadata or its source. Switch on the regex toggle in the search box to match the message with a regular expression instead (case-insensitive, applied in your browser to the lines already loaded).

- `timeout` — Find all logs mentioning "timeout"
- `user_123` — Find logs for a specific user
- `500` — Find HTTP 500 errors
- `connection refused` — Find connection errors

### Time Range

Choose from preset ranges to scope your search:

- **Last 1 hour** (default)
- **Last 24 hours**
- **Last 7 days**
- **Last 30 days**

Logs are kept for 7 days unless you add 30-day retention (+50,000 Toman per project a month from your wallet), so longer ranges only show what is still kept.

Use the **Environment** dropdown to narrow to one environment.

### Dashboard Features

- **Level Counts** — Each level chip shows its line count at a glance
- **Live Stream** — New lines stream in as they arrive (the latest 1,000 are kept on screen); pause the stream to scroll and load older lines
- **Stream and Columns Views** — Read one merged stream, or compare up to 4 sources side by side
- **Log Details** — Click any log to see the full message and metadata

Saving a search needs the member role or higher; deleting logs or sources needs admin or owner. See [Roles & Permissions](/docs/trace/error-dashboard#roles).

- Ignore rules: https://abrova.ir/en/docs/trace/ignore-rules

<BestPracticeList columns={2} items={[
  ['What are Ignore Rules?', "Ignore Rules drop errors you never want to see — like \"ResizeObserver loop limit exceeded\" or a browser extension's noise — before they reach your Issues inbox."],
]} />

<Callout kind="wallet" title="Included">Ignore Rules are included for every project at no cost. Dropped errors never become new issues, so they do not use your free allowance or your wallet.</Callout>

### Ignore Rules

A rule is a pattern tested against the **error message** of every new error your SDKs send. Rules belong to the Abrova project, so one rule applies to all of its platforms (iOS, Android, Flutter, web, server).

#### Creating an Ignore Rule

1. In Abrova Console, open **Trace → Ignore rules**
2. Click **"New rule"**
3. Pick a **Match** type — Contains, Exact or Regex — and type the **Message pattern**
4. Check the preview: it shows how many issues from the last 30 days the pattern would have matched (tested in your browser against your latest issues)
5. Click **"Save rule"**

Managing rules (add, edit, switch on/off, delete) needs the **admin** or **owner** role; every role can view them. See [Roles & Permissions](/docs/trace/error-dashboard#roles).

#### Match Types

Matching is case-insensitive.

<div>
  <table>
    <thead>
      <tr>
        {['Type', 'Description', 'Example'].map((h) => (
          <th key={h}>{h}</th>
        ))}
      </tr>
    </thead>
    <tbody>
      {[
        ['Contains', 'Pattern appears anywhere in the message', 'ResizeObserver loop matches "ResizeObserver loop limit exceeded"'],
        ['Exact', 'The whole message must equal the pattern', 'Network Error matches only "Network Error"'],
        ['Regex', 'JavaScript regular expression tested against the message', '^ChunkLoadError: Loading chunk \\d+ failed'],
      ].map(([type, desc, ex]) => (
        <tr key={type}>
          <td>{type}</td>
          <td>{desc}</td>
          <td><code>{ex}</code></td>
        </tr>
      ))}
    </tbody>
  </table>
</div>

Rules match the error message only. Matching by URL, platform or environment isn't supported in the Console.

#### Managing Ignore Rules

- **Turn on/off:** Each rule has a switch, so you can disable it without deleting it.
- **Edit:** Change a rule's match type or pattern.
- **Delete:** Remove a rule; errors matching it will reach your inbox again.

<Callout kind="note" title="Note">Ignored errors are dropped at ingest: they are not stored, don't create or update issues, and don't trigger alerts. Rules only affect new errors — existing issues are not removed. Messages sent with captureMessage are not affected.</Callout>

- Mark all resolved: https://abrova.ir/en/docs/trace/mark-all-resolved

<BestPracticeList columns={2} items={[
  ['What is Mark All Resolved?', "A quick action to mark all currently active errors as resolved in a single click. Perfect for after deployments or when you've addressed multiple issues at once."],
]} />

<Callout kind="wallet" title="Included">Mark All Resolved is included for every project at no cost.</Callout>

### Mark All Resolved

A quick action to mark all currently active errors as resolved in a single click — perfect for after deployments or when you've addressed multiple issues at once.

#### How to Use

1. In Abrova Console, open **Trace → Issues**
2. Open the **More actions** (**⋯**) menu next to the page title and choose **"Resolve all open issues…"**
3. A confirmation dialog appears — click **"Resolve all"**
4. Every open and in-progress issue in the project (all platforms) is marked resolved. The current list filters are not applied.

This action needs the member role or higher; viewers do not see it. See [Roles & Permissions](/docs/trace/error-dashboard#roles).

#### Understanding Error States

<div>
  {[
    { state: 'Open / In progress', color: 'bg-red-900/20 border-red-200', desc: 'Issues that need attention. New issues start as Open and appear in the default Issues view.' },
    { state: 'Resolved', color: 'bg-emerald-900/20 border-emerald-800', desc: 'Issues that have been fixed. New events still increase their count, but the issue stays resolved.' },
    { state: 'Ignored / Archived', color: 'bg-orange-900/20 border-orange-800', desc: 'Issues you have set aside. You can reopen any issue from its status menu.' },
  ].map((s) => (
    <div key={s.state}>
      <strong>{s.state}</strong>
      <p>{s.desc}</p>
    </div>
  ))}
</div>

#### When to Use

<BestPracticeList items={[
  ['After Deployment', "When you've deployed fixes for multiple errors, mark them all resolved to start fresh."],
  ['Sprint Cleanup', 'At the end of a sprint, resolve all errors that were addressed during development.'],
  ['Fresh Start', "Starting a new phase? Mark old errors as resolved to focus on what's new."],
  ['Migration Complete', 'After completing a major migration or refactoring, clear the slate.'],
]} />

#### What Happens When You Resolve All?

<ul>
  <li><span>{'✓'}</span> All open and in-progress issues are moved to "Resolved" status</li>
  <li><span>{'✓'}</span> Integration notifications (Slack, Email, etc.) are only sent for brand-new issues, so resolved issues don't notify again</li>
  <li><span>{'✓'}</span> Error history and occurrence count are preserved</li>
  <li><span>{'✓'}</span> Resolved issues can be viewed by filtering Issues by status</li>
  <li><span>!</span> If the error occurs again, its count and last seen time update but it is not reopened automatically — reopen it yourself if needed</li>
</ul>

#### Individual vs Bulk Resolution

<div>
  <table>
    <thead>
      <tr>
        {['Action', 'Use When', 'How'].map((h) => (
          <th key={h}>{h}</th>
        ))}
      </tr>
    </thead>
    <tbody>
      <tr>
        <td>Resolve Single Error</td>
        <td>You've fixed one specific issue</td>
        <td>Open the issue → "Resolve" (shortcut R)</td>
      </tr>
      <tr>
        <td>Resolve All</td>
        <td>Multiple fixes deployed at once</td>
        <td>Issues → ⋯ → "Resolve all open issues…"</td>
      </tr>
    </tbody>
  </table>
</div>

#### Best Practices

<BestPracticeList items={[
  ['Review Before Resolving', 'Quickly scan the list to ensure there are no critical unaddressed issues'],
  ['Watch Last Seen', 'Resolved issues are not reopened automatically — check the Resolved filter for issues whose last seen is after you resolved them'],
  ['Use with Ignore Rules', 'Combine with Ignore Rules so known noise is dropped before it ever becomes an issue'],
]} />

- Weekly e-mail digest: https://abrova.ir/en/docs/trace/weekly-digest

<BestPracticeList columns={2} items={[
  ['What is Weekly Digest?', "Every Monday at 9:00 AM New York time (16:30 Tehran time, 17:30 while New York is on winter time), you'll receive an email summary of your errors from the past week. Stay informed about your application's health without checking the dashboard constantly."],
]} />

<Callout kind="wallet" title="Included">The Weekly Email Digest is included in Abrova Trace at no extra cost — see [Pricing](/pricing).</Callout>

### Weekly Email Digest

Every Monday at 9:00 AM New York time, you'll receive an email summary of your errors from the past week — new, resolved and open issues, occurrences, the week-over-week trend and the top errors. Stay informed about your application's health without checking the dashboard constantly.

#### What's in the Digest?

<BestPracticeList items={[
  ['New Errors', 'Issues first seen in the past 7 days'],
  ['Resolved', 'Issues marked as resolved in the past 7 days'],
  ['Open', 'Issues currently open'],
  ['Occurrences', 'Total event count of the issues seen in the past 7 days'],
  ['Trend Comparison', 'New errors compared with the previous week'],
  ['Top Errors', 'Top 5 issues seen this week, ranked by their total event count, with their status'],
]} />

#### Example Digest Email

<div>
  <div>
    <p><strong>Subject:</strong> {'\u{1F4CA}'} Your Weekly Error Report - Dec 15</p>
  </div>
  <div>
    <h4>{'\u{1F4CA}'} Your Weekly Error Report</h4>
    <p>Week of December 15, 2025</p>
    <div>
      <div>
        <p>8</p>
        <p>New Errors</p>
      </div>
      <div>
        <p>12</p>
        <p>Resolved</p>
      </div>
      <div>
        <p>5</p>
        <p>Open</p>
      </div>
      <div>
        <p>47</p>
        <p>Occurrences</p>
      </div>
    </div>
    <p>{'↑'} 33% more than last week</p>
    <div>
      <p>Top Errors This Week:</p>
      <div>
        <p>1. TypeError: Cannot read 'map' of undefined — <strong>23</strong> · open</p>
        <p>2. NetworkError: Failed to fetch — <strong>15</strong> · resolved</p>
        <p>3. ReferenceError: user is not defined — <strong>9</strong> · open</p>
      </div>
    </div>
  </div>
</div>

#### How It Works

1. **Automatic Collection:** AbrovaTrace automatically collects all error data throughout the week
2. **Weekly Processing:** Every Monday at 9:00 AM New York time (afternoon in Tehran), we compile your error statistics across your projects
3. **Email Delivery:** A formatted summary is sent to the project owner's email address

#### Managing Your Digest

The digest is sent automatically; there is no separate on/off setting in Abrova Console.

<Callout kind="note" title="Note">The digest is sent even in a quiet week — if there were no errors, the Top Errors section says so.</Callout>

- Spike detection alerts: https://abrova.ir/en/docs/trace/spike-detection

<BestPracticeList columns={2} items={[
  ['What is Spike Detection?', "AbrovaTrace monitors how fast new issues appear and automatically detects when that rate spikes above normal levels. When a spike is detected, an alert goes to your project's active integrations so you can investigate before it affects more users."],
]} />

<Callout kind="wallet" title="Included">Spike Detection Alerts are included in Abrova Trace at no extra cost — see [Pricing](/pricing).</Callout>

### Spike Detection

Automatically detects when the number of new issues in the last hour reaches 200% (2x) or more of the hourly baseline and sends an alert through your project's integrations — so you can investigate before the spike affects more users.

#### How It Works

1. **Continuous Monitoring** — Every 15 minutes, AbrovaTrace counts new issues (errors seen for the first time) per project and platform.
2. **Baseline Comparison** — The number of new issues in the last hour is compared with the hourly average of the 23 hours before it.
3. **Spike Detection** — If the last hour has at least 3 new issues and reaches 200% (2x) or more of the baseline, a spike is detected. With no baseline at all, more than 5 new issues in the last hour counts as a spike.
4. **Alert Sent** — A notification is sent to every active integration of the project (Email, Slack, Discord, Telegram, Webhook, GitHub). If you have no integrations set up, no alert is sent.

#### Visual Example

New issues suddenly jump to 5 in the last hour when the baseline was 1 per hour:

<div>
  <div>
    {[
      { label: '09:00', h: 20, spike: false },
      { label: '10:00', h: 20, spike: false },
      { label: '11:00', h: 20, spike: false },
      { label: '12:00', h: 20, spike: false },
      { label: '13:00', h: 100, spike: true },
    ].map((bar) => (
      <div key={bar.label}>
        {bar.spike && <span>SPIKE!</span>}
        <div style={{ height: `${bar.h}%` }} />
        <span>{bar.label}</span>
      </div>
    ))}
  </div>
  <div>
    <div><div /> Normal (~1/hour)</div>
    <div><div /> Spike (5/hour)</div>
  </div>
</div>

<Callout kind="note" title="Spike Detected!">5 new issues in the last hour is 500% of the baseline (1 per hour). Since this exceeds the 200% threshold, an alert is triggered.</Callout>

#### Alert Email Preview (Email integration)

<div>
  <div>
    <p><strong>Subject:</strong> [AbrovaTrace] New Error: {'\u{1F6A8}'} Error Spike Detected: 500% increase in error rate</p>
  </div>
  <div>
    <p>{'\u{1F6A8}'} Error Spike Detected: 500% increase in error rate</p>
    <p>Project: My Flutter App</p>
    <div>
      <div>
        <p>5</p>
        <p>Occurrences (new issues, last hour)</p>
      </div>
      <div>
        <p>~1</p>
        <p>Baseline (avg/hour)</p>
      </div>
    </div>
    <p>Error rate increased from ~1/hour to 5/hour</p>
  </div>
</div>

#### Configuration

Spike detection runs automatically for every project. There is nothing to switch on. Current settings:

<ConfigTable rows={[
  ['Check Interval', '-', '-', 'Every 15 minutes'],
  ['Spike Threshold', '-', '-', '200% (2x) of baseline, at least 3 new issues'],
  ['Comparison Window', '-', '-', 'Last 1 hour'],
  ['Baseline Window', '-', '-', 'Hourly average of the previous 23 hours'],
  ['Alert Method', '-', '-', "The project's active integrations"],
]} />

Need your own threshold, window or channels? Create an **Error spike** rule under **Trace → Alerts**. Managing alert rules needs the admin or owner role; members can acknowledge and mute alerts — see [Roles & Permissions](/docs/trace/error-dashboard#roles).

#### Best Practices

<BestPracticeList items={[
  ['Respond Quickly', 'When you receive a spike alert, investigate immediately. Check recent deployments, third-party services, or infrastructure issues.'],
  ['Set Up Integrations', 'Spike alerts go only to integrations — configure Email or a Webhook under Trace → Integrations. Email and webhooks work without a connection outside Iran.'],
  ['Use with Ignore Rules', 'Combine with Ignore Rules to filter out known errors and reduce false spike alerts.'],
]} />

#### Troubleshooting

<TroubleshootItem title="No spike alert arrived?">
  <ul>
    <li>Check that the project has at least one integration and that it is switched on in Trace → Integrations</li>
    <li>Use "Send test" on the integration to confirm it delivers</li>
    <li>Spikes count <strong>new issues</strong>, not repeated events of an issue you already have — a flood of the same error does not count as a spike</li>
    <li>The last hour needs at least 3 new issues. A brand-new project has no baseline yet: then more than 5 new issues in the last hour count as a spike</li>
    <li>Integrations that deliver to Slack, Discord, Telegram or GitHub need those services to be reachable — see each integration's page</li>
  </ul>
</TroubleshootItem>

- Cron monitoring: https://abrova.ir/en/docs/trace/cron-monitoring

<BestPracticeList columns={2} items={[
  ['Cron Monitoring', 'Monitor your scheduled jobs and cron tasks. Abrova Trace notifies you through your configured integrations when a check-in is missed, and records failed runs. No SDK required — any HTTP client can send check-ins.'],
]} />

<Callout kind="wallet" title="Free monitors">
  3 cron monitors are free every month. Each extra monitor costs 2,000 Toman a month from your wallet — see [Pricing](/pricing). Check-ins themselves cost nothing.
</Callout>

<Callout kind="secret">Check-ins send your server secret (`ab_srv_…`) in the `X-API-Key` header. Run them from your server or CI, from an environment variable — never from an app.</Callout>

### Cron Monitoring

Monitor scheduled jobs and cron tasks with HTTP check-ins. Missed check-ins notify you through Email, webhooks or your other integrations; failed runs are recorded and shown on the monitor. No SDK required — any HTTP client can send check-ins.

#### How It Works

1. **Create a Monitor** — Define a cron monitor in Abrova Console with a unique slug, a schedule (cron expression or interval), and a grace period.
2. **Send Check-Ins** — Your cron job sends an HTTP POST to the check-in API when it runs. No SDK needed — just a simple HTTP call.
3. **Detect Missed Jobs** — AbrovaTrace evaluates all monitors every 5 minutes. If a check-in is overdue (past expected interval + grace period), the monitor status changes to "missed".
4. **Get Notified** — When a job is missed, notifications are sent to the integrations you selected on the monitor (Email, Webhook, etc.).

#### Create a Monitor (Dashboard)

1. In Abrova Console, open your project → **Trace → Crons**
2. Click **"New monitor"**
3. Fill in the monitor details (see configuration below)
4. Optionally select notification channels from your active integrations
5. Click **"Create monitor"** to save

Managing monitors (create, edit, pause, delete) needs the **admin** or **owner** role; every role can see monitors and their check-in history. See [Roles & Permissions](/docs/trace/error-dashboard#roles).

#### Monitor Configuration

<ConfigTable rows={[
  ['Name', 'string', 'Yes', 'Descriptive name (e.g., "Daily Database Backup")'],
  ['Slug', 'string', 'Yes', 'Unique identifier used in check-in API (e.g., "daily-backup"). Auto-generated from name.'],
  ['Schedule', 'string', 'No', 'Cron expression (e.g., "0 2 * * *"). When set, it decides the expected interval.'],
  ['Expected Interval', 'number', 'Yes', 'How often the job should run, in minutes (default: 60). Used when no cron expression is set.'],
  ['Grace Period', 'number', 'Yes', 'Extra minutes to wait before marking as missed (default: 5)'],
  ['Environment', 'string', 'No', 'Filter by environment (e.g., production)'],
  ['Notification Channels', 'multi-select', 'No', 'Select from your active integrations'],
]} />

#### Send Check-Ins from Your Jobs

When your cron job runs, send an HTTP POST to the check-in endpoint. Authenticate with your project's **server secret** (`ab_srv_...`) in the `X-API-Key` header. The monitor will be **auto-created** if the slug doesn't exist yet.

<Callout kind="note" title="Which key?">
  Cron jobs run on your servers, so use the server secret. The app key (<code>ab_live_...</code>) is also accepted while the project setting <strong>Server routes require the server secret</strong> is off — but it ships inside your apps, so anyone who extracts it could send a fake "ok" check-in. Switch the setting on once your jobs use the server secret. See <a href="/docs/trace/server-secret">Server Secret &amp; Server Routes</a>.
</Callout>

<Callout kind="note" title="Auto-Create Monitors">
  If you send a check-in with a slug that doesn't exist, AbrovaTrace will automatically create a monitor with default settings (60-minute interval, 5-minute grace period). You can then customize it in the dashboard.
</Callout>

#### Check-In API

<Endpoint method="POST" url="https://trace.abrova.ir/api/cron-monitors/check-in" />

<div>
  <table>
    <thead>
      <tr>
        {['Field', 'Type', 'Required', 'Description'].map((h) => (
          <th key={h}>{h}</th>
        ))}
      </tr>
    </thead>
    <tbody>
      {[
        ['monitor_slug', 'string', 'Yes', 'The unique slug of the monitor'],
        ['status', 'string', 'Yes', '"ok", "error", or "in_progress"'],
        ['check_in_id', 'string', 'No', 'UUID to track multi-step jobs (returned as `id` from in_progress)'],
        ['duration_ms', 'number', 'No', 'How long the job took in milliseconds'],
        ['environment', 'string', 'No', 'Environment name (e.g., "production")'],
        ['message', 'string', 'No', 'Optional message or error details'],
      ].map(([field, type, required, desc]) => (
        <tr key={field}>
          <td><code>{field}</code></td>
          <td>{type}</td>
          <td>{required === 'Yes' ? <span>Yes</span> : <span>No</span>}</td>
          <td>{desc}</td>
        </tr>
      ))}
    </tbody>
  </table>
</div>

#### Examples

#### Simple Check-In (curl)

Send a single "ok" check-in when your job completes successfully:

```bash
curl -X POST https://trace.abrova.ir/api/cron-monitors/check-in \
  -H "X-API-Key: ab_srv_your_server_secret" \
  -H "Content-Type: application/json" \
  -d '{
    "monitor_slug": "daily-backup",
    "status": "ok",
    "duration_ms": 4500
  }'
```

#### Report an Error (curl)

If the job fails, report it with "error" status:

```bash
curl -X POST https://trace.abrova.ir/api/cron-monitors/check-in \
  -H "X-API-Key: ab_srv_your_server_secret" \
  -H "Content-Type: application/json" \
  -d '{
    "monitor_slug": "daily-backup",
    "status": "error",
    "message": "Connection to database timed out"
  }'
```

#### Multi-Step Job (curl)

For long-running jobs, start with "in_progress" and complete with "ok" or "error":

<CodeBlock language="bash" code={`# Step 1: Mark job as in_progress (returns a check_in_id)
CHECK_IN_ID=$(curl -s -X POST https://trace.abrova.ir/api/cron-monitors/check-in \\
  -H "X-API-Key: ab_srv_your_server_secret" \\
  -H "Content-Type: application/json" \\
  -d '{"monitor_slug": "nightly-report", "status": "in_progress"}' \\
  | jq -r '.id')

# ... run your job ...

# Step 2: Mark job as complete
curl -X POST https://trace.abrova.ir/api/cron-monitors/check-in \\
  -H "X-API-Key: ab_srv_your_server_secret" \\
  -H "Content-Type: application/json" \\
  -d "{
    \\"monitor_slug\\": \\"nightly-report\\",
    \\"status\\": \\"ok\\",
    \\"check_in_id\\": \\"$CHECK_IN_ID\\",
    \\"duration_ms\\": 120000
  }"`} />

#### Node.js

```javascript
const axios = require('axios');

const API_KEY = process.env.ABROVA_SERVER_SECRET; // ab_srv_...
const BASE_URL = 'https://trace.abrova.ir/api/cron-monitors/check-in';

async function runDailyBackup() {
  const start = Date.now();

  try {
    // ... your backup logic here ...
    await performBackup();

    // Report success
    await axios.post(BASE_URL, {
      monitor_slug: 'daily-backup',
      status: 'ok',
      duration_ms: Date.now() - start,
    }, { headers: { 'X-API-Key': API_KEY } });

  } catch (error) {
    // Report failure
    await axios.post(BASE_URL, {
      monitor_slug: 'daily-backup',
      status: 'error',
      duration_ms: Date.now() - start,
      message: error.message,
    }, { headers: { 'X-API-Key': API_KEY } });
  }
}
```

#### Python

```python
import os
import requests
import time

API_KEY = os.environ["ABROVA_SERVER_SECRET"]  # ab_srv_...
BASE_URL = "https://trace.abrova.ir/api/cron-monitors/check-in"

def run_daily_backup():
    start = time.time()
    headers = {"X-API-Key": API_KEY, "Content-Type": "application/json"}

    try:
        # ... your backup logic here ...
        perform_backup()

        # Report success
        requests.post(BASE_URL, json={
            "monitor_slug": "daily-backup",
            "status": "ok",
            "duration_ms": int((time.time() - start) * 1000),
        }, headers=headers)

    except Exception as e:
        # Report failure
        requests.post(BASE_URL, json={
            "monitor_slug": "daily-backup",
            "status": "error",
            "duration_ms": int((time.time() - start) * 1000),
            "message": str(e),
        }, headers=headers)
```

#### Laravel (Artisan Command)

<CodeBlock language="php" code={`<?php
// In your scheduled command or Kernel.php

use Illuminate\\Support\\Facades\\Http;

$start = microtime(true);

try {
    // ... your job logic ...
    $this->performCleanup();

    Http::withHeaders([
        'X-API-Key' => env('ABROVATRACE_SERVER_SECRET'),
    ])->post('https://trace.abrova.ir/api/cron-monitors/check-in', [
        'monitor_slug' => 'daily-cleanup',
        'status' => 'ok',
        'duration_ms' => (int)((microtime(true) - $start) * 1000),
    ]);

} catch (\\Exception $e) {
    Http::withHeaders([
        'X-API-Key' => env('ABROVATRACE_SERVER_SECRET'),
    ])->post('https://trace.abrova.ir/api/cron-monitors/check-in', [
        'monitor_slug' => 'daily-cleanup',
        'status' => 'error',
        'message' => $e->getMessage(),
    ]);
}`} />

#### Bash Script

Wrap any cron job with a simple check-in call at the end:

```bash
#!/bin/bash
# Add this to the end of your cron job script

API_KEY="$ABROVA_SERVER_SECRET"   # ab_srv_...

# Run your job
/usr/local/bin/my-backup-script.sh

# Report based on exit code
if [ $? -eq 0 ]; then
  curl -s -X POST https://trace.abrova.ir/api/cron-monitors/check-in \
    -H "X-API-Key: $API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"monitor_slug": "my-backup", "status": "ok"}'
else
  curl -s -X POST https://trace.abrova.ir/api/cron-monitors/check-in \
    -H "X-API-Key: $API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"monitor_slug": "my-backup", "status": "error"}'
fi
```

#### Monitor Statuses

<div>
  {[
    { status: 'OK', color: 'bg-emerald-900/20 border-emerald-800 text-emerald-400', desc: 'Last check-in was successful' },
    { status: 'Error', color: 'bg-red-900/20 border-red-800 text-red-400', desc: 'Last check-in reported an error' },
    { status: 'Missed', color: 'bg-amber-900/20 border-amber-800 text-amber-400', desc: 'No check-in received within expected time' },
    { status: 'Disabled', color: 'bg-white/[0.05] border-white/[0.08] text-zinc-500', desc: 'Monitor is paused' },
  ].map((s) => (
    <div key={s.status}>
      <strong>{s.status}</strong>
      <p>{s.desc}</p>
    </div>
  ))}
</div>

#### API Reference

Your cron job sends check-ins to one public endpoint:

```
POST /api/cron-monitors/check-in
```

It takes a project credential in the `X-API-Key` header: the **server secret** (recommended), or the app key while the "Server routes require the server secret" setting is off.

Manage monitors in Abrova Console. What a signed-in user may do there depends on their role — see <a href="/docs/trace/error-dashboard#roles">Roles &amp; Permissions</a>.

#### Best Practices

<BestPracticeList items={[
  ['Use Descriptive Slugs', 'Choose slugs like "daily-backup", "hourly-sync", or "weekly-report" that clearly identify the job.'],
  ['Set Appropriate Grace Periods', 'Give enough buffer for natural job duration variation. A 5-minute grace period works for most jobs; use longer for jobs with variable runtimes.'],
  ['Report Errors, Not Just Success', 'Always send a check-in with status "error" when a job fails. This gives you visibility into both missed and failed jobs.'],
  ['Track Duration', 'Include duration_ms in your check-ins to spot performance degradation over time.'],
  ['Use Multi-Step for Long Jobs', 'For jobs that take minutes or hours, use in_progress + ok/error pattern. This lets you distinguish between "still running" and "missed".'],
  ['Configure Notifications', 'Connect at least one integration (Email or a Webhook work without a connection outside Iran) to get alerted when jobs are missed.'],
]} />

#### Troubleshooting

<TroubleshootItem title="Monitor shows as missed but job ran?">
  <ul>
    <li>Verify the key is correct and active — check the HTTP status of the check-in; a 401 means it was refused</li>
    <li>Check that the <code>monitor_slug</code> matches exactly</li>
    <li>Ensure the check-in request is reaching the server (check network/firewall)</li>
    <li>Review the expected interval — if your job runs every 24 hours, set the interval to 1440 minutes</li>
    <li>Check the grace period — increase it if your job has variable start times</li>
  </ul>
</TroubleshootItem>

<TroubleshootItem title="Not receiving missed notifications?">
  <ul>
    <li>Verify notification channels are selected on the monitor</li>
    <li>Check that the selected integrations are active (test them in Trace → Integrations)</li>
    <li>Missed detection runs every 5 minutes — there may be a short delay</li>
    <li>Ensure the monitor is enabled (not disabled/toggled off)</li>
  </ul>
</TroubleshootItem>

<TroubleshootItem title="Check-in API returns 401?">
  <ul>
    <li>Verify the key starts with <code>ab_srv_</code> (or <code>ab_live_</code>)</li>
    <li>If the response says <code>server_credential_required</code>, the project setting <strong>Server routes require the server secret</strong> is on and the job sent the app key — use the server secret</li>
    <li>Check that the key is being sent in the <code>X-API-Key</code> header</li>
    <li>Ensure the API key belongs to an active project with Trace enabled</li>
  </ul>
</TroubleshootItem>

<TroubleshootItem title="Cannot create another monitor?">
  <ul>
    <li>3 monitors are free; more monitors are paid from your organisation's wallet (2,000 Toman per extra monitor a month)</li>
    <li>Top up the wallet in Abrova Console, or delete a monitor you no longer need</li>
  </ul>
</TroubleshootItem>

<TroubleshootItem title="Auto-created monitor has wrong settings?">
  <ul>
    <li>Auto-created monitors use defaults (60 min interval, 5 min grace)</li>
    <li>Go to Trace → Crons in Abrova Console and edit the monitor</li>
    <li>Alternatively, create the monitor in the dashboard first with your desired settings</li>
  </ul>
</TroubleshootItem>

- Server secret & server routes: https://abrova.ir/en/docs/trace/server-secret

Every Abrova project has two credentials. This page explains which one belongs where, and how to make the routes that only your servers use accept the server secret only.

### The two credentials

<ConfigTable headers={['Credential', 'Looks like', 'Where it lives']} rows={[
  ['App key', 'ab_live_...', 'Inside your mobile and web apps. It ships with the app, so anyone who has the app can extract it.'],
  ['Server secret', 'ab_srv_...', 'Only on your servers: the log agent, cron jobs, deploy scripts and backend SDKs. Never put it in an app or in code that runs in a browser.'],
]} />

Both are in Abrova Console under **Project settings → Keys**. The server secret is shown once, when you create or rotate it — store it in your secret manager or server environment.

### What the setting does

**Server routes require the server secret** is a per-project switch in Abrova Console under **Project settings → Products → Abrova Trace**. It is **off by default**.

When it is **on**, the routes that only servers and agents call accept the server secret only. A request that carries just the app key is refused there with `401`:

<ConfigTable headers={['Route', 'Used by', 'With the setting on']} rows={[
  ['Log agent connection', 'Abrova Trace Agent', 'Server secret required'],
  ['Container registration and status', 'Abrova Trace Agent', 'Server secret required'],
  ['POST /api/cron-monitors/check-in', 'Your cron jobs', 'Server secret required'],
  ['POST /api/logs/deploys', 'Your deploy scripts', 'Server secret required'],
  ['POST /api/logs/ingest and /api/logs/ingest/batch', 'Apps, servers and the agent', 'Not affected — the app key keeps working'],
  ['Errors, messages and performance data', 'Your apps and SDKs', 'Not affected — the app key keeps working'],
]} />

Nothing changes for your apps: errors, messages, performance data and logs sent with the app key keep working whether the setting is on or off.

### Why you would switch it on

The app key is public by nature. Without this setting, someone who extracted it from your app could:

- send a fake "job succeeded" cron check-in, hiding a job that is failing or not running,
- write fake deploy markers,
- connect as a fake log agent.

With the setting on, the app key is no longer enough for any of these.

**Switch it on when** you run the log agent, use cron monitoring, or send deploy markers. A project that only uses the mobile and web SDKs does not need it.

<H2 id="give-your-servers-the-server-secret" step={1}>Give your servers the server secret</H2>

There are two ways to send the server secret over HTTP. Both work on every route in the table above:

- Use the server secret **as the key**: `x-api-key: ab_srv_...`
- Keep the app key in `x-api-key` and add the server secret in a second header: `x-server-secret: ab_srv_...`

#### Log agent

The agent takes one credential, in `ABROVA_TRACE_API_KEY`. Set it to the server secret and redeploy the agent:

```bash
docker run -d \
  --name abrova-trace-agent \
  --restart=always \
  -v /var/run/docker.sock:/var/run/docker.sock:ro \
  -e ABROVA_TRACE_API_KEY=ab_srv_your_server_secret \
  ghcr.io/abrova-co/abrova-trace-agent:latest
```

In a multi-host setup only the collector holds the credential; remote agents need no change. The Abrova [desktop app](/desktop) (coming soon) will also deploy the agent; it will ask for this key. See [Abrova Trace Agent](/docs/trace/agent).

#### Cron check-ins

```bash
curl -X POST https://trace.abrova.ir/api/cron-monitors/check-in \
  -H "X-API-Key: ab_srv_your_server_secret" \
  -H "Content-Type: application/json" \
  -d '{"monitor_slug": "daily-backup", "status": "ok"}'
```

See [Cron Monitoring](/docs/trace/cron-monitoring).

#### Deploy markers

A deploy marker tells Abrova Trace "a deploy happened now", so the Logs page can show what is new since the last deploy. Call it at the end of your deploy script. Every field is optional:

```bash
curl -X POST https://trace.abrova.ir/api/logs/deploys \
  -H "x-api-key: ab_srv_your_server_secret" \
  -H "Content-Type: application/json" \
  -d '{
    "version": "1.4.2",
    "environment": "production",
    "source": "api-server",
    "description": "Checkout fixes"
  }'
```

<ConfigTable rows={[
  ['version', 'string', 'No', 'The version or commit you deployed'],
  ['environment', 'string', 'No', 'Environment (default: production)'],
  ['source', 'string', 'No', 'What was deployed, e.g. the service name'],
  ['description', 'string', 'No', 'Free text'],
  ['deployedAt', 'string', 'No', 'ISO 8601 timestamp (default: now)'],
]} />

Response (`201`): <code>{`{"success": true, "deploy": { ... }}`}</code>

#### Logs sent from your servers

The [Logs REST API](/docs/trace/logs-rest-api) is never refused because of this setting, but a server should still authenticate with the server secret rather than the app key. The Node.js and Laravel SDKs already send the server secret you configure them with.

<H2 id="check-that-nothing-still-uses-the-app-key" step={2}>Check that nothing still uses the app key</H2>

In Abrova Console, open **Project settings → Products → Abrova Trace**. The line under the switch tells you how recent requests on the server routes authenticated (last 30 days):

- **"N requests in the last 30 days used the app key on server routes."** — something still sends the app key. Find it and move it to the server secret first.
- **"Ready: every request on server routes in the last 30 days used the server secret."** — safe to switch on.
- **"No requests on server routes in the last 30 days."** — nothing uses these routes yet; switching on affects nobody.

<H2 id="switch-it-on" step={3}>Switch it on</H2>

Turn on **Server routes require the server secret** and save. From then on, a request on a server route without the server secret gets:

```json
{
  "error": "Server credential required",
  "code": "server_credential_required"
}
```

A request that sends a wrong `x-server-secret` gets `401` with `"code": "server_credential_invalid"`.

You can switch the setting off again at any time; the app key is then accepted on these routes as before.

### Troubleshooting

<TroubleshootItem title="Cron check-ins or deploy markers return 401 after switching on">
  <p>The job still sends the app key. Replace it with the server secret (<code>ab_srv_...</code>) in the <code>X-API-Key</code> header, or add an <code>x-server-secret</code> header. Until then the monitor shows the job as missed.</p>
</TroubleshootItem>

<TroubleshootItem title="Containers stop updating or can't be controlled after switching on">
  <p>The agent still runs with the app key. Log lines keep arriving, but the agent can no longer register containers, report their status or receive commands. Redeploy it with <code>ABROVA_TRACE_API_KEY</code> set to the server secret.</p>
</TroubleshootItem>

<TroubleshootItem title="I rotated the server secret">
  <p>Update it everywhere it is used: the agent, cron jobs, deploy scripts and backend SDK configuration. The old secret stops working when you rotate.</p>
</TroubleshootItem>

- E-mail: https://abrova.ir/en/docs/trace/email

Get error alerts delivered to your inbox. Configure the recipients for email notifications from AbrovaTrace.

<Callout kind="note" title="What you'll need">
  <ul>
    <li>Email addresses to receive notifications</li>
    <li>Owner or admin access to the project</li>
  </ul>
</Callout>

<Callout kind="tip" title="Works inside Iran">Email is a good default channel in Iran: it needs no chat service outside the country, and it works with any mailbox your team uses, including Iranian mail providers.</Callout>

Which channels your project can use is shown on the **Trace → Integrations** page in Abrova Console.

<H2 id="set-up-email-integration" step={1}>Set Up Email Integration</H2>

1. In Abrova Console, open **Trace → Integrations** (integrations belong to the selected project)
2. Click **"Add integration"** and choose **Email** (or **"Connect"** on the Email card)
3. Enter a **Name** and fill in the configuration fields
4. Click **"Save channel"** — or **"Save and send test"** to save and verify it

<ConfigTable rows={[
  ['Name', 'string', 'Yes', 'Friendly name (e.g., "On-call team")'],
  ['Recipients', 'string', 'Yes', 'One or more addresses (up to 50) — press Enter or comma after each'],
]} />

Managing integrations (add, edit, switch on/off, delete, test) needs the **admin** or **owner** role; every role can see them and their delivery log. See [Roles & Permissions](/docs/trace/error-dashboard#roles).

### Configuration Examples

- **Single Recipient** — To: `dev@company.com`
- **Multiple Recipients** — To: `dev@co.com`, `ops@co.com`, `team@co.com`
- **Distribution List** — To: `alerts@company.com`

### Email Format

Each notification email contains:

- **Subject** — `[AbrovaTrace] New Error: TypeError: Cannot read property 'map' of undefined`
- Error message and stack trace
- Project name and environment
- When the error first occurred
- Number of occurrences
- Page URL and user agent, when the error has them
- A link to view the error

New-error emails are sent the first time an error is seen. Spike detection also emails these recipients, and alert rules and cron monitors do when you pick this channel for them.

### Best Practices

<BestPracticeList items={[
  ['Use Team Distribution Lists', 'team@company.com instead of individual addresses'],
  ['Filter on the Subject', 'Every email subject starts with [AbrovaTrace], which makes inbox rules easy'],
  ['Set Up Email Filters', 'Create filters in your mail app to organize AbrovaTrace notifications'],
  ['Multiple Integrations for Teams', 'Separate integrations for frontend team, backend team, etc.'],
]} />

### Troubleshooting

<TroubleshootItem title="Not receiving emails?">
  <ul>
    <li>Check your spam/junk folder</li>
    <li>Verify email addresses are correct (no typos)</li>
    <li>Make sure the integration is switched on in Trace → Integrations</li>
    <li>Test the integration using the "Send test" button</li>
  </ul>
</TroubleshootItem>

<TroubleshootItem title="Address marked in red?">
  <ul>
    <li>Each recipient must be a valid address, e.g. <code>email1@domain.com</code></li>
    <li>Press Enter or type a comma after each address to add it</li>
    <li>Fix or remove the addresses marked in red before saving</li>
  </ul>
</TroubleshootItem>

- Custom webhooks: https://abrova.ir/en/docs/trace/webhooks

Send error data to any HTTP endpoint via custom webhooks. Integrate with your incident tools, internal systems, or anything that accepts POST requests.

<Callout kind="note" title="What you'll need">
  <ul>
    <li>An HTTP endpoint that accepts POST requests</li>
    <li>(Optional) A signing secret to verify requests</li>
    <li>Owner or admin access to the project</li>
  </ul>
</Callout>

<Callout kind="tip" title="Works inside Iran">Webhooks are a good default channel in Iran: point them at your own server (or an internal tool reachable on the public internet) and no service outside the country is involved.</Callout>

Which channels your project can use is shown on the **Trace → Integrations** page in Abrova Console.

<H2 id="set-up-webhook-integration" step={1}>Set Up Webhook Integration</H2>

1. In Abrova Console, open **Trace → Integrations** (integrations belong to the selected project)
2. Click **"Add integration"** and choose **Webhook** (or **"Connect"** on the Webhook card)
3. Enter a **Name** and fill in the configuration fields
4. Click **"Save channel"** — or **"Save and send test"** to save and verify it

<ConfigTable rows={[
  ['Name', 'string', 'Yes', 'Name for identification (e.g., "Incident bridge")'],
  ['URL', 'string', 'Yes', 'Your endpoint URL. Must start with https:// and be reachable on the public internet (e.g., https://your-server.com/api/abrova-trace-webhook)'],
  ['Signing secret', 'string', 'No', 'Used to sign each request so your server can verify it'],
]} />

#### URL rules

- The URL must use `https://` and must not contain a user name or password.
- The host must be a public address. Private, loopback and other internal addresses (for example `localhost`, `10.x.x.x`, `192.168.x.x`) are refused when you save and are never called.
- Redirects are not followed: if your endpoint answers with a `3xx`, the delivery counts as failed. Enter the final URL.

#### After saving

Managing integrations (add, edit, switch on/off, delete, test) needs the **admin** or **owner** role; every role can see them and their delivery log. See [Roles & Permissions](/docs/trace/error-dashboard#roles).

The URL and the signing secret are never shown again once saved: the form shows them as set (for the URL, only its scheme and host). Leave a field as it is to keep the saved value, or press **Replace** to enter a new one.

If you change the URL to a different host (or switch scheme or port), enter the signing secret again as well — a saved secret is never sent to a new destination on its own. Changing only the path on the same host keeps it.

### Payload Format

When an error is seen for the first time, AbrovaTrace sends a JSON POST request with the following structure:

<CodeBlock language="json" code={`{
  "event": "error.new",
  "timestamp": "2025-01-18T10:30:00.000Z",
  "data": {
    "id": 456,
    "message": "TypeError: Cannot read property 'map' of undefined",
    "project": "My App",
    "environment": "production",
    "count": 1,
    "first_seen": "2025-01-18T10:30:00.000Z",
    "last_seen": "2025-01-18T10:30:00.000Z",
    "stack_trace": "...",
    "url": "https://myapp.com/checkout",
    "user_agent": "Mozilla/5.0 ..."
  }
}`} />

Alert rules and cron monitors connected to this webhook send `alert.triggered` / `alert.resolved` events instead, with `data` holding `rule_name`, `rule_type`, `metric_value`, `threshold`, `operator`, `window_minutes`, `project` and `environment`.

#### Signature

When a signing secret is set, each request carries:

- `X-AbrovaTrace-Signature: sha256=<hex>` — HMAC-SHA256 of the JSON body, keyed with your secret
- `X-AbrovaTrace-Timestamp` — the send time in milliseconds

### Best Practices

<BestPracticeList items={[
  ['Verify Signatures', 'Use the secret to verify incoming requests are from AbrovaTrace'],
  ['Respond Quickly', 'Return a 2xx response within 10 seconds — slower, redirect (3xx) or other non-2xx responses count as failed'],
  ['Check the Delivery Log', 'Failed deliveries are not retried; they show as failed in the integration\'s delivery log'],
]} />

- Telegram: https://abrova.ir/en/docs/trace/telegram

Receive instant error alerts via Telegram bot. Set up a bot, get your chat ID, and start receiving notifications in minutes.

<Callout kind="warn" title="Reaching Telegram from Iran">
  Telegram is a service outside Iran and may be unreachable from some networks in Iran. To set it up and to read the alerts you need a connection that can reach Telegram, and deliveries only arrive while api.telegram.org answers — failed deliveries show in the integration's delivery log. If that is a problem for your team, use the [Email](/docs/trace/email) or [Webhook](/docs/trace/webhooks) integration instead, or alongside it.
</Callout>

Which channels your project can use is shown on the **Trace → Integrations** page in Abrova Console.

<H2 id="create-a-telegram-bot" step={1}>Create a Telegram Bot</H2>

1. Open Telegram and search for **@BotFather**
2. Send the command: `/newbot`
3. Enter a name for your bot (e.g., **"AbrovaTrace Alerts"**)
4. Enter a username (must end with "bot", e.g., **"MyAbrovaTrace_bot"**)
5. Copy the **Bot Token** provided by BotFather

Token format: `1234567890:ABCdefGHIjklMNOpqrsTUVwxyz123456789`

<Callout kind="note" title="Security Note">Keep your bot token secret. Anyone with the token can control your bot.</Callout>

<H2 id="get-your-chat-id" step={2}>Get Your Chat ID</H2>

#### Option A: Personal Chat

1. Start a conversation with your bot (search by username)
2. Send any message to the bot
3. Open this URL in your browser:

<CodeBlock language="text" code="https://api.telegram.org/bot{YOUR_BOT_TOKEN}/getUpdates" />

Find your Chat ID in the JSON response under `message.chat.id`.

#### Option B: Group Chat

1. Create a new group or use an existing one
2. Add your bot to the group
3. Send a message in the group
4. Use the same `getUpdates` URL above

Group Chat IDs are negative numbers (e.g., `-1001234567890`).

<H2 id="configure-in-abrovatrace" step={3}>Configure in AbrovaTrace</H2>

1. In Abrova Console, open **Trace → Integrations** (integrations belong to the selected project)
2. Click **"Add integration"** and choose **Telegram** (or **"Connect"** on the Telegram card)
3. Enter a **Name**, your Bot token and Chat ID
4. Click **"Save and send test"** to save and verify it (or **"Save channel"**)

<ConfigTable rows={[
  ['Name', 'string', 'Yes', 'Friendly name (e.g., Ops chat)'],
  ['Bot token', 'string', 'Yes', 'Token from BotFather (1234567890:ABC...)'],
  ['Chat ID', 'string', 'Yes', 'Personal or group Chat ID (a number, e.g. -1001234567890), or @channelname'],
]} />

#### After saving

Managing integrations (add, edit, switch on/off, delete, test) needs the **admin** or **owner** role; every role can see them and their delivery log. See [Roles & Permissions](/docs/trace/error-dashboard#roles).

The bot token is never shown again once saved: the form shows it as set. Leave it as it is to keep the saved token, or press **Replace** to enter a new one.

If you change the Chat ID, enter the bot token again as well — a saved token is never used for a different chat on its own.

### Notification Format

Telegram messages from AbrovaTrace include:

- **🚨 New Error Detected** header
- Error message in a monospace block
- Project, environment, occurrence count, first-seen timestamp
- The first 500 characters of the stack trace
- A **View in Dashboard** link

### Troubleshooting

<TroubleshootItem title="Bot not sending messages?">
  <ul>
    <li>You must start a conversation with the bot first</li>
    <li>Verify Bot Token is correct</li>
    <li>Check Chat ID is accurate</li>
    <li>For groups, ensure bot is added as a member</li>
    <li>Check the delivery log of the integration: a timeout or connection error means Telegram could not be reached</li>
  </ul>
</TroubleshootItem>

<TroubleshootItem title="Chat ID not appearing in getUpdates?">
  <ul>
    <li>Send a message to the bot after creating it</li>
    <li>Wait a few seconds and refresh the URL</li>
    <li>For groups, send a message after adding the bot</li>
  </ul>
</TroubleshootItem>

<TroubleshootItem title='"Unauthorized" error?'>
  <ul>
    <li>Bot Token may be invalid or revoked</li>
    <li>Create a new token with BotFather using <code>/revoke</code></li>
    <li>Edit the integration in Trace → Integrations and press Replace on the bot token</li>
  </ul>
</TroubleshootItem>

- Discord: https://abrova.ir/en/docs/trace/discord

Get real-time error notifications in Discord channels via webhooks. Rich embed messages with error details, environment info, and direct dashboard links.

<Callout kind="note" title="What you'll need">
  <ul>
    <li>A Discord server where you have admin permissions</li>
    <li>A channel for error notifications</li>
    <li>~5 minutes to set up</li>
  </ul>
</Callout>

<Callout kind="warn" title="Reaching Discord from Iran">
  Discord is a service outside Iran and may be unreachable from some networks in Iran. To set it up and to read the alerts you need a connection that can reach Discord, and deliveries only arrive while discord.com answers — failed deliveries show in the integration's delivery log. If that is a problem for your team, use the [Email](/docs/trace/email) or [Webhook](/docs/trace/webhooks) integration instead, or alongside it.
</Callout>

Which channels your project can use is shown on the **Trace → Integrations** page in Abrova Console.

<H2 id="create-a-discord-webhook" step={1}>Create a Discord Webhook</H2>

1. Open your Discord server and navigate to the target channel
2. Right-click the channel → **Edit Channel**
3. Go to the **Integrations** tab
4. Click **"Create Webhook"** or **"New Webhook"**
5. Optionally rename the webhook (e.g., **"AbrovaTrace"**) — messages are posted with the AbrovaTrace name and avatar either way
6. Click **"Copy Webhook URL"**
7. Click **"Save Changes"**

<H2 id="configure-in-abrovatrace" step={2}>Configure in AbrovaTrace</H2>

1. In Abrova Console, open **Trace → Integrations** (integrations belong to the selected project)
2. Click **"Add integration"** and choose **Discord** (or **"Connect"** on the Discord card)
3. Enter a **Name** and fill in the configuration fields
4. Click **"Save channel"** — or **"Save and send test"** to save and verify it

<ConfigTable rows={[
  ['Name', 'string', 'Yes', 'Friendly name for identification (e.g., #errors)'],
  ['Webhook URL', 'string', 'Yes', 'Discord webhook URL. Must be on discord.com (https://discord.com/api/webhooks/...)'],
]} />

#### After saving

Managing integrations (add, edit, switch on/off, delete, test) needs the **admin** or **owner** role; every role can see them and their delivery log. See [Roles & Permissions](/docs/trace/error-dashboard#roles).

The webhook URL is never shown again once saved: the form shows it as set, with only its scheme and host visible. Leave it as it is to keep the saved URL, or press **Replace** to paste a new one. Only Discord's own webhook addresses are accepted (`discord.com`, and `discordapp.com`, `ptb.discord.com` or `canary.discord.com`).

### Configuration Examples

- **Production Alerts** — Name: `#prod-errors`, webhook in your production channel
- **Dev Notifications** — Name: `#dev-errors`, webhook in your dev channel

Messages are posted with the username **Abrova Trace**.

### Notification Format

Discord messages from AbrovaTrace include:

- **🚨 New Error: &lt;error message&gt;** title (sent the first time an error is seen)
- Project, environment and occurrence count, with the first-seen time as the embed timestamp
- A link on the title back to the error

Spike detection also posts here, and alert rules and cron monitors post here when you pick this channel for them.

### Best Practices

<BestPracticeList items={[
  ['Create Dedicated Channels', 'Separate channels for prod/dev/staging errors'],
  ['Use Channel Permissions', 'Control who sees error notifications with Discord permissions'],
  ['Pin Important Webhooks', 'Pin the setup message in channel for easy reference'],
  ['Use Descriptive Names', 'Name each integration after its channel, e.g. "#prod-errors"'],
]} />

### Troubleshooting

<TroubleshootItem title="Not receiving messages?">
  <ul>
    <li>Verify webhook URL is correct and complete</li>
    <li>Check webhook wasn't deleted in Discord</li>
    <li>Ensure the integration is switched on in Trace → Integrations</li>
    <li>Test the integration with the "Send test" button</li>
    <li>Check server and channel permissions</li>
    <li>Check the delivery log of the integration: a timeout or connection error means Discord could not be reached</li>
  </ul>
</TroubleshootItem>

<TroubleshootItem title="Webhook deleted or invalid?">
  <ul>
    <li>Create a new webhook in Discord channel settings</li>
    <li>Edit the integration in Trace → Integrations and press Replace on the webhook URL</li>
    <li>Don't share webhook URLs publicly</li>
  </ul>
</TroubleshootItem>

<TroubleshootItem title="Messages going to wrong channel?">
  <ul>
    <li>Each webhook is tied to a specific channel</li>
    <li>Create a new webhook in the correct channel</li>
    <li>Edit the integration in Trace → Integrations and press Replace on the webhook URL</li>
  </ul>
</TroubleshootItem>

<TroubleshootItem title="Rate limiting issues?">
  <ul>
    <li>Discord has rate limits for webhooks</li>
    <li>Use error grouping to reduce frequency</li>
    <li>Use Ignore Rules to drop noisy errors before they notify</li>
  </ul>
</TroubleshootItem>

- GitHub issues: https://abrova.ir/en/docs/trace/github

Automatically create GitHub issues from AbrovaTrace errors. Each new error creates an issue with the error details and full stack trace.

<Callout kind="note" title="What you'll need">
  <ul>
    <li>A GitHub account</li>
    <li>A GitHub repository for tracking issues</li>
    <li>A GitHub Personal Access Token</li>
  </ul>
</Callout>

<Callout kind="warn" title="Reaching GitHub from Iran">
  GitHub is a service outside Iran and may be unreachable from some networks in Iran. To set it up and to read the alerts you need a connection that can reach GitHub, and deliveries only arrive while github.com and api.github.com answer — failed deliveries show in the integration's delivery log. If that is a problem for your team, use the [Email](/docs/trace/email) or [Webhook](/docs/trace/webhooks) integration instead, or alongside it.
</Callout>

Which channels your project can use is shown on the **Trace → Integrations** page in Abrova Console.

<H2 id="create-a-github-personal-access-token" step={1}>Create a GitHub Personal Access Token</H2>

1. Go to **GitHub → Settings → Developer settings → Personal access tokens → Tokens (classic)**
2. Click **"Generate new token"** → **"Generate new token (classic)"**
3. Configure the token:
   - **Note:** "AbrovaTrace Integration"
   - **Expiration:** 90 days recommended
   - **Scopes:** Select `repo` (full control of private repositories)
4. Click **"Generate token"** and copy it immediately

<Callout kind="note" title="Important">You won't be able to see the token again after leaving the page. Save it securely.</Callout>

<H2 id="configure-in-abrovatrace" step={2}>Configure in AbrovaTrace</H2>

1. In Abrova Console, open **Trace → Integrations** (integrations belong to the selected project)
2. Click **"Add integration"** and choose **GitHub** (or **"Connect"** on the GitHub card)
3. Enter a **Name** and fill in the configuration fields
4. Click **"Save channel"** — or **"Save and send test"** to save and verify it

<ConfigTable rows={[
  ['Name', 'string', 'Yes', 'Friendly name (e.g., "acme/web issues")'],
  ['Personal access token', 'string', 'Yes', 'Token starting with ghp_ from step 1; needs permission to create issues'],
  ['Repository owner', 'string', 'Yes', 'User or organisation (e.g., myorg)'],
  ['Repository name', 'string', 'Yes', 'Repository (e.g., my-app)'],
]} />

#### After saving

Managing integrations (add, edit, switch on/off, delete, test) needs the **admin** or **owner** role; every role can see them and their delivery log. See [Roles & Permissions](/docs/trace/error-dashboard#roles).

The personal access token is never shown again once saved: the form shows it as set. Leave it as it is to keep the saved token, or press **Replace** to enter a new one.

If you change the repository owner or name, enter the token again as well — a saved token is never used for a different repository on its own.

### What Gets Created

When a new error is detected (the first time it is seen), AbrovaTrace automatically creates a GitHub issue with:

- **Title** — `[AbrovaTrace] <error message>` (e.g. `[AbrovaTrace] TypeError: Cannot read property 'map' of undefined`)
- **Error Details** — project, environment, first-seen timestamp, occurrence count
- **Stack Trace** — full stack from the error event
- **Additional Info** — page URL and user agent

Spike detection also opens an issue here, and alert rules you connect to this channel open a `[AbrovaTrace Alert] <rule name>` issue labelled `abrovatrace-alert` when they trigger.

### Best Practices

<BestPracticeList items={[
  ['Use a Dedicated Repository or Filter', 'Issues are titled "[AbrovaTrace] …", so they are easy to find with a search filter'],
  ['Set Token Expiration Reminders', 'Set a calendar reminder before your token expires'],
  ['Separate Integrations per Repository', 'Add one GitHub integration per repository you want issues in'],
]} />

### Troubleshooting

<TroubleshootItem title="Issues not being created?">
  <ul>
    <li>Verify personal access token is correct</li>
    <li>Check token has "repo" scope permissions</li>
    <li>Ensure the repository owner and name are correct</li>
    <li>Verify repository exists and you have access</li>
    <li>Test the integration using the "Send test" button</li>
    <li>Check the delivery log of the integration: a timeout or connection error means GitHub could not be reached</li>
  </ul>
</TroubleshootItem>

<TroubleshootItem title="Authentication failed error?">
  <ul>
    <li>Token may have expired — create a new one, then edit the integration and press Replace on the token</li>
    <li>Token doesn't have sufficient permissions</li>
    <li>You may not have access to the repository</li>
    <li>Try regenerating token with "repo" scope</li>
  </ul>
</TroubleshootItem>

<TroubleshootItem title="Wrong repository?">
  <ul>
    <li>Enter the owner and the repository name in separate fields</li>
    <li>Don't include "github.com" or "https://"</li>
    <li>Correct: owner <code>myorg</code>, name <code>abrova-trace</code></li>
    <li>Incorrect: <code>github.com/myorg/abrova-trace</code></li>
  </ul>
</TroubleshootItem>

- Slack: https://abrova.ir/en/docs/trace/slack

Get real-time error notifications in your Slack workspace. Learn how to create a webhook, connect it, and what the notifications look like.

<Callout kind="note" title="What you'll learn">
  <ul>
    <li>How to create a Slack incoming webhook</li>
    <li>Configure Slack notifications in AbrovaTrace</li>
    <li>What the notifications contain</li>
    <li>Test your Slack integration</li>
  </ul>
</Callout>

<Callout kind="warn" title="Reaching Slack from Iran">
  Slack is a service outside Iran and may be unreachable from some networks in Iran. To set it up and to read the alerts you need a connection that can reach Slack, and deliveries only arrive while hooks.slack.com answers — failed deliveries show in the integration's delivery log. If that is a problem for your team, use the [Email](/docs/trace/email) or [Webhook](/docs/trace/webhooks) integration instead, or alongside it.
</Callout>

Which channels your project can use is shown on the **Trace → Integrations** page in Abrova Console.

<H2 id="create-a-slack-webhook" step={1}>Create a Slack Webhook</H2>

1. Go to **api.slack.com/apps**
2. Click **"Create New App"** → **"From scratch"**
3. Name your app **"AbrovaTrace"** and select your workspace
4. Navigate to **"Incoming Webhooks"** in the sidebar
5. Toggle **"Activate Incoming Webhooks"** to ON
6. Click **"Add New Webhook to Workspace"**
7. Select the channel where you want notifications
8. Copy the webhook URL

Your webhook URL will look like: `https://hooks.slack.com/services/...`

<H2 id="configure-in-abrovatrace" step={2}>Configure in AbrovaTrace</H2>

1. In Abrova Console, open **Trace → Integrations** (integrations belong to the selected project)
2. Click **"Add integration"** and choose **Slack** (or **"Connect"** on the Slack card)
3. Enter a **Name** and paste the webhook URL
4. Click **"Save and send test"** to save and verify it (or **"Save channel"**)

<ConfigTable rows={[
  ['Name', 'string', 'Yes', 'Friendly name (e.g., #alerts)'],
  ['Incoming webhook URL', 'string', 'Yes', 'Full Slack webhook URL from step 1. Must be on hooks.slack.com (https://hooks.slack.com/...)'],
]} />

#### After saving

Managing integrations (add, edit, switch on/off, delete, test) needs the **admin** or **owner** role; every role can see them and their delivery log. See [Roles & Permissions](/docs/trace/error-dashboard#roles).

The webhook URL is never shown again once saved: the form shows it as set, with only `https://hooks.slack.com/…` visible. Leave it as it is to keep the saved URL, or press **Replace** to paste a new one. Only Slack's own webhook addresses (`https://hooks.slack.com/...`) are accepted.

### Notification Format

Slack messages from AbrovaTrace include:

- **Header** — AbrovaTrace bot username + ⚠️ icon
- **Alert title** — `New Error: <error message>`, linked back to the error
- **Metadata** — project, environment, first-seen timestamp, occurrence count

New-error messages are sent the first time an error is seen. Spike detection also posts here, and alert rules and cron monitors post here when you pick this channel for them.

### Best Practices

<BestPracticeList items={[
  ['Create Dedicated Channels', 'Separate channels for different environments (#prod-errors, #dev-errors)'],
  ['Reduce Noise with Ignore Rules', 'Drop known noisy errors so they never notify'],
  ['Use Thread Replies', 'Keep error discussions organized in Slack threads'],
]} />

### Troubleshooting

<TroubleshootItem title="Not receiving notifications?">
  <ul>
    <li>Verify webhook URL is correct — it must start with https://hooks.slack.com/</li>
    <li>Check the integration is switched on in Trace → Integrations</li>
    <li>Ensure Slack app is installed in your workspace</li>
    <li>Try the "Send test" button again</li>
    <li>Check the delivery log of the integration: a timeout or connection error means Slack could not be reached</li>
  </ul>
</TroubleshootItem>

<TroubleshootItem title="Messages going to wrong channel?">
  <ul>
    <li>The webhook URL determines the channel</li>
    <li>Create a new webhook for the correct channel</li>
    <li>Edit the integration in Trace → Integrations and press Replace on the webhook URL</li>
  </ul>
</TroubleshootItem>

<TroubleshootItem title="Getting rate limited?">
  <ul>
    <li>Slack has rate limits for incoming webhooks</li>
    <li>Use error grouping to reduce notification frequency</li>
    <li>Use Ignore Rules to drop noisy errors</li>
  </ul>
</TroubleshootItem>

- Overview & setup: https://abrova.ir/en/docs/trace/self-hosted

<Callout kind="soon" title="Coming soon">
  Self-hosted Abrova Trace is not available yet. This page describes how it will work. To be told when it launches, or to talk about running Abrova Trace on your own servers, [contact us](/contact).
</Callout>

### Self-Hosted Overview & Setup

Run AbrovaTrace on your own infrastructure. Same features as the cloud version — you control the data.

<Callout kind="note" title="Same SDKs, Same Dashboard">
  Self-hosted uses the exact same SDKs and dashboard as the cloud version. The only difference is where the data is stored.
</Callout>

<H3 id="what-you-get">What you get</H3>

- Error tracking, logs, APM, breadcrumbs, crash detection
- Dashboard with all the same features as cloud
- 6 SDKs: Flutter, Next.js, Node.js, Android, iOS, Laravel
- Source maps & dSYM symbolication
- Alert rules, cron monitors, integrations (Email, Webhook, etc.)
- Data stays on your server

<H2 id="prerequisites" step={1}>Prerequisites</H2>

- Docker & Docker Compose
- 512 MB RAM (Console) + 1 GB RAM (Trace)
- Works on a small VPS or a local machine

<H2 id="install-Abrova-console" step={2}>Install Abrova Console</H2>

The Console is the shared dashboard for all Abrova self-hosted services. It runs as a Docker Compose stack: the Console dashboard, its API and its own database, all on your server.

1. Download the self-hosted setup files (published when self-hosting launches). They contain a ready `docker-compose.yml` for the Console.
2. Create a `.env` file next to it and set your own random secrets and database password — the setup files list every variable.
3. Start it:

```bash
docker compose up -d
```

Open `http://localhost:3000` — register your account (first user becomes the server owner).

<H2 id="install-abrovatrace" step={3}>Install AbrovaTrace</H2>

AbrovaTrace runs as a second Compose stack: the Trace API with its own database and cache.

1. Use the `docker-compose.trace.yml` from the same setup files.
2. Create a `.env.trace` file: your own random secrets and database password, the address of your Console API (for example `http://host.docker.internal:3004`) and the address your dashboard is opened on (for example `http://localhost:3000`).
3. Start it:

```bash
docker compose -f docker-compose.trace.yml --env-file .env.trace up -d
```

Go to the Console (`http://localhost:3000`) and click **Abrova Trace** in the sidebar.

<H2 id="connect-your-sdk" step={4}>Connect Your SDK</H2>

Point any SDK to your self-hosted Trace API by adding `apiUrl`. See the [SDK Configuration](/docs/trace/self-hosted-sdk) page for all 6 SDKs.

<H3 id="ports">Ports</H3>

On your server, the stacks listen on:

- **3000** — Console Dashboard
- **3004** — Console Auth API
- **3001** — AbrovaTrace API

<H3 id="updates">Updates</H3>

```bash
# Console
docker compose pull && docker compose up -d

# Trace
docker compose -f docker-compose.trace.yml pull
docker compose -f docker-compose.trace.yml up -d
```

<H3 id="licensing">Licensing</H3>

Self-hosting starts with a free tier that needs no licence key. See [Self-Hosted Licensing](/docs/trace/licensing).

- SDK configuration: https://abrova.ir/en/docs/trace/self-hosted-sdk

<Callout kind="soon" title="Coming soon">
  Self-hosted Abrova Trace is not available yet. This page shows how the SDKs will point at your own server. For Abrova's cloud, leave `apiUrl` out — the SDKs use `https://trace.abrova.ir` by default. Questions? [Contact us](/contact).
</Callout>

### SDK Configuration for Self-Hosted

All 6 SDKs work with self-hosted. Just add `apiUrl` pointing to your server. Everything else stays the same.

### Flutter

<CodeBlock language="dart" code={`await AbrovaTrace.initWithZone(
  AbrovaTraceConfig(
    apiKey: 'ab_live_your_api_key_here',
    apiUrl: 'http://your-server:3001',  // Your self-hosted Trace API
    environment: 'production',
    release: '1.0.0',
    captureUncaughtErrors: true,
  ),
  () async {
    WidgetsFlutterBinding.ensureInitialized();
    runApp(MyApp());
  },
);`} />

### Next.js

```tsx
AbrovaTrace.init({
  apiKey: 'ab_live_your_api_key',
  apiUrl: 'http://your-server:3001',  // Your self-hosted Trace API
  environment: process.env.NODE_ENV,
  release: process.env.NEXT_PUBLIC_APP_VERSION,
});
```

### Node.js

```javascript
const AbrovaTrace = require('@abrova-trace/nodejs-sdk');

AbrovaTrace.init({
  apiKey: 'ab_live_your_api_key_here',
  serverSecret: 'ab_srv_your_server_secret_here',
  apiUrl: 'http://your-server:3001',  // Your self-hosted Trace API
  environment: 'production',
  release: '1.0.0'
});
```

### Android (Kotlin)

```kotlin
val config = AbrovaTraceConfig.Builder("ab_live_your_api_key")
    .apiUrl("http://your-server:3001")  // Your self-hosted Trace API
    .environment(if (BuildConfig.DEBUG) "development" else "production")
    .release(BuildConfig.VERSION_NAME)
    .build()

AbrovaTrace.init(this, config)
```

### iOS (Swift)

```swift
let config = AbrovaTraceConfigBuilder(apiKey: "ab_live_your_api_key")
    .apiUrl("http://your-server:3001")  // Your self-hosted Trace API
    .environment("production")
    .release(Bundle.main.infoDictionary?["CFBundleShortVersionString"] as? String)
    .build()

AbrovaTrace.shared.initialize(config: config)
```

### Laravel

Add to your `.env`:

```bash
ABROVATRACE_API_URL=http://your-server:3001
ABROVATRACE_API_KEY=ab_live_your_api_key_here
ABROVATRACE_SERVER_SECRET=ab_srv_your_secret_here
ABROVATRACE_ENVIRONMENT=production
```

<H3 id="notes">Notes</H3>

- Replace `your-server:3001` with your actual server IP or domain
- For local development, use `http://localhost:3001`
- For production, use HTTPS with a reverse proxy (nginx, Caddy)
- Get your API key from the self-hosted Console dashboard
- The app key (`ab_live_...`) goes into mobile and web apps; the server secret (`ab_srv_...`) belongs only on your servers — see [Server Secret & Server Routes](/docs/trace/server-secret)
- All features (breadcrumbs, APM, logs, crash detection) work identically to cloud

- Licensing: https://abrova.ir/en/docs/trace/licensing

<Callout kind="soon" title="Coming soon">
  Self-hosted Abrova Trace is not available yet, and licence prices are not set. This page describes how licensing will work. To talk about a licence for your company, [contact us](/contact).
</Callout>

### Licensing

Self-hosted will work immediately with a free tier. A licence key from Abrova raises the limits and turns on the larger features.

<Callout kind="note" title="No Licence Needed for the Free Tier">
  Just run the Docker containers and start tracking errors. No sign-up, no licence key, no payment.
</Callout>

<H3 id="plan-comparison">What a licence changes</H3>

| Feature                | Free tier | With a licence |
|------------------------|-----------|----------------|
| Projects               | 1         | More, set by your licence |
| New issues / month     | 50        | More, set by your licence |
| Team members           | 2         | More, set by your licence |
| Error tracking & Logs  | Yes       | Yes |
| APM & Web Vitals       | No        | Yes |
| Source maps / dSYM     | No        | Yes |
| Custom alert rules     | 1         | More, set by your licence |
| Cron monitors          | 1         | More, set by your licence |
| Integrations           | Email     | More channels |
| Spike detection        | No        | Yes |

Licences are paid in Toman. For prices and a licence for your company, [contact us](/contact).

### What Happens When a Limit Is Reached

"New issues / month" in the table above means new issues per month. An error is counted the first time it is seen, when it creates a new issue. Further events of an issue that already exists are not counted.

When the monthly limit is reached:

- **New issues are not stored** until the limit resets at the start of the next month.
- **Events of issues that already exist keep updating them** — counts and last-seen times stay current.
- **Your apps are never disturbed.** The API still answers success (`200`), with a body that says the event was not stored, so no SDK retries, queues or logs an error:

```json
{
  "status": "dropped",
  "code": "plan_limit_reached",
  "metric": "errors_monthly",
  "limit": 50,
  "used": 50,
  "resets_at": "2026-11-01T00:00:00.000Z"
}
```

(`limit` and `used` are example values; they reflect your licence.)

Performance monitoring needs a licence that includes it. Without it, spans and Web Vitals sent by your apps are answered the same way (`200`, `"status": "dropped"`, `"code": "feature_not_in_plan"`) and are not stored.

The project, alert rule and cron monitor limits apply when you create one: creating beyond the limit is refused.

### How to Activate a Licence

1. [Contact us](/contact) to get a licence key for your company
2. Open your self-hosted Console → Dashboard → License
3. Paste the key and click **Activate**

### How Licensing Works

- The licence key is tied to your account, not to a specific server
- Your server validates the licence every 24 hours
- If your server can't reach Abrova, it uses the limits it has cached (7-day grace period)
- When a licence ends, you have 7 days before the server goes back to the free tier
- Going back is graceful — existing data is preserved, limits reduced

### What Happens When a Licence Ends

- Projects beyond the free limit become **read-only** (newest kept active)
- Members beyond the limit can still log in but can't be added to projects
- Licensed features (APM, source maps) stop working — performance data sent by your apps is no longer stored
- All existing data is preserved — nothing is deleted
- Activating a licence again instantly restores all features

- Error handling strategies: https://abrova.ir/en/docs/trace/error-handling

Best practices for implementing effective error tracking in your application. Follow these 10 strategies to get the most out of AbrovaTrace.

### 1. Use initWithZone() for Comprehensive Error Catching

Catches all error types including Dart exceptions, async errors, Future rejections, and platform exceptions.

<div>
  <div>
    <p>✓ Recommended</p>

```dart
void main() async {
  await AbrovaTrace.initWithZone(
    AbrovaTraceConfig(
      apiKey: 'ab_live_your_api_key',
      environment: 'production',
      release: '1.0.0',
      captureUncaughtErrors: true,
    ),
    () async {
      WidgetsFlutterBinding.ensureInitialized();
      runApp(MyApp());
    },
  );
}
```

  </div>
  <div>
    <p>✗ Basic (misses async errors)</p>

```dart
void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  // This only catches some errors
  await AbrovaTrace.init(
    AbrovaTraceConfig(
      apiKey: 'ab_live_your_api_key',
      environment: 'production',
    ),
  );
  runApp(MyApp());
}
```

  </div>
</div>

### 2. Always Include Stack Traces

When manually capturing exceptions, always include the stack trace parameter for crucial debugging context.

```dart
try {
  await riskyOperation();
} catch (e, stackTrace) {
  await AbrovaTrace.captureException(
    e,
    stackTrace: stackTrace, // Always include this!
    message: 'Failed to complete operation',
  );
}
```

### 3. Add Meaningful Context

Include relevant data using the `extra` parameter to understand the circumstances.

```dart
try {
  await processPayment(orderId, amount);
} catch (e, stackTrace) {
  await AbrovaTrace.captureException(
    e,
    stackTrace: stackTrace,
    message: 'Payment processing failed',
    extra: {
      'order_id': orderId,
      'amount': amount,
      'payment_method': paymentMethod,
      'user_tier': userTier,
    },
  );
}
```

<Callout kind="note" title="Tip">Include data that helps reproduce the error, but avoid sensitive information like passwords or credit card numbers.</Callout>

### 4. Combine Errors with Breadcrumbs

Track user actions leading up to an error for a complete timeline.

```dart
// Track user actions
AbrovaTrace.addBreadcrumb(
  'User opened checkout screen',
  type: BreadcrumbType.navigation,
);

AbrovaTrace.addBreadcrumb(
  'User selected credit card payment',
  type: BreadcrumbType.user,
  data: {'payment_type': 'credit_card'},
);

try {
  await submitOrder();
} catch (e, stackTrace) {
  // Error will include all breadcrumbs above
  await AbrovaTrace.captureException(
    e,
    stackTrace: stackTrace,
    message: 'Order submission failed',
  );
}
```

### 5. Implement Crash Detection

Native crash capture is automatic on iOS and Android: the Flutter SDK bundles the native Abrova Trace SDKs and starts them during `init()` / `initWithZone()`. No extra code is needed.

How it works: on iOS, PLCrashReporter saves signal and Mach exception crashes to disk; on Android, an uncaught exception handler plus `ApplicationExitInfo` (API 30+) record crashes and ANRs. The report is sent on the next app launch and appears as an issue. Desktop and web have no native crash capture.

`AbrovaTrace.close()` is not needed for crash detection. It flushes pending logs and tears the SDK down, so call it only when the app is really shutting down.

### 6. Use Environment-Specific Configuration

```dart
void main() async {
  const environment = String.fromEnvironment(
    'ENV', defaultValue: 'development',
  );

  await AbrovaTrace.initWithZone(
    AbrovaTraceConfig(
      apiKey: 'ab_live_your_api_key',
      environment: environment,
      release: '1.0.0',
      captureUncaughtErrors: environment == 'production',
      enabled: environment != 'development',
    ),
    () async {
      WidgetsFlutterBinding.ensureInitialized();
      runApp(MyApp());
    },
  );
}
```

### 7. Manage Error Status in Dashboard

- **Open:** New errors that need investigation
- **In Progress:** Errors you're actively working on
- **Resolved:** Fixed errors (reopen if they recur)
- **Ignored:** Known issues you're choosing not to fix
- **Archived:** Historical errors to keep but not see in active list

### 8. Handle Async Errors Properly

```dart
// Catching Future errors
Future<void> loadData() async {
  try {
    final data = await fetchFromAPI();
    processData(data);
  } catch (e, stackTrace) {
    await AbrovaTrace.captureException(
      e, stackTrace: stackTrace,
      message: 'Failed to load data',
    );
  }
}

// Handling Stream errors
void listenToStream() {
  myStream.listen(
    (data) => processData(data),
    onError: (e, stackTrace) async {
      await AbrovaTrace.captureException(
        e, stackTrace: stackTrace,
        message: 'Stream error occurred',
      );
    },
  );
}
```

### 9. Don't Over-Report

<div>
  <div>
    <strong>Don't Report</strong>
    <ul>
      <li>Expected validation errors</li>
      <li>User cancellations</li>
      <li>Network timeouts in offline mode</li>
      <li>Permission denials</li>
    </ul>
  </div>
  <div>
    <strong>Do Report</strong>
    <ul>
      <li>Unexpected exceptions (null ref, index out of bounds)</li>
      <li>API errors (server 500, malformed responses)</li>
      <li>Data corruption</li>
      <li>Native crashes</li>
    </ul>
  </div>
</div>

### 10. Test Your Error Tracking

Before deploying to production, verify error tracking works (the event appears under **Abrova Trace → Issues**):

```dart
// Add a test button in debug builds
if (kDebugMode) {
  ElevatedButton(
    onPressed: () async {
      try {
        throw Exception('Test error from debug menu');
      } catch (e, stackTrace) {
        await AbrovaTrace.captureException(
          e,
          stackTrace: stackTrace,
          message: 'Test error',
        );
      }
    },
    child: Text('Test Error Tracking'),
  );
}
```

The SDK drops an identical error (same message and platform) sent again within one minute, so change the message if you test several times in a row.

### Summary Checklist

<div>
  <ul>
    <li><span>✓</span><span>Use initWithZone() for comprehensive error catching</span></li>
    <li><span>✓</span><span>Always include stack traces in manual captures</span></li>
    <li><span>✓</span><span>Add meaningful context with the extra parameter</span></li>
    <li><span>✓</span><span>Combine errors with breadcrumbs for user journey tracking</span></li>
    <li><span>✓</span><span>Test on a real iOS/Android build so native crashes are captured</span></li>
    <li><span>✓</span><span>Use environment-specific configurations</span></li>
    <li><span>✓</span><span>Manage error status effectively in the dashboard</span></li>
    <li><span>✓</span><span>Handle async errors properly</span></li>
    <li><span>✓</span><span>Only report actionable errors</span></li>
    <li><span>✓</span><span>Test your error tracking before production</span></li>
  </ul>
</div>


## Abrova Auth

- Overview & quick start: https://abrova.ir/en/docs/auth/quick-start

Abrova Auth signs in your app's users without a backend of your own. Your app calls the SDK with its public API key; Abrova checks the credentials, keeps the session and gives the app a **user token**. That token is the Abrova user token: Abrova Trace can attach the signed-in user to errors today, and Sync, Chat, Push, Storage and A/B Testing will accept the same token when they launch, so their security rules know who the user is (`auth.uid`) without a server of yours minting anything.

<BestPracticeList columns={2} items={[
  ['No backend', 'Public API key only. Nothing secret ships in your app'],
  ['Six sign-in methods', 'Anonymous, e-mail + password, magic link, Telegram code, Apple, Google'],
  ['One user everywhere', 'The same user id in Abrova Trace today, and in the other Abrova products as they launch'],
  ['Upgradeable guests', 'Start anonymous, link a password, Apple or Google later: same user id'],
  ['Sessions handled', '1-hour access token, rotating refresh token, renewed by the SDK'],
  ['Account deletion', 'One call, as the App Store requires for apps with sign-in'],
]} />

<Callout kind="tip" title="Users in Iran">
Lead with anonymous, e-mail and password, magic link and Telegram code. Apple and Google sign-in need a connection to Apple or Google (and Google Play services on Android), which some users in Iran don't have. Offer them, but don't make them the only way in.
</Callout>

Using an AI assistant? Give it this page with **Copy page for AI**, or all the docs as plain text from [/docs/llms.txt](/docs/llms.txt). See [AI assistants](/docs/auth/ai-assistants).

### Available SDKs

Every package comes from Abrova Center (`center.abrova.ir`); the iOS SDK installs with Swift Package Manager from GitHub.

| Platform | Package | Docs |
|---|---|---|
| Flutter | `abrova_auth` | [Flutter SDK](/docs/auth/flutter) |
| iOS | `AbrovaAuth` (Swift Package Manager) | [iOS SDK](/docs/auth/ios) |
| Android | `ir.abrova:abrova-auth` | [Android SDK](/docs/auth/android) |
| Web | `@abrova/auth-web` | [Web SDK](/docs/auth/web) |
| React Native | `@abrova/auth-react-native` | [React Native SDK](/docs/auth/react-native) |

All five SDKs have the same calls under platform-style names. Abrova Auth is for apps: there is no server SDK, and none is needed.

<H2 id="turn-on-abrova-auth" step={1}>Turn on Abrova Auth</H2>

1. In [Abrova Console](https://console.abrova.ir), open your project's **Settings › Products** and turn on **Abrova Auth**.
2. Open **Abrova Auth › Sign-in methods** and turn on the methods your app offers: anonymous, e-mail and password, magic link, Telegram code, Apple, Google. Every method is off until you turn it on.
3. For Apple and Google, add your app's identifiers on the same page. For e-mail links, add your **link addresses** under **Abrova Auth › Settings**. For Telegram, connect your bot. Each method's page says what it needs.

<H2 id="keys" step={2}>Keys</H2>

Abrova Auth needs only your project's **public API key** (`ab_live_...`), shown under **Abrova Auth › Setup**. It is safe in an app: it names the project, and it cannot act as any user.

| Credential | Lives in | Proves |
|---|---|---|
| **API key** (`ab_live_…`) | Your app, public | Which project |
| **Access token** (1 hour) | Memory on the device | Which user is signed in |
| **Refresh token** | Secure storage on the device | That this device may get new access tokens |

The SDK keeps both tokens for you. You never handle the refresh token yourself.

<Callout kind="warn" title="Never ship the server secret">
The server secret (`ab_srv_...`) is not used by Abrova Auth. Keep it on your server only, out of apps and browser bundles.
</Callout>

<H2 id="install-and-sign-in" step={3}>Install and sign in</H2>

The shortest path is an anonymous user: no screen, one call. Turn on **Anonymous** in the Console first.

Add the package with the Abrova registry as its source:

<Code file="pubspec.yaml" lang="YAML">{`dependencies:
  abrova_auth:
    hosted: https://center.abrova.ir/api/packages/abrova/pub
    version: ^0.1.1`}</Code>

Then run `flutter pub get` and sign in:

```dart
import 'package:abrova_auth/abrova_auth.dart';

final auth = await AbrovaAuth.initialize('ab_live_your_api_key');

auth.authStateChanges.listen((user) {
  // null when signed out
});

if (auth.currentUser == null) {
  await auth.signInAnonymously();
}
print(auth.currentUser?.id); // ru_...
```

The user gets a stable id and a user token from the first launch. Later, link a method to the same user — their data stays theirs:

```dart
await auth.linkPassword(email: 'sara@example.com', password: password);
```

The same on the web, after pointing the `@abrova` scope at Abrova Center in `.npmrc`:

<Code file=".npmrc" lang="INI">{`@abrova:registry=https://center.abrova.ir/api/packages/abrova/npm/`}</Code>

```typescript
import { createAbrovaAuth } from '@abrova/auth-web';

const auth = createAbrovaAuth({ apiKey: 'ab_live_your_api_key' });
await auth.ready();
if (!auth.isSignedIn) await auth.signInAnonymously();
console.log(auth.currentUserId); // ru_...
```

Every platform's page has the full setup: [Flutter](/docs/auth/flutter), [iOS](/docs/auth/ios), [Android](/docs/auth/android), [Web](/docs/auth/web), [React Native](/docs/auth/react-native).

<H2 id="use-the-user-in-other-abrova-products" step={4}>Use the user in other Abrova products</H2>

Today, give the user id to Abrova Trace, so errors show which user they happened to:

```dart
AbrovaTrace.setUserId(auth.currentUser!.id);
```

<Callout kind="soon">Abrova Sync, Chat, Push, Storage and A/B Testing are coming soon. When they launch, you give them the Auth SDK's token provider, as below; they cannot be used yet.</Callout>

The other Abrova SDKs will ask the token provider for a token when they need one, and the Auth SDK renews it before it expires.

```dart
await AbrovaSync.init(AbrovaSyncConfig(
  apiKey: 'ab_live_your_api_key',
  tokenProvider: AbrovaAuth.instance.tokenProvider,
));
```

Sync security rules will then see the signed-in user as `auth.uid`. See [Use with other Abrova products](/docs/auth/other-products) for every product and platform.

### How it works

<NumberedPipeline steps={[
  { title: 'The app signs in', body: 'The SDK sends the credential (an e-mail and password, a code, an Apple or Google ID token) with your public key.' },
  { title: 'Abrova Auth checks it', body: 'Against your project only: its methods, its Apple and Google app ids, its users.' },
  { title: 'The app gets a session', body: 'A 1-hour access token (the Abrova user token) and a refresh token the SDK stores securely.' },
  { title: 'Abrova products trust it', body: 'Each product verifies the token and reads the user id from it.' },
]} />

### Pricing

Abrova Auth is paid by **monthly active users**: each user who signs in or renews a session in a calendar month counts once that month, however often they use the app. There are no plans: you pay from a prepaid Toman wallet for what you use above the free allowance.

| | Free every month | Above that |
|---|---|---|
| Monthly active users | 1,000 | 10,000 Toman per 1,000, from your wallet |
| New anonymous users per day | 200 | Daily cap |
| Sign-in methods and activity log | All included | Included |

When the wallet is empty and the free 1,000 are used up, new users of the month wait (`MAU_LIMIT`); users already counted keep signing in. See [Monthly active users & limits](/docs/auth/mau) and the [pricing page](/pricing). For daily active and returning users, turn on [Usage insights](/docs/auth/usage-insights).

### Common mistakes

- **The method is not turned on.** Every sign-in method starts off. A call to a method that is off fails with `METHOD_DISABLED`. Call `getMethods()` and show only the buttons it returns.
- **Abrova Auth is not turned on for the project.** Calls fail with `PRODUCT_DISABLED` until you turn it on under **Settings › Products**.
- **Only Apple or Google is offered.** Some users in Iran cannot reach Apple or Google. Offer anonymous, e-mail, magic link or Telegram code too.
- **Apple or Google says the ID token is invalid.** Your bundle ID, Services ID or Google client ID is missing in the Console, or the nonce you gave the provider is not the SHA-256 of the raw nonce you gave Abrova. See [Sign in with Apple](/docs/auth/apple) and [Sign in with Google](/docs/auth/google).
- **E-mail links are refused.** The `redirectUrl` must start with one of the link addresses in **Abrova Auth › Settings**.
- **Signing in a second time on every start.** The SDK restores the saved session at start. Check for a current user before you sign in again, or each start creates a new anonymous user.
- **Using `currentUser` before the session is restored.** On the web and React Native, wait for `ready()` (or the first auth state callback) after a reload.

- Flutter SDK: https://abrova.ir/en/docs/auth/flutter

<BestPracticeList columns={2} items={[
  ['Client-Safe', 'Uses the public API key only. Safe to ship in an app'],
  ['Restored at Start', 'initialize() loads the saved session with no network call'],
  ['Secure Storage', 'Refresh token in the Keychain / Keystore-backed storage'],
  ['Token Provider', 'tokenProvider and chatTokenProvider for the other Abrova SDKs'],
  ['All Methods', 'Anonymous, Apple, Google, e-mail, magic link, Telegram'],
  ['Upgrade Guests', 'linkApple, linkGoogle, linkPassword keep the user id'],
]} />

<Callout kind="note" title="Abrova Auth Flutter SDK v0.1.1">
This page describes `abrova_auth` 0.1.1.
</Callout>

<Callout kind="note" title="Requirements">
Flutter 3.13 or higher. Dart 3.0 or higher. Uses `flutter_secure_storage` for the session.
</Callout>

Using an AI assistant? Give it this page with **Copy page for AI**, or all the docs as plain text from [/docs/llms.txt](/docs/llms.txt). See [AI assistants](/docs/auth/ai-assistants).

<H2 id="installation" step={1}>Installation</H2>

Packages come from Abrova Center, so pub.dev blocks don't matter. Add the package with the Abrova registry as its `hosted` source in your `pubspec.yaml`:

<Code file="pubspec.yaml" lang="YAML">{`dependencies:
  abrova_auth:
    hosted: https://center.abrova.ir/api/packages/abrova/pub
    version: ^0.1.1`}</Code>

Then install it:

```bash
flutter pub get
```

In Abrova Console, turn on **Abrova Auth** for your project (**Settings › Products**) and the sign-in methods you want (**Abrova Auth › Sign-in methods**).

<H2 id="initialization" step={2}>Initialization</H2>

Call `AbrovaAuth.initialize` once, before `runApp`, with your public API key (`ab_live_...`). It restores the session saved on the device without a network call, so `currentUser` is ready right away.

```dart
import 'package:flutter/material.dart';
import 'package:abrova_auth/abrova_auth.dart';

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await AbrovaAuth.initialize('ab_live_your_api_key');
  runApp(const MyApp());
}
```

Then use `AbrovaAuth.instance` anywhere.

<ConfigTable headers={['Option', 'Default', 'Description']} rows={[
  ['apiKey', '-', 'Your public API key (ab_live_...). Never the server secret.'],
  ['timeout', '15 seconds', 'Request timeout.'],
  ['refreshMargin', '2 minutes', 'Renew the access token when less than this is left.'],
  ['storage', 'SecureAbrovaAuthStorage()', 'Where the session is kept. MemoryAbrovaAuthStorage keeps nothing (tests).'],
]} />

<H2 id="sign-in" step={3}>Sign in</H2>

Show only the methods your project has turned on, and sign in only when nobody is signed in yet:

```dart
final auth = AbrovaAuth.instance;

final methods = await auth.getMethods();
// methods.anonymous, methods.apple, methods.google, methods.password, methods.magicLink, methods.telegram

if (auth.currentUser == null && methods.anonymous) {
  await auth.signInAnonymously();
}
print(auth.currentUser!.id); // ru_...
```

`signInAnonymously()` returns the current user when an anonymous user is already signed in on this device.

<H2 id="use-the-user-with-other-abrova-sdks" step={4}>Use the user with other Abrova SDKs</H2>

<Callout kind="soon">Abrova Sync, Chat, Push, Storage and A/B Testing are coming soon. The calls below show how they will take the Auth user; today, attach the user to Abrova Trace with `AbrovaTrace.setUserId(auth.currentUser!.id)`.</Callout>

Pass the token provider. The other SDK asks it for a token when it needs one; Abrova Auth renews the token before it expires, and callers at the same time share one renewal.

```dart
await AbrovaSync.init(AbrovaSyncConfig(
  apiKey: 'ab_live_your_api_key',
  tokenProvider: AbrovaAuth.instance.tokenProvider, // null while signed out
));
```

Abrova Chat takes `AbrovaAuth.instance.chatTokenProvider` (it throws instead of returning null) and `currentUser.id` as its user id. After a sign-in or sign-out, call the other SDK's refresh method, for example `AbrovaSync.refreshUserToken()`. See [Use with other Abrova products](/docs/auth/other-products).

### Sign-in methods

Each method has its own page with the Console setup: [Anonymous](/docs/auth/anonymous), [Apple](/docs/auth/apple), [Google](/docs/auth/google), [E-mail & password](/docs/auth/email-password), [Magic link](/docs/auth/magic-link), [Telegram](/docs/auth/telegram).

#### E-mail and password

```dart
final result = await auth.signUpWithEmail(
  email: email,
  password: password,
  redirectUrl: 'https://example.com/auth/verify', // optional: sends a verification e-mail
);
// result.signedIn is false when the project requires a verified e-mail first.

await auth.signInWithEmail(email: email, password: password);

await auth.sendPasswordReset(email, redirectUrl: 'https://example.com/auth/reset');
await auth.resetPassword(tokenFromLink, newPassword); // ends every session; does not sign in
await auth.verifyEmail(tokenFromLink);
await auth.sendEmailVerification(redirectUrl: 'https://example.com/auth/verify');
```

The links open your `redirectUrl` with `?token=...`. It must start with one of the link addresses in **Abrova Auth › Settings**.

#### Magic link

```dart
await auth.sendMagicLink(email, redirectUrl: 'myapp://auth/magic');
// When the app is opened with the link:
await auth.signInWithMagicLink(Uri.parse(link).queryParameters['token']!);
```

#### Telegram

```dart
final r = await auth.requestTelegramCode('+989121234567');
if (!r.sent && r.botUrl != null) {
  // First time: open r.botUrl so the user starts the bot and shares the number.
}
await auth.verifyTelegramCode('+989121234567', code);
```

#### Apple and Google

Run the provider's native plugin with the **hashed** nonce, and give Abrova the **raw** one:

```dart
final raw = AbrovaAuthNonce.generate();

// sign_in_with_apple
final apple = await SignInWithApple.getAppleIDCredential(
  scopes: [AppleIDAuthorizationScopes.email, AppleIDAuthorizationScopes.fullName],
  nonce: AbrovaAuthNonce.sha256Hex(raw),
);
await auth.signInWithApple(
  idToken: apple.identityToken!,
  rawNonce: raw,
  authorizationCode: apple.authorizationCode, // lets account deletion revoke the Apple sign-in
  name: [apple.givenName, apple.familyName].whereType<String>().join(' '),
);

// google_sign_in 7 — use a new nonce for each sign-in
final rawG = AbrovaAuthNonce.generate();
await GoogleSignIn.instance.initialize(
  serverClientId: 'xxx.apps.googleusercontent.com',
  nonce: AbrovaAuthNonce.sha256Hex(rawG),
);
final account = await GoogleSignIn.instance.authenticate();
await auth.signInWithGoogle(idToken: account.authentication.idToken!, rawNonce: rawG);
```

Add your bundle IDs and Google client IDs in the Console first. Each nonce works once.

Google sign-in needs a connection to Google, and on Android also Google Play services; some users in Iran have neither. Anonymous, e-mail and password, magic link and Telegram code work without Google, so offer at least one of them as well. See [Sign in with Google](/docs/auth/google).

### Upgrade an anonymous user

Linking keeps the user id, so the user's data stays theirs:

```dart
try {
  await auth.linkGoogle(idToken: idToken, rawNonce: raw);
  // or linkApple(...), linkPassword(email: ..., password: ...)
} on AbrovaProviderAlreadyLinkedException {
  // This Google account already has a user: offer to sign in with it instead.
}
```

See [Anonymous users & upgrading](/docs/auth/upgrading).

### The current user

```dart
auth.currentUser;          // AbrovaAuthUser? — null when signed out
auth.isSignedIn;

auth.authStateChanges.listen((user) {
  // Emits the current user first, then on every sign-in, sign-out and profile change.
});

final me = await auth.getMe(); // fresh from the server
final token = await auth.getToken(); // the access token, if you call your own API with it
```

<ConfigTable headers={['Field', 'Type', 'Description']} rows={[
  ['id', 'String', 'The user id (ru_...)'],
  ['anonymous', 'bool', 'True until a method is linked'],
  ['emailVerified', 'bool', 'True once the e-mail is proved'],
  ['createdAt', 'DateTime?', 'When the user was created'],
  ['providers', 'List<String>', 'Linked methods, for example apple, password'],
]} />

### Sign out and delete the account

```dart
await auth.signOut();           // this device; never fails
await auth.signOutEverywhere(); // every device
await auth.deleteAccount();     // deletes the user, then signs out
```

Apple requires apps with sign-in to offer account deletion in the app. See [Security & data](/docs/auth/security).

### Handle errors

Every call throws `AbrovaAuthException`:

```dart
try {
  await auth.signInWithEmail(email: email, password: password);
} on AbrovaAuthException catch (e) {
  switch (e.code) {
    case AbrovaAuthErrorCode.invalidCredentials:
      showError('Wrong e-mail or password');
    case AbrovaAuthErrorCode.rateLimited:
      showError('Too many attempts. Try again in ${e.retryAfter?.inSeconds ?? 60} s');
    case AbrovaAuthErrorCode.networkError:
      showError('No connection');
    default:
      showError('Sign-in failed');
  }
}
```

`code` is one of `AbrovaAuthErrorCode`; `message` is an English hint for developers, not for users. `isNetworkError` and `isSessionEnded` help with the common cases. A network error never signs the user out; when the session ends (revoked, expired, account disabled), the SDK signs out and `authStateChanges` emits `null`. All codes: [Error codes](/docs/auth/error-codes).

### Troubleshooting

<TroubleshootItem title="METHOD_DISABLED or PRODUCT_DISABLED">
  <p>Turn on Abrova Auth under Settings › Products and the method under Abrova Auth › Sign-in methods. Use getMethods() to show only the methods that are on.</p>
</TroubleshootItem>

<TroubleshootItem title="A new anonymous user on every start">
  <p>Call initialize() before reading currentUser, and sign in only when currentUser is null.</p>
</TroubleshootItem>

<TroubleshootItem title="INVALID_ID_TOKEN from Apple or Google">
  <p>Check that the bundle ID, Services ID or client ID is in the Console, and that you gave the provider AbrovaAuthNonce.sha256Hex(raw) and Abrova the raw value.</p>
</TroubleshootItem>

<TroubleshootItem title="Other Abrova SDKs still act as the previous user">
  <p>They cache their token. Call their refresh method (for example AbrovaSync.refreshUserToken()) from your authStateChanges listener.</p>
</TroubleshootItem>

- iOS SDK: https://abrova.ir/en/docs/auth/ios

<BestPracticeList columns={2} items={[
  ['Client-Safe', 'Uses the public API key only. Safe to ship in an app'],
  ['Apple in One Call', 'signInWithAppleNative() runs the sheet, nonce included'],
  ['Keychain', 'Refresh token on this device only; access token in memory'],
  ['Token Providers', 'tokenProvider and strictTokenProvider for the other Abrova SDKs'],
  ['Swift Concurrency', 'async/await API'],
  ['Upgrade Guests', 'linkApple, linkGoogle, linkPassword keep the user id'],
]} />

<Callout kind="note" title="Abrova Auth iOS SDK v0.1.1">
This page describes `AbrovaAuth` 0.1.1.
</Callout>

<Callout kind="note" title="Requirements">
iOS 13 or later, or macOS 12 or later. Swift 5.7 or later.
</Callout>

Using an AI assistant? Give it this page with **Copy page for AI**, or all the docs as plain text from [/docs/llms.txt](/docs/llms.txt). See [AI assistants](/docs/auth/ai-assistants).

<H2 id="installation" step={1}>Installation</H2>

Install with Swift Package Manager. In Xcode: **File → Add Packages** → enter the repository URL:

```text
https://github.com/Abrova-co/abrova-auth-ios-sdk
```

Or add it to your `Package.swift`:

```swift
dependencies: [
    .package(url: "https://github.com/Abrova-co/abrova-auth-ios-sdk.git", from: "0.1.1")
]
```

Then add `AbrovaAuth` to your target's dependencies.

In Abrova Console, turn on **Abrova Auth** for your project (**Settings › Products**) and the sign-in methods you want (**Abrova Auth › Sign-in methods**).

<H2 id="initialization" step={2}>Initialization</H2>

Configure the SDK once at app start, before any other call, with your public API key (`ab_live_...`). A session saved by an earlier launch is restored.

```swift
import AbrovaAuth

@main
struct MyApp: App {
    init() {
        AbrovaAuth.shared.configure(apiKey: "ab_live_your_api_key")
    }
    var body: some Scene { WindowGroup { ContentView() } }
}
```

<ConfigTable headers={['Parameter', 'Default', 'Description']} rows={[
  ['apiKey', '-', 'Your public API key (ab_live_...). Never the server secret.'],
  ['keychainAccessGroup', 'nil', 'Share the session with your app extensions.'],
]} />

The Keychain survives an uninstall, so the SDK forgets a session left by a previous install: a fresh install starts signed out.

<H2 id="sign-in" step={3}>Sign in</H2>

```swift
let auth = AbrovaAuth.shared

let methods = try await auth.getMethods()
if auth.currentUserId == nil && methods.isEnabled("anonymous") {
    try await auth.signInAnonymously()
}
print(auth.currentUserId!) // ru_...
```

Show only the buttons for methods where `methods.isEnabled(...)` is true: `anonymous`, `apple`, `google`, `password`, `magicLink`, `telegram`.

<H2 id="use-the-user-with-other-abrova-sdks" step={4}>Use the user with other Abrova SDKs</H2>

<Callout kind="soon">Abrova Sync, Chat, Push, Storage and A/B Testing are coming soon. The calls below show how they will take the Auth user; today, attach the user to Abrova Trace with `AbrovaTrace.shared.setUserId(auth.currentUserId)`.</Callout>

```swift
// Abrova Sync
sync.userTokens.provider = auth.tokenProvider

// Abrova Push
AbrovaPushConfig(apiKey: key, tokenProvider: auth.tokenProvider)

// Abrova Chat: create the client after sign-in
AbrovaChatConfig(apiKey: key, userId: auth.currentUserId!, tokenProvider: auth.strictTokenProvider)
```

`tokenProvider` returns `nil` when nobody is signed in; `strictTokenProvider` throws. Both return a token that is renewed before it expires. After a sign-in or sign-out, call the other SDK's refresh method (for example `sync.refreshUserToken()`). Abrova A/B Testing and more: [Use with other Abrova products](/docs/auth/other-products).

### Sign-in methods

Each method has its own page with the Console setup: [Anonymous](/docs/auth/anonymous), [Apple](/docs/auth/apple), [Google](/docs/auth/google), [E-mail & password](/docs/auth/email-password), [Magic link](/docs/auth/magic-link), [Telegram](/docs/auth/telegram).

#### Sign in with Apple

Add the **Sign in with Apple** capability to your app and your bundle ID under **Abrova Auth › Sign-in methods › Apple**. Then:

```swift
try await AbrovaAuth.shared.signInWithAppleNative()
```

The SDK runs Apple's sheet with a nonce and passes the authorization code (so account deletion can revoke the Apple sign-in) and the name Apple shares on the first sign-in. It throws `.canceled` when the user closes the sheet. If you run the Apple request yourself:

```swift
let rawNonce = AbrovaNonce.generate()
request.nonce = AbrovaNonce.sha256(rawNonce)   // to Apple
// ... when Apple answers:
try await auth.signInWithApple(idToken: idToken, rawNonce: rawNonce,
                               authorizationCode: code, fullName: name)
```

#### Sign in with Google

Request the Google ID token with `AbrovaNonce.sha256(rawNonce)` as its nonce, then:

```swift
try await auth.signInWithGoogle(idToken: idToken, rawNonce: rawNonce)
```

Google sign-in needs a connection to Google, which some users in Iran don’t have. Anonymous, e-mail and password, magic link and Telegram code work without Google, so offer at least one of them as well. See [Sign in with Google](/docs/auth/google).

#### E-mail and password

```swift
let result = try await auth.signUp(email: email, password: password,
                                   redirectURL: "https://example.com/auth/verify")
// result.signedIn is false when the project requires a verified e-mail first.

try await auth.signIn(email: email, password: password)

try await auth.sendPasswordReset(email: email, redirectURL: "https://example.com/auth/reset")
try await auth.resetPassword(token: token, newPassword: newPassword) // ends every session
try await auth.verifyEmail(token: token)
try await auth.sendEmailVerification(redirectURL: "https://example.com/auth/verify")
```

`AbrovaAuth.token(in: url)` reads the `token` from the link the app was opened with.

#### Magic link

```swift
try await auth.sendMagicLink(email: email, redirectURL: "myapp://auth/magic")
// When the app is opened with the link:
try await auth.signInWithMagicLink(url: openedURL)
```

#### Telegram

```swift
let code = try await auth.requestTelegramCode(phone: "+989121234567")
if !code.sent, let url = code.botURL { await UIApplication.shared.open(url) }
try await auth.verifyTelegramCode(phone: "+989121234567", code: "123456")
```

### Upgrade an anonymous user

Linking keeps the user id, so everything they created stays theirs:

```swift
do {
    try await auth.signInWithAppleNative(link: true)
    // or linkGoogle(idToken:rawNonce:), linkApple(...), linkPassword(email:password:)
} catch let error as AbrovaAuthError where error.code == .providerAlreadyLinked {
    // This Apple ID already belongs to another user.
}
```

### The current user

```swift
auth.currentUserId                  // nil when signed out
auth.isSignedIn
let user = try await auth.me()      // AbrovaUser: id, isAnonymous, emailVerified, createdAt, providers
auth.currentUser                    // the profile last loaded by me()

let listener = auth.addAuthStateListener { userId in
    // On the main queue: now, then on every sign-in, sign-out and session end
}
listener.remove()

let token = try await auth.getAccessToken() // if you call your own API with it
```

### Sign out and delete the account

```swift
await auth.signOut()                // this device; never fails
try await auth.signOutEverywhere()  // every device
try await auth.deleteAccount()      // required by the App Store for apps with sign-in
```

See [Security & data](/docs/auth/security) for what deletion removes.

### Handle errors

Every error is an `AbrovaAuthError`. Branch on `code`:

```swift
do {
    try await auth.signIn(email: email, password: password)
} catch let error as AbrovaAuthError {
    switch error.code {
    case .invalidCredentials: showError("Wrong e-mail or password")
    case .rateLimited: showError("Try again in \(error.retryAfterSec ?? 60) s")
    case .network: showError("No connection")
    default: showError("Sign-in failed")
    }
}
```

`message` is an English hint for developers. Besides the server's codes the SDK uses `.network`, `.canceled` (the user closed the Apple sheet), `.notSignedIn` and `.sdkNotConfigured` (call `configure` first). A network error never signs the user out. All codes: [Error codes](/docs/auth/error-codes).

### Troubleshooting

<TroubleshootItem title="SDK_NOT_CONFIGURED">
  <p>Call AbrovaAuth.shared.configure(apiKey:) at app start, before any other call.</p>
</TroubleshootItem>

<TroubleshootItem title="Sign in with Apple fails with INVALID_ID_TOKEN">
  <p>Add your app's bundle ID under Abrova Auth › Sign-in methods › Apple, and the Sign in with Apple capability to the target.</p>
</TroubleshootItem>

<TroubleshootItem title="METHOD_DISABLED or PRODUCT_DISABLED">
  <p>Turn on Abrova Auth under Settings › Products and the method under Abrova Auth › Sign-in methods.</p>
</TroubleshootItem>

- Android SDK: https://abrova.ir/en/docs/auth/android

<BestPracticeList columns={2} items={[
  ['Client-Safe', 'Uses the public API key only. Safe to ship in an app'],
  ['Coroutines', 'Every call is a suspend function'],
  ['Keystore', 'Refresh token encrypted with a key that never leaves the Android Keystore'],
  ['Token Providers', 'Suspend, strict and blocking providers for the other Abrova SDKs'],
  ['StateFlow', 'authState for Compose and coroutines, or a classic listener'],
  ['Upgrade Guests', 'linkApple, linkGoogle, linkPassword keep the user id'],
]} />

<Callout kind="note" title="Abrova Auth Android SDK v0.1.1">
This page describes `ir.abrova:abrova-auth` 0.1.1.
</Callout>

<Callout kind="note" title="Requirements">
Android API 23 (Android 6.0) or higher. Kotlin coroutines.
</Callout>

Using an AI assistant? Give it this page with **Copy page for AI**, or all the docs as plain text from [/docs/llms.txt](/docs/llms.txt). See [AI assistants](/docs/auth/ai-assistants).

<H2 id="installation" step={1}>Installation</H2>

The SDK comes from Abrova Center. First add the Abrova Maven repository in `settings.gradle.kts`:

<Code file="settings.gradle.kts" lang="Kotlin">{`dependencyResolutionManagement {
    repositories {
        google()
        mavenCentral()
        maven { url = uri("https://center.abrova.ir/api/packages/abrova/maven") }
    }
}`}</Code>

Then add the dependency in your app's `build.gradle.kts`:

```kotlin
dependencies {
    implementation("ir.abrova:abrova-auth:0.1.1")
}
```

In Abrova Console, turn on **Abrova Auth** for your project (**Settings › Products**) and the sign-in methods you want (**Abrova Auth › Sign-in methods**).

<H2 id="initialization" step={2}>Initialization</H2>

Configure the SDK once, in `Application.onCreate`, with your public API key (`ab_live_...`). A session saved by an earlier launch is restored.

```kotlin
import ir.abrova.auth.AbrovaAuth

class MyApp : Application() {
    override fun onCreate() {
        super.onCreate()
        AbrovaAuth.shared.configure(this, "ab_live_your_api_key")
    }
}
```

All sign-in calls are `suspend` functions: call them from a coroutine (for example `lifecycleScope.launch { ... }`).

<H2 id="sign-in" step={3}>Sign in</H2>

```kotlin
val auth = AbrovaAuth.shared

val methods = auth.getMethods()
if (auth.currentUserId == null && methods.isEnabled("anonymous")) {
    auth.signInAnonymously()
}
Log.d("Auth", auth.currentUserId!!) // ru_...
```

Show only the buttons for methods where `methods.isEnabled(...)` is true: `anonymous`, `apple`, `google`, `password`, `magicLink`, `telegram`.

<H2 id="use-the-user-with-other-abrova-sdks" step={4}>Use the user with other Abrova SDKs</H2>

<Callout kind="soon">Abrova Sync, Chat, Push, Storage and A/B Testing are coming soon. The calls below show how they will take the Auth user; today, attach the user to Abrova Trace with `AbrovaTrace.setUserId(auth.currentUserId)`.</Callout>

```kotlin
// Abrova Sync: its provider is called off the main thread
AbrovaSyncConfig.builder(apiKey).userTokenProvider(auth.blockingTokenProvider).build()

// Abrova Push
AbrovaPushConfig(apiKey = apiKey, tokenProvider = auth.tokenProvider)

// Abrova Chat: create the client after sign-in
AbrovaChatConfig(apiKey = apiKey, userId = auth.currentUserId!!, tokenProvider = auth.strictTokenProvider)
```

<ConfigTable headers={['Provider', 'Type', 'When nobody is signed in']} rows={[
  ['tokenProvider', 'suspend () -> String?', 'Returns null'],
  ['strictTokenProvider', 'suspend () -> String', 'Throws NOT_SIGNED_IN'],
  ['blockingTokenProvider', '() -> String?', 'Returns null. Blocks the calling thread: never call it on the main thread'],
]} />

All return a token that is renewed before it expires. After a sign-in or sign-out, call the other SDK's refresh method (for example `sync.userTokens.refresh()`). Abrova A/B Testing and more: [Use with other Abrova products](/docs/auth/other-products).

### Sign-in methods

Each method has its own page with the Console setup: [Anonymous](/docs/auth/anonymous), [Apple](/docs/auth/apple), [Google](/docs/auth/google), [E-mail & password](/docs/auth/email-password), [Magic link](/docs/auth/magic-link), [Telegram](/docs/auth/telegram).

#### Sign in with Google

Use Credential Manager with your **web** client ID and a hashed nonce. Add `androidx.credentials:credentials`, `androidx.credentials:credentials-play-services-auth` and `com.google.android.libraries.identity.googleid:googleid` to your app:

```kotlin
val rawNonce = AbrovaNonce.generate()
val option = GetGoogleIdOption.Builder()
    .setServerClientId(WEB_CLIENT_ID)
    .setFilterByAuthorizedAccounts(false)
    .setNonce(AbrovaNonce.sha256(rawNonce))
    .build()
val response = CredentialManager.create(context)
    .getCredential(context, GetCredentialRequest.Builder().addCredentialOption(option).build())
val idToken = GoogleIdTokenCredential.createFrom(response.credential.data).idToken

auth.signInWithGoogle(idToken, rawNonce)
```

Add the web client ID under **Abrova Auth › Sign-in methods › Google**.

Google sign-in needs a connection to Google, and on Android also Google Play services; some users in Iran have neither. Anonymous, e-mail and password, magic link and Telegram code work without Google, so offer at least one of them as well. See [Sign in with Google](/docs/auth/google).

#### Sign in with Apple

Run Apple's web sign-in with your **Services ID** and `AbrovaNonce.sha256(rawNonce)` as the nonce, then pass the `id_token` and `code` Apple returns:

```kotlin
auth.signInWithApple(idToken, rawNonce, authorizationCode = code)
```

#### E-mail and password

```kotlin
val result = auth.signUp(email, password, redirectUrl = "https://example.com/auth/verify")
// result.signedIn is false when the project requires a verified e-mail first.

auth.signIn(email, password)

auth.sendPasswordReset(email, redirectUrl = "https://example.com/auth/reset")
auth.resetPassword(token, newPassword) // ends every session; does not sign in
auth.verifyEmail(token)
auth.sendEmailVerification(redirectUrl = "https://example.com/auth/verify")
```

#### Magic link

```kotlin
auth.sendMagicLink(email, redirectUrl = "myapp://auth/magic")
// In the activity the link opens:
AbrovaAuth.tokenFromLink(intent.dataString ?: "")?.let { auth.signInWithMagicLink(it) }
```

#### Telegram

```kotlin
val code = auth.requestTelegramCode("+989121234567")
if (!code.sent) startActivity(Intent(Intent.ACTION_VIEW, Uri.parse(code.botUrl)))
auth.verifyTelegramCode("+989121234567", "123456")
```

### Upgrade an anonymous user

Linking keeps the user id, so everything they created stays theirs:

```kotlin
try {
    auth.linkGoogle(idToken, rawNonce)   // or linkApple(...), linkPassword(email, password)
} catch (e: AbrovaAuthException) {
    if (e.code == AbrovaAuthErrorCode.PROVIDER_ALREADY_LINKED) {
        // This Google account already belongs to another user.
    }
}
```

### The current user

```kotlin
auth.currentUserId                 // null when signed out
auth.isSignedIn
val user = auth.me()               // AbrovaUser: id, isAnonymous, emailVerified, createdAt, providers
auth.currentUser                   // the profile last loaded by me()

// StateFlow of the user id
lifecycleScope.launch { auth.authState.collect { userId -> /* sign-in, sign-out, session end */ } }

// Or a listener
val registration = auth.addAuthStateListener { userId -> }
registration.remove()

val token = auth.getAccessToken()  // if you call your own API with it
```

### Sign out and delete the account

```kotlin
auth.signOut()            // this device; never fails
auth.signOutEverywhere()  // every device
auth.deleteAccount()      // deletes the user, then signs out
```

See [Security & data](/docs/auth/security) for what deletion removes.

### Handle errors

Every error is an `AbrovaAuthException`. Branch on `code`:

```kotlin
try {
    auth.signIn(email, password)
} catch (e: AbrovaAuthException) {
    when (e.code) {
        AbrovaAuthErrorCode.INVALID_CREDENTIALS -> showError("Wrong e-mail or password")
        AbrovaAuthErrorCode.RATE_LIMITED -> showError("Try again in ${e.retryAfterSec ?: 60} s")
        AbrovaAuthErrorCode.NETWORK_ERROR -> showError("No connection")
        else -> showError("Sign-in failed")
    }
}
```

`message` is an English hint for developers. Besides the server's codes the SDK uses `NETWORK_ERROR`, `NOT_SIGNED_IN` and `SDK_NOT_CONFIGURED` (call `configure` first). A network error never signs the user out. All codes: [Error codes](/docs/auth/error-codes).

### Troubleshooting

<TroubleshootItem title="SDK_NOT_CONFIGURED">
  <p>Call AbrovaAuth.shared.configure(context, apiKey) in Application.onCreate.</p>
</TroubleshootItem>

<TroubleshootItem title="Google sign-in fails with INVALID_ID_TOKEN">
  <p>Credential Manager issues the ID token to the web client ID you pass as serverClientId. Add that web client ID in the Console, and pass AbrovaNonce.sha256(rawNonce) as the nonce.</p>
</TroubleshootItem>

<TroubleshootItem title="The app freezes when Sync asks for a token">
  <p>blockingTokenProvider blocks its thread. Give it only to SDKs that call it off the main thread, and never call it yourself on the main thread.</p>
</TroubleshootItem>

- Web SDK: https://abrova.ir/en/docs/auth/web

<BestPracticeList columns={2} items={[
  ['Client-Safe', 'Uses the public API key only. Safe in a browser bundle'],
  ['Any Framework', 'Plain TypeScript: React, Vue, Svelte, Next.js client code, or none'],
  ['Memory by Default', 'Nothing is stored unless you opt in'],
  ['Token Provider', 'tokenProvider and getToken() for the other Abrova SDKs'],
  ['Nonce Helper', 'createNonce() for Apple JS and Google Identity Services'],
  ['Upgrade Guests', 'linkApple, linkGoogle, linkPassword keep the user id'],
]} />

<Callout kind="note" title="Abrova Auth Web SDK v0.1.1">
This page describes `@abrova/auth-web` 0.1.1.
</Callout>

<Callout kind="note" title="Requirements">
A browser with `fetch` and `crypto.getRandomValues` (every current browser). Runs in client code only; Abrova Auth has no server SDK.
</Callout>

Using an AI assistant? Give it this page with **Copy page for AI**, or all the docs as plain text from [/docs/llms.txt](/docs/llms.txt). See [AI assistants](/docs/auth/ai-assistants).

<H2 id="installation" step={1}>Installation</H2>

The package comes from Abrova Center. First point the `@abrova` scope at the Abrova registry in your project's `.npmrc`:

<Code file=".npmrc" lang="INI">{`@abrova:registry=https://center.abrova.ir/api/packages/abrova/npm/`}</Code>

Then install:

```bash
npm install @abrova/auth-web
```

Or in `package.json`:

```json
{
  "dependencies": {
    "@abrova/auth-web": "^0.1.1"
  }
}
```

In Abrova Console, turn on **Abrova Auth** for your project (**Settings › Products**) and the sign-in methods you want (**Abrova Auth › Sign-in methods**).

<H2 id="initialization" step={2}>Initialization</H2>

Create one client for your app, with your public API key (`ab_live_...`):

```typescript
import { createAbrovaAuth } from '@abrova/auth-web';

export const auth = createAbrovaAuth({ apiKey: 'ab_live_your_api_key' });

auth.onAuthStateChanged((userId) => {
  console.log(userId ? `signed in as ${userId}` : 'signed out');
});
```

<ConfigTable headers={['Option', 'Default', 'Description']} rows={[
  ['apiKey', '-', 'Your public API key (ab_live_...). Never the server secret.'],
  ['storage', 'memory', 'Where the refresh token is kept between page loads. See Staying signed in.'],
  ['storageKey', 'derived from the API key', 'Storage key, so two projects never share a session.'],
  ['timeoutMs', '15000', 'Request timeout in milliseconds.'],
]} />

`await auth.ready()` resolves once a stored session (if any) is loaded. `onAuthStateChanged` calls your listener with the current user id at that point, and again on every sign-in or sign-out. It returns a function that stops listening.

<H2 id="sign-in" step={3}>Sign in</H2>

```typescript
const { methods } = await auth.getMethods(); // e.g. ['anonymous', 'google', 'password']

await auth.ready();
if (!auth.isSignedIn && methods.includes('anonymous')) {
  await auth.signInAnonymously();
}
console.log(auth.currentUserId); // ru_...
```

Show only the buttons for the methods `getMethods()` returns.

<H2 id="use-the-user-with-other-abrova-sdks" step={4}>Use the user with other Abrova SDKs</H2>

<Callout kind="soon">Abrova Sync, Chat, Push, Storage and A/B Testing are coming soon. The calls below show how they will take the Auth user; today, attach the user to Abrova Trace with its Next.js SDK (`setUserId(auth.currentUserId)`).</Callout>

```typescript
import { AbrovaSync } from '@abrova/sync-web';

// Sync, Push and A/B Testing: null while signed out
const sync = new AbrovaSync({ apiKey: 'ab_live_your_api_key', tokenProvider: () => auth.getToken() });
```

`auth.getToken()` resolves to a fresh access token, or `null` when nobody is signed in. `auth.tokenProvider` resolves to the token and rejects with `UNAUTHENTICATED` when nobody is signed in: use it for Abrova Chat, whose provider must return a token. After a sign-in or sign-out, call the other SDK's refresh method (for example `sync.refreshUserToken()`). More: [Use with other Abrova products](/docs/auth/other-products).

### Sign-in methods

Each method has its own page with the Console setup: [Anonymous](/docs/auth/anonymous), [Apple](/docs/auth/apple), [Google](/docs/auth/google), [E-mail & password](/docs/auth/email-password), [Magic link](/docs/auth/magic-link), [Telegram](/docs/auth/telegram).

#### E-mail and password

```typescript
const result = await auth.signUpWithEmail({ email, password, redirectUrl: 'https://example.com/auth/verify' });
// result.signedIn is false when the project requires a verified e-mail first.

await auth.signInWithEmail({ email, password });

await auth.sendPasswordReset({ email, redirectUrl: 'https://example.com/auth/reset' });
await auth.resetPassword({ token, password }); // token from the link's ?token=
await auth.verifyEmail({ token });
await auth.sendEmailVerification({ redirectUrl: 'https://example.com/auth/verify' });
```

#### Magic link

```typescript
await auth.sendMagicLink({ email, redirectUrl: 'https://example.com/auth/magic' });

// On the page the link opens:
const token = new URL(location.href).searchParams.get('token');
if (token) await auth.signInWithMagicLink({ token });
```

#### Telegram

```typescript
const { sent, botUrl } = await auth.requestTelegramCode({ phone: '+989121234567' });
if (!sent && botUrl) window.open(botUrl); // the user starts the bot and shares the number
await auth.verifyTelegramCode({ phone: '+989121234567', code: '123456' });
```

#### Apple and Google

Run the provider's own sign-in with a nonce from the SDK, then hand its ID token to Abrova:

```typescript
const { rawNonce, hashedNonce } = await auth.createNonce();
// Give hashedNonce to Google Identity Services or Sign in with Apple JS as the `nonce`.
await auth.signInWithGoogle({ idToken, rawNonce });
await auth.signInWithApple({ idToken, rawNonce, authorizationCode, name });
```

Create a new nonce for every sign-in. Google sign-in needs a connection to Google, which some users in Iran don’t have. Anonymous, e-mail and password, magic link and Telegram code work without Google, so offer at least one of them as well. See [Sign in with Google](/docs/auth/google). On the web, Apple uses your **Services ID**: add it under **Abrova Auth › Sign-in methods › Apple**.

### Upgrade an anonymous user

Linking keeps the user id, so the user's data stays theirs:

```typescript
import { isAbrovaAuthError } from '@abrova/auth-web';

try {
  await auth.linkGoogle({ idToken, rawNonce }); // or linkApple(...), linkPassword({ email, password })
} catch (e) {
  if (isAbrovaAuthError(e) && e.code === 'PROVIDER_ALREADY_LINKED') {
    // This Google account already belongs to another user.
  }
}
```

### The current user

```typescript
auth.currentUserId;           // null when signed out
auth.isSignedIn;
const me = await auth.getMe(); // { id, anonymous, emailVerified, createdAt, providers }
auth.currentUser;             // the user last loaded by getMe()
```

### Sign out and delete the account

```typescript
await auth.signOut();           // this device
await auth.signOutEverywhere(); // every device
await auth.deleteAccount();     // deletes the user, then signs out
```

### Staying signed in

By default nothing is stored: the user signs in again after a page reload. To keep the session, opt in to `localStorage`:

```typescript
import { createAbrovaAuth, localStorageStorage } from '@abrova/auth-web';

const auth = createAbrovaAuth({ apiKey: 'ab_live_your_api_key', storage: localStorageStorage() });
```

<Callout kind="warn" title="localStorage and XSS">
Any script on your page can read `localStorage`. An XSS bug or a compromised dependency could take the refresh token and with it the user's session. Use this only with a strict Content Security Policy and no untrusted scripts. The SDK never sets cookies.
</Callout>

You can also pass your own storage: an object with async `get`, `set` and `remove`.

### Handle errors

Every failure is an `AbrovaAuthError` with a `code`:

```typescript
import { isAbrovaAuthError } from '@abrova/auth-web';

try {
  await auth.signInWithEmail({ email, password });
} catch (e) {
  if (isAbrovaAuthError(e) && e.code === 'INVALID_CREDENTIALS') showError('Wrong e-mail or password');
  if (isAbrovaAuthError(e) && e.code === 'RATE_LIMITED') retryIn(e.retryAfterSec);
}
```

Besides the server's codes the SDK uses `NETWORK_ERROR`. A network error never signs the user out; a revoked or expired session does (`onAuthStateChanged(null)`). The access token is renewed 2 minutes before it expires, and calls at the same time share one renewal. All codes: [Error codes](/docs/auth/error-codes).

### Troubleshooting

<TroubleshootItem title="Signed out after every reload">
  <p>That is the default: the session is kept in memory. Pass storage: localStorageStorage() if your page has a strict Content Security Policy, or sign in anonymously again.</p>
</TroubleshootItem>

<TroubleshootItem title="currentUserId is null right after a reload">
  <p>The stored session loads asynchronously. Wait for auth.ready() or the first onAuthStateChanged call.</p>
</TroubleshootItem>

<TroubleshootItem title="E-mail link refused with INVALID_INPUT">
  <p>The redirectUrl must start with one of the link addresses under Abrova Auth › Settings.</p>
</TroubleshootItem>

- React Native SDK: https://abrova.ir/en/docs/auth/react-native

<BestPracticeList columns={2} items={[
  ['Client-Safe', 'Uses the public API key only. Safe to ship in an app'],
  ['Expo or Bare', 'react-native-keychain or expo-secure-store for the session'],
  ['Secure Storage', 'Refresh token on this device only; access token in memory'],
  ['Token Provider', 'tokenProvider and getToken() for the other Abrova SDKs'],
  ['Same API as Web', 'One set of calls for your web and mobile code'],
  ['Upgrade Guests', 'linkApple, linkGoogle, linkPassword keep the user id'],
]} />

<Callout kind="note" title="Abrova Auth React Native SDK v0.1.1">
This page describes `@abrova/auth-react-native` 0.1.1.
</Callout>

<Callout kind="note" title="Requirements">
React Native with `react-native-keychain`, or Expo with `expo-secure-store`. Apple and Google sign-in also need `crypto.getRandomValues` (`react-native-get-random-values`).
</Callout>

Using an AI assistant? Give it this page with **Copy page for AI**, or all the docs as plain text from [/docs/llms.txt](/docs/llms.txt). See [AI assistants](/docs/auth/ai-assistants).

<H2 id="installation" step={1}>Installation</H2>

The package comes from Abrova Center. First point the `@abrova` scope at the Abrova registry in your project's `.npmrc`:

<Code file=".npmrc" lang="INI">{`@abrova:registry=https://center.abrova.ir/api/packages/abrova/npm/`}</Code>

Then install it with one of the secure storage libraries:

```bash
npm install @abrova/auth-react-native react-native-keychain
# or, with Expo
npx expo install @abrova/auth-react-native expo-secure-store
```

Or in `package.json`:

```json
{
  "dependencies": {
    "@abrova/auth-react-native": "^0.1.1"
  }
}
```

For Apple and Google sign-in nonces, also install `react-native-get-random-values` and import it first thing in `index.js`:

```bash
npm install react-native-get-random-values
```

```typescript
// index.js, before anything else
import 'react-native-get-random-values';
```

In Abrova Console, turn on **Abrova Auth** for your project (**Settings › Products**) and the sign-in methods you want (**Abrova Auth › Sign-in methods**).

<H2 id="initialization" step={2}>Initialization</H2>

Create one client for your app, with your public API key (`ab_live_...`) and secure storage:

```typescript
import * as Keychain from 'react-native-keychain';
import { createAbrovaAuth, keychainStorage } from '@abrova/auth-react-native';

export const auth = createAbrovaAuth({
  apiKey: 'ab_live_your_api_key',
  storage: keychainStorage(Keychain),
});

auth.onAuthStateChanged((userId) => {
  console.log(userId ? `signed in as ${userId}` : 'signed out');
});
```

With Expo:

```typescript
import * as SecureStore from 'expo-secure-store';
import { createAbrovaAuth, secureStoreStorage } from '@abrova/auth-react-native';

export const auth = createAbrovaAuth({ apiKey: 'ab_live_your_api_key', storage: secureStoreStorage(SecureStore) });
```

Only the refresh token is stored (Keychain on iOS, Keystore-backed storage on Android, this device only). The access token stays in memory. **Without a `storage`, nothing survives an app restart.**

`await auth.ready()` resolves once the stored session is loaded. `onAuthStateChanged` calls your listener with the current user id at that point, and again on every sign-in or sign-out.

<H2 id="sign-in" step={3}>Sign in</H2>

```typescript
const { methods } = await auth.getMethods(); // e.g. ['anonymous', 'apple', 'google']

await auth.ready();
if (!auth.isSignedIn && methods.includes('anonymous')) {
  await auth.signInAnonymously();
}
console.log(auth.currentUserId); // ru_...
```

<H2 id="use-the-user-with-other-abrova-sdks" step={4}>Use the user with other Abrova SDKs</H2>

<Callout kind="soon">Abrova Sync, Chat, Push, Storage and A/B Testing are coming soon. The calls below show how they will take the Auth user; they are not available yet.</Callout>

```typescript
import AbrovaSync from '@abrova/sync-react-native';

// Sync, Push and A/B Testing: null while signed out
await AbrovaSync.init({ apiKey: 'ab_live_your_api_key', tokenProvider: () => auth.getToken() });
```

`auth.getToken()` resolves to a fresh access token, or `null` when nobody is signed in. `auth.tokenProvider` rejects with `UNAUTHENTICATED` instead: use it for Abrova Chat. When the user signs in or out, ask the other SDKs to fetch a new token (for example `AbrovaSync.refreshUserToken()`). More: [Use with other Abrova products](/docs/auth/other-products).

### Sign-in methods

Each method has its own page with the Console setup: [Anonymous](/docs/auth/anonymous), [Apple](/docs/auth/apple), [Google](/docs/auth/google), [E-mail & password](/docs/auth/email-password), [Magic link](/docs/auth/magic-link), [Telegram](/docs/auth/telegram).

#### E-mail and password

```typescript
const result = await auth.signUpWithEmail({ email, password, redirectUrl: 'myapp://auth/verify' });
// result.signedIn is false when the project requires a verified e-mail first.

await auth.signInWithEmail({ email, password });

await auth.sendPasswordReset({ email, redirectUrl: 'myapp://auth/reset' });
await auth.resetPassword({ token, password }); // token from the link's ?token=
await auth.verifyEmail({ token });
```

#### Magic link

```typescript
await auth.sendMagicLink({ email, redirectUrl: 'myapp://auth/magic' });

// When the app is opened with the link (Linking):
const token = new URL(url).searchParams.get('token');
if (token) await auth.signInWithMagicLink({ token });
```

#### Telegram

```typescript
import { Linking } from 'react-native';

const { sent, botUrl } = await auth.requestTelegramCode({ phone: '+989121234567' });
if (!sent && botUrl) await Linking.openURL(botUrl);
await auth.verifyTelegramCode({ phone: '+989121234567', code: '123456' });
```

#### Apple and Google

Run the native sign-in with a nonce from the SDK, then hand its ID token to Abrova:

```typescript
const { rawNonce, hashedNonce } = await auth.createNonce();
// Give hashedNonce to your Apple / Google sign-in library as the `nonce`.
await auth.signInWithApple({ idToken, rawNonce, authorizationCode });
await auth.signInWithGoogle({ idToken, rawNonce });
```

Create a new nonce for every sign-in. Google sign-in needs a connection to Google, and on Android also Google Play services; some users in Iran have neither. Anonymous, e-mail and password, magic link and Telegram code work without Google, so offer at least one of them as well. See [Sign in with Google](/docs/auth/google).

### Upgrade an anonymous user

Linking keeps the user id, so the user's data stays theirs:

```typescript
import { isAbrovaAuthError } from '@abrova/auth-react-native';

try {
  await auth.linkApple({ idToken, rawNonce }); // or linkGoogle(...), linkPassword({ email, password })
} catch (e) {
  if (isAbrovaAuthError(e) && e.code === 'PROVIDER_ALREADY_LINKED') {
    // This Apple ID already belongs to another user.
  }
}
```

### The current user

```typescript
auth.currentUserId;           // null when signed out
auth.isSignedIn;
const me = await auth.getMe(); // { id, anonymous, emailVerified, createdAt, providers }
auth.currentUser;             // the user last loaded by getMe()
```

### Sign out and delete the account

```typescript
await auth.signOut();           // this device
await auth.signOutEverywhere(); // every device
await auth.deleteAccount();     // deletes the user, then signs out (required by the App Store)
```

### Handle errors

Every failure is an `AbrovaAuthError` with a `code`:

```typescript
import { isAbrovaAuthError } from '@abrova/auth-react-native';

try {
  await auth.signInWithEmail({ email, password });
} catch (e) {
  if (isAbrovaAuthError(e) && e.code === 'INVALID_CREDENTIALS') showError('Wrong e-mail or password');
  if (isAbrovaAuthError(e) && e.code === 'RATE_LIMITED') retryIn(e.retryAfterSec);
}
```

Besides the server's codes the SDK uses `NETWORK_ERROR`. A network error never signs the user out; a revoked or expired session does (`onAuthStateChanged(null)`). The access token is renewed 2 minutes before it expires, and calls at the same time share one renewal. All codes: [Error codes](/docs/auth/error-codes).

### Troubleshooting

<TroubleshootItem title="Signed out after every restart">
  <p>Pass storage: keychainStorage(Keychain) or secureStoreStorage(SecureStore). Without it, the session is kept in memory only.</p>
</TroubleshootItem>

<TroubleshootItem title="createNonce fails with NOT_CONFIGURED">
  <p>crypto.getRandomValues is missing. Install react-native-get-random-values and import it first in index.js.</p>
</TroubleshootItem>

<TroubleshootItem title="E-mail link refused with INVALID_INPUT">
  <p>The redirectUrl must start with one of the link addresses under Abrova Auth › Settings, for example myapp://auth.</p>
</TroubleshootItem>

- AI assistants (coming soon): https://abrova.ir/en/docs/auth/ai-assistants

<Callout kind="soon">
There is no Abrova docs server for AI assistants yet. This page says what it will do, and what works today.
</Callout>

### What it will do

Once it launches, you connect your AI assistant (for example a coding assistant in your editor) to it once. When you ask it to add Abrova Auth to your app, the assistant looks up the current SDK version, install lines and setup steps from these docs instead of answering from memory.

It will be read-only, with tools like these:

<ConfigTable headers={['Tool', 'What it does']} rows={[
  ['list_products', 'What Abrova offers, with the platforms that have an SDK.'],
  ['search_docs', 'Finds the docs pages for a few words or a short question.'],
  ['read_doc', 'Reads one docs page.'],
  ['get_sdk_info', 'The current SDK version and install lines for a product and platform.'],
  ['get_setup_guide', 'The ordered setup steps for a product and platform.'],
]} />

### Privacy

- **It reads:** the public Abrova docs, current SDK versions, and the words your assistant sends it.
- **It never sees:** your code, your projects, your keys or your users.

<Callout kind="warn" title="Keep your keys out of the chat">
Never paste a key into a chat with an AI assistant. Let it write the placeholder from the docs (`ab_live_your_api_key`) and put the real value in your project's configuration yourself.
</Callout>

### What works today

- **Copy page for AI** on every docs page copies that page as plain text, ready to paste into your assistant.
- [/docs/llms.txt](/docs/llms.txt) has every docs page as plain text, for assistants that can read a link.

Good pages to start with: [Overview & quick start](/docs/auth/quick-start) and the SDK page for your platform ([Flutter](/docs/auth/flutter), [iOS](/docs/auth/ios), [Android](/docs/auth/android), [Web](/docs/auth/web), [React Native](/docs/auth/react-native)).

More about AI assistants and Abrova: [AI assistants](/ai-assistants).

- Anonymous: https://abrova.ir/en/docs/auth/anonymous

<Callout kind="note" title="Anonymous sign-in">
One call creates a user with a random id and signs the device in. There is no screen and nothing to type. Only this device holds the session, so treat the user as a guest until they [link a sign-in method](/docs/auth/upgrading).
</Callout>

<H2 id="turn-it-on" step={1}>Turn it on</H2>

In Abrova Console, open **Abrova Auth › Sign-in methods** and turn on **Anonymous**. Optionally set a lower daily limit for new anonymous users under **Abrova Auth › Settings › Anonymous users**.

<H2 id="sign-in" step={2}>Sign in</H2>

Sign in only when nobody is signed in yet. The SDK restores the saved session at start, so the same guest comes back on the next launch.

```dart
// Flutter
final auth = AbrovaAuth.instance;
if (auth.currentUser == null) {
  await auth.signInAnonymously();
}
```

```swift
// iOS
if AbrovaAuth.shared.currentUserId == nil {
    try await AbrovaAuth.shared.signInAnonymously()
}
```

```kotlin
// Android
if (AbrovaAuth.shared.currentUserId == null) {
    AbrovaAuth.shared.signInAnonymously()
}
```

```typescript
// Web and React Native
await auth.ready(); // the saved session is loaded
if (!auth.isSignedIn) {
  await auth.signInAnonymously();
}
```

On Flutter, `signInAnonymously()` returns the current user when an anonymous user is already signed in on the device.

<H2 id="upgrade-later" step={3}>Upgrade later</H2>

Link Apple, Google or an e-mail and password to the anonymous user when they want to keep their account. The id stays the same:

```dart
await AbrovaAuth.instance.linkPassword(email: email, password: password);
```

See [Anonymous users & upgrading](/docs/auth/upgrading) for what happens when the account already exists.

### Limits

<ConfigTable headers={['Limit', 'Value']} rows={[
  ['New anonymous users per day', '200 per project, or your own lower limit'],
  ['From one address', 'A burst of new users from one address is slowed down'],
  ['Removed when unused', 'After 90 days without a sign-in or renewal (7 to 3,650, in Settings)'],
]} />

Over a limit, the call fails with `RATE_LIMITED`. Each new anonymous user who uses the app counts as a monthly active user, like any other user.

### Errors

<ConfigTable headers={['Code', 'Meaning']} rows={[
  ['METHOD_DISABLED', 'Anonymous sign-in is off for the project.'],
  ['RATE_LIMITED', 'Too many new anonymous users: per address, or the daily limit. Try again after retryAfterSec.'],
  ['MAU_LIMIT', 'This month’s free 1,000 monthly active users are used up and the wallet has no balance to pay for more.'],
]} />

- Apple: https://abrova.ir/en/docs/auth/apple

<Callout kind="note" title="Sign in with Apple">
Your app runs Apple's own sign-in and receives an **ID token** from Apple. The SDK sends that token to Abrova Auth, which checks that Apple signed it for one of **your** app identifiers and signs the user in. On iOS the SDK can run the whole Apple sheet for you.
</Callout>

<Callout kind="warn" title="App Store rule">
An iOS app that offers Sign in with Google (or another third-party login) must also offer Sign in with Apple, and an app that lets users create an account must let them delete it in the app. Abrova Auth supports both.
</Callout>

<Callout kind="note" title="Users in Iran">
Sign in with Apple needs a connection to Apple, which can be unreliable from Iran. Offer anonymous, e-mail and password, magic link or Telegram code as well: they do not depend on Apple or Google.
</Callout>

<H2 id="set-it-up-in-the-console" step={1}>Set it up in the Console</H2>

Open **Abrova Auth › Sign-in methods**, turn on **Apple**, and enter your identifiers:

<ConfigTable headers={['Field', 'What to enter']} rows={[
  ['Bundle IDs (iOS apps)', 'The bundle id of each iOS or macOS app that uses the native Apple sheet, for example com.example.app.'],
  ['Services IDs (web and Android)', 'The Services ID you created in the Apple Developer portal for Sign in with Apple on the web or on Android.'],
]} />

Abrova Auth accepts an Apple ID token only when it was issued to one of these identifiers. A token Apple issued for any other app is refused.

#### Account deletion key (recommended)

Apple asks apps to revoke a user's Sign in with Apple when the user deletes their account. To let Abrova Auth do that, create a **Sign in with Apple key** in the Apple Developer portal (Certificates, Identifiers & Profiles › Keys) and enter, in the same Apple section:

<ConfigTable headers={['Field', 'Where to find it']} rows={[
  ['Team ID', '10 characters, Apple Developer › Membership.'],
  ['Key ID', '10 characters, shown with the key.'],
  ['Private key (.p8)', 'The whole file. It is stored encrypted and never shown again.'],
]} />

Then pass Apple's `authorizationCode` when the user signs in (the SDKs show where). Abrova Auth redeems the code when the user first signs up with Apple (or links Apple), so add the key **before** you launch: users who signed up before the key was saved cannot have their Apple sign-in revoked. Without the key or the code, account deletion still deletes the user; only the Apple-side revocation is skipped.

<H2 id="the-nonce" step={2}>The nonce</H2>

A nonce ties Apple's ID token to this one sign-in, so a captured token cannot be used again:

1. Create a random **raw nonce** with the SDK's helper (16 to 256 characters).
2. Give **Apple** the lowercase hex SHA-256 of it.
3. Give **Abrova Auth** the raw value.

Abrova Auth checks that they match and accepts each nonce once. Apple's ID token must also be less than 10 minutes old.

<ConfigTable headers={['SDK', 'Raw nonce', 'Value for Apple']} rows={[
  ['Flutter', 'AbrovaAuthNonce.generate()', 'AbrovaAuthNonce.sha256Hex(raw)'],
  ['iOS', 'AbrovaNonce.generate()', 'AbrovaNonce.sha256(raw)'],
  ['Android', 'AbrovaNonce.generate()', 'AbrovaNonce.sha256(raw)'],
  ['Web, React Native', '(await auth.createNonce()).rawNonce', '(await auth.createNonce()).hashedNonce'],
]} />

<H2 id="sign-in" step={3}>Sign in</H2>

#### iOS: the SDK runs Apple's sheet

Add the **Sign in with Apple** capability to your app target, then:

```swift
try await AbrovaAuth.shared.signInWithAppleNative()
```

The SDK creates the nonce, shows Apple's sheet, and passes the ID token, the authorization code and the name Apple shares on the first sign-in. It throws `.canceled` when the user closes the sheet.

#### Flutter

With the `sign_in_with_apple` package:

```dart
final raw = AbrovaAuthNonce.generate();

final apple = await SignInWithApple.getAppleIDCredential(
  scopes: [AppleIDAuthorizationScopes.email, AppleIDAuthorizationScopes.fullName],
  nonce: AbrovaAuthNonce.sha256Hex(raw),
);

await AbrovaAuth.instance.signInWithApple(
  idToken: apple.identityToken!,
  rawNonce: raw,
  authorizationCode: apple.authorizationCode, // lets account deletion revoke Apple
  name: [apple.givenName, apple.familyName].whereType<String>().join(' '),
);
```

#### Android

Run Apple's web sign-in with your **Services ID** and `AbrovaNonce.sha256(rawNonce)` as the nonce, then pass the `id_token` and `code` Apple returns:

```kotlin
AbrovaAuth.shared.signInWithApple(idToken, rawNonce, authorizationCode = code)
```

#### Web and React Native

Use Sign in with Apple JS (web) or your React Native Apple sign-in library with `hashedNonce` as the nonce:

```typescript
const { rawNonce, hashedNonce } = await auth.createNonce();
// ... run Apple's sign-in with nonce: hashedNonce, then:
await auth.signInWithApple({ idToken, rawNonce, authorizationCode, name });
```

### Name and e-mail

Apple shares the user's name only on the **first** sign-in, and the e-mail may be a private relay address. Abrova Auth stores them (encrypted) only when **Store profile data** is on under **Abrova Auth › Settings**. If your app needs the name, save it in your own data on the first sign-in.

### Link Apple to a signed-in user

To upgrade an anonymous user, use the link call with the same arguments: `linkApple(...)`, or on iOS `signInWithAppleNative(link: true)`. The user keeps their id. If this Apple ID already belongs to another user, the call fails with `PROVIDER_ALREADY_LINKED`.

### Errors

<ConfigTable headers={['Code', 'Meaning']} rows={[
  ['NOT_CONFIGURED', 'Apple is on, but no bundle ID or Services ID is entered.'],
  ['INVALID_ID_TOKEN', 'Apple did not sign it, it was issued to another app id, it is older than 10 minutes, or its nonce is not the SHA-256 of the raw nonce you sent.'],
  ['INVALID_INPUT', 'The raw nonce is missing or not 16 to 256 characters.'],
  ['NONCE_REUSED', 'This nonce was already used. Create a new one for every sign-in.'],
  ['PROVIDER_ALREADY_LINKED', 'Linking only: the Apple ID belongs to another user.'],
  ['METHOD_DISABLED', 'Apple sign-in is off for the project.'],
]} />

- Google: https://abrova.ir/en/docs/auth/google

<Callout kind="note" title="Sign in with Google">
Your app runs Google's own sign-in (Credential Manager on Android, Google Sign-In on iOS and Flutter, Google Identity Services on the web) and receives an **ID token**. The SDK sends that token to Abrova Auth, which checks that Google issued it to one of **your** OAuth client IDs and signs the user in.
</Callout>

<Callout kind="warn" title="Users in Iran">
Google sign-in needs a connection to Google, and on Android also Google Play services. Some users in Iran have neither: phones sold without Google Play services, or Google services that cannot be reached. For them the Google button fails before Abrova Auth is asked. Anonymous, e-mail and password, magic link and Telegram code work without Google, so offer at least one of them next to the Google button.
</Callout>

<H2 id="set-it-up-in-the-console" step={1}>Set it up in the Console</H2>

1. In Google Cloud Console › **APIs & Services › Credentials**, find (or create) the OAuth client IDs your apps sign in with. Android, iOS and web each have their own.
2. In Abrova Console, open **Abrova Auth › Sign-in methods**, turn on **Google**, and add **every** client ID your apps use.

Abrova Auth accepts a Google ID token only when its audience is one of these client IDs.

<Callout kind="note" title="Which client ID ends up in the token">
On Android with Credential Manager, and with `google_sign_in` when you pass a `serverClientId`, the ID token is issued to your **web** client ID. Add the web client ID to the list even if you have no web app.
</Callout>

<H2 id="the-nonce" step={2}>The nonce</H2>

Create a random **raw nonce** with the SDK's helper, give **Google** its lowercase hex SHA-256, and give **Abrova Auth** the raw value. Abrova checks that they match and accepts each nonce once. The ID token must be less than 10 minutes old.

<ConfigTable headers={['SDK', 'Raw nonce', 'Value for Google']} rows={[
  ['Flutter', 'AbrovaAuthNonce.generate()', 'AbrovaAuthNonce.sha256Hex(raw)'],
  ['iOS', 'AbrovaNonce.generate()', 'AbrovaNonce.sha256(raw)'],
  ['Android', 'AbrovaNonce.generate()', 'AbrovaNonce.sha256(raw)'],
  ['Web, React Native', '(await auth.createNonce()).rawNonce', '(await auth.createNonce()).hashedNonce'],
]} />

<Callout kind="warn" title="The nonce is required">
Abrova Auth refuses a Google sign-in without a raw nonce (`INVALID_INPUT`), so every SDK requires it.
</Callout>

<H2 id="sign-in" step={3}>Sign in</H2>

#### Android (Credential Manager)

Add `androidx.credentials:credentials`, `androidx.credentials:credentials-play-services-auth` and `com.google.android.libraries.identity.googleid:googleid` to your app:

```kotlin
val rawNonce = AbrovaNonce.generate()
val option = GetGoogleIdOption.Builder()
    .setServerClientId(WEB_CLIENT_ID)
    .setFilterByAuthorizedAccounts(false)
    .setNonce(AbrovaNonce.sha256(rawNonce))
    .build()
val response = CredentialManager.create(context)
    .getCredential(context, GetCredentialRequest.Builder().addCredentialOption(option).build())
val idToken = GoogleIdTokenCredential.createFrom(response.credential.data).idToken

AbrovaAuth.shared.signInWithGoogle(idToken, rawNonce)
```

#### Flutter

With `google_sign_in` 7:

```dart
final raw = AbrovaAuthNonce.generate();
await GoogleSignIn.instance.initialize(
  serverClientId: 'xxx.apps.googleusercontent.com',
  nonce: AbrovaAuthNonce.sha256Hex(raw),
);
final account = await GoogleSignIn.instance.authenticate();

await AbrovaAuth.instance.signInWithGoogle(
  idToken: account.authentication.idToken!,
  rawNonce: raw,
);
```

#### iOS

Request the Google ID token with `AbrovaNonce.sha256(rawNonce)` as its nonce, then:

```swift
try await AbrovaAuth.shared.signInWithGoogle(idToken: idToken, rawNonce: rawNonce)
```

#### Web and React Native

Give `hashedNonce` to Google Identity Services (web) or your React Native Google sign-in library as the `nonce`:

```typescript
const { rawNonce, hashedNonce } = await auth.createNonce();
// ... run Google's sign-in with nonce: hashedNonce, then:
await auth.signInWithGoogle({ idToken, rawNonce });
```

### E-mail

Abrova Auth uses the Google e-mail only when Google says it is verified, and stores it (encrypted) only when **Store profile data** is on under **Abrova Auth › Settings**. A Google account and an Apple or password account with the same e-mail stay separate users unless the user links them.

### Link Google to a signed-in user

To upgrade an anonymous user, call `linkGoogle(...)` with the same arguments. The user keeps their id. If this Google account already belongs to another user, the call fails with `PROVIDER_ALREADY_LINKED`.

### Errors

<ConfigTable headers={['Code', 'Meaning']} rows={[
  ['NOT_CONFIGURED', 'Google is on, but no client ID is entered.'],
  ['INVALID_ID_TOKEN', 'Google did not sign it, it was issued to a client ID that is not in your list, it is older than 10 minutes, or its nonce is not the SHA-256 of the raw nonce you sent.'],
  ['INVALID_INPUT', 'The raw nonce is missing or not 16 to 256 characters.'],
  ['NONCE_REUSED', 'This nonce was already used. Create a new one for every sign-in.'],
  ['PROVIDER_ALREADY_LINKED', 'Linking only: the Google account belongs to another user.'],
  ['METHOD_DISABLED', 'Google sign-in is off for the project.'],
]} />

- E-mail & password: https://abrova.ir/en/docs/auth/email-password

<Callout kind="note" title="E-mail and password">
Users create an account with an e-mail address and a password, then sign in with them. Abrova Auth sends the verification and password-reset e-mails; the links open your app (or web page) with a one-time `token` that your app hands back to the SDK.
</Callout>

<H2 id="set-it-up-in-the-console" step={1}>Set it up in the Console</H2>

1. **Abrova Auth › Sign-in methods:** turn on **E-mail and password**. Set the **shortest password** (8 to 128 characters, default 8) and whether users need a **verified e-mail** before they can sign in.
2. **Abrova Auth › Settings › Link addresses:** add the addresses your e-mail links may open, for example `https://example.com/auth` or `myapp://auth`. Each must be an `https://` address or your app's own URL scheme.

<H2 id="sign-up" step={2}>Sign up</H2>

```dart
// Flutter
final result = await AbrovaAuth.instance.signUpWithEmail(
  email: email,
  password: password,
  redirectUrl: 'https://example.com/auth/verify', // optional: sends a verification e-mail
);
if (!result.signedIn) {
  // The project requires a verified e-mail: ask the user to open the link first.
}
```

```swift
// iOS
let result = try await AbrovaAuth.shared.signUp(email: email, password: password,
                                                redirectURL: "https://example.com/auth/verify")
```

```kotlin
// Android
val result = AbrovaAuth.shared.signUp(email, password, redirectUrl = "https://example.com/auth/verify")
```

```typescript
// Web and React Native
const result = await auth.signUpWithEmail({ email, password, redirectUrl: 'https://example.com/auth/verify' });
```

The result tells you `verificationSent` (a verification e-mail went out) and `signedIn`. When **Require a verified e-mail** is on, the user is not signed in until they open the link and then sign in.

A password must be at least the project's shortest length, at most 128 characters, and not a very common password. Otherwise the call fails with `WEAK_PASSWORD`. An address that already has an account fails with `EMAIL_TAKEN`.

<H2 id="sign-in" step={3}>Sign in</H2>

<ConfigTable headers={['SDK', 'Call']} rows={[
  ['Flutter', 'signInWithEmail(email: email, password: password)'],
  ['iOS', 'signIn(email: email, password: password)'],
  ['Android', 'signIn(email, password)'],
  ['Web, React Native', 'signInWithEmail({ email, password })'],
]} />

A wrong password and an unknown e-mail both fail with `INVALID_CREDENTIALS`, so the answer never reveals who has an account. Repeated failures for one address or from one place are slowed down (`RATE_LIMITED`).

<H2 id="verify-the-e-mail" step={4}>Verify the e-mail</H2>

The verification link opens `<your link address>?token=...` and is valid for **24 hours**. Read the `token` and pass it to the SDK:

<ConfigTable headers={['SDK', 'Call']} rows={[
  ['Flutter', 'verifyEmail(token)'],
  ['iOS', 'verifyEmail(token: token)'],
  ['Android', 'verifyEmail(token)'],
  ['Web, React Native', 'verifyEmail({ token })'],
]} />

Verifying only marks the e-mail as verified; it does not sign the user in. To send the e-mail again for the signed-in user, call `sendEmailVerification` with a `redirectUrl`.

<H2 id="reset-a-forgotten-password" step={5}>Reset a forgotten password</H2>

1. Call `sendPasswordReset` with the e-mail and a `redirectUrl`. The answer is the same whether or not the address has an account.
2. The e-mail links to `<redirectUrl>?token=...`, valid for **30 minutes** and usable once.
3. Show a "new password" screen and call `resetPassword` with the token and the new password.

```dart
// Flutter
await AbrovaAuth.instance.sendPasswordReset(email, redirectUrl: 'https://example.com/auth/reset');
// ... in the screen the link opens:
await AbrovaAuth.instance.resetPassword(tokenFromLink, newPassword);
```

A reset ends **every** session of the user and marks the e-mail as verified. It does not sign the user in: they sign in with the new password.

### Give an anonymous user a password

`linkPassword` adds an e-mail and password to the signed-in (usually anonymous) user. The id stays the same. It fails with `EMAIL_TAKEN` when another user has that address.

### The e-mails

Abrova Auth sends three e-mails: **verify your e-mail**, **reset your password** and the **magic link**. They name your project, and are sent from Abrova's address. Sending is limited per address (a few per hour) and per project.

<Callout kind="warn" title="Link addresses are enforced">
A `redirectUrl` that does not start with one of your link addresses is refused with `INVALID_INPUT`, before any e-mail is sent. This stops anyone from using your project to send links that point somewhere else.
</Callout>

### Errors

<ConfigTable headers={['Code', 'Meaning']} rows={[
  ['INVALID_CREDENTIALS', 'Wrong e-mail or password.'],
  ['EMAIL_TAKEN', 'An account with this e-mail already exists.'],
  ['WEAK_PASSWORD', 'Too short, too long, or a common password.'],
  ['EMAIL_NOT_VERIFIED', 'The project requires a verified e-mail and this one is not verified yet.'],
  ['TOKEN_INVALID', 'The verification or reset link is invalid, already used, or expired.'],
  ['INVALID_INPUT', 'Not a valid e-mail, or the redirectUrl is not one of your link addresses.'],
  ['NOT_CONFIGURED', 'E-mail delivery is temporarily unavailable.'],
  ['USER_DISABLED', 'You disabled this user in the Console.'],
]} />

- Magic link: https://abrova.ir/en/docs/auth/magic-link

<Callout kind="note" title="Magic link">
The user types an e-mail address and receives a sign-in link. Opening it brings them back to your app with a one-time `token`, which the SDK trades for a session. No password to remember; the account is created the first time the address signs in.
</Callout>

<H2 id="set-it-up-in-the-console" step={1}>Set it up in the Console</H2>

1. **Abrova Auth › Sign-in methods:** turn on **Magic link**.
2. **Abrova Auth › Settings › Link addresses:** add the address the link opens, for example `https://example.com/auth/magic` or `myapp://auth/magic`.

On mobile, make that address open your app: a custom URL scheme, or an Apple universal link / Android App Link for an `https://` address.

<H2 id="send-the-link" step={2}>Send the link</H2>

```dart
// Flutter
await AbrovaAuth.instance.sendMagicLink(email, redirectUrl: 'myapp://auth/magic');
```

```swift
// iOS
try await AbrovaAuth.shared.sendMagicLink(email: email, redirectURL: "myapp://auth/magic")
```

```kotlin
// Android
AbrovaAuth.shared.sendMagicLink(email, redirectUrl = "myapp://auth/magic")
```

```typescript
// Web and React Native
await auth.sendMagicLink({ email, redirectUrl: 'https://example.com/auth/magic' });
```

The answer is the same whether or not the address has an account. Tell the user to check their inbox.

<H2 id="sign-in-with-the-link" step={3}>Sign in with the link</H2>

The link opens `<redirectUrl>?token=...`. Read the token and sign in:

```dart
// Flutter: token from the incoming link
await AbrovaAuth.instance.signInWithMagicLink(Uri.parse(link).queryParameters['token']!);
```

```swift
// iOS: pass the URL the app was opened with
try await AbrovaAuth.shared.signInWithMagicLink(url: openedURL)
```

```kotlin
// Android: from the intent that opened the activity
AbrovaAuth.tokenFromLink(intent.dataString ?: "")?.let { AbrovaAuth.shared.signInWithMagicLink(it) }
```

```typescript
// Web
const token = new URL(location.href).searchParams.get('token');
if (token) await auth.signInWithMagicLink({ token });
```

The first sign-in with an address creates the user, with the e-mail marked as verified. Later links sign in to the same user.

### Rules

<ConfigTable headers={['Rule', 'Value']} rows={[
  ['Link lifetime', '15 minutes'],
  ['Uses', 'Once. A second open fails with TOKEN_INVALID'],
  ['E-mails per address', 'A few per hour'],
  ['Link addresses', 'Only the ones you allowed; anything else fails with INVALID_INPUT'],
]} />

A magic-link user and an e-mail-and-password user with the same address are the same user: the link proves the address. Users signed in with Apple or Google are separate, even with the same address.

### Errors

<ConfigTable headers={['Code', 'Meaning']} rows={[
  ['TOKEN_INVALID', 'The link is invalid, already used, or older than 15 minutes. Send a new one.'],
  ['INVALID_INPUT', 'Not a valid e-mail, or the redirectUrl is not one of your link addresses.'],
  ['RATE_LIMITED', 'Too many links for this address or from this place. Try again after retryAfterSec.'],
  ['USER_DISABLED', 'You disabled this user in the Console.'],
  ['NOT_CONFIGURED', 'E-mail delivery is temporarily unavailable.'],
  ['METHOD_DISABLED', 'Magic link is off for the project.'],
]} />

- Telegram code: https://abrova.ir/en/docs/auth/telegram

<Callout kind="note" title="Telegram code">
The user enters a phone number and receives a 6-digit sign-in code from **your project's Telegram bot**. Where Telegram is common, it replaces SMS at no cost per message. Telegram confirms the number belongs to the user's Telegram account, so a code only ever goes to the owner of that number.
</Callout>

Telegram is filtered in Iran but widely used, and it does not depend on Google or Apple. Users without Telegram need another method, such as e-mail or magic link.

<H2 id="create-and-connect-a-bot" step={1}>Create and connect a bot</H2>

1. In Telegram, talk to **@BotFather**, send `/newbot`, and pick a name and username for your bot (for example `MyAppLoginBot`). BotFather gives you a **bot token**.
2. In Abrova Console, open **Abrova Auth › Sign-in methods**, turn on **Telegram**, and paste the bot token.

Abrova Auth checks the token with Telegram and connects the bot. The token is stored encrypted and never shown again. Use the bot for Abrova Auth only: Abrova takes over its incoming messages.

<H2 id="how-the-user-signs-in" step={2}>How the user signs in</H2>

<NumberedPipeline steps={[
  { title: 'The user enters a phone number', body: 'In international format, for example +989121234567. Your app calls requestTelegramCode.' },
  { title: 'First time only: the user connects the bot', body: 'If this number has not talked to your bot yet, the answer has sent: false and a botUrl. Open it: the user presses Start and taps "Share my phone number".' },
  { title: 'The code arrives in Telegram', body: 'A 6-digit code, valid for 5 minutes. After the first time, codes arrive right away (sent: true).' },
  { title: 'The user types the code', body: 'Your app calls verifyTelegramCode with the number and the code.' },
]} />

The bot accepts only the user's **own** number, shared with Telegram's button. A forwarded contact of someone else is refused.

<H2 id="code" step={3}>Code</H2>

```dart
// Flutter
final auth = AbrovaAuth.instance;
final r = await auth.requestTelegramCode('+989121234567');
if (!r.sent && r.botUrl != null) {
  await launchUrl(Uri.parse(r.botUrl!)); // url_launcher: the user starts the bot and shares the number
}
// ... the user types the code from Telegram:
await auth.verifyTelegramCode('+989121234567', code);
```

```swift
// iOS
let r = try await AbrovaAuth.shared.requestTelegramCode(phone: "+989121234567")
if !r.sent, let url = r.botURL { await UIApplication.shared.open(url) }
try await AbrovaAuth.shared.verifyTelegramCode(phone: "+989121234567", code: code)
```

```kotlin
// Android
val r = AbrovaAuth.shared.requestTelegramCode("+989121234567")
if (!r.sent) startActivity(Intent(Intent.ACTION_VIEW, Uri.parse(r.botUrl)))
AbrovaAuth.shared.verifyTelegramCode("+989121234567", code)
```

```typescript
// Web and React Native
const { sent, botUrl } = await auth.requestTelegramCode({ phone: '+989121234567' });
if (!sent && botUrl) window.open(botUrl); // React Native: Linking.openURL(botUrl)
await auth.verifyTelegramCode({ phone: '+989121234567', code });
```

The first successful code for a number creates the user. Later codes for that number sign in to the same user.

### Rules

<ConfigTable headers={['Rule', 'Value']} rows={[
  ['Code', '6 digits, valid for 5 minutes'],
  ['Attempts', '5 per code; then request a new one'],
  ['Codes per number', '5 per hour'],
  ['Phone format', 'International, with + and the country code'],
]} />

`getMethods()` returns the bot's username as `telegramBot` when Telegram is on, if you want to show it ("Codes come from @MyAppLoginBot").

### Errors

<ConfigTable headers={['Code', 'Meaning']} rows={[
  ['INVALID_CREDENTIALS', 'The code is wrong, expired, or out of attempts.'],
  ['INVALID_INPUT', 'The phone number is not in international format, or the code is not 6 digits.'],
  ['RATE_LIMITED', 'Too many codes for this number or from this place. Try again after retryAfterSec.'],
  ['NOT_CONFIGURED', 'Telegram is on, but no bot is connected.'],
  ['USER_DISABLED', 'You disabled this user in the Console.'],
  ['METHOD_DISABLED', 'Telegram sign-in is off for the project.'],
]} />

- Users & sessions: https://abrova.ir/en/docs/auth/users-sessions

<Callout kind="note" title="Users & Sessions">
An Abrova Auth **user** belongs to one project and has a random id. A **session** is what keeps that user signed in on one device: a short-lived access token for Abrova products and a long-lived refresh token the SDK trades for new access tokens.
</Callout>

### Users

Each user has an id like `ru_4fK9xQ2mB7nT1pLz8RcV3w`: `ru_` and 22 random letters and digits. The id never contains an e-mail, a phone number or an Apple or Google account id, so it is safe to store in your data and show in logs.

- **One project, one user list.** The same person in two of your projects is two unrelated users. A user of one project can never sign in to another.
- **Several ways in, one user.** A user can have more than one sign-in method linked (for example anonymous, then Apple, then a password). The id stays the same. See [Anonymous users & upgrading](/docs/auth/upgrading).
- **No automatic merge by e-mail.** An Apple account and a Google account with the same e-mail are two users, unless the user links them on purpose. Merging by e-mail is a known way to take over accounts.

The SDKs return the user as:

<ConfigTable headers={['Field', 'Meaning']} rows={[
  ['id', 'The user id (ru_...). Use it as the user id everywhere in your app.'],
  ['anonymous', 'True until the user links Apple, Google or a password.'],
  ['emailVerified', 'True once the user proved the e-mail address (verification link, magic link, password reset, or a verified Google e-mail).'],
  ['createdAt', 'When the user was created.'],
  ['providers', 'Linked sign-in methods, for example apple, google, password.'],
]} />

### Sessions

Every sign-in starts a session on that device. A session has two tokens:

| | Access token | Refresh token |
|---|---|---|
| What it is | The Abrova user token (a signed JWT) | A random value with no meaning of its own |
| Lifetime | **1 hour** | 60 days from its last use, at most 1 year from sign-in |
| Kept on the device | In memory | In secure storage (Keychain, Android Keystore-backed storage, or what you choose on the web) |
| Kept by Abrova | Nothing: it is checked by its signature | Only a hash of it |
| Sent to | Every Abrova product | Abrova Auth only |

A user who opens the app at least once every 60 days stays signed in for up to a year. After a year, or after 60 days without the app, the user signs in again.

#### The access token

The access token is the standard **Abrova user token**. Abrova Sync, Chat, Push, A/B Testing and Storage verify its signature and read the user from it, so you never pass a user id to them yourself. It carries:

<ConfigTable headers={['Claim', 'Value']} rows={[
  ['sub', 'The user id (ru_...). This is auth.uid in Sync security rules.'],
  ['pid', 'Your project. A token of another project is refused everywhere.'],
  ['exp', 'One hour after it was issued.'],
  ['amr', 'How the user signed in: anonymous, apple, google, password, magic_link or telegram.'],
]} />

#### Renewal

You do not renew tokens yourself. The SDK keeps the access token, and when an Abrova SDK (or your code) asks for it, the SDK returns it while it has more than 2 minutes left and renews it otherwise. Several callers asking at the same time share one renewal.

<Callout kind="note" title="Rotation and reuse detection">
Every renewal returns a **new** refresh token and retires the old one. If a retired refresh token is ever used again, someone has copied it: Abrova Auth ends that whole session at once and records it in the activity log. The real user simply signs in again; the copy stops working. Simultaneous renewals from one app are handled safely.
</Callout>

#### Offline and network errors

A network error never signs the user out. The SDK keeps the session and tries again on the next request. The user is signed out only when Abrova Auth says the session is over.

### Ending a session

<ConfigTable headers={['What happens', 'Effect']} rows={[
  ['signOut()', 'Ends the session on this device. Never fails: the device forgets the session even when it is offline.'],
  ['signOutEverywhere()', 'Ends every session of the user, on every device.'],
  ['deleteAccount()', 'Deletes the user and all its sessions. See Security & data.'],
  ['Password reset', 'Ends every session of the user. The user signs in with the new password.'],
  ['User disabled in the Console', 'Ends every session. Sign-in and renewal answer USER_DISABLED until you enable the user again.'],
  ['Copied refresh token used', 'Ends that session (reuse detection).'],
  ['60 days unused, or 1 year old', 'The session expires. The next renewal answers SESSION_EXPIRED.'],
]} />

When a session ends on the server, the SDK on that device notices at its next renewal, clears the session and tells your auth state listener (the user becomes `null`).

<Callout kind="warn" title="Up to one hour">
Access tokens are checked by their signature, not looked up. An access token that was issued before a sign-out everywhere, a disable or a deletion keeps working in other Abrova products until it expires, at most one hour later. Renewal is refused at once, so it cannot be extended.
</Callout>

### In the Console

**Abrova Auth › Users** lists your project's users with their sign-in methods, when they were created and when they were last active. From there you can disable or enable a user, sign them out everywhere, or delete them.

- Anonymous users & upgrading: https://abrova.ir/en/docs/auth/upgrading

<Callout kind="note" title="Anonymous users">
An anonymous user is a real Abrova Auth user with no credentials of its own: only the device that created it holds its session. Your app can use it right away with every Abrova product, then ask the user to sign in properly later without losing anything.
</Callout>

### Why start anonymous

- **No sign-in wall.** The user tries your app first. Sync documents, chat rooms and A/B test assignments already belong to a stable user id.
- **Security rules from the first screen.** `auth.uid` is set for an anonymous user too, so rules such as `data.ownerId === auth.uid` protect their data from other users.
- **Experiments for signed-out visitors.** Abrova A/B Testing needs a user token for each user; an anonymous user has one.

<H2 id="create-the-anonymous-user" step={1}>Create the anonymous user</H2>

Turn on **Anonymous** in **Abrova Auth › Sign-in methods**, then:

```dart
if (AbrovaAuth.instance.currentUser == null) {
  await AbrovaAuth.instance.signInAnonymously();
}
```

Check for a current user first. The SDK restores the saved session at start; calling `signInAnonymously()` on every start creates a new user each time. See [Anonymous sign-in](/docs/auth/anonymous).

<H2 id="upgrade-link-a-sign-in-method" step={2}>Upgrade: link a sign-in method</H2>

When the user is ready to keep their account, **link** a method to the signed-in anonymous user. The user id does not change, so everything stored under it stays theirs.

<ConfigTable headers={['Call', 'Links']} rows={[
  ['linkApple', 'Sign in with Apple'],
  ['linkGoogle', 'Sign in with Google'],
  ['linkPassword', 'An e-mail address and a password'],
]} />

```dart
try {
  await AbrovaAuth.instance.linkGoogle(idToken: idToken, rawNonce: rawNonce);
  // Same user id. currentUser.anonymous is now false.
} on AbrovaProviderAlreadyLinkedException {
  // This Google account already belongs to another user.
}
```

After linking, the user can sign in with that method on any device and reach the same account. Linking also starts a fresh session, which the SDK takes over.

<H2 id="when-the-account-already-exists" step={3}>When the account already exists</H2>

If the Apple or Google account already belongs to another user of your project, linking fails with `PROVIDER_ALREADY_LINKED` (for a password: `EMAIL_TAKEN`). Nothing is merged on its own: two users' data is never combined behind your back.

What most apps do:

1. Tell the user this account already exists.
2. Offer to sign in to it. Call the normal sign-in (`signInWithGoogle`), which replaces the anonymous session.
3. If the anonymous user had data worth keeping, copy it to the signed-in user in your app before you switch, or discard it.

<Callout kind="warn" title="Signing in replaces the anonymous user">
Calling a sign-in method (not a link method) while an anonymous user is signed in switches the device to the other user. The anonymous user is not deleted, but no device holds its session any more, so it can never be reached again. Link when you want to keep the id; sign in when you want the other account.
</Callout>

### Limits against bots

Anonymous sign-in needs no details, so it is the easiest method to abuse. Abrova Auth limits it in three ways:

- **Per device address:** a burst of new anonymous users from one address is slowed down.
- **Per project per day:** up to 200 new anonymous users a day. You can set a lower limit under **Abrova Auth › Settings › Anonymous users**.
- Over a limit, `signInAnonymously()` fails with `RATE_LIMITED`. Existing users are not affected.

### Cleanup of abandoned anonymous users

An anonymous user that never comes back is removed after a number of days without a sign-in or session renewal: **90 days** by default, from 7 to 3,650 under **Abrova Auth › Settings › Anonymous users**. Users who linked a method are never removed this way.

<Callout kind="note" title="Data in other products is yours to clean">
Cleanup removes the user from Abrova Auth only. Documents in Sync, messages in Chat and other data stored under that user id stay where they are. Remove them in your own cleanup if you need to.
</Callout>

- Monthly active users & limits: https://abrova.ir/en/docs/auth/mau

<Callout kind="note" title="Monthly active users">
Abrova Auth is paid by **monthly active users** (MAU): the number of different users who signed in or renewed a session during a calendar month. A user counts **once per month**, however many times they open the app and on however many devices.
</Callout>

### What counts

A user is counted the first time in a month (UTC) that they:

- sign in with any method, including anonymous sign-in and linking a method, or
- renew a session (the SDK does this in the background about once an hour while the app is used).

Everything else is free: reading the current user, calls to other Abrova products with the token, sign-out, account deletion. A user who installs your app and never opens it again in the next month is not counted that month.

### Free every month, then from your wallet

| | Free every month | Above that |
|---|---|---|
| Monthly active users | 1,000 | 10,000 Toman per 1,000 users, from your wallet |
| New anonymous users per day | 200 | Daily cap: no more new anonymous users that day |
| Sign-in methods | All 6 | Included |
| Activity log | Included | Included |

There is no plan or subscription. Abrova bills from a prepaid Toman wallet: you top it up when you like, and usage above the free allowance is taken from it. See the [pricing page](/pricing).

<Callout kind="wallet">1,000 monthly active users are free every month. Each further 1,000 costs 10,000 Toman from your wallet.</Callout>

### At the limit

#### With money in your wallet

Nobody is refused. Users above the free 1,000 are paid from your wallet at 10,000 Toman per 1,000. You see the month's count under **Abrova Auth › Overview**.

#### When the wallet is empty

When 1,000 users have been active this month and the wallet cannot pay for more, a **new** user of the month cannot sign in: the call fails with `MAU_LIMIT`.

- Users already counted this month keep working: they sign in and renew their sessions as usual.
- A user who is refused keeps their saved session. It works again on the 1st of next month, or as soon as you top up the wallet.
- Nothing is deleted: your users and settings stay as they are.

Show a friendly message for `MAU_LIMIT` ("Sign-in is unavailable right now, please try again later"). Your users cannot fix it; you can, by topping up the wallet.

### New anonymous users per day

Separately from MAU, a project can create up to **200 new anonymous users** a day. This stops bots from filling your user list (and your MAU count). You can set a lower limit under **Abrova Auth › Settings › Anonymous users**.

Over the limit, `signInAnonymously()` fails with `RATE_LIMITED` and a retry time. Users who already exist are not affected, and other sign-in methods keep working.

### Keeping the count honest

- **Do not create a new anonymous user on every start.** Check for a signed-in user first; the SDK restores the session at start.
- **Abandoned anonymous users** are removed after 90 days without use (adjustable). They stop being counted the month after they stop using the app anyway.
- **One user per person.** Link a sign-in method to an anonymous user instead of creating a second user. See [Anonymous users & upgrading](/docs/auth/upgrading).

Daily active users, new users and how many come back are in [Usage insights](/docs/auth/usage-insights) (turn it on per project).

- Usage insights: https://abrova.ir/en/docs/auth/usage-insights

<Callout kind="note" title="How many people use your app, and do they come back?">
Abrova Auth already sees each of your users sign in and renew their session. **Usage insights** turns that into daily numbers: active users, new users and returning users. There is nothing to add to your app: no new SDK, no new data from the device, no setup beyond one switch.
</Callout>

### Turn it on

Usage insights are **off** until you turn them on, per project, in **Abrova Auth › Settings › Usage insights** (owners and admins). Counting starts at that moment; nothing from before is filled in.

Pick the **time zone** your days are counted in (default UTC; for users in Iran, `Asia/Tehran`), so "today" matches your market. It is one setting per project, the same for everyone who views it. A change applies from the next day; past days keep their numbers, and on the day of the change some users can be counted twice.

Turning it off stops counting and **deletes** the project's usage numbers.

### What you see

Under **Abrova Auth › Overview › Usage**:

| | What it means |
|---|---|
| **Active today** | Different users active today |
| **Daily active users** | Different users active on each day (30, 90 or 400 days) |
| **Weekly active** | Different users active this week (Monday to Sunday) |
| **Monthly active** | Different users active this calendar month — the same count you are billed on |
| **Stickiness** | Average daily active users over the last 30 days ÷ monthly active ("people use it on X % of days") |
| **New users** | Users created on each day |
| **Returning users** | Of the users who joined on a day, how many were active again exactly 1, 7 and 30 days later, shown per week of sign-up |
| **By platform** | Daily active users per SDK platform: Android, iOS, web, Flutter, React Native |
| **By sign-in method** | Daily active users per method: anonymous, Apple, Google, password, magic link, Telegram |

Numbers update within about a minute. Weekly and monthly active users are for the current week and calendar month, not a rolling 7 or 30 days.

### What "active" means

A user is active on a day when they **sign in** or **renew a session** that day. The SDKs renew the 1-hour access token when it has less than 2 minutes left and your app (or another Abrova SDK) asks for it: in practice when the app starts after more than an hour, and about once an hour while it is used.

- A request that is refused does not count: the monthly user limit with an empty wallet (`MAU_LIMIT`), a disabled user, an expired or ended session.
- Deleting a user, or the removal of idle anonymous users, does not change past days.

**Known gap.** A user who opens the app late in the evening and again shortly after midnight, within the same hour, is not seen on the second day: their token is still valid, so nothing reaches Abrova Auth. Daily numbers can therefore be slightly low, never high.

### What is stored

Counts, not tracking. Abrova Auth stores **how many** of your users were active on each day — for example "312 users on 24 October" — never a list of the days or times a person used your app.

- No new data leaves the device; only requests Abrova Auth already receives are counted.
- No IP address, e-mail, phone, token or user id is part of a count.
- The numbers are only for you: no third parties, no advertising, no profiling.
- Counts are kept 400 days.

You can describe it in your own privacy policy, for example: *"We count how many people use the app each day with an anonymous id; no name, no e-mail, no tracking."*

### Free and with a wallet balance

Usage insights cost nothing extra. How much the Console shows depends on whether your project uses only the free monthly allowance or pays as you go from a wallet balance:

| | Free allowance only | With a wallet balance (pay as you go) |
|---|---|---|
| Active today, daily active users | 30 days | 400 days |
| Weekly / monthly active, stickiness, new users | Yes | Yes |
| Returning users (day 1 / 7 / 30) | Last 4 weeks | 400 days |
| By platform / by sign-in method | — | Yes |
| Insights API | — | Yes |

Counts are always kept 400 days; only what is shown changes, so topping up the wallet shows your full history at once.

### Insights API

For your own dashboards and scripts, when your project pays as you go from a wallet balance. Call it **from your server** with your API key and server secret, never from an app or a browser: the server secret must not ship in client code. An app that only signs users in needs none of this — the Console shows the same numbers.

```bash
curl "https://auth-users.abrova.ir/v1/projects/YOUR_PROJECT_ID/insights?from=2026-10-01&to=2026-10-24" \
  -H "x-api-key: $ABROVA_API_KEY" \
  -H "x-server-secret: $ABROVA_SERVER_SECRET"
```

```json
{
  "enabled": true,
  "timeZone": "Asia/Tehran",
  "today": "2026-10-24",
  "activeToday": 312,
  "weeklyActive": 1104,
  "monthlyActive": 1840,
  "stickiness": 0.17,
  "days": [
    { "day": "2026-10-24", "active": 312, "new": 41,
      "byPlatform": { "android": 201, "ios": 111 },
      "byMethod": { "anonymous": 290, "google": 22 } }
  ],
  "returning": [
    { "cohort": "2026-10-17", "size": 52, "day1": 21, "day7": 12, "day30": null }
  ]
}
```

- `from` and `to` are days in the project's time zone, `YYYY-MM-DD`. Without them you get the whole window you can see; a range outside it is shortened to it.
- `day1`, `day7` and `day30` are `null` until the cohort is old enough.
- Your project's server-secret IP allow-list applies.

| Status | `code` | Meaning |
|---|---|---|
| 401 | `UNAUTHENTICATED` | Missing or wrong API key or server secret, or they belong to another project |
| 403 | `LIMIT_REACHED` | The API needs a wallet balance (pay as you go) |
| 429 | `RATE_LIMITED` | More than 60 calls a minute from one address |

### Not included

Events, funnels, screens and custom properties are not part of Abrova Auth: it counts users, not what they do. Keep "did users finish level 3" in your own data, for example one Abrova Sync document per user.

- Security & data: https://abrova.ir/en/docs/auth/security

<Callout kind="note" title="Security & data">
Abrova Auth keeps as little about your users as it can, encrypts what it must keep, and stores secrets (passwords, tokens, codes) only in a form that cannot be turned back into the secret.
</Callout>

### What is stored

<ConfigTable headers={['Data', 'When', 'How']} rows={[
  ['User id, created, last active', 'Always', 'Plain (the id is random)'],
  ['Linked methods', 'Always', 'Which methods, plus a keyed hash of the Apple or Google account id'],
  ['E-mail address', 'E-mail + password and magic link (it is the login)', 'Encrypted, plus a keyed hash to find the account'],
  ['E-mail and name from Apple or Google', 'Only when Store profile data is on (off by default)', 'Encrypted'],
  ['Phone number', 'Telegram sign-in (it is the login)', 'Encrypted, plus a keyed hash to find the account'],
  ['Password', 'E-mail + password', 'One-way hash only'],
  ['Refresh tokens, e-mail link tokens, codes, nonces', 'While valid', 'Hash only'],
]} />

Turn **Store profile data** on under **Abrova Auth › Settings** only if your app needs the e-mail or name Apple and Google return. With it off, those users are known only by their id and the hash of their provider account id.

### Encryption

- **At rest:** personal data (e-mail addresses, names and phone numbers) is encrypted at rest.
- **In transit:** every request uses HTTPS.
- **Passwords:** stored as one-way hashes, never stored or logged in any readable form. Sign-in takes the same time whether or not the e-mail has an account.
- **Your project's secrets** (the Telegram bot token and the Apple key for account deletion) are stored encrypted and never shown again after you save them.
- **Logs** never contain tokens, passwords, e-mail addresses, phone numbers or IP addresses in clear.

### Isolation between projects

The project of every request comes from its API key, never from what the app sends in the request. Users, sessions and settings of one project cannot be read or used from another. An access token names its project, and every Abrova product refuses a token of another project.

### Protection against attacks

<ConfigTable headers={['Threat', 'Protection']} rows={[
  ['Password guessing', 'Limits per address and per e-mail; the same answer (INVALID_CREDENTIALS) for an unknown e-mail and a wrong password.'],
  ['Finding out who has an account', 'Password reset and magic link always answer the same, whether the address has an account or not.'],
  ['Bots creating users', 'Per-address limits and a daily cap on new anonymous users per project.'],
  ['A stolen refresh token', 'Rotation on every renewal; using an old one again ends the session.'],
  ['A stolen access token', 'Lives one hour. Never logged.'],
  ['A captured Apple or Google ID token', 'Each nonce works once; ID tokens older than 10 minutes are refused.'],
  ['An ID token issued to another app', 'Accepted only for the bundle IDs, Services IDs and client IDs you entered for this project.'],
  ['Guessing a code or link', '6-digit codes allow 5 attempts in 5 minutes; e-mail links are long random values that work once.'],
  ['E-mail links sent elsewhere', 'Links only open the link addresses you allowed.'],
]} />

Over a limit, the call fails with `RATE_LIMITED` and says when to try again (`retryAfterSec`).

### Activity log

Included for every project: **Abrova Auth › Activity** shows your project's security events: users created, sign-ins and failed sign-ins, linked methods, password resets, sign-out everywhere, reused refresh tokens, users disabled, enabled or deleted, and settings changes. Events show a hashed source address, so you can tell that two events came from the same place without seeing the address.

### Account deletion

Apple requires apps that offer account creation to let users delete their account in the app. Call `deleteAccount()`:

- The user, all of their sessions and linked methods, and everything Abrova Auth stores about them are deleted. This cannot be undone.
- If the user signed in with Apple and you set up the **account deletion key** (Team ID, Key ID and the `.p8` private key under **Abrova Auth › Sign-in methods › Apple**), Abrova Auth also revokes the user's Sign in with Apple for your app, as Apple asks. Pass Apple's `authorizationCode` when the user signs in with Apple, or this step has nothing to revoke.
- Data in other Abrova products (Sync documents, Chat messages, files in Storage) is not deleted. Delete it from your app before you call `deleteAccount()`, while the user's token still works.

You can also delete a user from **Abrova Auth › Users** in the Console.

- Use with other Abrova products: https://abrova.ir/en/docs/auth/other-products

<Callout kind="note" title="One user for every Abrova product">
Abrova Sync, Chat, Push, A/B Testing and Storage identify your app's user with a signed **Abrova user token**. Without Abrova Auth, your own server mints that token with the server secret. With Abrova Auth, the Auth SDK has the token already: hand its **token provider** to the other SDKs and they act as the signed-in user.
</Callout>

<Callout kind="soon">Abrova Sync, Chat, Push, Storage and A/B Testing are coming soon. This page shows how they will take the Auth user once they launch; they cannot be used yet. Today the signed-in user works with [Abrova Trace](#abrova-trace-today).</Callout>

### Abrova Trace, today

Abrova Trace is live. Give it the Abrova Auth user id, so errors and crashes show which user they happened to. Set it after sign-in and clear it after sign-out:

```dart
// Flutter
AbrovaTrace.setUserId(AbrovaAuth.instance.currentUser!.id);
```

```swift
// iOS
AbrovaTrace.shared.setUserId(AbrovaAuth.shared.currentUserId)   // nil after sign-out
```

```kotlin
// Android
AbrovaTrace.setUserId(AbrovaAuth.shared.currentUserId)   // null after sign-out
```

Trace takes the user id only; it does not need the token. See the [Trace Flutter SDK](/docs/trace/flutter-sdk), [iOS SDK](/docs/trace/ios-sdk) and [Android SDK](/docs/trace/android-sdk).

### What you get

- **Sync security rules work without a server.** `auth.uid` is the Abrova Auth user id (`ru_...`), so `data.ownerId === auth.uid` protects each user's documents. See [Sync security rules](/docs/sync/rules).
- **Chat knows who is talking.** Messages are sent as the token's user; nobody can write as someone else.
- **Storage access rules see the user.** Rules like `users/{userId}/**` let each user read and write only their own files. See [Storage access rules](/docs/storage/bucket-policies).
- **A/B Testing and Push** attach events, variants and inbox messages to the user, including anonymous users who have not signed in properly yet.
- **Nothing extra to wire.** The other SDKs take a token provider. The token is the same one your own server would mint.

### How the token flows

<NumberedPipeline steps={[
  { title: 'Another Abrova SDK needs a token', body: 'At start, before a request, or when its token is about to expire, it calls the provider you gave it.' },
  { title: 'The Auth SDK answers', body: 'With the current access token, renewed first if it has less than 2 minutes left. Calls at the same moment share one renewal.' },
  { title: 'The product checks it', body: 'It verifies the signature, the project and the expiry, and takes the user id from the token.' },
]} />

When nobody is signed in, the provider returns no token (or, for Chat, throws), and each SDK waits for a user the way its docs describe.

### Pass the token provider

These products are coming soon; the calls below are how they will take the token.

Use the user's id from Abrova Auth wherever an SDK asks for a user id (Chat's `userId`, A/B Testing's `setUserId`), so it matches the token.

#### Flutter

```dart
final auth = AbrovaAuth.instance;

// Abrova Sync
await AbrovaSync.init(AbrovaSyncConfig(
  apiKey: 'ab_live_your_api_key',
  tokenProvider: auth.tokenProvider,
));

// Abrova Push
await AbrovaPush.init(AbrovaPushConfig(
  apiKey: 'ab_live_your_api_key',
  tokenProvider: auth.tokenProvider,
));

// Abrova A/B Testing
await AbrovaAbTesting.init(AbrovaAbTestingConfig(
  apiKey: 'ab_live_your_api_key',
  tokenProvider: auth.tokenProvider,
));

// Abrova Storage
final storage = AbrovaStorage(
  apiKey: 'ab_live_your_api_key',
  tokenProvider: auth.tokenProvider,
);

// Abrova Chat: its provider must return a token, so use chatTokenProvider
final chat = AbrovaChatClient(AbrovaChatConfig(
  apiKey: 'ab_live_your_api_key',
  userId: auth.currentUser!.id,
  tokenProvider: auth.chatTokenProvider,
));
```

`tokenProvider` returns `null` when nobody is signed in. `chatTokenProvider` throws `UNAUTHENTICATED` instead; create the Chat client after sign-in.

#### iOS

```swift
let auth = AbrovaAuth.shared

// Abrova Sync
sync.userTokens.provider = auth.tokenProvider

// Abrova Push
AbrovaPushConfig(apiKey: key, tokenProvider: auth.tokenProvider)

// Abrova Storage
let storage = AbrovaStorage(apiKey: key, userTokenProvider: auth.tokenProvider)

// Abrova Chat: create the client after sign-in
AbrovaChatConfig(apiKey: key, userId: auth.currentUserId!, tokenProvider: auth.strictTokenProvider)

// Abrova A/B Testing takes a completion handler
AbrovaAbTestingConfig(apiKey: key, tokenProvider: { completion in
    Task {
        do { completion(.success(try await auth.strictTokenProvider())) }
        catch { completion(.failure(error)) }
    }
})
```

`tokenProvider` returns `nil` when nobody is signed in; `strictTokenProvider` throws.

#### Android

```kotlin
val auth = AbrovaAuth.shared

// Abrova Sync: its provider is called off the main thread
AbrovaSyncConfig.builder(apiKey).userTokenProvider(auth.blockingTokenProvider).build()

// Abrova Push
AbrovaPushConfig(apiKey = apiKey, tokenProvider = auth.tokenProvider)

// Abrova Storage: also called off the main thread
AbrovaStorage.builder(apiKey).userTokenProvider(auth.blockingTokenProvider).build()

// Abrova A/B Testing: also called off the main thread
AbrovaAbTestingConfig(apiKey = apiKey, tokenProvider = AbrovaTokenProvider { auth.blockingTokenProvider() })

// Abrova Chat: create the client after sign-in
AbrovaChatConfig(apiKey = apiKey, userId = auth.currentUserId!!, tokenProvider = auth.strictTokenProvider)
```

`tokenProvider` is a suspend function that returns `null` when nobody is signed in; `strictTokenProvider` throws instead; `blockingTokenProvider` blocks the calling thread and must never run on the main thread.

#### Web

```typescript
import { createAbrovaAuth } from '@abrova/auth-web';
import { AbrovaSync } from '@abrova/sync-web';
import { AbrovaStorage } from '@abrova/storage-web';

const auth = createAbrovaAuth({ apiKey: 'ab_live_your_api_key' });

// Abrova Sync, Push, A/B Testing and Storage: null while signed out
const sync = new AbrovaSync({ apiKey: 'ab_live_your_api_key', tokenProvider: () => auth.getToken() });
const storage = new AbrovaStorage({ apiKey: 'ab_live_your_api_key', tokenProvider: () => auth.getToken() });

// Abrova Chat: auth.tokenProvider rejects with UNAUTHENTICATED while signed out
const chat = new AbrovaChatClient({
  apiKey: 'ab_live_your_api_key',
  userId: auth.currentUserId!,
  tokenProvider: auth.tokenProvider,
});
```

#### React Native

```typescript
import AbrovaSync from '@abrova/sync-react-native';
import { AbrovaStorage } from '@abrova/storage-react-native';

// Abrova Sync, Push, A/B Testing and Storage: null while signed out
await AbrovaSync.init({ apiKey: 'ab_live_your_api_key', tokenProvider: () => auth.getToken() });
const storage = new AbrovaStorage({ apiKey: 'ab_live_your_api_key', tokenProvider: () => auth.getToken() });

// Abrova Chat: create the client after sign-in
const chat = new AbrovaChatClient({
  apiKey: 'ab_live_your_api_key',
  userId: auth.currentUserId!,
  tokenProvider: auth.tokenProvider,
});
```

### When the user signs in or out

The other SDKs cache the token they have. After a sign-in, a sign-out or a switch to another user, tell them to ask the provider again:

<ConfigTable headers={['Product', 'Call']} rows={[
  ['Abrova Sync', 'AbrovaSync.refreshUserToken() (Flutter, React Native, Web); sync.userTokens.refresh() (Android); sync.refreshUserToken() (iOS)'],
  ['Abrova A/B Testing', 'refreshUserToken() after sign-in; clearUserId() after sign-out'],
  ['Abrova Storage', 'storage.refreshUserToken() (every platform). While nobody is signed in, file calls wait and go on after sign-in.'],
  ['Abrova Chat', 'Create the client for the new user; disconnect the old one'],
]} />

Listen to the Auth SDK's auth state (`authStateChanges`, `onAuthStateChanged`, `addAuthStateListener` or `authState`) and make these calls there, so every product follows the user.

### Write security rules for the user

The user id in the token is `auth.uid` in Abrova Sync rules. Store it in the documents a user owns:

```json
{
  "rules": {
    "notes": {
      ".read": "data.ownerId === auth.uid",
      ".write": "newData.ownerId === auth.uid"
    }
  }
}
```

```dart
await AbrovaSync.database('my-app').collection('notes').add({
  'ownerId': AbrovaAuth.instance.currentUser!.id,
  'text': 'Hello',
});
```

Then turn on **Require signed user tokens** for Sync in the Console, so only a signed token can set `auth.uid`. See [Sync security rules](/docs/sync/rules).

### With your own server too

You can still mint tokens on your own server with the server secret (`POST https://auth.abrova.ir/users/token`) for your own user ids. Both kinds of token work in every product. Keep one source of user ids per app, so the same person is not two users.

- Error codes: https://abrova.ir/en/docs/auth/error-codes

<Callout kind="note" title="Error codes">
Every failed call has a stable `code`. Show your users messages based on the code, in their language. The `message` that comes with it is an English hint for developers: it never contains a secret or an e-mail address, and it may change.
</Callout>

### How errors arrive

<ConfigTable headers={['SDK', 'Error type', 'Code field']} rows={[
  ['Flutter', 'AbrovaAuthException (AbrovaProviderAlreadyLinkedException for linking)', 'code, compare with AbrovaAuthErrorCode'],
  ['iOS', 'AbrovaAuthError', 'code, for example .invalidCredentials'],
  ['Android', 'AbrovaAuthException', 'code, compare with AbrovaAuthErrorCode'],
  ['Web, React Native', 'AbrovaAuthError (check with isAbrovaAuthError)', "code, for example 'INVALID_CREDENTIALS'"],
]} />

Over a rate limit, the error also carries the wait: `retryAfterSec` (iOS, Android, Web, React Native) or `retryAfter` (Flutter).

### Codes from Abrova Auth

<ConfigTable headers={['Code', 'HTTP', 'Meaning', 'What to do']} rows={[
  ['INVALID_INPUT', '400', 'A field is missing or malformed: e-mail, phone format, a nonce shorter than 16 characters, a redirectUrl that is not one of your link addresses.', 'Fix the request. A fields object may name the field.'],
  ['INVALID_API_KEY', '401', 'The API key is unknown.', 'Use the public key from Abrova Auth › Setup.'],
  ['PRODUCT_DISABLED', '403', 'Abrova Auth is not turned on for the project.', 'Turn it on under Settings › Products.'],
  ['METHOD_DISABLED', '403', 'This sign-in method is off for the project.', 'Turn it on, or hide the button (use getMethods).'],
  ['NOT_CONFIGURED', '400 / 503', 'The method is on but not set up (no Apple or Google ids, no Telegram bot), or e-mail delivery is unavailable (503).', 'Finish the setup in the Console. For 503, try again later.'],
  ['INVALID_CREDENTIALS', '401', 'Wrong e-mail or password, or a wrong or expired Telegram code.', 'Ask the user to check and try again.'],
  ['EMAIL_TAKEN', '409', 'Another user has this e-mail.', 'Offer sign-in or password reset.'],
  ['EMAIL_NOT_VERIFIED', '403', 'The project requires a verified e-mail and this one is not verified.', 'Ask the user to open the verification e-mail; offer to send it again.'],
  ['WEAK_PASSWORD', '400', 'The password is too short, longer than 128 characters, or very common.', 'Ask for a longer, less common password.'],
  ['INVALID_ID_TOKEN', '401', 'The Apple or Google ID token is not valid for this project: wrong app id, expired, older than 10 minutes, or the nonce does not match.', 'Check the ids in the Console and the nonce handling.'],
  ['NONCE_REUSED', '401', 'This nonce was already used for a sign-in.', 'Create a new nonce for every sign-in.'],
  ['PROVIDER_ALREADY_LINKED', '409', 'Linking: the Apple or Google account belongs to another user.', 'Offer to sign in to that account instead.'],
  ['TOKEN_INVALID', '400 / 401', 'An e-mail link token is invalid, used or expired (400), or the refresh token is unknown (401).', 'Ask for a new link, or sign in again.'],
  ['SESSION_EXPIRED', '401', 'The session ran out (60 days unused, or 1 year old).', 'The SDK signs out. Ask the user to sign in.'],
  ['SESSION_REVOKED', '401', 'The session was ended: sign-out everywhere, password reset, or a reused refresh token.', 'The SDK signs out. Ask the user to sign in.'],
  ['USER_DISABLED', '403', 'You disabled this user in the Console.', 'The SDK signs out. Tell the user the account is disabled.'],
  ['UNAUTHENTICATED', '401', 'The call needs a signed-in user and there is none (or the access token is not valid).', 'Sign in first.'],
  ['RATE_LIMITED', '429', 'Too many attempts, or the daily limit of new anonymous users.', 'Wait retryAfterSec, then try again.'],
  ['MAU_LIMIT', '403', "This month's free 1,000 monthly active users are used up, the wallet has no balance to pay for more, and this user is new this month.", 'Show a friendly message. Top up the wallet to let new users in.'],
  ['LIMIT_REACHED', '403', 'A feature needs a wallet balance (for example the usage insights API). Not returned by sign-in calls.', 'Top up the wallet.'],
  ['INTERNAL', '500 / 503', 'Something went wrong on the Abrova side.', 'Try again later.'],
]} />

### Codes the SDKs add

These come from the SDK, not from Abrova Auth: there was no answer, or the problem is on the device.

<ConfigTable headers={['Code', 'SDK', 'Meaning']} rows={[
  ['NETWORK_ERROR', 'All', 'No answer (offline, timeout). The session is kept; try again.'],
  ['UNKNOWN', 'Flutter, Web, React Native', 'The answer could not be read.'],
  ['INVALID_RESPONSE', 'iOS, Android', 'The answer could not be read.'],
  ['SDK_NOT_CONFIGURED', 'iOS, Android', 'configure() was not called first.'],
  ['NOT_SIGNED_IN', 'iOS, Android', 'strictTokenProvider or a signed-in call with nobody signed in.'],
  ['CANCELED', 'iOS', 'The user closed the Apple sign-in sheet.'],
]} />

### Errors that end the session

When a renewal fails with `SESSION_EXPIRED`, `SESSION_REVOKED`, `TOKEN_INVALID` or `USER_DISABLED`, the SDK clears the session on the device and your auth state listener receives `null`. Send the user to your sign-in screen there. Every other error, including `NETWORK_ERROR`, keeps the session.


## Abrova Push (coming soon)

- Quick start: https://abrova.ir/en/docs/push/quick-start

Get up and running with Abrova Push in minutes. Pick your platform: every SDK installs from Abrova Center, and every app uses only your public project key (`ab_live_…`).

Abrova Push delivers to Android over its own persistent connection (TLS, port 443), so it reaches phones without Google Play services, including Huawei. An optional [FCM bridge](/docs/push/android-fcm) can add Firebase where it is available. iOS uses APNs, and browsers use Web Push.

10,000 messages a month are free. The price above that is set when Abrova Push launches.

Using an AI assistant? See [AI assistants](/docs/push/ai-assistants) for what works today.

<H2 id="flutter" step={1}>Flutter</H2>

#### 1. Add Dependency

Add the package to `pubspec.yaml` from Abrova Center, then run `flutter pub get`:

```yaml
dependencies:
  abrova_push:
    hosted: https://center.abrova.ir/api/packages/abrova/pub
    version: ^0.1.20
```

The plugin uses the native SDKs. Add the Abrova Center repository to `android/build.gradle`, and the iOS SDK to `ios/Podfile` (see [Flutter SDK](/docs/push/flutter) for details):

```groovy
maven { url "https://center.abrova.ir/api/packages/abrova/maven" }
```

```ruby
pod 'AbrovaPushSDK', :git => 'https://github.com/Abrova-co/abrova-push-ios-sdk.git', :tag => '0.1.16'
```

#### 2. Initialize SDK

```dart
import 'package:abrova_push/abrova_push.dart';

void main() async {
  WidgetsFlutterBinding.ensureInitialized();

  await AbrovaPush.init(AbrovaPushConfig(
    apiKey: 'ab_live_your_api_key',
  ));

  runApp(MyApp());
}
```

#### 3. Register & Listen

```dart
@override
void initState() {
  super.initState();

  // Listen for messages
  AbrovaPush.onMessage((message) {
    print('Title: ${message.title}');
    print('Body: ${message.body}');
    print('Data: ${message.data}');
  });

  // Connection status
  AbrovaPush.onConnectionState((connected) {
    print(connected ? 'Connected' : 'Disconnected');
  });

  // Register device
  AbrovaPush.register(userId: 'user_123');
}
```

#### Android Platform Setup

Add permissions to `AndroidManifest.xml`:

```xml
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
<uses-permission android:name="android.permission.POST_NOTIFICATIONS" />
```

#### iOS Platform Setup

1. Enable Push Notifications capability in Xcode
2. Enable Background Modes → Remote notifications
3. For VoIP Push, enable Voice over IP in Background Modes

<H2 id="android" step={2}>Android</H2>

#### 1. Add Dependency

Add the Abrova Center repository to `settings.gradle.kts`:

```kotlin
dependencyResolutionManagement {
    repositories {
        google()
        mavenCentral()
        maven { url = uri("https://center.abrova.ir/api/packages/abrova/maven") }
    }
}
```

Then add the dependency to `build.gradle.kts` (app level):

```kotlin
dependencies {
    implementation("ir.abrova:abrova-push-android:0.1.15")
}
```

#### 2. Add Permissions

Add to `AndroidManifest.xml`:

```xml
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.WAKE_LOCK" />
<uses-permission android:name="android.permission.RECEIVE_BOOT_COMPLETED" />
<uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
<uses-permission android:name="android.permission.FOREGROUND_SERVICE_SPECIAL_USE" />
<uses-permission android:name="android.permission.POST_NOTIFICATIONS" />
```

#### 3. Initialize SDK

```kotlin
import ir.abrova.push.sdk.AbrovaPush
import ir.abrova.push.sdk.AbrovaPushConfig

// In your Application class or MainActivity
AbrovaPush.init(
    applicationContext,
    AbrovaPushConfig(apiKey = "ab_live_your_api_key"),
)
```

#### 4. Register & Listen

```kotlin
import ir.abrova.push.sdk.AbrovaPushCallbackAdapter
import ir.abrova.push.sdk.AbrovaPushError
import ir.abrova.push.sdk.AbrovaPushMessage

AbrovaPush.setCallback(object : AbrovaPushCallbackAdapter() {
    override fun onMessageReceived(message: AbrovaPushMessage) {
        // message.title, message.body, message.data
    }

    override fun onConnectionStateChanged(connected: Boolean) {
        // true / false
    }

    override fun onRegistered(deviceId: String) {
        // Device registered
    }

    override fun onDetailedError(error: AbrovaPushError) {
        // error.code, error.message
    }
})

// Call on every app launch: keeps the device's token, app version
// and last-seen time current on the server
AbrovaPush.register(userId = "user_123")
```

#### 5. Topic Subscription

```kotlin
AbrovaPush.subscribeTopic("news")
AbrovaPush.subscribeTopic("promotions")

AbrovaPush.unsubscribeTopic("promotions")
```

<Callout kind="note" title="Foreground Service">
The Android SDK uses a foreground service for reliable message delivery. Users will see a persistent notification while the service is running, unless you set `showServiceNotification = false` in `AbrovaPushConfig`.
</Callout>

<H2 id="ios" step={3}>iOS</H2>

#### 1. Add Dependency

In Xcode: **File → Add Packages…** → enter `https://github.com/Abrova-co/abrova-push-ios-sdk.git`

Choose version `0.1.16` or later. Or in `Package.swift`:

```swift
dependencies: [
    .package(url: "https://github.com/Abrova-co/abrova-push-ios-sdk.git", from: "0.1.16")
]
```

#### 2. Configure Capabilities

In Xcode, enable:

- **Push Notifications**
- **Background Modes** → Remote notifications
- **Background Modes** → Voice over IP (optional, for VoIP push)

#### 3. Initialize SDK

```swift
import AbrovaPush

// In AppDelegate didFinishLaunchingWithOptions
AbrovaPush.shared.initialize(
    config: AbrovaPushConfig(apiKey: "ab_live_your_api_key")
)
AbrovaPush.shared.delegate = self

// Forward the APNs token
func application(_ application: UIApplication,
                 didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data) {
    AbrovaPush.shared.setAPNsToken(deviceToken)
}
```

#### 4. Register & Listen

```swift
extension AppDelegate: AbrovaPushDelegate {
    func abrovaPush(_ abrovaPush: AbrovaPush, didReceiveMessage message: AbrovaPushMessage) {
        // message.title, message.body, message.data
    }

    func abrovaPush(_ abrovaPush: AbrovaPush, didChangeConnectionState connected: Bool) {
        // true / false
    }

    func abrovaPush(_ abrovaPush: AbrovaPush, didRegisterWithDeviceId deviceId: String) {
        // Device registered
    }

    func abrovaPush(_ abrovaPush: AbrovaPush, didFailWithError error: Error) {
        // Connection or registration error
    }
}

// Call on every app launch, with an optional user ID
AbrovaPush.shared.register(userId: "user_123")
```

#### 5. Topic Subscription

```swift
AbrovaPush.shared.subscribeTopic("news")
AbrovaPush.shared.subscribeTopic("promotions")

AbrovaPush.shared.unsubscribeTopic("promotions")
```

<Callout kind="note" title="Notification Permission">
iOS requires user permission for notifications. The SDK automatically requests permission during registration.
</Callout>

<H2 id="react-native" step={4}>React Native</H2>

#### 1. Install Package

Install the package from Abrova Center (it has no dependencies of its own):

```bash
npm install abrova-push-react-native --registry=https://center.abrova.ir/api/packages/abrova/npm/
```

The package uses the native SDKs: add the Abrova Center Maven repository and the iOS Podfile line exactly as for Flutter above (see [React Native SDK](/docs/push/react-native)).

#### 2. Initialize SDK

```typescript
import AbrovaPush from 'abrova-push-react-native';

await AbrovaPush.init({ apiKey: 'ab_live_your_api_key' });
```

#### 3. Register & Listen

```typescript
// Listen for messages
const unsubscribe = AbrovaPush.onMessage((message) => {
  console.log('Title:', message.title);
  console.log('Body:', message.body);
  console.log('Data:', message.data);
});

// Register device
await AbrovaPush.register({ userId: 'user_123' });

// Don't forget to unsubscribe when component unmounts
// unsubscribe();
```

#### Android Platform Setup

Add to `android/app/src/main/AndroidManifest.xml`:

```xml
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
<uses-permission android:name="android.permission.POST_NOTIFICATIONS" />
```

#### iOS Platform Setup

1. Enable Push Notifications capability in Xcode
2. Enable Background Modes → Remote notifications
3. For VoIP Push, enable Voice over IP in Background Modes

<H2 id="web" step={5}>Web</H2>

#### 1. Install SDK

Point the `@abrova` scope at Abrova Center in your project's `.npmrc`, then install:

```
# .npmrc
@abrova:registry=https://center.abrova.ir/api/packages/abrova/npm/
```

```bash
npm install @abrova/push-web
```

#### 2. Add Service Worker

Create `public/abrova-push-sw.js` for background push notifications:

```bash
cp node_modules/@abrova/push-web/service-worker.js public/abrova-push-sw.js
```

Copy the service worker again whenever you upgrade the SDK.

#### 3. Initialize SDK

```typescript
import AbrovaPush from '@abrova/push-web';

// Create AbrovaPush instance - only apiKey is required
const abrovaPush = new AbrovaPush({
  apiKey: 'ab_live_your_api_key',
  serviceWorkerPath: '/abrova-push-sw.js',  // optional, default path
});
```

#### 4. Set Up Callbacks

```typescript
// Message received (foreground)
abrovaPush.onMessage((message) => {
  console.log('Title:', message.title);
  console.log('Body:', message.body);
  console.log('Data:', message.data);
});

// Connection state changes
abrovaPush.onConnectionState((state) => {
  console.log('Connection:', state); // 'connecting' | 'connected' | 'disconnected' | 'error'
});

// Registration success
abrovaPush.onRegistered((deviceId) => {
  console.log('Device registered:', deviceId);
});

// Notification clicked (from background)
abrovaPush.onNotificationClick((message, action) => {
  console.log('Notification clicked:', message.title);
  if (message.deepLink) {
    window.location.href = message.deepLink;
  }
});

// Error handling with detailed error codes
abrovaPush.onDetailedError((error) => {
  console.error(`Error [${error.code}]: ${error.message}`, error.details);
});
```

#### 5. Register Device

```typescript
// Register device - requests notification permission automatically
// This also sets up Web Push for background notifications.
// Once permission is granted, call register() on every page load.
try {
  const deviceId = await abrovaPush.register({ userId: 'user_123' });
  console.log('Registered with device ID:', deviceId);
} catch (error) {
  if (error.code === 1600) {
    console.log('User denied notification permission');
  }
}
```

#### 6. Topic Subscription

```typescript
// Subscribe to topics
await abrovaPush.subscribeTopic('news');
await abrovaPush.subscribeTopic('promotions');

// Unsubscribe
await abrovaPush.unsubscribeTopic('promotions');
```

#### Complete HTML Example

```html
<!DOCTYPE html>
<html>
<head>
  <title>AbrovaPush Web Demo</title>
</head>
<body>
  <h1>AbrovaPush Web Push Demo</h1>
  <button id="registerBtn">Enable Notifications</button>
  <div id="status"></div>

  <!-- copied from node_modules/@abrova/push-web/dist/index.umd.js -->
  <script src="/abrova-push.umd.js"></script>
  <script>
    const abrovaPush = new AbrovaPush.default({
      apiKey: 'ab_live_your_api_key'
    });

    // Set up callbacks
    abrovaPush.onMessage((msg) => {
      document.getElementById('status').innerHTML =
        '<strong>' + msg.title + '</strong><br>' + msg.body;
    });

    abrovaPush.onConnectionState((state) => {
      console.log('Connection:', state);
    });

    // Register on button click
    document.getElementById('registerBtn').onclick = async () => {
      try {
        const deviceId = await abrovaPush.register();
        document.getElementById('status').textContent = 'Registered: ' + deviceId;
      } catch (e) {
        document.getElementById('status').textContent = 'Error: ' + e.message;
      }
    };
  </script>
</body>
</html>
```

<Callout kind="tip" title="Web Push (VAPID)">
The SDK automatically sets up Web Push notifications using VAPID keys. This enables background notifications even when the browser is closed.
</Callout>

<Callout kind="warn" title="Web Requirements">
- HTTPS required (localhost works for development)
- Service worker file must be in public root directory
- Safari on iOS does not support Web Push (Safari on macOS does)
</Callout>

<H2 id="send-a-test-notification" step={6}>Send a Test Notification</H2>

Send from Abrova Console (**Push → Send**), or from your server with the server secret (`ab_srv_…`, kept in an environment variable, never in an app):

```bash
curl -X POST "https://push-api.abrova.ir/push/send-to-user" \
  -H "x-api-key: ab_live_your_api_key" \
  -H "x-server-secret: $ABROVA_SERVER_SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "userId": "user_123", "title": "Hello", "body": "Your first Abrova push" }'
```

[Templates](/docs/push/templates) support variables and Farsi / English versions of the same message. See [Send push](/docs/push/send) for every target, and [Node.js SDK](/docs/push/nodejs) for the server SDK.

- Configuration: https://abrova.ir/en/docs/push/configuration

All available configuration options for the AbrovaPush SDK.

### Configuration Options

<ConfigTable
  headers={['Option', 'Type', 'Default', 'Description']}
  rows={[
    ['apiKey', 'string', 'required', 'Your API key from dashboard'],
    ['notificationIcon', 'string', 'null', 'Android: Resource name of the small notification icon'],
    ['usePushKit', 'boolean', 'true (Flutter, React Native), false (native iOS)', 'iOS: Enable PushKit VoIP pushes (calling apps)'],
    ['showServiceNotification', 'boolean', 'true', 'Android: Show foreground service notification'],
    ['showNotificationInForeground', 'boolean', 'true', 'Show notifications while the app is in foreground (native iOS default: false)'],
    ['autoConnect', 'boolean', 'true', 'iOS: Connect when the app enters foreground'],
    ['appGroup', 'string', 'null', 'iOS: App Group shared with a Notification Service Extension, for background delivery confirmation'],
    ['autoRefresh', 'boolean', 'true', 'All SDKs (Android, iOS, Flutter, React Native, Web): silently refresh a registered device on launch, at most once every 24h or sooner when the app version, SDK version, push token or user changed. Never prompts for permission'],
  ]}
/>

Call `register()` on every app launch. It keeps the device's token, app version and last-seen time current on the server. Log verbosity is set at runtime with `setLogLevel()` (see below).

### Full Configuration Example

```dart
await AbrovaPush.init(AbrovaPushConfig(
  // Required - only apiKey needed, server config is auto-fetched
  apiKey: 'ab_live_your_api_key',

  // iOS Options
  usePushKit: false,  // Enable only for apps with calling features
  appGroup: 'group.com.yourcompany.yourapp',

  // Android Options
  notificationIcon: 'ic_notification',
  showServiceNotification: true,

  // Optional
  showNotificationInForeground: true,
  autoConnect: true,
));
```

### Log Levels

<div>
  <table>
    <thead>
      <tr>
        <th>Level</th>
        <th>Description</th>
      </tr>
    </thead>
    <tbody>
      <tr>
        <td>none</td>
        <td>No logging output</td>
      </tr>
      <tr>
        <td>error</td>
        <td>Only error messages</td>
      </tr>
      <tr>
        <td>warning</td>
        <td>Errors and warnings</td>
      </tr>
      <tr>
        <td>info</td>
        <td>Errors, warnings, and info messages</td>
      </tr>
      <tr>
        <td>debug</td>
        <td>All messages (recommended for development)</td>
      </tr>
      <tr>
        <td>verbose</td>
        <td>Everything including stack traces</td>
      </tr>
    </tbody>
  </table>
</div>

```dart
import 'package:flutter/foundation.dart';

// Set log level based on build mode
if (kReleaseMode) {
  await AbrovaPush.setLogLevel(AbrovaPushLogLevel.error);
} else {
  await AbrovaPush.setLogLevel(AbrovaPushLogLevel.debug);
}
```

### Web

The Web SDK requires only `apiKey`. Connection configuration is automatically fetched from the server; the realtime connection runs over TLS on port 443.

<ConfigTable
  headers={['Option', 'Type', 'Default', 'Description']}
  rows={[
    ['apiKey', 'string', 'required', 'Your API key from dashboard'],
    ['serviceWorkerPath', 'string', '/abrova-push-sw.js', 'Path to service worker file'],
    ['autoRegisterServiceWorker', 'boolean', 'true', 'Auto-register service worker on init'],
    ['maxReconnectAttempts', 'number', '0', 'Max reconnection attempts (0 = keep retrying, backing off up to 60 s)'],
    ['logLevel', 'AbrovaPushLogLevel', 'ERROR', 'Logging verbosity (NONE, ERROR, WARNING, INFO, DEBUG, VERBOSE)'],
    ['appVersion', 'string', '-', 'Your web app version, shown per device and usable as a segment filter'],
    ['autoRefresh', 'boolean', 'true', 'Silently re-register a browser that registered before, at most once every 24h or sooner when something changed. Never prompts'],
  ]}
/>

#### Web SDK Full Example

```typescript
import AbrovaPush, { AbrovaPushLogLevel } from '@abrova/push-web';

const abrovaPush = new AbrovaPush({
  // Required
  apiKey: 'ab_live_your_api_key',

  // Optional - defaults shown
  serviceWorkerPath: '/abrova-push-sw.js',
  autoRegisterServiceWorker: true,
  maxReconnectAttempts: 0,
  logLevel: AbrovaPushLogLevel.ERROR,
  appVersion: '2.0.0',
  autoRefresh: true,
});

// Change log level at runtime
abrovaPush.setLogLevel(AbrovaPushLogLevel.ERROR);
```

<Callout kind="note" title="Automatic Configuration">
The Web SDK automatically fetches connection credentials and VAPID keys from the server using your API key. You don't need to configure these manually.
</Callout>

- AI assistants: https://abrova.ir/en/docs/push/ai-assistants

<Callout kind="soon" title="Coming soon">
Abrova does not have a docs server for AI assistants yet. This page describes how it will work and what you can use today.
</Callout>

When it is ready, you connect your AI assistant (any tool that supports MCP, the open standard AI tools use to connect to outside sources) once. Then, when you ask it to add Abrova Push to your project, it looks up the current SDK version, install lines and setup steps from these docs instead of answering from memory.

### What works today

- **Copy page for AI.** Every docs page has a **Copy page for AI** link. Paste the page into your assistant's chat before you ask it to write code.
- **Plain-text docs.** Give your assistant the address `https://abrova.ir/docs/llms.txt`. It lists every docs page as plain text that assistants read well.

Tell your assistant to follow the page you gave it, to install the SDK from Abrova Center as the page shows, and to use the placeholder keys from the docs.

### What it will do

The docs server will have read-only tools. Your assistant chooses them by itself; you do not call them by hand.

<ConfigTable headers={['Tool', 'What it will do']} rows={[
  ['list_products', 'Lists the Abrova products, with the platforms that have an SDK and the docs link.'],
  ['search_docs', 'Searches the docs for a few words or a short question and returns the best pages.'],
  ['read_doc', 'Returns one docs page as text, with its link and last-updated date.'],
  ['get_sdk_info', 'Returns the SDK package for a product and platform: name, current version and install lines.'],
  ['get_setup_guide', 'Returns the ordered setup steps for a product and platform: install, keys, initialization and how to test.'],
]} />

Examples of what you will be able to ask:

- **"Add Abrova Push to my Flutter app and open the order screen when a notification is tapped."** It would answer from the [Flutter SDK](/docs/push/flutter) and [Callbacks](/docs/push/callbacks) pages.
- **"Send an order-shipped notification from my Node.js server to every device of a user."** It would answer from the [Node.js SDK](/docs/push/nodejs) and [Send push](/docs/push/send) pages.
- **"Show a banner in my Android app the first time a user opens it."** It would answer from [In-App Messages](/docs/push/in-app).
- **"Deliver to Android phones without Google services, and also use Firebase where it exists."** It would answer from [Android SDK](/docs/push/android) and [Android FCM bridge](/docs/push/android-fcm).
- **"Which Abrova key goes in the app and which one stays on the server?"** It would answer from the [Node.js guide](/docs/push/nodejs-guide).

### Privacy

- **What it reads:** the public Abrova docs, the current SDK versions, and the words your assistant sends (the search words, the page it wants, the product and platform names).
- **What it never sees:** your code, your files, your Abrova project, your keys or your users. The tools have no input for them, and they cannot change any setting.

<Callout kind="warn" title="Keep your keys out of the chat">
Never paste a key into a chat with an AI assistant. Your assistant writes the placeholder from the docs (`ab_live_your_api_key`); you put the real value in your project's configuration yourself. The server secret (`ab_srv_...`) belongs only on your server, in an environment variable.
</Callout>

More about AI assistants and Abrova: [AI assistants](/ai-assistants). Questions? [Contact us](/contact).

- iOS: https://abrova.ir/en/docs/push/ios

<BestPracticeList columns={2} items={[
  ['PushKit VoIP Delivery', 'Background push wakes the app even when killed or terminated'],
  ['Real-time Connection', 'The Abrova real-time connection delivers instantly in the foreground'],
  ['Automatic Setup', 'Connection settings are fetched automatically'],
  ['Local Notifications', 'Foreground UI driven by the SDK'],
  ['No Google/Firebase', 'Full control over your push infrastructure'],
  ['Topics & User IDs', 'Subscribe users to topics or target by user ID'],
]} />

<H2 id="installation" step={1}>Installation</H2>

AbrovaPush installs with Swift Package Manager:

1. In Xcode: **File → Add Package Dependencies** → enter the repository URL:

```
https://github.com/Abrova-co/abrova-push-ios-sdk.git
```

2. Choose version `0.1.16` or later and add the `AbrovaPush` library to your app target.

Or, in a `Package.swift`:

```swift
dependencies: [
    .package(url: "https://github.com/Abrova-co/abrova-push-ios-sdk.git", from: "0.1.16")
]
```

Import the module as `AbrovaPush`:

```swift
import AbrovaPush
```

#### Required Capabilities

In your Xcode project, enable:

1. **Push Notifications**
2. **Background Modes**:
   - Voice over IP
   - Background fetch
   - Remote notifications

#### APNs Key

Background delivery (APNs, and VoIP if you enable it) uses your project's APNs auth key — the same `.p8` key covers both regular and VoIP pushes:

1. Apple Developer Portal → **Certificates, Identifiers & Profiles → Keys**
2. Create a key with **Apple Push Notifications service (APNs)** enabled and download the `.p8` file
3. In Abrova Console → **Abrova Push → Settings → iOS Push (APNs) Configuration**, enter the Key ID, Team ID and paste the `.p8` key content

<H2 id="quick-start" step={2}>Quick Start</H2>

Initialize AbrovaPush in your `AppDelegate`:

```swift
import UIKit
import AbrovaPush

@main
class AppDelegate: UIResponder, UIApplicationDelegate {
    func application(_ application: UIApplication,
                     didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {

        // Only apiKey is required — connection settings are fetched
        // automatically during registration.
        let config = AbrovaPushConfig(apiKey: "ab_live_your_api_key")

        AbrovaPush.shared.initialize(config: config)
        AbrovaPush.shared.delegate = self

        return true
    }

    func application(_ application: UIApplication,
                     didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data) {
        // Forward the APNs token so the server can reach the device in background.
        AbrovaPush.shared.setAPNsToken(deviceToken)
    }

    func applicationDidBecomeActive(_ application: UIApplication) {
        // Open the Abrova real-time connection while the app is in foreground.
        AbrovaPush.shared.connect()
    }

    func applicationWillResignActive(_ application: UIApplication) {
        // Close the real-time connection when going to background.
        // VoIP pushes will still wake the app.
        AbrovaPush.shared.disconnect()
    }
}
```

<H2 id="register-the-device" step={3}>Register the Device</H2>

```swift
import UIKit
import AbrovaPush

class ViewController: UIViewController {
    override func viewDidLoad() {
        super.viewDidLoad()

        // Register on every launch: it keeps the device's token, app version
        // and last-seen time current on the server.
        AbrovaPush.shared.register(
            userId: "user_123",
            metadata: [
                "tier": "premium"
            ]
        )
    }
}
```

<H2 id="implement-the-delegate" step={4}>Implement the Delegate</H2>

```swift
extension AppDelegate: AbrovaPushDelegate {
    func abrovaPush(_ abrovaPush: AbrovaPush, didReceiveMessage message: AbrovaPushMessage) {
        // New push notification — message.title, message.body, message.data
    }

    func abrovaPush(_ abrovaPush: AbrovaPush, didChangeConnectionState connected: Bool) {
        // Real-time connection state changed
    }

    func abrovaPush(_ abrovaPush: AbrovaPush, didRegisterWithDeviceId deviceId: String) {
        // Device registered with the Abrova backend
    }

    func abrovaPush(_ abrovaPush: AbrovaPush, didReceiveVoIPToken token: String) {
        // VoIP token for backend delivery
    }

    func abrovaPush(_ abrovaPush: AbrovaPush, didFailWithError error: Error) {
        // Connection or registration error
    }
}
```

<H2 id="how-push-delivery-works" step={5}>How Push Delivery Works</H2>

```
┌────────────────────────────────────────────────────────────┐
│                    App State                                │
├─────────────────┬─────────────────┬────────────────────────┤
│   Foreground    │   Background    │   Killed/Terminated    │
├─────────────────┼─────────────────┼────────────────────────┤
│  Abrova         │      APNs       │         APNs           │
│  (real-time)    │ (VoIP optional) │    (VoIP optional)     │
└─────────────────┴─────────────────┴────────────────────────┘
```

1. **Foreground**: the Abrova real-time connection delivers messages instantly with no APNs latency.
2. **Background / Killed**: APNs delivers the notification. With `usePushKit` enabled, messages whose `data.type` is `"voip_call"` go out as VoIP pushes instead (calling apps only, see step 8).

<Callout kind="note" title="Apple VoIP Push Requirement">
  VoIP push is for calling apps. Apple requires every VoIP push to report an incoming call through CallKit, so enable `usePushKit` only if your app makes calls.
</Callout>

<H2 id="topics" step={6}>Topics</H2>

Subscribe users to topics so you can broadcast notifications to interest groups:

```swift
AbrovaPush.shared.subscribeTopic("news")

// Later, when the user opts out
AbrovaPush.shared.unsubscribeTopic("news")
```

<H2 id="user-identification" step={7}>User Identification</H2>

```swift
// Set user ID after login
AbrovaPush.shared.setUserId("user_123")

// Clear user ID after logout — also detaches the user on the server,
// so this device stops receiving the previous user's notifications
AbrovaPush.shared.clearUserId()
```

<H2 id="backend-voip-push-format" step={8}>Backend VoIP Push Format</H2>

Abrova sends a VoIP push (instead of a regular APNs push) only when the message's `data.type` is `"voip_call"` and the device registered a VoIP token (`usePushKit: true`). The VoIP payload Abrova builds has this shape:

```json
{
  "title": "New Message",
  "body": "You have a new message",
  "data": {
    "type": "voip_call",
    "screen": "chat",
    "chatId": "123"
  }
}
```

The `data` dictionary is delivered verbatim to `didReceiveMessage` so you can drive in-app navigation.

<H2 id="configuration-options" step={9}>Configuration Options</H2>

```swift
let config = AbrovaPushConfig(
    apiKey: "ab_live_your_api_key",
    usePushKit: false,
    useAPNs: true,
    showNotificationInForeground: false,
    autoConnect: true,
    appGroup: "group.com.yourcompany.yourapp",
    autoRefresh: true
)
```

<ConfigTable rows={[
  ['apiKey', 'String', 'Yes', 'Your Abrova Push API key'],
  ['usePushKit', 'Bool', 'No', 'Enable VoIP pushes, for calling apps only (default: false)'],
  ['useAPNs', 'Bool', 'No', 'Enable standard APNs (default: true)'],
  ['autoConnect', 'Bool', 'No', 'Auto-connect when app enters foreground (default: true)'],
  ['autoReconnect', 'Bool', 'No', 'Reconnect with exponential backoff (default: true)'],
  ['showNotificationInForeground', 'Bool', 'No', 'Show notification banner when app is in foreground (default: false)'],
  ['appGroup', 'String', 'No', 'App Group shared with a Notification Service Extension, required only for background delivery confirmation (see Delivery Confirmation below)'],
  ['autoRefresh', 'Bool', 'No', 'On initialize, silently refresh a previously registered device at most once every 24h, or sooner when the app version, SDK version, push token or user changed. Never prompts for permission (default: true)'],
]} />

<Callout kind="note" title="Automatic connection setup">
Connection settings are fetched automatically. There is nothing to configure.
</Callout>

You can also build the config fluently with `AbrovaPushConfig.builder(apiKey:)`, for example `.usePushKit(false).autoRefresh(true).appGroup("group.com.yourcompany.yourapp").build()`. The installed SDK version is available as `AbrovaPush.sdkVersion`.

<H2 id="delivery-confirmation-notification-service-extension" step={10}>Delivery Confirmation (Notification Service Extension)</H2>

**Optional.** Set this up only if you want to know that background notifications actually
*arrived*. Everything else in the SDK works without it.

APNs tells the server it *accepted* a notification for delivery — it never
confirms one reached the device. The SDK confirms delivery itself for messages
the app sees:

<ConfigTable
  headers={['How the message arrived', 'Confirmed by']}
  rows={[
    ['Abrova real-time connection (app in foreground)', 'The SDK, no setup'],
    ['APNs, app in foreground', 'The SDK, when it is the `UNUserNotificationCenter` delegate. If you use your own delegate, call `AbrovaPush.shared.handleRemoteNotification(userInfo:)`'],
    ['APNs, user taps the notification', 'The SDK, no setup'],
    ['APNs, app in background or not running', 'Your Notification Service Extension (this step)'],
  ]}
/>

iOS does not run your app when a notification arrives in the background, so
without an extension those deliveries stay `sent`. A Notification Service
Extension is the only way iOS lets an app observe a real arrival: the system
runs the extension before the notification is displayed, even when your app is
not running. Each message is confirmed once — the app and the extension share
the list of confirmed messages through the App Group.

If you handle silent pushes, forward them too:

```swift
func application(_ application: UIApplication,
                 didReceiveRemoteNotification userInfo: [AnyHashable: Any],
                 fetchCompletionHandler completionHandler: @escaping (UIBackgroundFetchResult) -> Void) {
    AbrovaPush.shared.handleRemoteNotification(userInfo: userInfo)
    completionHandler(.noData)
}
```

<Callout kind="warn" title="This is the one step that requires an Xcode change">
An extension is a separate process, so it must be its own target — Apple provides
no alternative. Every push SDK that reports iOS delivery works this way. Skip this
section entirely if you do not need delivery confirmation.
</Callout>

#### 1. Add the extension target

In Xcode: **File → New → Target → Notification Service Extension**.

<ConfigTable
  headers={['Field', 'Value']}
  rows={[
    ['Product Name', 'NotificationService (any name works)'],
    ['Language', 'Swift'],
    ['Project', 'Your app project'],
    ['Embed in Application', 'Your app target — if this is not set the extension never ships, and fails silently'],
  ]}
/>

When Xcode asks **"Activate scheme?"**, choose **Don't Activate** so your app
stays the active scheme.

Then set the extension's **iOS Deployment Target** to match your app. Xcode
defaults new targets to the latest iOS version, which would drop support for
every older device.

#### 2. Enable the same App Group on both targets

Select each target → **Signing & Capabilities → + Capability → App Groups**, and
add the *same* group to **both** your app and the extension, for example
`group.com.yourcompany.yourapp`.

The extension runs in its own process and cannot read your app's storage. The
App Group is the shared container the SDK uses to hand the device identity to
the extension.

#### 3. Add the SDK to the extension

The extension needs the SDK too. In Xcode, select the extension target → **General → Frameworks and Libraries → +** and add the `AbrovaPush` library from the package you already added. The extension only uses `AbrovaPushServiceExtension`, which never touches `UIApplication`.

#### 4. Pass the App Group to the SDK

```swift
AbrovaPush.shared.initialize(
    config: AbrovaPushConfig(
        apiKey: "ab_live_your_api_key",
        appGroup: "group.com.yourcompany.yourapp"
    )
)
```

#### 5. Report delivery from the extension

Replace the generated `NotificationService.swift` with:

```swift
import UserNotifications
import AbrovaPush

class NotificationService: UNNotificationServiceExtension {

    private static let appGroup = "group.com.yourcompany.yourapp"
    private static let apiKey = "ab_live_your_api_key"

    var contentHandler: ((UNNotificationContent) -> Void)?
    var bestAttemptContent: UNMutableNotificationContent?

    override func didReceive(
        _ request: UNNotificationRequest,
        withContentHandler contentHandler: @escaping (UNNotificationContent) -> Void
    ) {
        self.contentHandler = contentHandler
        bestAttemptContent = request.content.mutableCopy() as? UNMutableNotificationContent

        AbrovaPushServiceExtension.didReceive(
            request,
            apiKey: NotificationService.apiKey,
            appGroup: NotificationService.appGroup
        )

        contentHandler(bestAttemptContent ?? request.content)
    }

    override func serviceExtensionTimeWillExpire() {
        if let contentHandler = contentHandler, let bestAttemptContent = bestAttemptContent {
            contentHandler(bestAttemptContent)
        }
    }
}
```

The report is fire-and-forget and never delays `contentHandler`. Extensions get a
short execution budget, so a missed report costs a delivery statistic — never the
notification itself.

<Callout kind="note" title="Delete the template code">
Xcode's generated extension appends `[modified]` to every notification title.
If you leave it in, your users will see it.
</Callout>

#### Verifying it works

Send a notification and check the receipt for that device: it should move from
`sent` to `delivered`. See [Delivery Receipts](/docs/push/receipts).

#### Troubleshooting

<ConfigTable
  headers={['Symptom', 'Cause']}
  rows={[
    ['Receipt stays `sent`', 'App Group string differs between the two targets or the config — it must match exactly in all three places. This fails silently.'],
    ['Receipt stays `sent` on first launch', 'The device must register once after you grant notification permission, so the SDK can write its identity into the shared container.'],
    ['`No such module AbrovaPush` in the extension', 'The extension target has no dependency — add the `AbrovaPush` library to the extension target, not just to the app.'],
    ['`Cycle inside <YourApp>`', 'Build phase ordering. In the app target, move `Embed Foundation Extensions` before any script phase that outputs the `.app`.'],
    ['Extension never runs', '`Embed in Application` was not set when the target was created, so the extension is not inside the build.'],
  ]}
/>

### API Reference

Core methods of `AbrovaPush.shared` and supporting types (the SDK also exposes in-app message, inbox and A/B testing APIs).

#### `AbrovaPush` — Initialization & Lifecycle

<ConfigTable rows={[
  ['initialize(config:)', '-', '-', 'Initialize the SDK with an AbrovaPushConfig'],
  ['connect()', '-', '-', 'Open the Abrova real-time connection (foreground)'],
  ['disconnect()', '-', '-', 'Close the real-time connection (VoIP push still works)'],
  ['register(userId:metadata:)', '-', '-', 'Register the device with the Abrova backend. Call on every launch'],
  ['setAPNsToken(_:)', '-', '-', 'Forward the APNs device token'],
  ['handleRemoteNotification(userInfo:)', '-', '-', 'Hand a received notification to the SDK (own notification delegate or silent pushes)'],
  ['unregister()', '-', '-', 'Disconnect and detach the user on the server'],
  ['sdkVersion', '-', '-', 'Static: the installed SDK version'],
]} />

#### User & Topics

<ConfigTable rows={[
  ['setUserId(_:)', '-', '-', 'Set the current user identifier'],
  ['clearUserId()', '-', '-', 'Clear the user identifier and detach the user on the server (e.g. on logout)'],
  ['subscribeTopic(_:)', '-', '-', 'Subscribe the device to a topic'],
  ['unsubscribeTopic(_:)', '-', '-', 'Unsubscribe from a topic'],
]} />

#### `AbrovaPushDelegate` callbacks

<ConfigTable rows={[
  ['didReceiveMessage', '-', '-', 'A push notification was received'],
  ['didChangeConnectionState', '-', '-', 'Real-time connection opened or closed'],
  ['didRegisterWithDeviceId', '-', '-', 'Registration completed; deviceId returned by the backend'],
  ['didReceiveVoIPToken', '-', '-', 'PushKit issued a new VoIP token'],
  ['didFailWithError', '-', '-', 'Connection or registration failed'],
]} />

### Requirements

- iOS 13.0+
- Xcode 14+
- Swift 5.7+

### Best Practices

<BestPracticeList items={[
  ['Initialize in AppDelegate', 'Call AbrovaPush.shared.initialize() in didFinishLaunchingWithOptions so the SDK is ready before any view controller'],
  ['Connect on Active, Disconnect on Resign', 'Use applicationDidBecomeActive / applicationWillResignActive to manage the real-time connection — VoIP pushes still work in background'],
  ['Set User ID After Login', 'Call setUserId() once authentication completes so notifications target the right account'],
  ['Use Topics for Broadcasts', 'Topics suit large audiences; use them for newsletters and app-wide announcements'],
  ['Handle data Payload in didReceiveMessage', 'The data dictionary is your deep-link contract — keep it small and versioned'],
]} />

- Android: https://abrova.ir/en/docs/push/android

<BestPracticeList columns={2} items={[
  ['Real-time push over Abrova\'s own connection', 'A persistent connection over TLS (port 443), no Firebase dependency (FCM bridge is optional)'],
  ['Survives close and reboot', 'Notifications delivered even when the app is killed or the device restarts'],
  ['Rich Notifications', 'Images, action buttons, deep links, custom sounds'],
  ['In-App Messages', 'Modal, banner, fullscreen, and card layouts'],
  ['Message Inbox', 'Persistent storage with real-time updates and unread counts'],
  ['Topics & Segments', 'Subscribe users to topics or target by segment'],
  ['A/B Testing', 'Variant assignment with delivery analytics'],
  ['No Google/Firebase Required', 'Full control over your push infrastructure; optional FCM bridge'],
]} />

<H2 id="installation" step={1}>Installation</H2>

AbrovaPush installs from Abrova Center in two steps.

1. Add the Abrova Center repository to `settings.gradle.kts`:

```kotlin
dependencyResolutionManagement {
    repositories {
        google()
        mavenCentral()
        maven { url = uri("https://center.abrova.ir/api/packages/abrova/maven") }
    }
}
```

Groovy: `maven { url "https://center.abrova.ir/api/packages/abrova/maven" }`

2. Add the dependency to your app's `build.gradle.kts`, then sync the project with Gradle files:

```kotlin
dependencies {
    implementation("ir.abrova:abrova-push-android:0.1.15")
}
```

#### Required Permissions

The SDK requires these permissions, automatically merged via the library manifest:

```xml
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.WAKE_LOCK" />
<uses-permission android:name="android.permission.RECEIVE_BOOT_COMPLETED" />
<uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
<uses-permission android:name="android.permission.FOREGROUND_SERVICE_SPECIAL_USE" />
<uses-permission android:name="android.permission.POST_NOTIFICATIONS" />
```

<H2 id="quick-start" step={2}>Quick Start</H2>

Initialize AbrovaPush in your `Application` class:

```kotlin
import android.app.Application
import ir.abrova.push.sdk.AbrovaPush
import ir.abrova.push.sdk.AbrovaPushConfig

class MyApplication : Application() {
    override fun onCreate() {
        super.onCreate()

        val config = AbrovaPushConfig(
            apiKey = "ab_live_your_api_key"
        )
        AbrovaPush.init(this, config)
    }
}
```

Don't forget to register the Application class in your `AndroidManifest.xml`:

```xml
<application
    android:name=".MyApplication"
    ...>
```

<H2 id="register-and-receive-messages" step={3}>Register and Receive Messages</H2>

```kotlin
import android.os.Build
import android.os.Bundle
import androidx.appcompat.app.AppCompatActivity
import ir.abrova.push.sdk.AbrovaPush
import ir.abrova.push.sdk.AbrovaPushCallbackAdapter
import ir.abrova.push.sdk.AbrovaPushMessage

class MainActivity : AppCompatActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

        // Request notification permission on Android 13+
        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.TIRAMISU) {
            requestPermissions(arrayOf(android.Manifest.permission.POST_NOTIFICATIONS), 1)
        }

        // Listen for messages and connection events
        AbrovaPush.setCallback(object : AbrovaPushCallbackAdapter() {
            override fun onMessageReceived(message: AbrovaPushMessage) {
                // New push notification arrived
            }

            override fun onConnectionStateChanged(connected: Boolean) {
                // Real-time connection state changed
            }

            override fun onRegistered(deviceId: String) {
                // Device registered with the Abrova backend
            }

            override fun onError(error: String) {
                // Connection or registration error
            }
        })

        // Register on every launch: it keeps the device's token, app version
        // and last-seen time current on the server
        AbrovaPush.register(
            userId = "user_123",
            metadata = mapOf(
                "tier" to "premium",
                "language" to "en"
            )
        )
    }
}
```

<H2 id="handle-notification-taps" step={4}>Handle Notification Taps</H2>

When the user taps a push notification and the app launches from the cold-start, retrieve the initial message:

```kotlin
val initialMessage = AbrovaPush.getInitialMessage()
if (initialMessage != null) {
    // Navigate based on initialMessage.deepLink or message data
    AbrovaPush.clearInitialMessage()
}
```

<H2 id="user-identification" step={5}>User Identification</H2>

```kotlin
// Set user ID after login
AbrovaPush.setUserId("user_123")

// Clear user ID after logout — also detaches the user on the server,
// so this device stops receiving the previous user's notifications
AbrovaPush.clearUserId()
```

<H2 id="topics" step={6}>Topics</H2>

Subscribe users to topics so you can broadcast notifications to interest groups:

```kotlin
AbrovaPush.subscribeTopic("news")
AbrovaPush.subscribeTopic("sports")

// Later, when the user opts out
AbrovaPush.unsubscribeTopic("news")
```

<H2 id="rich-notifications" step={7}>Rich Notifications</H2>

Rich notifications support images, action buttons, deep links, and custom sounds. These fields are populated from the dashboard or API when sending a push.

<ConfigTable rows={[
  ['imageUrl', 'String?', 'No', 'URL of a large image displayed in the expanded notification'],
  ['actions', 'List<Action>', 'No', 'Up to 3 action buttons'],
  ['sound', 'String?', 'No', 'Custom sound file name or "default"'],
  ['deepLink', 'String?', 'No', 'Deep link URI launched when the notification is tapped'],
  ['priority', 'String?', 'No', '"default", "high" or "low"'],
  ['ttl', 'Int?', 'No', 'Time-to-live in seconds before the notification expires'],
]} />

<H2 id="in-app-messages" step={8}>In-App Messages</H2>

In-app messages display modal, banner, fullscreen, or card layouts inside your app — useful for promotions, onboarding, and announcements.

The built-in UI draws on the Activity you pass to `AbrovaPush.setCurrentActivity(this)` (call it in `onResume()`), and runs only while no `InAppMessageCallback` is set. Setting a callback means you render messages yourself: the SDK records the impression, calls `onMessageReady` and shows nothing. `onButtonClicked` / `onMessageDismissed` come only from the built-in UI, so they do not fire while a callback is set.

```kotlin
import ir.abrova.push.sdk.inapp.InAppMessage
import ir.abrova.push.sdk.inapp.InAppButton
import ir.abrova.push.sdk.inapp.InAppMessageCallback

// Built-in UI: in your Activity's onResume()
AbrovaPush.setCurrentActivity(this)

// Optional, only to render messages yourself (disables the built-in UI)
AbrovaPush.setInAppMessageCallback(object : InAppMessageCallback {
    override fun onMessageReady(message: InAppMessage) {
        // Render the message with your own UI
    }

    override fun onButtonClicked(message: InAppMessage, button: InAppButton) {
        // Built-in UI only
    }

    override fun onMessageDismissed(message: InAppMessage) {
        // Built-in UI only
    }

    override fun onError(error: String) {
        // Failed to fetch or display a message
    }
})

// Trigger on app open
AbrovaPush.triggerInAppOnAppOpen()

// Trigger on custom event
AbrovaPush.triggerInAppEvent("viewed_product")
```

<H2 id="message-inbox" step={9}>Message Inbox</H2>

Inbox messages are stored server-side (sent from Abrova Console or the Inbox API, separately from pushes) so users can revisit them, similar to a messaging app inbox.

```kotlin
import ir.abrova.push.sdk.inbox.InboxFilter
import ir.abrova.push.sdk.inbox.InboxCallback
import ir.abrova.push.sdk.inbox.InboxMessage
import ir.abrova.push.sdk.inbox.InboxMessageStatus

// Fetch inbox messages
AbrovaPush.getInboxMessages(
    filter = InboxFilter(limit = 50),
    onSuccess = { response ->
        val messages = response.messages
        val unread = response.unreadCount
    },
    onError = { error -> /* handle */ }
)

// Listen for real-time inbox updates
AbrovaPush.getInboxManager().setCallback(object : InboxCallback {
    override fun onMessageReceived(message: InboxMessage) {
        // New inbox message arrived
    }

    override fun onMessageStatusChanged(messageId: String, status: InboxMessageStatus) {
        // Read / unread / archived state changed
    }
})

// Unread count for badges
val count = AbrovaPush.getInboxManager().getUnreadCount()
```

<H2 id="configuration-options" step={10}>Configuration Options</H2>

```kotlin
val config = AbrovaPushConfig(
    apiKey = "ab_live_your_api_key",
    notificationIcon = "ic_notification",
    showServiceNotification = true,
    showNotificationInForeground = true,
    autoRefresh = true
)
```

<ConfigTable rows={[
  ['apiKey', 'String', 'Yes', 'Your project API Key from the dashboard'],
  ['notificationIcon', 'String?', 'No', 'Resource name of the small notification icon'],
  ['showServiceNotification', 'Boolean', 'No', 'Show the persistent foreground-service notification (default: true)'],
  ['showNotificationInForeground', 'Boolean', 'No', 'Show notifications when the app is in foreground (default: true)'],
  ['autoRefresh', 'Boolean', 'No', 'On init(), silently refresh a previously registered device at most once every 24h, or sooner when the app version, SDK version or user changed (default: true)'],
]} />

The SDK never prompts for notification permission during a refresh. The installed SDK version is available as `AbrovaPush.SDK_VERSION`.

#### Delivery Tracking

Every notification the device receives is confirmed to Abrova Push, so the **Delivery** page in the Abrova Console shows it as *delivered*, not just *sent*. No setup is needed. See [Delivery Receipts](/docs/push/receipts).

<H2 id="voip-calls-optional" step={11}>VoIP Calls (Optional)</H2>

For incoming-call UI on Android, add the companion VoIP SDK. The Push SDK works on its own — VoIP is only needed if your app has real calling features.

```kotlin
dependencies {
    implementation("ir.abrova:abrova-push-android:0.1.15")
    implementation("ir.abrova:abrova-push-voip:0.1.0")  // Optional
}
```

```kotlin
import ir.abrova.push.voip.AbrovaPushVoip
import ir.abrova.push.voip.VoipConfig
import ir.abrova.push.voip.VoipCallback
import ir.abrova.push.voip.CallData

AbrovaPushVoip.initialize(this, VoipConfig(appName = "MyApp"))

AbrovaPushVoip.setCallback(object : VoipCallback {
    override fun onCallAccepted(callData: CallData) {
        // Connect to your calling service (Jitsi, WebRTC, etc.)
    }

    override fun onCallDeclined(callData: CallData) { }
    override fun onCallTimeout(callData: CallData) { }
})
```

Send a push payload with `{"type": "voip_call", "callerName": "John"}` to trigger the incoming call screen automatically.

### API Reference

Full method surface of `AbrovaPush` and supporting classes.

#### `AbrovaPush` — Initialization & Lifecycle

<ConfigTable rows={[
  ['init(context, config)', '-', '-', 'Initialize the SDK with an AbrovaPushConfig'],
  ['register(userId?, metadata?)', '-', '-', 'Register the device with the Abrova backend. Call on every launch'],
  ['setCallback(callback)', '-', '-', 'Set the message and connection callback'],
  ['getInitialMessage()', '-', '-', 'Get the message that launched the app, if any'],
  ['clearInitialMessage()', '-', '-', 'Clear the cached initial message after handling'],
]} />

#### User & Topics

<ConfigTable rows={[
  ['setUserId(id)', '-', '-', 'Set the current user identifier'],
  ['clearUserId()', '-', '-', 'Clear the user identifier and detach the user on the server (e.g. on logout)'],
  ['subscribeTopic(topic)', '-', '-', 'Subscribe the device to a topic'],
  ['unsubscribeTopic(topic)', '-', '-', 'Unsubscribe from a topic'],
]} />

#### In-App Messages

<ConfigTable rows={[
  ['setCurrentActivity(activity)', '-', '-', 'Activity the built-in in-app UI draws on (call in onResume)'],
  ['setInAppMessageCallback(callback)', '-', '-', 'Render in-app messages yourself (turns off the built-in UI)'],
  ['triggerInAppOnAppOpen()', '-', '-', 'Trigger any in-app message registered for app-open'],
  ['triggerInAppEvent(eventName, properties?)', '-', '-', 'Trigger in-app messages registered for a custom event'],
]} />

#### Inbox

<ConfigTable rows={[
  ['getInboxMessages(filter, onSuccess, onError)', '-', '-', 'Fetch a page of inbox messages'],
  ['getInboxManager()', '-', '-', 'Get the InboxManager for real-time updates and unread counts'],
]} />

### Device Compatibility

- **Android 5.0 Lollipop** — API 21 (minimum supported)
- **Android 8.0 Oreo** — API 26 (notification channels)
- **Android 13 Tiramisu** — API 33 (runtime POST_NOTIFICATIONS permission)
- **Android 14** — API 34

### Best Practices

<BestPracticeList items={[
  ['Initialize in Application Class', 'Call AbrovaPush.init() in your Application onCreate() so the SDK is ready before any Activity'],
  ['Request Permission on Android 13+', 'POST_NOTIFICATIONS is a runtime permission — request it the first time the user lands on a screen that benefits from notifications'],
  ['Set User ID After Login', 'Call setUserId() once authentication completes so notifications target the right account across devices'],
  ['Use Topics for Broad Audiences', 'Topics suit large audiences; use them for newsletters, news categories, and broadcast announcements'],
  ['Use Segments for Targeted Sends', 'Segments evaluate user metadata server-side — better for targeted product launches and re-engagement'],
  ['Cache the Initial Message', 'Call getInitialMessage() once on cold start, navigate, then call clearInitialMessage() so it isn\'t replayed on resume'],
]} />

- Android FCM bridge: https://abrova.ir/en/docs/push/android-fcm

Abrova Push delivers to Android over its own persistent connection (TLS, port 443), so the default delivery path needs no Google Play services, no Google account and no Firebase project. Android, though, closes background connections to save battery: Doze, standby buckets and the battery managers on Xiaomi, Huawei, Samsung and others all do it, and a phone on low battery does it sooner.

The FCM bridge adds a **second** delivery path through Firebase, which rides the connection Google Play services already keeps alive. It is optional and off until you upload a Firebase key, and it only works on devices that have Google Play services.

<Callout kind="note" title="Nothing is replaced">
Both paths carry every push and the SDK shows whichever arrives first, so a device never sees two notifications. Where Google services are blocked or missing — Iran, China, many Huawei phones — the Firebase copy simply never arrives and Abrova delivers as before.
</Callout>

<H2 id="upload-your-firebase-key" step={1}>Upload your Firebase key</H2>

1. In the [Firebase console](https://console.firebase.google.com), open (or create) the project your app is built with.
2. **Project settings → Service accounts → Generate new private key**. A JSON file downloads.
3. In [Abrova Console](https://console.abrova.ir): **Push → Settings → Android: Firebase Cloud Messaging**, then upload or paste that file.

Abrova checks the key with Google before saving it and tells you if the Cloud Messaging API is disabled or the account lacks permission. The key is stored encrypted and never shown again. You can turn the bridge off without deleting it.

<Callout kind="warn" title="Use a key that can only send messages">
An Admin SDK key can also read your database and manage users. Create a service account with just the **Firebase Cloud Messaging API Sender** role and upload that one.
</Callout>

<H2 id="add-the-add-on-to-your-app" step={2}>Add the add-on to your app</H2>

The core SDK stays free of Firebase; the bridge ships as a separate package from Abrova Center. Your app needs `google-services.json` and the Google services Gradle plugin, which Firebase's own setup adds.

#### Android

1. Make sure the Abrova Center repository is listed (see [Android SDK](/docs/push/android)):

```kotlin
maven { url = uri("https://center.abrova.ir/api/packages/abrova/maven") }
```

2. Add the add-on next to the Push SDK:

```gradle
dependencies {
    implementation("ir.abrova:abrova-push-fcm:0.1.0")
}
```

#### Flutter

Same line in `android/app/build.gradle`. No Dart changes.

#### React Native

Same line in `android/app/build.gradle`. No JavaScript changes.

No other code is needed: the add-on registers itself, sends the device's Firebase token with the normal device registration, and hands incoming messages to the SDK you already use. Notifications, taps, delivery confirmation and in-app suppression behave exactly as before.

<H2 id="apps-that-already-handle-firebase-messages" step={3}>Apps that already handle Firebase messages</H2>

Android delivers Firebase messages to one service only. If your app has its own `FirebaseMessagingService`, pass Abrova's messages through it:

```kotlin
override fun onMessageReceived(message: RemoteMessage) {
    if (AbrovaPushFcm.handleMessage(message)) return   // an Abrova push
    // your own handling
}

override fun onNewToken(token: String) {
    AbrovaPushFcm.onNewToken(token)
}
```

Then remove the add-on's own service in your manifest:

```xml
<service android:name="ir.abrova.push.fcm.AbrovaFcmMessagingService"
         tools:node="remove" />
```

<H2 id="check-it-is-working" step={4}>Check it is working</H2>

Send a test push from Console, then open **Delivery**. Receipts show which path carried each notification:

<ConfigTable rows={[
  ['Transport', '-', '-', 'Which path accepted the push: `fcm` or `pn` (the Abrova connection)'],
  ['Delivered via', '-', '-', 'Which copy the device actually received first'],
]} />

On a healthy connection the Abrova path usually wins; the Firebase copy matters when Android has closed that connection, which is exactly the case the bridge exists for.

### What to expect

<BestPracticeList items={[
  ['Optional everywhere', 'Apps without the add-on, and projects without a Firebase key, work exactly as before'],
  ['No duplicate notifications', 'Both copies carry the same message id and the SDK shows the first one only'],
  ['Blocked regions keep working', 'No Firebase token is issued, so those devices simply use the Abrova connection'],
  ['Privacy', 'With the bridge on, push content passes through Google servers, as it does for any Firebase app'],
]} />

- Flutter: https://abrova.ir/en/docs/push/flutter

<BestPracticeList columns={2} items={[
  ['Push Notifications', 'Real-time delivery on Android & iOS via persistent connection'],
  ['In-App Messages', 'Modal, banner, fullscreen layouts triggered by events'],
  ['Inbox', 'Persistent message center with read / archive / unread count'],
  ['A/B Testing', 'Experiment variant assignment with delivery tracking'],
  ['Topics & Silent Messages', 'Broadcast to interest groups or deliver data-only payloads'],
  ['Auto-reconnect', 'Exponential backoff handles flaky networks'],
  ['Notification Tap Handling', 'Cold-start initial message + foreground tap callback'],
  ['No Google/Firebase Required', 'Full control over your push infrastructure; optional FCM bridge on Android'],
]} />

<H2 id="installation" step={1}>Installation</H2>

AbrovaPush installs from Abrova Center in two steps.

1. Add the package to `pubspec.yaml`, pointing at Abrova Center:

```yaml
dependencies:
  abrova_push:
    hosted: https://center.abrova.ir/api/packages/abrova/pub
    version: ^0.1.20
```

2. Fetch the package:

```bash
flutter pub get
```

#### Android repository

The plugin uses the native Android SDK. Add the Abrova Center repository in `android/build.gradle` (or `android/settings.gradle`, wherever your project lists repositories):

```groovy
allprojects {
    repositories {
        google()
        mavenCentral()
        maven { url "https://center.abrova.ir/api/packages/abrova/maven" }
    }
}
```

#### iOS native SDK

The plugin uses the native iOS SDK. Add it inside the app target in `ios/Podfile`, then run `pod install` in `ios/`:

```ruby
pod 'AbrovaPushSDK', :git => 'https://github.com/Abrova-co/abrova-push-ios-sdk.git', :tag => '0.1.16'
```

#### Android Manifest

Add to `android/app/src/main/AndroidManifest.xml`:

```xml
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.POST_NOTIFICATIONS" />
```

#### iOS Capabilities

In Xcode → **Signing & Capabilities** enable:

- **Push Notifications**
- **Background Modes** → **Remote notifications**

<H2 id="quick-start" step={2}>Quick Start</H2>

Initialize AbrovaPush before `runApp`:

```dart
import 'package:flutter/material.dart';
import 'package:abrova_push/abrova_push.dart';

void main() async {
  WidgetsFlutterBinding.ensureInitialized();

  await AbrovaPush.init(AbrovaPushConfig(
    apiKey: 'ab_live_your_api_key',
  ));

  runApp(const MyApp());
}
```

<H2 id="register-and-receive-messages" step={3}>Register and Receive Messages</H2>

```dart
@override
void initState() {
  super.initState();

  // Listen for messages
  AbrovaPush.onMessage((message) {
    // message.title, message.body, message.data
  });

  // Connection status
  AbrovaPush.onConnectionState((connected) {
    // true / false
  });

  // Register the device
  AbrovaPush.register(userId: 'user_123');
}
```

<H2 id="notification-tap-handling" step={4}>Notification Tap Handling</H2>

When the app cold-starts from a notification tap, fetch the initial message before showing UI:

```dart
void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await AbrovaPush.init(config);

  final initialMessage = await AbrovaPush.getInitialMessage();
  if (initialMessage != null) {
    runApp(MyApp(initialRoute: routeFor(initialMessage)));
  } else {
    runApp(const MyApp());
  }
}
```

For taps that happen while the app is running, listen via callback:

```dart
AbrovaPush.onNotificationTapped((AbrovaPushMessage message) {
  // Navigate based on message.data
});
```

<H2 id="user-identification" step={5}>User Identification</H2>

```dart
// Set user ID after login
await AbrovaPush.setUserId('user_123');

// Clear user ID after logout
await AbrovaPush.clearUserId();

// Register with user ID + metadata in one call
await AbrovaPush.register(
  userId: 'user_123',
  metadata: {'appVersion': '1.0.0', 'language': 'en'},
);
```

<H2 id="topics" step={6}>Topics</H2>

```dart
await AbrovaPush.subscribeTopic('news');
await AbrovaPush.subscribeTopic('promotions');

await AbrovaPush.unsubscribeTopic('promotions');
```

<H2 id="in-app-messages" step={7}>In-App Messages</H2>

Trigger in-app messages on app open or custom events. To display them, wrap your app in `AbrovaPushInAppOverlay`; the native SDKs do not render in-app UI for Flutter (see [In-App Messages](/docs/push/in-app)):

```dart
// On app open
await AbrovaPush.triggerInAppOnAppOpen();

// On custom event with properties
await AbrovaPush.triggerInAppEvent('purchase_complete', properties: {
  'amount': 29.99,
});

// Button taps on overlay-rendered messages arrive in the overlay's onButtonTap
MaterialApp(
  builder: (context, child) => AbrovaPushInAppOverlay(
    onButtonTap: (context, message, button) {
      // User tapped an action button
    },
    child: child ?? const SizedBox.shrink(),
  ),
);
```

`AbrovaPushInAppOverlay` listens through `AbrovaPush.onInAppMessageReady`, which holds a single callback; setting your own `onInAppMessageReady` replaces the overlay's listener.

<H2 id="inbox" step={8}>Inbox</H2>

Inbox messages are stored server-side (sent from Abrova Console or the Inbox API, separately from pushes) so users can revisit them:

```dart
// Fetch inbox messages
final response = await AbrovaPush.getInboxMessages(
  status: InboxMessageStatus.unread,
  limit: 50,
);

// Mark as read
await AbrovaPush.markInboxMessageAsRead(messageId);

// Archive
await AbrovaPush.archiveInboxMessage(messageId);

// Unread count for badges
final count = await AbrovaPush.getInboxUnreadCount();

// Listen for new inbox messages
AbrovaPush.onInboxMessage((message) {
  // message.content.title, message.content.body
});
```

<H2 id="a-b-testing" step={9}>A/B Testing</H2>

```dart
// Get active tests
final tests = await AbrovaPush.getActiveABTests();

// Get the assigned variant for a test
final variant = await AbrovaPush.getABTestVariant('test_id');
if (variant != null) {
  // variant.variantName, variant.content
}

// Track events
await AbrovaPush.trackABTestImpression('test_id', 'variant_id');
await AbrovaPush.trackABTestClicked('test_id', 'variant_id');

// Listen for new variant assignments
AbrovaPush.onABTestVariantAssigned((variant) {
  // Newly assigned to a variant
});
```

<H2 id="analytics" step={10}>Analytics</H2>

Forward SDK events to your analytics service:

```dart
AbrovaPush.setAnalyticsHandler((event, properties) {
  // Example: forward to Firebase Analytics
  FirebaseAnalytics.instance.logEvent(
    name: 'abrova_push_${event.name}',
    parameters: properties?.map((k, v) => MapEntry(k, v.toString())),
  );
});
```

<H2 id="log-levels" step={11}>Log Levels</H2>

```dart
import 'package:flutter/foundation.dart';

if (kReleaseMode) {
  await AbrovaPush.setLogLevel(AbrovaPushLogLevel.error);
} else {
  await AbrovaPush.setLogLevel(AbrovaPushLogLevel.debug);
}
```

Available levels: `none`, `error`, `warning`, `info`, `debug`, `verbose`.

<H2 id="configuration-options" step={12}>Configuration Options</H2>

```dart
await AbrovaPush.init(AbrovaPushConfig(
  apiKey: 'ab_live_your_api_key',
  notificationIcon: 'ic_notification',
  usePushKit: false,
  showServiceNotification: true,
  showNotificationInForeground: true,
));
```

<ConfigTable rows={[
  ['apiKey', 'String', 'Yes', 'Your project API Key from the dashboard'],
  ['notificationIcon', 'String?', 'No', 'Android notification icon resource name'],
  ['usePushKit', 'bool', 'No', 'Enable iOS PushKit VoIP for calling apps (default: true)'],
  ['showServiceNotification', 'bool', 'No', 'Show Android foreground-service notification (default: true)'],
  ['showNotificationInForeground', 'bool', 'No', 'Show notifications when the app is in foreground (default: true)'],
  ['autoConnect', 'bool', 'No', 'Auto-connect when the app enters the foreground (default: true)'],
  ['autoRefresh', 'bool', 'No', 'Refresh a previously registered device in the background on launch (default: true)'],
  ['appGroup', 'String?', 'No', 'iOS only. App Group shared with a Notification Service Extension, for delivery confirmation (see iOS Delivery Confirmation below)'],
]} />

<Callout kind="note" title="Auto-configured Connection">
Connection configuration is fetched from the server using your API key. No manual setup is needed.
</Callout>

<H2 id="voip-calls-optional" step={13}>VoIP Calls (Optional)</H2>

For apps with calling features, add the companion VoIP plugin for native incoming-call UI:

```yaml
dependencies:
  abrova_push:
    hosted: https://center.abrova.ir/api/packages/abrova/pub
    version: ^0.1.20
  abrova_push_voip:  # Optional - for calling apps
    hosted: https://center.abrova.ir/api/packages/abrova/pub
    version: ^0.1.1
```

```dart
await AbrovaPushVoIP.init(
  config: AbrovaPushVoIPConfig(appName: 'MyApp'),
  onCallAccepted: (callData) => navigateToCallScreen(callData),
  onCallDeclined: (callData) => notifyCallDeclined(callData.callId),
);

// Register VoIP after AbrovaPush has issued a deviceId
final deviceId = await AbrovaPush.getDeviceId();
await AbrovaPushVoIP.setApiKey(apiKey: 'ab_live_your_api_key', deviceId: deviceId); // deviceId is optional
```

Trigger an incoming call from the backend with `type: "voip_call"`:

```json
{
  "title": "Incoming Call",
  "body": "John Doe is calling",
  "data": {
    "type": "voip_call",
    "callerName": "John Doe",
    "callerId": "user_456",
    "callType": "video"
  }
}
```

<H2 id="ios-delivery-confirmation-optional" step={14}>iOS Delivery Confirmation (Optional)</H2>

**Optional, iOS only.** Android confirms delivery on its own — nothing to do
there. On iOS, APNs only reports that Apple *accepted* a notification, so
without this step iOS devices report `sent` and never `delivered`.

Confirming delivery on iOS requires a Notification Service Extension, which is a
native Xcode target. Follow the full walkthrough in the
[iOS SDK guide](/docs/push/ios) — adding the target, enabling an App Group
on both targets, and adding the SDK to the extension target.

From Flutter, the only change is passing the same App Group to the config:

```dart
await AbrovaPush.init(AbrovaPushConfig(
  apiKey: 'ab_live_your_api_key',
  // iOS only. Must match the App Group enabled on BOTH your Runner target and
  // the Notification Service Extension target.
  appGroup: 'group.com.yourcompany.yourapp',
));
```

`appGroup` is ignored on Android, so it is safe to pass unconditionally.

<Callout kind="warn" title="The App Group string must match exactly">
It appears in four places: both targets' capabilities, your extension's Swift
code, and `AbrovaPushConfig`. A mismatch fails silently — the extension runs,
finds no device identity, and reports nothing.
</Callout>

### API Reference

#### `AbrovaPush` — Initialization & Lifecycle

<ConfigTable rows={[
  ['init(config)', '-', '-', 'Initialize the SDK with an AbrovaPushConfig'],
  ['register(userId?, metadata?)', '-', '-', 'Register the device with the Abrova backend'],
  ['unregister()', '-', '-', 'Unregister the device'],
  ['isConnected()', '-', '-', 'Check whether the real-time connection is open'],
  ['getDeviceId()', '-', '-', 'Get the current device identifier'],
]} />

#### Callbacks

<ConfigTable rows={[
  ['onMessage(callback)', '-', '-', 'Called when a push message is received'],
  ['onConnectionState(callback)', '-', '-', 'Connection open / closed state changes'],
  ['onRegistered(callback)', '-', '-', 'Device registration completed'],
  ['onNotificationTapped(callback)', '-', '-', 'User tapped a notification while app is running'],
  ['onError(callback)', '-', '-', 'String error message'],
  ['onDetailedError(callback)', '-', '-', 'Structured AbrovaPushError with code + message'],
  ['onReconnecting(callback)', '-', '-', 'Reconnection attempt state'],
  ['onNetworkState(callback)', '-', '-', 'Network availability change'],
  ['onAppState(callback)', '-', '-', 'App foreground / background change'],
]} />

#### User & Topics

<ConfigTable rows={[
  ['setUserId(id)', '-', '-', 'Set the current user identifier'],
  ['clearUserId()', '-', '-', 'Clear the user identifier'],
  ['subscribeTopic(topic)', '-', '-', 'Subscribe to a topic'],
  ['unsubscribeTopic(topic)', '-', '-', 'Unsubscribe from a topic'],
]} />

#### Inbox

<ConfigTable rows={[
  ['getInboxMessages(status?, limit?)', '-', '-', 'Fetch a page of inbox messages'],
  ['markInboxMessageAsRead(id)', '-', '-', 'Mark an inbox message as read'],
  ['archiveInboxMessage(id)', '-', '-', 'Archive an inbox message'],
  ['getInboxUnreadCount()', '-', '-', 'Get the unread count for badges'],
  ['onInboxMessage(callback)', '-', '-', 'Listen for new inbox messages'],
]} />

#### In-App Messages

<ConfigTable rows={[
  ['triggerInAppOnAppOpen()', '-', '-', 'Trigger any in-app message registered for app-open'],
  ['triggerInAppEvent(event, properties?)', '-', '-', 'Trigger in-app messages registered for a custom event'],
  ['onInAppMessageReady(callback)', '-', '-', 'An in-app message matched a trigger (used by AbrovaPushInAppOverlay)'],
  ['onInAppButtonClick(callback)', '-', '-', 'Button tap on a natively rendered message; overlay taps go to AbrovaPushInAppOverlay.onButtonTap'],
]} />

#### A/B Testing

<ConfigTable rows={[
  ['getActiveABTests()', '-', '-', 'Get active A/B tests'],
  ['getABTestVariant(testId)', '-', '-', 'Get the assigned variant for a test'],
  ['trackABTestImpression(testId, variantId)', '-', '-', 'Track an impression'],
  ['trackABTestClicked(testId, variantId)', '-', '-', 'Track a click conversion'],
  ['onABTestVariantAssigned(callback)', '-', '-', 'Listen for new variant assignments'],
]} />

### Best Practices

<BestPracticeList items={[
  ['Initialize Before runApp', 'Call WidgetsFlutterBinding.ensureInitialized() then await AbrovaPush.init() before runApp so callbacks are ready'],
  ['Check Initial Message on Cold Start', 'Always await getInitialMessage() before showing your first screen so deep-link taps land on the right route'],
  ['Set User ID After Login', 'Call setUserId() once authentication completes so notifications target the right account across devices'],
  ['Use Topics for Broad Audiences', 'Topics suit large audiences; use for newsletters, sports scores, news categories'],
  ['Use Segments for Targeted Sends', 'Segments evaluate user metadata server-side — better for product launches and re-engagement'],
  ['Forward Analytics', 'Wire setAnalyticsHandler to your analytics provider so SDK events (messages, connection, in-app, inbox, A/B tests) show up next to your other product metrics'],
]} />

- React Native: https://abrova.ir/en/docs/push/react-native

<BestPracticeList columns={2} items={[
  ['Push Notifications', 'Real-time delivery on Android & iOS via persistent connection'],
  ['In-App Messages', 'Trigger-matched messages delivered to JS for your own UI'],
  ['Inbox', 'Persistent message center with read / archive / unread count'],
  ['A/B Testing', 'Experiment variant assignment with delivery tracking'],
  ['Topics & Silent Messages', 'Broadcast to interest groups or deliver data-only payloads'],
  ['Auto-reconnect', 'Exponential backoff handles flaky networks'],
  ['TypeScript Support', 'Written in TypeScript (the bundled index.d.ts is out of date, see below)'],
  ['No Google/Firebase', 'Full control over your push infrastructure'],
]} />

<H2 id="installation" step={1}>Installation</H2>

The package installs from Abrova Center in two steps.

1. Abrova Center serves the package at this registry address:

```
https://center.abrova.ir/api/packages/abrova/npm/
```

2. Install the package from it (it has no dependencies of its own, so nothing else is fetched from there):

```bash
npm install abrova-push-react-native --registry=https://center.abrova.ir/api/packages/abrova/npm/
# or
yarn add abrova-push-react-native --registry https://center.abrova.ir/api/packages/abrova/npm/
```

#### Android Setup

The package uses the native Android SDK. Add the Abrova Center repository in `android/build.gradle` (or `android/settings.gradle`, wherever your project lists repositories):

```groovy
allprojects {
    repositories {
        google()
        mavenCentral()
        maven { url "https://center.abrova.ir/api/packages/abrova/maven" }
    }
}
```

No manifest changes are needed: the native Android SDK (`ir.abrova:abrova-push-android`) declares the permissions it needs (`INTERNET`, `ACCESS_NETWORK_STATE`, `WAKE_LOCK`, `RECEIVE_BOOT_COMPLETED`, `FOREGROUND_SERVICE`, `FOREGROUND_SERVICE_SPECIAL_USE`, `POST_NOTIFICATIONS`) and they are merged into your app's manifest automatically.

#### iOS Setup

The package uses the native iOS SDK. Add it inside the app target in `ios/Podfile`:

```ruby
pod 'AbrovaPushSDK', :git => 'https://github.com/Abrova-co/abrova-push-ios-sdk.git', :tag => '0.1.16'
```

Then install the pods:

```bash
cd ios && pod install
```

In Xcode → **Signing & Capabilities** enable:

- **Push Notifications**
- **Background Modes** → **Remote notifications**

<H2 id="quick-start" step={2}>Quick Start</H2>

```typescript
import AbrovaPush from 'abrova-push-react-native';

// Initialize on app start
await AbrovaPush.init({
  apiKey: 'ab_live_your_api_key',
});

// Listen for messages
const unsubscribe = AbrovaPush.onMessage((message) => {
  // message.title, message.body, message.data
});

// Register the device
await AbrovaPush.register({ userId: 'user_123' });

// Later, when the component unmounts
unsubscribe();
```

<H2 id="react-hook" step={3}>React Hook</H2>

Idiomatic React Native pattern — encapsulate registration + listeners in a custom hook:

```typescript
import { useEffect, useState } from 'react';
import AbrovaPush from 'abrova-push-react-native';

export function useAbrovaPush(userId: string) {
  const [connected, setConnected] = useState(false);
  const [deviceId, setDeviceId] = useState<string | null>(null);

  useEffect(() => {
    const unsubMessage = AbrovaPush.onMessage((msg) => {
      // handle msg
    });
    const unsubConnection = AbrovaPush.onConnectionState(setConnected);
    const unsubRegistered = AbrovaPush.onRegistered(setDeviceId);

    AbrovaPush.register({ userId });

    return () => {
      unsubMessage();
      unsubConnection();
      unsubRegistered();
    };
  }, [userId]);

  return { connected, deviceId };
}
```

<H2 id="notification-tap-handling" step={4}>Notification Tap Handling</H2>

```typescript
// Get the message that launched the app (from notification tap)
const message = await AbrovaPush.getInitialMessage();
if (message) {
  // Navigate based on message.data
}

// While the app is running, listen for taps
AbrovaPush.onNotificationTapped((message) => {
  // Navigate based on message.data
});

// Action button taps
AbrovaPush.onNotificationAction((event) => {
  // event.actionId, event.title, event.body, event.data, event.messageId
});
```

<H2 id="user-identification" step={5}>User Identification</H2>

```typescript
// Set user ID after login
await AbrovaPush.setUserId('user_123');

// Clear user ID on logout
await AbrovaPush.clearUserId();

// Register with user ID and metadata
await AbrovaPush.register({
  userId: 'user_123',
  metadata: { appVersion: '1.0.0', language: 'en' },
});
```

<H2 id="topics" step={6}>Topics</H2>

```typescript
await AbrovaPush.subscribeTopic('news');
await AbrovaPush.subscribeTopic('promotions');

await AbrovaPush.unsubscribeTopic('promotions');
```

<H2 id="in-app-messages" step={7}>In-App Messages</H2>

This package has no built-in in-app UI yet. When a trigger matches, the native SDK records the impression and emits `onInAppMessageReady`, and your app renders the message. `onInAppButtonClick` and `onInAppMessageDismissed` come only from the native SDKs' built-in UI, which the wrapper turns off, so they do not fire.

```typescript
// Trigger on app open
await AbrovaPush.triggerInAppOnAppOpen();

// Trigger custom event with properties
await AbrovaPush.triggerInAppEvent('purchase_complete', { amount: 29.99 });

// Render the message yourself when a trigger matches
AbrovaPush.onInAppMessageReady((message) => {
  // message.type, message.content.title, message.content.buttons, ...
});

// Manual fetch / emit / dismiss
const messages = await AbrovaPush.fetchInAppMessages();
await AbrovaPush.showInAppMessage(messageId);
await AbrovaPush.dismissInAppMessage();
```

<H2 id="inbox" step={8}>Inbox</H2>

```typescript
import { InboxMessageStatus } from 'abrova-push-react-native';

// Fetch inbox messages
const response = await AbrovaPush.getInboxMessages({
  status: InboxMessageStatus.UNREAD,
  limit: 50,
});

// Mark as read
await AbrovaPush.markInboxMessageAsRead(messageId);

// Archive
await AbrovaPush.archiveInboxMessage(messageId);

// Unread count for badges
const count = await AbrovaPush.getInboxUnreadCount();

// Mark every message as read at once
await AbrovaPush.markAllInboxMessagesAsRead();
```

<H2 id="a-b-testing" step={9}>A/B Testing</H2>

```typescript
// Get active tests
const tests = await AbrovaPush.getActiveABTests();

// Get the assigned variant for a test
const variant = await AbrovaPush.getABTestVariant('test_id');
if (variant) {
  // variant.variantName, variant.isControlGroup
}

// Track events
await AbrovaPush.trackABTestImpression('test_id', 'variant_id');
await AbrovaPush.trackABTestClicked('test_id', 'variant_id');

// Listen for new variant assignments
AbrovaPush.onABTestVariantAssigned((variant) => {
  // Newly assigned to a variant
});
```

<H2 id="log-levels" step={10}>Log Levels</H2>

```typescript
import { LogLevel } from 'abrova-push-react-native';

await AbrovaPush.setLogLevel(LogLevel.DEBUG);   // Development
await AbrovaPush.setLogLevel(LogLevel.ERROR);   // Production
```

Available levels: `NONE`, `ERROR`, `WARNING`, `INFO`, `DEBUG`, `VERBOSE`.

<H2 id="configuration-options" step={11}>Configuration Options</H2>

```typescript
await AbrovaPush.init({
  apiKey: 'ab_live_your_api_key',
  notificationIcon: 'ic_notification',
  usePushKit: false,
  showServiceNotification: true,
  appGroup: 'group.com.yourcompany.yourapp',
  autoRefresh: true,
});
```

<ConfigTable rows={[
  ['apiKey', 'string', 'Yes', 'Your project API key (`ab_live_...`) from Abrova Console'],
  ['notificationIcon', 'string', 'No', 'Android notification icon resource name'],
  ['usePushKit', 'boolean', 'No', 'Enable iOS PushKit VoIP mode (default: true in this SDK — set false unless your app is a calling app, or App Store review may reject it)'],
  ['showServiceNotification', 'boolean', 'No', 'Show Android foreground-service notification (default: true)'],
  ['appGroup', 'string', 'No', 'iOS only: App Group shared with a Notification Service Extension, for delivery confirmation'],
  ['autoRefresh', 'boolean', 'No', 'Refresh a previously registered device on launch when 24h passed or app/SDK version or user changed; never prompts (default: true)'],
]} />

<Callout kind="note" title="Auto-configured Connection">
Connection configuration is fetched from the server using your API key. No manual setup is needed.
</Callout>

<H2 id="voip-calls-optional" step={12}>VoIP Calls (Optional)</H2>

The Push SDK works on its own. For native incoming-call UI, add the separate `abrova-push-react-native-voip` package (see [VoIP Add-on](/docs/push/voip)) and send a push whose `data` contains `type: "voip_call"`:

```json
{
  "type": "voip_call",
  "callerName": "John Doe",
  "callerId": "user_456",
  "callerAvatar": "https://example.com/avatar.jpg",
  "callType": "video"
}
```

The `type: "voip_call"` is the system trigger (fixed). Caller-data keys are configurable via the VoIP SDK config.

### API Reference

#### `AbrovaPush` — Initialization & Lifecycle

<ConfigTable rows={[
  ['init(config)', '-', '-', 'Initialize the SDK with a config object'],
  ['register(options)', '-', '-', 'Register the device with the Abrova backend'],
  ['unregister()', '-', '-', 'Unregister the device'],
  ['isConnected()', '-', '-', 'Check whether the real-time connection is open'],
  ['getDeviceId()', '-', '-', 'Get the current device identifier'],
  ['removeAllListeners()', '-', '-', 'Remove every registered listener (useful in tests)'],
]} />

#### Callbacks

All event handlers return an unsubscribe function.

<ConfigTable rows={[
  ['onMessage(callback)', '-', '-', 'Called when a push message is received'],
  ['onConnectionState(callback)', '-', '-', 'Connection open / closed state changes'],
  ['onRegistered(callback)', '-', '-', 'Device registration completed; deviceId returned'],
  ['onError(callback)', '-', '-', 'String error message'],
  ['onDetailedError(callback)', '-', '-', 'Structured error with code + message'],
  ['onReconnecting(callback)', '-', '-', 'Reconnection attempt state'],
  ['onNetworkState(callback)', '-', '-', 'Network availability change'],
  ['onAppState(callback)', '-', '-', 'App foreground / background change'],
  ['onNotificationTapped(callback)', '-', '-', 'User tapped a notification while the app was running'],
  ['onNotificationAction(callback)', '-', '-', 'User tapped a notification action button'],
  ['onAppUpdated(callback)', '-', '-', 'The SDK detected an app update'],
]} />

#### User & Topics

<ConfigTable rows={[
  ['setUserId(id)', '-', '-', 'Set the current user identifier'],
  ['clearUserId()', '-', '-', 'Clear the user identifier'],
  ['subscribeTopic(topic)', '-', '-', 'Subscribe to a topic'],
  ['unsubscribeTopic(topic)', '-', '-', 'Unsubscribe from a topic'],
]} />

#### Inbox

<ConfigTable rows={[
  ['getInboxMessages(filter)', '-', '-', 'Fetch a page of inbox messages'],
  ['markInboxMessageAsRead(id)', '-', '-', 'Mark an inbox message as read'],
  ['archiveInboxMessage(id)', '-', '-', 'Archive an inbox message'],
  ['getInboxUnreadCount()', '-', '-', 'Get the unread count for badges'],
  ['markAllInboxMessagesAsRead()', '-', '-', 'Bulk mark every message as read'],
]} />

#### A/B Testing

<ConfigTable rows={[
  ['getActiveABTests()', '-', '-', 'Get active A/B tests'],
  ['getABTestVariant(testId)', '-', '-', 'Get the assigned variant for a test'],
  ['trackABTestImpression(testId, variantId)', '-', '-', 'Track an impression'],
  ['trackABTestClicked(testId, variantId)', '-', '-', 'Track a click conversion'],
]} />

### Best Practices

<BestPracticeList items={[
  ['Initialize Once at App Start', 'Call AbrovaPush.init() in your root component or app entry — not in every screen'],
  ['Unsubscribe in useEffect Cleanup', 'Every callback returns an unsubscribe function — call it in your effect cleanup to avoid duplicate handlers across re-mounts'],
  ['Set User ID After Login', 'Call setUserId() once authentication completes so notifications target the right account across devices'],
  ['Check Initial Message on Cold Start', 'Always await getInitialMessage() at app launch so deep-link taps land on the right screen'],
  ['Use TypeScript', 'The SDK is written in TypeScript. The package\'s `types` entry (src/index.d.ts) is stale and does not declare the inbox, in-app, A/B testing, onNotificationTapped or onNotificationAction APIs, so the TypeScript compiler may flag calls that work at runtime'],
]} />

- Web: https://abrova.ir/en/docs/push/web

<BestPracticeList columns={2} items={[
  ['Real-time via WebSocket', 'A persistent connection over TLS (port 443) delivers messages instantly while the tab is open'],
  ['Web Push (VAPID)', 'Background notifications when browser is closed via service worker'],
  ['Rich Notifications', 'Images, action buttons, badges, deep links'],
  ['Topic Subscriptions', 'Broadcast to interest groups'],
  ['Auto-reconnect', 'Exponential backoff handles flaky networks'],
  ['Badge API + Favicon Fallback', 'Unified badge count across the platforms that support it'],
  ['Localization Support', 'Notification title/body localizations picked by the browser language'],
  ['Framework-Agnostic', 'React, Vue, Angular, Svelte, vanilla JS'],
]} />

<H2 id="installation" step={1}>Installation</H2>

The SDK installs from Abrova Center in two steps.

1. Point the `@abrova` scope at Abrova Center in your project's `.npmrc`:

```
# .npmrc (in your project root)
@abrova:registry=https://center.abrova.ir/api/packages/abrova/npm/
```

2. Install the package:

```bash
npm install @abrova/push-web@^0.1.12
```

#### Without a bundler

The package also ships a ready-made browser build. Copy it into your public directory and load it from your own site:

```bash
cp node_modules/@abrova/push-web/dist/index.umd.js public/abrova-push.umd.js
```

```html
<script src="/abrova-push.umd.js"></script>
```

<H2 id="service-worker-setup" step={2}>Service Worker Setup</H2>

The Web SDK uses a service worker for background notifications (Web Push). Copy it once to your public directory:

```bash
cp node_modules/@abrova/push-web/service-worker.js public/abrova-push-sw.js
```

<Callout kind="warn" title="HTTPS Required">
Web Push requires HTTPS. `localhost` works for development. Make sure the service worker file is served from the **root** of your public directory.
</Callout>

<Callout kind="note" title="Upgrading the SDK">
Copy `service-worker.js` again whenever you upgrade `@abrova/push-web`. An older worker keeps working, but misses fixes such as SDK version reporting on re-subscription.
</Callout>

<H2 id="quick-start" step={3}>Quick Start</H2>

```typescript
import AbrovaPush from '@abrova/push-web';

const abrovaPush = new AbrovaPush({
  apiKey: 'ab_live_your_api_key',
});

abrovaPush.onMessage((message) => {
  // message.title, message.body, message.data
});

abrovaPush.onConnectionState((state) => {
  // 'connecting' | 'connected' | 'disconnected' | 'error'
});

abrovaPush.onRegistered((deviceId) => {
  // Device registered with the Abrova backend
});

// Register the device — this also requests notification permission.
// Once permission is granted, call register() on every page load to keep the
// device's subscription, app version and last-seen time current.
const deviceId = await abrovaPush.register({ userId: 'user_123' });
```

<H2 id="callbacks" step={4}>Callbacks</H2>

All event handlers return an unsubscribe function. Call it on teardown.

```typescript
// Foreground messages
const unsub = abrovaPush.onMessage((message) => {
  // message.title, message.body
});

// Connection state changes
abrovaPush.onConnectionState((state) => {
  // 'connecting' | 'connected' | 'disconnected' | 'error'
});

// Notification clicked while the browser was in background
abrovaPush.onNotificationClick((message, action) => {
  if (message.deepLink) {
    window.location.href = message.deepLink;
  }
});

// Action button clicked on a notification
abrovaPush.onActionClicked((actionId, message) => {
  // actionId from the original push payload
});

// Errors
abrovaPush.onError((error) => {});
abrovaPush.onDetailedError((error) => {
  // error.code, error.message
});

// Reconnection attempts
abrovaPush.onReconnecting((state) => {
  // state.retryAttempt, state.nextRetryMs
});

// Network state changes
abrovaPush.onNetworkState((state) => {
  // state.isAvailable, state.networkType
});

// Tab visibility changes
abrovaPush.onAppState((state) => {
  // state.isVisible
});

// Clean up
unsub();
```

<H2 id="user-identification" step={5}>User Identification</H2>

```typescript
// Set user ID after login
await abrovaPush.setUserId('user_123');

// Clear user ID on logout — also detaches the user on the server,
// so this browser stops receiving the previous user's notifications
await abrovaPush.clearUserId();

// Register with user ID in one call
await abrovaPush.register({ userId: 'user_123' });
```

<H2 id="topics" step={6}>Topics</H2>

```typescript
await abrovaPush.subscribeTopic('news');
await abrovaPush.subscribeTopic('promotions');

await abrovaPush.unsubscribeTopic('promotions');
```

<H2 id="badge-management" step={7}>Badge Management</H2>

Unified badge API — uses the [native Badge API](https://developer.mozilla.org/en-US/docs/Web/API/Badging_API) where available and falls back to drawing on the favicon.

```typescript
abrovaPush.setBadgeCount(5);
abrovaPush.clearBadge();
const count = abrovaPush.getBadgeCount();
```

<H2 id="message-inbox" step={8}>Message Inbox</H2>

Server-stored messages users can revisit, with live updates and an offline cache
(0.1.6+). See the [Inbox guide](/docs/push/inbox).

```typescript
abrovaPush.inbox.onMessage((message) => render(message));
abrovaPush.inbox.onUnreadCountChange((count) => setBadge(count));

const { messages, unreadCount } = await abrovaPush.inbox.getMessages({ status: 'unread' });
await abrovaPush.inbox.markAsRead(messages[0].id);
await abrovaPush.inbox.markAllAsRead();
```

<H2 id="analytics" step={9}>Analytics</H2>

Forward SDK events to your analytics service:

```typescript
abrovaPush.setAnalyticsHandler((event, properties) => {
  analytics.track(`abrova_push_${event}`, properties);
});

// Disable if needed (e.g. for GDPR)
abrovaPush.disableAnalytics();
```

<H2 id="log-levels" step={10}>Log Levels</H2>

```typescript
import { AbrovaPushLogLevel } from '@abrova/push-web';

abrovaPush.setLogLevel(AbrovaPushLogLevel.DEBUG);   // Development
abrovaPush.setLogLevel(AbrovaPushLogLevel.ERROR);   // Production
```

Available levels: `NONE`, `ERROR`, `WARNING`, `INFO`, `DEBUG`, `VERBOSE`.

<H2 id="utilities" step={11}>Utilities</H2>

```typescript
const connected = abrovaPush.isConnected();
const deviceId = abrovaPush.getDeviceId();
const network = abrovaPush.getNetworkState();
const appState = abrovaPush.getAppState();
const initialMessage = abrovaPush.getInitialMessage();

// Static checks
AbrovaPush.isSupported();
AbrovaPush.getPermissionStatus();

// Unregister the device
await abrovaPush.unregister();
```

<H2 id="configuration-options" step={12}>Configuration Options</H2>

```typescript
const abrovaPush = new AbrovaPush({
  apiKey: 'ab_live_your_api_key',
  serviceWorkerPath: '/abrova-push-sw.js',
  autoRegisterServiceWorker: true,
  maxReconnectAttempts: 0,
  logLevel: AbrovaPushLogLevel.ERROR,
  appVersion: '2.0.0',
  autoRefresh: true,
});
```

<ConfigTable rows={[
  ['apiKey', 'string', 'Yes', 'Your project API key (`ab_live_...`) from Abrova Console'],
  ['serviceWorkerPath', 'string', 'No', 'Path to the service worker file (default: "/abrova-push-sw.js")'],
  ['autoRegisterServiceWorker', 'boolean', 'No', 'Auto-register the service worker (default: true)'],
  ['maxReconnectAttempts', 'number', 'No', 'Max reconnect attempts after the connection drops; 0 = no limit, backing off up to 60 s (default: 0)'],
  ['logLevel', 'AbrovaPushLogLevel', 'No', 'NONE / ERROR / WARNING / INFO / DEBUG / VERBOSE (default: ERROR)'],
  ['appVersion', 'string', 'No', 'Your web app version, shown per device and usable as a segment filter'],
  ['vapidPublicKey', 'string', 'No', 'Fallback VAPID public key for Web Push; the key fetched from the server takes precedence, so normally leave unset'],
  ['autoRefresh', 'boolean', 'No', 'On page load, silently re-register a browser that registered before, at most once every 24h or sooner when the push subscription, appVersion, SDK version or user changed. Never prompts for permission (default: true)'],
  ['inApp', 'InAppConfig', 'No', 'In-app message options: enabled, display (\'auto\' | \'manual\'), autoTrigger, bannerPosition, locale. The in-app API is on `abrovaPush.inApp`'],
]} />

The installed SDK version is exported as `SDK_VERSION`:

```typescript
import { SDK_VERSION } from '@abrova/push-web';
```

#### Delivery Tracking

Notifications are confirmed as `delivered` automatically: Web Push arrivals by the service worker, and messages received over the real-time connection while the page is open by the SDK. No code needed. See [Delivery Receipts](/docs/push/receipts).

<H2 id="usage-without-a-bundler" step={13}>Usage Without a Bundler</H2>

For sites that don't use a bundler, load the browser build you copied in step 1:

```html
<!DOCTYPE html>
<html>
<head>
  <title>My App</title>
</head>
<body>
  <script src="/abrova-push.umd.js"></script>
  <script>
    const abrovaPush = new AbrovaPush.default({
      apiKey: 'ab_live_your_api_key',
    });

    abrovaPush.onMessage(function(message) {
      // message.title, message.body
    });

    abrovaPush.register().then(function(deviceId) {
      // Device registered
    });
  </script>
</body>
</html>
```

### API Reference

#### `AbrovaPush` — Initialization & Lifecycle

<ConfigTable rows={[
  ['constructor(config)', '-', '-', 'Create the SDK instance'],
  ['register(options?)', '-', '-', 'Register the device + request notification permission. Call on every page load once permission is granted'],
  ['unregister()', '-', '-', 'Unregister the device'],
  ['isConnected()', '-', '-', 'Check whether the WebSocket connection is open'],
  ['getDeviceId()', '-', '-', 'Get the current device identifier'],
  ['getNetworkState()', '-', '-', 'Get the current network availability + type'],
  ['getAppState()', '-', '-', 'Get the current tab visibility state'],
  ['getInitialMessage()', '-', '-', 'Get the message that opened the page from a notification tap'],
]} />

#### `abrovaPush.inbox` — Message Inbox (0.1.6+)

<ConfigTable rows={[
  ['getMessages(filter?)', '-', '-', 'Fetch messages (status, category, limit, offset, locale)'],
  ['getMessage(id)', '-', '-', 'Fetch one message'],
  ['getCachedMessages()', '-', '-', 'Cached messages, no network'],
  ['getUnreadCount()', '-', '-', 'Unread count from the cache'],
  ['fetchUnreadCount()', '-', '-', 'Unread count from the server'],
  ['markAsRead(id)', '-', '-', 'Mark one message read'],
  ['archiveMessage(id)', '-', '-', 'Archive one message'],
  ['deleteMessage(id)', '-', '-', 'Delete one message'],
  ['markMultiple(ids, status)', '-', '-', "Set status on several messages ('read' | 'archived' | 'deleted')"],
  ['markAllAsRead()', '-', '-', 'Mark every message read'],
  ['clearCache()', '-', '-', 'Drop the local cache'],
  ['onMessage(cb)', '-', '-', 'New inbox message; returns an unsubscribe function'],
  ['onStatusChange(cb)', '-', '-', 'A message status changed'],
  ['onUnreadCountChange(cb)', '-', '-', 'Unread count changed — use it for a badge'],
]} />

#### Static methods

<ConfigTable rows={[
  ['AbrovaPush.isSupported()', '-', '-', 'Check whether the browser supports notifications + service workers'],
  ['AbrovaPush.getPermissionStatus()', '-', '-', 'Current Notification.permission value'],
]} />

#### Callbacks

All callbacks return an unsubscribe function.

<ConfigTable rows={[
  ['onMessage(callback)', '-', '-', 'Foreground push received'],
  ['onConnectionState(callback)', '-', '-', 'WebSocket connection state changed'],
  ['onRegistered(callback)', '-', '-', 'Device registration completed'],
  ['onNotificationClick(callback)', '-', '-', 'User clicked a background notification'],
  ['onActionClicked(callback)', '-', '-', 'User clicked an action button'],
  ['onError(callback)', '-', '-', 'Error object'],
  ['onDetailedError(callback)', '-', '-', 'Structured error with code + message'],
  ['onReconnecting(callback)', '-', '-', 'Reconnection attempt state'],
  ['onNetworkState(callback)', '-', '-', 'Network availability changed'],
  ['onAppState(callback)', '-', '-', 'Tab visibility changed'],
]} />

#### User & Topics

<ConfigTable rows={[
  ['setUserId(id)', '-', '-', 'Set the current user identifier'],
  ['clearUserId()', '-', '-', 'Async. Clear the user identifier and detach the user on the server'],
  ['subscribeTopic(topic)', '-', '-', 'Subscribe to a topic'],
  ['unsubscribeTopic(topic)', '-', '-', 'Unsubscribe from a topic'],
]} />

#### Badge + Analytics + Logs

<ConfigTable rows={[
  ['setBadgeCount(count)', '-', '-', 'Set the app badge count'],
  ['clearBadge()', '-', '-', 'Clear the app badge'],
  ['getBadgeCount()', '-', '-', 'Get the current badge count'],
  ['setAnalyticsHandler(callback)', '-', '-', 'Forward SDK events to your analytics service'],
  ['disableAnalytics()', '-', '-', 'Stop forwarding SDK events'],
  ['setLogLevel(level)', '-', '-', 'Set the SDK log verbosity'],
]} />

### Browser Support

- **Chrome 50+** (Desktop & Android)
- **Firefox 44+**
- **Edge 17+**
- **Safari 16+** (macOS only — iOS does not support Web Push)
- **Opera 37+**

### Requirements

- HTTPS required (`localhost` works for development)
- Service worker file must be in the public root directory
- User must grant notification permission via the browser's permission prompt

### Best Practices

<BestPracticeList items={[
  ['Initialize Once Per Page Load', 'Create one AbrovaPush instance per page — re-creating it on every render leaks listeners'],
  ['Request Permission in Context', 'The first time, call register() from a UI affordance where the user understands why notifications matter. After permission is granted, call it on every page load'],
  ['Check Static Support First', 'Call AbrovaPush.isSupported() before showing notification UI — some browsers / private modes don\'t support Web Push'],
  ['Set User ID After Login', 'Call setUserId() once authentication completes so notifications target the right account across devices'],
  ['Unsubscribe Listeners on Teardown', 'Every callback returns an unsubscribe function — call it when components unmount to prevent stale handlers'],
  ['Handle the Initial Message', 'When the user clicks a notification while the tab is closed, getInitialMessage() returns the payload on page load — use it for deep linking'],
]} />

- Node.js: https://abrova.ir/en/docs/push/nodejs

<BestPracticeList columns={2} items={[
  ['Send to User / Device / Topic', 'Push to a single device, all of a user\'s devices, or topic / segment audiences'],
  ['Broadcast', 'Single call to push to every registered device'],
  ['Rich Notifications', 'Images, action buttons, deep links, custom data'],
  ['Templates', 'Reusable notification copy with variable substitution'],
  ['Segments', 'Server-evaluated audiences from user metadata'],
  ['Scheduled Messages', 'Send at a specific time + timezone'],
  ['Webhooks', 'Subscribe to message sent / delivered / failed and device events'],
  ['Inbox + Receipts + Analytics', 'Inbox sends, per-device delivery receipts and delivery analytics from the server'],
]} />

<H2 id="installation" step={1}>Installation</H2>

The SDK installs from Abrova Center in two steps.

1. Point the `@abrova` scope at Abrova Center in your project's `.npmrc`:

```
# .npmrc (in your project root)
@abrova:registry=https://center.abrova.ir/api/packages/abrova/npm/
```

2. Install the package:

```bash
npm install @abrova/push-node
```

<H2 id="quick-start" step={2}>Quick Start</H2>

```typescript
import { AbrovaPush } from '@abrova/push-node';

const abrovaPush = new AbrovaPush({
  apiKey: process.env.ABROVA_API_KEY,             // ab_live_...
  serverSecret: process.env.ABROVA_SERVER_SECRET, // ab_srv_..., server only
});

await abrovaPush.push.sendToUser({
  userId: 'user-123',
  title: 'Order Shipped',
  body: 'Your order #1234 has been shipped!',
  data: { orderId: '1234' },
});
```

<Callout kind="note" title="Server Credentials Required">
Both `apiKey` and `serverSecret` are required for all server-side operations. Find them in your [Abrova Console](https://console.abrova.ir) under project settings. **Never** ship the `serverSecret` to client-side code.
</Callout>

<H2 id="send-push-notifications" step={3}>Send Push Notifications</H2>

```typescript
// Send to a specific device
await abrovaPush.push.sendToDevice({
  deviceId: 'device-uuid',
  title: 'Hello',
  body: 'Welcome to our app!',
});

// Send to all of a user's devices
await abrovaPush.push.sendToUser({
  userId: 'user-123',
  title: 'New Message',
  body: 'You have a new message',
});

// Send to multiple specific devices
await abrovaPush.push.sendToDevices({
  deviceIds: ['device-1', 'device-2', 'device-3'],
  title: 'Update Available',
  body: 'A new version is available',
});

// Send to a topic
await abrovaPush.push.sendToTopic({
  topic: 'promotions',
  title: 'Flash Sale!',
  body: '50% off everything today only',
  imageUrl: 'https://example.com/sale.jpg',
});

// Send to a segment
await abrovaPush.push.sendToSegment({
  segmentId: 'segment-uuid',
  title: 'Exclusive Offer',
  body: 'Just for our VIP customers',
});

// Broadcast to every registered device
await abrovaPush.push.broadcast({
  title: 'App Update',
  body: 'Check out the new features!',
});
```

<H2 id="multi-app-targeting" step={4}>Multi-App Targeting</H2>

If your project hosts multiple apps (e.g. a shopping app and a chat app), use `appIdentifier` (the bundle ID / package name) to target a specific app:

```typescript
await abrovaPush.push.sendToUser({
  userId: 'user-123',
  title: 'New Order',
  body: 'Your order is ready',
  appIdentifier: 'com.myshop.app', // only this app receives it
});
```

<Callout kind="note" title="Optional">
`appIdentifier` is optional. When omitted, the notification is sent to **all** apps registered under the project. Single-app projects don't need to set it.
</Callout>

<H2 id="rich-notifications" step={5}>Rich Notifications</H2>

```typescript
await abrovaPush.push.sendToUser({
  userId: 'user-123',
  title: 'New Product',
  body: 'Check out our latest arrival',
  imageUrl: 'https://example.com/product.jpg',
  actions: [
    { id: 'buy', title: 'Buy Now', action: 'OPEN_PRODUCT' },
    { id: 'later', title: 'Save for Later' },
  ],
  deepLink: 'myapp://product/123',
  data: { productId: '123' },
});
```

<H2 id="templates" step={6}>Templates</H2>

Reusable copy with variable substitution. Useful when the same message shape ships in many flows (order shipped, password reset, etc.).

```typescript
// Send using a template
await abrovaPush.push.sendToUser({
  userId: 'user-123',
  templateId: 'order-shipped-template',
  templateVariables: {
    orderNumber: '#1234',
    trackingUrl: 'https://track.example.com/1234',
  },
});

// Create a template
const template = await abrovaPush.templates.create({
  name: 'Order Shipped',
  title: 'Your order {{orderNumber}} has shipped!',
  body: 'Track your package: {{trackingUrl}}',
  variables: ['orderNumber', 'trackingUrl'],
});

// List templates
const templates = await abrovaPush.templates.list();

// Preview render
const rendered = await abrovaPush.templates.render(template.id, {
  orderNumber: '#1234',
  trackingUrl: 'https://track.example.com/1234',
});
```

<H2 id="inbox-messages" step={7}>Inbox Messages</H2>

Push delivers a message to the device. Inbox stores it persistently so the user can revisit later.

```typescript
// Send inbox message to a user
await abrovaPush.inbox.sendToUser({
  userId: 'user-123',
  content: {
    title: 'Welcome!',
    body: 'Thanks for joining us.',
    imageUrl: 'https://example.com/welcome.jpg',
    deepLink: 'myapp://onboarding',
  },
});

// Send to multiple users
await abrovaPush.inbox.sendToUsers({
  userIds: ['user-1', 'user-2', 'user-3'],
  content: { title: 'New Feature', body: 'Check out our latest feature' },
});

// Broadcast with expiry
await abrovaPush.inbox.broadcast({
  content: { title: 'Holiday Sale', body: 'Up to 70% off!' },
  expiresAt: '2025-12-31T23:59:59Z',
});
```

<H2 id="device-management" step={8}>Device Management</H2>

```typescript
// List all devices
const devices = await abrovaPush.devices.list();

// Subscribe a device to a topic
await abrovaPush.devices.subscribeTopic('device-uuid', 'news');
await abrovaPush.devices.unsubscribeTopic('device-uuid', 'news');

// Associate device with a user
await abrovaPush.devices.setUserId('device-uuid', 'user-123');

// Delete a device
await abrovaPush.devices.delete('device-uuid');

// Paginated, filtered list (includes inactive devices unless isActive is set)
const { items, total } = await abrovaPush.devices.listPage({
  platform: 'ios',
  isActive: true,
  page: 1,
  limit: 50,
});

// Values you can filter on (app versions, SDK versions, failure reasons)
const options = await abrovaPush.devices.filterOptions();

// Stop sending to a device but keep its history, and undo it
await abrovaPush.devices.unregister('device-uuid');
await abrovaPush.devices.reactivate('device-uuid');
```

<H2 id="segments" step={9}>Segments</H2>

Segments evaluate user metadata server-side. Use them when you need "all users with more than 10 orders" or "all users in Tehran on the premium tier."

```typescript
// Create a segment
const segment = await abrovaPush.segments.create({
  name: 'VIP Customers',
  description: 'Customers with more than 10 orders',
  filters: [
    { field: 'metadata.orders', operator: 'greater_than', value: 10 },
  ],
});

// Get devices in a segment
const devices = await abrovaPush.segments.getDevices(segment.id);

// Recalculate segment membership (e.g. after metadata changes)
await abrovaPush.segments.recalculate(segment.id);
```

<H2 id="scheduled-messages" step={10}>Scheduled Messages</H2>

```typescript
// Schedule a message
const scheduled = await abrovaPush.scheduled.create({
  title: 'Reminder',
  body: 'Don\'t forget to complete your purchase!',
  targetType: 'user',
  targetValue: 'user-123',
  scheduledAt: '2025-02-14T09:00:00Z',
  timezone: 'Asia/Tehran',
});

// List pending messages
const pending = await abrovaPush.scheduled.listPending();

// Cancel a scheduled message
await abrovaPush.scheduled.cancel(scheduled.id);
```

<H2 id="webhooks" step={11}>Webhooks</H2>

Subscribe to message (`message.sent`, `message.delivered`, `message.failed`, `message.no_recipients`) and device (`device.registered`, `device.unregistered`, `device.updated`) events so your backend can react in real time.

```typescript
// Create a webhook
const webhook = await abrovaPush.webhooks.create({
  name: 'Order Events',
  url: 'https://example.com/webhooks/abrova-push',
  events: ['message.sent', 'message.delivered', 'message.failed'],
  secret: 'my-secret-key',
});

// Test a webhook
await abrovaPush.webhooks.test(webhook.id, 'message.delivered');

// Read delivery logs for debugging
const logs = await abrovaPush.webhooks.getLogs(webhook.id);
```

<H2 id="analytics" step={12}>Analytics</H2>

```typescript
// Device and message totals, delivery rate, platform distribution
const overview = await abrovaPush.analytics.getOverview();

// Daily breakdown
const daily = await abrovaPush.analytics.getDaily(30); // last 30 days

// App-level totals (devices per platform, topics, users)
const stats = await abrovaPush.analytics.getStats();
```

#### Delivery receipts

A send's `success` count means the push service *accepted* the notification. Receipts show what happened on each device. See [Delivery Receipts](/docs/push/receipts).

```typescript
const { messageId } = await abrovaPush.push.sendToUser({ userId: 'user-123', title: 'Hi', body: 'Hello' });

// Per device, for one message
const receipts = await abrovaPush.receipts.getForMessage(messageId!);
const stats = await abrovaPush.receipts.getMessageStats(messageId!);

// Receipt log with filters
const { items, total } = await abrovaPush.receipts.list({
  status: 'failed',
  platform: 'android',
  startDate: new Date(Date.now() - 7 * 86400_000),
  page: 1,
  limit: 100,
});

// Delivery analytics (default: last 30 days)
const analytics = await abrovaPush.receipts.analytics({ bucket: 'day' });
console.log(analytics.totals, analytics.byPlatform, analytics.topFailureReasons);
```

<H2 id="a-b-tests-and-in-app-messages" step={13}>A/B Tests and In-App Messages</H2>

Create A/B tests and in-app messages in Abrova Console.

<H2 id="error-handling" step={14}>Error Handling</H2>

```typescript
import { AbrovaPush, AbrovaPushError } from '@abrova/push-node';

try {
  await abrovaPush.push.sendToUser({
    userId: 'user-123',
    title: 'Hello',
    body: 'World',
  });
} catch (error) {
  if (error instanceof AbrovaPushError) {
    // error.statusCode, error.message, error.response
  }
}
```

<H2 id="configuration" step={15}>Configuration</H2>

```typescript
const abrovaPush = new AbrovaPush({
  apiKey: process.env.ABROVA_API_KEY!,
  serverSecret: process.env.ABROVA_SERVER_SECRET!,
});
```

#### Environment Variables

We recommend storing credentials in environment variables, never in version control:

```bash
# .env
ABROVA_API_KEY=ab_live_your_api_key
ABROVA_SERVER_SECRET=ab_srv_your_server_secret
```

#### Credential Reference

<ConfigTable rows={[
  ['apiKey', 'String', 'Yes', 'Used for client-side SDKs and server-side SDKs (ab_live_... format)'],
  ['serverSecret', 'String', 'Yes', 'Required for server-side operations (ab_srv_... format). Never expose in client code.'],
]} />

### API Reference

#### `push` — sending notifications

<ConfigTable rows={[
  ['sendToUser(payload)', '-', '-', 'Send to all of a user\'s devices'],
  ['sendToDevice(payload)', '-', '-', 'Send to a single device'],
  ['sendToDevices(payload)', '-', '-', 'Send to multiple specific devices'],
  ['sendToTopic(payload)', '-', '-', 'Send to every subscriber of a topic'],
  ['sendToSegment(payload)', '-', '-', 'Send to a segment'],
  ['broadcast(payload)', '-', '-', 'Send to every registered device'],
]} />

#### `inbox` — persistent message center

<ConfigTable rows={[
  ['sendToUser(payload)', '-', '-', 'Add an inbox message for a single user'],
  ['sendToUsers(payload)', '-', '-', 'Add an inbox message for multiple users'],
  ['broadcast(payload)', '-', '-', 'Add an inbox message for every user that has a device with a user ID'],
]} />

#### `devices` — device management

<ConfigTable rows={[
  ['list()', '-', '-', 'List all active devices'],
  ['listPage(filters)', '-', '-', 'Paginated, filtered device list (platform, active, user, app or SDK version, last seen)'],
  ['filterOptions()', '-', '-', 'App versions, SDK versions and failure reasons you can filter on'],
  ['unregister(deviceId)', '-', '-', 'Stop sending to a device, keep its history'],
  ['reactivate(deviceId)', '-', '-', 'Undo unregister'],
  ['subscribeTopic(deviceId, topic)', '-', '-', 'Subscribe a device to a topic'],
  ['unsubscribeTopic(deviceId, topic)', '-', '-', 'Unsubscribe a device from a topic'],
  ['setUserId(deviceId, userId)', '-', '-', 'Associate a device with a user'],
  ['delete(deviceId)', '-', '-', 'Delete a device'],
]} />

#### `receipts` — per-device delivery

<ConfigTable rows={[
  ['getForMessage(messageId)', '-', '-', 'Receipts for every device a message went to'],
  ['getMessageStats(messageId)', '-', '-', 'Sent / delivered / failed counts for one message'],
  ['getActionStats(messageId)', '-', '-', 'Clicks per action button'],
  ['getForDevice(deviceId, limit?)', '-', '-', 'Recent receipts for one device'],
  ['list(filters)', '-', '-', 'Paginated receipt log (platform, status, error, user, device, message, dates)'],
  ['analytics(options)', '-', '-', 'Totals, per-platform and per-SDK breakdowns, timeseries, top failure reasons'],
]} />

#### `templates` — reusable copy

<ConfigTable rows={[
  ['create(payload)', '-', '-', 'Create a template'],
  ['list()', '-', '-', 'List templates'],
  ['render(id, variables)', '-', '-', 'Render a template with variable substitution'],
]} />

#### `segments` — audience targeting

<ConfigTable rows={[
  ['create(payload)', '-', '-', 'Create a segment with metadata filters'],
  ['getDevices(segmentId)', '-', '-', 'Get devices in a segment'],
  ['recalculate(segmentId)', '-', '-', 'Recalculate segment membership'],
]} />

#### `scheduled` — time-based delivery

<ConfigTable rows={[
  ['create(payload)', '-', '-', 'Schedule a message for a specific time + timezone'],
  ['listPending()', '-', '-', 'List pending scheduled messages'],
  ['cancel(id)', '-', '-', 'Cancel a scheduled message'],
]} />

#### `webhooks` — delivery event subscriptions

<ConfigTable rows={[
  ['create(payload)', '-', '-', 'Create a webhook for message and device events'],
  ['test(id, eventType)', '-', '-', 'Trigger a test event'],
  ['getLogs(id)', '-', '-', 'Read webhook delivery logs'],
]} />

#### `analytics` — delivery + engagement metrics

<ConfigTable rows={[
  ['getOverview()', '-', '-', 'Device and message totals, delivery rate, platform distribution'],
  ['getDaily(days)', '-', '-', 'Per-day stats for the last N days'],
  ['getStats()', '-', '-', 'App-level totals (devices per platform, topics, users)'],
]} />

### Best Practices

<BestPracticeList items={[
  ['Use Environment Variables', 'Never hardcode apiKey or serverSecret — load from env so credentials don\'t end up in version control'],
  ['Use Templates for Repeated Copy', 'When the same message shape ships in many flows (order shipped, password reset), templates keep copy consistent and edit-able without a deploy'],
  ['Topics for Broadcasts, Segments for Targeted', 'Topics suit large audiences but the user opts in client-side. Segments evaluate server-side metadata — better for "all premium users in Tehran"-style targeting.'],
  ['Catch AbrovaPushError', 'Wrap calls in try/catch and check for AbrovaPushError so you can surface statusCode + response to your logs'],
  ['Subscribe to Webhooks for Real-time Reactions', 'message.delivered / message.failed / message.no_recipients let your backend react in real time (e.g. mark order as notified, retry on miss)'],
]} />

- Callbacks: https://abrova.ir/en/docs/push/callbacks

Monitor SDK state and events with these callbacks. The callback set is shared across SDKs; syntax varies by platform.

<H2 id="flutter" step={1}>Flutter</H2>

#### Message Received

```dart
AbrovaPush.onMessage((message) {
  print('Title: ${message.title}');
  print('Body: ${message.body}');
  print('Data: ${message.data}');

  // Show local notification or update UI
});
```

#### Connection State

```dart
AbrovaPush.onConnectionState((connected) {
  if (connected) {
    print('Connected to server');
  } else {
    print('Disconnected from server');
  }
});
```

#### Registration Success

```dart
AbrovaPush.onRegistered((deviceId) {
  print('Device registered with ID: $deviceId');
  // Store deviceId for later use
});
```

#### Error Handling

```dart
// Simple error callback
AbrovaPush.onError((error) {
  print('Error: $error');
});

// Detailed error with codes
AbrovaPush.onDetailedError((error) {
  print('Code: ${error.code}');
  print('Message: ${error.message}');
  print('Details: ${error.details}');
});
```

#### Network State

```dart
AbrovaPush.onNetworkState((state) {
  print('Network available: ${state.isAvailable}');
  print('Network type: ${state.networkType}');
  // wifi, cellular, ethernet, vpn, none, unknown
});
```

#### App State

```dart
AbrovaPush.onAppState((state) {
  print('In foreground: ${state.isInForeground}');
  // SDK auto-reconnects when app returns to foreground
});
```

<H2 id="android-kotlin" step={2}>Android (Kotlin)</H2>

The Android SDK uses a single `AbrovaPushCallback` interface — implement the methods you need and register it once via `setCallback(...)`. Extend `AbrovaPushCallbackAdapter` for empty defaults on the methods you don't override.

```kotlin
import ir.abrova.push.sdk.AbrovaPush
import ir.abrova.push.sdk.AbrovaPushCallback
import ir.abrova.push.sdk.AbrovaPushCallbackAdapter
import ir.abrova.push.sdk.AbrovaPushMessage
import ir.abrova.push.sdk.AbrovaPushError

AbrovaPush.setCallback(object : AbrovaPushCallback {
    override fun onMessageReceived(message: AbrovaPushMessage) {
        Log.d("AbrovaPush", "Title: ${message.title}")
        Log.d("AbrovaPush", "Body: ${message.body}")
        Log.d("AbrovaPush", "Data: ${message.data}")
    }

    override fun onConnectionStateChanged(connected: Boolean) {
        Log.d("AbrovaPush", if (connected) "Connected" else "Disconnected")
    }

    override fun onRegistered(deviceId: String) {
        Log.d("AbrovaPush", "Device registered: $deviceId")
    }

    override fun onError(error: String) {
        Log.e("AbrovaPush", "Error: $error")
    }

    override fun onDetailedError(error: AbrovaPushError) {
        Log.e("AbrovaPush", "Code: ${error.code}, Message: ${error.message}")
    }

    override fun onReconnecting(attempt: Int, nextRetryMs: Long) {
        Log.d("AbrovaPush", "Retry $attempt, next in ${nextRetryMs}ms")
    }

    override fun onNetworkStateChanged(isAvailable: Boolean, networkType: String) {
        Log.d("AbrovaPush", "Network: $isAvailable ($networkType)")
        // networkType: wifi, cellular, ethernet, vpn, none, unknown
    }

    override fun onAppStateChanged(isInForeground: Boolean) {
        Log.d("AbrovaPush", "Foreground: $isInForeground")
    }

    override fun onAppUpdated(previousVersion: String, currentVersion: String, needsReregistration: Boolean) {
        Log.d("AbrovaPush", "Updated $previousVersion → $currentVersion")
        if (needsReregistration) {
            AbrovaPush.register(userId = "user_123")
        }
    }

    override fun onNotificationTapped(message: AbrovaPushMessage) {
        Log.d("AbrovaPush", "Notification tapped: ${message.title}")
        // Handle when app is in foreground / resumed
    }

    override fun onNotificationAction(message: AbrovaPushMessage, actionId: String) {
        Log.d("AbrovaPush", "Action clicked: $actionId for ${message.title}")
    }
})
```

#### Adapter for Selected Callbacks

```kotlin
// Only override what you need
AbrovaPush.setCallback(object : AbrovaPushCallbackAdapter() {
    override fun onMessageReceived(message: AbrovaPushMessage) {
        showNotification(message)
    }

    override fun onNotificationTapped(message: AbrovaPushMessage) {
        navigateToDeepLink(message.data?.get("deepLink") as? String)
    }
})
```

#### Initial Message (App Opened from Notification)

```kotlin
// Returns the notification that launched the app, or null
val initialMessage = AbrovaPush.getInitialMessage()
if (initialMessage != null) {
    val deepLink = initialMessage.data?.get("deepLink") as? String
    if (deepLink != null) {
        // Navigate to deep link
    }
}
```

#### Analytics Handler

Not supported on Android: the handler is never called. Use the `AbrovaPushCallback` methods above for telemetry.

```kotlin
import ir.abrova.push.sdk.AbrovaPush
import ir.abrova.push.sdk.AbrovaPushAnalyticsCallback
import ir.abrova.push.sdk.AbrovaPushAnalyticsEvent

AbrovaPush.setAnalyticsHandler(AbrovaPushAnalyticsCallback { event, properties ->
    Log.d("AbrovaPush", "Event: $event, Properties: $properties")

    // Send to your analytics service (Firebase, Mixpanel, etc.)
    when (event) {
        AbrovaPushAnalyticsEvent.MESSAGE_RECEIVED ->
            FirebaseAnalytics.getInstance(context).logEvent("push_received", null)
        AbrovaPushAnalyticsEvent.NOTIFICATION_CLICKED ->
            FirebaseAnalytics.getInstance(context).logEvent("push_clicked", null)
        AbrovaPushAnalyticsEvent.CONNECTION_ERROR ->
            FirebaseAnalytics.getInstance(context).logEvent("push_error", null)
        else -> { /* ignore */ }
    }
})

// Disable / re-enable / check
AbrovaPush.disableAnalytics()
val enabled = AbrovaPush.isAnalyticsEnabled()
```

<H2 id="react-native" step={3}>React Native</H2>

#### Message Received

```typescript
const unsubscribe = AbrovaPush.onMessage((message) => {
  console.log('Title:', message.title);
  console.log('Body:', message.body);
  console.log('Data:', message.data);
});

// Clean up in useEffect
useEffect(() => {
  return () => unsubscribe();
}, []);
```

#### Connection State

```typescript
const unsubscribe = AbrovaPush.onConnectionState((connected) => {
  console.log(connected ? 'Connected' : 'Disconnected');
});
```

#### Registration Success

```typescript
const unsubscribe = AbrovaPush.onRegistered((deviceId) => {
  console.log('Device ID:', deviceId);
});
```

#### Complete Hook Example

```typescript
import { useEffect, useState } from 'react';
import AbrovaPush from 'abrova-push-react-native';

export function useAbrovaPush(userId: string) {
  const [connected, setConnected] = useState(false);
  const [deviceId, setDeviceId] = useState<string | null>(null);

  useEffect(() => {
    const unsubMessage = AbrovaPush.onMessage((msg) => {
      console.log('Message:', msg);
    });

    const unsubConnection = AbrovaPush.onConnectionState(setConnected);
    const unsubRegistered = AbrovaPush.onRegistered(setDeviceId);

    AbrovaPush.register({ userId });

    return () => {
      unsubMessage();
      unsubConnection();
      unsubRegistered();
    };
  }, [userId]);

  return { connected, deviceId };
}
```

<H2 id="ios-swift" step={4}>iOS (Swift)</H2>

The iOS SDK uses a delegate pattern. Conform to `AbrovaPushDelegate` and assign it via `AbrovaPush.shared.delegate`. All methods are optional via the default extension — implement only the ones you need.

```swift
import AbrovaPushSDK

class PushHandler: NSObject, AbrovaPushDelegate {
    func abrovaPush(_ abrovaPush: AbrovaPush, didReceiveMessage message: AbrovaPushMessage) {
        print("Title: \(message.title)")
        print("Body: \(message.body)")
        print("Data: \(message.data ?? [:])")
    }

    func abrovaPush(_ abrovaPush: AbrovaPush, didChangeConnectionState connected: Bool) {
        print(connected ? "Connected" : "Disconnected")
    }

    func abrovaPush(_ abrovaPush: AbrovaPush, didRegisterWithDeviceId deviceId: String) {
        print("Device registered: \(deviceId)")
    }

    func abrovaPush(_ abrovaPush: AbrovaPush, didReceiveAPNsToken token: String) {
        print("APNs token: \(token)")
    }

    func abrovaPush(_ abrovaPush: AbrovaPush, didReceiveVoIPToken token: String) {
        print("VoIP token: \(token)")
    }

    func abrovaPush(_ abrovaPush: AbrovaPush, didFailWithError error: Error) {
        print("Error: \(error.localizedDescription)")
    }

    func abrovaPush(_ abrovaPush: AbrovaPush, didFailWithDetailedError error: AbrovaPushError) {
        print("Code: \(error.code), Message: \(error.message)")
    }

    func abrovaPush(_ abrovaPush: AbrovaPush, didStartReconnecting state: ReconnectionState) {
        print("Retry \(state.attempt), next in \(state.nextRetryMs)ms")
    }

    func abrovaPush(_ abrovaPush: AbrovaPush, didChangeNetworkState state: NetworkState) {
        print("Network: \(state.isAvailable) (\(state.networkType))")
    }

    func abrovaPush(_ abrovaPush: AbrovaPush, didChangeAppState state: AppState) {
        print("Foreground: \(state.isInForeground)")
    }

    func abrovaPush(_ abrovaPush: AbrovaPush, didDetectAppUpdate info: AppUpdateInfo) {
        print("Updated \(info.previousVersion) → \(info.currentVersion)")
        if info.needsReregistration {
            AbrovaPush.shared.register(userId: "user_123")
        }
    }

    func abrovaPush(_ abrovaPush: AbrovaPush, didTapNotification message: AbrovaPushMessage) {
        print("Notification tapped: \(message.title)")
    }

    func abrovaPush(_ abrovaPush: AbrovaPush, didReceiveNotificationAction action: NotificationAction, forMessage message: AbrovaPushMessage) {
        print("Action: \(action.id) for \(message.title)")
    }
}

// Wire it up once (e.g., in AppDelegate or App init).
// `delegate` is weak, so keep a strong reference to the handler (e.g., a property).
let pushHandler = PushHandler()
AbrovaPush.shared.delegate = pushHandler
```

#### Initial Message (App Opened from Notification)

```swift
// Returns the notification that launched the app, or nil
if let initialMessage = AbrovaPush.shared.getInitialMessage() {
    if let deepLink = initialMessage.deepLink ?? (initialMessage.data?["deepLink"]?.value as? String) {
        // Navigate to deep link
    }
    AbrovaPush.shared.clearInitialMessage()
}

// If the app was opened by tapping an action button on the launching notification
if let clicked = AbrovaPush.shared.getClickedAction() {
    print("Launched via action \(clicked.action.id) on \(clicked.message.title)")
}
```

<Callout kind="warn" title="Analytics Handler Not Available on iOS">
The iOS SDK does not currently expose `setAnalyticsHandler`. For SDK telemetry, observe the relevant delegate methods (`didReceiveMessage`, `didChangeConnectionState`, `didFailWithDetailedError`, etc.) and forward those events to your analytics provider directly. Flutter and Web support `setAnalyticsHandler`; Android exposes it but it is not supported there, and the React Native wrapper does not expose it either.
</Callout>

<H2 id="web" step={5}>Web</H2>

#### Message Received

```typescript
abrovaPush.onMessage((message) => {
  console.log('Title:', message.title);
  console.log('Body:', message.body);
  console.log('Data:', message.data);

  // Show notification or update UI
});
```

#### Connection State

```typescript
abrovaPush.onConnectionState((state) => {
  console.log('Connection state:', state);
  // 'connecting' | 'connected' | 'disconnected' | 'error'
});
```

#### Registration Success

```typescript
abrovaPush.onRegistered((deviceId) => {
  console.log('Device ID:', deviceId);
});
```

#### Notification Click

```typescript
abrovaPush.onNotificationClick((message, action) => {
  console.log('Notification clicked:', message);
  console.log('Action:', action);

  // Navigate to specific page based on message data
  if (message.data?.url) {
    window.location.href = message.data.url;
  }
});
```

#### Action Button Clicked

```typescript
abrovaPush.onActionClicked((actionId, message) => {
  console.log('Action clicked:', actionId);
  console.log('Message:', message);

  // Handle specific actions
  switch (actionId) {
    case 'view':
      window.location.href = message.data?.deepLink || '/';
      break;
    case 'dismiss':
      // Handle dismiss
      break;
  }
});
```

#### Error Handling

```typescript
import { AbrovaPushErrorCode } from '@abrova/push-web';

// Simple error callback
abrovaPush.onError((error) => {
  console.error('Error:', error.message);
});

// Detailed error with codes
abrovaPush.onDetailedError((error) => {
  console.error('Code:', error.code);
  console.error('Message:', error.message);
  console.error('Details:', error.details);

  switch (error.code) {
    case AbrovaPushErrorCode.CONNECTION_FAILED:
      // Handle connection failure
      break;
    case AbrovaPushErrorCode.PERMISSION_DENIED:
      // Handle permission denied
      break;
  }
});
```

#### Reconnecting State

```typescript
abrovaPush.onReconnecting((state) => {
  console.log('Retry attempt:', state.retryAttempt);
  console.log('Next retry in:', state.nextRetryMs, 'ms');
  console.log('Max attempts:', state.maxRetryAttempts);

  // Show reconnecting UI
  showReconnectingBanner(state.retryAttempt, state.maxRetryAttempts);
});
```

#### Network State

```typescript
abrovaPush.onNetworkState((state) => {
  console.log('Network available:', state.isAvailable);
  console.log('Network type:', state.networkType);
  // wifi, cellular, ethernet, none, unknown

  if (!state.isAvailable) {
    showOfflineBanner();
  }
});

// Get current network state
const networkState = abrovaPush.getNetworkState();
```

#### App State (Visibility)

```typescript
abrovaPush.onAppState((state) => {
  console.log('Is visible:', state.isVisible);
  console.log('Visibility state:', state.visibilityState);
  // visible, hidden, prerender

  // SDK auto-reconnects when page becomes visible
});

// Get current app state
const appState = abrovaPush.getAppState();
```

#### Initial Message (App Opened from Notification)

```typescript
// Get the notification that launched/opened the app
const initialMessage = abrovaPush.getInitialMessage();

if (initialMessage) {
  console.log('App opened from notification:', initialMessage.title);
  // Navigate to relevant page
  if (initialMessage.data?.deepLink) {
    window.location.href = initialMessage.data.deepLink;
  }
}
```

#### Analytics Handler

```typescript
import { AbrovaPushAnalyticsEvent } from '@abrova/push-web';

abrovaPush.setAnalyticsHandler((event, properties) => {
  console.log('Event:', event, properties);

  // Send to your analytics service
  switch (event) {
    case AbrovaPushAnalyticsEvent.MESSAGE_RECEIVED:
      analytics.track('push_received', properties);
      break;
    case AbrovaPushAnalyticsEvent.NOTIFICATION_CLICKED:
      analytics.track('push_clicked', properties);
      break;
    case AbrovaPushAnalyticsEvent.CONNECTION_ERROR:
      analytics.track('push_error', properties);
      break;
  }
});

// Disable analytics
abrovaPush.disableAnalytics();
```

- SDK analytics: https://abrova.ir/en/docs/push/sdk-analytics

Track SDK events with custom analytics handlers to integrate with your analytics service.

### Flutter

#### Setting Up Analytics

```dart
AbrovaPush.setAnalyticsHandler((event, properties) {
  print('Event: $event');
  print('Properties: $properties');

  // Send to your analytics service
  FirebaseAnalytics.instance.logEvent(
    name: 'abrovaPush_${event.name}',
    parameters: properties?.map((k, v) => MapEntry(k, v.toString())),
  );
});
```

#### Handling Specific Events

```dart
AbrovaPush.setAnalyticsHandler((event, properties) {
  switch (event) {
    case AbrovaPushAnalyticsEvent.messageReceived:
      // Track message received
      analytics.track('push_received', properties);
      break;

    case AbrovaPushAnalyticsEvent.connected:
      // Track successful connection
      analytics.track('push_connected');
      break;

    case AbrovaPushAnalyticsEvent.connectionError:
      // Track connection failures
      FirebaseCrashlytics.instance.recordError(
        Exception('Push connection error'),
        null,
        reason: properties?['error_code']?.toString() ?? properties?['error'],
      );
      break;

    default:
      break;
  }
});
```

The Flutter SDK's `AbrovaPushAnalyticsEvent` is a Dart enum with its own set of values: `sdkInitialized`, `deviceRegistered`, `deviceUnregistered`, `messageReceived`, `messageDisplayed`, `connected`, `disconnected`, `connectionError`, `retryStarted`, `topicSubscribed`, `topicUnsubscribed`, `networkStateChanged`, `appStateChanged`, `appUpdated`, the in-app events (`inAppMessageDisplayed`, `inAppButtonClicked`, `inAppMessageDismissed`, `inAppMessagesFetched`), the inbox events (`inboxMessagesFetched`, `inboxMessageRead`, `inboxMessageArchived`, `inboxMessageDeleted`) and the A/B test events (`abTestVariantAssigned`, `abTestImpression`, `abTestOpened`, `abTestClicked`). It has no notification-clicked or permission events; use `AbrovaPush.onNotificationTapped` for taps. Property keys are snake_case (for example `error_code`, `error_message`). Use `AbrovaPush.disableAnalytics()` / `AbrovaPush.enableAnalytics()` and the `AbrovaPush.isAnalyticsEnabled` getter to toggle it.

### Android (Kotlin)

<Callout kind="warn" title="Not supported on Android">
Not supported on Android. The native Android SDK has `setAnalyticsHandler`, `enableAnalytics`, `disableAnalytics` and `isAnalyticsEnabled`, but the handler below is never called. Forward the events you need from your `AbrovaPushCallback` (see [Callbacks](/docs/push/callbacks)). The Flutter SDK's handler is not affected: it emits its events from Dart.
</Callout>

#### Setting Up Analytics

```kotlin
import ir.abrova.push.sdk.AbrovaPush
import ir.abrova.push.sdk.AbrovaPushAnalyticsCallback
import ir.abrova.push.sdk.AbrovaPushAnalyticsEvent

AbrovaPush.setAnalyticsHandler(AbrovaPushAnalyticsCallback { event, properties ->
    Log.d("AbrovaPush", "Event: $event")
    Log.d("AbrovaPush", "Properties: $properties")

    // Send to your analytics service
    val params = Bundle().apply {
        properties.forEach { (k, v) -> putString(k, v?.toString()) }
    }
    FirebaseAnalytics.getInstance(context).logEvent("abrovaPush_$event", params)
})
```

#### Handling Specific Events

```kotlin
AbrovaPush.setAnalyticsHandler(AbrovaPushAnalyticsCallback { event, properties ->
    when (event) {
        AbrovaPushAnalyticsEvent.MESSAGE_RECEIVED -> {
            // Track message received
            analytics.track("push_received", properties)
        }
        AbrovaPushAnalyticsEvent.NOTIFICATION_CLICKED -> {
            // Track notification tap
            analytics.track("push_clicked", properties)
        }
        AbrovaPushAnalyticsEvent.CONNECTED -> {
            // Track successful connection
            analytics.track("push_connected")
        }
        AbrovaPushAnalyticsEvent.CONNECTION_ERROR -> {
            // Track connection failures
            FirebaseCrashlytics.getInstance().recordException(
                Exception("Push connection error: ${properties["errorCode"]}")
            )
        }
        else -> { /* ignore */ }
    }
})
```

#### Disable Analytics

```kotlin
// Disable analytics tracking
AbrovaPush.disableAnalytics()

// Check if analytics is enabled
val isEnabled = AbrovaPush.isAnalyticsEnabled()
```

### iOS (Swift)

<Callout kind="warn" title="Analytics Handler Not Available on iOS">
The iOS SDK does not currently expose `setAnalyticsHandler`. To collect SDK telemetry on iOS, conform to `AbrovaPushDelegate` and forward the events you care about — `didReceiveMessage`, `didChangeConnectionState`, `didFailWithDetailedError`, `didStartReconnecting`, `didTapNotification`, `didReceiveNotificationAction` — to your analytics provider directly. See the [Callbacks](/docs/push/callbacks) page for the full delegate surface.
</Callout>

```swift
import AbrovaPush

class PushAnalyticsForwarder: NSObject, AbrovaPushDelegate {
    func abrovaPush(_ abrovaPush: AbrovaPush, didReceiveMessage message: AbrovaPushMessage) {
        Analytics.logEvent("push_received", parameters: [
            "messageId": message.messageId ?? "",
            "title": message.title,
        ])
    }

    func abrovaPush(_ abrovaPush: AbrovaPush, didTapNotification message: AbrovaPushMessage) {
        Analytics.logEvent("push_clicked", parameters: [
            "messageId": message.messageId ?? "",
        ])
    }

    func abrovaPush(_ abrovaPush: AbrovaPush, didFailWithDetailedError error: AbrovaPushError) {
        Analytics.logEvent("push_error", parameters: [
            "errorCode": error.code,
            "errorMessage": error.message,
        ])
    }

    func abrovaPush(_ abrovaPush: AbrovaPush, didChangeConnectionState connected: Bool) {
        Analytics.logEvent(connected ? "push_connected" : "push_disconnected", parameters: nil)
    }
}

// `delegate` is a weak reference: keep the forwarder alive yourself
let forwarder = PushAnalyticsForwarder()
AbrovaPush.shared.delegate = forwarder
```

### React Native

<Callout kind="warn" title="Analytics Handler Not Available in React Native">
The React Native SDK (`abrova-push-react-native`) does not expose `setAnalyticsHandler`. Forward the events you need from its listeners (for example `onMessage`, `onNotificationTapped`, `onConnectionState`, `onDetailedError`) to your analytics provider directly.
</Callout>

### Web

#### Setting Up Analytics

```typescript
import AbrovaPush, { AbrovaPushAnalyticsEvent } from '@abrova/push-web';

const abrovaPush = new AbrovaPush({
  apiKey: 'ab_live_your_api_key',
});

// Set up analytics handler
abrovaPush.setAnalyticsHandler((event, properties) => {
  console.log('Analytics:', event, properties);

  // Send to your analytics service (Google Analytics, Mixpanel, etc.)
  gtag('event', `abrovaPush_${event}`, properties);
});
```

#### Handling Specific Events

```typescript
abrovaPush.setAnalyticsHandler((event, properties) => {
  switch (event) {
    case AbrovaPushAnalyticsEvent.SDK_INITIALIZED:
      // SDK was initialized
      analytics.track('push_sdk_init', properties);
      break;

    case AbrovaPushAnalyticsEvent.DEVICE_REGISTERED:
      // Device registered successfully
      analytics.track('push_registered', {
        deviceId: properties?.deviceId,
        userId: properties?.userId,
      });
      break;

    case AbrovaPushAnalyticsEvent.MESSAGE_RECEIVED:
      // Push message received
      analytics.track('push_received', {
        messageId: properties?.messageId,
        title: properties?.title,
        silent: properties?.silent,
      });
      break;

    case AbrovaPushAnalyticsEvent.MESSAGE_DISPLAYED:
      // Notification was shown
      analytics.track('push_displayed', properties);
      break;

    case AbrovaPushAnalyticsEvent.NOTIFICATION_CLICKED:
      // User tapped notification
      analytics.track('push_clicked', {
        messageId: properties?.messageId,
        action: properties?.action,
      });
      break;

    case AbrovaPushAnalyticsEvent.ACTION_CLICKED:
      // User tapped action button
      analytics.track('push_action', {
        actionId: properties?.actionId,
        messageId: properties?.messageId,
      });
      break;

    case AbrovaPushAnalyticsEvent.CONNECTED:
      // Connected
      analytics.track('push_connected');
      break;

    case AbrovaPushAnalyticsEvent.DISCONNECTED:
      // Disconnected
      analytics.track('push_disconnected');
      break;

    case AbrovaPushAnalyticsEvent.CONNECTION_ERROR:
      // Connection error occurred
      analytics.track('push_error', {
        errorCode: properties?.errorCode,
        errorMessage: properties?.errorMessage,
      });
      break;

    case AbrovaPushAnalyticsEvent.RETRY_STARTED:
      // Reconnection attempt
      analytics.track('push_retry', {
        attempt: properties?.retryAttempt,
      });
      break;

    case AbrovaPushAnalyticsEvent.TOPIC_SUBSCRIBED:
      // Topic subscribed
      analytics.track('push_topic_sub', { topic: properties?.topic });
      break;

    case AbrovaPushAnalyticsEvent.PERMISSION_GRANTED:
      // User granted notification permission
      analytics.track('push_permission_granted');
      break;

    case AbrovaPushAnalyticsEvent.PERMISSION_DENIED:
      // User denied permission
      analytics.track('push_permission_denied');
      break;
  }
});
```

#### Disable Analytics

```typescript
// Disable analytics tracking
abrovaPush.disableAnalytics();

// Check if analytics is enabled
const isEnabled = abrovaPush.isAnalyticsEnabled();
```

### Available Events

These are the events of the Web SDK (`AbrovaPushAnalyticsEvent.X`, string values in camelCase). The Android enum has the same names, but analytics events are not supported on Android (see above). Property names below are those sent by the Web SDK. The Flutter event set differs (see above).

<div>
  <table>
    <thead>
      <tr>
        <th>Event</th>
        <th>Description</th>
        <th>Properties</th>
      </tr>
    </thead>
    <tbody>
      <tr>
        <td>SDK_INITIALIZED</td>
        <td>SDK was initialized</td>
        <td>-</td>
      </tr>
      <tr>
        <td>DEVICE_REGISTERED</td>
        <td>Device registered successfully</td>
        <td>deviceId, userId</td>
      </tr>
      <tr>
        <td>DEVICE_UNREGISTERED</td>
        <td>Device was unregistered</td>
        <td>deviceId</td>
      </tr>
      <tr>
        <td>MESSAGE_RECEIVED</td>
        <td>Push message received</td>
        <td>messageId, title, silent, hasImage</td>
      </tr>
      <tr>
        <td>MESSAGE_DISPLAYED</td>
        <td>Notification was shown to user</td>
        <td>messageId, title</td>
      </tr>
      <tr>
        <td>NOTIFICATION_CLICKED</td>
        <td>User tapped notification</td>
        <td>messageId, title, action</td>
      </tr>
      <tr>
        <td>ACTION_CLICKED</td>
        <td>User tapped action button</td>
        <td>actionId, messageId</td>
      </tr>
      <tr>
        <td>CONNECTED</td>
        <td>Connected successfully</td>
        <td>-</td>
      </tr>
      <tr>
        <td>DISCONNECTED</td>
        <td>Disconnected</td>
        <td>-</td>
      </tr>
      <tr>
        <td>CONNECTION_ERROR</td>
        <td>Connection error occurred</td>
        <td>errorCode, errorMessage, details</td>
      </tr>
      <tr>
        <td>RETRY_STARTED</td>
        <td>Reconnection attempt started</td>
        <td>retryAttempt, nextRetryMs</td>
      </tr>
      <tr>
        <td>TOPIC_SUBSCRIBED</td>
        <td>Subscribed to topic</td>
        <td>topic</td>
      </tr>
      <tr>
        <td>TOPIC_UNSUBSCRIBED</td>
        <td>Unsubscribed from topic</td>
        <td>topic</td>
      </tr>
      <tr>
        <td>NETWORK_STATE_CHANGED</td>
        <td>Network state changed</td>
        <td>isAvailable, networkType</td>
      </tr>
      <tr>
        <td>APP_STATE_CHANGED</td>
        <td>App visibility changed</td>
        <td>isVisible, visibilityState</td>
      </tr>
      <tr>
        <td>PERMISSION_REQUESTED</td>
        <td>Permission prompt shown</td>
        <td>-</td>
      </tr>
      <tr>
        <td>PERMISSION_GRANTED</td>
        <td>User granted permission</td>
        <td>-</td>
      </tr>
      <tr>
        <td>PERMISSION_DENIED</td>
        <td>User denied permission</td>
        <td>-</td>
      </tr>
    </tbody>
  </table>
</div>

### Integration Examples

#### Google Analytics 4

```typescript
abrovaPush.setAnalyticsHandler((event, properties) => {
  gtag('event', `abrovaPush_${event}`, {
    ...properties,
    send_to: 'GA_MEASUREMENT_ID',
  });
});
```

#### Mixpanel

```typescript
abrovaPush.setAnalyticsHandler((event, properties) => {
  mixpanel.track(`AbrovaPush: ${event}`, properties);
});
```

#### Amplitude

```typescript
abrovaPush.setAnalyticsHandler((event, properties) => {
  amplitude.track(`abrovaPush_${event}`, properties);
});
```

- Topics: https://abrova.ir/en/docs/push/topics

Subscribe to topics for targeted group messaging.

<H2 id="what-are-topics" step={1}>What are Topics?</H2>

Topics allow you to send messages to groups of devices that have subscribed to a specific topic. Useful for:

- **News categories** — sports, tech, entertainment
- **User preferences** — promotions, updates, alerts
- **Geographic targeting** — cities, regions, stores
- **App features** — beta users, premium members

<H2 id="subscribe-to-topics" step={2}>Subscribe to Topics</H2>

#### Flutter

```dart
// Subscribe to a single topic
await AbrovaPush.subscribeTopic('news');
await AbrovaPush.subscribeTopic('promotions');
await AbrovaPush.subscribeTopic('sports');

// Subscribe to several topics: call subscribeTopic once per topic
for (final topic in ['tech', 'gaming', 'movies']) {
  await AbrovaPush.subscribeTopic(topic);
}
```

#### React Native

```typescript
// Subscribe to a topic
await AbrovaPush.subscribeTopic('news');
await AbrovaPush.subscribeTopic('promotions');
```

#### Android (Kotlin)

```kotlin
// Subscribe to a topic
AbrovaPush.subscribeTopic("news")
AbrovaPush.subscribeTopic("promotions")
AbrovaPush.subscribeTopic("sports")
```

#### iOS (Swift)

```swift
// Subscribe to a topic
AbrovaPush.shared.subscribeTopic("news")
AbrovaPush.shared.subscribeTopic("promotions")
AbrovaPush.shared.subscribeTopic("sports")
```

#### Web

```typescript
// Subscribe to a topic
await abrovaPush.subscribeTopic('news');
await abrovaPush.subscribeTopic('promotions');
```

<H2 id="unsubscribe-from-topics" step={3}>Unsubscribe from Topics</H2>

#### Flutter

```dart
// Unsubscribe from a single topic
await AbrovaPush.unsubscribeTopic('promotions');

// Unsubscribe from several topics: call unsubscribeTopic once per topic
for (final topic in ['sports', 'gaming']) {
  await AbrovaPush.unsubscribeTopic(topic);
}
```

#### React Native

```typescript
await AbrovaPush.unsubscribeTopic('promotions');
```

#### Android (Kotlin)

```kotlin
// Unsubscribe from a single topic
AbrovaPush.unsubscribeTopic("promotions")
```

#### iOS (Swift)

```swift
// Unsubscribe from a single topic
AbrovaPush.shared.unsubscribeTopic("promotions")
```

#### Web

```typescript
await abrovaPush.unsubscribeTopic('promotions');
```

<H2 id="get-subscribed-topics" step={4}>Get Subscribed Topics</H2>

The client SDKs do not expose a method to list a device's subscribed topics. Keep track of the topics your app subscribes to (for example in local storage), or open a device's profile in Abrova Console (Abrova Push → **Devices**) to see its topics. On the server, segment previews (`abrovaPush.segments.preview()`) include each matching device's `topics`, and a segment filter on the `topics` field targets subscribers of a topic.

<H2 id="topic-naming-rules" step={5}>Topic Naming Rules</H2>

Topic names aren't validated by the server, so stick to these conventions:

- Use lowercase letters, numbers, and underscores
- Avoid spaces, commas and the characters `/`, `#`, `+` in topic names.
- Topic names are case-sensitive: `News` and `news` are different topics
- Examples: `news`, `sports_updates`, `store_123`

- Error handling: https://abrova.ir/en/docs/push/errors

Handle errors gracefully with detailed error codes. All SDKs use standardized numeric error codes for consistent error handling across platforms.

<H2 id="connection-errors-1000-1099" step={1}>Connection Errors (1000-1099)</H2>

<ConfigTable
  headers={['Code', 'Name', 'Description']}
  rows={[
    ['1000', 'CONNECTION_FAILED', 'Failed to connect to server'],
    ['1001', 'CONNECTION_TIMEOUT', 'Connection timed out'],
    ['1002', 'CONNECTION_LOST', 'Connection to server was lost'],
    ['1003', 'CONNECTION_REFUSED', 'Connection was refused by server'],
    ['1004', 'AUTHENTICATION_FAILED', 'Invalid credentials or API key'],
    ['1005', 'SSL_ERROR', 'SSL/TLS handshake failed'],
    ['1006', 'BROKER_UNAVAILABLE', 'Server is unavailable'],
  ]}
/>

<H2 id="subscription-errors-1100-1199" step={2}>Subscription Errors (1100-1199)</H2>

<ConfigTable
  headers={['Code', 'Name', 'Description']}
  rows={[
    ['1100', 'SUBSCRIPTION_FAILED', 'Failed to subscribe to topic'],
    ['1101', 'UNSUBSCRIPTION_FAILED', 'Failed to unsubscribe from topic'],
    ['1102', 'INVALID_TOPIC', 'Invalid topic format'],
  ]}
/>

<H2 id="message-errors-1200-1299" step={3}>Message Errors (1200-1299)</H2>

<ConfigTable
  headers={['Code', 'Name', 'Description']}
  rows={[
    ['1200', 'MESSAGE_DELIVERY_FAILED', 'Failed to deliver message'],
    ['1201', 'MESSAGE_PARSE_ERROR', 'Failed to parse message payload'],
    ['1202', 'MESSAGE_TIMEOUT', 'Message delivery timed out'],
  ]}
/>

#### Configuration Errors (1300-1399)

<ConfigTable
  headers={['Code', 'Name', 'Description']}
  rows={[
    ['1300', 'INVALID_CONFIG', 'Invalid configuration'],
    ['1301', 'MISSING_API_KEY', 'API key is missing'],
    ['1302', 'MISSING_SERVER_URL', 'Server URL is missing'],
    ['1303', 'INVALID_CREDENTIALS', 'Invalid connection credentials'],
    ['1304', 'CONFIGURATION_FAILED', 'Failed to fetch configuration from server (Android, Flutter)'],
  ]}
/>

<H2 id="registration-errors-1400-1499" step={4}>Registration Errors (1400-1499)</H2>

<ConfigTable
  headers={['Code', 'Name', 'Description']}
  rows={[
    ['1400', 'REGISTRATION_FAILED', 'Device registration failed'],
    ['1401', 'DEVICE_ID_GENERATION_FAILED', 'Failed to generate device ID'],
    ['1402', 'SERVER_ERROR', 'Server returned an error'],
    ['1403', 'NETWORK_ERROR', 'Network request failed'],
  ]}
/>

#### State Errors (1500-1599)

<ConfigTable
  headers={['Code', 'Name', 'Description']}
  rows={[
    ['1500', 'NOT_INITIALIZED', 'SDK is not initialized'],
    ['1501', 'NOT_CONNECTED', 'Not connected to server'],
    ['1502', 'ALREADY_CONNECTED', 'Already connected to server'],
    ['1503', 'SERVICE_NOT_RUNNING', 'Background service (Web: service worker) is not running'],
    ['9999', 'UNKNOWN_ERROR', 'An unknown error occurred'],
  ]}
/>

<H2 id="permission-errors-1600-1699" step={5}>Permission Errors (1600-1699)</H2>

Web SDK only. Android and Flutter define no 1600 codes; on iOS, 1600 / 1601 are the A/B testing errors `variantNotFound` / `testNotFound`.

<ConfigTable
  headers={['Code', 'Name', 'Description']}
  rows={[
    ['1600', 'PERMISSION_DENIED', 'Notification permission denied'],
    ['1601', 'PERMISSION_DISMISSED', 'User dismissed permission prompt'],
  ]}
/>

<H2 id="flutter" step={6}>Flutter</H2>

```dart
AbrovaPush.onDetailedError((error) async {
  switch (error.errorCode) {
    case AbrovaPushErrorCode.connectionFailed:
      // Show "Connection failed" message
      // SDK will auto-retry
      break;

    case AbrovaPushErrorCode.authenticationFailed:
      // Invalid API key - check dashboard
      break;

    case AbrovaPushErrorCode.registrationFailed:
      // Retry registration
      await AbrovaPush.register(userId: userId);
      break;

    case AbrovaPushErrorCode.subscriptionFailed:
      // Topic subscription failed
      break;

    case AbrovaPushErrorCode.networkError:
      // Show offline indicator
      // SDK will reconnect when network returns
      break;

    default:
      print('Error: ${error.message}');
  }
});
```

<H2 id="web" step={7}>Web</H2>

```typescript
import { AbrovaPushErrorCode } from '@abrova/push-web';

abrovaPush.onDetailedError((error) => {
  switch (error.code) {
    case AbrovaPushErrorCode.CONNECTION_FAILED:
      // Show "Connection failed" message — SDK auto-retries
      break;

    case AbrovaPushErrorCode.AUTHENTICATION_FAILED:
      // Invalid API key — check dashboard
      break;

    case AbrovaPushErrorCode.REGISTRATION_FAILED:
      // Retry registration
      abrovaPush.register({ userId });
      break;

    case AbrovaPushErrorCode.SUBSCRIPTION_FAILED:
      // Topic subscription failed
      break;

    case AbrovaPushErrorCode.NETWORK_ERROR:
      // Show offline indicator — SDK reconnects when network returns
      break;

    case AbrovaPushErrorCode.PERMISSION_DENIED:
      // User denied notification permission
      showPermissionRequestUI();
      break;

    default:
      console.error('Error:', error.code, error.message, error.details);
  }
});
```

<H2 id="simple-error-handler" step={8}>Simple Error Handler</H2>

For projects that just need to log errors without branching:

```dart
AbrovaPush.onError((error) {
  // Log to crash reporting
  FirebaseCrashlytics.instance.recordError(
    Exception(error),
    null,
    reason: 'AbrovaPush error',
  );
});
```

<H2 id="best-practices" step={9}>Best Practices</H2>

<BestPracticeList items={[
  ['Always Set Error Handlers First', 'Register onError / onDetailedError before calling any other SDK methods'],
  ['Log to Crash Reporting', 'Forward errors to Crashlytics / Sentry for debugging production issues'],
  ['Show User-Friendly Messages', 'Translate technical error codes into messages users can understand'],
  ['Don\'t Block the UI', 'The SDK auto-retries most errors — let it work'],
  ['Handle networkError Gracefully', 'Show an offline indicator instead of treating it as a hard failure'],
]} />

- Send push: https://abrova.ir/en/docs/push/send

Send push notifications from your server using the REST API.

<Callout kind="note" title="Server-Side Only">
This REST API must only be used from your backend server, **never** from mobile apps or client-side code. The server secret can be extracted from mobile apps by attackers, which would allow them to send unauthorized push notifications.

**For mobile apps:** use the native SDKs (iOS, Android, Flutter, React Native) which only support *receiving* notifications. To send notifications from your app, make a request to your own backend server, which then calls the AbrovaPush API.
</Callout>

<H2 id="authentication" step={1}>Authentication</H2>

All API requests require both your **API Key** and **Server Secret** in the headers.

```bash
curl -H "x-api-key: ab_live_your_api_key" \
     -H "x-server-secret: ab_srv_your_server_secret" \
  https://push-api.abrova.ir/push/...
```

#### Required Headers

<ConfigTable rows={[
  ['x-api-key', 'String', 'Yes', 'Your project API key (ab_live_xxx)'],
  ['x-server-secret', 'String', 'Yes', 'Your server secret (ab_srv_xxx) — required for all send operations'],
]} />

<Callout kind="note" title="IP Whitelist (Optional)">
For additional security, you can configure an IP whitelist in your project settings. When enabled, only requests from whitelisted IP addresses can use the server secret.
</Callout>

<H2 id="send-notification" step={2}>Send Notification</H2>

The REST API exposes six send endpoints, one per audience shape: a single user (all their devices), a single device, multiple devices by ID, a topic, a segment, or every registered device.

#### Send to User

Send to all devices of a user.

```bash
curl -X POST https://push-api.abrova.ir/push/send-to-user \
  -H "x-api-key: ab_live_your_api_key" \
  -H "x-server-secret: ab_srv_your_server_secret" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "user_123",
    "title": "Hello!",
    "body": "You have a new message",
    "data": {
      "messageId": "msg_456",
      "action": "open_chat"
    }
  }'
```

#### Send to Device

Send to a specific device.

```bash
curl -X POST https://push-api.abrova.ir/push/send \
  -H "x-api-key: ab_live_your_api_key" \
  -H "x-server-secret: ab_srv_your_server_secret" \
  -H "Content-Type: application/json" \
  -d '{
    "deviceId": "dev_abc123def456",
    "title": "Order Update",
    "body": "Your order has shipped!",
    "data": {
      "orderId": "ORD-789"
    }
  }'
```

#### Send to Devices

Send to multiple devices by ID.

```bash
curl -X POST https://push-api.abrova.ir/push/send-to-devices \
  -H "x-api-key: ab_live_your_api_key" \
  -H "x-server-secret: ab_srv_your_server_secret" \
  -H "Content-Type: application/json" \
  -d '{
    "deviceIds": ["dev_abc123", "dev_def456", "dev_ghi789"],
    "title": "Batch Notification",
    "body": "This goes to multiple devices",
    "data": {
      "campaign": "promo_2024"
    }
  }'
```

#### Send to Topic

Send to every subscriber of a topic.

```bash
curl -X POST https://push-api.abrova.ir/push/send-to-topic \
  -H "x-api-key: ab_live_your_api_key" \
  -H "x-server-secret: ab_srv_your_server_secret" \
  -H "Content-Type: application/json" \
  -d '{
    "topic": "sports",
    "title": "Breaking News",
    "body": "Your team just won!"
  }'
```

#### Send to Segment

Send to every device in a saved [segment](/docs/push/segments).

```bash
curl -X POST https://push-api.abrova.ir/push/send-to-segment \
  -H "x-api-key: ab_live_your_api_key" \
  -H "x-server-secret: ab_srv_your_server_secret" \
  -H "Content-Type: application/json" \
  -d '{
    "segmentId": "segment-uuid-123",
    "title": "Just for you",
    "body": "A deal for our most active users"
  }'
```

#### Broadcast

Send to every registered device.

```bash
curl -X POST https://push-api.abrova.ir/push/broadcast \
  -H "x-api-key: ab_live_your_api_key" \
  -H "x-server-secret: ab_srv_your_server_secret" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "App Update",
    "body": "New features available! Update now."
  }'
```

<H2 id="request-body" step={3}>Request Body</H2>

<ConfigTable rows={[
  ['title', 'string', 'Conditional', 'Notification title (required unless templateId is set)'],
  ['body', 'string', 'Conditional', 'Notification body text (required unless templateId is set)'],
  ['templateId', 'string', 'No', 'Render a saved template instead of title/body'],
  ['templateVariables', 'object', 'No', 'Variables substituted into the template'],
  ['locale', 'string', 'No', 'Template locale to render (e.g. en, fa)'],
  ['data', 'object', 'No', 'Custom data payload delivered to the client as-is'],
  ['userId', 'string', 'Conditional', 'Target user ID (required for send-to-user)'],
  ['deviceId', 'string', 'Conditional', 'Target device ID (required for /push/send)'],
  ['deviceIds', 'string[]', 'Conditional', 'Array of device IDs (required for send-to-devices)'],
  ['topic', 'string', 'Conditional', 'Target topic name (required for send-to-topic)'],
  ['segmentId', 'string', 'Conditional', 'Target segment ID (required for send-to-segment)'],
  ['appIdentifier', 'string', 'No', 'Only deliver to devices of this app (bundle ID / package name). Not accepted by send-to-devices'],
]} />

Unknown body fields are rejected with `400 Bad Request`.

For rich notifications with images, action buttons, deep links, and more, see [Rich Notifications](/docs/push/rich).

<H2 id="response" step={4}>Response</H2>

Successful sends return the device counts, the generated `messageId` (a UUID) and a billing summary:

```json
{
  "success": 5,
  "failed": 0,
  "messageId": "3f1c2a9e-8b7d-4e21-9a0c-5d6e7f8a9b0c",
  "billing": {
    "messagesCharged": 5,
    "remaining": 99995
  }
}
```

`success` and `failed` are device counts. `billing.remaining` is `-1` when nothing was charged or the remaining quota is unknown.

#### No Recipients

When the target had zero registered devices the send is **not** treated as a delivery failure. The response carries `reason: "no_recipients"` and both counts are zero so your server can distinguish the two cases without polling the message:

```json
{
  "success": 0,
  "failed": 0,
  "messageId": "3f1c2a9e-8b7d-4e21-9a0c-5d6e7f8a9b0c",
  "reason": "no_recipients",
  "billing": { "messagesCharged": 0, "remaining": -1 }
}
```

The message is recorded with `status: "no_recipients"` and the webhook fires `message.no_recipients` (not `message.failed`).

<H2 id="error-responses" step={5}>Error Responses</H2>

#### Missing or Invalid Credentials

```json
{
  "statusCode": 401,
  "message": "API key is required (x-api-key header)"
}
```

#### Missing Server Secret

```json
{
  "statusCode": 401,
  "message": "Server secret is required for this operation (x-server-secret header). Server secret can only be used from your backend server, never from client apps."
}
```

#### IP Not in Whitelist

```json
{
  "statusCode": 403,
  "message": "Access denied: Your IP address (x.x.x.x) is not in the allowed list. Please add your server IP to the allowed IPs in Abrova Console (Project settings)."
}
```

- Node.js guide: https://abrova.ir/en/docs/push/nodejs-guide

Server-side SDK for sending push notifications, managing inbox, devices, and more from your Node.js backend. For the per-platform SDK reference page, see [Node.js SDK reference](/docs/push/nodejs).

<H2 id="installation" step={1}>Installation</H2>

The SDK installs from Abrova Center in two steps.

1. Point the `@abrova` scope at Abrova Center in your project's `.npmrc`:

```
# .npmrc (in your project root)
@abrova:registry=https://center.abrova.ir/api/packages/abrova/npm/
```

2. Install the package:

```bash
npm install @abrova/push-node
```

#### Initialize

```typescript
import { AbrovaPush } from '@abrova/push-node';

const abrovaPush = new AbrovaPush({
  apiKey: process.env.ABROVA_API_KEY,             // ab_live_xxx
  serverSecret: process.env.ABROVA_SERVER_SECRET, // ab_srv_xxx (required, server only)
});
```

#### Quick Example

```typescript
await abrovaPush.push.sendToUser({
  userId: 'user-123',
  title: 'Order Shipped',
  body: 'Your order #1234 has been shipped!',
  data: { orderId: '1234' },
});
```

#### Error Handling

```typescript
import { AbrovaPush, AbrovaPushError } from '@abrova/push-node';

try {
  await abrovaPush.push.sendToUser({
    userId: 'user-123',
    title: 'Hello',
    body: 'World',
  });
} catch (error) {
  if (error instanceof AbrovaPushError) {
    // error.statusCode, error.message
  }
}
```

<H2 id="security-authentication" step={2}>Security — Authentication</H2>

Server-side operations require **both API Key and Server Secret** for authentication. This ensures that only your backend server can perform privileged operations.

#### Two Credential Types

- **API Key** (`ab_live_xxx`) — Used by client SDKs (iOS, Android, Flutter, Web). Can be embedded in mobile/web apps.
- **Server Secret** (`ab_srv_xxx`) — **Required** for all server-side operations. Used by Node.js SDK and direct REST API calls from your backend. **Never expose this in client-side code!**

#### Why Both Are Required

- API Key alone can be extracted from mobile apps
- Server Secret ensures the request comes from your trusted backend
- Prevents unauthorized server-side operations even if API key leaks
- Simplifies security — no need to decide which operations need extra protection

#### Where to Find Your Credentials

1. Go to **Abrova Console**
2. Create a new project (add the **Server / API** platform to get a server secret) or select an existing one
3. The **API Key** and **Server Secret** are shown in full at project creation
4. **Save both immediately** — they are only shown once!
5. If lost (or never created), regenerate / generate them from **Project Settings → Credentials**

#### Environment Variables

```bash
# .env file
ABROVA_API_KEY=ab_live_abc123def456...
ABROVA_SERVER_SECRET=ab_srv_xyz789...
```

```typescript
import { AbrovaPush } from '@abrova/push-node';

const abrovaPush = new AbrovaPush({
  apiKey: process.env.ABROVA_API_KEY,
  serverSecret: process.env.ABROVA_SERVER_SECRET,
});
```

#### Example — Order Update Notification

```typescript
// services/notification.service.ts
import { AbrovaPush } from '@abrova/push-node';

const abrovaPush = new AbrovaPush({
  apiKey: process.env.ABROVA_API_KEY,
  serverSecret: process.env.ABROVA_SERVER_SECRET,
});

export async function notifyOrderShipped(userId: string, orderId: string, trackingUrl: string) {
  // Send push notification
  await abrovaPush.push.sendToUser({
    userId,
    title: 'Order Shipped!',
    body: `Your order #${orderId} is on its way`,
    data: { orderId, trackingUrl },
    deepLink: `myapp://orders/${orderId}`,
  });

  // Also add to inbox for permanent record
  await abrovaPush.inbox.sendToUser({
    userId,
    content: {
      title: 'Order Shipped',
      body: `Your order #${orderId} has been shipped. Track your package.`,
      deepLink: `myapp://orders/${orderId}`,
    },
    category: 'orders',
  });
}

// Usage in your order controller
app.post('/orders/:orderId/ship', async (req, res) => {
  const { orderId } = req.params;
  const order = await Order.findById(orderId);

  order.status = 'shipped';
  order.trackingUrl = req.body.trackingUrl;
  await order.save();

  await notifyOrderShipped(order.userId, orderId, order.trackingUrl);

  res.json({ success: true });
});
```

#### Client vs Server Authentication

<ConfigTable rows={[
  ['iOS / Android / Flutter', 'Mobile SDK', '-', 'API Key only'],
  ['Web Browser', 'Web SDK', '-', 'API Key only'],
  ['Node.js Backend', 'Node.js SDK', '-', 'API Key + Server Secret'],
  ['Direct REST API', 'curl / fetch / axios', '-', 'API Key + Server Secret'],
]} />

<H2 id="push-send-notifications" step={3}>Push — Send Notifications</H2>

#### Send to User

```typescript
await abrovaPush.push.sendToUser({
  userId: 'user-123',
  title: 'New Message',
  body: 'You have a new message from John',
  data: { chatId: 'chat-456' },
  deepLink: 'myapp://chat/456',
});
```

#### Send to Device

```typescript
await abrovaPush.push.sendToDevice({
  deviceId: 'device-uuid',
  title: 'Welcome!',
  body: 'Thanks for installing our app',
});
```

#### Send to Multiple Devices

```typescript
await abrovaPush.push.sendToDevices({
  deviceIds: ['device-1', 'device-2', 'device-3'],
  title: 'Update Available',
  body: 'A new version is available',
});
```

#### Send to Topic

```typescript
await abrovaPush.push.sendToTopic({
  topic: 'promotions',
  title: 'Flash Sale!',
  body: '50% off everything today only',
  imageUrl: 'https://example.com/sale.jpg',
});
```

#### Send to Segment

```typescript
await abrovaPush.push.sendToSegment({
  segmentId: 'vip-customers-segment-id',
  title: 'Exclusive Offer',
  body: 'Just for our VIP customers',
});
```

#### Broadcast

```typescript
await abrovaPush.push.broadcast({
  title: 'App Update',
  body: 'Check out the new features!',
});
```

#### Rich Notifications

```typescript
await abrovaPush.push.sendToUser({
  userId: 'user-123',
  title: 'New Product',
  body: 'Check out our latest arrival',
  imageUrl: 'https://example.com/product.jpg',
  actions: [
    { id: 'buy', title: 'Buy Now', action: 'BUY_PRODUCT' },
    { id: 'later', title: 'Save for Later' },
  ],
  deepLink: 'myapp://product/123',
  badge: 1,
  sound: 'notification.wav',
  priority: 'high',
  ttl: 3600, // 1 hour
});
```

#### Using Templates

```typescript
await abrovaPush.push.sendToUser({
  userId: 'user-123',
  templateId: 'order-shipped-template-id',
  templateVariables: {
    orderNumber: '#1234',
    trackingUrl: 'https://track.example.com/1234',
  },
});
```

#### App Identifier (Multi-app Targeting)

```typescript
// Send only to a specific app on the device
await abrovaPush.push.sendToUser({
  userId: 'user-123',
  title: 'New Order',
  body: 'Your order is ready',
  appIdentifier: 'com.myshop.app', // only this app receives it
});
```

`appIdentifier` If your project has multiple apps (e.g. a shopping app and a chat app), use appIdentifier to target a specific app. This is the bundle ID / package name of the app (e.g. com.myapp.ios).

#### Response

```typescript
const result = await abrovaPush.push.sendToUser({...});

console.log(result);
// {
//   success: 3,
//   failed: 0,
//   messageId: '6f1c…',  // use with abrovaPush.receipts
//   billing: {
//     messagesCharged: 3,   // messages counted for this send
//     remaining: 9997       // free messages left this month
//   }
// }
```

<H2 id="inbox" step={4}>Inbox</H2>

<Callout kind="note" title="Signed user tokens">
The read / update calls (`getMessages`, `getMessage`, `updateStatus`, `updateMultiple`, `markAllRead`, `delete`) use the inbox routes the client SDKs call. If the project turns on **Require signed user tokens for the inbox** (Project Settings → Abrova Push), those routes need a user's `x-user-token`, which this SDK does not send, so they return `401` (`token_required`) for user-owned messages. The `send*` / `broadcast` calls are not affected.
</Callout>

```typescript
// Send to single user
await abrovaPush.inbox.sendToUser({
  userId: 'user-123',
  content: {
    title: 'Welcome!',
    body: 'Thanks for joining us. Here are some tips to get started.',
    imageUrl: 'https://example.com/welcome.jpg',
    deepLink: 'myapp://onboarding',
  },
  category: 'onboarding',
  expiresAt: '2025-12-31T23:59:59Z',
});

// Send to multiple users
await abrovaPush.inbox.sendToUsers({
  userIds: ['user-1', 'user-2', 'user-3'],
  content: { title: 'New Feature', body: 'Check out our latest feature' },
});

// Send to device
await abrovaPush.inbox.sendToDevice({
  deviceId: 'device-uuid',
  content: { title: 'Device-specific Message', body: 'This message is for this device only' },
});

// Broadcast
await abrovaPush.inbox.broadcast({
  content: { title: 'Holiday Sale', body: 'Up to 70% off!' },
  category: 'promotions',
  expiresAt: '2025-01-05T23:59:59Z',
});

// Target specific app
await abrovaPush.inbox.sendToUser({
  userId: 'user-123',
  appIdentifier: 'com.myshop.app',
  content: { title: 'Order Shipped', body: 'Your order is on its way!' },
  category: 'orders',
});

// Get user's inbox — resolves to { messages, total, unreadCount }
const inbox = await abrovaPush.inbox.getMessages({
  userId: 'user-123',
  status: 'unread',
  limit: 20,
  offset: 0,
});

// Mark single message as read
await abrovaPush.inbox.updateStatus('message-id', 'read');

// Mark multiple messages as read
await abrovaPush.inbox.updateMultiple(
  ['msg-1', 'msg-2', 'msg-3'],
  'read'
);

// Mark all as read for a user
await abrovaPush.inbox.markAllRead({ userId: 'user-123' });
```

<H2 id="devices" step={5}>Devices</H2>

```typescript
// List devices
const devices = await abrovaPush.devices.list();

// Subscribe / unsubscribe to topic
await abrovaPush.devices.subscribeTopic('device-uuid', 'news');
await abrovaPush.devices.unsubscribeTopic('device-uuid', 'promotions');

// Associate / clear user
await abrovaPush.devices.setUserId('device-uuid', 'user-123');
await abrovaPush.devices.clearUserId('device-uuid');

// Delete devices
await abrovaPush.devices.delete('device-uuid');
await abrovaPush.devices.bulkDelete(['device-1', 'device-2', 'device-3']);

// Paginated, filtered list (includes inactive devices unless isActive is set)
const { items, total } = await abrovaPush.devices.listPage({
  platform: 'ios',
  isActive: true,
  page: 1,
  limit: 50,
});

// Values you can filter on (app versions, SDK versions, failure reasons)
const options = await abrovaPush.devices.filterOptions();

// Stop sending to a device but keep its history, and undo it
await abrovaPush.devices.unregister('device-uuid');
await abrovaPush.devices.reactivate('device-uuid');
```

<H2 id="templates" step={6}>Templates</H2>

Reusable notification content with variable substitution.

```typescript
// Create template
const template = await abrovaPush.templates.create({
  name: 'Order Shipped',
  title: 'Your order {{orderNumber}} has shipped!',
  body: 'Track your package: {{trackingUrl}}',
  variables: ['orderNumber', 'trackingUrl'],
  localizations: {
    fa: {
      title: 'سفارش {{orderNumber}} ارسال شد!',
      body: 'پیگیری مرسوله: {{trackingUrl}}',
    },
  },
});

// List
const templates = await abrovaPush.templates.list();

// Render (preview)
const rendered = await abrovaPush.templates.render(
  'template-id',
  { orderNumber: '#1234', trackingUrl: 'https://track.example.com/1234' },
  'en' // locale
);

// Update / Delete / Duplicate
await abrovaPush.templates.update('template-id', {
  body: 'Updated body text with {{variable}}',
});
await abrovaPush.templates.delete('template-id');
const copy = await abrovaPush.templates.duplicate('template-id');
```

<H2 id="segments" step={7}>Segments</H2>

```typescript
// Create segment
const segment = await abrovaPush.segments.create({
  name: 'VIP Customers',
  description: 'Customers with more than 10 orders',
  color: '#FFD700',
  filters: [
    { field: 'metadata.orderCount', operator: 'greater_than', value: 10 },
    { field: 'metadata.tier', operator: 'equals', value: 'gold' },
  ],
});
```

#### Filter Operators

<ConfigTable
  headers={['Operator', 'Description']}
  rows={[
    ['equals / not_equals', 'Exact match / no match'],
    ['contains / not_contains', 'String (or topics) contains / does not contain'],
    ['starts_with', 'String starts with'],
    ['in / not_in', 'Value in / not in array'],
    ['greater_than / greater_than_or_equal', 'Numeric comparison'],
    ['less_than / less_than_or_equal', 'Numeric comparison'],
    ['exists', 'Field is set'],
  ]}
/>

```typescript
// List, get, devices
const segments = await abrovaPush.segments.list();
const segment = await abrovaPush.segments.get('segment-id');
const devices = await abrovaPush.segments.getDevices('segment-id');

// Recalculate
const { deviceCount } = await abrovaPush.segments.recalculate('segment-id');
await abrovaPush.segments.recalculateAll();
```

<H2 id="scheduled-messages" step={8}>Scheduled Messages</H2>

```typescript
// Schedule
const scheduled = await abrovaPush.scheduled.create({
  title: 'Reminder',
  body: "Don't forget to complete your purchase!",
  targetType: 'user',
  targetValue: 'user-123',
  scheduledAt: '2025-02-14T09:00:00Z',
  timezone: 'Asia/Tehran',
});
```

#### Target Types

<ConfigTable rows={[
  ['broadcast', '-', '-', 'Not required (every device). The 0.1.4 SDK type lists `all`, which the API rejects — pass `broadcast` (cast it, e.g. `targetType: \'broadcast\' as any`, until the type is fixed)'],
  ['user', '-', '-', 'targetValue = User ID'],
  ['device', '-', '-', 'targetValue = Device ID'],
  ['topic', '-', '-', 'targetValue = Topic name'],
  ['segment', '-', '-', 'targetValue = Segment ID'],
]} />

```typescript
// List all scheduled messages
const all = await abrovaPush.scheduled.list();

// List pending only
const pending = await abrovaPush.scheduled.listPending();

// Get specific scheduled message
const message = await abrovaPush.scheduled.get('scheduled-id');

// Update scheduled message
await abrovaPush.scheduled.update('scheduled-id', {
  scheduledAt: '2025-02-15T10:00:00Z',
});

// Cancel scheduled message
await abrovaPush.scheduled.cancel('scheduled-id');

// Delete scheduled message
await abrovaPush.scheduled.delete('scheduled-id');
```

<H2 id="webhooks" step={9}>Webhooks</H2>

```typescript
// Create webhook
const webhook = await abrovaPush.webhooks.create({
  name: 'Order Events',
  url: 'https://example.com/webhooks/abrova-push',
  events: [
    'message.sent',
    'message.delivered',
    'message.failed',
  ],
  secret: 'my-webhook-secret',
  maxRetries: 3,
  timeoutMs: 5000,
});
```

#### Available Events

<ConfigTable rows={[
  ['message.sent', '-', '-', 'Message was sent'],
  ['message.delivered', '-', '-', 'Message was delivered to device'],
  ['message.failed', '-', '-', 'Message failed to send'],
  ['message.no_recipients', '-', '-', 'Target had no registered devices'],
  ['device.registered', '-', '-', 'New device registered'],
  ['device.unregistered', '-', '-', 'Device was unregistered'],
  ['device.updated', '-', '-', 'Device was updated'],
]} />

```typescript
// Test, get logs, regenerate secret
await abrovaPush.webhooks.test('webhook-id', 'message.delivered');
const logs = await abrovaPush.webhooks.getLogs('webhook-id', 50);
const { secret } = await abrovaPush.webhooks.regenerateSecret('webhook-id');

// Manage
const webhooks = await abrovaPush.webhooks.list();
await abrovaPush.webhooks.update('webhook-id', {
  events: ['message.delivered', 'message.failed'],
  isActive: true,
});
await abrovaPush.webhooks.delete('webhook-id');
```

<H2 id="analytics" step={10}>Analytics</H2>

```typescript
// Overview stats
const overview = await abrovaPush.analytics.getOverview();

// overview: {
//   totalDevices: 15000,
//   activeDevices: 12500,
//   totalMessages: 50000,
//   totalDelivered: 48500,
//   totalFailed: 500,
//   deliveryRate: 97,
//   platformDistribution: { android: 8000, ios: 6500, web: 500 }
// }

// Get last 30 days of stats
const daily = await abrovaPush.analytics.getDaily(30);

// daily: [
//   { date: '2025-02-01', sent: 1500, delivered: 1450, pending: 20, failed: 30 },
//   { date: '2025-02-02', sent: 1600, delivered: 1550, pending: 10, failed: 40 },
//   ...
// ]

// Get hourly distribution for last 7 days
const hourly = await abrovaPush.analytics.getHourly(7);

// hourly: [
//   { hour: 0, count: 120 },
//   { hour: 1, count: 80 },
//   ...
//   { hour: 23, count: 150 }
// ]

// App-level stats
const stats = await abrovaPush.analytics.getStats();

// stats: {
//   totalDevices: 15000,
//   activeDevices: 12500,
//   androidDevices: 8000,
//   iosDevices: 6500,
//   totalTopics: 25,
//   topics: ['news', 'promotions', 'updates', ...],
//   totalUsers: 10000
// }

// Recent messages
const recent = await abrovaPush.analytics.getRecent(10);
```

#### Delivery receipts

A send's `success` count means the push service *accepted* the notification. Receipts show what happened on each device. See [Delivery Receipts](/docs/push/receipts).

```typescript
const { messageId } = await abrovaPush.push.sendToUser({ userId: 'user-123', title: 'Hi', body: 'Hello' });

// Per device, for one message
const receipts = await abrovaPush.receipts.getForMessage(messageId!);
const stats = await abrovaPush.receipts.getMessageStats(messageId!);

// Receipt log with filters
const { items, total } = await abrovaPush.receipts.list({
  status: 'failed',
  platform: 'android',
  startDate: new Date(Date.now() - 7 * 86400_000),
  page: 1,
  limit: 100,
});

// Delivery analytics (default: last 30 days)
const analytics = await abrovaPush.receipts.analytics({ bucket: 'day' });
console.log(analytics.totals, analytics.byPlatform, analytics.topFailureReasons);
```

- Analytics: https://abrova.ir/en/docs/push/analytics

Track push notification performance with detailed analytics. Every analytics endpoint is available both through the Node.js SDK and the REST API. These endpoints return data for the whole project, so they need the server secret (`x-server-secret`) as well as the API key; the API key alone is refused.

<div>
  <div>
    <p>Total</p>
    <p>Messages sent</p>
  </div>
  <div>
    <p>Delivered</p>
    <p>Successfully</p>
  </div>
  <div>
    <p>Failed</p>
    <p>Delivery failures</p>
  </div>
  <div>
    <p>Rate</p>
    <p>Success %</p>
  </div>
</div>

<H2 id="get-overview" step={1}>Get Overview</H2>

Get overall statistics for your push notifications.

#### Node.js SDK

```typescript
import { AbrovaPush } from '@abrova/push-node';

const abrovaPush = new AbrovaPush({
  apiKey: 'ab_live_your_api_key',
  serverSecret: 'ab_srv_your_server_secret',
});

const overview = await abrovaPush.analytics.getOverview();
```

#### REST API

```bash
curl -X GET "https://push-api.abrova.ir/analytics/overview" \
  -H "x-api-key: ab_live_your_api_key" \
  -H "x-server-secret: ab_srv_your_server_secret"
```

#### Response

```json
{
  "totalMessages": 15420,
  "totalDelivered": 14890,
  "totalFailed": 530,
  "totalPending": 0,
  "totalNoTargets": 12,
  "totalAttempts": 3210,
  "deliveryRate": 97,
  "totalDevices": 2500,
  "activeDevices": 2100,
  "platformDistribution": {
    "android": 1400,
    "ios": 900,
    "web": 200
  }
}
```

<H2 id="daily-statistics" step={2}>Daily Statistics</H2>

Get message statistics broken down by day. `days` defaults to 30 (max 90); days with no sends are returned with zeros. `sent` counts messages (API sends), while `delivered` and `failed` count individual devices.

#### Node.js SDK

```typescript
const daily = await abrovaPush.analytics.getDaily(30);
```

#### REST API

```bash
curl -X GET "https://push-api.abrova.ir/analytics/daily?days=30" \
  -H "x-api-key: ab_live_your_api_key" \
  -H "x-server-secret: ab_srv_your_server_secret"
```

#### Response

```json
[
  {
    "date": "2024-01-15",
    "sent": 12,
    "delivered": 510,
    "pending": 0,
    "failed": 10
  },
  {
    "date": "2024-01-16",
    "sent": 9,
    "delivered": 475,
    "pending": 0,
    "failed": 5
  }
  // ... more days
]
```

<H2 id="message-type-breakdown" step={3}>Message Type Breakdown</H2>

See how messages are distributed by send type (user / device / topic / broadcast). `percentage` is rounded to a whole number.

#### Node.js SDK

```typescript
const messageTypes = await abrovaPush.analytics.getMessageTypes();
```

#### REST API

```bash
curl -X GET "https://push-api.abrova.ir/analytics/message-types" \
  -H "x-api-key: ab_live_your_api_key" \
  -H "x-server-secret: ab_srv_your_server_secret"
```

#### Response

```json
[
  { "type": "user", "count": 8500, "percentage": 55 },
  { "type": "topic", "count": 4200, "percentage": 27 },
  { "type": "broadcast", "count": 2000, "percentage": 13 },
  { "type": "device", "count": 720, "percentage": 5 }
]
```

<H2 id="hourly-distribution" step={4}>Hourly Distribution</H2>

Analyze message distribution by hour of day (UTC). `days` defaults to 7 (max 30); all 24 hours are always returned.

#### Node.js SDK

```typescript
const hourly = await abrovaPush.analytics.getHourly(7);
```

#### REST API

```bash
curl -X GET "https://push-api.abrova.ir/analytics/hourly?days=7" \
  -H "x-api-key: ab_live_your_api_key" \
  -H "x-server-secret: ab_srv_your_server_secret"
```

#### Response

```json
[
  { "hour": 0, "count": 120 },
  { "hour": 1, "count": 85 },
  { "hour": 2, "count": 45 },
  // ...
  { "hour": 12, "count": 650 },
  { "hour": 13, "count": 580 },
  // ...
  { "hour": 23, "count": 180 }
]
```

<H2 id="recent-activity" step={5}>Recent Activity</H2>

Get the most recent messages sent. `limit` defaults to 10 (max 50). Each item is a full message record.

#### Node.js SDK

```typescript
const recent = await abrovaPush.analytics.getRecent(10);
```

#### REST API

```bash
curl -X GET "https://push-api.abrova.ir/analytics/recent?limit=10" \
  -H "x-api-key: ab_live_your_api_key" \
  -H "x-server-secret: ab_srv_your_server_secret"
```

#### Response

```json
[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "type": "user",
    "target": "user_123",
    "title": "New message",
    "body": "You have a new notification",
    "successCount": 2,
    "failedCount": 0,
    "status": "delivered",
    "createdAt": "2024-01-15T10:30:00Z"
  },
  {
    "id": "6fa459ea-ee8a-3ca4-894e-db77e160355e",
    "type": "device",
    "target": "device_abc",
    "title": "Order update",
    "body": "Your order has shipped",
    "successCount": 1,
    "failedCount": 0,
    "status": "delivered",
    "createdAt": "2024-01-15T10:25:00Z"
  }
]
```

- Scheduled: https://abrova.ir/en/docs/push/scheduled

Schedule push notifications for delivery at a specific future time.

<H2 id="use-cases" step={1}>Use Cases</H2>

- **Marketing campaigns** — send at optimal engagement times
- **Event reminders** — notify before appointments
- **Time-sensitive content** — flash sales, limited offers
- **Global audiences** — schedule separate messages for each region's local time

<H2 id="schedule-a-message" step={2}>Schedule a Message</H2>

`scheduledAt` is an ISO 8601 timestamp and must be in the future; it is the exact instant the message is sent. `timezone` is optional (defaults to `UTC`) and is stored with the message for display only — it does not shift `scheduledAt`, so include the offset (or use `Z`) in `scheduledAt` itself. Due messages are picked up once a minute. Only `title`, `body` and `data` are delivered with a scheduled message.

#### Node.js SDK

```typescript
import { AbrovaPush } from '@abrova/push-node';

const abrovaPush = new AbrovaPush({
  apiKey: 'ab_live_your_api_key',
  serverSecret: 'ab_srv_your_server_secret',
});

const scheduled = await abrovaPush.scheduled.create({
  title: 'Flash Sale!',
  body: '50% off for the next 2 hours',
  targetType: 'broadcast',
  scheduledAt: '2024-01-20T10:00:00Z',
  timezone: 'Asia/Tehran',
});
```

#### REST API

```bash
curl -X POST "https://push-api.abrova.ir/scheduled" \
  -H "x-api-key: ab_live_your_api_key" \
  -H "x-server-secret: ab_srv_your_server_secret" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Flash Sale!",
    "body": "50% off for the next 2 hours",
    "targetType": "broadcast",
    "scheduledAt": "2024-01-20T10:00:00Z",
    "timezone": "Asia/Tehran"
  }'
```

<H2 id="target-types" step={3}>Target Types</H2>

<ConfigTable rows={[
  ['broadcast', '-', '-', 'Send to all devices (no targetValue required)'],
  ['device', '-', '-', 'Send to specific device (targetValue = device ID)'],
  ['user', '-', '-', "Send to user's devices (targetValue = user ID)"],
  ['topic', '-', '-', 'Send to topic subscribers (targetValue = topic name)'],
  ['segment', '-', '-', 'Scheduled messages can\'t target segments; send to a segment immediately.'],
]} />

<H2 id="target-specific-devices-users" step={4}>Target Specific Devices/Users</H2>

#### Node.js SDK

```typescript
await abrovaPush.scheduled.create({
  title: 'Your appointment reminder',
  body: "Don't forget your meeting in 1 hour",
  targetType: 'user',
  targetValue: 'user_123',
  scheduledAt: '2024-01-20T09:00:00Z',
  timezone: 'Asia/Tehran',
});
```

#### REST API

```bash
curl -X POST "https://push-api.abrova.ir/scheduled" \
  -H "x-api-key: ab_live_your_api_key" \
  -H "x-server-secret: ab_srv_your_server_secret" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Your appointment reminder",
    "body": "Dont forget your meeting in 1 hour",
    "targetType": "user",
    "targetValue": "user_123",
    "scheduledAt": "2024-01-20T09:00:00Z",
    "timezone": "Asia/Tehran"
  }'
```

<H2 id="list-scheduled-messages" step={5}>List Scheduled Messages</H2>

#### Node.js SDK

```typescript
const messages = await abrovaPush.scheduled.list();

// Or only pending
const pending = await abrovaPush.scheduled.listPending();
```

#### REST API

```bash
curl -X GET "https://push-api.abrova.ir/scheduled" \
  -H "x-api-key: ab_live_your_api_key" \
  -H "x-server-secret: ab_srv_your_server_secret"
```

#### Response

```json
[
  {
    "id": "sch_abc123",
    "title": "Flash Sale!",
    "body": "50% off for 2 hours",
    "targetType": "broadcast",
    "scheduledAt": "2024-01-20T10:00:00Z",
    "timezone": "Asia/Tehran",
    "status": "pending",
    "createdAt": "2024-01-15T12:00:00Z"
  }
]
```

<H2 id="message-status" step={6}>Message Status</H2>

<ConfigTable rows={[
  ['pending', '-', '-', 'Waiting for scheduled time'],
  ['processing', '-', '-', 'Currently being sent'],
  ['sent', '-', '-', 'Successfully sent'],
  ['failed', '-', '-', 'Failed to send'],
  ['cancelled', '-', '-', 'Cancelled before sending'],
]} />

<H2 id="cancel-a-scheduled-message" step={7}>Cancel a Scheduled Message</H2>

Cancel a pending message before it's sent. Only messages with status `pending` can be cancelled (or updated with `PUT /scheduled/:id` / `abrovaPush.scheduled.update(id, {...})`).

#### Node.js SDK

```typescript
await abrovaPush.scheduled.cancel('sch_abc123');
```

#### REST API

```bash
curl -X POST "https://push-api.abrova.ir/scheduled/sch_abc123/cancel" \
  -H "x-api-key: ab_live_your_api_key" \
  -H "x-server-secret: ab_srv_your_server_secret"
```

<H2 id="delete-a-scheduled-message" step={8}>Delete a Scheduled Message</H2>

#### Node.js SDK

```typescript
await abrovaPush.scheduled.delete('sch_abc123');
```

#### REST API

```bash
curl -X DELETE "https://push-api.abrova.ir/scheduled/sch_abc123" \
  -H "x-api-key: ab_live_your_api_key" \
  -H "x-server-secret: ab_srv_your_server_secret"
```

- Templates: https://abrova.ir/en/docs/push/templates

Create reusable notification templates with dynamic variables and localizations. Define a template once, send it many times with different variables.

<H2 id="overview" step={1}>Overview</H2>

Templates let you define reusable notification content with placeholders for dynamic data. Instead of hardcoding notification text in your backend, create a template once and send it with different variables each time. Templates support localization: store per-locale copy and pick the language with `locale` when you send.

<div>
  <div>
    <h3>Dynamic Variables</h3>
    <p>Use {`{{variable}}`} placeholders that get replaced at send time with real data</p>
  </div>
  <div>
    <h3>Localization</h3>
    <p>Define per-locale title and body; choose the locale per send</p>
  </div>
  <div>
    <h3>Reusable</h3>
    <p>One template, many sends. Update the template and all future sends use the new content</p>
  </div>
</div>

<H2 id="variable-syntax" step={2}>Variable Syntax</H2>

Use double curly braces to insert dynamic content: `{{variableName}}` (letters, digits and underscores). Variables are automatically detected from your template's title and body unless you pass an explicit `variables` array.

**Title:** `Hello {{username}}!`
**Body:** `Your order #{{orderId}} has been shipped to {{address}}`

Detected variables: `username`, `orderId`, `address`.

<Callout kind="note" title="Case Sensitivity">
Variable names are case-sensitive. `{{UserName}}` and `{{username}}` are different variables. If a variable is not provided at send time, the placeholder is left in the text as-is (e.g. `{{username}}`).
</Callout>

<H2 id="create-a-template" step={3}>Create a Template</H2>

#### Node.js SDK

```typescript
import { AbrovaPush } from '@abrova/push-node';

const abrovaPush = new AbrovaPush({
  apiKey: 'ab_live_your_api_key',
  serverSecret: 'ab_srv_your_server_secret',
});

const template = await abrovaPush.templates.create({
  name: 'Order Shipped',
  title: 'Order #{{orderId}} Shipped!',
  body: 'Hi {{username}}, your order is on the way to {{address}}.',
  description: 'Sent when an order ships',
});
```

#### REST API

```bash
curl -X POST "https://push-api.abrova.ir/templates" \
  -H "x-api-key: ab_live_your_api_key" \
  -H "x-server-secret: ab_srv_your_server_secret" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Order Shipped",
    "title": "Order #{{orderId}} Shipped!",
    "body": "Hi {{username}}, your order is on the way to {{address}}.",
    "description": "Sent when an order ships"
  }'
```

#### Response

```json
{
  "id": "tpl_abc123",
  "name": "Order Shipped",
  "title": "Order #{{orderId}} Shipped!",
  "body": "Hi {{username}}, your order is on the way to {{address}}.",
  "description": "Sent when an order ships",
  "variables": ["orderId", "username", "address"],
  "createdAt": "2024-01-15T10:00:00Z"
}
```

<H2 id="send-using-a-template" step={4}>Send Using a Template</H2>

Pass the template ID and a `templateVariables` object when sending (any `send*` / `broadcast` call). AbrovaPush renders the template server-side and delivers the final notification. A `title`, `body` or `data` you pass in the same request overrides the template's value.

#### Node.js SDK

```typescript
await abrovaPush.push.sendToUser({
  userId: 'user_123',
  templateId: 'tpl_abc123',
  templateVariables: {
    orderId: 'ORD-12345',
    username: 'John',
    address: '123 Main St',
  },
});
```

#### REST API

```bash
curl -X POST "https://push-api.abrova.ir/push/send-to-user" \
  -H "x-api-key: ab_live_your_api_key" \
  -H "x-server-secret: ab_srv_your_server_secret" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "user_123",
    "templateId": "tpl_abc123",
    "templateVariables": {
      "orderId": "ORD-12345",
      "username": "John",
      "address": "123 Main St"
    }
  }'
```

#### Rendered Result

<div>
  <div>
    <div>
      <div>
        <span>📦</span>
      </div>
      <span>Your App</span>
      <span>now</span>
    </div>
    <p>Order #ORD-12345 Shipped!</p>
    <p>Hi John, your order is on the way to 123 Main St.</p>
  </div>
</div>

<H2 id="localization" step={5}>Localization</H2>

Templates support per-locale overrides. Pass `locale` in the send request (e.g. `"locale": "fa"`) and AbrovaPush uses the localization stored under that exact key. If `locale` is omitted or has no match, the default title and body are used. The locale is chosen per request, not per recipient device — send one request per language to reach a mixed audience.

```bash
curl -X POST "https://push-api.abrova.ir/templates" \
  -H "x-api-key: ab_live_your_api_key" \
  -H "x-server-secret: ab_srv_your_server_secret" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Order Shipped",
    "title": "Order #{{orderId}} Shipped!",
    "body": "Hi {{username}}, your order is on the way.",
    "localizations": {
      "fa": {
        "title": "سفارش #{{orderId}} ارسال شد!",
        "body": "سلام {{username}}، سفارش شما در راه است."
      },
      "es": {
        "title": "Pedido #{{orderId}} enviado!",
        "body": "Hola {{username}}, tu pedido va en camino."
      }
    }
  }'
```

Use standard locale codes (`en`, `fa`, `es`, `fr`, `de`, etc.) — the key must match the `locale` you send exactly. The same `{{variables}}` work across all locales.

<H2 id="custom-data-payload" step={6}>Custom Data Payload</H2>

Besides template variables (which control notification text), you can attach a `data` object that gets delivered alongside the notification. Useful for deep linking, navigation, or passing metadata to your app.

```bash
curl -X POST "https://push-api.abrova.ir/push/send-to-user" \
  -H "x-api-key: ab_live_your_api_key" \
  -H "x-server-secret: ab_srv_your_server_secret" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "user_123",
    "templateId": "tpl_abc123",
    "templateVariables": {
      "orderId": "ORD-12345",
      "username": "John"
    },
    "data": {
      "screen": "order_detail",
      "orderId": "ORD-12345",
      "action": "view_tracking"
    }
  }'
```

The `data` payload is not rendered in the notification text — it's passed through to your app when the user taps the notification. Use it for routing, deep linking, or storing context. A template can also store a default `data` object; a `data` object in the send request replaces it entirely (it is not merged, and variables are not substituted inside `data`).

<H2 id="manage-templates" step={7}>Manage Templates</H2>

#### List Templates (SDK)

```typescript
const templates = await abrovaPush.templates.list();
```

#### List Templates (REST API)

```bash
curl -X GET "https://push-api.abrova.ir/templates" \
  -H "x-api-key: ab_live_your_api_key" \
  -H "x-server-secret: ab_srv_your_server_secret"
```

#### Update a Template (SDK)

```typescript
const updated = await abrovaPush.templates.update('tpl_abc123', {
  title: 'Your order #{{orderId}} is on the way!',
  body: 'Hi {{username}}, track it here: {{trackingUrl}}',
});
```

#### Update a Template (REST API)

```bash
curl -X PUT "https://push-api.abrova.ir/templates/tpl_abc123" \
  -H "x-api-key: ab_live_your_api_key" \
  -H "x-server-secret: ab_srv_your_server_secret" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Your order #{{orderId}} is on the way!",
    "body": "Hi {{username}}, track it here: {{trackingUrl}}"
  }'
```

#### Delete a Template (SDK)

```typescript
await abrovaPush.templates.delete('tpl_abc123');
```

#### Delete a Template (REST API)

```bash
curl -X DELETE "https://push-api.abrova.ir/templates/tpl_abc123" \
  -H "x-api-key: ab_live_your_api_key" \
  -H "x-server-secret: ab_srv_your_server_secret"
```

<Callout kind="warn" title="Permanent Deletion">
Deleting a template is permanent. Any service or integration that references this template ID will fail to send notifications until updated with a new template ID.
</Callout>

<H2 id="example-templates" step={8}>Example Templates</H2>

Common templates for different industries. Use these as starting points for your own notifications.

<div>
  <div>
    <div>
      <h3>Welcome Message</h3>
      <span>Onboarding</span>
    </div>
    <p>Title: Welcome, {`{{name}}`}!</p>
    <p>Body: Thanks for joining. Start exploring at {`{{appUrl}}`}</p>
    <p>Variables: <code>name, appUrl</code></p>
  </div>

  <div>
    <div>
      <h3>Order Shipped</h3>
      <span>Notifications</span>
    </div>
    <p>Title: Order #{`{{orderId}}`} shipped!</p>
    <p>Body: Hi {`{{username}}`}, your package is on the way to {`{{address}}`}.</p>
    <p>Variables: <code>orderId, username, address</code></p>
  </div>

  <div>
    <div>
      <h3>Payment Received</h3>
      <span>Billing</span>
    </div>
    <p>Title: Payment of {`{{amount}}`} received</p>
    <p>Body: Your payment for invoice #{`{{invoiceId}}`} was successful.</p>
    <p>Variables: <code>amount, invoiceId</code></p>
  </div>

  <div>
    <div>
      <h3>Event Reminder</h3>
      <span>Scheduling</span>
    </div>
    <p>Title: Reminder: {`{{eventName}}`} tomorrow</p>
    <p>Body: Hi {`{{userName}}`}, your meeting with {`{{hostName}}`} is at {`{{time}}`}.</p>
    <p>Variables: <code>eventName, userName, hostName, time</code></p>
  </div>

  <div>
    <div>
      <h3>New Assignment</h3>
      <span>Education</span>
    </div>
    <p>Title: New assignment in {`{{courseName}}`}</p>
    <p>Body: {`{{teacherName}}`} posted "{`{{assignmentTitle}}`}". Due: {`{{dueDate}}`}</p>
    <p>Variables: <code>courseName, teacherName, assignmentTitle, dueDate</code></p>
  </div>

  <div>
    <div>
      <h3>Delivery Update</h3>
      <span>Food Delivery</span>
    </div>
    <p>Title: Your order from {`{{restaurantName}}`}</p>
    <p>Body: {`{{driverName}}`} is on the way! Estimated arrival: {`{{eta}}`}</p>
    <p>Variables: <code>restaurantName, driverName, eta</code></p>
  </div>
</div>

<H2 id="using-templates-with-other-services" step={9}>Using Templates with Other Services</H2>

AbrovaPush templates work with any service that integrates with the AbrovaPush API. Define the template once and any service can send notifications using it by passing the template ID and variables.

1. Create a template in AbrovaPush (dashboard or API)
2. Copy the template ID (e.g. `tpl_abc123`)
3. Configure the template ID in your service (e.g. Abrova Chat, your backend)
4. The service calls AbrovaPush with the template ID + `templateVariables` (and optional `locale`) at the right moment
5. AbrovaPush renders the template, applies localization, and delivers the push notification

<H2 id="best-practices" step={10}>Best Practices</H2>

<BestPracticeList items={[
  ['Keep Titles Short', 'Aim for under 50 characters. Titles get truncated on most devices'],
  ['Use Descriptive Template Names', 'Name templates by their purpose ("Order Shipped", "Password Reset") so your team can find them'],
  ['Always Provide All Variables', 'Missing variables are left as raw {{placeholders}} in the text. Test your templates with all variables before sending'],
  ['Add Localizations Early', "It's easier to add translations when creating the template than retrofitting later"],
  ['Use Data Payloads for Navigation', "Don't put navigation info in the notification text. Use the data object so your app can route users to the right screen"],
]} />

- Segments: https://abrova.ir/en/docs/push/segments

Create dynamic groups based on device attributes for targeted messaging.

<H2 id="available-filter-fields" step={1}>Available Filter Fields</H2>

<div>
  <div>
    <code>platform</code>
    <p>android, ios, web</p>
  </div>
  <div>
    <code>userId</code>
    <p>User identifier</p>
  </div>
  <div>
    <code>appVersion</code>
    <p>App version string</p>
  </div>
  <div>
    <code>country</code>
    <p>Country code</p>
  </div>
  <div>
    <code>language</code>
    <p>Device language</p>
  </div>
  <div>
    <code>metadata.*</code>
    <p>Custom fields</p>
  </div>
</div>

<H2 id="create-a-segment" step={2}>Create a Segment</H2>

#### Node.js SDK

```typescript
import { AbrovaPush } from '@abrova/push-node';

const abrovaPush = new AbrovaPush({
  apiKey: 'ab_live_your_api_key',
  serverSecret: 'ab_srv_your_server_secret',
});

const segment = await abrovaPush.segments.create({
  name: 'Premium iOS Users',
  description: 'iOS users with premium subscription',
  filters: [
    { field: 'platform', operator: 'equals', value: 'ios' },
    { field: 'metadata.tier', operator: 'equals', value: 'premium' },
  ],
});
```

#### REST API

```bash
curl -X POST "https://push-api.abrova.ir/segments" \
  -H "x-api-key: ab_live_your_api_key" \
  -H "x-server-secret: ab_srv_your_server_secret" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Premium iOS Users",
    "description": "iOS users with premium subscription",
    "filters": [
      { "field": "platform", "operator": "equals", "value": "ios" },
      { "field": "metadata.tier", "operator": "equals", "value": "premium" }
    ]
  }'
```

#### Response

```json
{
  "id": "seg_abc123",
  "name": "Premium iOS Users",
  "description": "iOS users with premium subscription",
  "color": "#6366f1",
  "filters": [
    { "field": "platform", "operator": "equals", "value": "ios" },
    { "field": "metadata.tier", "operator": "equals", "value": "premium" }
  ],
  "deviceCount": 850,
  "createdAt": "2024-01-15T10:00:00Z"
}
```

<H2 id="filter-operators" step={3}>Filter Operators</H2>

<ConfigTable
  headers={['Operator', 'Description']}
  rows={[
    ['equals', 'Exact match (platform = "ios")'],
    ['not_equals', 'Not equal to (platform != "web")'],
    ['contains', 'String contains (appVersion contains "2.")'],
    ['not_contains', 'String does not contain'],
    ['greater_than', 'Numeric greater than (metadata.age > 18)'],
    ['less_than', 'Numeric less than (metadata.age < 65)'],
    ['in', 'In list of values (country in ["US", "CA", "GB"])'],
    ['not_in', 'Not in list of values'],
    ['exists', 'metadata.* key is present (value true) or missing (value false) — metadata.vip exists true'],
    ['starts_with', 'String starts with — top-level fields only (not metadata.*)'],
    ['greater_than_or_equal', 'Greater than or equal — top-level fields only (not metadata.*)'],
    ['less_than_or_equal', 'Less than or equal — top-level fields only (not metadata.*)'],
  ]}
/>

Filters are combined with AND. Comparisons on `appVersion` are version-aware (`2.10.0` > `2.9.0`), and `platform` values are matched in lowercase. `starts_with`, `greater_than_or_equal` and `less_than_or_equal` are not in the Node SDK's `SegmentFilterOperator` type yet.

<Callout kind="note">
The dashboard **auto-discovers** which `metadata.*` keys and values your devices actually send — the segment builder suggests real keys from your project, and operator choices adapt to each key's inferred type (string, number, boolean). You can still type any custom `metadata.*` key you plan to write from your SDK later.
</Callout>

<H2 id="example-segments" step={4}>Example Segments</H2>

#### Android Users in US/Canada

```json
{
  "name": "North American Android",
  "filters": [
    { "field": "platform", "operator": "equals", "value": "android" },
    { "field": "country", "operator": "in", "value": ["US", "CA"] }
  ]
}
```

#### VIP Users (Custom Metadata)

```json
{
  "name": "VIP Members",
  "filters": [
    { "field": "metadata.vip", "operator": "equals", "value": true },
    { "field": "metadata.totalSpent", "operator": "greater_than", "value": 1000 }
  ]
}
```

#### Beta Testers on Latest Version

```json
{
  "name": "Beta Testers",
  "filters": [
    { "field": "metadata.betaTester", "operator": "equals", "value": true },
    { "field": "appVersion", "operator": "contains", "value": "3." }
  ]
}
```

<H2 id="send-to-segment" step={5}>Send to Segment</H2>

Send to a segment with an immediate push. Scheduled messages can't target segments; send to a segment immediately.

#### Node.js SDK

```typescript
// Send to segment immediately
await abrovaPush.push.sendToSegment({
  segmentId: 'seg_abc123',
  title: 'Exclusive for Premium!',
  body: 'Check out your member benefits',
});
```

#### REST API

```bash
curl -X POST "https://push-api.abrova.ir/push/send-to-segment" \
  -H "x-api-key: ab_live_your_api_key" \
  -H "x-server-secret: ab_srv_your_server_secret" \
  -H "Content-Type: application/json" \
  -d '{
    "segmentId": "seg_abc123",
    "title": "Exclusive for Premium!",
    "body": "Check out your member benefits"
  }'
```

<H2 id="preview-segment" step={6}>Preview Segment</H2>

Get the match count + a small device sample for a set of filters **without saving** them. Useful for validating filter logic before creating a segment.

<Callout kind="note">
The dashboard's segment builder shows this preview live in the right panel as you edit — no code needed there. The API + SDK below are for programmatic use (CI checks, batch jobs, custom UIs).
</Callout>

#### Node.js SDK

```typescript
const { count, preview } = await abrovaPush.segments.preview({
  filters: [
    { field: 'platform', operator: 'equals', value: 'ios' },
    { field: 'metadata.tier', operator: 'equals', value: 'premium' },
  ],
  limit: 10, // optional, default 20, max 50
});

console.log(`${count} devices match`);
preview.forEach((d) => console.log(d.deviceId, d.userId));
```

#### REST API

```bash
curl -X POST "https://push-api.abrova.ir/segments/preview?limit=10" \
  -H "x-api-key: ab_live_your_api_key" \
  -H "x-server-secret: ab_srv_your_server_secret" \
  -H "Content-Type: application/json" \
  -d '{
    "filters": [
      { "field": "platform", "operator": "equals", "value": "ios" },
      { "field": "metadata.tier", "operator": "equals", "value": "premium" }
    ]
  }'
```

#### Response

```json
{
  "count": 1250,
  "preview": [
    {
      "deviceId": "dev_abc...",
      "platform": "ios",
      "userId": "user_1",
      "topics": ["news", "promos"],
      "metadata": { "tier": "premium", "country": "US" }
    },
    {
      "deviceId": "dev_def...",
      "platform": "ios",
      "userId": "user_2",
      "topics": null,
      "metadata": { "tier": "premium" }
    }
  ]
}
```

Long metadata string values are truncated to 200 characters (with an ellipsis) in the preview response to keep payloads small.

- Webhooks: https://abrova.ir/en/docs/push/webhooks

Receive real-time HTTP callbacks when events occur.

<H2 id="available-events" step={1}>Available Events</H2>

<div>
  <div>
    <code>message.sent</code>
    <p>A send request was accepted for delivery (fired once per message, with success/failed counts)</p>
  </div>
  <div>
    <code>message.delivered</code>
    <p>A device confirmed receipt (fired once per device)</p>
  </div>
  <div>
    <code>message.failed</code>
    <p>The send failed (fired once per message)</p>
  </div>
  <div>
    <code>message.no_recipients</code>
    <p>No device matched the target — message not attempted</p>
  </div>
  <div>
    <code>device.registered</code>
    <p>New device registered</p>
  </div>
  <div>
    <code>device.updated</code>
    <p>Existing device re-registered or re-activated</p>
  </div>
  <div>
    <code>device.unregistered</code>
    <p>Device unregistered or deactivated</p>
  </div>
</div>

<H2 id="create-a-webhook" step={2}>Create a Webhook</H2>

#### Node.js SDK

```typescript
import { AbrovaPush } from '@abrova/push-node';

const abrovaPush = new AbrovaPush({
  apiKey: 'ab_live_your_api_key',
  serverSecret: 'ab_srv_your_server_secret',
});

const webhook = await abrovaPush.webhooks.create({
  name: 'Analytics Webhook',
  url: 'https://your-server.com/webhooks/abrova-push',
  events: ['message.sent', 'message.delivered', 'message.failed'],
});
console.log('Webhook secret:', webhook.secret);
```

#### REST API

```bash
curl -X POST "https://push-api.abrova.ir/webhooks" \
  -H "x-api-key: ab_live_your_api_key" \
  -H "x-server-secret: ab_srv_your_server_secret" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Analytics Webhook",
    "url": "https://your-server.com/webhooks/abrova-push",
    "events": ["message.sent", "message.delivered", "message.failed"]
  }'
```

#### Response

```json
{
  "id": "wh_abc123",
  "name": "Analytics Webhook",
  "url": "https://your-server.com/webhooks/abrova-push",
  "events": ["message.sent", "message.delivered", "message.failed"],
  "secret": "whsec_xyz789...",
  "isActive": true,
  "maxRetries": 3,
  "timeoutMs": 5000,
  "createdAt": "2024-01-15T10:00:00Z"
}
```

<Callout kind="warn" title="Save the Secret">
Save the `secret` value — you'll need it to verify webhook signatures. If you don't pass your own `secret`, one is generated (`whsec_...`). You can rotate it with `POST /webhooks/:id/regenerate-secret` (`abrovaPush.webhooks.regenerateSecret(id)`).
</Callout>

<H2 id="webhook-payload" step={3}>Webhook Payload</H2>

When an event occurs, we send a POST request to your URL with the headers `X-AbrovaPush-Signature`, `X-AbrovaPush-Event` and `X-AbrovaPush-Webhook-Id`, and this payload:

```json
{
  "event": "message.sent",
  "timestamp": "2024-01-15T10:30:00Z",
  "webhookId": "wh_abc123",
  "data": {
    "messageId": "msg_xyz789",
    "type": "user",
    "target": "user_456",
    "title": "Hello!",
    "body": "Test message",
    "successCount": 2,
    "failedCount": 0,
    "status": "sent"
  }
}
```

The `data` object depends on the event:

- `message.sent` / `message.failed` / `message.no_recipients` — `messageId`, `type`, `target`, `title`, `body`, `successCount`, `failedCount`, `status`
- `message.delivered` — `messageId`, `deviceId`, `title`
- `device.registered` / `device.updated` — `deviceId`, `platform`, `userId`, `appIdentifier`, `isActive` (or just `deviceId`, `isActive` when a device is re-activated)
- `device.unregistered` — `deviceId` (plus `isActive: false` when deactivated)

<H2 id="verify-webhook-signature" step={4}>Verify Webhook Signature</H2>

Always verify the `X-AbrovaPush-Signature` header to ensure the webhook came from AbrovaPush.

```javascript
const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

// Express.js example
app.post('/webhooks/abrova-push', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.headers['x-abrovapush-signature'];
  const payload = req.body.toString();

  if (!verifyWebhook(payload, signature, process.env.WEBHOOK_SECRET)) {
    return res.status(401).send('Invalid signature');
  }

  const event = JSON.parse(payload);

  switch (event.event) {
    case 'message.sent':
      // Record send event
      break;
    case 'message.delivered':
      // Record delivery
      break;
    case 'message.failed':
      // Handle failure
      break;
    case 'message.no_recipients':
      // Target had no registered device — mark the user as push-unreachable,
      // fall back to email/SMS, etc. Not a delivery failure.
      break;
  }

  res.status(200).send('OK');
});
```

<H2 id="retry-policy" step={5}>Retry Policy</H2>

If your endpoint returns a non-2xx status code or times out (default timeout 5 seconds, configurable with `timeoutMs` from 1000 to 30000), we'll retry with exponential backoff. With the default `maxRetries` of 3:

- **Attempt 1**: Immediate
- **Attempt 2**: After 1 second
- **Attempt 3**: After 2 seconds
- **Attempt 4**: After 4 seconds

After 4 failed attempts, the webhook delivery is marked as failed. Set `maxRetries` (1–10) when creating or updating the webhook to change the number of retries. Every attempt is logged — fetch the log with `GET /webhooks/:id/logs?limit=50` (max 100) or `abrovaPush.webhooks.getLogs(id)`.

<H2 id="list-webhooks" step={6}>List Webhooks</H2>

#### Node.js SDK

```typescript
const webhooks = await abrovaPush.webhooks.list();
```

#### REST API

```bash
curl -X GET "https://push-api.abrova.ir/webhooks" \
  -H "x-api-key: ab_live_your_api_key" \
  -H "x-server-secret: ab_srv_your_server_secret"
```

<H2 id="update-webhook" step={7}>Update Webhook</H2>

#### Node.js SDK

```typescript
await abrovaPush.webhooks.update('wh_abc123', {
  name: 'Updated Webhook',
  events: ['message.sent', 'device.registered'],
  isActive: true,
});
```

#### REST API

```bash
curl -X PUT "https://push-api.abrova.ir/webhooks/wh_abc123" \
  -H "x-api-key: ab_live_your_api_key" \
  -H "x-server-secret: ab_srv_your_server_secret" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Webhook",
    "events": ["message.sent", "device.registered"],
    "isActive": true
  }'
```

<H2 id="delete-webhook" step={8}>Delete Webhook</H2>

#### Node.js SDK

```typescript
await abrovaPush.webhooks.delete('wh_abc123');
```

#### REST API

```bash
curl -X DELETE "https://push-api.abrova.ir/webhooks/wh_abc123" \
  -H "x-api-key: ab_live_your_api_key" \
  -H "x-server-secret: ab_srv_your_server_secret"
```

<H2 id="test-webhook" step={9}>Test Webhook</H2>

Send a test event to verify your webhook is configured correctly. The test delivery uses the `message.sent` event unless you pass another one (`{ "event": "device.registered" }` in the body, or `abrovaPush.webhooks.test(id, 'device.registered')`), and its `data` is `{ "test": true, "timestamp": "...", "message": "This is a test webhook delivery" }`. The response is the delivery log entry (`success`, `responseStatus`, `error`, `durationMs`, ...).

#### Node.js SDK

```typescript
const result = await abrovaPush.webhooks.test('wh_abc123');
```

#### REST API

```bash
curl -X POST "https://push-api.abrova.ir/webhooks/wh_abc123/test" \
  -H "x-api-key: ab_live_your_api_key" \
  -H "x-server-secret: ab_srv_your_server_secret"
```

- A/B testing: https://abrova.ir/en/docs/push/ab-testing

Test different push notification variants to optimize engagement and conversion rates. Compare up to 10 variants with statistical significance analysis.

<Callout kind="wallet" title="Included">
A/B testing, control groups, early stopping and the statistics are included with Abrova Push. Every variant you send counts toward your monthly messages like any other push: 10,000 messages a month are free, and the price above that is set when Abrova Push launches.
</Callout>

<H2 id="overview" step={1}>Overview</H2>

AbrovaPush A/B testing lets you send different notification variants to different user segments and measure which performs best. Tests are created and run in Abrova Console.

<div>
  <div>
    <h3>Key Features</h3>
    <ul>
      <li>• Up to 10 variants per test</li>
      <li>• Control groups (no message sent)</li>
      <li>• Early stopping when significance reached</li>
      <li>• Statistical confidence analysis</li>
      <li>• Automatic click tracking on mobile</li>
      <li>• Target by segment or percentage</li>
    </ul>
  </div>
  <div>
    <h3>Tracked Metrics</h3>
    <ul>
      <li>• <span>Sent</span> — Messages dispatched</li>
      <li>• <span>Delivered</span> — Successfully received</li>
      <li>• <span>Opened</span> — Notification viewed</li>
      <li>• <span>Clicked</span> — User tapped notification</li>
      <li>• <span>Converted</span> — Custom goal achieved</li>
    </ul>
  </div>
</div>

<H2 id="creating-tests-via-dashboard" step={2}>Creating Tests via Dashboard</H2>

Create A/B tests in the [AbrovaPush A/B Testing dashboard](https://console.abrova.ir/dashboard/abrova-push/ab-testing).

1. **Create New Test** — Click "Create A/B Test" and enter test name and description
2. **Configure Variants** — Add 2-10 variants with different titles, bodies, images, and action buttons. Set traffic percentage for each
3. **Set Target Audience** — Choose "All users", a specific segment, or a percentage of your audience
4. **Configure Options** — Enable control group, early stopping, select winning metric, set test duration
5. **Start Test** — Review and start. Send notifications to begin collecting data

<H2 id="control-groups" step={3}>Control Groups</H2>

A control group receives no notification, letting you measure the true impact of your messaging versus no messaging at all.

**Example:** If your control group has 5% conversion and Variant A has 12%, the notification drove a 7% lift — not just that 12% of users converted.

<H2 id="early-stopping" step={4}>Early Stopping</H2>

When enabled, the test automatically completes when statistical significance is reached, saving you from running tests longer than necessary.

<ConfigTable rows={[
  ['Significance Threshold', '-', '-', 'Confidence level required (90%, 95%, or 99%)'],
  ['Minimum Sample Size', '-', '-', 'Minimum deliveries per variant before checking significance (default 100)'],
]} />

<H2 id="sdk-integration-auto-click-tracking" step={5}>SDK Integration — Auto Click Tracking</H2>

Mobile SDKs support A/B testing with automatic click tracking. When users tap A/B test notifications, clicks are tracked without additional code.

#### Android (Kotlin)

```kotlin
// Get variant for a test (with caching)
AbrovaPush.getABTestVariant(
    testId = "test_id",
    forceRefresh = false,
    onSuccess = { variant ->
        // Display content based on variant
        showBanner(
            title = variant.content?.title ?: "Default",
            backgroundColor = variant.content?.data?.get("backgroundColor")
        )

        // Track that variant was displayed
        AbrovaPush.trackABTestDisplay(variant)
    },
    onError = { error -> /* handle */ }
)

// Track click manually (automatic for push notifications)
AbrovaPush.trackABTestClicked(testId, variantId)

// Track conversion
AbrovaPush.trackABTestConverted(testId, variantId)
```

#### iOS (Swift)

```swift
// Get variant for a test
AbrovaPush.shared.getABTestVariant(testId: "test_id") { result in
    switch result {
    case .success(let variant):
        showBanner(
            title: variant.content?.title ?? "Default",
            color: variant.content?.data?["backgroundColor"]?.value as? String
        )
        AbrovaPush.shared.trackABTestDisplay(variant: variant)

    case .failure(let error):
        // handle
    }
}

// Track click manually (automatic for push notifications)
AbrovaPush.shared.trackABTestClicked(testId: testId, variantId: variantId)
// Note: the iOS SDK has no conversion-tracking method yet

// Handle notification tap (automatic click tracking)
func userNotificationCenter(_ center: UNUserNotificationCenter,
                           didReceive response: UNNotificationResponse,
                           withCompletionHandler completionHandler: @escaping () -> Void) {
    // This automatically tracks A/B test clicks
    AbrovaPush.shared.handleNotificationResponse(
        userInfo: response.notification.request.content.userInfo,
        actionIdentifier: response.actionIdentifier
    )
    completionHandler()
}
```

#### Flutter

```dart
final variant = await AbrovaPush.getABTestVariant('test_id');
if (variant != null) {
  showBanner(
    title: variant.content?.title ?? 'Default',
    color: variant.content?.data?['backgroundColor'],
  );

  await AbrovaPush.trackABTestDisplay(variant);
}

await AbrovaPush.trackABTestClicked(testId, variantId);
// Note: the Flutter SDK has no conversion-tracking method yet
```

#### React Native

```typescript
const variant = await AbrovaPush.getABTestVariant('test_id');
if (variant) {
  showBanner({
    title: variant.content?.title ?? 'Default',
    color: variant.content?.data?.backgroundColor,
  });

  await AbrovaPush.trackABTestDisplay(variant);
}

await AbrovaPush.trackABTestClicked(testId, variantId);
// Note: trackABTestConverted is declared in the React Native package but its
// native method is missing, so calling it fails. Conversions are Android-only today.
```

<H2 id="automatic-click-tracking" step={6}>Automatic Click Tracking</H2>

When you send A/B test notifications from the dashboard, the SDK automatically tracks clicks when users tap on the notification or action buttons. No additional code required.

**How it works:** A/B test notifications include `abTestId` and `variantId` in the payload. When the user taps the notification, the SDK extracts these values and sends a click event to the server automatically.

<H2 id="winner-metrics" step={7}>Winner Metrics</H2>

<ConfigTable rows={[
  ['delivery_rate', 'delivered / sent', '-', 'Testing delivery optimization'],
  ['open_rate', 'opened / delivered', '-', 'Testing notification appeal'],
  ['click_rate', 'clicked / delivered', '-', 'Testing engagement (recommended)'],
  ['conversion_rate', 'converted / sent', '-', 'Testing business outcomes'],
]} />

<H2 id="best-practices" step={8}>Best Practices</H2>

<BestPracticeList items={[
  ['Test One Variable at a Time', 'Change only one element (title, body, or image) per test to understand what drives the improvement'],
  ['Use Sufficient Sample Size', 'Wait for at least 100-1,000 sends per variant before drawing conclusions'],
  ['Include a Control Group', '10-20% control group helps measure true lift vs. no messaging at all'],
  ['Enable Early Stopping', 'Save time by automatically completing tests when statistical significance is reached'],
  ['Wait for Statistical Significance', '95%+ confidence before selecting a winner. The dashboard shows real-time confidence levels'],
]} />

- Teams: https://abrova.ir/en/docs/push/teams

Collaborate with your team by inviting members with role-based access control.

<Callout kind="note">
Team members are managed per **organisation and project** in Abrova Console (**Members** in the sidebar), not per service — a member added to a project has access to Abrova Push and every other service in it. There is no team-management API in the `@abrova/push-node` SDK, and the API key / server secret cannot manage members.
</Callout>

<H2 id="roles-permissions" step={1}>Roles & Permissions</H2>

<ConfigTable rows={[
  ['Owner', 'Full', 'Yes', 'Full team management + wallet management (top-ups, spending); the only role that can delete the organisation'],
  ['Admin', 'Full', 'Yes', 'Add/remove members and change roles, manage project settings and API keys, view the wallet (cannot top up or change spending settings)'],
  ['Member', 'Limited', 'Yes', 'Can view the API key; cannot manage members, project settings or the wallet'],
  ['Viewer', 'View only', 'No', 'Read-only access; cannot view the API key or manage the team'],
]} />

<H2 id="invite-a-team-member" step={2}>Invite a Team Member</H2>

1. Open **Members** in the Abrova Console sidebar (requires Admin or Owner).
2. Click **Add Member** and choose the project.
3. Enter the email (and optionally a name), pick a role — **Admin**, **Member** or **Viewer** — and submit.

If the email doesn't belong to an existing Abrova account, the Console shows a one-time **setup link** you share with the person so they can set a password and access the project.

<H2 id="list-team-members" step={3}>List Team Members</H2>

The **Members** page lists everyone in your organisations with their organisation role, the projects they can access (with per-project role), and pending invites. Use the **All / Org Members / Project-Only / Pending** tabs to filter.

<H2 id="update-member-role" step={4}>Update Member Role</H2>

In **Members → Add Member**, select the project to see its current members, then change a member's role from the role dropdown. Only Admins and Owners can change roles; a project Owner's role cannot be changed there.

<H2 id="remove-team-member" step={5}>Remove Team Member</H2>

Admins and Owners can remove a member from a project from the **Members** page (or from the project's member list in the **Add Member** dialog). Owners can't be removed there, and you can't remove yourself.

<H2 id="transfer-ownership" step={6}>Transfer Ownership</H2>

<Callout kind="warn" title="Irreversible">
Transferring ownership is irreversible. The new owner will have full control including the wallet.
</Callout>

Only the current Owner can transfer ownership of an organisation. Contact support to transfer ownership.

<H2 id="team-limits" step={7}>Team Limits</H2>

Abrova has no plans or tiers to compare: adding team members does not cost anything from your wallet. If your organisation reaches a member limit, the Console tells you when you try to add a member; [contact us](/contact) if you need more.

- Rate limits: https://abrova.ir/en/docs/push/rate-limits

Understand API rate limits to ensure fair usage and service stability.

<H2 id="general-limits" step={1}>General Limits</H2>

Limits are counted per endpoint and per client IP. Unless an endpoint below sets its own per-second limit, these defaults apply to every API request:

<ConfigTable
  headers={['Limit Type', 'Value', 'Notes']}
  rows={[
    ['Per second', '10 requests', 'Overridden per endpoint in the tables below'],
    ['Per minute', '100 requests', 'Applies to every endpoint (broadcast and A/B test send: 10/min)'],
    ['Per hour', '1,000 requests', 'Applies to every endpoint'],
    ['Action buttons', '3 per notification', 'actions array'],
    ['Message size', '4KB', 'APNs / FCM payload limit, including custom data'],
  ]}
/>

<H2 id="sdk-endpoint-rate-limits" step={2}>SDK Endpoint Rate Limits</H2>

Rate limits for SDK endpoints (using API key authentication).

#### Push Notifications (server: API key + server secret)

<ConfigTable
  headers={['Endpoint', 'Limit', 'Notes']}
  rows={[
    ['POST /push/send', '30/sec', 'Send to one device'],
    ['POST /push/send-to-user', '20/sec', 'Send to all of a user\'s devices'],
    ['POST /push/send-to-devices', '10/sec', 'Send to multiple devices'],
    ['POST /push/send-to-topic', '5/sec', 'Send to a topic'],
    ['POST /push/send-to-segment', '5/sec', 'Send to a segment'],
    ['POST /push/broadcast', '1/sec, 10/min', 'Send to every device'],
  ]}
/>

#### Device Management

<ConfigTable
  headers={['Endpoint', 'Limit', 'Notes']}
  rows={[
    ['POST /devices/register', '10/sec', 'Device registration'],
    ['POST /devices/:id/topics/:topic', '20/sec', 'Topic subscription'],
    ['POST /devices/:id/user', '10/sec', 'User ID updates'],
  ]}
/>

#### Delivery Receipts

<ConfigTable
  headers={['Endpoint', 'Limit', 'Notes']}
  rows={[
    ['POST /receipts/*', '100/sec', 'All receipt tracking (delivered, opened, clicked, dismissed)'],
  ]}
/>

#### Inbox

<ConfigTable
  headers={['Endpoint', 'Limit', 'Notes']}
  rows={[
    ['POST /inbox/messages', '30/sec', 'Fetch inbox messages'],
    ['PUT /inbox/messages/:id', '50/sec', 'Update message status'],
    ['POST /inbox/messages/mark-multiple', '20/sec', 'Bulk mark operations'],
    ['POST /inbox/messages/mark-all-read', '10/sec', 'Mark all as read'],
    ['POST /inbox/sdk/send-to-device', '20/sec', 'Send to device inbox (client SDK)'],
    ['POST /inbox/api/send-to-user', '50/sec', 'Server inbox send to a user'],
    ['POST /inbox/api/send-to-device', '50/sec', 'Server inbox send to a device'],
    ['POST /inbox/api/send-to-users', '20/sec', 'Server inbox send to many users'],
    ['POST /inbox/api/broadcast', '5/sec', 'Server inbox broadcast'],
  ]}
/>

#### In-App Messages

<ConfigTable
  headers={['Endpoint', 'Limit', 'Notes']}
  rows={[
    ['POST /in-app/fetch', '30/sec', 'Fetch in-app messages'],
    ['POST /in-app/impression', '100/sec', 'Track impressions'],
  ]}
/>

#### A/B Testing

<ConfigTable
  headers={['Endpoint', 'Limit', 'Notes']}
  rows={[
    ['POST /ab-tests/sdk/assignment', '50/sec', 'Get variant assignment'],
    ['POST /ab-tests/sdk/track/*', '100/sec', 'Track impressions, opens, clicks, conversions'],
  ]}
/>

<H2 id="rate-limit-headers" step={3}>Rate Limit Headers</H2>

Every API response includes headers for each window, suffixed with the window name (`-short` = per second, `-medium` = per minute, `-long` = per hour), e.g. `X-RateLimit-Remaining-short`:

<ConfigTable
  headers={['Header', 'Description']}
  rows={[
    ['X-RateLimit-Limit-{window}', 'Maximum requests allowed per window'],
    ['X-RateLimit-Remaining-{window}', 'Requests remaining in current window'],
    ['X-RateLimit-Reset-{window}', 'Seconds until the window resets'],
    ['Retry-After-{window}', 'Sent with a 429: seconds to wait before retrying'],
  ]}
/>

<H2 id="rate-limit-exceeded-response" step={4}>Rate Limit Exceeded Response</H2>

When you exceed the rate limit, you will receive a 429 Too Many Requests response:

```json
{
  "statusCode": 429,
  "message": "Too Many Requests"
}
```

<H2 id="best-practices" step={5}>Best Practices</H2>

<BestPracticeList items={[
  ['Implement Exponential Backoff', 'When rate limited, wait and retry with increasing delays (1s, 2s, 4s, etc.)'],
  ['Use Bulk Endpoints', 'Send to multiple devices in a single request instead of individual calls'],
  ['Monitor Usage Headers', 'Track X-RateLimit-Remaining-* to proactively slow down before hitting limits'],
  ['Queue Non-Urgent Messages', 'Use scheduled messages for non-time-sensitive notifications to spread load'],
]} />

<H2 id="handling-rate-limits-in-code" step={6}>Handling Rate Limits in Code</H2>

```typescript
async function sendWithRetry(payload: any, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      const response = await fetch('https://push-api.abrova.ir/push/send', {
        method: 'POST',
        headers: {
          'x-api-key': 'ab_live_your_api_key',
          'x-server-secret': 'ab_srv_your_server_secret',
          'Content-Type': 'application/json',
        },
        body: JSON.stringify(payload),
      });

      if (response.status === 429) {
        const waitTime = Math.pow(2, attempt) * 1000; // Exponential backoff
        await new Promise(resolve => setTimeout(resolve, waitTime));
        continue;
      }

      if (!response.ok) {
        throw new Error(`HTTP ${response.status}`);
      }

      return await response.json();
    } catch (error) {
      if (attempt === maxRetries - 1) throw error;
    }
  }
}
```

- Rich notifications: https://abrova.ir/en/docs/push/rich

Enhance your notifications with images, action buttons, and custom sounds.

<H2 id="send-rich-notification" step={1}>Send Rich Notification</H2>

#### Node.js SDK

```typescript
import { AbrovaPush } from '@abrova/push-node';

const abrovaPush = new AbrovaPush({
  apiKey: 'ab_live_your_api_key',
  serverSecret: 'ab_srv_your_server_secret',
});

await abrovaPush.push.sendToUser({
  userId: 'user_123',
  title: 'New Product Available!',
  body: 'Check out our latest arrival',
  imageUrl: 'https://example.com/product.jpg',
  iconUrl: 'https://example.com/icon.png',
  actions: [
    { id: 'view', title: 'View Product', action: 'VIEW_PRODUCT' },
    { id: 'dismiss', title: 'Not Interested', action: 'DISMISS' }
  ],
  data: {
    productId: 'prod_123',
    deepLink: '/products/prod_123'
  }
});
```

#### REST API

```bash
curl -X POST "https://push-api.abrova.ir/push/send-to-user" \
  -H "x-api-key: ab_live_your_api_key" \
  -H "x-server-secret: ab_srv_your_server_secret" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "user_123",
    "title": "New Product Available!",
    "body": "Check out our latest arrival",
    "imageUrl": "https://example.com/product.jpg",
    "iconUrl": "https://example.com/icon.png",
    "actions": [
      { "id": "view", "title": "View Product", "action": "VIEW_PRODUCT" },
      { "id": "dismiss", "title": "Not Interested", "action": "DISMISS" }
    ],
    "data": {
      "productId": "prod_123",
      "deepLink": "/products/prod_123"
    }
  }'
```

These rich notification fields work with all send endpoints: `send` (one device), `send-to-user`, `send-to-devices`, `send-to-topic`, `send-to-segment`, and `broadcast`. See [REST API](/docs/push/send) for all endpoints.

<H2 id="rich-notification-fields" step={2}>Rich Notification Fields</H2>

<ConfigTable
  headers={['Field', 'Type', 'Description']}
  rows={[
    ['imageUrl', 'string', 'Large image displayed in the notification (max 1MB)'],
    ['iconUrl', 'string', 'Notification icon URL (used by Web notifications; the Android SDK uses its notificationIcon resource)'],
    ['actions', 'array', 'Action buttons (max 3, enforced by the API)'],
    ['deepLink', 'string', 'Deep link to open when the notification is tapped'],
    ['sound', 'string', 'Custom sound file name or "default"'],
    ['badge', 'number', 'App badge number (iOS only)'],
    ['badgeAction', 'string', '"set", "increment", "decrement" or "clear"'],
    ['category', 'string', 'iOS notification category for action buttons'],
    ['threadId', 'string', 'Thread identifier for grouping (iOS)'],
    ['collapseKey', 'string', 'Key for collapsing multiple notifications'],
    ['priority', 'string', '"default", "high" or "low"'],
    ['ttl', 'number', 'Time-to-live in seconds (Web push defaults to 86400 when omitted)'],
  ]}
/>

<H2 id="action-button-structure" step={3}>Action Button Structure</H2>

Each action needs an `id` and a `title` (max 20 characters). `action` is optional: Android passes it to your app as the deep link of the tap, and the Web service worker opens it as a URL. `icon` (Android icon name), `destructive` and `authRequired` (iOS) are optional too.

```json
{
  "actions": [
    {
      "id": "reply",
      "title": "Reply",
      "action": "REPLY_ACTION",
      "icon": "reply_icon"
    },
    {
      "id": "archive",
      "title": "Archive",
      "action": "ARCHIVE_ACTION",
      "destructive": true
    }
  ]
}
```

<H2 id="platform-support" step={4}>Platform Support</H2>

<div>
  <div>
    <h3>iOS</h3>
    <ul>
      <li>Large images on notifications the SDK shows itself (foreground / real-time connection); background APNs notifications show no image, as the SDK's Notification Service Extension does not download it</li>
      <li>Up to 3 action buttons</li>
      <li>Badge number support</li>
      <li>Thread grouping</li>
      <li>Custom sounds (must be in app bundle)</li>
    </ul>
  </div>
  <div>
    <h3>Android</h3>
    <ul>
      <li>Big picture style notifications</li>
      <li>Up to 3 action buttons</li>
      <li>Large image shown as the large icon when collapsed</li>
      <li>Notification channels</li>
      <li>Custom sounds (file name of a res/raw resource)</li>
    </ul>
  </div>
</div>

<H2 id="handling-actions-in-sdks" step={5}>Handling Actions in SDKs</H2>

#### Flutter

```dart
import 'package:abrova_push/abrova_push.dart';

AbrovaPush.onNotificationAction((event) {
  print('Action tapped: ${event.actionId}');
  print('Notification title: ${event.title}');
  print('Notification data: ${event.data}');

  switch (event.actionId) {
    case 'view':
      Navigator.pushNamed(context, '/product/${event.data?['productId']}');
      break;
    case 'dismiss':
      // Handle dismiss
      break;
  }
});
```

#### Android

Override `onNotificationAction` in your `AbrovaPushCallback` (see [Callbacks](/docs/push/callbacks)):

```kotlin
import ir.abrova.push.sdk.AbrovaPush
import ir.abrova.push.sdk.AbrovaPushCallbackAdapter
import ir.abrova.push.sdk.AbrovaPushMessage

AbrovaPush.setCallback(object : AbrovaPushCallbackAdapter() {
    override fun onNotificationAction(message: AbrovaPushMessage, actionId: String) {
        Log.d("AbrovaPush", "Action tapped: $actionId")
        Log.d("AbrovaPush", "Data: ${message.data}")

        when (actionId) {
            "view" -> {
                val productId = message.data?.get("productId") as? String
                // Navigate to product
            }
            "dismiss" -> {
                // Handle dismiss
            }
        }
    }
})
```

#### iOS

Implement the `AbrovaPushDelegate` method (see [Callbacks](/docs/push/callbacks)):

```swift
import AbrovaPushSDK

class PushHandler: NSObject, AbrovaPushDelegate {
    func abrovaPush(_ abrovaPush: AbrovaPush, didReceiveNotificationAction action: NotificationAction, forMessage message: AbrovaPushMessage) {
        print("Action tapped: \(action.id)")
        print("Data: \(message.data ?? [:])")

        switch action.id {
        case "view":
            if let productId = message.data?["productId"]?.value as? String {
                // Navigate to product
            }
        case "dismiss":
            break // Handle dismiss
        default:
            break
        }
    }
}

// Keep a strong reference: `delegate` is weak
let pushHandler = PushHandler()
AbrovaPush.shared.delegate = pushHandler
```

#### React Native

```typescript
import AbrovaPush from 'abrova-push-react-native';

AbrovaPush.onNotificationAction((event) => {
  console.log('Action tapped:', event.actionId);
  console.log('Title:', event.title);
  console.log('Data:', event.data);

  if (event.actionId === 'view') {
    navigation.navigate('Product', { id: event.data?.productId });
  }
});
```

#### Web

The SDK's service worker handles `notificationclick`: it opens the clicked action's `action` URL (or the message `deepLink`) and reports the click to the page. Listen for it with `onActionClicked`:

```typescript
abrovaPush.onActionClicked((actionId, message) => {
  console.log('Action tapped:', actionId);

  if (actionId === 'view') {
    window.location.href = '/product/' + message.data?.productId;
  }
});
```

<H2 id="image-requirements" step={6}>Image Requirements</H2>

<div>
  <div>
    <div>
      <h3>Large Image (imageUrl)</h3>
      <ul>
        <li>Format: JPEG, PNG, GIF</li>
        <li>Max size: 1MB</li>
        <li>Recommended: 1024x512px (2:1 ratio)</li>
        <li>Must be HTTPS URL</li>
      </ul>
    </div>
    <div>
      <h3>Icon (iconUrl)</h3>
      <ul>
        <li>Format: PNG (transparent)</li>
        <li>Max size: 256KB</li>
        <li>Recommended: 192x192px</li>
        <li>Used by Web notifications</li>
      </ul>
    </div>
  </div>
</div>

<H2 id="example-rich-notification-payload" step={7}>Example: Rich Notification Payload</H2>

```json
{
  "userId": "user_123",
  "title": "Flash Sale! 50% Off",
  "body": "Your favorite items are on sale for the next 2 hours",
  "imageUrl": "https://cdn.example.com/sales/flash-sale-banner.jpg",
  "iconUrl": "https://cdn.example.com/icons/sale-icon.png",
  "sound": "sale_alert",
  "badge": 1,
  "priority": "high",
  "ttl": 7200,
  "collapseKey": "flash_sale",
  "actions": [
    { "id": "shop_now", "title": "Shop Now", "action": "OPEN_SALE" },
    { "id": "remind_later", "title": "Remind Me", "action": "SET_REMINDER" }
  ],
  "data": {
    "saleId": "sale_flash_001",
    "expiresAt": "2024-01-15T12:00:00Z",
    "deepLink": "/sales/flash"
  }
}
```

- Delivery receipts: https://abrova.ir/en/docs/push/receipts

Track notification delivery, opens, clicks, and dismissals in real-time.

<H2 id="receipt-statuses" step={1}>Receipt Statuses</H2>

<ConfigTable
  headers={['Status', 'Description']}
  rows={[
    ['sent', 'Message handed to the transport (APNs, Web Push, the Abrova connection or FCM)'],
    ['delivered', 'Confirmed delivery to device'],
    ['opened', 'User opened/viewed the notification'],
    ['clicked', 'User tapped an action button'],
    ['dismissed', 'User dismissed the notification'],
    ['failed', 'Delivery failed (invalid token, etc.)'],
  ]}
/>

<Callout kind="warn" title="iOS needs one extra step to report `delivered`">
APNs confirms only that Apple accepted a notification, never that it arrived, so
iOS devices stay at `sent` until you add a Notification Service Extension. It is
optional and takes a few minutes — see
[iOS Delivery Confirmation](/docs/push/ios). Notifications shown
while the app is in the foreground, tapped, or received over the real-time
connection are confirmed by the app itself. Android and Web confirm delivery on
their own, with no extra setup.
</Callout>

<Callout kind="note" title="Receipts for every send type">
Per-device receipts are created for every send: to a user, a device, a list of
devices, a topic, a segment, or a broadcast. Each targeted device gets one.
</Callout>

The **Delivery** page in the [Abrova Console](https://console.abrova.ir) shows
sent, delivered and failed counts per platform, with the most common failure
reasons, and a filterable receipt log.

### Transports

Which path carried a notification. Every receipt records one.

<ConfigTable
  headers={['Transport', 'Description']}
  rows={[
    ['apns', 'Apple Push Notification service (iOS)'],
    ['voip', 'PushKit VoIP push (iOS calling apps)'],
    ['webpush', 'Web Push (browsers)'],
    ['pn', 'The Abrova connection (Android)'],
    ['fcm', 'Firebase, when the optional [Android FCM bridge](/docs/push/android-fcm) is set up'],
  ]}
/>

With the FCM bridge on, a push travels over both Android paths. `deliveredVia` then says which copy the device received first, `pn` or `fcm`.

<H2 id="get-message-stats" step={2}>Get Message Stats</H2>

Aggregate delivery / open / click rates for a single message.

```bash
curl -X GET "https://push-api.abrova.ir/receipts/message/msg_abc123/stats" \
  -H "x-api-key: ab_live_your_api_key" \
  -H "x-server-secret: ab_srv_your_server_secret"
```

#### Response

```json
{
  "total": 1000,
  "sent": 980,
  "delivered": 950,
  "opened": 450,
  "clicked": 120,
  "failed": 20,
  "deliveryRate": 96.94,
  "openRate": 47.37,
  "clickRate": 12.63
}
```

<H2 id="get-individual-receipts" step={3}>Get Individual Receipts</H2>

Per-device receipt for a single message — includes timestamps for each lifecycle stage and the action button tapped.

```bash
curl -X GET "https://push-api.abrova.ir/receipts/message/msg_abc123" \
  -H "x-api-key: ab_live_your_api_key" \
  -H "x-server-secret: ab_srv_your_server_secret"
```

#### Response

Returns an array of receipts, newest first.

```json
[
    {
      "id": "rcpt_1",
      "messageId": "msg_abc123",
      "deviceId": "dev_xyz",
      "platform": "ios",
      "status": "clicked",
      "sentAt": "2024-01-15T10:00:00Z",
      "deliveredAt": "2024-01-15T10:00:01Z",
      "openedAt": "2024-01-15T10:05:00Z",
      "clickedAt": "2024-01-15T10:05:30Z",
      "actionId": "shop_now"
    },
    {
      "id": "rcpt_2",
      "messageId": "msg_abc123",
      "deviceId": "dev_abc",
      "platform": "android",
      "status": "failed",
      "sentAt": "2024-01-15T10:00:00Z",
      "error": "InvalidRegistration"
    }
]
```

<H2 id="get-action-stats" step={4}>Get Action Stats</H2>

See which action buttons users clicked most.

```bash
curl -X GET "https://push-api.abrova.ir/receipts/message/msg_abc123/actions" \
  -H "x-api-key: ab_live_your_api_key" \
  -H "x-server-secret: ab_srv_your_server_secret"
```

#### Response

```json
[
  { "actionId": "shop_now", "count": "85" },
  { "actionId": "remind_later", "count": "35" }
]
```

`count` is returned as a string.

<H2 id="get-device-receipts" step={5}>Get Device Receipts</H2>

Receipt history for a specific device, newest first. `limit` defaults to 50. Each receipt includes its parent `message` object (title, body, ...).

```bash
curl -X GET "https://push-api.abrova.ir/receipts/device/dev_xyz?limit=20" \
  -H "x-api-key: ab_live_your_api_key" \
  -H "x-server-secret: ab_srv_your_server_secret"
```

#### Response

```json
[
  {
    "id": "rcpt_1",
    "messageId": "msg_abc123",
    "deviceId": "dev_xyz",
    "status": "opened",
    "sentAt": "2024-01-15T10:00:00Z",
    "openedAt": "2024-01-15T10:05:00Z",
    "message": { "id": "msg_abc123", "title": "New message", "body": "..." }
  },
  {
    "id": "rcpt_2",
    "messageId": "msg_def456",
    "deviceId": "dev_xyz",
    "status": "clicked",
    "sentAt": "2024-01-14T15:30:00Z",
    "clickedAt": "2024-01-14T15:32:00Z",
    "actionId": "view_order",
    "message": { "id": "msg_def456", "title": "Order update", "body": "..." }
  }
]
```

<H2 id="get-app-wide-stats" step={6}>Get App-wide Stats</H2>

Aggregate stats across the app that owns your API key, for a date range. Without `startDate`/`endDate` it covers the last 30 days. `deliveryRate` here is `delivered / totalRecipients`.

```bash
curl -X GET "https://push-api.abrova.ir/receipts/stats?startDate=2024-01-01&endDate=2024-01-31" \
  -H "x-api-key: ab_live_your_api_key" \
  -H "x-server-secret: ab_srv_your_server_secret"
```

#### Response

```json
{
  "totalMessages": 150,
  "totalRecipients": 45000,
  "delivered": 43500,
  "opened": 18000,
  "clicked": 4500,
  "failed": 1500,
  "deliveryRate": 96.67,
  "openRate": 41.38,
  "clickRate": 10.34
}
```

<H2 id="sdk-integration" step={7}>SDK Integration</H2>

Receipts are tracked automatically by the SDKs. The only manual hook is on iOS: if the SDK is not your `UNUserNotificationCenter` delegate, call `AbrovaPush.shared.handleRemoteNotification(userInfo:)` from `application(_:didReceiveRemoteNotification:fetchCompletionHandler:)`. Each message is confirmed once per device, and redeliveries are not counted twice. Ensure you have the latest version installed:

<ConfigTable
  headers={['Platform', 'What confirms delivery']}
  rows={[
    ['Android', 'The SDK, for every notification the device receives'],
    ['iOS', 'The SDK for foreground, tapped and real-time messages; a Notification Service Extension for background APNs notifications'],
    ['Web', 'The service worker for Web Push, and the SDK for messages received while the page is open'],
  ]}
/>

<H2 id="webhooks-for-receipts" step={8}>Webhooks for Receipts</H2>

When a device confirms delivery, a `message.delivered` webhook fires:

```json
{
  "event": "message.delivered",
  "timestamp": "2024-01-15T10:00:01Z",
  "webhookId": "wh_123",
  "data": {
    "messageId": "msg_abc123",
    "deviceId": "dev_xyz",
    "title": "New message"
  }
}
```

#### Available Webhook Events

- `message.sent` — Message sent
- `message.delivered` — A device confirmed delivery
- `message.failed` — Delivery failed
- `message.no_recipients` — The target had no registered devices
- `device.registered`, `device.unregistered`, `device.updated` — Device lifecycle

Opens, clicks and dismissals are recorded on the receipt but do not fire webhooks.

- In-app messages: https://abrova.ir/en/docs/push/in-app

Display targeted messages to users while they're actively using your app. Perfect for onboarding, feature announcements, promotions, and contextual tips.

<H2 id="key-features" step={1}>Key Features</H2>

<div>
  <div>
    <div>
      <div></div>
      <div>
        <p>Multiple Message Types</p>
        <p>Modal, Banner, Fullscreen, and Card formats</p>
      </div>
    </div>
    <div>
      <div></div>
      <div>
        <p>Smart Triggers</p>
        <p>On app open, custom events, or session start, within an optional start/end date window</p>
      </div>
    </div>
    <div>
      <div></div>
      <div>
        <p>User Targeting</p>
        <p>Target by segments, user IDs, or properties</p>
      </div>
    </div>
    <div>
      <div></div>
      <div>
        <p>Built-in Analytics</p>
        <p>Track impressions, clicks, and conversions</p>
      </div>
    </div>
  </div>
</div>

<H2 id="message-types" step={2}>Message Types</H2>

<div>
  <div>
    <h3>Modal</h3>
    <p>Centered popup dialog that requires user action. Best for important announcements or confirmations.</p>
  </div>
  <div>
    <h3>Banner</h3>
    <p>Top or bottom bar that doesn't interrupt the user flow. Good for tips and non-urgent messages.</p>
  </div>
  <div>
    <h3>Fullscreen</h3>
    <p>Full screen takeover for maximum impact. Ideal for onboarding or major announcements.</p>
  </div>
  <div>
    <h3>Card</h3>
    <p>Floating card notification that appears in corner. Perfect for contextual tips.</p>
  </div>
</div>

<H2 id="using-the-dashboard" step={3}>Using the Dashboard</H2>

1. In the Abrova Console sidebar, open **AbrovaPush → In-App**
2. Click **Create Message** and choose your message type
3. **Configure Trigger** — Select when the message should appear (on app open, event, etc.)
4. **Add Content** — Set title, body, image, and action buttons
5. **Activate** — Save as draft or activate immediately

<H2 id="trigger-types" step={4}>Trigger Types</H2>

<ConfigTable
  headers={['Trigger', 'Description', 'Use Case']}
  rows={[
    ['on_app_open', 'Shows when user opens the app', 'Announcements, promotions'],
    ['on_event', 'Shows when specific event is tracked', 'Feature discovery, tips'],
    ['on_session_start', 'Shows at the start of each session', 'Daily tips, streaks'],
    ['scheduled', 'Not fired automatically by the SDKs: fetch it and call showInAppMessage(id); limit the window with startDate/endDate', 'Time-sensitive offers'],
    ['manual', 'Shown only when your app calls showInAppMessage(id)', 'Custom logic'],
  ]}
/>

<H2 id="flutter" step={5}>Flutter</H2>

**Required:** wrap your app with `AbrovaPushInAppOverlay`. The Flutter plugin forwards every in-app message to Dart; the native SDK does not render its own UI. Without this widget, messages fetch and match but nothing displays.

```dart
import 'package:abrova_push/abrova_push.dart';

MaterialApp(
  builder: (context, child) => AbrovaPushInAppOverlay(
    onButtonTap: (context, message, button) {
      if (button.action == InAppButtonAction.deepLink && button.value != null) {
        Navigator.pushNamed(context, button.value!);
      }
    },
    child: child ?? const SizedBox.shrink(),
  ),
  home: const HomePage(),
);
```

The overlay renders modal, banner, fullscreen, and card messages out of the box, records impressions/clicks/dismisses, respects `Directionality` (RTL), `Theme.of(context).brightness` (dark mode), and safe areas.

**Customize styling** with `AbrovaPushInAppTheme`:

```dart
AbrovaPushInAppOverlay(
  theme: const AbrovaPushInAppTheme(
    modalBorderRadius: 24,
    modalMaxWidth: 360,
    bannerBackgroundColor: Color(0xFF1E1E1E),
    bannerTextColor: Colors.white,
    animationDuration: Duration(milliseconds: 260),
  ),
  child: child!,
);
```

**Fully replace a renderer** with `AbrovaPushInAppBuilders` (any type left null falls back to the default):

```dart
AbrovaPushInAppOverlay(
  builders: AbrovaPushInAppBuilders(
    banner: (context, message, content, actions) => MyBanner(
      title: content.title,
      body: content.body,
      onTap: () => actions.onButtonTap(content.buttons.first),
      onClose: actions.onDismiss,
    ),
  ),
  child: child!,
);
```

```dart
// 1. Initialize AbrovaPush (only apiKey required)
await AbrovaPush.init(AbrovaPushConfig(
  apiKey: 'ab_live_your_api_key',
));

// 2. Register device (required for in-app messages to work)
await AbrovaPush.register();

// 3. Trigger in-app messages based on your trigger type
// For "on_app_open" trigger:
await AbrovaPush.triggerInAppOnAppOpen();

// For "on_event" trigger (e.g., after purchase):
await AbrovaPush.triggerInAppEvent('purchase_completed',
  properties: {'amount': 99.99});

// For "on_session_start" trigger:
await AbrovaPush.triggerInAppOnSessionStart();

// Or manually fetch and show a specific message:
final messages = await AbrovaPush.fetchInAppMessages();
if (messages.isNotEmpty) {
  await AbrovaPush.showInAppMessage(messages.first.id);
}

// Dismiss current message programmatically:
await AbrovaPush.dismissInAppMessage();
```

<H2 id="android" step={6}>Android</H2>

The SDK shows messages with its built-in UI when the current Activity is set with `AbrovaPush.setCurrentActivity(this)` (call it in `onResume()`) and **no** `InAppMessageCallback` is set. Setting a callback hands rendering to you: the SDK then records the impression and calls `onMessageReady`, but shows nothing (this is how the Flutter and React Native wrappers take over). `onButtonClicked` and `onMessageDismissed` are called only by the built-in UI, which does not run while a callback is set.

```kotlin
import ir.abrova.push.sdk.AbrovaPush
import ir.abrova.push.sdk.inapp.*

// Built-in UI: tell the SDK which Activity to draw on (in onResume)
AbrovaPush.setCurrentActivity(this)

// Optional, only if you render messages yourself (disables the built-in UI)
AbrovaPush.setInAppMessageCallback(object : InAppMessageCallback {
    override fun onMessageReady(message: InAppMessage) {
        // Render the message with your own UI
        Log.d("InApp", "Message ready: ${message.id}")
    }

    override fun onButtonClicked(message: InAppMessage, button: InAppButton) {
        // Handle button click
        when (button.action) {
            InAppButtonAction.DEEP_LINK -> {
                // Navigate to deep link
                val intent = Intent(Intent.ACTION_VIEW, Uri.parse(button.value))
                startActivity(intent)
            }
            InAppButtonAction.URL -> {
                // Open URL in browser
                val intent = Intent(Intent.ACTION_VIEW, Uri.parse(button.value))
                startActivity(intent)
            }
            InAppButtonAction.CUSTOM -> {
                // Handle custom action
                handleCustomAction(button.value)
            }
            else -> {} // Dismiss handled automatically
        }
    }

    override fun onMessageDismissed(message: InAppMessage) {
        Log.d("InApp", "Message dismissed: ${message.id}")
    }

    override fun onError(error: String) {
        Log.e("InApp", "In-app error: $error")
    }
})

// Trigger in-app messages
AbrovaPush.triggerInAppOnAppOpen()
AbrovaPush.triggerInAppEvent("viewed_product")
AbrovaPush.triggerInAppOnSessionStart()

// Or manually fetch and show messages
AbrovaPush.fetchInAppMessages { messages ->
    if (messages.isNotEmpty()) {
        AbrovaPush.showInAppMessage(messages.first().id)
    }
}

// Dismiss current message
AbrovaPush.dismissInAppMessage()
```

<H2 id="ios" step={7}>iOS</H2>

As on Android, the built-in UI needs a view controller to present from (`AbrovaPush.shared.setCurrentViewController(_:)`) and runs only while **no** `InAppMessageCallback` is set. With a callback set, the SDK records the impression and calls `inAppMessageReady` but shows nothing; `inAppMessageButtonClicked` and `inAppMessageDismissed` come only from the built-in UI.

```swift
import AbrovaPushSDK

// Built-in UI: give the SDK a view controller to present from
AbrovaPush.shared.setCurrentViewController(viewController)

// Optional, only if you render messages yourself (disables the built-in UI)
class MyInAppHandler: InAppMessageCallback {
    func inAppMessageReady(_ message: InAppMessage) {
        print("Message ready: \(message.id)")
    }

    func inAppMessageButtonClicked(_ message: InAppMessage, button: InAppButton) {
        switch button.action {
        case .deepLink:
            if let urlString = button.value, let url = URL(string: urlString) {
                UIApplication.shared.open(url)
            }
        case .url:
            if let urlString = button.value, let url = URL(string: urlString) {
                UIApplication.shared.open(url)
            }
        case .custom:
            handleCustomAction(button.value)
        default:
            break // Dismiss handled automatically
        }
    }

    func inAppMessageDismissed(_ message: InAppMessage) {
        print("Message dismissed: \(message.id)")
    }

    func inAppMessageError(_ error: String) {
        print("In-app error: \(error)")
    }
}

// Register the callback. It is held weakly, so keep a strong reference.
let inAppHandler = MyInAppHandler()
AbrovaPush.shared.setInAppMessageCallback(inAppHandler)

// Trigger in-app messages
AbrovaPush.shared.triggerInAppOnAppOpen()
AbrovaPush.shared.triggerInAppEvent("viewed_product")
AbrovaPush.shared.triggerInAppOnSessionStart()

// Or manually fetch and show messages
AbrovaPush.shared.fetchInAppMessages { messages in
    if let first = messages.first {
        AbrovaPush.shared.showInAppMessage(first.id)
    }
}

// Dismiss current message
AbrovaPush.shared.dismissInAppMessage()
```

<H2 id="react-native" step={8}>React Native</H2>

```typescript
import AbrovaPush, { InAppButtonAction } from 'abrova-push-react-native';

// The React Native wrapper has no built-in in-app UI yet: when a trigger matches,
// the native SDK records the impression and emits onInAppMessageReady, and your
// app renders the message. onInAppButtonClick / onInAppMessageDismissed come only
// from the native SDKs' built-in UI, which the wrapper turns off, so they do not fire.
// To fetch messages and emit one manually:
const messages = await AbrovaPush.fetchInAppMessages();
if (messages.length > 0) {
  await AbrovaPush.showInAppMessage(messages[0].id);
}

// Render the message yourself when it is ready
AbrovaPush.onInAppMessageReady((message) => {
  console.log('Message ready:', message.id);
  // e.g. show your own modal from message.content; for its buttons:
  // if (button.action === InAppButtonAction.DEEP_LINK && button.value) {
  //   navigation.navigate(button.value);
  // }
});

// Trigger messages
await AbrovaPush.triggerInAppOnAppOpen();
await AbrovaPush.triggerInAppEvent('viewed_product');
await AbrovaPush.triggerInAppOnSessionStart();
```

<H2 id="web" step={9}>Web</H2>

Requires `@abrova/push-web` 0.1.7 or newer, and a registered device. In-app messages are on by default and render in a built-in shadow-DOM UI.

```typescript
import AbrovaPush from '@abrova/push-web';

const abrovaPush = new AbrovaPush({
  apiKey: 'ab_live_your_api_key',
  inApp: {
    // enabled: true,        // default
    // display: 'auto',      // 'manual' = render nothing, only fire onMessageReady
    // autoTrigger: false,   // true = fire on_session_start + on_app_open on page load
    // bannerPosition: 'top',
  },
});
await abrovaPush.register({ userId: 'user_123' });

// Trigger messages
await abrovaPush.inApp.triggerOnAppOpen();
await abrovaPush.inApp.triggerEvent('viewed_product', { productId: 'prod_123' });
await abrovaPush.inApp.triggerSessionStart();

// Or fetch and show one manually
const messages = await abrovaPush.inApp.fetchMessages();
if (messages.length > 0) {
  await abrovaPush.inApp.showMessage(messages[0].id);
}

// Listen to interactions (each returns an unsubscribe function)
abrovaPush.inApp.onMessageReady((message) => console.log('Ready:', message.id));
abrovaPush.inApp.onButtonClicked((message, button) => {
  // url / deep_link buttons are opened in a new tab by the SDK;
  // custom buttons are left to your app
  if (button.action === 'custom') {
    handleCustomAction(button.value);
  }
});
abrovaPush.inApp.onDismissed((message) => console.log('Dismissed:', message.id));

// Close the message on screen
abrovaPush.inApp.dismissCurrentMessage();
```

<H2 id="configuration-options" step={10}>Configuration Options</H2>

<ConfigTable
  headers={['Option', 'Type', 'Description']}
  rows={[
    ['maxImpressions', 'number', 'Maximum times to show this message to each device, 1 to 100 (default: 1)'],
    ['delaySeconds', 'number', 'Wait time after trigger before showing message (default: 0)'],
    ['minSessionCount', 'number', 'Only show to users with at least this many sessions (engagement targeting)'],
    ['priority', 'number', 'Higher priority messages display first when multiple match (default: 0)'],
    ['startDate', 'date', 'Message becomes active on this date (scheduling)'],
    ['endDate', 'date', 'Message stops showing after this date (scheduling)'],
    ['segmentId', 'string', 'Show only to devices in this saved segment (mutually exclusive with targetUserIds)'],
    ['targetUserIds', 'string[]', 'Show only to specific user IDs (mutually exclusive with segmentId)'],
    ['content.backgroundColor', 'string', 'Custom background color (hex, e.g., #FFFFFF)'],
    ['content.textColor', 'string', 'Custom text color (hex, e.g., #000000)'],
  ]}
/>

<Callout kind="note">
**Audience targeting is mutually exclusive.** A message reaches its audience one of three ways:

1. **Everyone** — set neither `segmentId` nor `targetUserIds` (default).
2. **A segment** — set `segmentId` to a saved segment UUID. Segment membership is checked on every fetch and matches the Console preview.
3. **Explicit user list** — set `targetUserIds` to an array of user IDs (as set via SDK `setUserId()`).

Setting both `segmentId` and `targetUserIds` is rejected by the API — the dashboard's Audience picker enforces the same rule visually.
</Callout>

<H2 id="button-actions" step={11}>Button Actions</H2>

Configure what happens when users tap buttons on your in-app messages.

<ConfigTable
  headers={['Action', 'Value', 'Description']}
  rows={[
    ['dismiss', '-', 'Simply closes the message'],
    ['deep_link', 'myapp://screen/123', 'Opens an in-app screen via deep link'],
    ['url', 'https://example.com', 'Opens a URL in the browser'],
    ['custom', 'any_custom_value', 'Custom action handled by your app code via callback'],
  ]}
/>

#### Handling Custom Actions

In Flutter, handle them in the overlay's `onButtonTap` (the overlay renders the message, so the native `onInAppButtonClick` callback does not fire for it):

```dart
AbrovaPushInAppOverlay(
  onButtonTap: (context, message, button) {
    if (button.action == InAppButtonAction.custom) {
      switch (button.value) {
        case 'share_promo':
          Share.share('Use code SUMMER20 for 20% off!');
          break;
        case 'rate_app':
          StoreRedirect.redirect(
            androidAppId: 'com.yourapp',
            iOSAppId: '123456789'
          );
          break;
        case 'start_subscription':
          Navigator.pushNamed(context, '/subscription');
          break;
        case 'play_video':
          showVideoPlayer(videoUrl: 'https://...');
          break;
      }
    }
  },
  child: child!,
);
```

<H2 id="common-use-cases" step={12}>Common Use Cases</H2>

<div>
  <div>
    <h3>Onboarding</h3>
    <p>Welcome new users and guide them through your app.</p>
    <ul>
      <li>• Type: <span>Fullscreen</span></li>
      <li>• Trigger: <span>on_app_open</span></li>
      <li>• minSessionCount: <span>0</span> (no minimum, so new users qualify)</li>
      <li>• maxImpressions: <span>1</span></li>
    </ul>
  </div>
  <div>
    <h3>Feature Announcement</h3>
    <p>Introduce new features to existing users.</p>
    <ul>
      <li>• Type: <span>Modal</span></li>
      <li>• Trigger: <span>on_app_open</span></li>
      <li>• minSessionCount: <span>5</span> (engaged users)</li>
      <li>• delaySeconds: <span>3</span></li>
    </ul>
  </div>
  <div>
    <h3>Contextual Tip</h3>
    <p>Show tips when users visit specific screens.</p>
    <ul>
      <li>• Type: <span>Banner</span> or <span>Card</span></li>
      <li>• Trigger: <span>on_event</span></li>
      <li>• Event: <span>viewed_settings</span></li>
      <li>• maxImpressions: <span>2</span></li>
    </ul>
  </div>
  <div>
    <h3>Time-Limited Promotion</h3>
    <p>Run limited-time offers with scheduling.</p>
    <ul>
      <li>• Type: <span>Modal</span></li>
      <li>• Trigger: <span>on_app_open</span></li>
      <li>• startDate/endDate: <span>Campaign dates</span></li>
      <li>• maxImpressions: <span>3</span></li>
    </ul>
  </div>
  <div>
    <h3>Post-Purchase Upsell</h3>
    <p>Cross-sell after a successful purchase.</p>
    <ul>
      <li>• Type: <span>Card</span></li>
      <li>• Trigger: <span>on_event</span></li>
      <li>• Event: <span>purchase_completed</span></li>
      <li>• delaySeconds: <span>2</span></li>
    </ul>
  </div>
  <div>
    <h3>VIP User Message</h3>
    <p>Target specific high-value users.</p>
    <ul>
      <li>• Type: <span>Modal</span></li>
      <li>• Trigger: <span>on_app_open</span></li>
      <li>• targetUserIds: <span>[user1, user2]</span></li>
      <li>• priority: <span>10</span> (show first)</li>
    </ul>
  </div>
</div>

<H2 id="best-practices" step={13}>Best Practices</H2>

<div>
  <div>
    <h3>Do</h3>
    <ul>
      <li>• Keep messages concise and actionable</li>
      <li>• Use appropriate message type for context</li>
      <li>• Set frequency caps to avoid fatigue</li>
      <li>• A/B test different message variations</li>
      <li>• Target messages to relevant user segments</li>
      <li>• Use scheduling for time-sensitive campaigns</li>
      <li>• Add delay to avoid interrupting app launch</li>
      <li>• Use minSessionCount to target engaged users</li>
    </ul>
  </div>
  <div>
    <h3>Don't</h3>
    <ul>
      <li>• Show too many messages per session</li>
      <li>• Use fullscreen for minor updates</li>
      <li>• Interrupt critical user flows</li>
      <li>• Forget to add a dismiss option</li>
      <li>• Use aggressive or misleading CTAs</li>
      <li>• Set maxImpressions too high (causes fatigue)</li>
      <li>• Show messages immediately on app open (use delay)</li>
      <li>• Target new users with advanced feature tips</li>
    </ul>
  </div>
</div>

<H2 id="analytics-metrics" step={14}>Analytics & Metrics</H2>

Track the performance of your in-app messages with built-in analytics.

<ConfigTable
  headers={['Metric', 'Description', 'Tracked Automatically']}
  rows={[
    ['Impressions', 'Number of times the message was displayed', 'Yes'],
    ['Clicks', 'Number of button clicks on the message', 'Yes'],
    ['Dismissals', 'Number of times users dismissed the message', 'Yes'],
    ['Click Rate', 'Clicks / Impressions × 100%', 'Yes'],
  ]}
/>

- Inbox: https://abrova.ir/en/docs/push/inbox

A persistent message center for your users. Unlike push notifications, inbox messages are stored and can be retrieved later — users never miss important updates.

<H2 id="why-use-message-inbox" step={1}>Why Use Message Inbox?</H2>

<div>
  <div>
    <div>
      <div></div>
      <div>
        <p>Persistent Storage</p>
        <p>Messages are stored and accessible anytime, unlike ephemeral push notifications</p>
      </div>
    </div>
    <div>
      <div></div>
      <div>
        <p>Read Tracking</p>
        <p>Know when users read your messages with built-in analytics</p>
      </div>
    </div>
    <div>
      <div></div>
      <div>
        <p>Category Filtering</p>
        <p>Organize messages by category (promotions, updates, alerts)</p>
      </div>
    </div>
    <div>
      <div></div>
      <div>
        <p>User Control</p>
        <p>Users can archive, delete, or mark messages as read</p>
      </div>
    </div>
  </div>
</div>

<H2 id="use-cases" step={2}>Use Cases</H2>

<div>
  <div>
    <h3>Announcements</h3>
    <p>Product updates, new features, company news that users should be able to reference later.</p>
  </div>
  <div>
    <h3>Promotions</h3>
    <p>Special offers, discounts, and deals with expiration dates that users can redeem at their convenience.</p>
  </div>
  <div>
    <h3>Transactional</h3>
    <p>Order updates, account alerts, and important notifications that need to be preserved.</p>
  </div>
</div>

<H2 id="using-the-dashboard" step={3}>Using the Dashboard</H2>

In Abrova Console, open **AbrovaPush → Inbox**. It provides four ways to send messages:

<div>
  <div>
    <div>
      <div>Send to User</div>
      <p>Send a message to a specific user by their ID</p>
    </div>
    <div>
      <div>Send to Device</div>
      <p>Send a message to a specific device by its device ID</p>
    </div>
    <div>
      <div>Send to Multiple</div>
      <p>Send to multiple users by providing a comma-separated list of user IDs</p>
    </div>
    <div>
      <div>Broadcast to All</div>
      <p>Send to all users of your app at once</p>
    </div>
  </div>
</div>

<H2 id="send-to-user" step={4}>Send to User</H2>

#### Node.js SDK

```typescript
import { AbrovaPush } from '@abrova/push-node';

const abrovaPush = new AbrovaPush({
  apiKey: 'ab_live_your_api_key',
  serverSecret: 'ab_srv_your_server_secret',
});

await abrovaPush.inbox.sendToUser({
  userId: 'user_123',
  content: {
    title: 'New Promotion!',
    body: 'Get 20% off your next purchase',
    imageUrl: 'https://example.com/promo.jpg',
    deepLink: 'myapp://promotions/123',
  },
  category: 'promotions',
  expiresAt: '2024-02-01T00:00:00Z',
});
```

#### REST API

```bash
curl -X POST "https://push-api.abrova.ir/inbox/api/send-to-user" \
  -H "x-api-key: ab_live_your_api_key" \
  -H "x-server-secret: ab_srv_your_server_secret" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "user_123",
    "content": {
      "title": "New Promotion!",
      "body": "Get 20% off your next purchase",
      "imageUrl": "https://example.com/promo.jpg",
      "deepLink": "myapp://promotions/123"
    },
    "category": "promotions",
    "expiresAt": "2024-02-01T00:00:00Z"
  }'
```

<H2 id="send-to-multiple-users" step={5}>Send to Multiple Users</H2>

#### Node.js SDK

```typescript
await abrovaPush.inbox.sendToUsers({
  userIds: ['user_123', 'user_456', 'user_789'],
  content: {
    title: 'Flash Sale!',
    body: 'Limited time offer for VIP members',
  },
  category: 'promotions',
});
```

#### REST API

```bash
curl -X POST "https://push-api.abrova.ir/inbox/api/send-to-users" \
  -H "x-api-key: ab_live_your_api_key" \
  -H "x-server-secret: ab_srv_your_server_secret" \
  -H "Content-Type: application/json" \
  -d '{
    "userIds": ["user_123", "user_456", "user_789"],
    "content": {
      "title": "Flash Sale!",
      "body": "Limited time offer for VIP members"
    },
    "category": "promotions"
  }'
```

<H2 id="broadcast-to-all-users" step={6}>Broadcast to All Users</H2>

#### Node.js SDK

```typescript
await abrovaPush.inbox.broadcast({
  content: {
    title: 'App Update Available',
    body: 'We have released new features! Check them out.',
  },
  category: 'announcements',
});
```

#### REST API

```bash
curl -X POST "https://push-api.abrova.ir/inbox/api/broadcast" \
  -H "x-api-key: ab_live_your_api_key" \
  -H "x-server-secret: ab_srv_your_server_secret" \
  -H "Content-Type: application/json" \
  -d '{
    "content": {
      "title": "App Update Available",
      "body": "We have released new features! Check them out."
    },
    "category": "announcements"
  }'
```

<H2 id="message-fields" step={7}>Message Fields</H2>

<ConfigTable rows={[
  ['content.title', 'string', 'Yes', 'Message title'],
  ['content.body', 'string', 'Yes', 'Message body'],
  ['content.imageUrl', 'string', 'No', 'Image URL to display with message'],
  ['content.iconUrl', 'string', 'No', 'Small icon/avatar for the message'],
  ['content.deepLink', 'string', 'No', 'Deep link to open when message is tapped'],
  ['content.data', 'object', 'No', 'Custom key/value data for your app'],
  ['localizations', 'array', 'No', 'Per-locale content: [{ locale, content }]'],
  ['category', 'string', 'No', 'Category for filtering (e.g., "promotions", "orders")'],
  ['expiresAt', 'ISO 8601', 'No', 'Expiration date (message hidden after this date)'],
]} />

<Callout kind="warn" title="Signed user tokens">
Abrova Console has a project setting, **Require signed user tokens for the inbox** (Project Settings → Abrova Push). With it on, the inbox read/update routes the SDKs call only serve a user's messages when the request carries an `x-user-token` minted by your server; otherwise they return `401` with `code: "token_required"`. The Push client SDKs below do not send this header yet, so leave the setting off unless your app calls the inbox API itself with the token. Device-only inboxes and push delivery are not affected.
</Callout>

<H2 id="flutter" step={8}>Flutter</H2>

```dart
// Fetch inbox messages
final response = await AbrovaPush.getInboxMessages(
  status: InboxMessageStatus.unread, // omit for all; unread, read, archived
  category: 'promotions', // optional filter
  limit: 20,
  offset: 0,
);
print('Total: ${response.total}, Unread: ${response.unreadCount}');

// Display messages in your UI
for (final message in response.messages) {
  print('Title: ${message.content.title}');
  print('Body: ${message.content.body}');
  print('Status: ${message.status}');
  print('Read at: ${message.readAt}');
}

// Mark message as read
await AbrovaPush.markInboxMessageAsRead(message.id);

// Mark multiple messages with a status
await AbrovaPush.markMultipleInboxMessages(
  ['msg_1', 'msg_2', 'msg_3'],
  InboxMessageStatus.read,
);

// Mark all messages as read
await AbrovaPush.markAllInboxMessagesAsRead();

// Archive a message
await AbrovaPush.archiveInboxMessage(message.id);

// Delete a message
await AbrovaPush.deleteInboxMessage(message.id);

// Get unread count for badge (cached; fetchInboxUnreadCount() asks the server)
final unreadCount = await AbrovaPush.getInboxUnreadCount();
print('Unread messages: $unreadCount');

// Listen to new inbox messages
AbrovaPush.onInboxMessage((message) {
  print('New inbox message: ${message.content.title}');
  // Update your UI or show a badge
});
```

<H2 id="react-native" step={9}>React Native</H2>

```typescript
import AbrovaPush, { InboxMessageStatus } from 'abrova-push-react-native';

// Fetch inbox messages
const { messages, total, unreadCount } = await AbrovaPush.getInboxMessages({
  status: InboxMessageStatus.UNREAD, // omit for all; UNREAD, READ, ARCHIVED
  category: 'promotions', // optional filter
  limit: 20,
  offset: 0,
});

// Display in FlatList or custom UI
messages.forEach(message => {
  console.log('Title:', message.content.title);
  console.log('Body:', message.content.body);
  console.log('Status:', message.status);
});

// Mark message as read
await AbrovaPush.markInboxMessageAsRead(message.id);

// Mark multiple messages with a status
await AbrovaPush.markMultipleInboxMessages(['msg_1', 'msg_2'], InboxMessageStatus.READ);

// Mark all messages as read
await AbrovaPush.markAllInboxMessagesAsRead();

// Archive a message
await AbrovaPush.archiveInboxMessage(message.id);

// Delete a message
await AbrovaPush.deleteInboxMessage(message.id);

// Get unread count for badge (cached; fetchInboxUnreadCount() asks the server)
const badgeCount = await AbrovaPush.getInboxUnreadCount();
console.log('Unread:', badgeCount);

// Cached messages, no network call
const cached = await AbrovaPush.getCachedInboxMessages();

// Note: the React Native wrapper has no live inbox listener yet.
// Refresh with getInboxMessages() / fetchInboxUnreadCount() (e.g. on screen focus).
```

<H2 id="android" step={10}>Android</H2>

```kotlin
// Fetch inbox messages
val filter = InboxFilter(
    status = InboxMessageStatus.UNREAD, // null for all
    category = "promotions", // optional
    limit = 20,
    offset = 0
)

AbrovaPush.getInboxMessages(
    filter = filter,
    onSuccess = { response ->
        Log.d("Inbox", "Total: ${response.total}, Unread: ${response.unreadCount}")
        response.messages.forEach { message ->
            Log.d("Inbox", "Title: ${message.content.title}")
            Log.d("Inbox", "Body: ${message.content.body}")
            Log.d("Inbox", "Status: ${message.status}")
        }
    },
    onError = { error ->
        Log.e("Inbox", "Failed to fetch: $error")
    }
)

// Mark message as read
AbrovaPush.markInboxMessageAsRead(
    messageId = message.id,
    onSuccess = { Log.d("Inbox", "Marked as read") },
    onError = { error -> Log.e("Inbox", "Error: $error") }
)

// Mark all messages as read
AbrovaPush.markAllInboxMessagesAsRead(
    onSuccess = { Log.d("Inbox", "All marked as read") },
    onError = { error -> Log.e("Inbox", "Error: $error") }
)

// Archive a message
AbrovaPush.archiveInboxMessage(
    messageId = message.id,
    onSuccess = { Log.d("Inbox", "Archived") },
    onError = { error -> Log.e("Inbox", "Error: $error") }
)

// Delete a message
AbrovaPush.deleteInboxMessage(
    messageId = message.id,
    onSuccess = { Log.d("Inbox", "Deleted") },
    onError = { error -> Log.e("Inbox", "Error: $error") }
)

// Get unread count (from cache, synchronous)
val unreadCount = AbrovaPush.getInboxUnreadCount()
Log.d("Inbox", "Unread: $unreadCount")

// Fetch unread count from server
AbrovaPush.fetchInboxUnreadCount(
    onSuccess = { count -> updateBadge(count) },
    onError = { error -> Log.e("Inbox", "Error: $error") }
)

// Get cached messages (no network call)
val cachedMessages = AbrovaPush.getCachedInboxMessages()

// Set callback for new inbox messages
AbrovaPush.setInboxCallback(object : InboxCallback {
    override fun onMessageReceived(message: InboxMessage) {
        Log.d("Inbox", "New message: ${message.content.title}")
        // Update your UI or show badge
    }

    override fun onMessageStatusChanged(messageId: String, status: InboxMessageStatus) {
        Log.d("Inbox", "Message $messageId status: $status")
    }
})
```

<H2 id="ios" step={11}>iOS</H2>

```swift
import AbrovaPush

// Fetch inbox messages
let filter = InboxFilter(
    status: .unread,       // nil for all
    category: "promotions", // optional
    limit: 20,
    offset: 0
)

AbrovaPush.shared.getInboxMessages(
    filter: filter,
    onSuccess: { response in
        print("Total: \(response.total), Unread: \(response.unreadCount)")
        for message in response.messages {
            print("Title: \(message.content.title)")
            print("Body: \(message.content.body)")
            print("Status: \(message.status.rawValue)")
        }
    },
    onError: { error in
        print("Failed to fetch: \(error)")
    }
)

// Mark message as read
AbrovaPush.shared.markInboxMessageAsRead(
    messageId: message.id,
    onSuccess: { print("Marked as read") },
    onError: { error in print("Error: \(error)") }
)

// Mark multiple messages with a status
AbrovaPush.shared.markMultipleInboxMessages(
    messageIds: ["msg_1", "msg_2", "msg_3"],
    status: .read,
    onSuccess: { print("Updated") },
    onError: { error in print("Error: \(error)") }
)

// Mark all messages as read
AbrovaPush.shared.markAllInboxMessagesAsRead(
    onSuccess: { print("All marked as read") },
    onError: { error in print("Error: \(error)") }
)

// Archive a message
AbrovaPush.shared.archiveInboxMessage(
    messageId: message.id,
    onSuccess: { print("Archived") },
    onError: { error in print("Error: \(error)") }
)

// Delete a message
AbrovaPush.shared.deleteInboxMessage(
    messageId: message.id,
    onSuccess: { print("Deleted") },
    onError: { error in print("Error: \(error)") }
)

// Get unread count (from cache, synchronous)
let unreadCount = AbrovaPush.shared.getInboxUnreadCount()
print("Unread: \(unreadCount)")

// Fetch unread count from server
AbrovaPush.shared.fetchInboxUnreadCount(
    onSuccess: { count in updateBadge(count) },
    onError: { error in print("Error: \(error)") }
)

// Get cached messages (no network call)
let cachedMessages = AbrovaPush.shared.getCachedInboxMessages()

// Set callback for new inbox messages
class MyInboxHandler: InboxCallback {
    func inboxMessageReceived(_ message: InboxMessage) {
        print("New message: \(message.content.title)")
        // Update your UI or show badge
    }

    func inboxMessageStatusChanged(messageId: String, status: InboxMessageStatus) {
        print("Message \(messageId) status: \(status.rawValue)")
    }
}

// The callback is held weakly, so keep a strong reference (e.g. a property).
let handler = MyInboxHandler()
AbrovaPush.shared.setInboxCallback(handler)
```

<H2 id="web" step={12}>Web</H2>

Requires `@abrova/push-web` 0.1.6 or newer, and a registered device.

```typescript
import AbrovaPush from '@abrova/push-web';

const abrovaPush = new AbrovaPush({ apiKey: 'ab_live_your_api_key' });
await abrovaPush.register({ userId: 'user_123' });

// Live updates — an inbox message never shows a notification
abrovaPush.inbox.onMessage((message) => {
  console.log('New:', message.content.title);
});
abrovaPush.inbox.onUnreadCountChange((count) => {
  document.querySelector('.badge').textContent = String(count);
});

// Read
const { messages, total, unreadCount } = await abrovaPush.inbox.getMessages({
  status: 'unread',
  category: 'promotions',
  limit: 20,
});
const cached = abrovaPush.inbox.getCachedMessages(); // instant, no network

// Write
await abrovaPush.inbox.markAsRead(messages[0].id);
await abrovaPush.inbox.archiveMessage(messages[0].id);
await abrovaPush.inbox.deleteMessage(messages[0].id);
await abrovaPush.inbox.markMultiple(['msg_1', 'msg_2'], 'read');
await abrovaPush.inbox.markAllAsRead();

// Badge count without a fetch
const count = abrovaPush.inbox.getUnreadCount();
```

Messages are cached per device and restored on the next page load, so an inbox
screen renders instantly and refreshes in the background. The cache is dropped
when the signed-in user changes (`setUserId` / `clearUserId`).

<H2 id="building-an-inbox-ui-flutter" step={13}>Building an Inbox UI (Flutter)</H2>

```dart
class InboxScreen extends StatefulWidget {
  @override
  _InboxScreenState createState() => _InboxScreenState();
}

class _InboxScreenState extends State<InboxScreen> {
  List<InboxMessage> messages = [];
  bool loading = true;

  @override
  void initState() {
    super.initState();
    loadMessages();
  }

  Future<void> loadMessages() async {
    final result = await AbrovaPush.getInboxMessages();
    setState(() {
      messages = result.messages;
      loading = false;
    });
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: Text('Inbox')),
      body: loading
          ? Center(child: CircularProgressIndicator())
          : ListView.builder(
              itemCount: messages.length,
              itemBuilder: (context, index) {
                final message = messages[index];
                return ListTile(
                  leading: message.content.imageUrl != null
                      ? Image.network(message.content.imageUrl!, width: 50)
                      : Icon(Icons.mail),
                  title: Text(
                    message.content.title,
                    style: TextStyle(
                      fontWeight: message.status == InboxMessageStatus.unread
                          ? FontWeight.bold
                          : FontWeight.normal,
                    ),
                  ),
                  subtitle: Text(message.content.body, maxLines: 2),
                  trailing: message.status == InboxMessageStatus.unread
                      ? Container(
                          width: 8,
                          height: 8,
                          decoration: BoxDecoration(
                            color: Colors.blue,
                            shape: BoxShape.circle,
                          ),
                        )
                      : null,
                  onTap: () async {
                    await AbrovaPush.markInboxMessageAsRead(message.id);
                    if (message.content.deepLink != null) {
                      // Navigate to deep link
                    }
                    loadMessages();
                  },
                );
              },
            ),
    );
  }
}
```

<H2 id="best-practices" step={14}>Best Practices</H2>

<div>
  <ul>
    <li>
      <span>1.</span>
      <span><strong>Show unread badge</strong> — Display an unread count badge on your inbox icon to encourage users to check messages.</span>
    </li>
    <li>
      <span>2.</span>
      <span><strong>Use categories</strong> — Organize messages into categories so users can filter and find relevant content.</span>
    </li>
    <li>
      <span>3.</span>
      <span><strong>Set expiration dates</strong> — Use expiresAt for time-sensitive offers to automatically hide outdated content.</span>
    </li>
    <li>
      <span>4.</span>
      <span><strong>Include deep links</strong> — Always add a deep link so users can take action directly from the message.</span>
    </li>
    <li>
      <span>5.</span>
      <span><strong>Mark as read</strong> — Automatically mark messages as read when opened to keep the unread count accurate.</span>
    </li>
    <li>
      <span>6.</span>
      <span><strong>Paginate results</strong> — Use limit and offset parameters when fetching messages to handle large inboxes efficiently.</span>
    </li>
  </ul>
</div>

- VoIP calls: https://abrova.ir/en/docs/push/voip

Native incoming call UI with CallKit (iOS) and CallStyle (Android) for voice and video calling apps.

<Callout kind="tip" title="No FCM or Google Play Services Required">
Works on all devices including Huawei and non-Google Android phones.
</Callout>

<H2 id="flutter" step={1}>Flutter</H2>

The VoIP add-on is a separate package, `abrova_push_voip`, used alongside `abrova_push`:

Both install from Abrova Center:

```yaml
dependencies:
  abrova_push:
    hosted: https://center.abrova.ir/api/packages/abrova/pub
    version: ^0.1.20
  abrova_push_voip:
    hosted: https://center.abrova.ir/api/packages/abrova/pub
    version: ^0.1.1
```

The Android side comes from the Abrova Center Maven repository you added for `abrova_push` (see [Flutter SDK](/docs/push/flutter)). On iOS, add the native VoIP SDK inside the app target in `ios/Podfile`:

```ruby
pod 'AbrovaPushVoip', :git => 'https://github.com/Abrova-co/abrova-push-voip-ios-sdk.git', :tag => '0.1.2'
```

#### iOS Setup

Add to your `Info.plist`:

```xml
<key>UIBackgroundModes</key>
<array>
  <string>voip</string>
  <string>remote-notification</string>
</array>
```

Enable **Push Notifications** and **Background Modes → Voice over IP, Remote notifications** in Xcode under Signing & Capabilities. No AppDelegate changes are needed: the plugin handles PushKit registration and CallKit.

#### Android Setup

No manifest changes are needed. The call activities, receivers and permissions (`USE_FULL_SCREEN_INTENT`, `VIBRATE`, `FOREGROUND_SERVICE`) are declared by the native `ir.abrova:abrova-push-voip` library and merged automatically.

#### Initialize VoIP (Flutter)

```dart
import 'package:abrova_push/abrova_push.dart';
import 'package:abrova_push_voip/abrova_push_voip.dart';

// Initialize AbrovaPush first
await AbrovaPush.init(AbrovaPushConfig(apiKey: 'ab_live_your_api_key'));
await AbrovaPush.register();

// Then initialize VoIP with its config and callbacks
await AbrovaPushVoIP.init(
  config: AbrovaPushVoIPConfig(
    appName: 'MyApp',
    callTimeout: 30,        // Seconds before an unanswered call times out (default: 60)
    ringtone: null,         // Custom ringtone (optional)
  ),
  onCallAccepted: (callData) {
    print('Call accepted: ${callData.callId}');
    print('Caller: ${callData.callerName}');
    print('Type: ${callData.mediaType}'); // CallMediaType.audio or .video

    // Navigate to your call screen
    Navigator.push(context, MaterialPageRoute(
      builder: (_) => CallScreen(call: callData),
    ));
  },
  onCallDeclined: (callData) {
    // Notify your server that call was declined
  },
  onCallTimeout: (callData) {
    // Show missed call notification
  },
);

// Let the plugin register its PushKit (VoIP) token with Abrova
final deviceId = await AbrovaPush.getDeviceId();
await AbrovaPushVoIP.setApiKey(apiKey: 'ab_live_your_api_key', deviceId: deviceId);
```

#### Handle Initial Call (Cold Start)

When the app is launched from an accepted call notification:

```dart
// Check for initial call when app starts
final initialCall = await AbrovaPushVoIP.getInitialCall();
if (initialCall != null) {
  // App was opened from accepting a call
  Navigator.push(context, MaterialPageRoute(
    builder: (_) => CallScreen(call: initialCall),
  ));
}
```

#### End Call

```dart
await AbrovaPushVoIP.endCall(callData.callId);

// Report call as connected (for CallKit on iOS)
await AbrovaPushVoIP.reportCallConnected(callData.callId);
```

#### Call Data Model

```dart
class CallData {
  final String callId;               // Unique call identifier
  final String callerName;           // Display name
  final String? callerAvatar;        // Avatar URL
  final CallMediaType mediaType;     // CallMediaType.audio or CallMediaType.video
  final Map<String, dynamic> extra;  // Extra data
  final DateTime receivedAt;         // When call was received
}
```

<H2 id="react-native" step={2}>React Native</H2>

The VoIP add-on is a separate package, used alongside `abrova-push-react-native`:

Install it from Abrova Center, like the core package:

```bash
npm install abrova-push-react-native-voip --registry=https://center.abrova.ir/api/packages/abrova/npm/
```

On iOS, add the native VoIP SDK inside the app target in `ios/Podfile`, then run `pod install`:

```ruby
pod 'AbrovaPushVoip', :git => 'https://github.com/Abrova-co/abrova-push-voip-ios-sdk.git', :tag => '0.1.2'
```

#### iOS Setup

Add VoIP background mode to `Info.plist`:

```xml
<key>UIBackgroundModes</key>
<array>
  <string>voip</string>
  <string>remote-notification</string>
</array>
```

#### Initialize VoIP (React Native)

```typescript
import AbrovaPush from 'abrova-push-react-native';
import AbrovaPushVoip, { CallData } from 'abrova-push-react-native-voip';

await AbrovaPushVoip.init({
  appName: 'MyApp',
  callTimeout: 30,
});

// Let the plugin register its PushKit (VoIP) token with Abrova (iOS)
const deviceId = await AbrovaPush.getDeviceId();
await AbrovaPushVoip.setApiKey({ apiKey: 'ab_live_your_api_key', deviceId: deviceId ?? undefined });

const unsubAccepted = AbrovaPushVoip.onCallAccepted((call: CallData) => {
  navigation.navigate('CallScreen', { call });
});

const unsubDeclined = AbrovaPushVoip.onCallDeclined((call: CallData) => {
  // Handle decline
});

const unsubTimeout = AbrovaPushVoip.onCallTimeout((call: CallData) => {
  // Handle timeout
});

// Clean up
useEffect(() => {
  return () => {
    unsubAccepted();
    unsubDeclined();
    unsubTimeout();
  };
}, []);
```

#### Handle Initial Call

```typescript
const initialCall = await AbrovaPushVoip.getInitialCall();
if (initialCall) {
  navigation.navigate('CallScreen', { call: initialCall });
}
```

#### Call Control

```typescript
await AbrovaPushVoip.endCall(call.callId);
await AbrovaPushVoip.reportCallConnected(call.callId);
```

#### TypeScript Types

```typescript
interface CallData {
  callId: string;
  callerName: string;
  callerId?: string;
  callerAvatar?: string;
  callType: 'audio' | 'video';
  payload?: Record<string, any>;
  timestamp: number;
}

interface VoipConfig {
  appName: string;
  ringtoneUri?: string;
  vibrate?: boolean;          // default: true
  callTimeout?: number;       // seconds, default: 30
  callIdKey?: string;         // payload key overrides
  callerNameKey?: string;
  callerIdKey?: string;
  callerAvatarKey?: string;
  callTypeKey?: string;
}
```

<H2 id="android" step={3}>Android</H2>

Add the VoIP module to your `build.gradle`. It comes from the Abrova Center repository (`https://center.abrova.ir/api/packages/abrova/maven`) you added for the [Android SDK](/docs/push/android):

```kotlin
dependencies {
    implementation("ir.abrova:abrova-push-voip:0.1.0")
}
```

#### Manifest Configuration

No manifest changes are needed. The library's manifest already declares the permissions (`VIBRATE`, `USE_FULL_SCREEN_INTENT`, `FOREGROUND_SERVICE`), `IncomingCallActivity`, the Android 12+ trampoline activities (`CallTrampolineActivity`, `DeclineCallActivity`) and the receivers, and they are merged into your app automatically.

#### Initialize VoIP (Android)

```kotlin
import ir.abrova.push.voip.AbrovaPushVoip
import ir.abrova.push.voip.VoipCallback
import ir.abrova.push.voip.VoipConfig
import ir.abrova.push.voip.CallData

// Initialize in Application.onCreate()
AbrovaPushVoip.initialize(
    context = this,
    config = VoipConfig(
        appName = "MyApp",
        timeoutSeconds = 30,
        showMissedCallNotification = true
    )
)

// Set callback
AbrovaPushVoip.setCallback(object : VoipCallback {
    override fun onCallAccepted(callData: CallData) {
        Log.d("VoIP", "Call accepted: ${callData.callId}")
        // Start your call activity
        startCallActivity(callData)
    }

    override fun onCallDeclined(callData: CallData) {
        Log.d("VoIP", "Call declined: ${callData.callId}")
    }

    override fun onCallTimeout(callData: CallData) {
        Log.d("VoIP", "Call timeout: ${callData.callId}")
    }

    override fun onError(error: String) {
        Log.e("VoIP", "Error: $error")
    }
})
```

#### Handle Incoming Call from Push (Android)

Incoming `voip_call` messages are picked up automatically: the library registers a receiver for Abrova Push messages that shows the call UI even when your app is in the background. If you also handle messages yourself, you can hand them to the VoIP module:

```kotlin
AbrovaPush.setCallback(object : AbrovaPushCallbackAdapter() {
    override fun onMessageReceived(message: AbrovaPushMessage) {
        val data = message.data ?: return
        if (AbrovaPushVoip.handlePushMessage(data)) return
        // Handle other messages
    }
})
```

#### Manual Call Trigger (Android)

```kotlin
val callData = CallData(
    callId = "unique-call-id",
    callerName = "John Doe",
    callerId = "user-123",
    callerAvatar = "https://example.com/avatar.jpg",
    callType = "video"
)

AbrovaPushVoip.showIncomingCall(callData)
```

#### Call Control (Android)

```kotlin
// End call
AbrovaPushVoip.endCall(callId)

// Report call as connected
AbrovaPushVoip.reportCallConnected(callId)

// Get initial call (if app was cold started from call)
val initialCall = AbrovaPushVoip.getInitialCall()
initialCall?.let { startCallActivity(it) }
```

<H2 id="ios" step={4}>iOS</H2>

Add AbrovaPushVoip with Swift Package Manager. In Xcode: **File → Add Package Dependencies** → enter the repository URL, choose version `0.1.2` or later and add the `AbrovaPushVoip` library to your app target:

```
https://github.com/Abrova-co/abrova-push-voip-ios-sdk.git
```

#### Capabilities

In Xcode, add these capabilities under Signing & Capabilities:

- Background Modes: **Voice over IP**, **Remote notifications**
- **Push Notifications**

#### Info.plist

```xml
<key>UIBackgroundModes</key>
<array>
  <string>voip</string>
  <string>remote-notification</string>
</array>
```

#### Initialize VoIP (iOS)

```swift
import AbrovaPushVoip

// In AppDelegate.didFinishLaunchingWithOptions
let config = VoipConfig(
    appName: "MyApp",
    callTimeout: 30,
    supportsVideo: true,
    ringtoneName: "ringtone.caf",
    iconTemplateName: "CallIcon"
)

AbrovaPushVoip.shared.initialize(config: config)
AbrovaPushVoip.shared.delegate = self
AbrovaPushVoip.shared.registerForVoIPPushes()
```

#### Implement Delegate (iOS)

```swift
extension AppDelegate: AbrovaPushVoipDelegate {
    func voip(_ voip: AbrovaPushVoip, didAcceptCall callData: VoipCallData) {
        print("Call accepted: \(callData.callId)")
        // Navigate to call screen
        DispatchQueue.main.async {
            self.showCallScreen(callData)
        }
    }

    func voip(_ voip: AbrovaPushVoip, didDeclineCall callData: VoipCallData) {
        print("Call declined: \(callData.callId)")
        // Notify server
    }

    func voip(_ voip: AbrovaPushVoip, didTimeoutCall callData: VoipCallData) {
        print("Call timeout: \(callData.callId)")
        // Show missed call
    }

    func voip(_ voip: AbrovaPushVoip, didFailWithError error: String) {
        print("VoIP error: \(error)")
    }
}
```

#### Handle Initial Call (iOS)

```swift
if let initialCall = AbrovaPushVoip.shared.getInitialCall() {
    showCallScreen(initialCall)
    AbrovaPushVoip.shared.clearInitialCall()
}
```

#### Call Control (iOS)

```swift
AbrovaPushVoip.shared.endCall(callId: callData.callId)
AbrovaPushVoip.shared.reportCallConnected(callId: callData.callId)
```

#### Get VoIP Token (iOS)

```swift
// Read the current PushKit (VoIP) token
if let token = AbrovaPushVoip.shared.getVoIPToken() {
    print("VoIP token: \(token)")
}
```

The native `AbrovaPushVoip` SDK does not upload this token to Abrova (the Flutter and React Native plugins do, through `setApiKey`). Abrova sends VoIP pushes to the VoIP token stored for the device, which the core `AbrovaPush` SDK uploads when it is initialized with `usePushKit: true`.

<H2 id="web" step={5}>Web</H2>

<Callout kind="note" title="Web Limitation">
VoIP calling features are only available for native mobile platforms (iOS, Android, Flutter, React Native). Web applications should use WebRTC directly for voice/video calls.
</Callout>

<H2 id="server-side-send-voip-call" step={6}>Server-Side: Send VoIP Call</H2>

#### Node.js SDK

```typescript
import { AbrovaPush } from '@abrova/push-node';

const abrovaPush = new AbrovaPush({
  apiKey: 'ab_live_your_api_key',
  serverSecret: 'ab_srv_your_server_secret',
});

await abrovaPush.push.sendToDevice({
  deviceId: 'DEVICE_ID',
  title: 'Incoming call',
  body: 'John Doe is calling',
  data: {
    type: 'voip_call',
    callId: 'unique-call-123',
    callerName: 'John Doe',
    callerId: 'user-456',
    callerAvatar: 'https://example.com/avatar.jpg',
    callType: 'video',
  },
});
```

#### REST API

```bash
curl -X POST https://push-api.abrova.ir/push/send \
  -H "x-api-key: ab_live_your_api_key" \
  -H "x-server-secret: ab_srv_your_server_secret" \
  -H "Content-Type: application/json" \
  -d '{
    "deviceId": "DEVICE_ID",
    "title": "Incoming call",
    "body": "John Doe is calling",
    "data": {
      "type": "voip_call",
      "callId": "unique-call-123",
      "callerName": "John Doe",
      "callerId": "user-456",
      "callerAvatar": "https://example.com/avatar.jpg",
      "callType": "video"
    }
  }'
```

<H2 id="payload-fields" step={7}>Payload Fields</H2>

<ConfigTable rows={[
  ['type', 'string', 'Yes', 'Must be "voip_call" (system trigger)'],
  ['callId', 'string', 'No', 'Unique call identifier; a random ID is generated if missing'],
  ['callerName', 'string', 'No', 'Display name of caller (falls back to "Unknown")'],
  ['callerId', 'string', 'No', 'User ID of caller'],
  ['callerAvatar', 'string', 'No', 'Avatar URL (shown in notification and call screen)'],
  ['callType', 'string', 'No', '"audio" or "video" (default: audio)'],
]} />

<Callout kind="note" title="Fixed System Trigger">
The `type: "voip_call"` field is the system trigger — it tells the SDK to show the incoming call UI. This value is **fixed** and cannot be changed. The other fields (`callerName`, `callerId`, etc.) are configurable via `VoipConfig` payload key mappings. The request itself also needs `title` and `body` (or a `templateId`) like any push.
</Callout>

<H2 id="how-it-works" step={8}>How It Works</H2>

1. **Server sends VoIP notification** — Your server sends a push with `type: "voip_call"` to the device
2. **Native call UI appears** — iOS shows CallKit, Android shows CallStyle notification (Android 12+) or full-screen activity
3. **User accepts or declines** — Your callback is triggered with the call data
4. **Navigate to your call screen** — Use WebRTC or your preferred calling solution for the actual call

- Device management: https://abrova.ir/en/docs/push/devices

Register, manage, and target devices for push notifications.

<H2 id="device-lifecycle" step={1}>Device Lifecycle</H2>

1. **Register** — Device gets push token
2. **Associate** — Link to user ID
3. **Subscribe** — Add to topics
4. **Receive** — Get notifications

<H2 id="sdk-registration" step={2}>SDK Registration</H2>

The SDK handles device registration automatically. Each platform exposes the same surface.

Call `register()` on every app launch (or page load, once notification permission is granted). It keeps the device's push token, app version, SDK version and last-seen time current on the server. The native Android, iOS and Web SDKs also refresh a registered device on their own (`autoRefresh`, on by default): at most once every 24 hours, or sooner when the app version, SDK version, push token or user changed. A refresh never prompts for notification permission.

`clearUserId()` detaches the user from the device on the server, so the device stops receiving that user's notifications after logout.

<Callout kind="note" title="One phone stays one device">
Reinstalling an app creates a new device id. The SDKs send a fingerprint of the install (hashed on the device, never a raw device id), so the record left by the previous install is retired instead of staying active for ever. Browsers re-subscribing to Web Push are matched the same way. Devices that stop checking in for 60 days are deactivated as well, and come back on their own the next time the app registers.
</Callout>

#### Flutter

```dart
import 'package:abrova_push/abrova_push.dart';

// Initialize AbrovaPush (only apiKey required)
await AbrovaPush.init(AbrovaPushConfig(
  apiKey: 'ab_live_your_api_key',
));

// Register device with optional user ID and metadata
await AbrovaPush.register(
  userId: 'user_123',
  metadata: {
    'tier': 'premium',
    'language': 'en',
  },
);

// Update user ID after login
await AbrovaPush.setUserId('user_123');

// Clear user ID after logout
await AbrovaPush.clearUserId();

// Topics
await AbrovaPush.subscribeTopic('news');
await AbrovaPush.subscribeTopic('promotions');
await AbrovaPush.unsubscribeTopic('promotions');

// Unregister (e.g., user opts out)
await AbrovaPush.unregister();
```

#### Android

```kotlin
import ir.abrova.push.sdk.AbrovaPush

// Result arrives in AbrovaPushCallback.onRegistered(deviceId) / onError(error)
AbrovaPush.register(
    userId = "user_123",
    metadata = mapOf(
        "tier" to "premium",
        "language" to "en"
    )
)

AbrovaPush.setUserId("user_123")
AbrovaPush.clearUserId()

AbrovaPush.subscribeTopic("news")
AbrovaPush.unsubscribeTopic("promotions")

// Stop the push service on this device
AbrovaPush.unregister()
```

#### iOS

```swift
import AbrovaPush

// Result arrives in AbrovaPushDelegate didRegisterWithDeviceId / didFailWithError
AbrovaPush.shared.register(
    userId: "user_123",
    metadata: [
        "tier": "premium",
        "language": "en"
    ]
)

AbrovaPush.shared.setUserId("user_123")
AbrovaPush.shared.clearUserId()

AbrovaPush.shared.subscribeTopic("news")
AbrovaPush.shared.unsubscribeTopic("promotions")

// Disconnect and detach the user on the server
AbrovaPush.shared.unregister()
```

#### React Native

```typescript
import AbrovaPush from 'abrova-push-react-native';

await AbrovaPush.register({
  userId: 'user_123',
  metadata: {
    tier: 'premium',
    language: 'en',
  },
});

await AbrovaPush.setUserId('user_123');
await AbrovaPush.clearUserId();

await AbrovaPush.subscribeTopic('news');
await AbrovaPush.unsubscribeTopic('promotions');

await AbrovaPush.unregister();
```

#### Web

```typescript
import AbrovaPush from '@abrova/push-web';

const abrovaPush = new AbrovaPush({ apiKey: 'ab_live_your_api_key' });

await abrovaPush.register({
  userId: 'user_123',
  metadata: { tier: 'premium' },
});

await abrovaPush.setUserId('user_123');
await abrovaPush.clearUserId();

await abrovaPush.subscribeTopic('news');
await abrovaPush.unsubscribeTopic('promotions');

await abrovaPush.unregister();
```

<H2 id="node-js-sdk" step={3}>Node.js SDK</H2>

Manage devices directly from your backend.

```typescript
import { AbrovaPush } from '@abrova/push-node';

const abrovaPush = new AbrovaPush({
  apiKey: 'ab_live_your_api_key',
  serverSecret: 'ab_srv_your_server_secret',
});

// List all active devices
const devices = await abrovaPush.devices.list();

// Subscribe / unsubscribe to topic
await abrovaPush.devices.subscribeTopic('device_id', 'news');
await abrovaPush.devices.unsubscribeTopic('device_id', 'news');

// Set / clear the user on a device
await abrovaPush.devices.setUserId('device_id', 'user_123');
await abrovaPush.devices.clearUserId('device_id');

// Permanently delete a device
await abrovaPush.devices.delete('device_id');
```

<H2 id="rest-api" step={4}>REST API</H2>

Devices normally register through the SDK. Use these endpoints to manage them from your backend.

#### Register

```bash
curl -X POST "https://push-api.abrova.ir/devices/register" \
  -H "x-api-key: ab_live_your_api_key" \
  -H "x-server-secret: ab_srv_your_server_secret" \
  -H "Content-Type: application/json" \
  -d '{
    "deviceId": "unique_device_id",
    "platform": "android",
    "userId": "user_123",
    "metadata": {
      "tier": "premium"
    }
  }'
```

#### Unregister (soft)

Stops sends to the device but keeps it, and its delivery history, in the Console. The device is reactivated automatically the next time the SDK registers.

```bash
curl -X POST "https://push-api.abrova.ir/devices/unique_device_id/unregister" \
  -H "x-api-key: ab_live_your_api_key" \
  -H "x-server-secret: ab_srv_your_server_secret"
```

#### Reactivate

```bash
curl -X POST "https://push-api.abrova.ir/devices/unique_device_id/reactivate" \
  -H "x-api-key: ab_live_your_api_key" \
  -H "x-server-secret: ab_srv_your_server_secret"
```

#### Delete

```bash
curl -X DELETE "https://push-api.abrova.ir/devices/unique_device_id" \
  -H "x-api-key: ab_live_your_api_key" \
  -H "x-server-secret: ab_srv_your_server_secret"
```

#### Subscribe to Topic

```bash
curl -X POST "https://push-api.abrova.ir/devices/unique_device_id/topics/news" \
  -H "x-api-key: ab_live_your_api_key" \
  -H "x-server-secret: ab_srv_your_server_secret"
```

#### Unsubscribe from Topic

```bash
curl -X DELETE "https://push-api.abrova.ir/devices/unique_device_id/topics/news" \
  -H "x-api-key: ab_live_your_api_key" \
  -H "x-server-secret: ab_srv_your_server_secret"
```

#### Set User ID

```bash
curl -X POST "https://push-api.abrova.ir/devices/unique_device_id/user" \
  -H "x-api-key: ab_live_your_api_key" \
  -H "x-server-secret: ab_srv_your_server_secret" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "user_123"
  }'
```

#### Clear User ID

```bash
curl -X DELETE "https://push-api.abrova.ir/devices/unique_device_id/user" \
  -H "x-api-key: ab_live_your_api_key" \
  -H "x-server-secret: ab_srv_your_server_secret"
```

#### List All Devices

Without `page` or `limit`, returns all active devices as an array. With either, returns `{ items, total, page, limit }` and accepts the filters `platform`, `isActive`, `userId`, `appVersion`, `sdkName`, `sdkVersion`, `search`, `lastSeenBefore`, `lastSeenAfter` and `failureReason` (the device's most recent delivery failure reason). `limit` defaults to 50 (max 200). Listing devices returns project-wide data, so it needs the server secret; the API key alone is refused.

```bash
curl -X GET "https://push-api.abrova.ir/devices?page=1&limit=50&platform=ios" \
  -H "x-api-key: ab_live_your_api_key" \
  -H "x-server-secret: ab_srv_your_server_secret"
```

<H2 id="device-fields" step={5}>Device Fields</H2>

<ConfigTable rows={[
  ['deviceId', 'string', 'Yes', 'Unique identifier for the device'],
  ['platform', 'string', 'Yes', '"android", "ios", or "web"'],
  ['pushToken', 'string', 'No', 'Push token set by the SDK (on iOS this is the PushKit VoIP token)'],
  ['apnsToken', 'string', 'No', 'iOS APNs device token, set by the SDK'],
  ['fcmToken', 'string', 'No', 'FCM token, only with the optional Android FCM bridge'],
  ['userId', 'string', 'No', 'Optional user ID to associate with device'],
  ['topics', 'string[]', 'No', 'List of subscribed topics'],
  ['metadata', 'object', 'No', 'Custom key-value pairs for targeting'],
  ['appVersion', 'string', '-', 'App version reported by the SDK'],
  ['sdkName', 'string', '-', 'SDK that registered the device, e.g. "android", "ios", "web", "flutter"'],
  ['sdkVersion', 'string', '-', 'Version of that SDK'],
  ['isActive', 'boolean', '-', 'Whether the device receives sends (false after unregister or a permanently invalid token)'],
  ['updatedAt', 'date', '-', 'Last registration or refresh (shown as last seen in the Console)'],
]} />

<H2 id="best-practices" step={6}>Best Practices</H2>

<BestPracticeList items={[
  ['Register on Every Launch', 'Call register() each time your app starts so the device record stays current'],
  ['Set User ID After Login', 'Call setUserId() when users log in to enable user-targeted notifications'],
  ['Clear User ID on Logout', 'Always call clearUserId() when users log out to prevent wrong-account notifications'],
  ['Use Metadata for Targeting', 'Store user preferences, membership tier, or other attributes for segmentation'],
  ['Let Users Manage Topics', 'Give users control over which topics they subscribe to in your app settings'],
]} />

View and manage all registered devices in the [Devices Dashboard](https://console.abrova.ir/dashboard/abrova-push/devices). Each row shows the platform, SDK name and version, app version and last-seen time; filter by any of them, and unregister or reactivate a device from the list. Click any row to open its **device profile** — a full page showing IDs, the raw metadata block (with copy-as-JSON), subscribed topics, and which saved segments the device currently belongs to. Handy for debugging targeting issues and answering "why isn't this device receiving my campaign?".


## Abrova Chat (coming soon)

- Quick start: https://abrova.ir/en/docs/chat/quick-start

Get AbrovaChat running in your app in under 5 minutes. Pick your platform and follow the steps.

Every client platform ships two packages: a **headless core** SDK and an optional **UI** package with pre-built components. The Node.js SDK is server-side only; REST is for any HTTP client.

Every SDK will install from Abrova Center. Apps use only your public project key (`ab_live_…`); the server secret (`ab_srv_…`) stays on your server. 5,000 messages a month are free; the price above that is set when Abrova Chat launches.

Using an AI assistant? See [AI assistants](/docs/chat/ai-assistants) for what works today.

<H2 id="install" step={1}>Install</H2>

Add the AbrovaChat SDK to your project.

#### Flutter

AbrovaChat offers two packages: `abrova_chat` (core, headless, no UI dependencies) and `abrova_chat_ui` (optional pre-built widgets, includes core). Add one to `pubspec.yaml` from Abrova Center, then run `flutter pub get`:

```yaml
dependencies:
  abrova_chat:                 # headless/custom UI (recommended)
    hosted: https://center.abrova.ir/api/packages/abrova/pub
    version: ^0.1.5
  # abrova_chat_ui:            # pre-built widgets
  #   hosted: https://center.abrova.ir/api/packages/abrova/pub
  #   version: ^0.1.0
```

#### iOS

AbrovaChat offers two libraries: `AbrovaChat` (headless) and `AbrovaChatUI` (optional SwiftUI components). Install with Swift Package Manager:

1. In Xcode: **File → Add Package Dependencies** → enter `https://github.com/Abrova-co/abrova-chat-ios-sdk.git`.
2. Choose version `0.1.4` or later and add the `AbrovaChat` library (and `AbrovaChatUI` if you want the components) to your target.

```swift
// Or in Package.swift:
dependencies: [
    .package(url: "https://github.com/Abrova-co/abrova-chat-ios-sdk.git", from: "0.1.4")
]

// Then add the product to your target:
.product(name: "AbrovaChat", package: "abrova-chat-ios-sdk")
```

#### Android

AbrovaChat offers two packages: `abrova-chat-android` (headless) and `abrova-chat-android-ui` (optional Jetpack Compose components).

1. Add the Abrova Center repository to `settings.gradle.kts`:

```kotlin
dependencyResolutionManagement {
    repositories {
        google()
        mavenCentral()
        maven { url = uri("https://center.abrova.ir/api/packages/abrova/maven") }
    }
}
```

2. Add the dependency to `build.gradle.kts` (app level):

```kotlin
dependencies {
    // For headless SDK:
    implementation("ir.abrova:abrova-chat-android:0.1.4")

    // For pre-built Compose components:
    // implementation("ir.abrova:abrova-chat-android-ui:0.1.0")
}
```

#### React Native

AbrovaChat offers two packages: `@abrova/react-native-chat` (headless) and `@abrova/react-native-chat-ui` (optional pre-built components, includes core).

1. Point the `@abrova` scope at Abrova Center in your project's `.npmrc`:

```
# .npmrc (in your project root)
@abrova:registry=https://center.abrova.ir/api/packages/abrova/npm/
```

2. Install one of them:

```bash
# For headless/custom UI:
npm install @abrova/react-native-chat

# For pre-built UI components (includes core):
npm install @abrova/react-native-chat-ui
```

#### Web

AbrovaChat offers `@abrova/web-chat` (headless). Pre-built React components (`@abrova/web-chat-ui`) will follow later.

1. Use the same `.npmrc` line as above:

```
@abrova:registry=https://center.abrova.ir/api/packages/abrova/npm/
```

2. Install the package:

```bash
npm install @abrova/web-chat
```

#### Node.js (Server)

The server-side SDK for Node.js backends has zero runtime dependencies (it uses native Node.js http/https) and includes TypeScript declarations.

1. Use the same `.npmrc` line as above:

```
@abrova:registry=https://center.abrova.ir/api/packages/abrova/npm/
```

2. Install the package:

```bash
npm install @abrova/chat
```

<Callout kind="note" title="Server-Side Only">
The Node.js SDK and REST API must only be used from your backend server, never from client apps. The server secret can be extracted from client apps.
</Callout>

#### REST API

```bash
# No SDK needed — use any HTTP client
# Base URL: https://chat.abrova.ir

# All requests require (one project key for every Abrova service):
X-API-Key: ab_live_your_api_key
X-Server-Secret: ab_srv_your_server_secret   # from an environment variable, server only
Content-Type: application/json
```

<H2 id="initialize" step={2}>Initialize</H2>

Create an `AbrovaChatClient` instance with your API key and connect to start receiving realtime events.

#### Flutter

```dart
import 'package:abrova_chat/abrova_chat.dart';

// Create client configuration
final config = AbrovaChatConfig(
  apiKey: 'ab_live_your_api_key',
  userId: currentUser.id,
  userInfo: {'displayName': currentUser.name},
);

// Initialize the client
final client = AbrovaChatClient(config);

// Connect to realtime (WebSocket)
await client.connect();

// Listen to events
client.onMessage.listen((message) {
  print('New message: ${message.content}');
});

client.onConnectionStateChange.listen((state) {
  print('Connection: $state');
});

// Get unread summary
final unread = await client.getUnreadSummary();
print('Total unread: ${unread.totalUnread}');

// Dispose on logout
client.dispose();
```

#### iOS

```swift
import AbrovaChat
import Combine

// Create configuration
let config = AbrovaChatConfig(
    apiKey: "ab_live_your_api_key",
    userId: currentUser.id,
    userInfo: ["displayName": currentUser.name]
)

// Initialize client
let client = AbrovaChatClient(config: config)
var cancellables = Set<AnyCancellable>()

// Connect to realtime (WebSocket)
try await client.connect()

// Listen to events using Combine
client.onMessage
    .sink { message in
        print("New message: \(message.content)")
    }
    .store(in: &cancellables)

client.onTypingEvent
    .sink { event in
        print("\(event.userId) is \(event.isTyping ? "typing" : "not typing")")
    }
    .store(in: &cancellables)

client.onPresenceChange
    .sink { event in
        print("\(event.userId) is \(event.isOnline ? "online" : "offline")")
    }
    .store(in: &cancellables)

// Dispose on logout
client.dispose()
```

#### Android

```kotlin
import ir.abrova.chat.AbrovaChatClient
import ir.abrova.chat.AbrovaChatConfig

// Create configuration
val config = AbrovaChatConfig(
    apiKey = "ab_live_your_api_key",
    userId = currentUser.id,
    userInfo = mapOf("displayName" to currentUser.name)
)

// Initialize client
val client = AbrovaChatClient(config)

// Connect to realtime (WebSocket)
client.connect()

// Listen to events using Kotlin Flow
lifecycleScope.launch {
    client.onMessage.collect { message ->
        println("New message: ${message.content}")
    }
}

lifecycleScope.launch {
    client.onTypingEvent.collect { event ->
        println("${event.userId} is ${if (event.isTyping) "typing" else "not typing"}")
    }
}

lifecycleScope.launch {
    client.onPresenceChange.collect { event ->
        println("${event.userId} is ${if (event.isOnline) "online" else "offline"}")
    }
}

// Dispose on logout
client.dispose()
```

#### React Native

```typescript
import { AbrovaChatClient } from '@abrova/react-native-chat';

// Create client
const client = new AbrovaChatClient({
  apiKey: 'ab_live_your_api_key',
  userId: currentUser.id,
  userInfo: { displayName: currentUser.name },
});

// Connect to realtime (WebSocket)
client.connect();

// Listen to events
client.on('message', (event) => {
  console.log('New message:', event.message.content);
});

client.on('typing', (event) => {
  console.log(`${event.userId} is ${event.isTyping ? 'typing' : 'not typing'}`);
});

client.on('presence', (event) => {
  console.log(`${event.userId} is ${event.isOnline ? 'online' : 'offline'}`);
});

// Dispose on logout
client.dispose();
```

#### Web

```typescript
import { AbrovaChatClient } from '@abrova/web-chat';

// Create client
const client = new AbrovaChatClient({
  apiKey: 'ab_live_your_api_key',
  userId: currentUser.id,
  userInfo: { displayName: currentUser.name },
});

// Connect to realtime (WebSocket)
client.connect();

// Listen to events
client.on('message', (event) => {
  console.log('New message:', event.message.content);
});

client.on('typing', (event) => {
  console.log(`${event.userId} is ${event.isTyping ? 'typing' : 'not typing'}`);
});

client.on('presence', (event) => {
  console.log(`${event.userId} is ${event.isOnline ? 'online' : 'offline'}`);
});

// Dispose on logout
client.dispose();
```

#### Node.js

```typescript
import { AbrovaChat } from '@abrova/chat';

// Initialize with your API key and server secret
const abrovaChat = new AbrovaChat({
  apiKey: process.env.ABROVA_API_KEY,             // ab_live_...
  serverSecret: process.env.ABROVA_SERVER_SECRET, // ab_srv_..., server only
});

// Rooms
const rooms = await abrovaChat.rooms.list('user-123');

// Messages
const { messages, hasMore } = await abrovaChat.messages.getHistory(roomId, {
  userId: 'user-123',
  limit: 50,
});

// Send a message
const msg = await abrovaChat.messages.send(roomId, {
  senderUserId: 'user-123',
  content: 'Hello from the server!',
});

// Reactions, Pins, Webhooks, User tokens
await abrovaChat.reactions.add(msg.id, 'user-456', '👍');
await abrovaChat.pins.pin(msg.id, 'user-123');
const config = await abrovaChat.webhooks.get();
const { token } = await abrovaChat.users.createToken({ userId: 'user-123' });
```

#### REST API

```bash
# Get your API key (ab_live_...) and server secret (ab_srv_...) from
# Abrova Console (console.abrova.ir): your project > Settings, with Chat enabled

# Test your credentials (lists the rooms of user-123):
curl -X GET "https://chat.abrova.ir/api/v1/rooms?userId=user-123" \
  -H "X-API-Key: ab_live_your_api_key" \
  -H "X-Server-Secret: $ABROVA_SERVER_SECRET"
```

<Callout kind="tip" title="Tip">
The `fileUploader` callback lets you use any storage — [Abrova Storage](/docs/storage/flutter), any S3-compatible storage, or your own server. AbrovaChat never stores files; it only stores the URL you return.
</Callout>

- Authentication: https://abrova.ir/en/docs/chat/authentication

Your API key identifies your **project**, not your **user**. It ships inside every app and web bundle, so anyone can extract it. To let AbrovaChat trust *who* is acting, your server issues a short-lived **user token** and the SDK sends it with every request.

This is the same model used by other chat platforms: your backend vouches for the user, the client never holds a secret.

<Callout kind="note" title="Existing apps keep working">
User tokens are opt-in. Without a `tokenProvider` the SDK uses the legacy mode (API key + `userId`), exactly as before. Add tokens when you are ready, then switch your project to strict mode.
</Callout>

<H2 id="the-three-credentials" step={1}>The three credentials</H2>

| Credential | Lives in | Proves | If leaked |
|---|---|---|---|
| **API key** (`ab_live_…`) | Your app, public | Which project | Harmless in strict mode: it cannot act as a user |
| **Server secret** (`ab_srv_…`) | Your server only | That your backend is calling | Serious — rotate it in Abrova Console |
| **User token** (JWT, 1 h) | Your app, per user | Which user | Limited: one user, one project, expires, and you can revoke it |

<H2 id="mint-tokens-on-your-server" step={2}>Mint tokens on your server</H2>

Add one endpoint, protected by your own login, that returns a token for the signed-in user.

#### Node.js

```typescript
import { AbrovaChat } from '@abrova/chat';

const chat = new AbrovaChat({
  apiKey: process.env.ABROVA_API_KEY!,
  serverSecret: process.env.ABROVA_SERVER_SECRET!, // server-side only
});

// Express — requireLogin is YOUR auth middleware
app.get('/chat-token', requireLogin, async (req, res) => {
  const { token, expiresAt } = await chat.users.createToken({
    userId: req.user.id,                       // your own user id
    info: { displayName: req.user.name },      // optional, shown to other clients
  });
  res.json({ token, expiresAt });
});
```

#### REST (any backend)

```bash
curl -X POST https://chat.abrova.ir/api/v1/users/token \
  -H "x-api-key: $ABROVA_API_KEY" \
  -H "x-server-secret: $ABROVA_SERVER_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"userId": "user-123", "ttl": 3600}'

# → { "token": "eyJhbGciOi…", "expiresAt": "2026-09-12T10:00:00.000Z", "userId": "user-123" }
```

`ttl` is in seconds: 3600 (1 hour) by default, 86400 (24 hours) maximum. Shorter is safer, and refreshing costs the client one call to your server.

<Callout kind="note" title="Never ship the server secret">
The server secret can mint a token for **any** user. Keep it on your server, out of app bundles, mobile binaries and client-side JavaScript.
</Callout>

#### One token for every Abrova product

If your app also uses Abrova Sync, Abrova Push or Abrova A/B Testing, mint **one** token for all of them from the Abrova auth endpoint:

```bash
curl -X POST https://auth.abrova.ir/users/token \
  -H "x-api-key: $ABROVA_API_KEY" \
  -H "x-server-secret: $ABROVA_SERVER_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"userId": "user-123", "expiresIn": 3600}'

# → { "token": "eyJhbGciOi…", "userId": "user-123", "expiresIn": 3600, "expiresAt": "2026-09-21T10:00:00.000Z" }
```

Give that same token to every SDK's `tokenProvider` (or `setUserToken`) — Chat, Sync, Push and A/B Testing — instead of fetching one per product. `expiresIn` is in seconds: 3600 (1 hour) by default, 86400 (24 hours) maximum. The same rules apply: call it from your server, never from an app.

<Callout kind="note" title="Keep it on the device">
A token is valid until it expires, so store it with the user's session (Keychain, Keystore or secure storage) and reuse it across app launches. Your app then only calls your backend when the token is close to expiry — not on every start.
</Callout>

Revoking a user (below) also blocks their Abrova token in Chat. It carries no `info`, so if other clients should see a display name from the token, mint the Chat token above instead.

<H2 id="use-the-token-in-your-app" step={3}>Use the token in your app</H2>

Pass a `tokenProvider` that calls your endpoint. The SDK caches the token, refreshes it about a minute before it expires, and retries once if the server reports an expired token — all invisible to the user.

#### Flutter

```dart
// abrova_chat: ^0.1.5
final client = AbrovaChatClient(AbrovaChatConfig(
  apiKey: 'ab_live_your_api_key',
  userId: currentUser.id,
  tokenProvider: () => myBackend.chatToken(), // Future<String>
));

// Identity errors a refresh cannot fix (revoked, invalid, logged out).
client.onAuthError.listen((e) => signOut());
```

#### Web

```typescript
// @abrova/web-chat: ^0.1.2
const client = new AbrovaChatClient({
  apiKey: process.env.NEXT_PUBLIC_ABROVA_API_KEY!,
  userId: currentUser.id,
  tokenProvider: async () => (await fetch('/chat-token')).json().then((j) => j.token),
});

client.on('authError', () => signOut());
```

#### React Native

```typescript
// @abrova/react-native-chat: ^0.1.2
const client = new AbrovaChatClient({
  apiKey: ABROVA_API_KEY,
  userId: currentUser.id,
  tokenProvider: async () => {
    const res = await fetch('https://api.example.com/chat-token', {
      headers: { Authorization: `Bearer ${sessionToken}` },
    });
    return (await res.json()).token;
  },
});

client.on('authError', () => signOut());
```

#### iOS

```swift
// Swift Package Manager: https://github.com/Abrova-co/abrova-chat-ios-sdk.git (0.1.4+)
let config = AbrovaChatConfig(
    apiKey: "ab_live_your_api_key",
    userId: currentUser.id,
    tokenProvider: { try await myBackend.chatToken() }
)
let client = AbrovaChatClient(config: config)

client.onAuthError
    .sink { _ in signOut() }
    .store(in: &cancellables)
```

#### Android

```kotlin
// implementation("ir.abrova:abrova-chat-android:0.1.4")
val config = AbrovaChatConfig(
    apiKey = "ab_live_your_api_key",
    userId = currentUser.id,
    tokenProvider = { myBackend.chatToken() }   // suspend fun returning the token
)
val client = AbrovaChatClient(config)

scope.launch { client.onAuthError.collect { signOut() } }
```

#### REST (any HTTP client)

```bash
curl https://chat.abrova.ir/api/v1/rooms \
  -H "x-api-key: $ABROVA_API_KEY" \
  -H "x-user-token: $USER_TOKEN"
```

<H2 id="revoke-on-logout" step={4}>Revoke on logout</H2>

Tokens expire on their own, but revoke them when a session ends so a stolen token dies immediately.

```typescript
await chat.users.revokeTokens(userId);
// REST: POST /api/v1/users/{userId}/revoke-tokens  (server secret required)
```

Every token issued to that user before this moment stops working, for REST and realtime alike, within a few seconds. Call it on **logout**, **password change** and **ban**.

<H2 id="what-the-server-enforces" step={5}>What the server enforces</H2>

Once a request carries a user token, AbrovaChat ignores any `userId` in the request and uses the token's user:

| Attempt | Result |
|---|---|
| Read or send as another user | `403 user_mismatch` |
| Open a room you are not in (details, history, pinned, presence, reactions) | `403 not_a_participant` |
| Edit or delete someone else's message | `403` |
| Use a token from another project | `401 token_invalid` |
| Use an expired token | `401 token_expired` — the SDK refreshes and retries automatically |
| Use a revoked token | `401 token_revoked` |

Error codes the SDKs act on:

| Code | Meaning | SDK behaviour |
|---|---|---|
| `token_expired` | Lifetime elapsed | Fetches a new token and retries the request once |
| `token_invalid` | Malformed, wrong project, or not server-minted | `authError` — send the user to login |
| `token_revoked` | Revoked by your server | `authError` |
| `token_required` | Project is in strict mode and no token was sent | `authError` |
| `token_provider_failed` | Your endpoint failed or is unreachable | `authError` |

<H2 id="turn-on-strict-mode" step={6}>Turn on strict mode</H2>

While a project allows the legacy mode, a request with only the API key is still accepted — which is what keeps already-released apps working. Once every live client sends tokens, enable **Require signed user tokens** under *Chat security* in your project's settings in Abrova Console.

From then on, for that project:

- every per-user request needs a user token (or your server secret);
- the legacy connection-token endpoint (deprecated, used only by old SDK versions) no longer issues a token to the public API key alone.

<Callout kind="warn" title="Retire old app versions first">
Apps already installed keep using the legacy mode. Enable strict mode only once those versions are gone — a force-update mechanism in your app makes that possible. Server-to-server calls with the server secret are unaffected.
</Callout>

<H2 id="room-management-from-your-server" step={7}>Room management from your server</H2>

Creating rooms and adding or removing participants take no acting user, so with the API key alone anyone could add themselves to a room. Do that work on your server with the server secret, then enable **Server-only room management** under *Chat security* in your project's settings in Abrova Console.

```typescript
// Your server, with the server secret
const { room } = await chat.rooms.findOrCreate({
  externalId: `dm-${a}-${b}`,
  participants: [{ externalUserId: a }, { externalUserId: b }],
});
```

Apps keep sending messages, reading history and subscribing as usual; only room management is restricted.

- AI assistants: https://abrova.ir/en/docs/chat/ai-assistants

<Callout kind="soon" title="Coming soon">
Abrova does not have a docs server for AI assistants yet. This page describes how it will work and what you can use today.
</Callout>

When it is ready, you connect your AI assistant (any tool that supports MCP, the open standard AI tools use to connect to outside sources) once. Then, when you ask it to add Abrova Chat to your project, it looks up the current SDK version, install lines and setup steps from these docs instead of answering from memory.

### What works today

- **Copy page for AI.** Every docs page has a **Copy page for AI** link. Paste the page into your assistant's chat before you ask it to write code.
- **Plain-text docs.** Give your assistant the address `https://abrova.ir/docs/llms.txt`. It lists every docs page as plain text that assistants read well.

Tell your assistant to follow the page you gave it, to install the SDK from Abrova Center as the page shows, and to use the placeholder keys from the docs.

### What it will do

The docs server will have read-only tools. Your assistant chooses them by itself; you do not call them by hand.

<ConfigTable headers={['Tool', 'What it will do']} rows={[
  ['list_products', 'Lists the Abrova products, with the platforms that have an SDK and the docs link.'],
  ['search_docs', 'Searches the docs for a few words or a short question and returns the best pages.'],
  ['read_doc', 'Returns one docs page as text, with its link and last-updated date.'],
  ['get_sdk_info', 'Returns the SDK package for a product and platform: name, current version and install lines.'],
  ['get_setup_guide', 'Returns the ordered setup steps for a product and platform: install, keys, initialization and how to test.'],
]} />

Examples of what you will be able to ask:

- **"Add Abrova Chat to my React Native app with a support room per order."** It would answer from [Quick Start](/docs/chat/quick-start) and [Rooms](/docs/chat/rooms).
- **"Sign my users into chat with tokens from my own server."** It would answer from [Authentication](/docs/chat/authentication).
- **"Show typing indicators and read receipts."** It would answer from [Events](/docs/chat/events) and [Messages](/docs/chat/messages).
- **"Send a push to offline users when a new message arrives."** It would answer from [Push setup](/docs/chat/push-setup) and [Notification settings](/docs/chat/notification-settings).
- **"Which Abrova key goes in the app and which one stays on the server?"** It would answer from [Authentication](/docs/chat/authentication).

### Privacy

- **What it reads:** the public Abrova docs, the current SDK versions, and the words your assistant sends (the search words, the page it wants, the product and platform names).
- **What it never sees:** your code, your files, your Abrova project, your keys or your users. The tools have no input for them, and they cannot change any setting.

<Callout kind="warn" title="Keep your keys out of the chat">
Never paste a key into a chat with an AI assistant. Your assistant writes the placeholder from the docs (`ab_live_your_api_key`); you put the real value in your project's configuration yourself. The server secret (`ab_srv_...`) belongs only on your server, in an environment variable.
</Callout>

More about AI assistants and Abrova: [AI assistants](/ai-assistants). Questions? [Contact us](/contact).

- Rooms & participants: https://abrova.ir/en/docs/chat/rooms

Create and manage chat rooms, add participants, and control room lifecycle.

#### Room Types

- `direct` — 1-to-1 conversation between two participants.
- `group` — Multi-participant chat.

<Callout kind="tip" title="Tip">
`findOrCreateRoom` is idempotent — call it every time a user opens a chat. If the room exists, participants are synced. If not, it's created.
</Callout>

### Find or Create a Room

Use `findOrCreateRoom` with your app's external ID. The call is idempotent: if a room already exists for that `externalId`, participants are synced and the existing room is returned.

#### Flutter

```dart
// Find or create room by external ID (idempotent — recommended)
final room = await client.findOrCreateRoom(
  externalId: 'order-456',         // Your app's unique ID
  type: RoomType.direct,
  participants: [
    {'externalUserId': 'seller-1', 'displayName': 'TechShop', 'locale': 'en'},
    {'externalUserId': 'buyer-2',  'displayName': 'Alice',    'locale': 'hy'},
  ],
  metadata: {
    'source': 'order',
    'pushVariables': {'storeName': 'TechShop', 'orderNumber': 'ORD-456'},
    'pushData': {'deepLink': 'myapp://orders/456'},
  },
);
```

#### iOS

```swift
// Find or create room by external ID (idempotent — recommended)
let room = try await client.findOrCreateRoom(
    externalId: "order-456",
    participants: [
        ["externalUserId": "seller-1", "displayName": "TechShop", "locale": "en"],
        ["externalUserId": "buyer-2",  "displayName": "Alice",    "locale": "hy"],
    ],
    metadata: [
        "source": "order",
        "pushVariables": ["storeName": "TechShop", "orderNumber": "ORD-456"],
        "pushData": ["deepLink": "myapp://orders/456"],
    ]
)
```

#### Android

```kotlin
// Find or create room by external ID (idempotent — recommended)
val room = client.findOrCreateRoom(
    externalId = "order-456",
    participants = listOf(
        mapOf("externalUserId" to "seller-1", "displayName" to "TechShop", "locale" to "en"),
        mapOf("externalUserId" to "buyer-2",  "displayName" to "Alice",    "locale" to "hy"),
    ),
    metadata = mapOf(
        "source" to "order",
        "pushVariables" to mapOf("storeName" to "TechShop", "orderNumber" to "ORD-456"),
        "pushData" to mapOf("deepLink" to "myapp://orders/456"),
    )
)
```

#### React Native

```typescript
// Find or create room by external ID (idempotent — recommended)
const room = await client.findOrCreateRoom(
  'order-456',
  [
    { externalUserId: 'seller-1', displayName: 'TechShop', locale: 'en' },
    { externalUserId: 'buyer-2',  displayName: 'Alice',    locale: 'hy' },
  ],
  {
    source: 'order',
    pushVariables: { storeName: 'TechShop', orderNumber: 'ORD-456' },
    pushData: { deepLink: 'myapp://orders/456' },
  }
);
```

#### Web

```typescript
// Find or create room by external ID (idempotent — recommended)
const room = await client.findOrCreateRoom({
  externalId: 'order-456',
  type: 'direct',
  participants: [
    { externalUserId: 'seller-1', displayName: 'TechShop', locale: 'en' },
    { externalUserId: 'buyer-2',  displayName: 'Alice',    locale: 'hy' },
  ],
  metadata: {
    source: 'order',
    pushVariables: { storeName: 'TechShop', orderNumber: 'ORD-456' },
    pushData: { deepLink: 'myapp://orders/456' },
  },
});
```

#### Node.js

```typescript
// Find or create room by external ID (idempotent — recommended)
// @abrova/chat 0.2.0+ returns { room, created }
const { room, created } = await abrovaChat.rooms.findOrCreate({
  externalId: 'order-456',
  type: 'direct',
  participants: [
    { externalUserId: 'seller-1', displayName: 'TechShop', locale: 'en' },
    { externalUserId: 'buyer-2',  displayName: 'Alice',    locale: 'hy' },
  ],
  metadata: {
    source: 'order',
    pushVariables: { storeName: 'TechShop', orderNumber: 'ORD-456' },
    pushData: { deepLink: 'myapp://orders/456' },
  },
});
```

#### REST API

```bash
# Find or create room (idempotent — recommended). Response: {"room": {...}, "created": true|false}
curl -X POST "https://chat.abrova.ir/api/v1/rooms/find-or-create" \
  -H "X-API-Key: ab_live_your_api_key" \
  -H "X-Server-Secret: $ABROVA_SERVER_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "externalId": "order-456",
    "type": "direct",
    "participants": [
      {"externalUserId": "seller-1", "displayName": "TechShop", "locale": "en"},
      {"externalUserId": "buyer-2",  "displayName": "Alice",    "locale": "hy"}
    ],
    "metadata": {
      "source": "order",
      "pushVariables": {"storeName": "TechShop", "orderNumber": "ORD-456"},
      "pushData": {"deepLink": "myapp://orders/456"}
    }
  }'
```

### Manage Rooms

List, fetch, and modify rooms after creation. Subscribe to realtime updates when the user opens a chat.

#### Flutter

```dart
// List rooms for current user (each Room carries lastMessage and unreadCount)
final rooms = await client.listRooms();

// Get a specific room
final room = await client.getRoom('room-id');

// Add a participant
await client.addParticipant(
  room.id,
  externalUserId: 'support-3',
  displayName: 'Support Agent',
  role: ParticipantRole.admin,
);
```

#### iOS

```swift
// List rooms for current user
let rooms = try await client.listRooms()

// Get a specific room
let room = try await client.getRoom("room-id")

// Subscribe to room events (realtime)
client.subscribeRoom(room.id)

// Unsubscribe when leaving the screen
client.unsubscribeRoom(room.id)
```

#### Android

```kotlin
// List rooms for current user
val rooms = client.listRooms()

// Get a specific room
val room = client.getRoom("room-id")

// Subscribe to room events (realtime)
client.subscribeRoom(room.id)

// Unsubscribe when leaving the screen
client.unsubscribeRoom(room.id)
```

#### React Native

```typescript
// List rooms for current user
const rooms = await client.listRooms();

// Get a specific room
const room = await client.getRoom('room-id');

// Subscribe to room events (realtime)
client.subscribeToRoom(room.id);

// Unsubscribe when leaving the screen
client.unsubscribeFromRoom(room.id);
```

#### Web

```typescript
// List rooms for current user
const rooms = await client.listRooms();

// Get a specific room
const room = await client.getRoom('room-id');

// Subscribe to room events (realtime)
client.subscribeToRoom(room.id);

// Unsubscribe when leaving the screen
client.unsubscribeFromRoom(room.id);
```

#### Node.js

```typescript
// List rooms for a user
const rooms = await abrovaChat.rooms.list('buyer-2');

// Get a specific room
const roomById = await abrovaChat.rooms.get('room-id');

// Get room by external ID
const roomByExt = await abrovaChat.rooms.getByExternalId('order-456');

// Add a participant
await abrovaChat.rooms.addParticipant(room.id, {
  externalUserId: 'support-3',
  displayName: 'Support Agent',
  role: 'admin',
});

// Get unread summary
const unread = await abrovaChat.rooms.getUnreadSummary('buyer-2');
```

#### REST API

```bash
# List rooms for a user
curl -X GET "https://chat.abrova.ir/api/v1/rooms?userId=buyer-2" \
  -H "X-API-Key: ab_live_your_api_key" -H "X-Server-Secret: $ABROVA_SERVER_SECRET"

# Add participant
curl -X POST "https://chat.abrova.ir/api/v1/rooms/{roomId}/participants" \
  -H "X-API-Key: ab_live_your_api_key" \
  -H "X-Server-Secret: $ABROVA_SERVER_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"externalUserId": "support-3", "displayName": "Support Agent", "role": "admin"}'
```

<Callout kind="note" title="Push Variables">
The `metadata.pushVariables` object is merged into push notification templates. For example, if your push template is `"{{storeName}} sent you a message"`, the `storeName` value from `pushVariables` will be interpolated automatically. Use `pushData` to attach custom key-value pairs (like deep links) to the push payload.
</Callout>

- Messages: https://abrova.ir/en/docs/chat/messages

Send, receive, and manage messages across all platforms. Supports text, images, files, reactions, replies, edits, deletes, and pins.

#### Message Types

- **Text** — Plain text messages
- **Image** — Photo attachments
- **File** — Document uploads
- **System** — Automated notices

### Send & Manage Messages

Send text or attachments, reply to existing messages, paginate history, edit/delete, react, and pin — all from one client API.

#### Flutter

```dart
// Send a text message
await client.sendMessage(
  room.id,
  content: 'Your order has been shipped!',
  metadata: {
    'pushVariables': {'trackingNumber': 'TRK-789'},
  },
);

// Send with attachment
await client.sendMessage(
  room.id,
  content: 'Receipt attached',
  type: MessageType.file,
  attachments: [
    Attachment(url: '...', mimeType: 'application/pdf', name: 'receipt.pdf', size: 51200),
  ],
);

// Reply to a message
await client.sendMessage(room.id, content: 'Thanks!', replyToId: originalMsg.id);

// Get history (paginated, oldest first; pass the oldest id to load earlier ones)
final result = await client.getMessages(room.id, limit: 50);
final older = await client.getMessages(room.id, limit: 50, before: result.messages.first.id);

// Mark as read
await client.markAsRead(room.id);

// Edit / Delete
await client.editMessage(messageId, content: 'Updated content');
await client.deleteMessage(messageId);

// Reactions
await client.addReaction(messageId, emoji: '👍');
await client.removeReaction(messageId, emoji: '👍');

// Pin / Unpin
await client.pinMessage(messageId);
await client.unpinMessage(messageId);
```

#### iOS

```swift
// Send a text message
let message = try await client.sendMessage(
    room.id,
    content: "Your order has been shipped!",
    metadata: ["pushVariables": ["trackingNumber": "TRK-789"]]
)

// Send with attachment
try await client.sendMessage(
    room.id,
    content: "Receipt attached",
    type: .file,
    attachments: [
        Attachment(url: "https://...", mimeType: "application/pdf", name: "receipt.pdf", size: 51200)
    ]
)

// Reply to a message
try await client.sendMessage(room.id, content: "Thanks!", replyToId: originalMsg.id)

// Get history (paginated, oldest first; pass the oldest id to load earlier ones)
let result = try await client.getMessages(room.id, limit: 50)
let older = try await client.getMessages(room.id, limit: 50, before: result.messages.first?.id)

// Mark as read
try await client.markAsRead(room.id)

// Edit / Delete
try await client.editMessage(messageId, content: "Updated content")
try await client.deleteMessage(messageId)

// Reactions
try await client.addReaction(messageId, emoji: "👍")
try await client.removeReaction(messageId, emoji: "👍")
```

#### Android

```kotlin
// Send a text message
val message = client.sendMessage(
    roomId = room.id,
    content = "Your order has been shipped!",
    metadata = mapOf("pushVariables" to mapOf("trackingNumber" to "TRK-789"))
)

// Send with attachment
client.sendMessage(
    roomId = room.id,
    content = "Receipt attached",
    type = MessageType.FILE,
    attachments = listOf(
        Attachment(url = "https://...", mimeType = "application/pdf", name = "receipt.pdf", size = 51200)
    )
)

// Reply to a message
client.sendMessage(roomId = room.id, content = "Thanks!", replyToId = originalMsg.id)

// Get history (paginated, oldest first; pass the oldest id to load earlier ones)
val result = client.getMessages(room.id, limit = 50)
val older = client.getMessages(room.id, limit = 50, before = result.messages.first().id)

// Mark as read
client.markAsRead(room.id)

// Edit / Delete
client.editMessage(messageId, content = "Updated content")
client.deleteMessage(messageId)

// Reactions
client.addReaction(messageId, emoji = "👍")
client.removeReaction(messageId, emoji = "👍")
```

#### React Native

```typescript
// Send a text message
const message = await client.sendMessage(roomId, 'Your order has been shipped!', {
  metadata: { pushVariables: { trackingNumber: 'TRK-789' } },
});

// Send with attachment
await client.sendMessage(roomId, 'Receipt attached', {
  type: 'file',
  attachments: [
    { url: 'https://...', mimeType: 'application/pdf', name: 'receipt.pdf', size: 51200 },
  ],
});

// Reply to a message
await client.sendMessage(roomId, 'Thanks!', { replyToId: originalMsg.id });

// Get history (paginated, oldest first; pass the oldest id to load earlier ones)
const { messages } = await client.getMessages(roomId, { limit: 50 });
const older = await client.getMessages(roomId, { limit: 50, before: messages[0].id });

// Mark as read
await client.markAsRead(roomId, lastMessageId);

// Edit / Delete
await client.editMessage(roomId, messageId, 'Updated content');
await client.deleteMessage(roomId, messageId);

// Reactions
await client.addReaction(roomId, messageId, '👍');
await client.removeReaction(roomId, messageId, '👍');

// Pin / Unpin
await client.pinMessage(roomId, messageId);
await client.unpinMessage(roomId, messageId);
```

#### Web

```typescript
// Send a text message
const message = await client.sendMessage(roomId, 'Your order has been shipped!', {
  metadata: { pushVariables: { trackingNumber: 'TRK-789' } },
});

// Send with attachment
await client.sendMessage(roomId, 'Receipt attached', {
  type: 'file',
  attachments: [
    { url: 'https://...', mimeType: 'application/pdf', name: 'receipt.pdf', size: 51200 },
  ],
});

// Reply to a message
await client.sendMessage(roomId, 'Thanks!', { replyToId: originalMsg.id });

// Get history (paginated, oldest first; pass the oldest id to load earlier ones)
const { messages } = await client.getMessages(roomId, { limit: 50 });
const older = await client.getMessages(roomId, { limit: 50, before: messages[0].id });

// Mark as read
await client.markAsRead(roomId);

// Edit / Delete
await client.editMessage(messageId, 'Updated content');
await client.deleteMessage(messageId);

// Reactions
await client.addReaction(messageId, '👍');
await client.removeReaction(messageId, '👍');

// Pin / Unpin
await client.pinMessage(messageId);
await client.unpinMessage(messageId);
```

#### Node.js

```typescript
// Send a text message
const message = await abrovaChat.messages.send(room.id, {
  senderUserId: 'seller-1',
  content: 'Your order has been shipped!',
  metadata: { pushVariables: { trackingNumber: 'TRK-789' } },
});

// Send with attachment
await abrovaChat.messages.send(room.id, {
  senderUserId: 'seller-1',
  content: 'Receipt attached',
  type: 'file',
  attachments: [
    { url: 'https://...', mimeType: 'application/pdf', name: 'receipt.pdf', size: 51200 },
  ],
});

// Reply to a message
await abrovaChat.messages.send(room.id, {
  senderUserId: 'buyer-2',
  content: 'Thanks!',
  replyToId: message.id,
});

// Get history (paginated)
const { messages, hasMore } = await abrovaChat.messages.getHistory(room.id, {
  userId: 'buyer-2',
  limit: 50,
});

// Mark as read
await abrovaChat.messages.markAsRead(room.id, 'buyer-2');

// Edit / Delete
await abrovaChat.messages.edit(messageId, 'seller-1', 'Updated content');
await abrovaChat.messages.delete(messageId, 'seller-1');

// Reactions
await abrovaChat.reactions.add(messageId, 'buyer-2', '👍');
await abrovaChat.reactions.remove(messageId, 'buyer-2', '👍');

// Pin / Unpin
await abrovaChat.pins.pin(messageId, 'seller-1');
await abrovaChat.pins.unpin(messageId, 'seller-1');

// Search messages
const results = await abrovaChat.messages.search(room.id, {
  q: 'shipped',
  userId: 'buyer-2',
});
```

#### REST API

```bash
# Send message with custom push variables
curl -X POST "https://chat.abrova.ir/api/v1/rooms/{roomId}/messages" \
  -H "X-API-Key: ab_live_your_api_key" \
  -H "X-Server-Secret: $ABROVA_SERVER_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "senderUserId": "seller-1",
    "content": "Your order has been shipped!",
    "metadata": {
      "pushVariables": {"trackingNumber": "TRK-789"}
    }
  }'

# Get messages (paginated)
curl "https://chat.abrova.ir/api/v1/rooms/{roomId}/messages?userId=buyer-2&limit=50" \
  -H "X-API-Key: ab_live_your_api_key" -H "X-Server-Secret: $ABROVA_SERVER_SECRET"

# Mark as read
curl -X POST "https://chat.abrova.ir/api/v1/rooms/{roomId}/read" \
  -H "X-API-Key: ab_live_your_api_key" -H "X-Server-Secret: $ABROVA_SERVER_SECRET" \
  -H "Content-Type: application/json" -d '{"userId": "buyer-2"}'

# Edit message
curl -X PUT "https://chat.abrova.ir/api/v1/messages/{messageId}" \
  -H "X-API-Key: ab_live_your_api_key" -H "X-Server-Secret: $ABROVA_SERVER_SECRET" \
  -H "Content-Type: application/json" -d '{"userId": "seller-1", "content": "Updated"}'

# Reactions
curl -X POST "https://chat.abrova.ir/api/v1/messages/{messageId}/reactions" \
  -H "X-API-Key: ab_live_your_api_key" -H "X-Server-Secret: $ABROVA_SERVER_SECRET" \
  -H "Content-Type: application/json" -d '{"userId": "buyer-2", "emoji": "👍"}'

# Pin message
curl -X POST "https://chat.abrova.ir/api/v1/messages/{messageId}/pin" \
  -H "X-API-Key: ab_live_your_api_key" -H "X-Server-Secret: $ABROVA_SERVER_SECRET" \
  -H "Content-Type: application/json" -d '{"userId": "seller-1"}'
```

<Callout kind="note" title="Per-message push variables">
You can pass `pushVariables` per message via `metadata.pushVariables`. These variables are merged into your push notification templates at delivery time, allowing each message to customize the notification the recipient sees.
</Callout>

- Realtime events: https://abrova.ir/en/docs/chat/events

Realtime events over a WebSocket connection with automatic reconnect and event recovery.

#### Event Types

- **Messages** — new message arrives
- **Read Receipts** — recipient marks the room as read
- **Typing** — start/stop typing in a room
- **Presence** — user online/offline transitions
- **Deletions** — message deleted
- **Edits** — message edited
- **Reactions** — emoji added/removed
- **Pins** — message pinned/unpinned

### Subscribe & Listen to Events

Subscribe to a room and listen to its realtime stream. Unsubscribe when the user leaves the screen to stop receiving events.

#### Flutter

```dart
// Subscribe to room channels (auto-done when using UI kit)
await client.subscribeRoom(room.id);

// Listen to realtime streams
client.onMessage.listen((message) {
  print('New message: ${message.content}');
});

client.onReadReceipt.listen((receipt) {
  print('${receipt.userId} read at ${receipt.readAt}');
});

client.onTypingEvent.listen((event) {
  print('${event.userId} ${event.isTyping ? "started" : "stopped"} typing');
});

client.onPresenceChange.listen((event) {
  print('${event.userId} is ${event.isOnline ? "online" : "offline"}');
});

client.onReactionEvent.listen((event) {
  print('${event.userId} ${event.added ? "added" : "removed"} ${event.emoji}');
});

client.onMessageEdited.listen((event) {
  print('Message ${event.messageId} edited to: ${event.content}');
});

client.onMessagePinChanged.listen((event) {
  print('Message ${event.messageId} ${event.pinned ? "pinned" : "unpinned"}');
});

// Send typing indicator
await client.publishTyping(room.id);

// Check presence in a room
final onlineUsers = await client.getRoomPresence(room.id);

// Unsubscribe when done
await client.unsubscribeRoom(room.id);
```

#### iOS

```swift
// Subscribe to room events
client.subscribeRoom(room.id)

// Listen to realtime events using Combine
client.onMessage
    .sink { message in print("New message: \(message.content)") }
    .store(in: &cancellables)

client.onReadReceipt
    .sink { event in print("\(event.userId) read at \(event.readAt)") }
    .store(in: &cancellables)

client.onTypingEvent
    .sink { event in print("\(event.userId) is \(event.isTyping ? "typing" : "not typing")") }
    .store(in: &cancellables)

client.onPresenceChange
    .sink { event in print("\(event.userId) is \(event.isOnline ? "online" : "offline")") }
    .store(in: &cancellables)

client.onReactionEvent
    .sink { event in print("\(event.userId) \(event.added ? "added" : "removed") \(event.emoji)") }
    .store(in: &cancellables)

client.onMessageEdited
    .sink { event in print("Message \(event.messageId) edited") }
    .store(in: &cancellables)

client.onMessageDeleted
    .sink { event in print("Message \(event.messageId) deleted") }
    .store(in: &cancellables)

// Send typing indicator
client.publishTyping(room.id)

// Check presence in a room
let onlineUsers = try await client.getRoomPresence(room.id)

// Unsubscribe when done
client.unsubscribeRoom(room.id)
```

#### Android

```kotlin
// Subscribe to room events
client.subscribeRoom(room.id)

// Listen to realtime events using Kotlin Flow
lifecycleScope.launch {
    client.onMessage.collect { message ->
        println("New message: ${message.content}")
    }
}

lifecycleScope.launch {
    client.onReadReceipt.collect { event ->
        println("${event.userId} read at ${event.readAt}")
    }
}

lifecycleScope.launch {
    client.onTypingEvent.collect { event ->
        println("${event.userId} is ${if (event.isTyping) "typing" else "not typing"}")
    }
}

lifecycleScope.launch {
    client.onPresenceChange.collect { event ->
        println("${event.userId} is ${if (event.isOnline) "online" else "offline"}")
    }
}

lifecycleScope.launch {
    client.onReactionEvent.collect { event ->
        println("${event.userId} ${if (event.added) "added" else "removed"} ${event.emoji}")
    }
}

lifecycleScope.launch {
    client.onMessageEdited.collect { event ->
        println("Message ${event.messageId} edited")
    }
}

lifecycleScope.launch {
    client.onMessageDeleted.collect { event ->
        println("Message ${event.messageId} deleted")
    }
}

// Send typing indicator
client.publishTyping(room.id)

// Check presence in a room
val onlineUsers = client.getRoomPresence(room.id)

// Unsubscribe when done
client.unsubscribeRoom(room.id)
```

#### React Native

```typescript
// Subscribe to room events
client.subscribeToRoom(roomId);

// Listen to realtime events
client.on('message', (event) => {
  console.log('New message:', event.message.content);
});

client.on('readReceipt', (event) => {
  console.log(`${event.userId} read up to ${event.readAt}`);
});

client.on('typing', (event) => {
  console.log(`${event.userId} is typing in room ${event.roomId}`);
});

client.on('presence', (event) => {
  console.log(`${event.userId} is ${event.isOnline ? 'online' : 'offline'}`);
});

client.on('reaction', (event) => {
  console.log(`${event.userId} ${event.added ? 'added' : 'removed'} ${event.emoji}`);
});

client.on('messageEdited', (event) => {
  console.log(`Message ${event.messageId} edited to: ${event.content}`);
});

client.on('messageDeleted', (event) => {
  console.log(`Message ${event.messageId} deleted`);
});

// Send typing indicator
await client.publishTyping(roomId);

// Check presence in a room
const onlineUsers = await client.getRoomPresence(roomId);

// Unsubscribe when done
client.unsubscribeFromRoom(roomId);
```

#### Web

```typescript
// Subscribe to room events
client.subscribeToRoom(roomId);

// Listen to realtime events
client.on('message', (event) => {
  console.log('New message:', event.message.content);
});

client.on('readReceipt', (event) => {
  console.log(`${event.userId} read up to ${event.readAt}`);
});

client.on('typing', (event) => {
  console.log(`${event.userId} is typing in room ${event.roomId}`);
});

client.on('presence', (event) => {
  console.log(`${event.userId} is ${event.isOnline ? 'online' : 'offline'}`);
});

client.on('reaction', (event) => {
  console.log(`${event.userId} ${event.added ? 'added' : 'removed'} ${event.emoji}`);
});

client.on('messageEdited', (event) => {
  console.log(`Message ${event.messageId} edited to: ${event.content}`);
});

client.on('messageDeleted', (event) => {
  console.log(`Message ${event.messageId} deleted`);
});

// Send typing indicator
await client.publishTyping(roomId);

// Check presence in a room
const onlineUsers = await client.getRoomPresence(roomId);

// Unsubscribe when done
client.unsubscribeFromRoom(roomId);
```

#### Node.js (Token Generation)

Node.js is a server-side SDK — no WebSocket connection. Use it to mint the user tokens your client apps return from their `tokenProvider` (see [Authentication](/docs/chat/authentication)). The client SDKs use the same token for REST calls and the WebSocket connection.

```typescript
// Generate a user token for a user
const { token, expiresAt } = await abrovaChat.users.createToken({
  userId: 'user-123',
  info: { displayName: 'Alice' },
});

// Example Express.js endpoint — requireLogin is YOUR auth middleware.
// The client app's tokenProvider calls it and returns `token`.
app.get('/api/chat-token', requireLogin, async (req, res) => {
  const { token, expiresAt } = await abrovaChat.users.createToken({
    userId: req.user.id,
    info: { displayName: req.user.name },
  });
  res.json({ token, expiresAt });
});
```

#### REST API

```bash
# Get a user token (also valid for the WebSocket connection)
curl -X POST "https://chat.abrova.ir/api/v1/users/token" \
  -H "X-API-Key: ab_live_your_api_key" -H "X-Server-Secret: $ABROVA_SERVER_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"userId": "buyer-2", "info": {"displayName": "Alice"}}'

# Live events are delivered through the client SDKs (see above).
```

- UI widgets: https://abrova.ir/en/docs/chat/ui-widgets

AbrovaChat ships a two-package architecture: a headless core SDK for full control, and an optional UI kit with ready-made components.

<Callout kind="note" title="Two Package Architecture">
- **Core SDK** — Headless SDK for 100% custom UI
- **UI Kit** — Pre-built components that depend on core
</Callout>

#### Available Widgets

- `ChatScreen` — Complete drop-in chat UI
- `ChatMessageBubble` — Single message bubble
- `ChatInputField` — Input with emoji & attachments
- `TypingIndicator` — Animated typing dots
- `PresenceIndicator` — Online / offline status dot
- `UnreadBadge` — Unread message count badge
- `SwipeableMessage` — Swipe-to-reply gesture
- `MessageReactionPicker` — Emoji reaction selector

### Flutter UI Kit

The `abrova_chat_ui` package uses InheritedWidget (no Riverpod/Bloc required).

```dart
// The abrova_chat_ui package uses InheritedWidget (no Riverpod/Bloc required)
import 'package:abrova_chat/abrova_chat.dart';
import 'package:abrova_chat_ui/abrova_chat_ui.dart';

// Step 1: Wrap your app with AbrovaChatScope
AbrovaChatScope(
  config: AbrovaChatConfig(apiKey: 'ab_live_your_api_key', userId: 'user-123'),
  child: MaterialApp(...),
)

// Step 2: Use pre-built widgets

// Option A: Full chat screen (drop-in)
ChatScreen(
  roomId: 'room-uuid',
  currentUserId: 'buyer-2',
)

// Option B: Build custom layout with individual widgets
ChatChannelScope(
  roomId: 'room-uuid',
  child: Column(
    children: [
      Expanded(
        child: Builder(builder: (context) {
          final state = ChatChannelScope.of(context);
          return ListView(children: [
            for (final m in state.messages)
              ChatMessageBubble(message: m, isMe: m.senderUserId == 'buyer-2'),
          ]);
        }),
      ),
      TypingIndicator(roomId: 'room-uuid'),
      ChatInputField(roomId: 'room-uuid'),
    ],
  ),
)

// Access state via InheritedWidget:
final client = AbrovaChatScope.of(context);     // Get AbrovaChatClient
final state = ChatChannelScope.of(context);   // Get room state

// Available widgets:
ChatScreen          // Complete chat UI
ChatMessageBubble   // Single message bubble
ChatInputField      // Input with emoji, attachments
TypingIndicator     // Animated typing dots
PresenceIndicator   // Online/offline dot
UnreadBadge         // Unread count badge
```

### iOS UI Kit

The `AbrovaChatUI` package uses SwiftUI Environment.

```swift
import AbrovaChat
import AbrovaChatUI

// Step 1: Wrap your app with AbrovaChatScope
let config = AbrovaChatConfig(apiKey: "ab_live_your_api_key", userId: "user-123")

AbrovaChatScope(config: config) {
    ContentView()
}

// Step 2: Use pre-built views

// Option A: Full chat screen (drop-in)
ChatScreen(roomId: "room-uuid", currentUserId: "buyer-2")

// Option B: Build custom layout with ChatChannelScope
// (@State private var draft = "" in your view)
ChatChannelScope(roomId: "room-uuid", currentUserId: "buyer-2") { state in
    VStack {
        ScrollView {
            ForEach(state.messages, id: \.id) { message in
                ChatMessageBubble(message: message, isMe: message.senderUserId == "buyer-2")
            }
        }
        TypingIndicator(typingUsers: state.typingUsers)
        ChatInputField(text: $draft, onSend: { text in
            Task { await state.sendMessage(content: text) }
        })
    }
}

// Access client via Environment:
@Environment(\.abrovaChatClient) var client

// Available views:
ChatScreen           // Complete chat UI
ChatMessageBubble    // Single message bubble
ChatInputField       // Input with emoji, attachments
TypingIndicator      // Animated typing dots
PresenceIndicator    // Online/offline status
UnreadBadge          // Unread count badge
```

### Android UI Kit

The `abrova-chat-ui` package uses Jetpack Compose CompositionLocal.

```kotlin
import ir.abrova.chat.AbrovaChatClient
import ir.abrova.chat.AbrovaChatConfig
import ir.abrova.chat.ui.components.*
import ir.abrova.chat.ui.state.*

// Step 1: Wrap your app with AbrovaChatScope
val config = AbrovaChatConfig(apiKey = "ab_live_your_api_key", userId = "user-123")

AbrovaChatScope(config = config) {
    App()
}

// Step 2: Use pre-built composables

// Option A: Full chat screen (drop-in)
ChatScreen(roomId = "room-uuid", currentUserId = "buyer-2")

// Option B: Build custom layout with rememberChatChannelState
val state = rememberChatChannelState(roomId = "room-uuid", currentUserId = "buyer-2")
val scope = rememberCoroutineScope()
Column {
    LazyColumn(modifier = Modifier.weight(1f)) {
        items(state.messages) { message ->
            ChatMessageBubble(message = message, isMe = message.senderUserId == "buyer-2")
        }
    }
    TypingIndicator(typingUsers = state.typingUsers)
    ChatInputField(onSendMessage = { text -> scope.launch { state.sendMessage(text) } })
}

// Access client via CompositionLocal:
val client = LocalAbrovaChatClient.current

// Available composables:
ChatScreen           // Complete chat UI
ChatMessageBubble    // Single message bubble
ChatInputField       // Input with emoji, attachments
TypingIndicator      // Animated typing dots
PresenceIndicator    // Online/offline status
UnreadBadge          // Unread count badge
```

### React Native UI Kit

The `@abrova/react-native-chat-ui` package uses React Context.

```tsx
import { AbrovaChatClient } from '@abrova/react-native-chat';
import { AbrovaChatProvider, ChatScreen } from '@abrova/react-native-chat-ui';

// Step 1: Create client and wrap your app
const client = new AbrovaChatClient({
  apiKey: 'ab_live_your_api_key',
  userId: 'user-123',
});

<AbrovaChatProvider client={client} autoConnect>
  <App />
</AbrovaChatProvider>

// Step 2: Use pre-built components

// Option A: Full chat screen (drop-in)
<ChatScreen roomId="room-uuid" currentUserId="buyer-2" />

// Option B: Build custom layout with the useChatChannel hook
import { useChatChannel, ChatMessageBubble, TypingIndicator, ChatInputField } from '@abrova/react-native-chat-ui';

function CustomChat({ roomId, currentUserId }) {
  const { messages, typingUsers, sendMessage } = useChatChannel(roomId, currentUserId);

  return (
    <View>
      {messages.map((m) => (
        <ChatMessageBubble key={m.id} message={m} isMe={m.senderUserId === currentUserId} />
      ))}
      <TypingIndicator typingUsers={typingUsers} />
      <ChatInputField onSendMessage={(text) => sendMessage(text)} />
    </View>
  );
}

// Available components:
ChatScreen            // Complete chat UI
ChatMessageBubble     // Single message bubble
ChatInputField        // Input with emoji, attachments
TypingIndicator       // Animated typing dots
PresenceIndicator     // Online/offline status
UnreadBadge           // Unread count badge
```

### Web UI Kit

The `@abrova/web-chat-ui` package uses React Context. It will be published on Abrova Center after the headless `@abrova/web-chat` package; the example below shows how it will be used.

```tsx
import { AbrovaChatClient } from '@abrova/web-chat';
import { AbrovaChatProvider, ChatScreen } from '@abrova/web-chat-ui';

// Step 1: Create client and wrap your app
const client = new AbrovaChatClient({
  apiKey: 'ab_live_your_api_key',
  userId: 'user-123',
});

<AbrovaChatProvider client={client} autoConnect>
  <App />
</AbrovaChatProvider>

// Step 2: Use pre-built components

// Option A: Full chat screen (drop-in)
<ChatScreen roomId="room-uuid" currentUserId="buyer-2" />

// Option B: Build custom layout with the useChatChannel hook
import { useChatChannel, ChatMessageBubble, TypingIndicator, ChatInputField } from '@abrova/web-chat-ui';

function CustomChat({ roomId, currentUserId }) {
  const { messages, typingUsers, sendMessage } = useChatChannel(roomId, currentUserId);

  return (
    <div>
      {messages.map((m) => (
        <ChatMessageBubble key={m.id} message={m} isMe={m.senderUserId === currentUserId} />
      ))}
      <TypingIndicator typingUsers={typingUsers} />
      <ChatInputField onSendMessage={(text) => sendMessage(text)} />
    </div>
  );
}

// Available components:
ChatScreen            // Complete chat UI
ChatMessageBubble     // Single message bubble
ChatInputField        // Input with emoji, attachments
TypingIndicator       // Animated typing dots
PresenceIndicator     // Online/offline status
UnreadBadge           // Unread count badge
```

### Node.js

Node.js is a server-side SDK — no UI components. Use it for backend operations:

```typescript
// 1. Room management from your server
const { room } = await abrovaChat.rooms.findOrCreate({
  externalId: 'order-456',
  participants: [
    { externalUserId: 'seller-1', displayName: 'TechShop' },
    { externalUserId: 'buyer-2', displayName: 'Alice' },
  ],
});

// 2. Send system messages from your backend
await abrovaChat.messages.send(room.id, {
  senderUserId: 'system',
  content: 'Order #456 has been shipped!',
  type: 'system',
});

// 3. Configure webhooks and push notifications
await abrovaChat.webhooks.setWebhook({
  url: 'https://your-server.com/webhooks/abrova-chat',
  secret: 'your-hmac-secret',
});

// 4. Generate user tokens for client apps (returned by their tokenProvider)
const { token } = await abrovaChat.users.createToken({
  userId: 'user-123',
});

// For UI, use the client SDKs:
// Flutter: abrova_chat + abrova_chat_ui
// Web: @abrova/web-chat + @abrova/web-chat-ui
// React Native: @abrova/react-native-chat + @abrova/react-native-chat-ui
```

### REST API

Use the REST endpoints to build any custom interface.

```bash
# Get messages for display
curl "https://chat.abrova.ir/api/v1/rooms/{roomId}/messages?userId={userId}&limit=50" \
  -H "X-API-Key: ab_live_your_api_key" -H "X-Server-Secret: $ABROVA_SERVER_SECRET"

# Send a message
curl -X POST "https://chat.abrova.ir/api/v1/rooms/{roomId}/messages" \
  -H "X-API-Key: ab_live_your_api_key" -H "X-Server-Secret: $ABROVA_SERVER_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"senderUserId": "user-123", "content": "Hello!"}'

# For realtime updates, use a client SDK (a WebSocket connection with automatic reconnect):
# 1. Get a user token: POST /api/v1/users/token (server secret required)
# 2. Return it from the client SDK's tokenProvider; the SDK connects and subscribes for you
```

- Core SDK API: https://abrova.ir/en/docs/chat/core-api

Complete API reference for every method available on the AbrovaChat client.

### Full API Reference

The full surface of `AbrovaChatClient` and the Node.js modular API, by platform.

#### Flutter

```dart
// AbrovaChatClient — Core SDK API
final client = AbrovaChatClient(config);

// Connection
await client.connect();
await client.disconnect();
client.dispose();

// Rooms
final rooms = await client.listRooms();
final room = await client.findOrCreateRoom(externalId: id, participants: participants);
final roomById = await client.getRoom(roomId);

// Messages
final result = await client.getMessages(roomId, limit: 50);
await client.sendMessage(roomId, content: 'Hello!');
await client.editMessage(messageId, content: 'Updated');
await client.deleteMessage(messageId);

// Mark as read
await client.markAsRead(roomId);

// Reactions
await client.addReaction(messageId, emoji: '👍');
await client.removeReaction(messageId, emoji: '👍');

// Room subscriptions (WebSocket)
await client.subscribeRoom(roomId);
await client.unsubscribeRoom(roomId);

// Presence & Typing
final onlineUsers = await client.getRoomPresence(roomId);
await client.publishTyping(roomId);

// Unread summary
final summary = await client.getUnreadSummary();

// Event streams (for custom UI)
client.onMessage              // Stream<Message>
client.onReadReceipt          // Stream<ReadReceipt>
client.onTypingEvent          // Stream<TypingEvent>
client.onPresenceChange       // Stream<PresenceEvent>
client.onReactionEvent        // Stream<ReactionEvent>
client.onMessageEdited        // Stream<MessageEditEvent>
client.onMessagePinChanged    // Stream<MessagePinEvent>
client.onConnectionStateChange // Stream<ConnectionState>
```

#### iOS

```swift
// AbrovaChatClient — Core SDK API
let client = AbrovaChatClient(config: config)

// Connection
try await client.connect()
client.disconnect()
client.dispose()

// Rooms
let rooms = try await client.listRooms()
let room = try await client.findOrCreateRoom(externalId: id, participants: participants)
let roomById = try await client.getRoom(roomId)

// Messages
let result = try await client.getMessages(roomId, limit: 50)
try await client.sendMessage(roomId, content: "Hello!")
try await client.editMessage(messageId, content: "Updated")
try await client.deleteMessage(messageId)

// Mark as read
try await client.markAsRead(roomId)

// Reactions
try await client.addReaction(messageId, emoji: "👍")
try await client.removeReaction(messageId, emoji: "👍")

// Room subscriptions (WebSocket)
client.subscribeRoom(roomId)
client.unsubscribeRoom(roomId)

// Presence & Typing
let onlineUsers = try await client.getRoomPresence(roomId)
client.publishTyping(roomId)

// Unread summary
let summary = try await client.getUnreadSummary()

// Combine publishers (for custom UI)
client.onMessage              // AnyPublisher<Message, Never>
client.onReadReceipt          // AnyPublisher<ReadReceipt, Never>
client.onTypingEvent          // AnyPublisher<TypingEvent, Never>
client.onPresenceChange       // AnyPublisher<PresenceEvent, Never>
client.onReactionEvent        // AnyPublisher<ReactionEvent, Never>
client.onMessageEdited        // AnyPublisher<MessageEditEvent, Never>
client.onMessageDeleted       // AnyPublisher<MessageDeletion, Never>
client.onMessagePinChanged    // AnyPublisher<MessagePinEvent, Never>
```

#### Android

```kotlin
// AbrovaChatClient — Core SDK API
val client = AbrovaChatClient(config)

// Connection
client.connect()
client.disconnect()
client.dispose()

// Rooms
val rooms = client.listRooms()
val room = client.findOrCreateRoom(externalId = id, participants = participants, metadata = metadata)
val roomById = client.getRoom(roomId)

// Messages
val result = client.getMessages(roomId, limit = 50)
client.sendMessage(roomId, content = "Hello!")
client.editMessage(messageId, content = "Updated")
client.deleteMessage(messageId)

// Mark as read
client.markAsRead(roomId)

// Reactions
client.addReaction(messageId, emoji = "👍")
client.removeReaction(messageId, emoji = "👍")

// Room subscriptions (WebSocket)
client.subscribeRoom(roomId)
client.unsubscribeRoom(roomId)

// Presence & Typing
val onlineUsers = client.getRoomPresence(roomId)
client.publishTyping(roomId)

// Unread summary
val summary = client.getUnreadSummary()

// Kotlin Flow streams (for custom UI)
client.onMessage              // SharedFlow<Message>
client.onReadReceipt          // SharedFlow<ReadReceipt>
client.onTypingEvent          // SharedFlow<TypingEvent>
client.onPresenceChange       // SharedFlow<PresenceEvent>
client.onReactionEvent        // SharedFlow<ReactionEvent>
client.onMessageEdited        // SharedFlow<MessageEditEvent>
client.onMessageDeleted       // SharedFlow<MessageDeletion>
client.onMessagePinChanged    // SharedFlow<MessagePinEvent>
```

#### React Native

```typescript
// AbrovaChatClient — Core SDK API
const client = new AbrovaChatClient(config);

// Connection
client.connect();
client.disconnect();
client.dispose();

// Rooms
const rooms = await client.listRooms();
const room = await client.findOrCreateRoom(externalId, participants, metadata);
const roomById = await client.getRoom(roomId);

// Messages
const { messages } = await client.getMessages(roomId, { limit: 50 });
await client.sendMessage(roomId, 'Hello!');
await client.editMessage(roomId, messageId, 'Updated');
await client.deleteMessage(roomId, messageId);

// Mark as read
await client.markAsRead(roomId, messageId);

// Reactions
await client.addReaction(roomId, messageId, '👍');
await client.removeReaction(roomId, messageId, '👍');

// Pin / Unpin
await client.pinMessage(roomId, messageId);
await client.unpinMessage(roomId, messageId);

// Room subscriptions (WebSocket)
client.subscribeToRoom(roomId);
client.unsubscribeFromRoom(roomId);

// Presence & Typing
const onlineUsers = await client.getRoomPresence(roomId);
await client.publishTyping(roomId);

// Unread summary
const summary = await client.getUnreadSummary();

// Event listeners (for custom UI)
client.on('message', (event) => { /* MessageEvent: { message } */ });
client.on('readReceipt', (event) => { /* ReadReceiptEvent */ });
client.on('typing', (event) => { /* TypingEvent */ });
client.on('presence', (event) => { /* PresenceEvent */ });
client.on('reaction', (event) => { /* ReactionEvent */ });
client.on('messageEdited', (event) => { /* MessageEditEvent */ });
client.on('messageDeleted', (event) => { /* MessageDeletionEvent */ });
client.on('messagePinChanged', (event) => { /* MessagePinEvent */ });
client.on('authError', (event) => { /* AuthErrorEvent */ });
```

#### Web

```typescript
// AbrovaChatClient — Core SDK API
const client = new AbrovaChatClient(config);

// Connection
await client.connect();
client.disconnect();
client.dispose();

// Rooms
const rooms = await client.listRooms();
const room = await client.findOrCreateRoom({ externalId, participants, metadata });
const roomById = await client.getRoom(roomId);

// Messages
const { messages } = await client.getMessages(roomId, { limit: 50 });
await client.sendMessage(roomId, 'Hello!');
await client.editMessage(messageId, 'Updated');
await client.deleteMessage(messageId);

// Mark as read
await client.markAsRead(roomId);

// Reactions
await client.addReaction(messageId, '👍');
await client.removeReaction(messageId, '👍');

// Pin / Unpin
await client.pinMessage(messageId);
await client.unpinMessage(messageId);

// Room subscriptions (WebSocket)
client.subscribeToRoom(roomId);
client.unsubscribeFromRoom(roomId);

// Presence & Typing
const onlineUsers = await client.getRoomPresence(roomId);
await client.publishTyping(roomId);

// Unread summary
const summary = await client.getUnreadSummary();

// Event listeners (for custom UI)
client.on('message', (event) => { /* MessageEvent: { message } */ });
client.on('readReceipt', (event) => { /* ReadReceiptEvent */ });
client.on('typing', (event) => { /* TypingEvent */ });
client.on('presence', (event) => { /* PresenceEvent */ });
client.on('reaction', (event) => { /* ReactionEvent */ });
client.on('messageEdited', (event) => { /* MessageEditEvent */ });
client.on('messageDeleted', (event) => { /* MessageDeletionEvent */ });
client.on('messagePinChanged', (event) => { /* MessagePinEvent */ });
client.on('authError', (event) => { /* AuthErrorEvent */ });
```

#### Node.js

```typescript
// AbrovaChat Node.js SDK — Modular API
import { AbrovaChat } from '@abrova/chat';
const abrovaChat = new AbrovaChat({
  apiKey: 'ab_live_your_api_key',
  serverSecret: process.env.ABROVA_SERVER_SECRET,
});

// ─── abrovaChat.rooms ───
abrovaChat.rooms.create(options)                         // Create room
abrovaChat.rooms.findOrCreate(options)                   // Find or create by externalId → { room, created }
abrovaChat.rooms.get(roomId)                             // Get room by ID
abrovaChat.rooms.getByExternalId(externalId)             // Get room by external ID
abrovaChat.rooms.list(userId)                            // List rooms for user
abrovaChat.rooms.addParticipant(roomId, options)          // Add participant
abrovaChat.rooms.removeParticipant(roomId, externalUserId) // Remove participant
abrovaChat.rooms.delete(roomId)                          // Delete room
abrovaChat.rooms.getUnreadSummary(userId)                // Unread counts
abrovaChat.rooms.getNotificationSettings(roomId, userId)  // Per-room push settings
abrovaChat.rooms.updateNotificationSettings(roomId, userId, settings)

// ─── abrovaChat.messages ───
abrovaChat.messages.send(roomId, options)                // Send message
abrovaChat.messages.getHistory(roomId, options)           // Paginated history
abrovaChat.messages.markAsRead(roomId, userId)            // Mark as read
abrovaChat.messages.edit(messageId, userId, content)      // Edit message
abrovaChat.messages.delete(messageId, userId)             // Delete message
abrovaChat.messages.search(roomId, options)               // Search messages
abrovaChat.messages.getMentions(roomId, options)           // Get @mentions

// ─── abrovaChat.reactions ───
abrovaChat.reactions.add(messageId, userId, emoji)        // Add reaction
abrovaChat.reactions.remove(messageId, userId, emoji)     // Remove reaction
abrovaChat.reactions.list(messageId)                      // List reactions

// ─── abrovaChat.pins ───
abrovaChat.pins.pin(messageId, userId)                    // Pin message
abrovaChat.pins.unpin(messageId, userId)                  // Unpin message
abrovaChat.pins.list(roomId)                              // List pinned messages

// ─── abrovaChat.webhooks ───
abrovaChat.webhooks.get()                                 // Get config
abrovaChat.webhooks.setWebhook({ url, secret? })          // Set webhook
abrovaChat.webhooks.removeWebhook()                       // Remove webhook
abrovaChat.webhooks.setPushTemplate(templateId)            // Set push template
abrovaChat.webhooks.removePushTemplate()                   // Remove push template
abrovaChat.webhooks.setPushTemplates(templates)             // Per-event templates
abrovaChat.webhooks.removePushTemplates()                  // Remove per-event

// ─── abrovaChat.users ───
abrovaChat.users.createToken({ userId, info?, ttl? })      // User token for tokenProvider
abrovaChat.users.revokeTokens(userId)                     // Revoke all of a user's tokens
abrovaChat.users.getNotificationSettings(userId)          // App-wide push settings
abrovaChat.users.updateNotificationSettings(userId, settings)

// ─── abrovaChat.tokens ───
abrovaChat.tokens.getConnectionToken({ userId, info? })   // Legacy connection token (prefer users.createToken)
```

#### REST API

```bash
# AbrovaChatClient — REST API Endpoints

# Rooms
GET  /api/v1/rooms?userId={userId}                    # List rooms
POST /api/v1/rooms/find-or-create                     # Find or create room
GET  /api/v1/rooms/{roomId}                           # Get room

# Messages
GET  /api/v1/rooms/{roomId}/messages?userId={userId}  # Get messages
POST /api/v1/rooms/{roomId}/messages                  # Send message
PUT  /api/v1/messages/{messageId}                     # Edit message
DELETE /api/v1/messages/{messageId}?userId={userId}   # Delete message

# Mark as read
POST /api/v1/rooms/{roomId}/read                      # Mark as read

# Reactions
POST /api/v1/messages/{messageId}/reactions           # Add reaction
DELETE /api/v1/messages/{messageId}/reactions         # Remove reaction

# Presence (typing is published over the WebSocket, not REST)
GET  /api/v1/rooms/{roomId}/presence                  # Get presence

# User tokens (server secret required)
POST /api/v1/users/token                              # Mint a user token (REST + WebSocket)

# Realtime (WebSocket): the client SDKs connect with the user token above
```

- Push setup: https://abrova.ir/en/docs/chat/push-setup

AbrovaChat automatically sends push notifications to offline participants via AbrovaPush.

### How it works

1. **Event occurs** — Message, reaction, pin, or other chat event is triggered.
2. **Check presence** — Who is currently online in the room?
3. **Offline users get push** — Push notification sent via AbrovaPush to offline participants.
4. **User settings** — Users who turned these pushes off or muted the room are skipped.
5. **Localized template** — Template rendered in the recipient's locale.

### Setup

Three steps to wire push notifications:

1. **Create a template in AbrovaPush** — In Abrova Console, open **AbrovaPush → Templates** and create a notification template. Use the built-in variables listed below to personalise the content.
2. **Configure push in AbrovaChat Settings** — In Abrova Console, open **Abrova Chat** and click **Notification Settings**, then link your AbrovaPush template. You can set a single default template or per-event templates.
3. **Set participant locale when creating rooms** — When adding participants, include their `locale` field (e.g. `"fa"`, `"en"`). AbrovaPush uses this to select the correct translation of your template.

### Built-in Template Variables

These variables are automatically populated by AbrovaChat and available in every push template.

<ConfigTable rows={[
  ['senderName', 'String', '-', 'Display name of who triggered the event (e.g. "Alice")'],
  ['recipientName', 'String', '-', 'Display name of the push recipient (e.g. "Bob")'],
  ['roomName', 'String', '-', 'Room name, or externalId, or room ID (e.g. "Order #456")'],
  ['messagePreview', 'String', '-', 'First 100 chars of the message'],
  ['messageType', 'String', '-', 'Message type (uppercase, e.g. "TEXT")'],
  ['roomId', 'String', '-', 'AbrovaChat internal room ID'],
  ['externalRoomId', 'String', '-', "Your app's external room ID"],
  ['emoji', 'String', '-', 'Emoji (reaction events only)'],
  ['participantName', 'String', '-', 'Name of participant who joined'],
]} />

### Push Event Types

Every chat event that produces an offline push notification.

<ConfigTable rows={[
  ['new_message', '-', '-', 'New text message from another user'],
  ['mention', '-', '-', 'User was @mentioned in a message'],
  ['reaction', '-', '-', 'Someone reacted to your message'],
  ['file_shared', '-', '-', 'Image or file message sent'],
  ['message_pinned', '-', '-', 'A message was pinned in the room'],
  ['room_created', '-', '-', 'Room was created, participants notified'],
  ['participant_joined', '-', '-', 'Someone was added to the room'],
  ['participant_removed', '-', '-', 'Someone left or was removed from the room'],
]} />

<Callout kind="note" title="Let users choose">
Users can turn chat pushes off, get them only when mentioned, or mute a room. See [Notification Settings](/docs/chat/notification-settings).
</Callout>

### Variable Merge Priority

When the same variable key exists at multiple levels, the highest-priority source wins:

```
participant.metadata.pushVariables  →  room.metadata.pushVariables  →  message.metadata.pushVariables  →  Built-in variables (Highest)
```

Use this to layer defaults: set per-room defaults, override per-message when needed, and let built-in variables always win for system fields like `senderName`.

- Notification settings: https://abrova.ir/en/docs/chat/notification-settings

AbrovaChat sends a push to participants who are offline when something happens in their rooms (see [Push Setup](/docs/chat/push-setup)). Some users want every one of them, others want none. Notification settings let **each user** decide, and you expose the choice in your own app's settings screen.

<Callout kind="note" title="Nothing changes until you set something">
A user without settings gets every push, exactly as before. Your project-wide push configuration still applies on top: a push the project doesn't send is never sent, whatever the user chooses.
</Callout>

<H2 id="what-a-user-can-choose" step={1}>What a user can choose</H2>

Settings exist at two levels. A push is sent only if **both** allow it.

| Level | Use it for |
|---|---|
| **App-wide** | "Chat notifications" switch in your app settings |
| **Per room** | "Mute this conversation", "Only notify me when mentioned" |

Each level has the same three fields:

<ConfigTable rows={[
  ['pushLevel', "'all' | 'mentions' | 'none'", "'all'", '`all` — every chat push. `mentions` — only when the user is @mentioned. `none` — no chat pushes.'],
  ['mutedUntil', 'ISO date | null', 'null', 'No chat pushes until this time, then back to normal. Send `null` to unmute early.'],
  ['disabledEvents', 'string[]', '[]', 'Event types to turn off, e.g. `["reaction", "message_pinned"]`.'],
]} />

Event types you can turn off:

<ConfigTable rows={[
  ['new_message', '-', '-', 'New text message'],
  ['file_shared', '-', '-', 'Image or file message'],
  ['mention', '-', '-', 'The user was @mentioned'],
  ['reaction', '-', '-', 'Someone reacted to the user\'s message'],
  ['message_pinned', '-', '-', 'A message was pinned'],
  ['room_created', '-', '-', 'The user was put in a new room'],
  ['participant_joined', '-', '-', 'Someone joined the room'],
  ['participant_removed', '-', '-', 'Someone left or was removed'],
]} />

Settings only affect push notifications. Messages, realtime events and unread counts are unchanged.

<H2 id="recommended-structure" step={2}>Recommended structure</H2>

Keep your server secret on your server, and let your app talk to **your** backend:

```
Your app  ──(your login)──▶  Your backend  ──(API key + server secret)──▶  AbrovaChat
```

Your backend already knows who the signed-in user is, so it passes that user's id to AbrovaChat. The app never chooses whose settings it changes, and never holds the secret.

<H2 id="your-backend-node-js" step={3}>Your backend (Node.js)</H2>

Install the server SDK from Abrova Center (the `.npmrc` line points the `@abrova` scope there):

```bash
# .npmrc
@abrova:registry=https://center.abrova.ir/api/packages/abrova/npm/
```

```bash
npm install @abrova/chat@^0.2.0
```

```typescript
import express from 'express';
import { AbrovaChat, AbrovaChatError } from '@abrova/chat';

const chat = new AbrovaChat({
  apiKey: process.env.ABROVA_API_KEY!,
  serverSecret: process.env.ABROVA_SERVER_SECRET!, // server-side only
});

const router = express.Router();
// requireLogin is YOUR auth middleware; req.user.id is YOUR user id,
// the same id you use as externalUserId in chat rooms.

// App-wide settings
router.get('/chat/notification-settings', requireLogin, async (req, res) => {
  res.json(await chat.users.getNotificationSettings(req.user.id));
});

router.put('/chat/notification-settings', requireLogin, async (req, res) => {
  const { pushLevel, mutedUntil, disabledEvents } = req.body;
  res.json(
    await chat.users.updateNotificationSettings(req.user.id, { pushLevel, mutedUntil, disabledEvents }),
  );
});

// One room
router.put('/chat/rooms/:roomId/notification-settings', requireLogin, async (req, res) => {
  const { pushLevel, mutedUntil, disabledEvents } = req.body;
  try {
    res.json(
      await chat.rooms.updateNotificationSettings(req.params.roomId, req.user.id, {
        pushLevel,
        mutedUntil,
        disabledEvents,
      }),
    );
  } catch (e) {
    if (e instanceof AbrovaChatError) return res.status(e.statusCode).json({ message: e.message });
    throw e;
  }
});
```

Only pass on the three fields shown. Never take the user id from the request body — use the id from your own session.

Common calls:

```typescript
// Chat notifications off
await chat.users.updateNotificationSettings(userId, { pushLevel: 'none' });

// Back on
await chat.users.updateNotificationSettings(userId, { pushLevel: 'all' });

// Only when mentioned, and never for reactions
await chat.users.updateNotificationSettings(userId, {
  pushLevel: 'mentions',
  disabledEvents: ['reaction'],
});

// Mute one room for 8 hours, or unmute it
await chat.rooms.updateNotificationSettings(roomId, userId, {
  mutedUntil: new Date(Date.now() + 8 * 60 * 60 * 1000),
});
await chat.rooms.updateNotificationSettings(roomId, userId, { mutedUntil: null });
```

Updates are partial: fields you leave out keep their current value.

<H2 id="your-app" step={4}>Your app</H2>

The app calls your backend like any other request of yours. For example, a settings switch:

```typescript
async function setChatNotifications(enabled: boolean) {
  await fetch('https://api.example.com/chat/notification-settings', {
    method: 'PUT',
    headers: { Authorization: `Bearer ${sessionToken}`, 'Content-Type': 'application/json' },
    body: JSON.stringify({ pushLevel: enabled ? 'all' : 'none' }),
  });
}
```

```dart
// Flutter
Future<void> muteRoom(String roomId, Duration duration) => dio.put(
  '/chat/rooms/$roomId/notification-settings',
  data: {'mutedUntil': DateTime.now().add(duration).toUtc().toIso8601String()},
);
```

<H2 id="rest-reference" step={5}>REST reference</H2>

All endpoints take `x-api-key`, plus **either** `x-server-secret` (your server, acting for any user) **or** `x-user-token` (a [user token](/docs/chat/authentication), acting only for that user).

| Method | Path | Purpose |
|---|---|---|
| `GET` | `/api/v1/users/notification-settings?userId=…` | App-wide settings |
| `PUT` | `/api/v1/users/notification-settings` | Update app-wide settings |
| `GET` | `/api/v1/rooms/{roomId}/notification-settings?userId=…` | Settings for one room |
| `PUT` | `/api/v1/rooms/{roomId}/notification-settings` | Update settings for one room |

```bash
curl -X PUT https://chat.abrova.ir/api/v1/rooms/$ROOM_ID/notification-settings \
  -H "x-api-key: $ABROVA_API_KEY" \
  -H "x-server-secret: $ABROVA_SERVER_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"userId": "user-123", "pushLevel": "mentions"}'
```

With a user token, leave `userId` out; the token decides the user.

Response:

```json
{
  "userId": "user-123",
  "scope": "room",
  "roomId": "5b1f…",
  "pushLevel": "mentions",
  "mutedUntil": null,
  "disabledEvents": [],
  "updatedAt": "2026-09-16T10:00:00.000Z"
}
```

App-wide settings return `"scope": "app"` and no `roomId`.

| Status | When |
|---|---|
| `400` | Missing `userId` (server secret), or an invalid value |
| `403 user_mismatch` | A user token tried to change another user |
| `404` | The room doesn't exist in your project, or the user isn't in it |

### Best Practices

<BestPracticeList items={[
  ['Go through your backend', 'Your server knows who is signed in; the app should never pick the user id or hold the server secret'],
  ['Mute for a while, not forever', 'Offer "1 hour", "8 hours", "Until I turn it back on" — timed mutes end on their own'],
  ['Mentions only for busy groups', "pushLevel 'mentions' keeps large rooms quiet without missing what matters"],
  ['Show the current state', 'Read the settings when the screen opens instead of keeping a local copy'],
]} />

- Examples: https://abrova.ir/en/docs/chat/examples

Real-world integration patterns for common industries. Each example shows room creation with push notification variables and deep links.

### Customer Support — Ticket Chat

Agent-customer chat per ticket. Push notification shows agent name and ticket number.

**AbrovaPush Template**
- Title: `{{senderName}} — {{teamName}}`
- Body: `Re: Ticket #{{ticketNumber}} — {{messagePreview}}`

#### Flutter

```dart
// Create support ticket chat room
final room = await client.findOrCreateRoom(
  externalId: 'ticket-${ticket.id}',
  type: RoomType.direct,
  name: 'Ticket #${ticket.number}',
  participants: [
    {'externalUserId': agent.id, 'displayName': agent.name, 'locale': 'en'},
    {'externalUserId': customer.id,  'displayName': customer.name,  'locale': customer.locale},
  ],
  metadata: {
    'pushVariables': {
      'teamName': team.name,
      'ticketNumber': ticket.number,
    },
    'pushData': {
      'deepLink': 'myapp://tickets/${ticket.id}',
      'ticketId': ticket.id,
    },
  },
);
```

#### Node.js

```typescript
// Create support ticket chat room
const { room } = await abrovaChat.rooms.findOrCreate({
  externalId: `ticket-${ticket.id}`,
  type: 'direct',
  name: `Ticket #${ticket.number}`,
  participants: [
    { externalUserId: agent.id, displayName: agent.name, locale: 'en' },
    { externalUserId: customer.id,  displayName: customer.name,  locale: customer.locale },
  ],
  metadata: {
    pushVariables: { teamName: team.name, ticketNumber: ticket.number },
    pushData: { deepLink: `myapp://tickets/${ticket.id}`, ticketId: ticket.id },
  },
});
```

#### REST API

```bash
# Create support ticket chat room
curl -X POST "https://chat.abrova.ir/api/v1/rooms/find-or-create" \
  -H "X-API-Key: ab_live_your_api_key" -H "X-Server-Secret: $ABROVA_SERVER_SECRET" -H "Content-Type: application/json" \
  -d '{
    "externalId": "ticket-456",
    "type": "direct",
    "name": "Ticket #456",
    "participants": [
      {"externalUserId": "agent-1", "displayName": "Support Team", "locale": "en"},
      {"externalUserId": "user-2",  "displayName": "Alice",       "locale": "hy"}
    ],
    "metadata": {
      "pushVariables": {"teamName": "Support Team", "ticketNumber": "456"},
      "pushData": {"deepLink": "myapp://tickets/456", "ticketId": "456"}
    }
  }'
```

### Team Collaboration — Project Chat

Team chat per project. Push shows project name and sender name.

**AbrovaPush Template**
- Title: `{{senderName}} — {{projectName}}`
- Body: `New message in your project`

#### Flutter

```dart
final room = await client.findOrCreateRoom(
  externalId: 'project-${project.id}',
  type: RoomType.group,
  name: project.name,
  participants: [
    {'externalUserId': lead.id, 'displayName': lead.name, 'role': 'admin', 'locale': 'en'},
    {'externalUserId': member.id, 'displayName': member.name, 'locale': member.locale},
  ],
  metadata: {
    'pushVariables': {'projectName': project.name, 'teamName': team.name},
    'pushData': {'deepLink': 'myapp://projects/${project.id}'},
  },
);
```

#### Node.js

```typescript
const { room } = await abrovaChat.rooms.findOrCreate({
  externalId: `project-${project.id}`,
  type: 'group',
  name: project.name,
  participants: [
    { externalUserId: lead.id, displayName: lead.name, role: 'admin', locale: 'en' },
    { externalUserId: member.id, displayName: member.name, locale: member.locale },
  ],
  metadata: {
    pushVariables: { projectName: project.name, teamName: team.name },
    pushData: { deepLink: `myapp://projects/${project.id}` },
  },
});
```

#### REST API

```bash
curl -X POST "https://chat.abrova.ir/api/v1/rooms/find-or-create" \
  -H "X-API-Key: ab_live_your_api_key" -H "X-Server-Secret: $ABROVA_SERVER_SECRET" -H "Content-Type: application/json" \
  -d '{
    "externalId": "project-789",
    "type": "group",
    "name": "Website Redesign",
    "participants": [
      {"externalUserId": "lead-1", "displayName": "Alex", "role": "admin", "locale": "en"},
      {"externalUserId": "dev-2", "displayName": "Alice", "locale": "hy"}
    ],
    "metadata": {
      "pushVariables": {"projectName": "Website Redesign", "teamName": "Engineering"},
      "pushData": {"deepLink": "myapp://projects/789"}
    }
  }'
```

### Education — Class Group Chat

Group chat per class. Push shows class name.

#### Flutter

```dart
final room = await client.findOrCreateRoom(
  externalId: 'class-${classId}',
  type: RoomType.group,
  name: 'Math 101 — Prof. Johnson',
  participants: [
    {'externalUserId': 'prof-1', 'displayName': 'Prof. Johnson', 'role': 'admin', 'locale': 'en'},
    {'externalUserId': 'student-1', 'displayName': 'Alice', 'locale': 'en'},
    {'externalUserId': 'student-2', 'displayName': 'Bob', 'locale': 'hy'},
  ],
  metadata: {
    'pushVariables': {'className': 'Math 101', 'semester': 'Spring 2026'},
    'pushData': {'deepLink': 'myapp://classes/${classId}'},
  },
);

// Pin an announcement — triggers message_pinned push
await client.pinMessage(announcementMsg.id);

// Share homework — triggers file_shared push
await client.sendMessage(
  room.id,
  content: 'Homework due Friday',
  type: MessageType.file,
  attachments: [homework],
);
```

#### Node.js

```typescript
const { room } = await abrovaChat.rooms.findOrCreate({
  externalId: `class-${classId}`,
  type: 'group',
  name: 'Math 101 — Prof. Johnson',
  participants: [
    { externalUserId: 'prof-1', displayName: 'Prof. Johnson', role: 'admin', locale: 'en' },
    { externalUserId: 'student-1', displayName: 'Alice', locale: 'en' },
    { externalUserId: 'student-2', displayName: 'Bob', locale: 'hy' },
  ],
  metadata: {
    pushVariables: { className: 'Math 101', semester: 'Spring 2026' },
    pushData: { deepLink: `myapp://classes/${classId}` },
  },
});

// Pin an announcement — triggers message_pinned push
await abrovaChat.pins.pin(announcementMsg.id, 'prof-1');

// Share homework — triggers file_shared push
await abrovaChat.messages.send(room.id, {
  senderUserId: 'prof-1',
  content: 'Homework due Friday',
  type: 'file',
  attachments: [homework],
});
```

#### REST API

```bash
# Create class group chat
curl -X POST "https://chat.abrova.ir/api/v1/rooms/find-or-create" \
  -H "X-API-Key: ab_live_your_api_key" -H "X-Server-Secret: $ABROVA_SERVER_SECRET" -H "Content-Type: application/json" \
  -d '{
    "externalId": "class-math101",
    "type": "group",
    "name": "Math 101 — Prof. Johnson",
    "participants": [
      {"externalUserId": "prof-1", "displayName": "Prof. Johnson", "role": "admin", "locale": "en"},
      {"externalUserId": "student-1", "displayName": "Alice", "locale": "en"},
      {"externalUserId": "student-2", "displayName": "Bob", "locale": "hy"}
    ],
    "metadata": {
      "pushVariables": {"className": "Math 101", "semester": "Spring 2026"},
      "pushData": {"deepLink": "myapp://classes/math101"}
    }
  }'
```


## Abrova Sync (coming soon)

- Installation: https://abrova.ir/en/docs/sync/installation

AbrovaSync ships native SDKs for every major platform. Pick yours below — installation takes two steps from Abrova Center and no Firebase / Google dependencies are pulled in. If you'd rather skip an SDK, the REST API is available from any HTTP client.

Using an AI assistant? See [AI assistants](/docs/sync/ai-assistants) for how to give it these docs.

<div>
  <div>
    <div>Flutter</div>
    <code>abrova_sync ^0.3.0</code>
  </div>
  <div>
    <div>React Native</div>
    <code>@abrova/sync-react-native</code>
  </div>
  <div>
    <div>Web</div>
    <code>@abrova/sync-web</code>
  </div>
  <div>
    <div>Android</div>
    <code>abrova-sync-android:0.3.0</code>
  </div>
  <div>
    <div>iOS</div>
    <code>AbrovaSync 0.3.0 (SPM)</code>
  </div>
  <div>
    <div>Node.js</div>
    <code>@abrova/sync-node</code>
  </div>
  <div>
    <div>REST API</div>
    <code>No install required</code>
  </div>
</div>

<Callout kind="note" title="Get your API key">
You'll need a Project API Key from the [Abrova Console](https://console.abrova.ir) before initializing the SDK. Server-side use (Node.js or REST) also needs the Server Secret — never embed that in a mobile / web client.
</Callout>

<Callout kind="wallet" title="What it will cost">
Free every month: 50,000 reads, 20,000 writes and 100 connections. Usage above that will cost from your prepaid wallet; the price is set at launch. See [Pricing](/pricing).
</Callout>

Every Abrova SDK installs from **Abrova Center**, the Abrova package registry, in two steps: add the registry once, then install the package.

<H2 id="flutter" step={1}>Flutter</H2>

```yaml
# 1. pubspec.yaml: install from Abrova Center
dependencies:
  abrova_sync:
    hosted: https://center.abrova.ir/api/packages/abrova/pub
    version: ^0.3.0
```

```bash
# 2. Install
flutter pub get
```

<H2 id="react-native" step={2}>React Native</H2>

```bash
# 1. .npmrc in your project root: @abrova packages come from Abrova Center
@abrova:registry=https://center.abrova.ir/api/packages/abrova/npm/
```

```bash
# 2. Install (npm or yarn)
npm install @abrova/sync-react-native
yarn add @abrova/sync-react-native
```

<H2 id="web" step={3}>Web</H2>

```bash
# 1. .npmrc in your project root
@abrova:registry=https://center.abrova.ir/api/packages/abrova/npm/
```

```bash
# 2. Install (npm or yarn)
npm install @abrova/sync-web
yarn add @abrova/sync-web
```

<H2 id="android" step={4}>Android</H2>

```groovy
// 1. settings.gradle (or the project build.gradle): add Abrova Center
repositories {
    google()
    mavenCentral()
    maven { url "https://center.abrova.ir/api/packages/abrova/maven" }
}
```

```kotlin
// 2. app/build.gradle(.kts)
dependencies {
    implementation("ir.abrova:abrova-sync-android:0.3.0")
}
```

<H2 id="ios" step={5}>iOS</H2>

Add the package with Swift Package Manager. In Xcode: **File → Add Package Dependencies…**, paste the URL, choose the version. Or in `Package.swift`:

```swift
dependencies: [
    .package(url: "https://github.com/Abrova-co/abrova-sync-ios-sdk.git", from: "0.3.0")
]
```

<H2 id="node-js" step={6}>Node.js</H2>

```bash
# 1. .npmrc in your project root
@abrova:registry=https://center.abrova.ir/api/packages/abrova/npm/
```

```bash
# 2. Install (npm, yarn or pnpm)
npm install @abrova/sync-node
yarn add @abrova/sync-node
pnpm add @abrova/sync-node
```

<H2 id="rest-api" step={7}>REST API</H2>

No package install — just point any HTTP client at `https://sync.abrova.ir`. Every request carries your Project API Key, plus one of these:

```bash
# Option 1: API Key + Server Secret (your backend only)
x-api-key: ab_live_YOUR_PROJECT_API_KEY
x-server-secret: ab_srv_YOUR_SERVER_SECRET
Content-Type: application/json

# Option 2: API Key + user token (acting as a signed-in user; the token is
# minted by your backend - see Security Rules)
x-api-key: ab_live_YOUR_PROJECT_API_KEY
x-user-token: USER_TOKEN_FROM_YOUR_BACKEND
Content-Type: application/json
```

<H2 id="upgrading-to-0-3-0" step={8}>Upgrading to 0.3.0</H2>

Version 0.3.0 is released for all six SDKs together and changes some behavior. Check these points when you upgrade from 0.2.x:

**`set()` replaces the document.** Fields you leave out are removed. Before 0.3.0, `set()` merged into the existing document. To keep merging, pass the merge option. `WriteBatch.set()` takes the same option. Writes that were queued offline before the upgrade keep the meaning they had when they were made.

```dart
// Flutter
await todos.set('todo-1', {'completed': true}, merge: true);
batch.set(todos, 'todo-1', {'completed': true}, merge: true);
```

```typescript
// React Native
await todos.set('todo-1', { completed: true }, { merge: true });
batch.set(todos, 'todo-1', { completed: true }, { merge: true });

// Web
await todos.document('todo-1').set({ completed: true }, { merge: true });
batch.set(todos.document('todo-1'), { completed: true }, { merge: true });

// Node.js
await todos.doc('todo-1').set({ completed: true }, { merge: true });
batch.set(todos.doc('todo-1'), { completed: true }, { merge: true });
```

```kotlin
// Android
todos.set("todo-1", mapOf("completed" to true), merge = true)
batch.set(todos, "todo-1", mapOf("completed" to true), merge = true)
```

```swift
// iOS
try await todos.set(documentId: "todo-1", data: ["completed": true], merge: true)
batch.set(todos, documentId: "todo-1", data: ["completed": true], merge: true)
```

**Flutter: catch `AbrovaSyncError`.** Failed calls (`add`, `get`, `getAll`, `update`, `set`, `delete`, `query.get()`, `batch.commit()`, `connect()`, and database and collection calls) throw an `AbrovaSyncError` instead of a `PlatformException`. Where you caught `PlatformException`, catch `AbrovaSyncError`:

```dart
try {
  await todos.update('todo-1', {'completed': true});
} on AbrovaSyncError catch (e) {
  print('${e.code} (${e.statusCode}): ${e.message}');
}
```

**Web and Node.js: `get()` returns the document.** On the Web SDK, `doc.get()` returns the document (`{ id, data, version, ... }`). On the Node.js SDK, `get()` and `add()` return it too. Before 0.3.0 the document came wrapped in an extra object, so its fields were at `doc.data.data`. If your code reads `doc.data.data`, read `doc.data` now.

**Listeners are checked by your security rules.** A listener is allowed only when the rules allow every document it could receive, exactly like a query. A listener that the rules do not allow now ends with an error. Filter it on the fields your rules read. See [Realtime Listeners](/docs/sync/listeners) and [Security Rules](/docs/sync/rules).

**With offline persistence, refusals are no longer hidden.** The cache stands in only when the server cannot be reached. When the server refuses a request (your security rules, invalid data), the call throws: reads are not answered from the cache, and writes are not queued. See [Offline Persistence](/docs/sync/offline).

**iOS: two new error cases.** `AbrovaSyncError` has the new cases `queryNotAllowed` and `listenerRevoked`. If you `switch` over `AbrovaSyncError` without a `default`, add them.

**Web: `disconnect()` takes the SDK offline.** After `disconnect()` or `goOffline()`, writes are queued and reads come from the cache until you call `reconnect()`. The SDK no longer reconnects by itself when the browser comes back online after `disconnect()`.

**`maxSyncRetries` has no effect.** It is deprecated on every SDK. A queued write is retried until it goes through, and a write the server refuses is rolled back. Remove the setting when convenient. Your code still compiles while it is there.

Error types and status codes per platform are listed in [Platform Notes](/docs/sync/platform-notes).

Next: [initialize and connect](/docs/sync/initialization).

- Initialization: https://abrova.ir/en/docs/sync/initialization

Once installed, the SDK needs two things to come alive: your **Project API Key** (read from the [Abrova Console](https://console.abrova.ir)) and, on Flutter, React Native, Android and iOS, a `connect()` call that opens the realtime channel (the Web SDK connects on its own). Only the language and entry-point shape differ.

<div>
  <h3>Two things you need</h3>
  <div>
    <div>
      <div></div>
      <div>
        <p>API Key</p>
        <p>From <strong>Console → Your Org → Project</strong>. Safe to embed in mobile / web apps.</p>
      </div>
    </div>
    <div>
      <div></div>
      <div>
        <p>Server Secret</p>
        <p>Only for server-side (Node.js / REST). Never embed in a client.</p>
      </div>
    </div>
  </div>
</div>

<H2 id="flutter" step={1}>Flutter</H2>

```dart
import 'package:abrova_sync/abrova_sync.dart';

void main() async {
  WidgetsFlutterBinding.ensureInitialized();

  // Initialize AbrovaSync with your API key
  await AbrovaSync.init(AbrovaSyncConfig(
    apiKey: 'YOUR_API_KEY', // Get from Abrova Console
  ));

  // Connect to start realtime sync
  await AbrovaSync.connect();

  runApp(MyApp());
}
```

<H2 id="react-native" step={2}>React Native</H2>

```typescript
import AbrovaSync from '@abrova/sync-react-native';

// Initialize in your app entry point
async function initializeApp() {
  await AbrovaSync.init({
    apiKey: 'YOUR_API_KEY', // Get from Abrova Console
  });

  // Connect to start realtime sync
  await AbrovaSync.connect();
}

initializeApp();
```

<H2 id="web" step={3}>Web</H2>

```typescript
import AbrovaSync from '@abrova/sync-web';

// Initialize AbrovaSync with your API key
const abrovaSync = new AbrovaSync({
  apiKey: 'YOUR_API_KEY', // Get from Abrova Console (Project API Key)
});

// The web SDK connects to realtime on its own - there is no connect() call.
```

<H2 id="android" step={4}>Android</H2>

```kotlin
import ir.abrova.sync.sdk.AbrovaSync
import ir.abrova.sync.sdk.AbrovaSyncConfig

class MyApplication : Application() {
    override fun onCreate() {
        super.onCreate()

        // Initialize AbrovaSync with your API key
        val config = AbrovaSyncConfig.Builder("YOUR_API_KEY") // Get from Abrova Console
            .debugMode(true)  // Optional: enable debug logging
            .build()

        // Create AbrovaSync instance
        val abrovaSync = AbrovaSync.initialize(this, config)
    }
}

// Connect when ready (in Activity/Fragment)
lifecycleScope.launch {
    AbrovaSync.getInstance().connect()
}
```

<H2 id="ios" step={5}>iOS</H2>

```swift
import AbrovaSync

// Initialize in AppDelegate or App struct
@main
struct MyApp: App {
    init() {
        let config = AbrovaSyncConfigBuilder(
            apiKey: "YOUR_API_KEY" // Get from Abrova Console
        )
        .debugMode(true)           // Optional: enable debug logging
        .build()

        AbrovaSync.initialize(config: config)
    }

    var body: some Scene {
        WindowGroup {
            ContentView()
                .task {
                    try? await AbrovaSync.shared.connect()
                }
        }
    }
}
```

<H2 id="node-js" step={6}>Node.js</H2>

The Node.js SDK uses **service account auth** — both `apiKey` and `serverSecret` are required. Use it from a backend, never from a client: the server secret can mint a token for any user in your project.

```typescript
import { AbrovaSyncAdmin } from '@abrova/sync-node';

const abrovaSync = new AbrovaSyncAdmin({
  apiKey: process.env.ABROVA_API_KEY!,           // Your Project API Key
  serverSecret: process.env.ABROVA_SERVER_SECRET!, // Required for server-side operations
});

// Mint a user token for your app. This is the only way auth.uid in Security
// Rules becomes something the server can trust.
const { token, expiresIn } = await abrovaSync.createUserToken(session.userId);
```

<Callout kind="warn" title="Security Rules apply to this SDK too">
Once a database has rules, they are evaluated for the Node.js SDK exactly as they are for a client, with `auth.uid` set to the `userId` you pass in its config — see [Security Rules](/docs/sync/rules). The one difference: a database with no rules saved is locked to client SDKs, but not to a request carrying your server secret.
</Callout>

<H2 id="rest-api" step={7}>REST API</H2>

The REST API has no init step — every request just carries the auth headers. Get your credentials from **Console → Your Org → Projects → API Key + Server Secret**, then attach them to any HTTP client:

```bash
# Example: list the documents in a collection (database and collection by name)
curl -X GET "https://sync.abrova.ir/databases/my-app/collections/todos/documents/sdk" \
  -H "x-api-key: YOUR_PROJECT_API_KEY" \
  -H "x-server-secret: YOUR_SERVER_SECRET" \
  -H "Content-Type: application/json"
```

<H2 id="telling-abrova-who-the-user-is" step={8}>Telling Abrova who the user is</H2>

Security Rules read `auth.uid`. Your app cannot set it: the API key it ships with is public, so the server has no reason to believe a user id that comes from a client. Instead, your backend mints a short-lived **user token** with your server secret, and the SDK sends it on every request.

Give the SDK a token provider and it handles the rest — fetching a token when it needs one and refreshing it shortly before expiry. The provider returns `null` when no one is signed in. It is the same Abrova user token Abrova Chat and Abrova Push use, so one function can serve every SDK. (Flutter and React Native have the provider from 0.2.1; on any client SDK you can instead fetch the token yourself and pass it with `setUserToken()` / `userTokens.set()`.)

```typescript
// Web
const abrovaSync = new AbrovaSync({
  apiKey: 'YOUR_API_KEY',
  tokenProvider: async () => {
    // Your own endpoint, behind your own session check.
    const res = await fetch('/api/abrova-sync-token', { method: 'POST' });
    return (await res.json()).token;
  },
});
```

```dart
// Flutter
await AbrovaSync.init(AbrovaSyncConfig(
  apiKey: 'YOUR_API_KEY',
  tokenProvider: () => myBackend.fetchAbrovaToken(), // null when signed out
));
```

```typescript
// React Native
await AbrovaSync.init({
  apiKey: 'YOUR_API_KEY',
  tokenProvider: () => myBackend.fetchAbrovaToken(), // null when signed out
});
```

```kotlin
// Android
val config = AbrovaSyncConfig.builder("YOUR_API_KEY")
    .userTokenProvider { myBackend.fetchAbrovaSyncToken() } // called off the main thread
    .build()
```

```swift
// iOS
let sync = AbrovaSync.initialize(config: config)
sync.userTokens.provider = { try await myBackend.fetchAbrovaSyncToken() }
```

#### When the user signs in or out

Tell the SDK, and it asks the provider again and reconnects as that user:

<ConfigTable headers={['SDK', 'Call']} rows={[
  ['Flutter, React Native', 'AbrovaSync.refreshUserToken()'],
  ['Web', 'abrovaSync.refreshUserToken()'],
  ['Android', 'sync.userTokens.refresh()'],
  ['iOS', 'sync.refreshUserToken()'],
]} />

If you pass tokens yourself instead of using a provider, call `setUserToken(token)` (Flutter, React Native, Web) or `userTokens.set(token)` (Android, iOS) with the new user's token, or with `null` / `nil` on sign-out.

#### Connecting before anyone is signed in

Without a token the SDK falls back to an unverified user id, which a project with **Require signed user tokens** turned on will refuse. From 0.2.1 that is not an error on any client SDK: call `connect()` at app start as usual (the Web SDK connects on its own). The SDK waits, and connects by itself as soon as it has a token. To know it is waiting, use `onAwaitingUserToken` or `isAwaitingUserToken`.

```dart
// Flutter
AbrovaSync.onAwaitingUserToken(() => print('Sync connects after sign-in'));
await AbrovaSync.connect();            // completes normally
// ... later, after your own sign-in:
await AbrovaSync.refreshUserToken();   // the SDK connects now
```

See [Security Rules](/docs/sync/rules).

Next: [CRUD operations](/docs/sync/crud).

- AI assistants: https://abrova.ir/en/docs/sync/ai-assistants

<Callout kind="soon" title="Coming soon">
Abrova does not have a docs server for AI assistants yet. This page describes how it will work and what you can use today.
</Callout>

When it is ready, you connect your AI assistant (any tool that supports MCP, the open standard AI tools use to connect to outside sources) once. Then, when you ask it to add Abrova Sync to your project, it looks up the current SDK version, install lines and setup steps from these docs instead of answering from memory.

### What works today

- **Copy page for AI.** Every docs page has a **Copy page for AI** link. Paste the page into your assistant's chat before you ask it to write code.
- **Plain-text docs.** Give your assistant the address `https://abrova.ir/docs/llms.txt`. It lists every docs page as plain text that assistants read well.

Tell your assistant to follow the page you gave it, and to use the placeholder keys from the docs.

### What it will do

The docs server will have read-only tools. Your assistant chooses them by itself; you do not call them by hand.

<ConfigTable headers={['Tool', 'What it will do']} rows={[
  ['list_products', 'Lists the Abrova products, with the platforms that have an SDK and the docs link.'],
  ['search_docs', 'Searches the docs for a few words or a short question and returns the best pages.'],
  ['read_doc', 'Returns one docs page as text, with its link and last-updated date.'],
  ['get_sdk_info', 'Returns the SDK package for a product and platform: name, current version and install lines.'],
  ['get_setup_guide', 'Returns the ordered setup steps for a product and platform: install, keys, initialization and how to test.'],
]} />

Examples of what you will be able to ask:

- **"Add Abrova Sync to this React Native app and keep the list working offline."** It would answer from [Installation](/docs/sync/installation) and [Offline persistence](/docs/sync/offline).
- **"Only let signed-in users edit their own profile document."** It would answer from [Security rules](/docs/sync/rules).
- **"Show a live list of open orders, newest first."** It would answer from [Queries](/docs/sync/queries) and [Realtime listeners](/docs/sync/listeners).

### Privacy

- **What it reads:** the public Abrova docs, the current SDK versions, and the words your assistant sends (the search words, the page it wants, the product and platform names).
- **What it never sees:** your code, your files, your Abrova project, your keys or your users. The tools have no input for them, and they cannot change any setting.

<Callout kind="warn" title="Keep your keys out of the chat">
Never paste a key into a chat with an AI assistant. Your assistant writes the placeholder from the docs (`ab_live_your_api_key`); you put the real value in your project's configuration yourself. The server secret (`ab_srv_...`) belongs only on your server, in an environment variable.
</Callout>

More about AI assistants and Abrova: [AI assistants](/ai-assistants). Questions? [Contact us](/contact).

- CRUD: https://abrova.ir/en/docs/sync/crud

Every piece of data in AbrovaSync lives inside a **document** — a JSON object with a unique ID — and documents live inside named **collections**, which sit inside a **database**. CRUD is therefore always one of four moves: add a new document, read an existing one, change part of it, or remove it.

<div>
  <div>
    <h3>Database</h3>
    <p>Top-level container. Created in the Abrova Console — you reference it from code by name (unique within a project).</p>
  </div>
  <div>
    <h3>Collection</h3>
    <p>A named group of documents. Created on first write — no migrations.</p>
  </div>
  <div>
    <h3>Document</h3>
    <p>A JSON object with a unique ID. Add nested objects, arrays, numbers, anything JSON-serializable.</p>
  </div>
</div>

<div>
  <h3>The five primitives</h3>
  <ul>
    <li><span>1</span><span><strong>add()</strong> — create a new document with an auto-generated ID.</span></li>
    <li><span>2</span><span><strong>get()</strong> — read a document by ID, or fetch every document in the collection.</span></li>
    <li><span>3</span><span><strong>update()</strong> — merge fields into an existing document (partial update).</span></li>
    <li><span>4</span><span><strong>set()</strong> — replace a document's data entirely.</span></li>
    <li><span>5</span><span><strong>delete()</strong> — remove a document.</span></li>
  </ul>
</div>

<Callout kind="warn" title="Databases come from the console">
Databases are created and managed via the [Abrova Console](https://console.abrova.ir), not from SDKs. Create your databases in the console, then use the SDK to interact with them using the **database name** shown in the console, e.g. `database('my-app').collection('users')`. The API key picks the project, and a database name is unique within a project. Don't pass database or collection IDs: live listeners need the names.
</Callout>

<H2 id="flutter" step={1}>Flutter</H2>

```dart
// Get database and collection references
final db = AbrovaSync.database('my-app');
final users = db.collection('users');

// CREATE - Add a new document
final newUser = await users.add({
  'name': 'John Doe',
  'email': 'john@example.com',
  'age': 28,
  'createdAt': DateTime.now().toIso8601String(),
});
print('Created user with ID: ${newUser.id}');

// READ - Get a single document
final user = await users.get('document-id');
print('User name: ${user?.data['name']}');

// READ - Get all documents
final allUsers = await users.getAll();
for (final user in allUsers) {
  print('${user.id}: ${user.data['name']}');
}

// UPDATE - Partial update
await users.update('document-id', {
  'age': 29,
  'updatedAt': DateTime.now().toIso8601String(),
});

// SET - Replace entire document
await users.set('document-id', {
  'name': 'John Updated',
  'email': 'john.new@example.com',
  'age': 29,
});

// DELETE - Remove a document
await users.delete('document-id');
```

<H2 id="react-native" step={2}>React Native</H2>

```typescript
// Get database and collection references
const db = AbrovaSync.database('my-app');
const users = db.collection('users');

// CREATE - Add a new document
const newUser = await users.add({
  name: 'John Doe',
  email: 'john@example.com',
  age: 28,
  createdAt: new Date().toISOString(),
});
console.log('Created user with ID:', newUser.id);

// READ - Get a single document
const user = await users.get('document-id');
console.log('User name:', user?.data.name);

// READ - Get all documents
const allUsers = await users.getAll();
allUsers.forEach(user => {
  console.log(`${user.id}: ${user.data.name}`);
});

// UPDATE - Partial update
await users.update('document-id', {
  age: 29,
  updatedAt: new Date().toISOString(),
});

// SET - Replace entire document
await users.set('document-id', {
  name: 'John Updated',
  email: 'john.new@example.com',
  age: 29,
});

// DELETE - Remove a document
await users.delete('document-id');
```

<H2 id="web" step={3}>Web</H2>

The Web SDK uses **document references** (`users.document('id')`) instead of passing the ID into every call. Pick whichever style your team prefers — the underlying API is identical.

```typescript
// Get database and collection references
const db = abrovaSync.database('my-app');
const users = db.collection('users');

// CREATE - Add a new document
const newUser = await users.add({
  name: 'John Doe',
  email: 'john@example.com',
  age: 28,
  createdAt: new Date().toISOString(),
});
console.log('Created user with ID:', newUser.id);

// READ - Get a single document
const userRef = users.document('document-id');
const user = await userRef.get();
console.log('User name:', user?.data.name);

// READ - Get all documents
const allUsers = await users.get();
allUsers.forEach(user => {
  console.log(`${user.id}: ${user.data.name}`);
});

// UPDATE - Partial update
await userRef.update({
  age: 29,
  updatedAt: new Date().toISOString(),
});

// SET - Replace entire document
await userRef.set({
  name: 'John Updated',
  email: 'john.new@example.com',
  age: 29,
});

// DELETE - Remove a document
await userRef.delete();
```

<H2 id="android" step={4}>Android</H2>

All CRUD operations are `suspend` functions — call them from a coroutine scope (`lifecycleScope`, `viewModelScope`, etc.).

```kotlin
// Get database and collection references
val db = AbrovaSync.getInstance().database("my-app")
val users = db.collection("users")

// CREATE - Add a new document (using coroutines)
lifecycleScope.launch {
    val newUser = users.add(mapOf(
        "name" to "John Doe",
        "email" to "john@example.com",
        "age" to 28,
        "createdAt" to System.currentTimeMillis()
    ))
    Log.d("AbrovaSync", "Created user with ID: ${newUser.id}")
}

// READ - Get a single document
lifecycleScope.launch {
    val user = users.get("document-id")
    Log.d("AbrovaSync", "User name: ${user?.data?.get("name")}")
}

// READ - Get all documents
lifecycleScope.launch {
    val allUsers = users.getAll()
    allUsers.forEach { user ->
        Log.d("AbrovaSync", "${user.id}: ${user.data["name"]}")
    }
}

// UPDATE - Partial update
lifecycleScope.launch {
    users.update("document-id", mapOf(
        "age" to 29,
        "updatedAt" to System.currentTimeMillis()
    ))
}

// SET - Replace entire document
lifecycleScope.launch {
    users.set("document-id", mapOf(
        "name" to "John Updated",
        "email" to "john.new@example.com",
        "age" to 29
    ))
}

// DELETE - Remove a document
lifecycleScope.launch {
    users.delete("document-id")
}
```

<H2 id="ios" step={5}>iOS</H2>

iOS uses Swift's `async`/`await` for every operation. Wrap calls in a `Task { }` block when invoked from a synchronous context like SwiftUI views.

```swift
// Get database and collection references
let db = AbrovaSync.shared.database("my-app")
let users = db.collection("users")

// CREATE - Add a new document
Task {
    let newUser = try await users.add(data: [
        "name": "John Doe",
        "email": "john@example.com",
        "age": 28,
        "createdAt": Date().ISO8601Format()
    ])
    print("Created user with ID: \(newUser.id)")
}

// READ - Get a single document
Task {
    if let user = try await users.get(documentId: "document-id") {
        print("User name: \(user.data["name"] ?? "")")
    }
}

// READ - Get all documents
Task {
    let allUsers = try await users.getAll()
    for user in allUsers {
        print("\(user.id): \(user.data["name"] ?? "")")
    }
}

// UPDATE - Partial update
Task {
    try await users.update(documentId: "document-id", data: [
        "age": 29,
        "updatedAt": Date().ISO8601Format()
    ])
}

// SET - Replace entire document
Task {
    try await users.set(documentId: "document-id", data: [
        "name": "John Updated",
        "email": "john.new@example.com",
        "age": 29
    ])
}

// DELETE - Remove a document
Task {
    try await users.delete(documentId: "document-id")
}
```

<H2 id="node-js" step={6}>Node.js</H2>

The Admin SDK exposes both the collection-level shortcut (`users.add(...)`) and the document-reference style (`users.doc('id').update(...)`). The latter is handy when you need to chain multiple writes on the same doc.

```typescript
// Get database and collection references
const db = abrovaSync.database('my-app');
const users = db.collection('users');

// CREATE - Add a new document
const newUser = await users.add({
  name: 'John Doe',
  email: 'john@example.com',
  age: 28,
  createdAt: new Date().toISOString(),
});
console.log('Created user with ID:', newUser.id);

// READ - Get a single document
const user = await users.get('document-id');
console.log('User name:', user?.data.name);

// READ - Get all documents
const allUsers = await users.getAll();
allUsers.forEach(user => {
  console.log(`${user.id}: ${user.data.name}`);
});

// UPDATE - Partial update (merge with existing)
await users.doc('document-id').update({
  age: 29,
  updatedAt: new Date().toISOString(),
});

// SET - Replace entire document
await users.doc('document-id').set({
  name: 'John Updated',
  email: 'john.new@example.com',
  age: 29,
});

// DELETE - Remove a document
await users.doc('document-id').delete();
```

<H2 id="rest-api" step={7}>REST API</H2>

Each primitive maps to a standard HTTP verb. `POST` for create, `GET` for read, `PATCH` for partial update, `PUT` for replace (it creates the document if the ID does not exist yet), `DELETE` for remove. API-key endpoints live under `/databases/{databaseName}/collections/{collectionName}/documents/sdk`, and every response is wrapped as `{ "data": ... }`. To act as a signed-in user instead of your backend, send `x-user-token` in place of `x-server-secret`.

```bash
# Base URL: https://sync.abrova.ir

# CREATE - Add a new document (SDK auth)
curl -X POST "https://sync.abrova.ir/databases/{databaseName}/collections/{collectionName}/documents/sdk" \
  -H "x-api-key: YOUR_PROJECT_API_KEY" \
  -H "x-server-secret: YOUR_SERVER_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "name": "John Doe",
      "email": "john@example.com",
      "age": 28
    }
  }'

# READ - Get a single document
curl -X GET "https://sync.abrova.ir/databases/{databaseName}/collections/{collectionName}/documents/sdk/{documentId}" \
  -H "x-api-key: YOUR_PROJECT_API_KEY" \
  -H "x-server-secret: YOUR_SERVER_SECRET"

# READ - Get all documents in a collection
curl -X GET "https://sync.abrova.ir/databases/{databaseName}/collections/{collectionName}/documents/sdk" \
  -H "x-api-key: YOUR_PROJECT_API_KEY" \
  -H "x-server-secret: YOUR_SERVER_SECRET"

# UPDATE - Partial update
curl -X PATCH "https://sync.abrova.ir/databases/{databaseName}/collections/{collectionName}/documents/sdk/{documentId}" \
  -H "x-api-key: YOUR_PROJECT_API_KEY" \
  -H "x-server-secret: YOUR_SERVER_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "age": 29,
      "updatedAt": "2024-01-15T10:30:00Z"
    }
  }'

# SET - Replace entire document
curl -X PUT "https://sync.abrova.ir/databases/{databaseName}/collections/{collectionName}/documents/sdk/{documentId}" \
  -H "x-api-key: YOUR_PROJECT_API_KEY" \
  -H "x-server-secret: YOUR_SERVER_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "name": "John Updated",
      "email": "john.new@example.com",
      "age": 29
    },
    "merge": false
  }'

# DELETE - Remove a document
curl -X DELETE "https://sync.abrova.ir/databases/{databaseName}/collections/{collectionName}/documents/sdk/{documentId}" \
  -H "x-api-key: YOUR_PROJECT_API_KEY" \
  -H "x-server-secret: YOUR_SERVER_SECRET"
```

`"merge": false` replaces the document, `"merge": true` merges the fields into it. A `PUT` without `merge` merges, as it always did — send the flag so the call says what it means.

<H2 id="merge-instead-of-replace" step={8}>Merge instead of replace</H2>

`set()` replaces the whole document (SDK 0.3.0 and later). To write only some fields and keep the rest — creating the document if it doesn't exist — pass the merge option:

```dart
// Flutter
await users.set('document-id', {'age': 29}, merge: true);
```

```typescript
// React Native
await users.set('document-id', { age: 29 }, { merge: true });

// Web
await users.document('document-id').set({ age: 29 }, { merge: true });

// Node.js
await users.doc('document-id').set({ age: 29 }, { merge: true });
```

```kotlin
// Android
users.set("document-id", mapOf("age" to 29), merge = true)
```

```swift
// iOS
try await users.set(documentId: "document-id", data: ["age": 29], merge: true)
```

`update()` also changes only the fields you pass, but the document must already exist.

<Callout kind="warn" title="Upgrading from 0.2.x">
In SDKs before 0.3.0, `set()` merged. If your app relied on that, add the merge option where it calls `set()`. See [Upgrading to 0.3.0](/docs/sync/installation) for the other changes.
</Callout>

<H2 id="deleting-and-errors" step={9}>Deleting and errors</H2>

Deleting a document that does not exist succeeds, so you can call `delete()` again safely, for example when a retry follows a delete that already went through.

When the server refuses a read or a write, the call throws (or rejects) with an error whose `statusCode` says why: 403 when your [security rules](/docs/sync/rules) refused it, 404 when the document does not exist (for example `update()` of a missing document), and no status when the server could not be reached. `get()` of a single document that does not exist returns `null` instead of throwing. On Flutter, catch `AbrovaSyncError`:

```dart
try {
  await users.update('document-id', {'age': 29});
} on AbrovaSyncError catch (e) {
  if (e.isPermissionDenied) {
    print('Not allowed by the security rules');
  }
}
```

The error types for every platform are in [Platform Notes](/docs/sync/platform-notes).

Next: filter and sort with [Querying Data](/docs/sync/queries).

- Queries: https://abrova.ir/en/docs/sync/queries

A query is a recipe for narrowing down a collection: "give me users **where** age is at least 18, **ordered by** signup date, **limit** 20". The SDK builds the query on the client, the backend evaluates it, and you get back a result list. Queries also work as inputs to [realtime listeners](/docs/sync/listeners) — same fluent shape.

<div>
  <div>
    <h3>where()</h3>
    <p>Filter rows by field. Chain multiple <code>where()</code> calls to AND them.</p>
  </div>
  <div>
    <h3>orderBy()</h3>
    <p>Sort by one field, ascending or descending. A second <code>orderBy</code> replaces the first.</p>
  </div>
  <div>
    <h3>limit() + offset()</h3>
    <p>Page through large result sets without loading everything.</p>
  </div>
</div>

<H2 id="available-operators" step={1}>Available operators</H2>

<ConfigTable headers={['Operator', 'Symbol / Enum', 'Description']} rows={[
  ['Equal', '==', 'Field equals value'],
  ['Not Equal', '!=', 'Field does not equal value'],
  ['Greater Than', '>', 'Field strictly greater than value (numeric fields only)'],
  ['Greater Than or Equal', '>=', 'Field greater than or equal to value (numeric fields only)'],
  ['Less Than', '<', 'Field strictly less than value (numeric fields only)'],
  ['Less Than or Equal', '<=', 'Field less than or equal to value (numeric fields only)'],
  ['Array Contains', 'array-contains', 'Array field contains the value (matched as text, so a partial match also counts)'],
  ['In', 'in', 'Field value is in the given array'],
  ['Not In', 'not-in', 'Not supported: the filter is ignored'],
]} />

Good to know: two `where()` calls on the same field with different operators make a range (`age >= 18` and `age < 65`); the same operator twice on one field is refused. Sorting puts numbers in number order, then text, and documents without the field last (`createdAt` / `updatedAt` sort by the document timestamps). A query returns at most 1000 documents (100 when you set no limit).

<H2 id="queries-and-your-security-rules" step={2}>Queries and your security rules</H2>

A query must match your [security rules](/docs/sync/rules): it is allowed only when the rules allow **every** document it could return, otherwise it fails as a whole with `403 query_not_allowed`. The error names the fields the rules read — filter on them with `==` (or `in`). For example, with a rule `data.ownerId === auth.uid`, query `where('ownerId', '==', <the user's id>)`. Every SDK reports it as a typed error with those `fields`, from `get()` and from listeners.

When the rules allow a query because of its `==` / `in` filters, those filters compare by type: `5` matches `5`, not `"5"`. Send values with their real type.

A query on a collection that has no documents yet is checked against the rules like any other query. When the rules allow it, it returns an empty list. When they don't, it fails with `query_not_allowed`, even though there is nothing to return.

The errors and how to catch them on each platform are in [Platform Notes](/docs/sync/platform-notes).

<H2 id="flutter" step={3}>Flutter</H2>

```dart
// Build queries with fluent API
final adults = await users
    .query()
    .where('age', QueryOperator.greaterThanOrEqual, 18)
    .where('status', QueryOperator.equal, 'active')
    .orderBy('createdAt', direction: OrderDirection.descending)
    .limit(20)
    .get();

// Available operators
QueryOperator.equal              // ==
QueryOperator.notEqual           // !=
QueryOperator.greaterThan        // >
QueryOperator.greaterThanOrEqual // >=
QueryOperator.lessThan           // <
QueryOperator.lessThanOrEqual    // <=
QueryOperator.arrayContains      // array contains value
QueryOperator.isIn               // value in array
QueryOperator.notIn              // value not in array (not supported)
```

<H2 id="react-native" step={4}>React Native</H2>

```typescript
// Build queries with fluent API
const adults = await users
    .query()
    .where('age', '>=', 18)
    .where('status', '==', 'active')
    .orderBy('createdAt', 'desc')
    .limit(20)
    .get();

// Available operators: '==', '!=', '>', '>=', '<', '<=', 'array-contains', 'in', 'not-in'
```

<H2 id="web" step={5}>Web</H2>

```typescript
// Build queries with fluent API
const adults = await users
    .where('age', '>=', 18)
    .where('status', '==', 'active')
    .orderBy('createdAt', 'desc')
    .limit(20)
    .get();

// Available operators: '==', '!=', '>', '>=', '<', '<=', 'array-contains', 'in', 'not-in'
```

<H2 id="android" step={6}>Android</H2>

```kotlin
// Build queries with fluent API
lifecycleScope.launch {
    val adults = users
        .query()
        .where("age", QueryOperator.GREATER_THAN_OR_EQUAL, 18)
        .where("status", QueryOperator.EQUAL, "active")
        .orderBy("createdAt", OrderDirection.DESCENDING)
        .limit(20)
        .get()
}

// Available operators
QueryOperator.EQUAL                 // ==
QueryOperator.NOT_EQUAL             // !=
QueryOperator.GREATER_THAN          // >
QueryOperator.GREATER_THAN_OR_EQUAL // >=
QueryOperator.LESS_THAN             // <
QueryOperator.LESS_THAN_OR_EQUAL    // <=
QueryOperator.ARRAY_CONTAINS        // array contains
QueryOperator.IN                    // value in array
QueryOperator.NOT_IN                // value not in array (not supported)
```

<H2 id="ios" step={7}>iOS</H2>

```swift
// Build queries with fluent API
Task {
    let adults = try await users
        .query()
        .where("age", .greaterThanOrEqual, 18)
        .where("status", .equal, "active")
        .orderBy("createdAt", direction: .descending)
        .limit(20)
        .get()
}

// Available operators: .equal, .notEqual, .greaterThan, .greaterThanOrEqual,
//                      .lessThan, .lessThanOrEqual, .arrayContains, .in, .notIn
```

<H2 id="node-js" step={8}>Node.js</H2>

```typescript
// Build queries with fluent API
const adults = await users
    .where('age', '>=', 18)
    .where('status', '==', 'active')
    .orderBy('createdAt', 'desc')
    .limit(20)
    .get();

// Compound queries
const recentActiveUsers = await users
    .where('status', '==', 'active')
    .where('lastLogin', '>=', thirtyDaysAgo)
    .orderBy('lastLogin', 'desc')
    .get();

// Pagination with offset
const page1 = await users.orderBy('name').limit(10).get();
const page2 = await users.orderBy('name').limit(10).offset(10).get();
const page3 = await users.orderBy('name').limit(10).offset(20).get();
```

<H2 id="rest-api" step={9}>REST API</H2>

```bash
# Query documents: POST the same shape the SDKs send
curl -X POST "https://sync.abrova.ir/databases/{databaseName}/collections/{collectionName}/documents/sdk/query" \
  -H "x-api-key: YOUR_PROJECT_API_KEY" \
  -H "x-server-secret: YOUR_SERVER_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "filters": [
      { "field": "age", "operator": ">=", "value": 18 },
      { "field": "status", "operator": "==", "value": "active" }
    ],
    "orderBy": { "field": "createdAt", "direction": "desc" },
    "limit": 20,
    "offset": 40
  }'
# Response: { "data": [...], "total": 123 }
# Operators: ==, !=, >, >=, <, <=, array-contains, in (not-in is not supported)

# Or GET with a JSON filter and sort (MongoDB-style operators)
curl -G "https://sync.abrova.ir/databases/{databaseName}/collections/{collectionName}/documents/sdk" \
  --data-urlencode 'filter={"age":{"$gte":18},"status":"active"}' \
  --data-urlencode 'sort={"createdAt":-1}' \
  --data-urlencode 'limit=20' \
  --data-urlencode 'skip=40' \
  -H "x-api-key: YOUR_PROJECT_API_KEY" \
  -H "x-server-secret: YOUR_SERVER_SECRET"
# Response: { "data": [...], "total": 123, "skip": 40, "limit": 20 }
# Filter operators: $eq, $ne, $gt, $gte, $lt, $lte, $in, $contains
```

Next: keep a UI in sync with [Realtime Listeners](/docs/sync/listeners).

- Realtime listeners: https://abrova.ir/en/docs/sync/listeners

Realtime listeners are what make AbrovaSync feel "live": instead of polling for changes, your code registers a callback once and the server pushes new data every time the underlying record changes. Three flavors are supported — listen to a whole collection, a single document, or a filtered query — and they all share the same lifecycle (register → receive snapshots → cancel).

<div>
  <div>
    <h3>Collection Listener</h3>
    <p>Fires when any document in the collection is added, updated, or removed. Best for short feeds and small lists.</p>
  </div>
  <div>
    <h3>Document Listener</h3>
    <p>Fires when one specific document changes or is deleted. Best for detail screens.</p>
  </div>
  <div>
    <h3>Query Listener</h3>
    <p>Same callback shape, but scoped to a <code>.where(...).orderBy(...)</code> chain.</p>
  </div>
</div>

<div>
  <h3>Always cancel listeners you don't need</h3>
  <p>A listener you never cancel keeps an open subscription on the server and continues firing your callback. On screens with their own lifecycle, attach the cancel to <code>dispose()</code> / <code>onDestroy()</code> / <code>deinit</code>.</p>
</div>

<Callout kind="warn" title="Use names, not IDs">
Get your references with the database and collection **names** shown in the console, e.g. `database('my-app').collection('users')`. A listener on a reference built from a database or collection ID never receives updates, so always use the names.
</Callout>

#### What a listener receives

The first callback has the current data: the documents of the collection or query, or the document (`null` when it does not exist). After that, the callback runs on every change. A listener on a collection or query that has no documents yet starts with an empty list and receives the first document when it is written. A document listener receives only changes to its own document.

Realtime reconnects by itself after a dropped connection, and open listeners resume. On Android, iOS, Flutter and React Native, listeners also follow the signed-in user: after sign-in, sign-out or a switch to another user they start again for that user.

#### Listeners follow your security rules

A listener is checked like a query (or a single read) when it starts, and again whenever your rules change or a document they look up changes (for example, a user removed from a team) — SDK 0.3.0 and later. It receives only the changes the user may read. If it isn't allowed, or stops being allowed, the listener ends and its error callback gets a typed error: `query_not_allowed` (with the `fields` to filter on) or `listener_revoked`. After an error the listener receives nothing more. The error callback is optional on every platform. Pass one to see why a listener stopped:

```dart
// Flutter
final registration = lists.where('teamId', QueryOperator.equal, teamId).listen(
  (docs) => render(docs),
  onError: (error) {
    if (error is AbrovaSyncListenerError && error.isQueryNotAllowed) {
      print('Filter on: ${error.fields}');
    } else if (error is AbrovaSyncListenerError && error.isListenerRevoked) {
      print('No longer allowed to read these lists');
    }
  },
);
```

```typescript
// React Native
import { AbrovaSyncError } from '@abrova/sync-react-native';

const registration = lists.where('teamId', '==', teamId).listen(
  (docs) => render(docs),
  (error) => {
    if (error.code === AbrovaSyncError.QUERY_NOT_ALLOWED) {
      console.warn('Filter on:', error.fields);
    } else if (error.code === AbrovaSyncError.LISTENER_REVOKED) {
      console.warn('No longer allowed to read these lists');
    }
  },
);
```

```typescript
// Web, Node.js
const stop = db.collection('lists').where('teamId', '==', teamId).onSnapshot(
  (docs) => render(docs),
  (error) => console.warn(error.message), // query_not_allowed, listener_revoked, …
);
```

```kotlin
// Android
val registration = lists.where("teamId", QueryOperator.EQUAL, teamId).listen(
    callback = { docs -> render(docs) },
    onError = { error ->
        when (error) {
            is AbrovaSyncException.QueryNotAllowedException -> Log.w("Sync", "Filter on: ${error.fields}")
            is AbrovaSyncException.ListenerRevokedException -> Log.w("Sync", "No longer allowed")
            else -> Log.w("Sync", error.message ?: "listener stopped")
        }
    },
)
```

```swift
// iOS
let registration = lists.query().where("teamId", .equal, teamId).listen(
    callback: { docs in render(docs) },
    onError: { error in
        if let error = error as? AbrovaSyncError, error.code == "query_not_allowed" {
            print("Filter on: \(error.fields)")
        }
    }
)
```

The same error callback works on `listen()` and `listenDocument()` (Android, iOS, Flutter, React Native) and on every `onSnapshot()` (Web, Node.js). On Web and Node.js a collection listener takes it as the third argument: `collection.onSnapshot(callback, undefined, onError)`. See [Platform Notes](/docs/sync/platform-notes) for the error types.

Listener updates carry the changed document and its version; they never say who made the change.

<H2 id="flutter" step={1}>Flutter</H2>

```dart
// Listen to collection changes
final registration = users.listen((documents) {
  print('Collection updated! Count: ${documents.length}');
  for (final doc in documents) {
    print('  ${doc.id}: ${doc.data['name']}');
  }
});

// Listen to a single document
final docRegistration = users.listenDocument('document-id', (document) {
  if (document != null) {
    print('Document updated: ${document.data}');
  } else {
    print('Document was deleted');
  }
});

// Listen to query results
final queryRegistration = users
    .query()
    .where('status', QueryOperator.equal, 'online')
    .listen((documents) {
      print('Online users: ${documents.length}');
    });

// Stop listening when done
registration.remove();
docRegistration.remove();
queryRegistration.remove();
```

To follow the realtime connection, listen to the `AbrovaSync.connectionStateChanges` stream (`true` when connected). Any number of widgets can listen to it; cancel the subscription in `dispose()`. The `onConnectionState` setter still works but keeps one callback, so a second screen replaces the first one's.

```dart
final connectionSub = AbrovaSync.connectionStateChanges.listen((connected) {
  print(connected ? 'Live' : 'Reconnecting...');
});

// In dispose():
connectionSub.cancel();
```

<H2 id="react-native" step={2}>React Native</H2>

```typescript
// Listen to collection changes
const registration = users.listen((documents) => {
  console.log('Collection updated! Count:', documents.length);
  documents.forEach(doc => {
    console.log(`  ${doc.id}: ${doc.data.name}`);
  });
});

// Listen to a single document
const docRegistration = users.listenDocument('document-id', (document) => {
  if (document) {
    console.log('Document updated:', document.data);
  } else {
    console.log('Document was deleted');
  }
});

// Listen to query results
const queryRegistration = users
    .query()
    .where('status', '==', 'online')
    .listen((documents) => {
      console.log('Online users:', documents.length);
    });

// Stop listening when done
registration.remove();
docRegistration.remove();
queryRegistration.remove();
```

<H2 id="web" step={3}>Web</H2>

```typescript
// Listen to collection changes
const unsubscribe = users.onSnapshot((documents) => {
  console.log('Collection updated! Count:', documents.length);
  documents.forEach(doc => {
    console.log(`  ${doc.id}: ${doc.data.name}`);
  });
});

// Listen to a single document
const userRef = users.document('document-id');
const unsubscribeDoc = userRef.onSnapshot((document) => {
  if (document) {
    console.log('Document updated:', document.data);
  } else {
    console.log('Document was deleted');
  }
});

// Listen to query results
const unsubscribeQuery = users
    .where('status', '==', 'online')
    .onSnapshot((documents) => {
      console.log('Online users:', documents.length);
    });

// Stop listening when done
unsubscribe();
unsubscribeDoc();
unsubscribeQuery();
```

<H2 id="android" step={4}>Android</H2>

```kotlin
// Listen to collection changes
val registration = users.listen { documents ->
    Log.d("AbrovaSync", "Collection updated! Count: ${documents.size}")
    documents.forEach { doc ->
        Log.d("AbrovaSync", "  ${doc.id}: ${doc.data["name"]}")
    }
}

// Listen to a single document
val docRegistration = users.listenDocument("document-id") { document ->
    if (document != null) {
        Log.d("AbrovaSync", "Document updated: ${document.data}")
    } else {
        Log.d("AbrovaSync", "Document was deleted")
    }
}

// Listen to query results
val queryRegistration = users
    .query()
    .where("status", QueryOperator.EQUAL, "online")
    .listen { documents ->
        Log.d("AbrovaSync", "Online users: ${documents.size}")
    }

// Stop listening when done (e.g., in onDestroy)
registration.remove()
docRegistration.remove()
queryRegistration.remove()
```

<H2 id="ios" step={5}>iOS</H2>

```swift
// Listen to collection changes
let registration = users.listen { documents in
    print("Collection updated! Count: \(documents.count)")
    for doc in documents {
        print("  \(doc.id): \(doc.data["name"] ?? "")")
    }
}

// Listen to a single document
let docRegistration = users.listenDocument(documentId: "document-id") { document in
    if let document = document {
        print("Document updated: \(document.data)")
    } else {
        print("Document was deleted")
    }
}

// Listen to query results
let queryRegistration = users
    .query()
    .where("status", .equal, "online")
    .listen { documents in
        print("Online users: \(documents.count)")
    }

// Stop listening when done (e.g., in deinit)
registration.remove()
docRegistration.remove()
queryRegistration.remove()
```

<H2 id="node-js" step={6}>Node.js</H2>

Realtime is opt-in on the server SDK — set `enableRealtime: true` in the config. Otherwise the SDK runs in pure-request mode (smaller footprint, no persistent connection). When the server refuses realtime (for example a wrong server secret), every listener's error callback receives the error. `disconnect()` stops every listener.

```typescript
// Note: Realtime requires enableRealtime: true in config
// const abrovaSync = new AbrovaSyncAdmin({
//   apiKey: '...',
//   serverSecret: '...',
//   enableRealtime: true,
// });

// Listen to collection changes (server-side)
const unsubscribe = users.onSnapshot((documents) => {
  console.log('Collection updated! Count:', documents.length);
  documents.forEach(doc => {
    console.log(`  ${doc.id}: ${doc.data.name}`);
  });
});

// Listen to a single document
const unsubscribeDoc = users.doc('document-id').onSnapshot((document) => {
  if (document) {
    console.log('Document updated:', document.data);
  } else {
    console.log('Document was deleted');
  }
});

// Listen to query results
const unsubscribeQuery = users
    .where('status', '==', 'online')
    .onSnapshot((documents) => {
      console.log('Online users:', documents.length);
    });

// Stop listening when done
unsubscribe();
unsubscribeDoc();
unsubscribeQuery();
```

<H2 id="rest-api" step={7}>REST API</H2>

The REST API has no realtime channel, and AbrovaSync does not send webhooks for document changes. To react to changes from a backend, use the Node.js SDK (step 6 above) with `enableRealtime: true`; from any other HTTP client, poll the query endpoint (see [Querying Data](/docs/sync/queries)).

Next: keep working when the network drops — [Offline Persistence](/docs/sync/offline).

- Batch: https://abrova.ir/en/docs/sync/batch

Batch operations let you execute multiple write operations as a single atomic unit. Either every operation succeeds, or none do — perfect for maintaining data consistency when one logical update spans multiple documents (think money transfers, multi-step workflows, dependent records).

<div>
  <div>
    <h3>Multi-step workflows</h3>
    <p>Update records, counters, and status flags as one atomic transaction so they never drift apart.</p>
  </div>
  <div>
    <h3>Money transfers</h3>
    <p>Debit one account and credit another together — never one without the other.</p>
  </div>
  <div>
    <h3>Bulk updates</h3>
    <p>Update many related documents together so your data is never in a half-applied state.</p>
  </div>
  <div>
    <h3>Data migrations</h3>
    <p>Safely move data between collections with all-or-nothing guarantees.</p>
  </div>
</div>

<H2 id="available-operations" step={1}>Available operations</H2>

A batch holds an in-memory list of writes. Add as many as you need, then call `commit()` to ship them as one atomic request. Four operation types are supported:

<ConfigTable headers={['Operation', 'Purpose']} rows={[
  ['set()', 'Create a document or replace it entirely if it exists. With the merge option it merges the fields instead (as in CRUD).'],
  ['update()', 'Apply a partial update — merge fields into an existing document.'],
  ['delete()', 'Remove a document.'],
  ['create()', 'Create a new document with an auto-generated ID.'],
]} />

<H2 id="flutter" step={2}>Flutter</H2>

```dart
// Create a batch for atomic operations
final batch = AbrovaSync.batch();

// Add multiple operations to the batch
batch.set(usersCollection, 'user1', {'name': 'John', 'status': 'active'});
batch.update(ordersCollection, 'order123', {'status': 'shipped'});
batch.delete(cartCollection, 'cart456');
batch.create(logsCollection, {'action': 'order_shipped', 'timestamp': DateTime.now().toIso8601String()});

// Commit all operations atomically
await batch.commit();
// All operations succeed or fail together!
```

<H2 id="react-native" step={3}>React Native</H2>

```typescript
// Create a batch for atomic operations
const batch = AbrovaSync.batch();

// Add multiple operations to the batch
batch.set(usersCollection, 'user1', { name: 'John', status: 'active' });
batch.update(ordersCollection, 'order123', { status: 'shipped' });
batch.delete(cartCollection, 'cart456');
batch.create(logsCollection, { action: 'order_shipped', timestamp: new Date().toISOString() });

// Commit all operations atomically
await batch.commit();
```

<H2 id="web" step={4}>Web</H2>

```typescript
// Create a batch for atomic operations
const batch = abrovaSync.batch();

// Add multiple operations to the batch
batch.set(usersCollection.document('user1'), { name: 'John', status: 'active' });
batch.update(ordersCollection.document('order123'), { status: 'shipped' });
batch.delete(cartCollection.document('cart456'));
batch.create(logsCollection, { action: 'order_shipped', timestamp: new Date().toISOString() });

// Commit all operations atomically
await batch.commit();
```

<H2 id="android" step={5}>Android</H2>

```kotlin
// Create a batch for atomic operations
val batch = AbrovaSync.getInstance().batch()

// Add multiple operations to the batch
batch.set(usersCollection, "user1", mapOf("name" to "John", "status" to "active"))
batch.update(ordersCollection, "order123", mapOf("status" to "shipped"))
batch.delete(cartCollection, "cart456")
batch.create(logsCollection, mapOf("action" to "order_shipped"))

// Commit all operations atomically
lifecycleScope.launch {
    batch.commit()
}
```

<H2 id="ios" step={6}>iOS</H2>

```swift
// Create a batch for atomic operations
let batch = AbrovaSync.shared.batch()

// Add multiple operations to the batch
batch.set(usersCollection, documentId: "user1", data: ["name": "John", "status": "active"])
batch.update(ordersCollection, documentId: "order123", data: ["status": "shipped"])
batch.delete(cartCollection, documentId: "cart456")
batch.create(logsCollection, data: ["action": "order_shipped"])

// Commit all operations atomically
try await batch.commit()
```

<H2 id="node-js" step={7}>Node.js</H2>

The Node.js SDK's batch supports `set()`, `update()` and `delete()` (no `create()`). Like every other SDK, `commit()` is atomic: all operations are written together, or none is when one is refused.

```typescript
// Create a batch for atomic operations
const batch = abrovaSync.batch();

// Add multiple operations to the batch
batch.set(users.doc('user1'), { name: 'John', status: 'active' });
batch.update(orders.doc('order123'), { status: 'shipped' });
batch.delete(carts.doc('cart456'));

// Commit all operations atomically
await batch.commit();
```

<H2 id="rest-api" step={8}>REST API</H2>

The REST API exposes batches as a single POST with an `operations` array. If any operation fails, the whole batch rolls back — the response tells you which one and why.

```bash
# Batch Operations via REST API
# Execute multiple operations atomically in a single request

curl -X POST "https://sync.abrova.ir/batch/sdk" \
  -H "x-api-key: YOUR_PROJECT_API_KEY" \
  -H "x-server-secret: YOUR_SERVER_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "operations": [
      {
        "type": "set",
        "databaseId": "my-app",
        "collectionId": "users",
        "documentId": "user1",
        "data": { "name": "John", "status": "active" }
      },
      {
        "type": "update",
        "databaseId": "my-app",
        "collectionId": "orders",
        "documentId": "order123",
        "data": { "status": "shipped" }
      },
      {
        "type": "delete",
        "databaseId": "my-app",
        "collectionId": "carts",
        "documentId": "cart456"
      }
    ]
  }'

# Response on success:
# { "success": true, "operationCount": 3 }
# If ANY operation fails, ALL are rolled back
```

When a batch is refused, `commit()` throws (or rejects) and nothing is saved. The error's `statusCode` is 403 when your security rules refused one of the operations. On Android, `commit()` throws an `AbrovaSyncException.BatchWriteException` whose `cause` is the server's answer, a `NetworkException` with that `statusCode`. See [Platform Notes](/docs/sync/platform-notes) for the error types.

<Callout kind="note" title="Batches and your security rules">
Every operation in a batch is checked by your [security rules](/docs/sync/rules) before anything is saved; if one is refused, nothing is. Rules see the database as it was before the batch, and `getAfter()` sees it as it will be after — so a batch can, for example, create a team and make its creator the admin in one go. In the REST body, a `set` operation takes `"merge": true` to merge.
</Callout>

<Callout kind="note" title="Batch size limit">
Batch operations have a limit of 500 operations per batch. For larger operations, split them into multiple batches or use background jobs.
</Callout>

- Offline persistence: https://abrova.ir/en/docs/sync/offline

AbrovaSync supports offline-first architecture. Enable offline mode to cache data locally and continue working without network connectivity. All changes are automatically synced when the connection is restored.

<div>
  <h3>Quick Start Guide</h3>
  <ol>
    <li>
      <span>1</span>
      <span><strong>Enable offline mode</strong> — Set <code>offlineEnabled: true</code> in your config</span>
    </li>
    <li>
      <span>2</span>
      <span><strong>Cache size</strong> — <code>offlineCacheSizeMb</code> is reserved; not used by the SDKs</span>
    </li>
    <li>
      <span>3</span>
      <span><strong>Choose conflict strategy</strong> — Pick <code>serverWins</code>, <code>clientWins</code>, <code>merge</code>, or <code>manual</code></span>
    </li>
    <li>
      <span>4</span>
      <span><strong>Listen to sync state</strong> — Monitor <code>onSyncState</code> for idle/syncing/offline/error</span>
    </li>
    <li>
      <span>5</span>
      <span><strong>Use normally</strong> — All CRUD operations work offline automatically!</span>
    </li>
  </ol>
</div>

<div>
  <div>
    <div>
      <div></div>
    </div>
    <div>
      <p>Optimistic Updates</p>
      <p>While offline, writes return immediately with local data</p>
    </div>
  </div>
  <div>
    <div>
      <div></div>
    </div>
    <div>
      <p>Auto Sync</p>
      <p>Pending changes sync automatically when online</p>
    </div>
  </div>
  <div>
    <div>
      <div></div>
    </div>
    <div>
      <p>Conflict Resolution</p>
      <p>Choose strategy: Server wins, Client wins, Merge, or Manual (Android / iOS)</p>
    </div>
  </div>
  <div>
    <div>
      <div></div>
    </div>
    <div>
      <p>Local Cache</p>
      <p>Documents you read and write are kept on the device</p>
    </div>
  </div>
</div>

<H2 id="conflict-resolution-strategies" step={1}>Conflict Resolution Strategies</H2>

When the same document is edited on a device that's offline and on the server at the same time, AbrovaSync needs a tie-break rule. Pick the strategy that matches your data model:

<div>
  <div>
    <code>serverWins</code>
    <p>Server version always wins. Best for shared data where server is source of truth.</p>
  </div>
  <div>
    <code>clientWins</code>
    <p>Client version always wins. Best for personal data or when offline edits should persist.</p>
  </div>
  <div>
    <code>merge</code>
    <p>Automatically merge non-conflicting fields. Best for documents with independent fields.</p>
  </div>
  <div>
    <code>manual</code>
    <p>Your app decides via callback (a <code>conflictResolver</code> on Android and iOS only). Best when you need custom merge logic.</p>
  </div>
</div>

For a deeper guide on picking and tuning conflict strategies, see [Conflict Resolution](/docs/sync/conflicts).

<H2 id="use-cases" step={2}>Use Cases</H2>

<div>
  <div>
    <div>
      <div></div>
      <span>Shopping Cart Sync</span>
    </div>
    <p>Users can add items to cart while offline. Use <code>merge</code> strategy to combine items added on multiple devices.</p>
  </div>
  <div>
    <div>
      <div></div>
      <span>Order Tracking</span>
    </div>
    <p>Display order status even without network. Use <code>serverWins</code> since order status is controlled by backend.</p>
  </div>
  <div>
    <div>
      <div></div>
      <span>Inventory Management</span>
    </div>
    <p>For inventory-sensitive operations, use <code>serverWins</code> and validate stock levels on sync.</p>
  </div>
</div>

<H2 id="optimistic-updates-explained" step={3}>Optimistic Updates Explained</H2>

Optimistic updates keep your app working without a connection: while the device is offline, a write is saved locally and returned immediately, then synced in the background once the connection is back. While online, writes go to the server first. After you call `disconnect()`, the SDK treats the device as offline: writes are queued at once.

<div>
  <div>
    <div>
      <div>
        <div>1</div>
        <span>User Action</span>
      </div>
      <div></div>
    </div>
    <div>
      <div>
        <div>2</div>
        <span>Local Update</span>
      </div>
      <div></div>
    </div>
    <div>
      <div>
        <div>3</div>
        <span>UI Updated</span>
      </div>
      <div></div>
    </div>
    <div>
      <div>
        <div>4</div>
        <span>Background Sync</span>
      </div>
    </div>
  </div>
  <p>
    User sees instant feedback (step 3) while sync happens in background (step 4)
  </p>
</div>

<H2 id="when-the-cache-is-used" step={4}>When the cache is used</H2>

The cache stands in for the server only when the server cannot be reached: no network, a timeout, or a server error. Then reads are answered from the cache, and writes are saved on the device and queued.

When the server answers and refuses the request (your [security rules](/docs/sync/rules), invalid data), the call fails with that error, even with offline persistence on. Reads are not answered from the cache, and the write is not queued. Check `statusCode` on the error (403 when the rules refused); see [Platform Notes](/docs/sync/platform-notes).

<ConfigTable headers={['Situation', 'Read', 'Write']} rows={[
  ['Server reached and allows the request', 'From the server', 'Saved on the server'],
  ['Server cannot be reached (no network, timeout, server error), or after disconnect()', 'From the cache', 'Saved on the device and queued'],
  ['Server refuses the request (security rules, invalid data)', 'Fails with the error', 'Fails with the error, nothing is queued'],
]} />

<H2 id="queued-writes" step={5}>Queued writes</H2>

A queued write is retried until it goes through.

A queued write can still be refused when it is finally sent, for example when your rules changed in the meantime. The SDK then drops the write and puts the local copy back to the server's version: a refused new document disappears, and a refused update or delete shows the server's document again. Listeners see the change. Your app is told through a callback, with the document id, the operation (create, update or delete) and the server's error:

<ConfigTable headers={['Platform', 'Callback']} rows={[
  ['Flutter', 'AbrovaSync.documentRejections (stream), or the AbrovaSync.onDocumentRejected setter'],
  ['React Native', 'AbrovaSync.onDocumentRejected(callback), returns a function that removes it'],
  ['Web', 'abrovaSync.onDocumentRejected(callback), returns a function that removes it'],
  ['Android', 'SyncListener.onDocumentRejected(documentId, operation, error), added with addSyncListener()'],
  ['iOS', 'SyncEngine.SyncListener.onDocumentRejected(documentId:operation:error:), added with addSyncListener(_:)'],
]} />

The `maxSyncRetries` setting is deprecated on every SDK and has no effect.

<H2 id="flutter" step={6}>Flutter</H2>

```dart
// Enable offline persistence in initialization
await AbrovaSync.init(AbrovaSyncConfig(
  apiKey: 'YOUR_API_KEY',
  offlineEnabled: true,
));

// Sync state: idle, syncing, offline or error
final syncStateSub = AbrovaSync.syncStateChanges.listen((state) {
  print('Sync state: $state');
});

// How many writes are waiting to be sent
final pendingSub = AbrovaSync.pendingCountChanges.listen((count) {
  print('Pending writes: $count');
});

// Queued writes the server refused when they were sent
final rejectionSub = AbrovaSync.documentRejections.listen((rejection) {
  print('${rejection.operation} of ${rejection.documentId} refused '
      '(${rejection.error.statusCode}): ${rejection.error.message}');
});

// All CRUD operations work offline automatically!
final doc = await collection.add({'task': 'Buy milk'});
// Offline: saved locally and returned at once, synced when back online

// Force sync when needed
await AbrovaSync.forceSyncNow();

// When the screen closes:
syncStateSub.cancel();
pendingSub.cancel();
rejectionSub.cancel();
```

Any number of widgets can listen to these streams. The `onSyncState`, `onPendingCount` and `onDocumentRejected` setters still work, but each keeps one callback, so a second screen replaces the first one's.

<H2 id="react-native" step={7}>React Native</H2>

```typescript
// Enable offline persistence in initialization
await AbrovaSync.init({
  apiKey: 'YOUR_API_KEY',
  offlineEnabled: true,
});

// Sync state: 'idle' | 'syncing' | 'offline' | 'error'
const stopSyncState = AbrovaSync.onSyncState((state) => {
  console.log('Sync state:', state);
});

// How many writes are waiting to be sent
const stopPending = AbrovaSync.onPendingCount((count) => {
  console.log('Pending writes:', count);
});

// Queued writes the server refused when they were sent
const stopRejected = AbrovaSync.onDocumentRejected((documentId, operation, error) => {
  console.warn(`${operation} of ${documentId} refused (${error.statusCode}): ${error.message}`);
});

// All CRUD operations work offline automatically!
const doc = await collection.add({ task: 'Buy milk' });
// Offline: saved locally and returned at once, synced when back online

// Force sync when needed
await AbrovaSync.forceSyncNow();
```

<H2 id="web" step={8}>Web</H2>

```typescript
// Offline persistence (IndexedDB) is on by default on Web
const abrovaSync = new AbrovaSync({
  apiKey: 'YOUR_API_KEY',
});

// Listen to sync state: 'idle' | 'syncing' | 'offline' | 'error'
abrovaSync.onSyncState((state) => {
  console.log('Sync state:', state);
});

// Listen to connection state: 'connecting' | 'connected' | 'disconnected' | 'error'
abrovaSync.onConnectionState((state) => {
  console.log('Connection:', state);
});

// Monitor pending changes
abrovaSync.onPendingCount((count) => {
  document.getElementById('pending-badge').textContent = String(count);
});

// Queued writes the server refused when they were sent
abrovaSync.onDocumentRejected((documentId, operation, error) => {
  console.warn(`${operation} of ${documentId} refused (${error.statusCode}): ${error.message}`);
});

// All operations work offline automatically
const doc = await collection.add({ task: 'Buy milk' });

// Force sync
await abrovaSync.forceSyncNow();
```

After `disconnect()` (or `goOffline()`), writes are queued and reads come from the cache until you call `reconnect()` (or `goOnline()`).

<H2 id="android" step={9}>Android</H2>

```kotlin
// Enable offline persistence in configuration
val config = AbrovaSyncConfig.Builder("YOUR_API_KEY")
    .offlineEnabled(true)
    .build()

val abrovaSync = AbrovaSync.initialize(context, config)

// Observe sync state with Flow
lifecycleScope.launch {
    abrovaSync.getSyncState()?.collect { state ->
        when (state) {
            SyncState.IDLE -> Log.d("AbrovaSync", "All synced")
            SyncState.SYNCING -> Log.d("AbrovaSync", "Syncing...")
            SyncState.OFFLINE -> Log.d("AbrovaSync", "Working offline")
            SyncState.ERROR -> Log.d("AbrovaSync", "Sync error")
        }
    }
}

// Queued writes the server refused when they were sent
abrovaSync.addSyncListener(object : SyncListener {
    override fun onSyncStarted() {}
    override fun onSyncCompleted(syncedCount: Int) {}
    override fun onSyncFailed(error: Throwable) {}
    override fun onConflictDetected(conflict: ConflictInfo) {}
    override fun onDocumentSynced(documentId: String, operation: OperationType) {}
    override fun onDocumentRejected(documentId: String, operation: OperationType, error: Throwable) {
        val status = (error as? AbrovaSyncException.NetworkException)?.statusCode
        Log.w("AbrovaSync", "$operation of $documentId refused ($status): ${error.message}")
    }
})

// All CRUD operations work offline automatically!
val doc = collection.add(mapOf("task" to "Buy milk"))
// Offline: saved locally and returned at once, synced when back online

// Force sync when needed
abrovaSync.forceSyncNow()
```

<H2 id="ios" step={10}>iOS</H2>

```swift
// Enable offline persistence in configuration
let config = AbrovaSyncConfigBuilder(apiKey: "YOUR_API_KEY")
    .offlineEnabled(true)
    .build()

AbrovaSync.initialize(config: config)

// Observe sync state with Combine
AbrovaSync.shared.syncStatePublisher?
    .receive(on: DispatchQueue.main)
    .sink { state in
        switch state {
        case .idle: print("All synced")
        case .syncing: print("Syncing...")
        case .offline: print("Working offline")
        case .error: print("Sync error")
        }
    }
    .store(in: &cancellables)

// Queued writes the server refused when they were sent.
// The other SyncListener methods are optional.
final class RejectedWrites: SyncEngine.SyncListener {
    func onDocumentRejected(documentId: String, operation: OperationType, error: Error) {
        let status = (error as? AbrovaSyncError)?.statusCode
        print("\(operation) of \(documentId) refused (\(String(describing: status))): \(error.localizedDescription)")
    }
}
let rejectedWrites = RejectedWrites() // keep a reference
AbrovaSync.shared.addSyncListener(rejectedWrites)

// All CRUD operations work offline automatically!
let doc = try await collection.add(data: ["task": "Buy milk"])
// Offline: saved locally and returned at once, synced when back online

// Force sync when needed
AbrovaSync.shared.forceSyncNow()
```

<H2 id="optional-settings" step={11}>Optional settings</H2>

Two settings change how offline sync behaves. Both are optional; the defaults suit most apps.

<ConfigTable headers={['Setting', 'Default', 'Effect']} rows={[
  ['syncOnReconnect', 'true', 'Send queued writes automatically when the connection comes back. Set it to false to send them only when you call forceSyncNow().'],
  ['conflictStrategy', 'serverWins', 'Which version wins when a document changed both on the device and on the server. See Conflict Resolution.'],
]} />

```dart
// Flutter
await AbrovaSync.init(AbrovaSyncConfig(
  apiKey: 'YOUR_API_KEY',
  offlineEnabled: true,
  syncOnReconnect: false,
  conflictStrategy: ConflictStrategy.clientWins,
));
```

```typescript
// React Native
await AbrovaSync.init({
  apiKey: 'YOUR_API_KEY',
  offlineEnabled: true,
  syncOnReconnect: false,
  conflictStrategy: 'clientWins',
});

// Web
const abrovaSync = new AbrovaSync({
  apiKey: 'YOUR_API_KEY',
  syncOnReconnect: false,
  conflictStrategy: 'clientWins',
});
```

```kotlin
// Android
val config = AbrovaSyncConfig.Builder("YOUR_API_KEY")
    .offlineEnabled(true)
    .syncOnReconnect(false)
    .conflictStrategy(ConflictStrategy.CLIENT_WINS)
    .build()
```

```swift
// iOS
let config = AbrovaSyncConfigBuilder(apiKey: "YOUR_API_KEY")
    .offlineEnabled(true)
    .syncOnReconnect(false)
    .conflictStrategy(.clientWins)
    .build()
```

<Callout kind="note" title="Server-side note">
The Node.js Admin SDK is designed for server-side use where offline persistence is not applicable. For client-side Node.js apps (Electron), consider using the Web SDK. For REST API clients, implement your own caching layer using localStorage, IndexedDB, or SQLite. Queue write operations when offline and sync when the connection is restored.
</Callout>

- Conflict resolution: https://abrova.ir/en/docs/sync/conflicts

When the same document is edited offline on a device and on another client (or on the server) before the device reconnects, AbrovaSync needs a policy for which version wins. Pick the strategy that matches your data model.

<H2 id="conflict-resolution-strategies" step={1}>Conflict Resolution Strategies</H2>

<div>
  <div>
    <h3>serverWins</h3>
    <p>Server version always wins. Best for shared data where the server is the source of truth.</p>
  </div>
  <div>
    <h3>clientWins</h3>
    <p>Client version always wins. Best for personal data or when offline edits should persist.</p>
  </div>
  <div>
    <h3>merge</h3>
    <p>Automatically merge non-conflicting fields. Best for documents with independent fields.</p>
  </div>
  <div>
    <h3>manual</h3>
    <p>Your app decides via a <code>conflictResolver</code> callback (Android and iOS only). Best when you need custom merge logic.</p>
  </div>
</div>

<H2 id="choosing-a-strategy" step={2}>Choosing a strategy</H2>

<ConfigTable headers={['Use case', 'Recommended strategy']} rows={[
  ['Shared documents (e.g. team workspace)', 'serverWins'],
  ['Personal data (e.g. user preferences, notes)', 'clientWins'],
  ['Counters or independent fields on one doc', 'merge'],
  ['Domain-specific (e.g. shopping cart line-items)', 'manual'],
]} />

<H2 id="configuring-the-strategy" step={3}>Configuring the strategy</H2>

The conflict strategy is set once at initialization — see [Offline Persistence](/docs/sync/offline) for the full per-platform setup. The relevant config field is:

- **Flutter** — `conflictStrategy: ConflictStrategy.serverWins`
- **React Native** — `conflictStrategy: 'serverWins'`
- **Web** — `conflictStrategy: 'serverWins'` (not supported on Web: see below)
- **Android** — `.conflictStrategy(ConflictStrategy.SERVER_WINS)`
- **iOS** — `.conflictStrategy(.serverWins)`

Swap `serverWins` for `clientWins`, `merge`, or `manual` as needed.

<Callout kind="warn" title="Where each strategy works">
The strategies are applied by the native Android and iOS SDKs, which Flutter and React Native wrap. `manual` needs a resolver, which only Android (`.conflictResolver { conflict -> ... }`) and iOS (`.conflictResolver(...)`) let you set; without one — including on Flutter and React Native — it falls back to `serverWins`. `conflictStrategy` is not supported on Web: writes queued offline are replayed as they are when the connection returns, so the last write wins.
</Callout>

- Security rules: https://abrova.ir/en/docs/sync/rules

Rules decide who may read and write each part of your database. They are evaluated on every request from a client SDK, using the identity of the user making it — reads, queries, listeners, writes and batches alike.

<Callout kind="warn" title="A new database is locked">
With no rules saved, a database refuses every read and write from a client SDK (a request carrying your server secret still gets through). Write rules before your app can use it. You can always browse and edit your data in the [Abrova Console](https://console.abrova.ir) — a signed-in Console session is not subject to rules, so you cannot lock yourself out.
</Callout>

<H2 id="rules-anatomy" step={1}>Rules anatomy</H2>

<ConfigTable headers={['Key', 'Allows']} rows={[
  ['.read', 'Reading: one document (.get) and queries / listeners on a collection (.list).'],
  ['.get · .list', 'The two halves of .read, when they need different rules.'],
  ['.write', 'Writing: creating (.create), changing (.update) and deleting (.delete) a document.'],
  ['.create · .update · .delete', 'The three halves of .write.'],
  ['.validate', 'A check every write must also pass.'],
  ['$wildcard', 'Matches any path segment and binds it as a variable for the rules below it.'],
]} />

How they combine:

- **Any rule that allows, allows.** The root, every level on the way down and both the general and the specific key at a level (`.read` and `.get`) are checked; one that holds is enough. No rule that holds = denied.
- **Every `.validate` on the path must hold**, from the root down, for `add()`, `set()`, `update()` and every write in a batch.
- A create is a write to a document that doesn't exist yet (`data` is `null`); a delete is a write with `newData` `null`; anything else is an update.

<H2 id="example-ruleset" step={2}>Example ruleset</H2>

```json
{
  "rules": {
    "posts": {
      ".read": true,
      ".write": "auth.uid === 'editor-1'"
    },

    "notes": {
      "$noteId": {
        ".get": "data.ownerId === auth.uid",
        ".list": "data.ownerId === auth.uid",
        ".create": "newData.ownerId === auth.uid",
        ".update": "data.ownerId === auth.uid && newData.ownerId === auth.uid",
        ".delete": "data.ownerId === auth.uid",
        ".validate": "newData.hasChildren(['title'])"
      }
    },

    "users": {
      "$userId": {
        ".read": "auth.uid === $userId",
        ".write": "auth.uid === $userId"
      }
    }
  }
}
```

Save rules in the [Abrova Console](https://console.abrova.ir) under your database. The Console checks them as you type, and refuses to publish a rule that can't be read (a typo, an unknown function, a `$name` that isn't on its path).

<H2 id="queries-and-listeners-rules-are-not-filters" step={3}>Queries and listeners: rules are not filters</H2>

A query or a listener is allowed only when the rules allow **every** document it could return. If they don't, the whole query is refused — it is never quietly trimmed to the documents you may see.

The rules are checked against the query itself: a field the query compares with `==` (or `in`, up to 10 values) is known, any other field is not. So with the `notes` rules above:

<ConfigTable headers={['Query', 'Result']} rows={[
  ["notes where ownerId == <the user's id>", 'Allowed: every result has ownerId === auth.uid.'],
  ['notes (no filter)', "Refused (query_not_allowed): it could return other users' notes."],
  ["notes where ownerId == 'someone-else'", 'Refused.'],
]} />

A refused query fails with `403 query_not_allowed`; the error names the fields the rules read, so you know what to filter on. Filters the rules don't mention (ranges, `!=`, sorting, limits) only narrow the results and never stop a query that is otherwise allowed. Rules can also read `request.query.limit` to cap page sizes.

A rule that needs the document's own id (`auth.uid === $userId`) can't allow a query — the query doesn't have one. Such rules suit `.get`; give `.list` a rule on a field instead.

<Callout kind="warn" title="Filter queries on the field your rule reads">
A query or listener without the filter the rules need is refused with `query_not_allowed` — even if every document it would return happens to be yours. When a rule reads `data.ownerId === auth.uid`, query with `where('ownerId', '==', <the signed-in user's id>)`; when it looks up a membership by `data.teamId`, query with `where('teamId', '==', teamId)`.
</Callout>

<H2 id="teams-groups-and-roles-rules-that-look-up-documents" step={4}>Teams, groups and roles: rules that look up documents</H2>

Rules can read other documents of the same database:

<ConfigTable headers={['Function', 'Returns']} rows={[
  ["exists('collection/' + id)", 'true when the document exists.'],
  ["get('collection/' + id).data.field", 'A field of that document (.id is its id). A document that does not exist is an error, so the rule denies.'],
  ["getAfter('collection/' + id).data.field", 'The same, as the document will be once the current write or batch is saved.'],
]} />

Build the path from text written in the rule and values joined with `+`: `$wildcards`, `auth.uid`, document fields. A value can only ever be one id — a value with `/` in it, or an empty one, makes the lookup fail and the rule deny — so data a user chose can't point the lookup at another collection.

A team with members and roles, kept by your app alone (no server needed):

```json
{
  "rules": {
    "teams": {
      "$teamId": {
        ".get": "exists('team_members/' + $teamId + '_' + auth.uid)",
        ".create": "newData.createdBy === auth.uid",
        ".update": "get('team_members/' + $teamId + '_' + auth.uid).data.role === 'admin'",
        ".delete": "get('team_members/' + $teamId + '_' + auth.uid).data.role === 'admin'"
      }
    },
    "team_members": {
      "$memberId": {
        ".read": "data.userId === auth.uid || exists('team_members/' + data.teamId + '_' + auth.uid)",
        ".create": "$memberId === newData.teamId + '_' + newData.userId && ((newData.userId === auth.uid && newData.role === 'admin' && !exists('teams/' + newData.teamId) && getAfter('teams/' + newData.teamId).data.createdBy === auth.uid) || get('team_members/' + newData.teamId + '_' + auth.uid).data.role === 'admin')",
        ".update": "get('team_members/' + data.teamId + '_' + auth.uid).data.role === 'admin' && newData.teamId === data.teamId && newData.userId === data.userId",
        ".delete": "data.userId === auth.uid || get('team_members/' + data.teamId + '_' + auth.uid).data.role === 'admin'"
      }
    },
    "lists": {
      "$listId": {
        ".read": "exists('team_members/' + data.teamId + '_' + auth.uid)",
        ".create": "get('team_members/' + newData.teamId + '_' + auth.uid).data.role in ['admin', 'editor']",
        ".update": "newData.teamId === data.teamId && get('team_members/' + data.teamId + '_' + auth.uid).data.role in ['admin', 'editor']",
        ".delete": "get('team_members/' + data.teamId + '_' + auth.uid).data.role in ['admin', 'editor']"
      }
    }
  }
}
```

- **Create a team** in one batch: the team document and its creator's `admin` member document (`<teamId>_<userId>`). `getAfter()` sees the team the same batch creates; `!exists(…)` makes sure it is new.
- **Members read their team** with queries that filter on what the rules check: `team_members where teamId == T` (allowed for members of T) or `where userId == <me>` ("my teams"), `lists where teamId == T`.
- **Nobody moves a document to another team:** `.update` requires `teamId` to stay the same.
- **Removing a member** takes effect at once, also for that member's open listeners (SDK 0.3.0 and later): they are checked again and end.
- **Invites:** add an invitations collection whose documents the invited user marks `used` in the same batch that creates their member document, and check it with `get()` / `getAfter()`. Use long random invite ids (at least 128 bits) and give invitations a `.get` rule but no `.list`, so they can't be listed.

A batch is checked and saved as one: two people using the same invite at the same moment can't both get in, and a member removed a moment before can't still write.

#### Limits and cost

- At most **10** documents looked up per request or query, **20** per batch (and 10 per operation in it). Beyond that the request is denied.
- Each document looked up is read once per request and **billed as a document read**.
- Lookups read only the same database, and are not themselves subject to rules.

<H2 id="where-auth-uid-comes-from" step={5}>Where auth.uid comes from</H2>

Rules are only as trustworthy as the identity behind them. Your API key is **public** — it ships inside every app bundle — so it cannot decide who the user is.

<ConfigTable headers={['Credential', 'Where it lives', 'What it proves']} rows={[
  ['API key (ab_live_…)', 'Inside your app. Public.', 'Which project the request belongs to.'],
  ['Server secret (ab_srv_…)', 'Your server only. Never in an app.', 'That a request comes from your backend.'],
  ['User token', 'Your app, one per signed-in user.', 'Which user is acting. This is what sets auth.uid.'],
]} />

Your backend mints a user token with the server secret and hands it to your app:

```js
// Your backend, behind your own session check
const response = await fetch('https://sync.abrova.ir/users/token', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': process.env.ABROVA_API_KEY,
    'x-server-secret': process.env.ABROVA_SERVER_SECRET,
  },
  body: JSON.stringify({ userId: session.userId }),  // your id for the user
});

const { token, expiresIn } = await response.json(); // expiresIn: 3600 by default
```

Every SDK takes it through a token provider and refreshes it before it expires — see [Initialization](/docs/sync/initialization). With [Abrova Auth](/docs/auth/quick-start) your app gets this token without a server of its own.

#### One token for every Abrova product

If your app also uses Abrova Chat, Abrova Push or Abrova A/B Testing, mint **one** token for all of them from the Abrova auth endpoint instead:

```bash
curl -X POST https://auth.abrova.ir/users/token \
  -H "x-api-key: $ABROVA_API_KEY" \
  -H "x-server-secret: $ABROVA_SERVER_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"userId": "user-123", "expiresIn": 3600}'

# → { "token": "eyJhbGciOi…", "userId": "user-123", "expiresIn": 3600, "expiresAt": "2026-09-21T10:00:00.000Z" }
```

Give that same token to every SDK's `tokenProvider` — Sync, Chat, Push and A/B Testing. `expiresIn` is in seconds: 3600 (1 hour) by default, 86400 (24 hours) maximum. Call it from your server, never from an app.

<Callout kind="note" title="Keep it on the device">
A token is valid until it expires, so store it with the user's session (Keychain, Keystore or secure storage) and reuse it across app launches. Your app then only calls your backend when the token is close to expiry — not on every start.
</Callout>

#### Custom claims (roles)

Your server can add facts about the user to the token it mints — a role, a membership level, the teams they belong to. Rules read them as `auth.token.<name>`, and a string `role` claim is also available as `auth.role`:

```js
body: JSON.stringify({ userId: session.userId, claims: { role: 'admin', membership: 'gold', teams: ['red'] } }),
```

```json
".write": "auth.role === 'admin' || auth.token.teams.includes('red')"
```

Both token endpoints accept `claims`: up to 20 names (letters, digits and `_`), each a text of up to 256 characters, a number, `true` / `false`, or a list of up to 50 texts — 1 KB in all. Reserved token names (`sub`, `exp`, `iat`, …) are refused. Claims are signed into the token, so an app can neither add nor change them; a user whose token has no such claim fails the check. Mint a new token when a user's role changes — or keep roles in documents and look them up (step 4), which needs no new token.

#### How the user signed in

With Abrova Auth, `auth.amr` says how the user signed in: `anonymous`, `apple`, `google`, `password`, `magic_link` or `telegram`. `auth.anonymous` is `true` only for a guest — use `auth.anonymous === false` to keep guests out of shared data. A token your server mints names a real user: it has no `auth.amr`, and `auth.anonymous` is `false`.

#### Signing a user out everywhere

In the Console, **Sync › Security › Sign a user out everywhere** refuses every token issued to that user before that moment, including live connections and listeners. Their apps get `401 token_expired`, ask your server for a new token through the token provider, and get one only if your server still issues it.

<Callout kind="warn" title="Signed user tokens">
Only a user token says who the user is. A plain user id sent by an app is not verified, so `auth.uid` would be a claim rather than a fact — signed user tokens are being required for every project, and **Console › Sync › Security** shows what your apps still send. Once they are, a request with no user at all is anonymous to the rules: `auth` is `null`, so `auth !== null` refuses it.
</Callout>

An app where no one is signed in yet has no token to send. The client SDKs (0.2.1 and later) handle that for you: the connection waits and the SDK connects after sign-in — see [Initialization](/docs/sync/initialization).

<H2 id="expression-reference" step={6}>Expression reference</H2>

<ConfigTable headers={['Expression', 'Meaning']} rows={[
  ['true / false', 'Always allow / always deny.'],
  ['auth !== null', 'A user is acting.'],
  ["auth.uid === 'value'", 'The acting user is exactly this id.'],
  ['auth.uid === $userId', 'A path segment captured by a $ name (either order).'],
  ['data.ownerId === auth.uid', 'A field of the stored document (either order).'],
  ['newData.ownerId === auth.uid', 'A field of the document as it will be saved.'],
  ["data.status === 'paid'", "Compare with text in quotes, a number, true / false or null. Also !==."],
  ['newData.total <= 100', 'Numbers: >, >=, <, <=.'],
  ['data.address.city', 'Nested fields, with dots.'],
  ["data.role in ['admin', 'editor']", 'One of a list.'],
  ['data.members.includes(auth.uid)', 'A list field contains a value.'],
  ["'owner' in data.roles", 'A map field has this key.'],
  ["data.first + ' ' + data.last", 'Join texts (or add numbers).'],
  ["auth.role === 'admin'", 'A role claim from the user token; auth.token.<name> reads any claim.'],
  ['auth.amr, auth.anonymous', 'How the user signed in with Abrova Auth.'],
  ['data === null  /  newData === null', 'The document does not exist yet (a create) / is being deleted.'],
  ["newData.hasChildren(['a','b'])", 'The document has these fields — useful in .validate.'],
  ["exists(…), get(…).data.f, getAfter(…)", 'Other documents (step 4).'],
  ['request.time', 'The server time, in milliseconds (e.g. data.expiresAt > request.time).'],
  ['request.query.limit', "The query's limit, in .list / .read rules."],
  ['!expr, a && b, a || b, c ? a : b, ( … )', 'Not, and, or, if-then-else, grouping. || binds looser than &&.'],
]} />

How they behave:

- `==` is the same as `===`: values are never converted, so `5` does not equal `'5'`.
- A field the document does not have counts as `null`.
- **Errors deny.** Some expressions can't be decided: a comparison with an `auth` value that is missing (no user, no such claim), `<` on something that isn't a number, `get()` of a document that doesn't exist, a field of a query document the query doesn't filter on. Such a part is neither true nor false: `error || true` still allows, `error && false` is false, `!error` stays an error, and a rule that ends in an error denies. So neither `data.ownerId !== auth.uid` nor `!(data.ownerId === auth.uid)` lets a request without a user in.
- A field used on its own as a condition (`data.public`) must be `true` or `false`.

<H2 id="who-is-not-subject-to-rules" step={7}>Who is not subject to rules</H2>

<ConfigTable headers={['Caller', 'Rules apply?']} rows={[
  ['Client SDKs (Web, Flutter, Android, iOS, React Native)', 'Yes — every read, query, listener and write.'],
  ['Node.js SDK or REST, using your server secret', 'Yes, once the database has rules — evaluated like any other caller, with auth.uid set to the userId it sends. A database with no rules saved is not locked to it.'],
  ['Abrova Console, signed in', 'No — you own the data, so the data browser always works.'],
]} />

<Callout kind="warn" title="The Node.js SDK is not a rules bypass">
Once a database has rules they are evaluated for it too, so give it an identity with `userId` in its config and write rules that account for your backend. Always set a `userId` (or a user token); without one, `auth.uid` is not your user. For privileged work with no rule to satisfy, use the Console.
</Callout>

- Data structure: https://abrova.ir/en/docs/sync/data-structure

AbrovaSync organizes data into three levels: a **Database** is the top-level container (created in the Abrova Console), a **Collection** is a named group of documents inside a database, and a **Document** is a JSON object with a unique ID.

Apps address databases and collections by **name**, not by ID: `sync.database('my-app').collection('todos')`. A database name is unique within a project, and the API key decides which project is used (two projects in one organization may reuse the same name).

<H2 id="visual-model" step={1}>Visual model</H2>

```text
Database: my-app
├── Collection: users
│   ├── Document: user_001
│   │   └── { name: "John", email: "john@..." }
│   ├── Document: user_002
│   │   └── { name: "Jane", email: "jane@..." }
│   └── ...
├── Collection: posts
│   ├── Document: post_001
│   │   └── { title: "Hello", content: "..." }
│   └── ...
└── Collection: settings
    └── Document: app_config
        └── { theme: "dark", version: "1.0" }
```

<H2 id="identifiers" step={2}>Identifiers</H2>

<ConfigTable headers={['Level', 'How it is named']} rows={[
  ['Database', 'Created from the Abrova Console. Reference it in code by its name (unique within the project the API key belongs to), not its ID.'],
  ['Collection', 'Created by its first write from an SDK — a single write or a batch — when your rules allow that write. Letters, digits, - and _, up to 64 characters. Reference it by that name.'],
  ['Document', 'Auto-generated ID from add() / create(), or a string you pass to set() / update().'],
]} />

<H2 id="creating-and-managing-databases-and-collections" step={3}>Creating and managing databases and collections</H2>

As in Firebase, your app's API key only reads and writes documents. Managing the structure belongs to the Console and to your own server:

<ConfigTable headers={['Who', 'What it can do']} rows={[
  ['App (API key only)', 'Read and write documents, which creates a collection on its first write. Listing, creating or deleting databases and collections is refused with 403 server_secret_required.'],
  ['Your server (API key + server secret)', 'List the databases of its project, and list, read, create and delete collections. Only within the project the API key belongs to.'],
  ['Abrova Console', 'Everything, including creating, renaming and deleting databases.'],
]} />

From your server, with the headers `x-api-key` and `x-server-secret`:

```bash
curl https://sync.abrova.ir/databases \
  -H "x-api-key: $ABROVA_API_KEY" -H "x-server-secret: $ABROVA_SERVER_SECRET"

curl https://sync.abrova.ir/databases/my-app/collections \
  -H "x-api-key: $ABROVA_API_KEY" -H "x-server-secret: $ABROVA_SERVER_SECRET"

curl -X DELETE https://sync.abrova.ir/databases/my-app/collections/old-logs \
  -H "x-api-key: $ABROVA_API_KEY" -H "x-server-secret: $ABROVA_SERVER_SECRET"
```

Deleting a collection deletes its documents too, for good. Keep the server secret on your server only — never in an app.

<H2 id="export-and-import" step={4}>Export and import</H2>

In the Console, **Sync › Settings › Data** (or a collection's ⋯ menu) exports a database or one collection as a JSON file, and imports a JSON file into a collection: it shows how many documents are new or would replace one with the same id, then merges by id or replaces the whole collection. Imports follow the same path as writes from the Console, so apps listening to the collection see every change, and they are not billed as reads or writes.

- Platform notes: https://abrova.ir/en/docs/sync/platform-notes

Behavior, authentication, and capability differences between each AbrovaSync SDK and the REST API.

<H2 id="per-platform-behavior" step={1}>Per-platform behavior</H2>

<ConfigTable headers={['Platform', 'Notes']} rows={[
  ['Flutter & React Native', 'Wrap the native Android and iOS SDKs — best performance with a consistent API across both platforms.'],
  ['Web SDK', 'Built-in offline support via IndexedDB. Offline writes sync automatically when the connection returns.'],
  ['Native Android & iOS', 'Both async/await and callback-based APIs. Choose the style that fits your app architecture.'],
  ['Node.js / Backend SDK', 'Server-side SDK. Requires both apiKey and serverSecret. Once a database has rules they apply to it as to any client (auth.uid is the userId you configure); a database with no rules is open to it, while client SDKs are locked out. Realtime is opt-in (enableRealtime). Batches are atomic, as on every SDK.'],
  ['REST API', 'Direct HTTP access from any language. There is no realtime channel or change webhook: poll, or use the Node.js SDK with enableRealtime.'],
]} />

Live updates use an encrypted connection on every platform (Android 0.2.5+, iOS 0.2.4+, Flutter and React Native 0.2.5+, Web, Node.js 0.2.2+).

<Callout kind="note" title="Server-Side Only (REST API & Node.js)">
Never use the server secret in client-side code (mobile/web apps). Anything shipped in an app should be treated as public, and the server secret can mint a user token for anyone in your project. Client apps use the API key only, plus a short-lived user token your backend mints for them — see [Security Rules](/docs/sync/rules).
</Callout>

<H2 id="errors" step={2}>Errors</H2>

When a call fails, every SDK throws (or rejects with) an error that carries the HTTP status of the server's answer as `statusCode`. Use `statusCode` to tell a refusal from a connection problem:

<ConfigTable headers={['statusCode', 'Meaning']} rows={[
  ['403', 'Your security rules refused the request.'],
  ['404', 'The document does not exist.'],
  ['400 / 422', 'The server does not accept the request (for example invalid data).'],
  ['401', 'The user token is missing, expired or not valid.'],
  ['null / undefined', 'The server could not be reached (no network, timeout).'],
]} />

With [offline persistence](/docs/sync/offline) on, a call that cannot reach the server is answered from the cache or queued instead of failing. A refusal by the server is always thrown.

Errors from your security rules also carry a code:

- **`query_not_allowed`**: the rules do not allow a query or a listener, because it could return documents the user may not read. `fields` names the fields to filter on. See [Queries and your security rules](/docs/sync/queries).
- **`listener_revoked`**: a listener was stopped because the rules no longer allow it (for example, the user was removed from a team). It receives nothing more and is not restarted.
- **`permission_denied`**: the rules do not allow reading what a listener listens to (Flutter, React Native, Web).

<ConfigTable headers={['Platform', 'Error type', 'Fields']} rows={[
  ['Android', 'AbrovaSyncException.NetworkException, with the subclasses QueryNotAllowedException and ListenerRevokedException', 'statusCode, code, fields (QueryNotAllowedException)'],
  ['iOS', 'AbrovaSyncError, with the cases .queryNotAllowed(_, fields:) and .listenerRevoked', 'statusCode, code, fields'],
  ['Flutter', 'AbrovaSyncError for calls; AbrovaSyncListenerError for listener errors', 'code, statusCode, fields; isPermissionDenied (AbrovaSyncError); isQueryNotAllowed, isListenerRevoked (AbrovaSyncListenerError)'],
  ['React Native', 'AbrovaSyncError', 'code, statusCode, fields'],
  ['Web', 'AbrovaSyncError', 'code, reason, statusCode (also status), fields'],
  ['Node.js', 'AbrovaSyncError, with the subclasses QueryNotAllowedError and ListenerRevokedError', 'code, statusCode (also status), serverCode, fields (QueryNotAllowedError)'],
]} />

```dart
// Flutter
try {
  final open = await todos.where('teamId', QueryOperator.equal, teamId).get();
} on AbrovaSyncError catch (e) {
  if (e.code == AbrovaSyncErrorCode.queryNotAllowed) {
    print('Filter on: ${e.fields}');
  } else if (e.isPermissionDenied) {
    print('Refused by the security rules');
  } else if (e.statusCode == null) {
    print('Could not reach the server');
  }
}
```

```typescript
// React Native
import { AbrovaSyncError } from '@abrova/sync-react-native';

try {
  const open = await todos.where('teamId', '==', teamId).get();
} catch (e) {
  if (e instanceof AbrovaSyncError && e.code === AbrovaSyncError.QUERY_NOT_ALLOWED) {
    console.log('Filter on:', e.fields);
  } else if (e instanceof AbrovaSyncError && e.statusCode === 403) {
    console.log('Refused by the security rules');
  }
}
```

```typescript
// Web
import { AbrovaSyncError } from '@abrova/sync-web';

try {
  const open = await todos.where('teamId', '==', teamId).get();
} catch (e) {
  if (e instanceof AbrovaSyncError && e.reason === 'query_not_allowed') {
    console.log('Filter on:', e.fields);
  } else if (e instanceof AbrovaSyncError && e.statusCode === 403) {
    console.log('Refused by the security rules');
  } else if (e instanceof AbrovaSyncError && e.statusCode === undefined) {
    console.log('Could not reach the server');
  }
}
```

```typescript
// Node.js
import { AbrovaSyncError, QueryNotAllowedError } from '@abrova/sync-node';

try {
  const open = await todos.where('teamId', '==', teamId).get();
} catch (e) {
  if (e instanceof QueryNotAllowedError) {
    console.log('Filter on:', e.fields);
  } else if (e instanceof AbrovaSyncError && e.statusCode === 403) {
    console.log('Refused by the security rules');
  } else if (e instanceof AbrovaSyncError && e.statusCode === undefined) {
    console.log('Could not reach the server');
  }
}
```

```kotlin
// Android
try {
    val open = todos.where("teamId", QueryOperator.EQUAL, teamId).get()
} catch (e: AbrovaSyncException.QueryNotAllowedException) {
    Log.w("Todos", "Filter on: ${e.fields}")
} catch (e: AbrovaSyncException.NetworkException) {
    when (e.statusCode) {
        403 -> Log.w("Todos", "Refused by the security rules")
        null -> Log.w("Todos", "Could not reach the server")
        else -> Log.w("Todos", "Failed: ${e.message}")
    }
}
```

```swift
// iOS
do {
    let open = try await todos.query().where("teamId", .equal, teamId).get()
} catch AbrovaSyncError.queryNotAllowed(_, let fields) {
    print("Filter on: \(fields)")
} catch let error as AbrovaSyncError {
    switch error.statusCode {
    case 403: print("Refused by the security rules")
    case nil: print("Could not reach the server")
    default: print("Failed: \(error.localizedDescription)")
    }
}
```

Listener errors arrive in the listener's error callback instead of being thrown. See [Realtime Listeners](/docs/sync/listeners).


## Abrova Flags (coming soon)

- Flutter: https://abrova.ir/en/docs/flags/flutter

<BestPracticeList columns={2} items={[
  ['Client-Safe', 'Uses the public API key only. Safe to ship in an app'],
  ['Evaluated by the Service', 'The app receives values for this user. Targeting rules never reach the device'],
  ['Typed Getters', 'getBool, getString, getNumber and getJson, each with a default'],
  ['Offline Cache', 'The last values are stored on the device and served at start and offline'],
  ['Anonymous Id', 'Percentage rollouts also work before sign-in'],
  ['All Flutter Platforms', 'iOS, Android, web, macOS, Windows and Linux'],
]} />

<Callout kind="note" title="Abrova Flags Flutter SDK v0.2.0">
This page describes `abrova_flutter_flags` 0.2.0. It is a breaking release: the entry class is now `AbrovaFlags`, getters are synchronous, and flags are evaluated by the service instead of on the device. Coming from 0.1.x? See **Upgrading from 0.1.x** at the end of this page.
</Callout>

<Callout kind="note" title="Requirements">
Flutter 3.13 or higher. Dart 3.0 or higher.
</Callout>

Using an AI assistant? See [AI assistants](/docs/flags/ai-assistants) for how to give it these docs.

<H2 id="installation" step={1}>Installation</H2>

Install from Abrova Center in two steps. First add the package to your `pubspec.yaml` with the Abrova Center address:

```yaml
dependencies:
  abrova_flutter_flags:
    hosted: https://center.abrova.ir/api/packages/abrova/pub
    version: ^0.2.0
```

Then run:

```bash
flutter pub get
```

<H2 id="initialization" step={2}>Initialization</H2>

Call `AbrovaFlags.init` once, before `runApp`. Use your public API key (`ab_live_...`).

```dart
import 'package:flutter/material.dart';
import 'package:abrova_flutter_flags/abrova_flutter_flags.dart';

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();

  await AbrovaFlags.init(const AbrovaFlagsConfig(
    apiKey: 'ab_live_xxx',
    environment: 'production', // leave out to use the Default values
  ));

  runApp(const MyApp());
}
```

`init` serves the values cached on the device right away and waits up to `initTimeout` (5 seconds) for the first answer from the network. If the network is slow, `init` returns anyway and the fetch continues in the background.

<Callout kind="note" title="Never use the server secret in an app">
`init` throws an `ArgumentError` if `apiKey` is a server secret (`ab_srv_...`). The server secret belongs on your backend, with the [Node.js](/docs/flags/nodejs) or [Next.js](/docs/flags/nextjs) server SDK.
</Callout>

<H2 id="read-flags" step={3}>Read flags</H2>

Getters are synchronous and never throw. Each one takes the default to use when the flag is unknown, when no values are available yet, or when the flag has another type.

```dart
final flags = AbrovaFlags.instance;

if (flags.isEnabled('new-checkout')) {
  // Show the new checkout
}

final dark = flags.getBool('dark-mode', false);
final theme = flags.getString('theme', 'light');
final maxItems = flags.getNumber('max-items', 10);
final layout = flags.getJson('home-layout', {'columns': 2});
```

<ConfigTable headers={['Method', 'Returns']} rows={[
  ['isEnabled(key, [defaultValue = false])', 'true when the flag is served on for this user'],
  ['getBool(key, defaultValue)', 'Value of a boolean flag'],
  ['getString(key, defaultValue)', 'Value of a string flag'],
  ['getNumber(key, defaultValue)', 'Value of a number flag, as num'],
  ['getJson(key, defaultValue)', 'Value of a json flag: a map, list, string, number, bool or null'],
  ['getAll()', 'Every value held, as Map<String, AbrovaFlagResult>'],
]} />

#### Details and reasons

Each typed getter has a `...Detail` form that also tells you why you got the value.

```dart
final d = flags.getStringDetail('theme', 'light');
print('${d.value} ${d.enabled} ${d.variant} ${d.reason} ${d.version}');
```

`getBoolDetail`, `getStringDetail`, `getNumberDetail` and `getJsonDetail` check the flag type. `getDetail(key, [defaultValue])` returns the stored value without a type check.

<ConfigTable headers={['Reason', 'Meaning']} rows={[
  ['ON', 'The flag is on and has no variants. The value is true'],
  ['VARIANT', 'The flag is on and a variant was served'],
  ['DISABLED', 'The flag is off in this environment. The flag off value is served'],
  ['NOT_TARGETED', 'The targeting rules did not match this user. The off value is served'],
  ['OUTSIDE_ROLLOUT', 'The user is outside the rollout percentage. The off value is served'],
  ['PREREQUISITE_FAILED', 'A flag this one depends on did not give the required result. The off value is served'],
  ['NO_BUCKETING_ID', 'A rollout or split needed a user id or anonymous id and none was sent'],
  ['ERROR', 'The flag could not be evaluated. The off value is served'],
  ['FLAG_NOT_FOUND', 'No such flag. Your default is returned'],
  ['NOT_READY', 'No cached or fetched values yet. Your default is returned'],
  ['TYPE_MISMATCH', 'For example getString on a boolean flag. Your default is returned'],
]} />

The constants are on `AbrovaFlagReason` (for example `AbrovaFlagReason.notReady`). `isEnabled` is `true` only for `ON` and `VARIANT`.

<H2 id="identify-the-user" step={4}>Identify the user</H2>

Tell the SDK who the user is and what you know about them. Targeting rules and percentage rollouts are evaluated against this context.

```dart
// After sign-in
await flags.identify('user-123', attributes: {
  'plan': 'pro',
  'country': 'IR',
  'beta': true,
});

// Replace all attributes
await flags.setAttributes({'plan': 'business'});

// Signed out, attributes stay
await flags.setUserId(null);

// Sign-out: clears the user id, the attributes and the cached values
await flags.reset();
```

- Each change fetches new values after a short pause (250 ms), so several calls in a row send one request.
- `setAttributes` and the `attributes` of `identify` **replace** the whole set. They do not merge.
- When the user id changes, the previous user's values are dropped at once. Until the new values arrive, getters return your defaults (reason `NOT_READY`).
- Attributes are strings, numbers, booleans, null, or lists of those. No nested maps. At most 100 attributes; a string holds at most 1,024 characters.

If you already know the user at start, pass `userId` and `attributes` in the config. The SDK then serves that user's cached values immediately and sends one request instead of two.

```dart
await AbrovaFlags.init(AbrovaFlagsConfig(
  apiKey: 'ab_live_xxx',
  environment: 'production',
  userId: currentUser?.id,
  attributes: {'plan': 'pro'},
));
```

#### Anonymous id

Every install gets a random anonymous id (a UUID). It is stored on the device and sent with every request, so a 10% rollout reaches about 10% of signed-out installs too. When a user id is set, rollouts use the user id instead.

The anonymous id survives `reset()`. Call `resetAnonymousId()` to replace it. Read it with `flags.anonymousId`.

<H2 id="updates-and-refresh" step={5}>Updates and refresh</H2>

```dart
// New values arrived
final sub = flags.onChange.listen((_) => setState(() {}));

// A request failed
flags.onError.listen((e) => debugPrint('${e.statusCode} ${e.code} ${e.message}'));

// Fetch now
await flags.refresh();
```

The SDK fetches values:

- on `init`,
- after `identify`, `setUserId`, `setAttributes`, `reset` and `resetAnonymousId`,
- when the app returns to the foreground and the last fetch is older than 15 minutes,
- on `refresh()`,
- on a timer, only if you set `refreshIntervalSeconds`.

<Callout kind="note" title="Each fetch counts as one evaluation">
Every request for values is counted as one flag evaluation, whatever the number of flags it returns (100,000 evaluations are free every month; the price above that is set at launch). This is why polling is off by default. `identify`, `setUserId` and `setAttributes` send a request every time you call them, also when nothing changed, so call them when the user or the attributes really change, not on every build.
</Callout>

<H2 id="offline-and-errors" step={6}>Offline and errors</H2>

The last values are stored with `shared_preferences` and served at the next start, before the network answers. A failed request never clears them.

- **Offline or server error:** the last values keep being served. The SDK retries with a growing delay (up to 5 minutes).
- **Rate limited (429):** the SDK waits the time the service asks for, then retries.
- **401, 403 or 404** (wrong key, Flags not enabled for the project, unknown environment): automatic fetches stop until you call `refresh()` or restart the app. Check `flags.lastError`.
- **Before the first values:** `flags.isReady` is `false` and getters return your defaults. `await flags.whenReady` completes when values are available.

Call `flags.close()` when you no longer need the client.

### Configuration Options

<ConfigTable headers={['Option', 'Type', 'Default', 'Description']} rows={[
  ['apiKey', 'String', 'required', 'Your public API key (ab_live_xxx)'],
  ['environment', 'String?', 'null', 'Environment key (production, staging, development or your own). null uses the Default values'],
  ['userId', 'String?', 'null', 'Signed-in user id at start'],
  ['attributes', 'Map<String, Object?>', '{}', 'Targeting attributes at start'],
  ['flagKeys', 'List<String>?', 'null', 'Only fetch these flags. null fetches every flag of the project'],
  ['refreshIntervalSeconds', 'int', '0', 'Polling while the app is in the foreground. 0 is off; otherwise at least 60'],
  ['initTimeout', 'Duration', '5 seconds', 'How long init waits for the first answer'],
  ['debug', 'bool', 'false', 'Verbose logging. Errors are always logged'],
]} />

### Testing

`AbrovaFlags.create` builds a client without touching `AbrovaFlags.instance`. Pass `MemoryFlagsStorage()` and your own `http.Client` (for example `MockClient` from `package:http/testing.dart`).

```dart
final flags = await AbrovaFlags.create(
  const AbrovaFlagsConfig(apiKey: 'ab_live_xxx'),
  storage: MemoryFlagsStorage(),
  httpClient: mockClient,
  observeAppLifecycle: false,
);
```

### Upgrading from 0.1.x

0.2.0 is a new API, and 0.1.x clients stop receiving flags. Update the package and change these calls:

<ConfigTable headers={['0.1.x', '0.2.0']} rows={[
  ['AbrovaFeatureFlags.init(AbrovaFeatureFlagsConfig(...))', 'AbrovaFlags.init(AbrovaFlagsConfig(...))'],
  ['AbrovaFeatureFlags.instance', 'AbrovaFlags.instance'],
  ["await flags.isEnabled('k')", "flags.isEnabled('k') (synchronous)"],
  ["await flags.getValue('k', defaultValue: x)", "getBool / getString / getNumber / getJson('k', x)"],
  ["await flags.evaluate('k')", "getDetail('k', x), which adds reason and version"],
  ['setUserAttributes(map), merged', 'setAttributes(map), replaces. Or identify(id, attributes: map)'],
  ['getAll() returned flag configurations', 'getAll() returns this user\'s values only'],
  ['callback: (event, data)', 'onChange and onError streams'],
  ['enableOfflineCache, isOnline, dispose()', 'Always cached; lastError; close()'],
]} />

- The class was renamed to `AbrovaFlags`, so it no longer clashes with `AbrovaFeatureFlags` in the Abrova A/B Testing Flutter SDK. You can import both packages.
- `connectivity_plus` and `crypto` are no longer needed by the SDK.
- Rollouts use a new bucketing method, so users are assigned to rollouts and variants again once.

### Best Practices

<BestPracticeList items={[
  ['Initialize early', 'Call AbrovaFlags.init() in main() before runApp()'],
  ['Pass the user at start', 'If a user is signed in, pass userId and attributes in the config so the cached values are served at once'],
  ['Always give a sensible default', 'The default is what your users see before the first values and when a flag is removed'],
  ['Reset on sign-out', 'Call reset() so the next user never sees the previous user\'s values'],
  ['Leave polling off', 'Values refresh on start, on context changes and on app resume. Turn polling on only if you need faster updates'],
]} />

- Node.js: https://abrova.ir/en/docs/flags/nodejs

<Callout kind="note" title="Server-Side Only">
The Node.js SDK requires both `apiKey` and `serverSecret`. The server secret can read every targeting rule of your project: never expose it in a browser or an app bundle. For client apps, use the Flutter, React Native, Android, iOS or Next.js client SDKs.
</Callout>

<Callout kind="note" title="Abrova Flags Node.js SDK v0.2.0">
This page describes `@abrova/flags-node` 0.2.0. It is a breaking release: typed getters replace `getValue`, the context field is `attributes`, and rules refresh on their own. Coming from 0.1.x? See **Upgrading from 0.1.x** at the end of this page.
</Callout>

<Callout kind="note" title="Requirements">
Node.js 18 or newer (the SDK uses the built-in `fetch`).
</Callout>

<H2 id="installation" step={1}>Installation</H2>

```bash
# 1. .npmrc in your project root: @abrova packages come from Abrova Center
@abrova:registry=https://center.abrova.ir/api/packages/abrova/npm/
```

```bash
# 2. Install
npm install @abrova/flags-node
# or
yarn add @abrova/flags-node
```

<H2 id="initialization" step={2}>Initialization</H2>

Create one instance for the process and reuse it.

```typescript
import { AbrovaFlags } from '@abrova/flags-node';

const flags = new AbrovaFlags({
  apiKey: process.env.ABROVA_FLAGS_API_KEY!,             // ab_live_xxx
  serverSecret: process.env.ABROVA_FLAGS_SERVER_SECRET!, // ab_srv_xxx, backend only
  environment: 'production',                             // leave out to use the Default values
});

await flags.init();
```

`init()` downloads the rules and starts refreshing them every 30 seconds. It resolves after the first download, or after `initTimeoutMs` (5 seconds) if the network is slow, and it never rejects. Until the rules arrive, every getter returns your default with reason `NOT_READY`.

The constructor throws when `apiKey` or `serverSecret` is missing, and when it runs in a browser.

<H2 id="usage" step={3}>Usage</H2>

There is no shared user state on a server. Pass the context with every call.

```typescript
const user = {
  userId: 'user-123',
  attributes: { plan: 'pro', country: 'IR' },
};

if (flags.isEnabled('new-checkout', user)) {
  // New checkout logic
}

const theme = flags.getString('theme', user, 'light');
const limit = flags.getNumber('upload-limit-mb', user, 10);
const dark = flags.getBoolean('dark-mode', user, false);
const banner = flags.getJson('banner', user, { text: '' });
```

Evaluation is local and synchronous: no network call per flag check.

#### Context

```typescript
interface EvaluationContext {
  userId?: string | null;      // the signed-in user's stable id
  anonymousId?: string | null; // for signed-out visitors, for example an id your client sends
  attributes?: Record<string, string | number | boolean | null | Array<string | number | boolean | null>>;
}
```

Percentage rollouts and variant splits use `userId`, or `anonymousId` when there is no user id. Without either, a partial rollout or a split is served off with reason `NO_BUCKETING_ID`. Rules on `userId` or `anonymousId` read these two fields, never an attribute of the same name.

#### Getters

<ConfigTable headers={['Method', 'Returns']} rows={[
  ['isEnabled(key, context?, defaultValue = false)', 'true when the flag is served on for this context'],
  ['getBoolean(key, context, defaultValue)', 'Value of a boolean flag, or the default'],
  ['getString(key, context, defaultValue)', 'Value of a string flag, or the default'],
  ['getNumber(key, context, defaultValue)', 'Value of a number flag, or the default'],
  ['getJson(key, context, defaultValue)', 'Value of a json flag, or the default'],
  ['getDetail(key, context, defaultValue, valueType?)', 'key, value, enabled, variant, reason, version and valueType'],
  ['getAll(context?)', 'Every flag evaluated for the context, by key'],
  ['getFlagKeys()', 'The keys of the loaded flags'],
]} />

#### Details and reasons

```typescript
const d = flags.getDetail('theme', user, 'light', 'string');
console.log(d.value, d.variant, d.reason); // "dark" "dark" "VARIANT"
```

Pass the fourth argument (`'boolean'`, `'string'`, `'number'` or `'json'`) to get your default and `TYPE_MISMATCH` when the flag has another type. Without it, `getDetail` returns the value as it is.

<ConfigTable headers={['Reason', 'Meaning']} rows={[
  ['ON', 'The flag is on and has no variants. The value is true'],
  ['VARIANT', 'The flag is on and a variant was served'],
  ['DISABLED', 'The flag is off in this environment. The flag off value is served'],
  ['NOT_TARGETED', 'The targeting rules did not match the context. The off value is served'],
  ['OUTSIDE_ROLLOUT', 'The user is outside the rollout percentage. The off value is served'],
  ['PREREQUISITE_FAILED', 'A flag this one depends on did not give the required result. The off value is served'],
  ['NO_BUCKETING_ID', 'A rollout or split needed a userId or anonymousId and the context has neither'],
  ['ERROR', 'The flag could not be evaluated. The off value is served'],
  ['FLAG_NOT_FOUND', 'No such flag. Your default is returned'],
  ['NOT_READY', 'Rules are not loaded yet. Your default is returned'],
  ['TYPE_MISMATCH', 'For example getString on a boolean flag. Your default is returned'],
]} />

`isEnabled` is `true` only for `ON` and `VARIANT`.

<H2 id="events" step={4}>Events</H2>

```typescript
const offReady = flags.on('ready', ({ flagCount }) => {
  console.log(`Loaded ${flagCount} flags`);
});

flags.on('update', ({ flagCount }) => {
  console.log(`Rules changed, ${flagCount} flags`);
});

flags.on('error', ({ status, code, message }) => {
  console.error(`Abrova Flags error ${status ?? ''} ${code ?? ''}: ${message}`);
});

// on() returns a function that removes the listener
offReady();
```

<H2 id="express-middleware" step={5}>Express Middleware</H2>

```typescript
import express from 'express';
import { AbrovaFlags } from '@abrova/flags-node';

const app = express();
const flags = new AbrovaFlags({
  apiKey: process.env.ABROVA_FLAGS_API_KEY!,
  serverSecret: process.env.ABROVA_FLAGS_SERVER_SECRET!,
  environment: 'production',
});

await flags.init();

// Pass the user context per request
app.get('/api/feature', (req, res) => {
  const enabled = flags.isEnabled('my-feature', {
    userId: req.user.id,
    attributes: { plan: req.user.plan },
  });

  res.json({ featureEnabled: enabled });
});

const server = app.listen(3000);

// Stop refreshing on shutdown
process.on('SIGTERM', async () => {
  await flags.close();
  server.close();
});
```

<H2 id="refresh-and-errors" step={6}>Refresh and errors</H2>

- **Automatic refresh:** the SDK checks for new rules every `pollIntervalSeconds` (30 by default). An unchanged answer costs almost nothing, so you do not need to call `refresh()` on a timer.
- **Failures:** a failed refresh keeps the last good rules. Rate limits (429) and server errors are retried with a growing delay (up to 5 minutes), following the wait time the service asks for.
- **401, 403 or 404** (wrong key or secret, a server address that is not on the secret's IP allow-list, unknown environment): refreshing stops and an `error` event fires. Fix the configuration, then call `flags.refresh()`, which also restarts the refresh.
- **`flags.refresh()`** fetches the rules now. **`flags.close()`** stops refreshing and sends pending usage counts.

<Callout kind="note" title="Not counted as evaluations">
Downloading rules and evaluating flags locally are not counted as evaluations. Set `sendUsage: true` if you want the evaluation charts in Abrova Console to include this server: the SDK then sends totals per flag about once a minute. They contain no user ids and are not billed.
</Callout>

<H2 id="environment-overrides" step={7}>Environment Overrides</H2>

Pass an `environment` in the config to get the flags with that environment's overrides applied.

```typescript
const flags = new AbrovaFlags({
  apiKey: process.env.ABROVA_FLAGS_API_KEY!,
  serverSecret: process.env.ABROVA_FLAGS_SERVER_SECRET!,
  environment: process.env.NODE_ENV === 'production'
    ? 'production'
    : 'development',
});

await flags.init();

const maintenance = flags.isEnabled('maintenance-mode', { userId: 'user-123' });
```

The environment key must exist in your project. An unknown key is answered with 404: the SDK logs an error and getters return your defaults.

### Configuration Options

<ConfigTable headers={['Option', 'Type', 'Default', 'Description']} rows={[
  ['apiKey', 'string', 'required', 'Your Abrova API key (ab_live_xxx)'],
  ['serverSecret', 'string', 'required', 'Your server secret (ab_srv_xxx)'],
  ['environment', 'string', 'none', 'Environment key (production, staging, development or your own). Leave out to use the Default values'],
  ['pollIntervalSeconds', 'number', '30', 'Seconds between rule refreshes. Minimum 10. 0 turns the refresh off'],
  ['initTimeoutMs', 'number', '5000', 'How long init() waits for the first download'],
  ['sendUsage', 'boolean', 'false', 'Send evaluation totals per flag for the charts in Abrova Console. Not billed, no user ids'],
  ['debug', 'boolean', 'false', 'Enable debug logging'],
  ['logger', 'object', 'console', 'Your own logger with debug, info, warn and error methods'],
]} />

### Upgrading from 0.1.x

Update the package and change these calls:

<ConfigTable headers={['0.1.x', '0.2.0']} rows={[
  ['isEnabled(key, { userId, userAttributes })', 'isEnabled(key, { userId, attributes })'],
  ['getValue(key, ctx, default)', 'getBoolean / getString / getNumber / getJson(key, ctx, default)'],
  ['evaluate(key, ctx)', 'getDetail(key, ctx, default), which adds reason and version'],
  ['getAll() returned raw flags', 'getAll(ctx) returns evaluated results; getFlagKeys() lists the keys'],
  ['init(callback)', "init(), plus on('ready' | 'update' | 'error', fn)"],
  ['dispose() / reset()', 'close()'],
  ['refresh() on your own timer', 'Not needed. Rules refresh every 30 seconds'],
]} />

- Rename `userAttributes` to `attributes` everywhere. A context that still uses `userAttributes` is evaluated without attributes.
- Flag dependencies and segments are now evaluated by the SDK, so results match the service.
- Rollouts use a new bucketing method, so users are assigned to rollouts and variants again once.

### Best Practices

<BestPracticeList items={[
  ['Never expose server secret', 'Keep the server secret in environment variables. Never commit it to version control or expose it in client code'],
  ['Initialize once', 'Create a single AbrovaFlags instance and reuse it across your application'],
  ['Pass user context per request', 'Always pass userId (or anonymousId) and attributes in each call for accurate targeting and rollout'],
  ['Always give a sensible default', 'The default is what your users get before the rules are loaded and when a flag is removed'],
  ['Close on shutdown', 'Call close() when the process stops so the refresh timer ends and usage counts are sent'],
]} />

- Next.js: https://abrova.ir/en/docs/flags/nextjs

<BestPracticeList columns={2} items={[
  ['Server Entry', 'AbrovaFlags with the server secret, for Server Components, Route Handlers, Server Actions and middleware'],
  ['Client Entry', 'AbrovaFlagsProvider and useAbrovaFlags with the public key, for Client Components'],
  ['Standalone Client', 'AbrovaFlagsClient for browser code without React'],
  ['Rules Stay on the Server', 'The browser receives values for this user. Targeting rules never reach it'],
  ['Typed Getters', 'getBoolean, getString, getNumber and getJson, each with a default'],
  ['TypeScript', 'Full type definitions included'],
]} />

<Callout kind="note" title="Abrova Flags Next.js SDK v0.2.0">
This page describes `@abrova/flags-nextjs` 0.2.0. It is a breaking release: the server SDK moved to `@abrova/flags-nextjs/server`, the browser no longer downloads rules, and typed getters replace `getValue`. Coming from 0.1.x? See **Upgrading from 0.1.x** at the end of this page.
</Callout>

<Callout kind="note" title="Requirements">
Node.js 18 or newer. React 18 or newer for the provider and the hook.
</Callout>

<H2 id="installation" step={1}>Installation</H2>

```bash
# 1. .npmrc in your project root: @abrova packages come from Abrova Center
@abrova:registry=https://center.abrova.ir/api/packages/abrova/npm/
```

```bash
# 2. Install
npm install @abrova/flags-nextjs
# or
yarn add @abrova/flags-nextjs
```

<H2 id="two-entry-points" step={2}>Two entry points</H2>

<ClientServerComparison
  left={{
    title: '@abrova/flags-nextjs/server',
    subtitle: 'Server Components, Route Handlers, Server Actions, middleware',
    accent: 'blue',
    bullets: [
      'API key and server secret',
      'Downloads the rules and evaluates locally',
      'You pass the user context with every call',
      'Not counted as evaluations',
    ],
  }}
  right={{
    title: '@abrova/flags-nextjs/client',
    subtitle: 'Client Components and other browser code',
    accent: 'emerald',
    bullets: [
      'Public API key only',
      'Abrova Flags evaluates; the browser gets values',
      'The client remembers the user you identify',
      'Each fetch counts as one evaluation',
    ],
  }}
/>

The package root (`@abrova/flags-nextjs`) is the same as `/client`. The server SDK is only in `/server`, so it cannot end up in a browser bundle, and it refuses to start in a browser.

<H2 id="server-side-app-router" step={3}>Server-Side (App Router)</H2>

<Callout kind="note" title="Server-Side Requires Server Secret">
Server-side usage requires both `apiKey` and `serverSecret`. The server secret can read every targeting rule of your project. Never expose it in client-side code or in an environment variable prefixed with `NEXT_PUBLIC_`.
</Callout>

Create one instance per process, in its own module:

```typescript
// lib/flags.ts
import { AbrovaFlags } from '@abrova/flags-nextjs/server';

export const flags = new AbrovaFlags({
  apiKey: process.env.ABROVA_FLAGS_API_KEY!,
  serverSecret: process.env.ABROVA_FLAGS_SERVER_SECRET!,
  environment: 'production', // leave out to use the Default values
});
```

```tsx
// app/page.tsx (Server Component)
import { flags } from '@/lib/flags';

export default async function Page() {
  await flags.init(); // the first call downloads the rules, later calls return at once

  const user = { userId: 'user-123', attributes: { plan: 'pro', country: 'IR' } };

  const newCheckout = flags.isEnabled('new-checkout', user);
  const theme = flags.getString('theme', user, 'light');

  return (
    <main data-theme={theme}>
      {newCheckout ? <NewCheckout /> : <OldCheckout />}
    </main>
  );
}
```

The context is passed with every call: `userId`, `anonymousId` and `attributes`, all optional. Percentage rollouts and variant splits use `userId`, or `anonymousId` when there is no user id.

<ConfigTable headers={['Method', 'Returns']} rows={[
  ['init()', 'Downloads the rules and starts refreshing them every 30 seconds. Resolves after the first download or after initTimeoutMs (5 seconds). Never rejects'],
  ['isEnabled(key, context?, defaultValue = false)', 'true when the flag is served on for this context'],
  ['getBoolean / getString / getNumber / getJson(key, context, defaultValue)', 'The typed value, or the default'],
  ['getDetail(key, context, defaultValue, valueType?)', 'key, value, enabled, variant, reason, version and valueType'],
  ['getAll(context?)', 'Every flag evaluated for the context, by key'],
  ['getFlagKeys()', 'The keys of the loaded flags'],
  ['refresh()', 'Fetch the rules now'],
  ['close()', 'Stop refreshing'],
  ["on('ready' | 'update' | 'error', fn)", 'Listen for events. Returns a function that removes the listener'],
]} />

The server entry behaves like the [Node.js SDK](/docs/flags/nodejs): the same options (`pollIntervalSeconds`, `initTimeoutMs`, `sendUsage`, `debug`, `logger`), the same reasons and the same error handling. It also runs in the Edge runtime.

<H2 id="client-side-react-hook" step={4}>Client-Side (React Hook)</H2>

<Callout kind="note" title="Client-Safe">
The client entry uses the public API key only. `AbrovaFlagsClient` throws if you pass a server secret.
</Callout>

```tsx
// app/providers.tsx
'use client';

import { AbrovaFlagsProvider } from '@abrova/flags-nextjs/client';

export function Providers({ children }: { children: React.ReactNode }) {
  return (
    <AbrovaFlagsProvider config={{
      apiKey: process.env.NEXT_PUBLIC_ABROVA_FLAGS_API_KEY!,
      environment: 'production', // leave out to use the Default values
    }}>
      {children}
    </AbrovaFlagsProvider>
  );
}
```

#### Using the Hook

```tsx
// components/Checkout.tsx
'use client';

import { useEffect } from 'react';
import { useAbrovaFlags } from '@abrova/flags-nextjs/client';

export function Checkout({ userId, plan }: { userId: string | null; plan: string }) {
  const { isReady, isEnabled, getString, identify } = useAbrovaFlags();

  useEffect(() => {
    identify(userId, { plan }); // null means signed out
  }, [identify, userId, plan]);

  if (!isReady) return <Skeleton />;

  return isEnabled('new-checkout')
    ? <NewCheckout theme={getString('theme', 'light')} />
    : <OldCheckout />;
}
```

The hook returns `client`, `isReady`, the getters (`isEnabled`, `getBoolean`, `getString`, `getNumber`, `getJson`, `getDetail`, `getAll`) and the actions (`identify`, `setUserId`, `setAttributes`, `reset`, `resetAnonymousId`, `refresh`). The functions keep the same identity between renders, so they are safe in effect dependency lists. Components re-render when the values change.

Call `identify` in an effect, not in the component body.

<H2 id="standalone-client-no-react" step={5}>Standalone Client (No React)</H2>

For browser code outside React, use `AbrovaFlagsClient` directly.

```typescript
import { AbrovaFlagsClient } from '@abrova/flags-nextjs/client';

const client = new AbrovaFlagsClient({
  apiKey: 'ab_live_xxx',
  environment: 'production',
  userId: 'user-123',
  attributes: { plan: 'pro' },
});

await client.init();

const enabled = client.isEnabled('new-checkout');
const theme = client.getString('theme', 'light');
const detail = client.getDetail('theme', 'light', 'string');
// { key, value, enabled, variant, reason, version, valueType }

// Sign-out: clears the user, the attributes and the cached values
await client.reset();

// Stop timers and network work
client.close();
```

<ConfigTable headers={['Method', 'What it does']} rows={[
  ['init()', 'Serves cached values and fetches fresh ones. Resolves after the first answer or after initTimeoutMs (5 seconds)'],
  ['isReady()', 'true when values for the current user are available'],
  ['isEnabled(key, defaultValue = false)', 'true when the flag is served on for this user'],
  ['getBoolean / getString / getNumber / getJson(key, defaultValue)', 'The typed value, or the default'],
  ['getDetail(key, defaultValue, valueType?)', 'The full result with the reason'],
  ['getAll()', 'Every value for the current user, by key'],
  ['identify(userId | null, attributes?)', 'Sets the user and, when given, replaces the attributes. Fetches new values'],
  ['setUserId(userId | null)', 'Changes the user id only'],
  ['setAttributes(attributes)', 'Replaces the whole set of attributes'],
  ['reset()', 'Sign-out: clears the user, the attributes and the cached values. Keeps the anonymous id'],
  ['resetAnonymousId()', 'Creates a new anonymous id'],
  ['refresh()', 'Fetch now'],
  ["on('ready' | 'change' | 'error', fn)", 'Listen for events. Returns a function that removes the listener'],
  ['getUserId() / getAttributes() / getAnonymousId()', 'The current context'],
  ['close()', 'Stops timers and network work'],
]} />

<H2 id="how-the-client-behaves" step={6}>How the client behaves</H2>

- **Context changes** fetch new values after a short pause (250 ms). A call that changes nothing sends no request. `setAttributes` and the attributes of `identify` replace the whole set; they do not merge.
- **User change:** the previous user's values are dropped at once. Until the new values arrive, `isReady` is `false` and getters return your defaults.
- **Anonymous id:** each browser gets a random id (a UUID), kept in `localStorage` and sent with every request, so percentage rollouts work for signed-out visitors too. If storage is blocked, the id lives in memory for the page.
- **Cache:** the last values are kept in `localStorage` and served at the next visit, before the network answers. Offline or on errors, the last values keep being served.
- **Refresh:** on `init`, on context changes, when the tab becomes visible and the last fetch is older than 15 minutes, and on `refresh()`. Polling is off unless you set `refreshIntervalSeconds` (minimum 60).
- **Errors:** rate limits (429) and server errors are retried with a growing delay (up to 5 minutes). 401, 403 and 404 (wrong key, Flags not enabled, unknown environment) stop automatic fetches until `refresh()`.
- **Attributes** are strings, numbers, booleans, null, or arrays of those. No nested objects. At most 100 attributes; a string holds at most 1,024 characters.

<Callout kind="note" title="Each fetch counts as one evaluation">
Every request the client entry sends for values is counted as one flag evaluation, whatever the number of flags it returns (100,000 evaluations are free every month; the price above that is set at launch). This is why polling is off by default. Rule downloads and local evaluations of the server entry are not counted.
</Callout>

Client options: `apiKey`, `environment`, `userId`, `attributes`, `flagKeys`, `refreshIntervalSeconds`, `initTimeoutMs`, `storage`, `debug` and `logger`.

<H2 id="server-rendering-and-hydration" step={7}>Server rendering and hydration</H2>

The client entry has no values while a page is rendered on the server: `isReady` is `false` and every getter returns the default you pass. In the browser, cached values from an earlier visit are available from the first render. The HTML from the server and the first render in the browser can therefore differ.

<BestPracticeList items={[
  ['Decide on the server when you can', 'Evaluate the flag in a Server Component with the server entry and pass the result down as a prop. There is no flicker and no extra request from the browser'],
  ['Otherwise render after mount', 'For flags read in Client Components, render the flag-dependent part only after the component has mounted and isReady is true. Show a skeleton or the default until then'],
  ['Use one id on both sides', 'For a signed-in user, pass the same userId on the server and to identify() in the browser. Both sides then give the same rollout and variant'],
  ['Signed-out visitors', 'The browser uses its own anonymous id, which the server does not know. For a signed-out visitor, decide a rollout flag in one place: on the server with an id you keep in a cookie, or in the browser'],
]} />

```tsx
'use client';

import { useEffect, useState } from 'react';
import { useAbrovaFlags } from '@abrova/flags-nextjs/client';

export function PromoBanner() {
  const { isReady, isEnabled } = useAbrovaFlags();
  const [mounted, setMounted] = useState(false);

  useEffect(() => setMounted(true), []);

  if (!mounted || !isReady) return null;
  return isEnabled('promo-banner') ? <Banner /> : null;
}
```

<H2 id="environment-variables" step={8}>Environment Variables</H2>

```bash
# .env.local

# Server-side only (NEVER expose these to the client)
ABROVA_FLAGS_API_KEY=ab_live_xxx
ABROVA_FLAGS_SERVER_SECRET=ab_srv_xxx

# For client-side usage (safe to expose)
NEXT_PUBLIC_ABROVA_FLAGS_API_KEY=ab_live_xxx
# Note: Do NOT create NEXT_PUBLIC_ABROVA_FLAGS_SERVER_SECRET
```

<Callout kind="note" title="Important">
Never prefix your server secret with `NEXT_PUBLIC_`. Only the API key should be exposed to the client.
</Callout>

### Upgrading from 0.1.x

Update the package and change these imports and calls:

<ConfigTable headers={['0.1.x', '0.2.0']} rows={[
  ["import { AbrovaFlags } from '@abrova/flags-nextjs'", "import { AbrovaFlags } from '@abrova/flags-nextjs/server'"],
  ["AbrovaFlagsProvider, useAbrovaFlags, AbrovaFlagsClient from '@abrova/flags-nextjs'", "Same names from '@abrova/flags-nextjs/client'. The package root still works"],
  ['Server: isEnabled(key, { userId, userAttributes })', 'isEnabled(key, { userId, attributes })'],
  ['getValue(key, ..., default)', 'getBoolean / getString / getNumber / getJson'],
  ['evaluate(key, ...)', 'getDetail(key, ..., default), with reason and version'],
  ['Client: setUserId + setUserAttributes', 'identify(userId, attributes), setUserId, setAttributes. They return a Promise and fetch new values'],
  ['Client: getAll() returned flags with rules', 'getAll() returns this user\'s values only'],
  ['isLoading from the hook', 'isReady'],
  ['dispose()', 'close()'],
]} />

- **Upgrade browser and server together:** in 0.2.0 Abrova Flags evaluates for the browser, and a 0.1.x client entry stops receiving flags.
- The root import no longer exports the server SDK. Importing `AbrovaFlags` from `@abrova/flags-nextjs` no longer works: change it to `@abrova/flags-nextjs/server`.
- On the server, rename `userAttributes` to `attributes`. A context that still uses `userAttributes` is evaluated without attributes.
- Rollouts use a new bucketing method, so users are assigned to rollouts and variants again once.

### Best Practices

<BestPracticeList items={[
  ['Separate server and client keys', 'Use ABROVA_FLAGS_API_KEY and ABROVA_FLAGS_SERVER_SECRET on the server and NEXT_PUBLIC_ABROVA_FLAGS_API_KEY in client components'],
  ['One server instance', 'Create the server AbrovaFlags once in a module and await flags.init() where you read flags. Later calls return at once'],
  ['Use the Provider pattern', 'Wrap your app with AbrovaFlagsProvider for consistent client-side flag access'],
  ['Handle the not-ready state', 'Use isReady from the hook to show a skeleton until values are available'],
  ['Prefer the server for first paint', 'Flags that change what the page looks like on load are best decided in a Server Component'],
]} />

- React Native: https://abrova.ir/en/docs/flags/react-native

<BestPracticeList columns={2} items={[
  ['Client-Safe', 'Uses the public API key only. No server secret needed'],
  ['Evaluated by the Service', 'The app receives values for this user. Targeting rules never reach the device'],
  ['React Hooks', 'useAbrovaFlags and one hook per flag type. Components re-render when values change'],
  ['Typed Getters', 'getBoolean, getString, getNumber and getJson, each with a default'],
  ['Offline Cache', 'The last values are stored with AsyncStorage and served at start and offline'],
  ['Anonymous Id', 'Percentage rollouts also work before sign-in'],
]} />

<Callout kind="note" title="Abrova Flags React Native SDK v0.2.0">
This page describes `@abrova/flags-react-native` 0.2.0. It is a breaking release: flags are evaluated by the service instead of on the device, and the getters changed. Coming from 0.1.x? See **Upgrading from 0.1.x** at the end of this page.
</Callout>

<Callout kind="note" title="Requirements">
React 18 or higher. React Native 0.70 or higher.
</Callout>

<H2 id="installation" step={1}>Installation</H2>

```bash
# 1. .npmrc in your project root: @abrova packages come from Abrova Center
@abrova:registry=https://center.abrova.ir/api/packages/abrova/npm/
```

```bash
# 2. Install
npm install @abrova/flags-react-native @react-native-async-storage/async-storage
cd ios && pod install
```

`@react-native-async-storage/async-storage` stores the anonymous id and the last values. Without it the SDK still works, but keeps them in memory only and logs a warning.

<H2 id="provider-and-hooks" step={2}>Provider and hooks</H2>

Wrap your app in `AbrovaFlagsProvider`. It creates the client, initialises it and closes it when the provider unmounts. Use your public API key (`ab_live_...`).

```tsx
import React from 'react';
import { AbrovaFlagsProvider } from '@abrova/flags-react-native';

export default function App() {
  return (
    <AbrovaFlagsProvider config={{ apiKey: 'ab_live_xxx', environment: 'production' }}>
      <Checkout />
    </AbrovaFlagsProvider>
  );
}
```

Read flags with the hooks. A component that uses a hook re-renders when the values change.

```tsx
import { useAbrovaFlags, useStringFlag } from '@abrova/flags-react-native';

function Checkout() {
  const { isReady, isEnabled, getNumber } = useAbrovaFlags();
  const theme = useStringFlag('theme', 'light');

  if (!isReady) return <Loading />;

  return isEnabled('new-checkout')
    ? <NewCheckout theme={theme} maxItems={getNumber('max-items', 10)} />
    : <OldCheckout />;
}
```

<ConfigTable headers={['Hook', 'Returns']} rows={[
  ['useAbrovaFlags()', 'client, isReady, anonymousId, userId, the getters, identify, setUserId, setAttributes, reset, resetAnonymousId and refresh'],
  ['useFlagEnabled(key, defaultValue = false)', 'true when the flag is served on for this user'],
  ['useBooleanFlag(key, defaultValue)', 'Value of a boolean flag'],
  ['useStringFlag(key, defaultValue)', 'Value of a string flag'],
  ['useNumberFlag(key, defaultValue)', 'Value of a number flag'],
  ['useJsonFlag(key, defaultValue)', 'Value of a json flag'],
  ['useFlagDetail(key, defaultValue)', 'value, enabled, variant, reason and version of one flag'],
]} />

The functions returned by `useAbrovaFlags()` are bound to the client, so you can destructure them. If you created the client yourself, pass it with `client` instead of `config`; the provider then leaves `init()` and `close()` to you.

<H2 id="direct-usage" step={3}>Direct Usage</H2>

You can use the client without React.

```typescript
import { AbrovaFlags } from '@abrova/flags-react-native';

const flags = new AbrovaFlags({ apiKey: 'ab_live_xxx', environment: 'production' });
await flags.init();

if (flags.isEnabled('new-checkout')) {
  // Show the new checkout
}

const dark = flags.getBoolean('dark-mode', false);
const theme = flags.getString('theme', 'light');
const maxItems = flags.getNumber('max-items', 10);
const layout = flags.getJson('home-layout', { columns: 2 });
```

`init()` serves the values cached on the device right away and waits up to `initTimeoutMs` (5 seconds) for the first answer from the network. After `init()`, the client is also available as `AbrovaFlags.instance`.

Getters are synchronous and never throw. Each one takes the default to use when the flag is unknown, when no values are available yet, or when the flag has another type.

<Callout kind="note" title="Never use the server secret in an app">
The constructor throws if `apiKey` is a server secret (`ab_srv_...`). The server secret belongs on your backend, with the [Node.js](/docs/flags/nodejs) or [Next.js](/docs/flags/nextjs) server SDK.
</Callout>

#### Details and reasons

```typescript
const d = flags.getStringDetail('theme', 'light');
// { value, enabled, variant, reason, version }
```

`getBooleanDetail`, `getStringDetail`, `getNumberDetail` and `getJsonDetail` check the flag type. `getDetail(key, defaultValue)` returns the stored value without a type check, and `getAll()` returns every value held.

<ConfigTable headers={['Reason', 'Meaning']} rows={[
  ['ON', 'The flag is on and has no variants. The value is true'],
  ['VARIANT', 'The flag is on and a variant was served'],
  ['DISABLED', 'The flag is off in this environment. The flag off value is served'],
  ['NOT_TARGETED', 'The targeting rules did not match this user. The off value is served'],
  ['OUTSIDE_ROLLOUT', 'The user is outside the rollout percentage. The off value is served'],
  ['PREREQUISITE_FAILED', 'A flag this one depends on did not give the required result. The off value is served'],
  ['NO_BUCKETING_ID', 'A rollout or split needed a user id or anonymous id and none was sent'],
  ['ERROR', 'The flag could not be evaluated. The off value is served'],
  ['FLAG_NOT_FOUND', 'No such flag. Your default is returned'],
  ['NOT_READY', 'No cached or fetched values yet. Your default is returned'],
  ['TYPE_MISMATCH', 'For example getString on a boolean flag. Your default is returned'],
]} />

`isEnabled` is `true` only for `ON` and `VARIANT`.

<H2 id="identify-the-user" step={4}>Identify the user</H2>

Tell the SDK who the user is and what you know about them. Targeting rules and percentage rollouts are evaluated against this context.

```typescript
// After sign-in
await flags.identify('user-123', { plan: 'pro', country: 'IR', beta: true });

// Replace all attributes
await flags.setAttributes({ plan: 'business' });

// Signed out, attributes stay
await flags.setUserId(null);

// Sign-out: clears the user id, the attributes and the cached values
await flags.reset();
```

In a component, call `identify` in an effect so it runs only when the user changes. Use `client` from the hook in the dependency list: it stays the same between renders, while the functions returned by the hook are created again when values change.

```tsx
import { useEffect } from 'react';
import { useAbrovaFlags } from '@abrova/flags-react-native';

function Session({ userId, plan }: { userId: string | null; plan: string }) {
  const { client } = useAbrovaFlags();

  useEffect(() => {
    client.identify(userId, { plan }); // null means signed out
  }, [client, userId, plan]);

  return null;
}
```

- Each change fetches new values after a short pause (250 ms), so several calls in a row send one request.
- `setAttributes` and the attributes of `identify` **replace** the whole set. They do not merge.
- When the user id changes, the previous user's values are dropped at once. Until the new values arrive, getters return your defaults (reason `NOT_READY`).
- Attributes are strings, numbers, booleans, null, or arrays of those. No nested objects. At most 100 attributes; a string holds at most 1,024 characters.

If you already know the user at start, pass `userId` and `attributes` in the config. The SDK then serves that user's cached values immediately and sends one request instead of two.

#### Anonymous id

Every install gets a random anonymous id (a UUID). It is stored on the device and sent with every request, so a 10% rollout reaches about 10% of signed-out installs too. When a user id is set, rollouts use the user id instead.

The anonymous id survives `reset()`. `resetAnonymousId()` replaces it. Read it with `flags.anonymousId`.

<H2 id="updates-and-refresh" step={5}>Updates and refresh</H2>

```typescript
// New values arrived
const unsubscribe = flags.subscribe(() => console.log('flags changed'));

// A request failed
const off = flags.onError((e) => console.log(e.statusCode, e.code, e.message));

// Fetch now
await flags.refresh();
```

The SDK fetches values:

- on `init()`,
- after `identify`, `setUserId`, `setAttributes`, `reset` and `resetAnonymousId`,
- when the app returns to the foreground and the last fetch is older than 15 minutes,
- on `refresh()`,
- on a timer, only if you set `refreshIntervalSeconds`.

<Callout kind="note" title="Each fetch counts as one evaluation">
Every request for values is counted as one flag evaluation, whatever the number of flags it returns (100,000 evaluations are free every month; the price above that is set at launch). This is why polling is off by default. `identify`, `setUserId` and `setAttributes` send a request every time you call them, also when nothing changed, so call them in an effect with dependencies, not on every render.
</Callout>

<H2 id="offline-and-errors" step={6}>Offline and errors</H2>

The last values are stored with AsyncStorage and served at the next start, before the network answers. A failed request never clears them.

- **Offline or server error:** the last values keep being served. The SDK retries with a growing delay (up to 5 minutes).
- **Rate limited (429):** the SDK waits the time the service asks for, then retries.
- **401, 403 or 404** (wrong key, Flags not enabled for the project, unknown environment): automatic fetches stop until you call `refresh()` or restart the app. Check `flags.lastError`.
- **Before the first values:** `flags.isReady` is `false` and getters return your defaults. `await flags.whenReady()` resolves when values are available.

`flags.close()` stops timers and network work.

### Configuration Options

<ConfigTable headers={['Option', 'Type', 'Default', 'Description']} rows={[
  ['apiKey', 'string', 'required', 'Your public API key (ab_live_xxx)'],
  ['environment', 'string', 'none', 'Environment key (production, staging, development or your own). Leave out to use the Default values'],
  ['userId', 'string | null', 'null', 'Signed-in user id at start'],
  ['attributes', 'object', '{}', 'Targeting attributes at start'],
  ['flagKeys', 'string[]', 'all flags', 'Only fetch these flags'],
  ['refreshIntervalSeconds', 'number', '0', 'Polling while the app is in the foreground. 0 is off; otherwise at least 60'],
  ['initTimeoutMs', 'number', '5000', 'How long init() waits for the first answer'],
  ['observeAppState', 'boolean', 'true', 'Refresh when the app returns to the foreground'],
  ['storage', 'FlagsStorage', 'AsyncStorage', 'Where the anonymous id and the last values are kept'],
  ['debug', 'boolean', 'false', 'Verbose logs. Errors are always logged'],
]} />

### Testing

Pass an in-memory store, your own `fetch` and `observeAppState: false`:

```typescript
import { AbrovaFlags, MemoryFlagsStorage } from '@abrova/flags-react-native';

const flags = new AbrovaFlags({
  apiKey: 'ab_live_xxx',
  storage: new MemoryFlagsStorage(),
  fetch: mockFetch,
  observeAppState: false,
});
```

### Upgrading from 0.1.x

0.2.0 is a new API, and 0.1.x clients stop receiving flags. Update the package and change these calls:

<ConfigTable headers={['0.1.x', '0.2.0']} rows={[
  ["getValue('k', x)", "getBoolean / getString / getNumber / getJson('k', x)"],
  ["evaluate('k')", "getDetail('k', x), which adds reason and version"],
  ['setUserId(id) + setUserAttributes(map), merged', 'identify(id, attributes), setUserId, setAttributes. Attributes are replaced'],
  ['getAll() returned flag configurations with rules', 'getAll() returns this user\'s values only'],
  ['init(callback)', 'init(), plus subscribe() and onError()'],
  ['isLoading from the hook', 'isReady'],
  ['enableOfflineCache, dispose()', 'Always cached; close()'],
  ['@react-native-community/netinfo peer dependency', 'Not needed. You can remove it if nothing else uses it'],
]} />

Rollouts use a new bucketing method, so users are assigned to rollouts and variants again once.

### Best Practices

<BestPracticeList items={[
  ['Use the Provider', 'Wrap your app with AbrovaFlagsProvider so every component reads the same client'],
  ['Identify in an effect', 'Call identify when the user or the attributes change, not on every render'],
  ['Always give a sensible default', 'The default is what your users see before the first values and when a flag is removed'],
  ['Reset on sign-out', 'Call reset() so the next user never sees the previous user\'s values'],
  ['Leave polling off', 'Values refresh on start, on context changes and on app resume. Turn polling on only if you need faster updates'],
]} />

- Android: https://abrova.ir/en/docs/flags/android

<BestPracticeList columns={2} items={[
  ['Client-Safe', 'Uses the public API key only. Safe to ship in an app'],
  ['Evaluated by the Service', 'The app receives values for this user. Targeting rules never reach the device'],
  ['Typed Getters', 'getBoolean, getString, getNumber and getJson, each with a default'],
  ['Offline Cache', 'The last values are stored in SharedPreferences and served at start and offline'],
  ['Anonymous Id', 'Percentage rollouts also work before sign-in'],
  ['Never Blocks', 'Getters return at once and never throw. Network work runs off the main thread'],
]} />

<Callout kind="note" title="Abrova Flags Android SDK v0.2.0">
This page describes `ir.abrova:abrova-flags-android` 0.2.0. It is a breaking release: flags are evaluated by the service instead of on the device, and the getters changed. Coming from 0.1.x? See **Upgrading from 0.1.x** at the end of this page.
</Callout>

<Callout kind="note" title="Requirements">
Android min SDK 21. The `INTERNET` permission is merged from the library manifest.
</Callout>

<H2 id="installation" step={1}>Installation</H2>

Install from Abrova Center in two steps.

1. Add the Abrova Center repository in `settings.gradle` (or the project `build.gradle`):

```groovy
repositories {
    google()
    mavenCentral()
    maven { url "https://center.abrova.ir/api/packages/abrova/maven" }
}
```

Kotlin DSL: `maven { url = uri("https://center.abrova.ir/api/packages/abrova/maven") }`

2. Add the dependency to your app's `build.gradle.kts`:

```kotlin
dependencies {
    implementation("ir.abrova:abrova-flags-android:0.2.0")
}
```

Groovy:

```groovy
implementation 'ir.abrova:abrova-flags-android:0.2.0'
```

<H2 id="initialization" step={2}>Initialization</H2>

Create one client for the app, for example in `Application.onCreate`, and call `start()`. Use your public API key (`ab_live_...`).

```kotlin
import android.app.Application
import ir.abrova.flags.AbrovaFlags
import ir.abrova.flags.AbrovaFlagsConfig

class MyApp : Application() {
    lateinit var flags: AbrovaFlags
        private set

    override fun onCreate() {
        super.onCreate()
        flags = AbrovaFlags(
            applicationContext,
            AbrovaFlagsConfig(
                apiKey = "ab_live_xxx",
                environment = "production", // null uses the Default values
            ),
        )
        flags.start()
    }
}
```

`start()` returns immediately. It serves the values cached on the device and fetches fresh ones in the background. There is no shared instance in 0.2.0: keep the client you created.

To wait for the first values, for example on a splash screen:

```kotlin
lifecycleScope.launch {
    val ready = flags.awaitReady(timeoutMs = 3_000) // false when the time ran out
}
```

<Callout kind="note" title="Never use the server secret in an app">
The constructor throws an `IllegalArgumentException` if `apiKey` is a server secret (`ab_srv_...`). The server secret belongs on your backend, with the [Node.js](/docs/flags/nodejs) or [Next.js](/docs/flags/nextjs) server SDK.
</Callout>

<H2 id="read-flags" step={3}>Read flags</H2>

Getters never block and never throw. Each one takes the default to use when the flag is unknown, when no values are available yet, or when the flag has another type.

```kotlin
if (flags.isEnabled("new-checkout")) {
    // Show the new checkout
}

val dark = flags.getBoolean("dark-mode", false)
val theme = flags.getString("theme", "light")
val maxItems = flags.getNumber("max-items", 10.0)
val layout = flags.getJson("home-layout", mapOf("columns" to 2.0))
```

<ConfigTable headers={['Method', 'Returns']} rows={[
  ['isEnabled(key, defaultValue = false)', 'true when the flag is served on for this user'],
  ['getBoolean(key, defaultValue)', 'Value of a boolean flag'],
  ['getString(key, defaultValue)', 'Value of a string flag'],
  ['getNumber(key, defaultValue)', 'Value of a number flag, as Double'],
  ['getJson(key, defaultValue)', 'Value of a json flag: Map, List, String, Double, Boolean or null'],
  ['getAll()', 'Every value held, as Map<String, FlagResult>'],
]} />

#### Details and reasons

```kotlin
val d = flags.getStringDetail("theme", "light")
Log.d("flags", "${d.value} ${d.enabled} ${d.variant} ${d.reason} ${d.version}")
```

`getBooleanDetail`, `getStringDetail`, `getNumberDetail` and `getJsonDetail` check the flag type and return a `FlagDetail`. `getDetail(key, defaultValue = null)` returns the stored value without a type check.

<ConfigTable headers={['Reason', 'Meaning']} rows={[
  ['ON', 'The flag is on and has no variants. The value is true'],
  ['VARIANT', 'The flag is on and a variant was served'],
  ['DISABLED', 'The flag is off in this environment. The flag off value is served'],
  ['NOT_TARGETED', 'The targeting rules did not match this user. The off value is served'],
  ['OUTSIDE_ROLLOUT', 'The user is outside the rollout percentage. The off value is served'],
  ['PREREQUISITE_FAILED', 'A flag this one depends on did not give the required result. The off value is served'],
  ['NO_BUCKETING_ID', 'A rollout or split needed a user id or anonymous id and none was sent'],
  ['ERROR', 'The flag could not be evaluated. The off value is served'],
  ['FLAG_NOT_FOUND', 'No such flag. Your default is returned'],
  ['NOT_READY', 'No cached or fetched values yet. Your default is returned'],
  ['TYPE_MISMATCH', 'For example getString on a boolean flag. Your default is returned'],
]} />

Compare with the constants on `FlagReason`, for example `d.reason == FlagReason.NOT_READY`. `isEnabled` is `true` only for `ON` and `VARIANT`.

<H2 id="identify-the-user" step={4}>Identify the user</H2>

Tell the SDK who the user is and what you know about them. Targeting rules and percentage rollouts are evaluated against this context.

```kotlin
// After sign-in
flags.identify("user-123", mapOf("plan" to "pro", "country" to "IR", "beta" to true, "age" to 31))

// Replace all attributes
flags.setAttributes(mapOf("plan" to "business"))

// Signed out, attributes stay
flags.setUserId(null)

// Sign-out: clears the user id, the attributes and the cached values
flags.reset()
```

- Each change fetches new values after a short pause (250 ms), so several calls in a row send one request. A call that changes nothing sends no request.
- `setAttributes` and the attributes of `identify` **replace** the whole set. They do not merge.
- When the user id changes, the previous user's values are dropped at once. Until the new values arrive, getters return your defaults (reason `NOT_READY`).
- Attributes are a String (at most 1,024 characters), a Number, a Boolean, null, or a list of those. At most 100 attributes. Anything else is dropped with a log warning.
- The user id and attributes are remembered on the device, so after a restart the client starts with the same user. Call `reset()` on sign-out.

If you call `identify` before `start()`, the first request already carries the user.

#### Anonymous id

Every install gets a random anonymous id (a UUID). It is stored on the device and sent with every request, so a 10% rollout reaches about 10% of signed-out installs too. When a user id is set, rollouts use the user id instead.

The anonymous id survives `reset()`. `flags.resetAnonymousId()` creates a new one. Read it with `flags.anonymousId`.

<H2 id="events" step={5}>Events</H2>

```kotlin
import ir.abrova.flags.AbrovaFlagsError
import ir.abrova.flags.AbrovaFlagsListener

val listener = object : AbrovaFlagsListener {
    override fun onReady() {
        // First values are available (from the cache or the network). Fires once
    }

    override fun onUpdate(changedKeys: Set<String>) {
        // Values changed after a fetch
    }

    override fun onError(error: AbrovaFlagsError) {
        Log.w("flags", "${error.kind} ${error.statusCode} ${error.code} ${error.message}")
    }
}

flags.addListener(listener)
// later
flags.removeListener(listener)
```

All three methods are optional. Callbacks run on the main thread.

<H2 id="activity-example" step={6}>Activity Example</H2>

```kotlin
class CheckoutActivity : AppCompatActivity(), AbrovaFlagsListener {
    private val flags get() = (application as MyApp).flags

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        flags.addListener(this)
        render()
    }

    override fun onUpdate(changedKeys: Set<String>) {
        if ("new-checkout" in changedKeys) render()
    }

    override fun onDestroy() {
        flags.removeListener(this)
        super.onDestroy()
    }

    private fun render() {
        if (flags.isEnabled("new-checkout")) {
            setContentView(R.layout.activity_checkout_new)
        } else {
            setContentView(R.layout.activity_checkout)
        }
    }
}
```

<H2 id="refresh-offline-and-errors" step={7}>Refresh, offline and errors</H2>

The SDK fetches values:

- on `start()`,
- after a change of user or attributes, `reset()` and `resetAnonymousId()`,
- when the app returns to the foreground and the values are older than 15 minutes,
- on `refresh()`,
- on a timer, only if you set `refreshIntervalSeconds`.

```kotlin
// In a coroutine: true when the values are current
val ok = flags.refresh()

// With a callback on the main thread
flags.refresh { ok -> /* ... */ }
```

<Callout kind="note" title="Each fetch counts as one evaluation">
Every request for values is counted as one flag evaluation, whatever the number of flags it returns (100,000 evaluations are free every month; the price above that is set at launch). This is why polling is off by default.
</Callout>

The last values are stored in `SharedPreferences` (never the API key) and served at the next start, before the network answers. A failed request never clears them.

- **Offline or server error:** the last values keep being served. The SDK retries with a growing delay (up to 5 minutes).
- **Rate limited (429):** the SDK waits the time the service asks for, then retries.
- **401, 403 or 404** (wrong key, Flags not enabled for the project, unknown environment): automatic fetches stop until you call `refresh()`.
- **Before the first values:** `flags.isReady` is `false` and getters return your defaults.

`flags.close()` stops all network work. The cached values stay on the device.

### Configuration Options

<ConfigTable headers={['Option', 'Type', 'Default', 'Description']} rows={[
  ['apiKey', 'String', 'required', 'Your public API key (ab_live_xxx)'],
  ['environment', 'String?', 'null', 'Environment key (production, staging, development or your own). null uses the Default values'],
  ['flagKeys', 'List<String>?', 'null', 'Only fetch these flags. null fetches every flag of the project'],
  ['refreshIntervalSeconds', 'Long', '0', 'Polling while the app is in the foreground. 0 is off; otherwise at least 60'],
  ['cacheEnabled', 'Boolean', 'true', 'Store the last values and the user context on the device'],
  ['requestTimeoutMs', 'Long', '10000', 'Network timeout per request'],
  ['debug', 'Boolean', 'false', 'Verbose logs. They never contain the API key'],
]} />

### Upgrading from 0.1.x

0.2.0 is a new API, and 0.1.x clients stop receiving flags. Update the dependency and change these calls:

<ConfigTable headers={['0.1.x', '0.2.0']} rows={[
  ['suspend fun init(callback)', 'start(), plus addListener or awaitReady()'],
  ['setUserId + setUserAttributes, merged', 'identify(userId, attributes), setUserId, setAttributes. Attributes are replaced'],
  ['getValue(key, defaultValue)', 'getBoolean / getString / getNumber / getJson'],
  ['evaluate(key) returning FlagEvalResult', 'getDetail(key) returning FlagDetail, with reason and version'],
  ['getAll() returning List<FeatureFlag> with rules', 'getAll() returning Map<String, FlagResult>, values only'],
  ['AbrovaFlags.getInstance()', 'Keep your own instance'],
  ['enableOfflineCache', 'cacheEnabled'],
  ['reset() / dispose()', 'reset() for sign-out, close() to stop the client'],
]} />

- The values cached by 0.1.x are removed the first time 0.2.0 runs.
- Rollouts use a new bucketing method, so users are assigned to rollouts and variants again once.

### Best Practices

<BestPracticeList items={[
  ['One client per app', 'Create the client in your Application class and reuse it'],
  ['Always give a sensible default', 'The default is what your users see before the first values and when a flag is removed'],
  ['Reset on sign-out', 'The user id and attributes are remembered on the device. Call reset() when the user signs out'],
  ['Listen for updates', 'Use addListener to redraw when values change instead of calling refresh() often'],
  ['Leave polling off', 'Values refresh on start, on context changes and on app resume. Turn polling on only if you need faster updates'],
]} />

- iOS: https://abrova.ir/en/docs/flags/ios

<BestPracticeList columns={2} items={[
  ['Client-Safe', 'Uses the public API key only. Safe to ship in an app'],
  ['Evaluated by the Service', 'The app receives values for this user. Targeting rules never reach the device'],
  ['Typed Getters', 'getBoolean, getString, getNumber and getJson, each with a default'],
  ['Offline Cache', 'The last values are stored in UserDefaults and served at start and offline'],
  ['Anonymous Id', 'Percentage rollouts also work before sign-in'],
  ['Multi-Platform', 'iOS 14+ and macOS 12+'],
]} />

<Callout kind="note" title="Abrova Flags iOS SDK v0.2.0">
This page describes the `AbrovaFlags` Swift package 0.2.0. It is a breaking release: flags are evaluated by the service instead of on the device, and the getters changed. Coming from 0.1.x? See **Upgrading from 0.1.x** at the end of this page.
</Callout>

<Callout kind="note" title="Requirements">
iOS 14 or macOS 12. Swift 5.9.
</Callout>

<H2 id="installation" step={1}>Installation</H2>

Install with Swift Package Manager. In Xcode: **File > Add Package Dependencies** and enter:

```text
https://github.com/Abrova-co/abrova-ios-flags-sdk.git
```

Or add it to your `Package.swift`:

```swift
dependencies: [
    .package(url: "https://github.com/Abrova-co/abrova-ios-flags-sdk.git", from: "0.2.0")
]
```

<H2 id="initialization" step={2}>Initialization</H2>

Create one client for the app and call `start()`. Use your public API key (`ab_live_...`).

```swift
import AbrovaFlags

let flags = AbrovaFlags(config: AbrovaFlagsConfig(
    apiKey: "ab_live_xxx",
    environment: "production" // nil uses the Default values
))
flags.start()
```

`start()` returns immediately. It serves the values cached on the device and fetches fresh ones in the background. There is no shared instance in 0.2.0: keep the client you created.

To wait for the first values, for example on a launch screen:

```swift
let ready = await flags.waitUntilReady(timeout: 3) // false when the time ran out
```

<Callout kind="note" title="Never use the server secret in an app">
A server secret (`ab_srv_...`) passed as `apiKey` is refused: the SDK logs an error and never sends a request, so every getter returns your default. The server secret belongs on your backend, with the [Node.js](/docs/flags/nodejs) or [Next.js](/docs/flags/nextjs) server SDK.
</Callout>

<H2 id="read-flags" step={3}>Read flags</H2>

Getters never block and never throw. Each one takes the default to use when the flag is unknown, when no values are available yet, or when the flag has another type.

```swift
if flags.isEnabled("new-checkout") {
    // Show the new checkout
}

let dark = flags.getBoolean("dark-mode", default: false)
let theme = flags.getString("theme", default: "light")
let maxItems = flags.getNumber("max-items", default: 10)
let layout = flags.getJson("home-layout", default: ["columns": 2])
```

A `json` flag can also be decoded into your own type:

```swift
struct HomeLayout: Decodable {
    let columns: Int
}

let layout = flags.getJson("home-layout", as: HomeLayout.self, default: HomeLayout(columns: 2))
```

<ConfigTable headers={['Method', 'Returns']} rows={[
  ['isEnabled(_:default:)', 'true when the flag is served on for this user. The default is false'],
  ['getBoolean(_:default:)', 'Value of a boolean flag'],
  ['getString(_:default:)', 'Value of a string flag'],
  ['getNumber(_:default:)', 'Value of a number flag, as Double'],
  ['getJson(_:default:)', 'Value of a json flag, as AbrovaJSON'],
  ['getJson(_:as:default:)', 'A json flag decoded into any Decodable type'],
  ['getAll()', 'Every value held, as [String: FlagResult]'],
]} />

#### Details and reasons

```swift
let d = flags.stringDetail("theme", default: "light")
print(d.value, d.enabled, d.variant ?? "-", d.reason, d.version ?? 0)
```

`booleanDetail`, `stringDetail`, `numberDetail` and `jsonDetail` check the flag type and return a `FlagDetail`. `getDetail(_:default:)` returns the stored value without a type check.

<ConfigTable headers={['Reason', 'Meaning']} rows={[
  ['ON', 'The flag is on and has no variants. The value is true'],
  ['VARIANT', 'The flag is on and a variant was served'],
  ['DISABLED', 'The flag is off in this environment. The flag off value is served'],
  ['NOT_TARGETED', 'The targeting rules did not match this user. The off value is served'],
  ['OUTSIDE_ROLLOUT', 'The user is outside the rollout percentage. The off value is served'],
  ['PREREQUISITE_FAILED', 'A flag this one depends on did not give the required result. The off value is served'],
  ['NO_BUCKETING_ID', 'A rollout or split needed a user id or anonymous id and none was sent'],
  ['ERROR', 'The flag could not be evaluated. The off value is served'],
  ['FLAG_NOT_FOUND', 'No such flag. Your default is returned'],
  ['NOT_READY', 'No cached or fetched values yet. Your default is returned'],
  ['TYPE_MISMATCH', 'For example getString on a boolean flag. Your default is returned'],
]} />

Compare with the constants on `FlagReason`, for example `d.reason == .notReady`. `isEnabled` is `true` only for `ON` and `VARIANT`.

<H2 id="identify-the-user" step={4}>Identify the user</H2>

Tell the SDK who the user is and what you know about them. Targeting rules and percentage rollouts are evaluated against this context.

```swift
// After sign-in
flags.identify("user-123", attributes: ["plan": "pro", "country": "IR", "beta": true, "age": 31])

// Replace all attributes
flags.setAttributes(["plan": "business"])

// Signed out, attributes stay
flags.setUserId(nil)

// Sign-out: clears the user id, the attributes and the cached values
flags.reset()
```

- Each change fetches new values after a short pause (250 ms), so several calls in a row send one request. A call that changes nothing sends no request.
- `setAttributes` and the attributes of `identify` **replace** the whole set. They do not merge.
- When the user id changes, the previous user's values are dropped at once. Until the new values arrive, getters return your defaults (reason `NOT_READY`).
- Attributes are a string (at most 1,024 characters), a number, a `Bool`, `nil` / `NSNull`, or an array of those. At most 100 attributes. Anything else is dropped with a log warning.
- The user id and attributes are remembered on the device, so after a restart the client starts with the same user. Call `reset()` on sign-out.

If you call `identify` before `start()`, the first request already carries the user.

#### Anonymous id

Every install gets a random anonymous id (a UUID). It is stored on the device and sent with every request, so a 10% rollout reaches about 10% of signed-out installs too. When a user id is set, rollouts use the user id instead.

The anonymous id survives `reset()`. `flags.resetAnonymousId()` creates a new one. Read it with `flags.anonymousId`.

<H2 id="events" step={5}>Events</H2>

```swift
let token = flags.addListener { event in
    switch event {
    case .ready:
        break // First values are available (from the cache or the network). Fires once
    case .updated(let changedKeys):
        print("changed:", changedKeys)
    case .error(let error):
        print(error.kind, error.statusCode ?? 0, error.code ?? "-", error.message)
    }
}

// later
token.cancel()
```

Events always arrive on the main thread.

<H2 id="swiftui-example" step={6}>SwiftUI Example</H2>

```swift
import SwiftUI
import AbrovaFlags

final class FlagStore: ObservableObject {
    let flags: AbrovaFlags
    @Published private(set) var revision = 0

    init() {
        flags = AbrovaFlags(config: AbrovaFlagsConfig(apiKey: "ab_live_xxx", environment: "production"))
        flags.addListener { [weak self] event in
            switch event {
            case .ready, .updated:
                self?.revision += 1 // redraw views that read flags
            case .error:
                break
            }
        }
        flags.start()
    }
}

@main
struct MyApp: App {
    @StateObject private var store = FlagStore()

    var body: some Scene {
        WindowGroup {
            CheckoutView().environmentObject(store)
        }
    }
}

struct CheckoutView: View {
    @EnvironmentObject var store: FlagStore

    var body: some View {
        if store.flags.isEnabled("new-checkout") {
            Text("New checkout")
        } else {
            Text("Checkout")
        }
    }
}
```

<H2 id="refresh-offline-and-errors" step={7}>Refresh, offline and errors</H2>

The SDK fetches values:

- on `start()`,
- after a change of user or attributes, `reset()` and `resetAnonymousId()`,
- when the app returns to the foreground and the values are older than 15 minutes,
- on `refresh()`,
- on a timer, only if you set `refreshIntervalSeconds`.

```swift
// true when the values are current
let ok = await flags.refresh()

// With a completion handler
flags.refresh { ok in /* ... */ }
```

<Callout kind="note" title="Each fetch counts as one evaluation">
Every request for values is counted as one flag evaluation, whatever the number of flags it returns (100,000 evaluations are free every month; the price above that is set at launch). This is why polling is off by default.
</Callout>

The last values are stored in `UserDefaults` (never the API key) and served at the next start, before the network answers. A failed request never clears them.

- **Offline or server error:** the last values keep being served. The SDK retries with a growing delay (up to 5 minutes).
- **Rate limited (429):** the SDK waits the time the service asks for, then retries.
- **401, 403 or 404** (wrong key, Flags not enabled for the project, unknown environment): automatic fetches stop until you call `refresh()`.
- **Before the first values:** `flags.isReady` is `false` and getters return your defaults.

`flags.close()` stops all network work. The cached values stay on the device.

### Configuration Options

<ConfigTable headers={['Option', 'Type', 'Default', 'Description']} rows={[
  ['apiKey', 'String', 'required', 'Your public API key (ab_live_xxx)'],
  ['environment', 'String?', 'nil', 'Environment key (production, staging, development or your own). nil uses the Default values'],
  ['flagKeys', '[String]?', 'nil', 'Only fetch these flags. nil fetches every flag of the project'],
  ['refreshIntervalSeconds', 'TimeInterval', '0', 'Polling while the app is in the foreground. 0 is off; otherwise at least 60'],
  ['cacheEnabled', 'Bool', 'true', 'Store the last values and the user context on the device'],
  ['requestTimeout', 'TimeInterval', '10', 'Network timeout per request, in seconds'],
  ['debug', 'Bool', 'false', 'Verbose logs. They never contain the API key'],
]} />

### Upgrading from 0.1.x

0.2.0 is a new API, and 0.1.x clients stop receiving flags. Update the package and change these calls:

<ConfigTable headers={['0.1.x', '0.2.0']} rows={[
  ['try await flags.initialize(callback:)', 'flags.start(), plus addListener or waitUntilReady()'],
  ['setUserId + setUserAttributes, merged', 'identify(_:attributes:), setUserId, setAttributes. Attributes are replaced'],
  ['getValue(_:defaultValue:)', 'getBoolean / getString / getNumber / getJson'],
  ['evaluate(_:) returning FlagEvalResult', 'getDetail(_:default:) returning FlagDetail, with reason and version'],
  ['getAll() returning [FeatureFlag] with rules', 'getAll() returning [String: FlagResult], values only'],
  ['AbrovaFlags.shared', 'Keep your own instance'],
  ['enableOfflineCache', 'cacheEnabled'],
  ['reset() / dispose()', 'reset() for sign-out, close() to stop the client'],
]} />

Rollouts use a new bucketing method, so users are assigned to rollouts and variants again once.

### Best Practices

<BestPracticeList items={[
  ['One client per app', 'Create the client at launch and reuse it'],
  ['Always give a sensible default', 'The default is what your users see before the first values and when a flag is removed'],
  ['Reset on sign-out', 'The user id and attributes are remembered on the device. Call reset() when the user signs out'],
  ['Listen for updates', 'Use addListener to redraw when values change instead of calling refresh() often'],
  ['Leave polling off', 'Values refresh on start, on context changes and on app resume. Turn polling on only if you need faster updates'],
]} />

- AI assistants: https://abrova.ir/en/docs/flags/ai-assistants

<Callout kind="soon" title="Coming soon">
Abrova does not have a docs server for AI assistants yet. This page describes how it will work and what you can use today.
</Callout>

When it is ready, you connect your AI assistant (any tool that supports MCP, the open standard AI tools use to connect to outside sources) once. Then, when you ask it to add Abrova Flags to your project, it looks up the current SDK version, install lines and setup steps from these docs instead of answering from memory.

### What works today

- **Copy page for AI.** Every docs page has a **Copy page for AI** link. Paste the page into your assistant's chat before you ask it to write code.
- **Plain-text docs.** Give your assistant the address `https://abrova.ir/docs/llms.txt`. It lists every docs page as plain text that assistants read well.

Tell your assistant to follow the page you gave it, and to use the placeholder keys from the docs.

### What it will do

The docs server will have read-only tools. Your assistant chooses them by itself; you do not call them by hand.

<ConfigTable headers={['Tool', 'What it will do']} rows={[
  ['list_products', 'Lists the Abrova products, with the platforms that have an SDK and the docs link.'],
  ['search_docs', 'Searches the docs for a few words or a short question and returns the best pages.'],
  ['read_doc', 'Returns one docs page as text, with its link and last-updated date.'],
  ['get_sdk_info', 'Returns the SDK package for a product and platform: name, current version and install lines.'],
  ['get_setup_guide', 'Returns the ordered setup steps for a product and platform: install, keys, initialization and how to test.'],
]} />

Examples of what you will be able to ask:

- **"Put the new checkout behind a flag in my Next.js app."** It would answer from [Next.js SDK](/docs/flags/nextjs) and [Feature flags](/docs/flags/feature-flags).
- **"Roll the new search out to 20 % of users, then to everyone."** It would answer from [Rollouts](/docs/flags/rollouts) and [Targeting](/docs/flags/targeting).
- **"Evaluate flags on my Node.js server without a request per check."** It would answer from [Node.js SDK](/docs/flags/nodejs) and [Evaluation flow](/docs/flags/evaluation).

### Privacy

- **What it reads:** the public Abrova docs, the current SDK versions, and the words your assistant sends (the search words, the page it wants, the product and platform names).
- **What it never sees:** your code, your files, your Abrova project, your keys or your users. The tools have no input for them, and they cannot change any setting.

<Callout kind="warn" title="Keep your keys out of the chat">
Never paste a key into a chat with an AI assistant. Your assistant writes the placeholder from the docs (`ab_live_your_api_key`); you put the real value in your project's configuration yourself. The server secret (`ab_srv_...`) belongs only on your server, in an environment variable.
</Callout>

More about AI assistants and Abrova: [AI assistants](/ai-assistants). Questions? [Contact us](/contact).

- Feature flags: https://abrova.ir/en/docs/flags/feature-flags

<Callout kind="note" title="What are Feature Flags?">
Feature flags (also called feature toggles) let you enable or disable features in your application without deploying new code. They decouple deployment from release, giving you full control over who sees what — and when.
</Callout>

<Callout kind="wallet" title="What it will cost">
100,000 flag evaluations are free every month. Usage above that will cost from your prepaid wallet; the price is set at launch. See [Pricing](/pricing).
</Callout>

### Flag Types

Every flag has a value type: `boolean`, `string`, `number` or `json`. The SDKs have one getter per type, and each getter takes the default to use when the flag cannot be served.

#### Boolean Flags

Simple on/off toggles. The most common type — perfect for feature rollouts, kill switches, and A/B testing.

```typescript
if (flags.isEnabled('dark_mode')) {
  // Show dark mode
}
```

#### Multivariate Flags

Return different values based on weighted variants. Use for A/B/n testing, configuration, and dynamic content.

```typescript
const flow = flags.getString('checkout_flow', 'control');
// Returns: 'control', 'variant_a', or 'variant_b'
```

The examples above use a client SDK. On a server you pass the user with every call: `flags.getString('checkout_flow', { userId: 'user-123' }, 'control')`.

### Client SDKs and Server SDKs

<ClientServerComparison
  left={{
    title: 'Client SDKs',
    subtitle: 'Flutter, React Native, Android, iOS, Next.js client',
    accent: 'emerald',
    bullets: [
      'Use the public API key only',
      'Abrova Flags evaluates for the current user; the app gets values',
      'Targeting rules never reach the device',
      'Values are cached for offline use',
    ],
  }}
  right={{
    title: 'Server SDKs',
    subtitle: 'Node.js, Next.js server',
    accent: 'blue',
    bullets: [
      'Use the API key and the server secret',
      'Download the rules and evaluate locally',
      'You pass the user context with every call',
      'No network call per evaluation',
    ],
  }}
/>

Pick the SDK for your platform: [Flutter](/docs/flags/flutter), [React Native](/docs/flags/react-native), [Android](/docs/flags/android), [iOS](/docs/flags/ios), [Next.js](/docs/flags/nextjs), [Node.js](/docs/flags/nodejs).

### Using a Flag

<NumberedPipeline steps={[
  {
    title: 'Initialise the SDK',
    body: <>Give it your API key and, if you use them, the environment. Client SDKs start from the values cached on the device.</>,
  },
  {
    title: 'Say who the user is',
    body: <>Client SDKs: call <code>identify(userId, attributes)</code> after sign-in. Server SDKs: pass <code>userId</code> and <code>attributes</code> with each call. Signed-out users are covered by an anonymous id the client SDK keeps for you.</>,
  },
  {
    title: 'Read the flag with a default',
    body: <>Use <code>isEnabled</code> or a typed getter. The default is returned before the first values arrive, when the flag does not exist, or when it has another type.</>,
  },
  {
    title: 'Change it from the dashboard',
    body: <>Client SDKs pick up changes on start, when the user changes, and when the app comes back to the foreground. Server SDKs refresh every 30 seconds.</>,
  },
]} />

### Common Use Cases

<BestPracticeList items={[
  ['Gradual Rollouts', 'Release features to 5% of users, then 25%, then 100%. If something breaks, instantly roll back to 0%.'],
  ['Kill Switches', 'Wrap risky features in a flag so you can disable them instantly without redeploying.'],
  ['A/B Testing', 'Use multivariate flags to test different versions of a feature and measure which performs better.'],
  ['Beta Programs', 'Target specific user segments (like beta testers) with new features before general release.'],
  ['Scheduled Launches', 'Schedule a flag to enable at a specific date/time for product launches and promotions.'],
  ['Environment-Specific Config', 'Enable a feature in staging but keep it disabled in production until ready.'],
]} />

### Flag Lifecycle

<CardGrid columns={4} items={[
  ['1. Create', 'Define a flag in the dashboard with a unique key, targeting rules, and rollout percentage.'],
  ['2. Integrate', 'Add the flag check in your code using the SDK. Deploy your code — the flag stays off.'],
  ['3. Enable', 'Toggle the flag on from the dashboard. Users start seeing the feature based on your rules.'],
  ['4. Clean Up', 'Once the feature is stable, remove the flag check from your code and delete the flag.'],
]} />

<Callout kind="note" title="Tip">
Always clean up stale flags. Feature flags are meant to be temporary — once a feature is fully rolled out, remove the flag from your code to reduce complexity.
</Callout>

### Upgrading from 0.1.x

All six SDKs are at 0.2.0, and it is a breaking release. Client apps receive evaluated values only.

<BestPracticeList items={[
  ['Client apps must upgrade', 'A 0.1.x client SDK stops receiving flag updates'],
  ['Typed getters replace getValue', 'Use getBoolean (getBool in Flutter), getString, getNumber and getJson, each with a default. getDetail replaces evaluate and adds a reason'],
  ['identify replaces setUserAttributes', 'identify(userId, attributes) and setAttributes replace the whole set of attributes. They no longer merge'],
  ['Signed-out users are bucketed', 'Client SDKs keep an anonymous id, so a 10% rollout reaches about 10% of signed-out users instead of all of them'],
  ['Server context field renamed', 'In the Node.js and Next.js server SDKs, userAttributes is now attributes'],
  ['Next.js imports moved', 'The server SDK is imported from @abrova/flags-nextjs/server and the browser code from @abrova/flags-nextjs/client'],
  ['Dependencies and segments apply everywhere', 'SDK 0.1.x ignored flag dependencies. With 0.2.0 every evaluation checks them'],
  ['Users are bucketed again once', 'Rollouts and variant splits use a new bucketing method, so a user may land in a different rollout group or variant after the upgrade'],
]} />

Each SDK page ends with the exact list of calls to rename.

- Targeting: https://abrova.ir/en/docs/flags/targeting

<Callout kind="note" title="Targeting Rules">
Targeting rules let you control which users see a feature based on their attributes. You define the rules in the dashboard and your app only says who the user is. Rules are never sent to apps or browsers.
</Callout>

### How Targeting Works

When you create a flag, you can define targeting rules as conditions on user attributes. The rules are checked against the context of the user: the user id, the anonymous id and the attributes you provide.

<BestPracticeList items={[
  ['Client SDKs', 'The SDK sends the context to Abrova Flags, which checks the rules and returns the values for this user. A change of attributes fetches new values'],
  ['Server SDKs', 'The SDK downloads the rules with the server secret and checks them locally against the context you pass with each call'],
]} />

Conditions are combined in a group with **AND** (all must match) or **OR** (at least one must match). If no targeting rules are defined, the flag applies to all users. A user who does not match gets the flag's off value with reason `NOT_TARGETED`.

### Setting User Attributes

Pass user attributes to the SDK so targeting rules can evaluate against them:

#### Client-Side SDKs

```typescript
// React Native / Next.js (client)
await flags.identify('user-123', {
  plan: 'pro',
  country: 'US',
  age: 28,
  email: 'user@company.com',
});

// Later: replace the whole set of attributes
await flags.setAttributes({ plan: 'business', country: 'US' });
```

```dart
// Flutter
await flags.identify('user-123', attributes: {'plan': 'pro', 'country': 'US'});
```

```kotlin
// Android
flags.identify("user-123", mapOf("plan" to "pro", "country" to "US"))
```

```swift
// iOS
flags.identify("user-123", attributes: ["plan": "pro", "country": "US"])
```

<Callout kind="note" title="Attributes are replaced, not merged">
`identify` with attributes and `setAttributes` replace the whole set. Send every attribute your rules need each time. An attribute you leave out no longer exists for the rules.
</Callout>

#### Server-Side SDKs

```typescript
// Node.js / Next.js (server) — pass context per evaluation
const isEnabled = flags.isEnabled('premium_feature', {
  userId: 'user-123',
  attributes: {
    plan: 'pro',
    country: 'US',
  },
});
```

#### What an attribute can be

<ConfigTable headers={['Limit', 'Value']} rows={[
  ['Value types', 'String, number, boolean, null, or an array of those. No nested objects'],
  ['Number of attributes', 'At most 100'],
  ['Attribute name', '1 to 100 characters'],
  ['String value', 'At most 1,024 characters'],
  ['Array', 'At most 100 items'],
  ['userId and anonymousId', 'Not attributes. Rules on userId or anonymousId read the id of the context, and an attribute with one of these names is ignored'],
]} />

Attributes are sent to Abrova Flags with each fetch. Send what your rules need, and avoid personal data you do not target on.

### Comparison Operators

Targeting rules support these operators:

<ConfigTable headers={['Operator', 'Value', 'Matches when']} rows={[
  ['equals', 'any', 'The attribute equals the value'],
  ['not_equals', 'any', 'The attribute does not equal the value'],
  ['in', 'array', 'The attribute is one of the values'],
  ['not_in', 'array', 'The attribute is none of the values'],
  ['contains', 'string', 'The attribute is a string that contains the value'],
  ['not_contains', 'string', 'The attribute does not contain the value'],
  ['starts_with', 'string', 'The attribute is a string that starts with the value'],
  ['ends_with', 'string', 'The attribute is a string that ends with the value'],
  ['regex', 'string', 'The attribute is a string and the pattern matches somewhere in it'],
  ['greater_than', 'number', 'Attribute > value'],
  ['less_than', 'number', 'Attribute < value'],
  ['greater_than_or_equal', 'number', 'Attribute >= value'],
  ['less_than_or_equal', 'number', 'Attribute <= value'],
  ['exists', 'boolean', 'true: the attribute is present and not null. false: it is missing or null'],
  ['in_segment', 'segment', 'The user matches the segment'],
  ['not_in_segment', 'segment', 'The user does not match the segment'],
]} />

The rule builder in Abrova Console offers is, is not, is one of, is not one of, contains, greater than, less than, matches regex, exists, doesn't exist, is in segment and is not in segment.

#### How values are compared

- Text comparison is case-sensitive: `Pro` does not equal `pro`.
- A number and a numeric string are equal when the numbers are equal: `28` equals `"28"`. The number operators also accept numeric strings.
- A boolean equals the strings `"true"` and `"false"`.
- If the attribute is an array, a condition matches when **any** item matches. For example `tags: ['beta', 'staff']` matches `tags equals beta`.
- If the attribute is missing, `equals`, `in`, `contains` and the other positive operators do not match, and `not_equals`, `not_in`, `not_contains` and `not_in_segment` do match.
- `regex` looks for the pattern anywhere in the value. Use `^` and `$` to match the whole value.

### Rule Examples

A rule set is a group with an operator and a list of conditions. You build it in the dashboard; this is the shape the server SDKs receive:

```json
{
  "operator": "AND",
  "rules": [
    { "attribute": "country", "operator": "in", "value": ["US", "CA", "UK"] },
    { "attribute": "plan", "operator": "equals", "value": "premium" }
  ]
}
```

Here are common patterns:

#### Country Targeting

```json
{ "attribute": "country", "operator": "in", "value": ["US", "CA", "UK"] }
```

#### Plan-Based Access

```json
{ "attribute": "plan", "operator": "equals", "value": "premium" }
```

#### Email Domain Targeting

```json
{ "attribute": "email", "operator": "regex", "value": "@company\\.com$" }
```

#### Combined Rules (AND Logic)

```json
{
  "operator": "AND",
  "rules": [
    { "attribute": "country", "operator": "in", "value": ["US", "CA"] },
    { "attribute": "plan", "operator": "equals", "value": "premium" },
    { "attribute": "age", "operator": "greater_than_or_equal", "value": 18 }
  ]
}
```

All three conditions must be true for the flag to be enabled for this user.

#### Either Condition (OR Logic)

```json
{
  "operator": "OR",
  "rules": [
    { "attribute": "plan", "operator": "equals", "value": "enterprise" },
    { "attribute": "segment", "operator": "in_segment", "value": "beta-testers" }
  ]
}
```

A segment is a saved group of users defined by its own attribute conditions. The flag is enabled for enterprise users and for everyone in the `beta-testers` segment.

### Targeting and Rollouts Together

Targeting is checked before the rollout percentage. With rules for `plan equals premium` and a rollout of 20%, the flag is on for 20% of premium users and off for everyone else. See [Percentage Rollouts](/docs/flags/rollouts) and the [Evaluation Flow](/docs/flags/evaluation).

<Callout kind="note" title="Debugging a rule">
Read the reason of the flag with `getDetail`. `NOT_TARGETED` means the rules did not match the attributes that were sent. Check the spelling and the type of each attribute, and remember that `setAttributes` replaces all of them.
</Callout>

- Environments: https://abrova.ir/en/docs/flags/environments

<Callout kind="note" title="Environments">
Environments let you manage flag values per deployment stage. A flag can be enabled in development, staged for testing, and disabled in production — all from the same dashboard.
</Callout>

### Default Environments

Each project starts with three default environments:

<CardGrid columns={3} items={[
  ['Development', 'Local development and testing. Safe to experiment.'],
  ['Staging', 'Pre-production testing. Mirrors production config.'],
  ['Production', 'Live environment. Changes affect real users.'],
]} />

You can create custom environments from the dashboard (e.g., `canary`, `qa`).

### How Overrides Work

Each flag has a **base configuration**. Environment overrides replace specific properties of the base flag when non-null:

```text
Base Flag (enabled: false, rollout: 100%)
  └── development override (enabled: true)     → enabled in dev
  └── staging override (enabled: true)          → enabled in staging
  └── production override (null = inherit)      → disabled (inherits base)
```

Override properties include: `enabled`, `rolloutPercentage`, `targetingRules`, `variants`, and `defaultValue`. If an override property is `null`, the base flag value is inherited.

### Passing Environment in SDKs

Pass the environment name when initializing the SDK:

#### Flutter

```dart
await AbrovaFlags.init(const AbrovaFlagsConfig(
  apiKey: 'ab_live_xxx',
  environment: 'production',
));
```

#### React Native / Next.js (client)

```tsx
<AbrovaFlagsProvider config={{ apiKey: 'ab_live_xxx', environment: 'production' }}>
  {children}
</AbrovaFlagsProvider>
```

#### Node.js / Next.js (server)

```typescript
const flags = new AbrovaFlags({
  apiKey: process.env.ABROVA_FLAGS_API_KEY!,
  serverSecret: process.env.ABROVA_FLAGS_SERVER_SECRET!,
  environment: process.env.NODE_ENV === 'production'
    ? 'production' : 'development',
});
```

#### Android

```kotlin
val flags = AbrovaFlags(
    applicationContext,
    AbrovaFlagsConfig(
        apiKey = "ab_live_xxx",
        environment = if (BuildConfig.DEBUG) "development" else "production",
    ),
)
flags.start()
```

#### iOS

```swift
#if DEBUG
let env = "development"
#else
let env = "production"
#endif

let flags = AbrovaFlags(config: AbrovaFlagsConfig(
    apiKey: "ab_live_xxx",
    environment: env
))
flags.start()
```

The environment is fixed for the lifetime of a client. Flag dependencies are checked in the same environment as the flag.

<Callout kind="note" title="Note">
If no environment is specified, the SDK gets the base flag values without any environment overrides (the Default values). If the key does not match an active environment of the project, the request is refused: the SDK logs an error, keeps serving cached values or the defaults in your code, and stops fetching until you call `refresh()`. Check the spelling of the key first when every flag suddenly returns its default.
</Callout>

- Rollouts: https://abrova.ir/en/docs/flags/rollouts

<Callout kind="note" title="Percentage Rollouts">
Percentage rollouts let you gradually release a feature to a growing percentage of your user base. Start at 5%, validate, then increase to 25%, 50%, and finally 100%.
</Callout>

### How Bucketing Works

Abrova Flags uses **deterministic hashing into 10,000 buckets** to assign users. It is the same in the service and in every SDK, ensuring:

<BestPracticeList items={[
  ['Consistent assignment', 'The same user always gets the same bucket for a given flag'],
  ['Even distribution', 'Users are evenly spread across 10,000 buckets'],
  ['Per-flag independence', 'A user at 10% for flag A might be at 73% for flag B'],
  ['Same answer everywhere', 'A client SDK and a server SDK put the same user id in the same bucket'],
]} />

### Evaluation Formula

```text
bucket = deterministic hash of the user → 0 … 9999

if rolloutPercentage is 100:  flag is ENABLED for everyone
if rolloutPercentage is 0:    flag is DISABLED for everyone
if bucket < rolloutPercentage × 100:
    flag is ENABLED for this user
else:
    flag is DISABLED for this user   (reason OUTSIDE_ROLLOUT)
```

For example, if rollout is set to 30%, users with a bucket value 0-2999 will see the feature, while users with bucket 3000-9999 will not. Raising the percentage keeps everyone who already had the feature and adds new users.

### Rollout Strategy

A recommended gradual rollout strategy:

<RolloutLadder steps={[
  ['5%', 'Canary', 'Validate with a small group. Monitor error rates and metrics.'],
  ['25%', 'Early Access', 'Expand to more users. Check performance at scale.'],
  ['50%', 'Broad Beta', 'Half your users. Final validation before full release.'],
  ['100%', 'General Availability', 'Full rollout. Clean up the flag after stabilization.'],
]} />

<Callout kind="note" title="Important">
Rollout percentage only applies when a flag is **enabled**. If the flag is toggled off, it is disabled for all users regardless of the rollout percentage.
</Callout>

### Which Id Is Used

A partial rollout (1% to 99%) needs an id to place the user in a bucket.

<BestPracticeList items={[
  ['Signed-in users', 'The user id you pass to identify() in a client SDK, or as userId in the context of a server SDK'],
  ['Signed-out users', 'The anonymous id. Client SDKs create one per install or browser, keep it on the device and send it with every request. On a server you pass anonymousId yourself'],
  ['Sign-in changes the bucket', 'When a user signs in, bucketing switches from the anonymous id to the user id, so the result for a partial rollout can change at that moment'],
  ['No id at all', 'The flag is served off with reason NO_BUCKETING_ID. This only happens on a server when the context has neither userId nor anonymousId'],
]} />

```typescript
// Client SDKs (React Native shown): set the user once, the SDK remembers it
await flags.identify('user-123');
const enabled = flags.isEnabled('new-checkout');

// Server SDKs: pass the id with every call
const enabled = flags.isEnabled('new-checkout', { userId: 'user-123' });
const forVisitor = flags.isEnabled('new-checkout', { anonymousId: visitorId });
```

<Callout kind="note" title="Upgrading from 0.1.x">
In SDK 0.1.x a user without a user id was treated as inside every rollout. From 0.2.0, signed-out users are bucketed by their anonymous id, so a 10% rollout reaches about 10% of them. The bucketing method also changed, so users were assigned to rollouts again once when you upgraded.
</Callout>

- Multivariate: https://abrova.ir/en/docs/flags/multivariate

<Callout kind="note" title="Multivariate Flags">
Multivariate flags go beyond simple on/off toggles. Define weighted variants to serve different values, configurations, or UI experiences to different user segments.
</Callout>

### Defining Variants

Each variant has a **key**, a **value**, and a **weight** (percentage). Weights must sum to 100 (Abrova Console enforces this). All values of one flag have the flag's type: `string`, `number`, `json` or `boolean`.

```json
{
  "variants": [
    { "key": "control", "value": "old_checkout", "weight": 80 },
    { "key": "variant_a", "value": "new_checkout", "weight": 15 },
    { "key": "variant_b", "value": "minimal_checkout", "weight": 5 }
  ]
}
```

### How Variant Selection Works

Variant selection is deterministic. Abrova Flags uses deterministic hashing into 10,000 buckets (0 to 9,999) and walks the variants in order by weight. This ensures each user always gets the same variant, in every SDK.

```text
bucket = deterministic hash of the user → 0 … 9999

Variants: control (80%) | variant_a (15%) | variant_b (5%)
Ranges:   0-7999        | 8000-9499       | 9500-9999

If bucket = 4200  → control (old_checkout)
If bucket = 8500  → variant_a (new_checkout)
If bucket = 9700  → variant_b (minimal_checkout)
```

- The id is the user id, or the anonymous id when no user is signed in. A user who signs in is placed again by their user id.
- The variant bucket is independent of the rollout bucket of the same flag.
- A user only gets a variant when the flag is on for them. Otherwise the flag's off value is served and `variant` is empty.
- Without any id, a split cannot be decided: the flag is served off with reason `NO_BUCKETING_ID`. Client SDKs always send an anonymous id, so this only happens on a server when you pass neither `userId` nor `anonymousId`.

### Using Variants in Code

#### Typed getter — get the variant value

```typescript
// Client SDKs
const checkoutFlow = flags.getString('checkout_flow', 'old_checkout');
// Returns: 'old_checkout', 'new_checkout', or 'minimal_checkout'

// Server SDKs: pass the context
const checkoutFlow = flags.getString('checkout_flow', { userId: 'user-123' }, 'old_checkout');
```

Use the getter that matches the flag type: `getString`, `getNumber`, `getJson` or `getBoolean` (`getBool` in Flutter). A getter of another type returns your default with reason `TYPE_MISMATCH`.

#### getDetail — get the full result with the variant key

```typescript
// Client SDKs (server SDKs: add the context as the second argument)
const result = flags.getDetail('checkout_flow', 'old_checkout');
// result includes {
//   value: 'new_checkout',
//   enabled: true,
//   variant: 'variant_a',
//   reason: 'VARIANT',
//   version: 4
// }
```

#### Flutter

```dart
final result = flags.getStringDetail('checkout_flow', 'old_checkout');

switch (result.variant) {
  case 'control':
    return OldCheckout();
  case 'variant_a':
    return NewCheckout();
  case 'variant_b':
    return MinimalCheckout();
  default:
    return OldCheckout();
}
```

### Use Cases

<BestPracticeList items={[
  ['A/B/n Testing', 'Test multiple versions of a feature simultaneously to find the best performer'],
  ['Dynamic Configuration', 'Return different config values (colors, copy, limits) per variant'],
  ['Phased Launches', 'Release a new experience to a small group while keeping the old one for most users'],
  ['Personalization', 'Serve different UI layouts or content based on user segments'],
]} />

<Callout kind="note" title="Tip">
Variant analytics are available in the flag detail page in Abrova Console. They count the evaluations the service makes for client SDKs. Server SDK evaluations run locally and are included only when the SDK runs with `sendUsage: true`.
</Callout>

- Dependencies: https://abrova.ir/en/docs/flags/dependencies

<Callout kind="note" title="Flag Dependencies">
Flag dependencies let you create relationships between flags. A dependent flag is only enabled when all its dependencies are met — perfect for feature chains and prerequisite logic.
</Callout>

### How Dependencies Work

When a flag has dependencies, all of them are checked first. If any dependency is not met, the dependent flag is served off (`enabled: false`, the flag's off value) with reason `PREREQUISITE_FAILED`.

<Callout kind="note" title="Upgrading from 0.1.x: enforced in every SDK">
With the 0.2.0 SDKs, dependencies apply everywhere. For client SDKs the service checks them when it evaluates for the user. The Node.js and Next.js server SDKs check them locally. SDK 0.1.x ignored dependencies.
</Callout>

```json
{
  "dependencies": [
    { "flagKey": "dark_mode" },
    { "flagKey": "beta_features", "expectedValue": true }
  ]
}
```

In this example, the flag is only enabled if **both** `dark_mode` is enabled AND `beta_features` evaluates to `true`.

- Without `expectedValue`, a dependency is met when that flag is served on for the user.
- With `expectedValue`, it is met when the value served to the user equals it.
- A dependency is evaluated in the same environment and for the same user as the flag itself. So a dependency with a 20% rollout is met only for the users inside that 20%.

### Evaluation Order

Dependencies are resolved recursively during evaluation:

```text
Evaluating flag "premium_dark_theme":
  1. Check dependency: "dark_mode"
     → dark_mode is enabled ✓
  2. Check dependency: "beta_features"
     → beta_features is enabled ✓
     → expectedValue matches ✓
  3. All dependencies met → continue evaluation
  4. Check targeting rules, rollout, variants...
  5. Return result
```

In code you can see the outcome in the reason:

```typescript
// Server SDK
const d = flags.getDetail('premium_dark_theme', { userId: 'user-123' }, false);
if (d.reason === 'PREREQUISITE_FAILED') {
  // dark_mode or beta_features is not met for this user
}
```

### Use Cases

<BestPracticeList items={[
  ['Feature Chains', 'Ensure a prerequisite feature is enabled before enabling dependent features (e.g., "dark mode themes" depends on "dark mode")'],
  ['Staged Rollouts', 'Release features in phases — Phase 2 depends on Phase 1 being enabled'],
  ['Platform Requirements', 'A mobile-only feature depends on a "mobile_v2" platform flag'],
  ['A/B Test Prerequisites', 'An experiment depends on the base feature being enabled first'],
]} />

<Callout kind="note" title="Circular Dependency Protection">
Circular dependencies are detected when a flag is created or updated, and the change is rejected with an error. A flag cannot depend on itself, and every referenced flag must exist. At evaluation time, a dependency on a flag that no longer exists, or a chain deeper than 10 flags, counts as not met.
</Callout>

- Scheduling: https://abrova.ir/en/docs/flags/scheduling

<Callout kind="note" title="Flag Scheduling">
Schedule flags to automatically enable or disable at a specific date and time. Perfect for product launches, promotions, maintenance windows, and time-sensitive features.
</Callout>

### How Scheduling Works

From the dashboard, you can schedule a flag to change state at a future time. Abrova Flags checks for due schedules every minute and applies them automatically.

#### Schedule Enable

Set a flag to automatically turn ON at a specific date/time. Great for launches and feature reveals.

#### Schedule Disable

Set a flag to automatically turn OFF at a specific date/time. Useful for promotions and temporary features.

### Use Cases

<BestPracticeList items={[
  ['Product Launches', 'Schedule a feature to go live at midnight on launch day — no manual intervention needed'],
  ['Limited-Time Promotions', 'Enable a promo banner at 9 AM and disable it at midnight automatically'],
  ['Maintenance Windows', 'Schedule a maintenance mode flag to enable during planned downtime'],
  ['Seasonal Features', 'Enable holiday-themed UI changes during specific date ranges'],
]} />

### Managing Schedules

Schedules are managed from the Feature Flags page in Abrova Console:

<RowList items={[
  ['Create', 'Create or edit a flag → in the Schedule field pick "Enable at" or "Disable at" and set the date and time'],
  ['Cancel', 'Open the flag detail page → click "Cancel Schedule" to remove a pending schedule'],
  ['View', 'Scheduled flags show a clock icon and the scheduled time in the flag list'],
]} />

### When Your App Sees the Change

A schedule changes the flag in Abrova Flags. Your code needs no change, but each SDK picks up the new state at its next refresh:

<BestPracticeList items={[
  ['Server SDKs (Node.js, Next.js server)', 'Within about 30 seconds, at the next automatic rule refresh'],
  ['Client SDKs (Flutter, React Native, Android, iOS, Next.js client)', 'At the next fetch: app start, a change of user or attributes, a return to the foreground after 15 minutes, or refresh()'],
]} />

If a client must switch close to the scheduled time, call `refresh()` at that moment or set `refreshIntervalSeconds` (minimum 60). Each client fetch counts as one evaluation.

<Callout kind="note" title="Note">
Schedules are checked every minute. There may be up to a 60-second delay between the scheduled time and the actual state change.
</Callout>

- Public SDK endpoints: https://abrova.ir/en/docs/flags/public-endpoints

<Callout kind="note" title="Public SDK Endpoints">
These are the endpoints the 0.2.0 SDKs call. You only need this page if you call Abrova Flags over HTTP yourself, for example from a platform without an SDK. Base URL: `https://flags.abrova.ir`. All bodies are JSON.
</Callout>

### Who calls what

<ClientServerComparison
  left={{
    title: 'Client SDKs',
    subtitle: 'Flutter, React Native, Android, iOS, Next.js client',
    accent: 'emerald',
    bullets: [
      'Public API key only',
      'POST /public/v2/evaluate',
      'The service evaluates and returns values for one user',
      'Rules, segments and variant weights are never returned',
    ],
  }}
  right={{
    title: 'Server SDKs',
    subtitle: 'Node.js, Next.js server',
    accent: 'blue',
    bullets: [
      'API key and server secret',
      'GET /server/v2/flags',
      'The SDK downloads the rules and evaluates locally',
      'Optional POST /server/v2/usage for the Console charts',
    ],
  }}
/>

### Authentication

<ConfigTable rows={[
  ['x-api-key', 'Header', 'Yes', 'Your project API key (ab_live_xxx)'],
  ['x-server-secret', 'Header', 'No', 'Server secret (ab_srv_xxx). Required on every /server route. Never send it from an app or a browser'],
  ['x-abrova-sdk', 'Header', 'No', 'Platform and version of the caller, for example node/0.2.0. Informational'],
  ['If-None-Match', 'Header', 'No', 'The ETag of your last answer for the same request. The service answers 304 when nothing changed'],
]} />

A public API key cannot read targeting rules. A `/server` route called without the server secret answers 403 with code `server_secret_required`. If the server secret has an IP allow-list, calls from other addresses are refused.

### POST /public/v2/evaluate

Evaluates the flags of the project for one user context and returns the values. Used by all client SDKs.

#### Request

```bash
curl -X POST "https://flags.abrova.ir/public/v2/evaluate" \
  -H "x-api-key: ab_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "environment": "production",
    "context": {
      "userId": "user-123",
      "anonymousId": "3f1c2b8e-9d0a-4c51-a1f2-6f0b7e2d9c11",
      "attributes": { "plan": "pro", "country": "IR", "beta": true, "age": 31 }
    },
    "flagKeys": ["new-checkout", "theme"]
  }'
```

#### Request Body

<ConfigTable rows={[
  ['environment', 'string', 'No', 'Environment key (production, staging, development or your own). Leave out to use the Default values. An unknown or inactive key answers 404'],
  ['context', 'object', 'Yes', 'Who the flags are evaluated for'],
  ['context.userId', 'string', 'No', 'The signed-in user id, 1 to 256 characters'],
  ['context.anonymousId', 'string', 'No', 'An id for a signed-out install or visitor, 1 to 256 characters. The SDKs always send it'],
  ['context.attributes', 'object', 'No', 'At most 100 attributes. A value is a string (at most 1,024 characters), a number, a boolean, null, or an array of at most 100 of those. No nested objects'],
  ['flagKeys', 'string[]', 'No', 'Only evaluate these flags, at most 500. Leave out to evaluate every flag'],
]} />

At least one of `context.userId` and `context.anonymousId` is required. Attributes named `userId` or `anonymousId` are ignored; the context fields are used instead.

#### Response

```json
{
  "environment": "production",
  "evaluatedAt": "2026-10-01T12:00:00.000Z",
  "flags": {
    "new-checkout": {
      "key": "new-checkout",
      "valueType": "boolean",
      "enabled": true,
      "value": true,
      "variant": null,
      "reason": "ON",
      "version": 7
    },
    "theme": {
      "key": "theme",
      "valueType": "string",
      "enabled": true,
      "value": "dark",
      "variant": "dark",
      "reason": "VARIANT",
      "version": 3
    }
  }
}
```

<ConfigTable headers={['Field', 'Type', 'Description']} rows={[
  ['environment', 'string | null', 'The environment that was evaluated. null for the Default values'],
  ['evaluatedAt', 'string', 'Time of the evaluation (ISO 8601)'],
  ['flags', 'object', 'One entry per flag, by key. Flags that are off are included with their off value. Keys that do not exist are left out'],
  ['flags.*.valueType', 'string', 'boolean, string, number or json'],
  ['flags.*.enabled', 'boolean', 'true when the flag is served on for this context'],
  ['flags.*.value', 'any', 'The value to use, already of the flag type'],
  ['flags.*.variant', 'string | null', 'Key of the served variant, if any'],
  ['flags.*.reason', 'string', 'Why: ON, VARIANT, DISABLED, PREREQUISITE_FAILED, NOT_TARGETED, OUTSIDE_ROLLOUT, NO_BUCKETING_ID or ERROR'],
  ['flags.*.version', 'number', 'Version of the flag'],
]} />

The response carries an `ETag` header. Send it back as `If-None-Match` with the same body to get `304 Not Modified` when the values did not change.

<Callout kind="note" title="Counted as one evaluation per request">
Each call to this endpoint is counted as one flag evaluation, whatever the number of flags it returns, and also when the answer is 304 (100,000 evaluations are free every month; the price above that is set at launch). Cache the values and call again only when the user or the attributes change.
</Callout>

### GET /server/v2/flags

Returns every flag of the project with its rules, for local evaluation. Used by the Node.js and Next.js server SDKs. Requires the server secret. Not counted as evaluations.

#### Request

```bash
curl -X GET "https://flags.abrova.ir/server/v2/flags?environment=production" \
  -H "x-api-key: ab_live_xxx" \
  -H "x-server-secret: ab_srv_xxx"
```

#### Query Parameters

<ConfigTable rows={[
  ['environment', 'string', 'No', 'Environment key. Leave out to use the Default values. An unknown or inactive key answers 404'],
]} />

#### Response

```json
{
  "schemaVersion": 2,
  "environment": "production",
  "generatedAt": "2026-10-01T12:00:00.000Z",
  "flags": [
    {
      "key": "theme",
      "valueType": "string",
      "enabled": true,
      "rolloutPercentage": 100,
      "salt": "a1b2c3d4e5f6",
      "rules": {
        "operator": "AND",
        "rules": [
          { "attribute": "plan", "operator": "in", "value": ["pro", "business"] }
        ]
      },
      "variants": [
        { "key": "dark", "value": "dark", "weight": 50 },
        { "key": "light", "value": "light", "weight": 50 }
      ],
      "offValue": "light",
      "prerequisites": [{ "flagKey": "new-ui" }],
      "version": 3
    }
  ],
  "segments": [
    {
      "key": "beta-testers",
      "rules": {
        "operator": "OR",
        "rules": [
          { "attribute": "email", "operator": "ends_with", "value": "@example.com" }
        ]
      }
    }
  ]
}
```

Environment overrides are already merged into each flag. `offValue` is the value served when the user does not get the flag. The response carries an `ETag` header; send it back as `If-None-Match` to get 304 when nothing changed. The server SDKs do this every 30 seconds.

<Callout kind="note" title="Use a server SDK when you can">
Evaluating these rules yourself means implementing the whole [evaluation flow](/docs/flags/evaluation), including bucketing. The Node.js and Next.js server SDKs already do it and give the same results as the service.
</Callout>

### POST /server/v2/usage

Optional. Reports how often a server evaluated each flag, so the evaluation charts in Abrova Console include server-side evaluations. The server SDKs send it when `sendUsage` is `true`. Requires the server secret. Not billed, and it contains no user ids.

#### Request

```bash
curl -X POST "https://flags.abrova.ir/server/v2/usage" \
  -H "x-api-key: ab_live_xxx" \
  -H "x-server-secret: ab_srv_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "environment": "production",
    "periodStart": "2026-10-01T12:00:00.000Z",
    "periodEnd": "2026-10-01T12:01:00.000Z",
    "counts": [
      { "flagKey": "theme", "variant": "dark", "enabled": true, "count": 1520 },
      { "flagKey": "theme", "variant": null, "enabled": false, "count": 40 }
    ]
  }'
```

#### Request Body

<ConfigTable rows={[
  ['environment', 'string', 'No', 'Environment key the counts belong to'],
  ['periodStart', 'string', 'Yes', 'Start of the period (ISO 8601)'],
  ['periodEnd', 'string', 'Yes', 'End of the period. Not before periodStart, at most one hour after it'],
  ['counts', 'array', 'Yes', 'At most 1,000 entries'],
  ['counts[].flagKey', 'string', 'Yes', 'The flag key. Unknown keys are ignored'],
  ['counts[].variant', 'string | null', 'No', 'The served variant key'],
  ['counts[].enabled', 'boolean', 'Yes', 'Whether the flag was served on'],
  ['counts[].count', 'number', 'Yes', 'Whole number from 1 to 10,000,000'],
]} />

#### Response

`202 Accepted`

```json
{ "accepted": 2 }
```

### Errors

Errors are JSON. Act on the HTTP status; `code` and `message` are for your logs.

```json
{
  "statusCode": 403,
  "error": "Forbidden",
  "code": "server_secret_required",
  "message": "This route returns targeting rules and needs the server secret (x-server-secret)."
}
```

<ConfigTable headers={['Status', 'When', 'What to do']} rows={[
  ['304', 'If-None-Match matched', 'Keep the values or rules you have'],
  ['400', 'Invalid body (code invalid_request): no user id and no anonymous id, too many attributes, a nested attribute', 'Fix the request. Do not send the same body again'],
  ['401', 'Missing or invalid API key, invalid server secret, or Flags is not set up for the project', 'Check the keys. Do not retry automatically'],
  ['403', 'A /server route without the server secret, or a caller outside the server secret IP allow-list', 'Do not retry automatically'],
  ['404', 'The environment does not exist or is inactive (code environment_not_found)', 'Check the environment key. Do not retry automatically'],
  ['429', 'Rate limited', 'Wait the number of seconds in the Retry-After header, then retry with a growing delay'],
  ['5xx', 'Server error', 'Keep the last values and retry with a growing delay'],
]} />

Requests are rate limited per key and per address. Server-secret calls have higher limits than public-key calls. Do not hard-code the limits: follow `Retry-After`.

### Older endpoints (upgrading from 0.1.x)

Two endpoints from the 0.1.x SDKs still answer. Use the endpoints above for new code.

<ConfigTable headers={['Endpoint', 'Status']} rows={[
  ['POST /public/flag-evaluation', 'Deprecated. Evaluates one flag for one user with the public key. Body: flagKey and userId (required), userAttributes and environment (optional). Answers flagKey, enabled, value and, when a variant was served, variant. An unknown flag answers enabled false with reason flag_not_found. Counted as one evaluation per call. Use POST /public/v2/evaluate instead'],
  ['GET /public/flags', 'Deprecated; needs the server secret. Use `GET /server/v2/flags`.'],
]} />

<Callout kind="note" title="Request Volume">
The client SDKs call the service on start, when the user context changes and when the app or tab comes back after 15 minutes. The server SDKs never call the service per evaluation. If you call the API yourself, follow the same pattern.
</Callout>

- Evaluation flow: https://abrova.ir/en/docs/flags/evaluation

<Callout kind="note" title="Evaluation Flow">
Understanding how Abrova Flags evaluates a flag helps you design better targeting rules and debug unexpected behavior. Every evaluation follows the same steps and ends with a **reason** that tells you which step decided.
</Callout>

### Where evaluation happens

<ClientServerComparison
  left={{
    title: 'Client SDKs',
    subtitle: 'Flutter, React Native, Android, iOS, Next.js client',
    accent: 'emerald',
    bullets: [
      'Send the user context to Abrova Flags',
      'The service runs the steps below',
      'The app receives and caches the values',
      'Targeting rules never reach the device',
    ],
  }}
  right={{
    title: 'Server SDKs',
    subtitle: 'Node.js, Next.js server',
    accent: 'blue',
    bullets: [
      'Download the rules with the server secret',
      'Run the steps below inside your process',
      'You pass the context with every call',
      'No network call per evaluation',
    ],
  }}
/>

Both sides run the same steps with the same bucketing, so a user gets the same result from a client SDK and from a server SDK.

### The Pipeline

The first step that decides ends the evaluation. "Off" means `enabled: false` with the flag's off value.

<NumberedPipeline highlightLast={true} steps={[
  {
    title: 'Is the flag enabled?',
    body: <>If the flag is toggled off in this environment → off, reason <code>DISABLED</code></>,
  },
  {
    title: 'Check flag dependencies',
    body: <>Each flag this one depends on is evaluated first, in the same environment and for the same user. If one of them does not give the required result → off, reason <code>PREREQUISITE_FAILED</code></>,
  },
  {
    title: 'Evaluate targeting rules',
    body: <>If the flag has targeting rules and they do not match the user context → off, reason <code>NOT_TARGETED</code></>,
  },
  {
    title: 'Rollout bucketing',
    body: <>At 100% everyone passes. At 0% nobody does. In between, the user is placed in a bucket by user id (or anonymous id). Outside the percentage → off, reason <code>OUTSIDE_ROLLOUT</code>. No id at all → off, reason <code>NO_BUCKETING_ID</code></>,
  },
  {
    title: 'Variant selection',
    body: <>If the flag has variants, one is picked by weight, again from the user id (or anonymous id) → on, reason <code>VARIANT</code>, the value is the variant value</>,
  },
  {
    title: 'Return result',
    body: <>A flag without variants → on, value <code>true</code>, reason <code>ON</code></>,
  },
]} />

### Flow Diagram

```text
┌────────────────────────┐
│  Is flag enabled?       │
└────────┬───────────────┘
         │ No → off, DISABLED
         │ Yes ↓
┌────────────────────────┐
│  Check dependencies     │
└────────┬───────────────┘
         │ Fail → off, PREREQUISITE_FAILED
         │ Pass ↓
┌────────────────────────┐
│  Evaluate targeting     │
│  rules                  │
└────────┬───────────────┘
         │ No match → off, NOT_TARGETED
         │ Match ↓
┌────────────────────────┐
│  Rollout bucketing      │
│  bucket of the user id  │
│  inside the rollout %?  │
└────────┬───────────────┘
         │ Outside → off, OUTSIDE_ROLLOUT
         │ No id → off, NO_BUCKETING_ID
         │ Inside ↓
┌────────────────────────┐
│  Has variants?          │
└────────┬───────────────┘
         │ Yes → on, VARIANT (value of the variant)
         │ No  → on, ON (value true)
```

### Reasons

Every result carries a reason. Read it with the detail getters of the SDKs (`getDetail`, `getStringDetail` and so on).

<ConfigTable headers={['Reason', 'Meaning']} rows={[
  ['ON', 'The flag is on and has no variants. The value is true'],
  ['VARIANT', 'The flag is on and a variant was served'],
  ['DISABLED', 'The flag is off in this environment'],
  ['PREREQUISITE_FAILED', 'A flag this one depends on did not give the required result'],
  ['NOT_TARGETED', 'The targeting rules did not match the context'],
  ['OUTSIDE_ROLLOUT', 'The user is outside the rollout percentage'],
  ['NO_BUCKETING_ID', 'A rollout or split needed an id and the context has neither a user id nor an anonymous id'],
  ['ERROR', 'The flag could not be evaluated. The off value is served'],
  ['FLAG_NOT_FOUND', 'Set by the SDK: no such flag. Your default is returned'],
  ['NOT_READY', 'Set by the SDK: no values or rules loaded yet. Your default is returned'],
  ['TYPE_MISMATCH', 'Set by the SDK: a typed getter was used on a flag of another type. Your default is returned'],
]} />

### Off Values and Defaults

There are two different fallbacks:

- **The flag's off value** is set on the flag in Abrova Console. It is served when the flag exists but the user does not get it (reasons `DISABLED`, `PREREQUISITE_FAILED`, `NOT_TARGETED`, `OUTSIDE_ROLLOUT`, `NO_BUCKETING_ID`, `ERROR`). For a boolean flag it is `false` unless you set it.
- **The default in your code** is the last argument of a getter. It is returned when the SDK has nothing to serve (reasons `FLAG_NOT_FOUND`, `NOT_READY`, `TYPE_MISMATCH`).

```typescript
// Client SDKs: (key, default)
const flow = flags.getString('checkout-flow', 'classic');

// Server SDKs: (key, context, default)
const flow = flags.getString('checkout-flow', { userId: 'user-123' }, 'classic');
```

<Callout kind="note" title="Debugging Tip">
If a flag isn't behaving as expected, read its reason first: it names the step that decided. Then check that step: Is the flag enabled in this environment? Are its dependencies met? Do the targeting rules match the attributes you send? Is the user inside the rollout percentage? The flag's page in Abrova Console shows evaluation counts from the client SDKs, and from server SDKs that run with `sendUsage: true`.
</Callout>


## Abrova A/B Testing (coming soon)

- Getting started: https://abrova.ir/en/docs/ab-testing/quick-start

<Callout kind="note" title="What is Abrova A/B Testing?">
Run controlled experiments, ship features behind flags, and measure conversion impact with statistical significance. The Abrova A/B Testing platform includes experiments, feature flags, event tracking, offline sync, mutual exclusion groups, holdout groups, and webhooks.
</Callout>

Using an AI assistant? See [AI assistants](/docs/ab-testing/ai-assistants) for how to give it these docs.

<Callout kind="wallet" title="What it will cost">
2,000 participants are free every month. The price above that is set at launch and will be paid from your prepaid wallet. See [Pricing](/pricing).
</Callout>

### Quick Start

Follow these steps to integrate Abrova A/B Testing into your app:

<CardGrid columns={4} items={[
  ['1. Install SDK', 'Add the Abrova Center registry, then install the SDK (version 0.2.3 or later)'],
  ['2. Add a token endpoint', 'Your server mints a user token for the signed-in user'],
  ['3. Initialize', 'Configure with your API key and a tokenProvider'],
  ['4. Get variants & track', 'Fetch variants, then log views and conversions'],
]} />

### Platform SDKs

Select your platform to view detailed installation and usage instructions.

<BestPracticeList columns={2} items={[
  ['Android', 'Native Kotlin SDK for Android apps'],
  ['iOS', 'Native Swift SDK for iOS apps'],
  ['Flutter', 'Cross-platform Dart SDK for Flutter apps'],
  ['React Native', 'Cross-platform SDK for React Native apps'],
  ['Next.js', 'Client-side SDK for Next.js / React web apps'],
  ['Node.js', 'Server-side SDK for Node.js backends'],
]} />

### User tokens

Your API key identifies your **project**, not your **user**. It ships inside every app and web bundle, so anyone can read it. To know *which user* a request is for, your server issues a short-lived **user token** and the SDK sends it with every request.

| Credential | Lives in | Proves |
|---|---|---|
| **API key** (`ab_live_…`) | Your app, public | Which project |
| **Server secret** (`ab_srv_…`) | Your server only | That your backend is calling |
| **User token** (1 hour by default) | Your app, per user | Which user |

A user token is **required** for everything that acts for a user: getting a variant, tracking events and conversions, and evaluating feature flags. Loading the experiment and flag lists works with the API key alone, so your app can do that before anyone signs in.

#### One token for every Abrova product

Mint the token on your server from the Abrova auth endpoint:

```bash
curl -X POST https://auth.abrova.ir/users/token \
  -H "x-api-key: $ABROVA_API_KEY" \
  -H "x-server-secret: $ABROVA_SERVER_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"userId": "user-123", "expiresIn": 3600}'

# → { "token": "eyJhbGciOi…", "userId": "user-123", "expiresIn": 3600, "expiresAt": "2026-09-27T10:00:00.000Z" }
```

`expiresIn` is in seconds: 3600 (1 hour) by default, 86400 (24 hours) maximum. The same token works for Abrova A/B Testing, Chat, Sync and Push — give it to every SDK's `tokenProvider` instead of fetching one per product. Using Node.js? `createUserToken(userId)` in the Node.js SDK does this call for you.

The SDKs call `tokenProvider` when they need a token, again shortly before it expires, and once more if the service reports it expired.

#### The token decides the user

The service takes the user from the signed token, not from the app, and the SDKs follow it: once an SDK has a token, it acts as the user that token was minted for. If you also call `setUserId`, pass the same ID your server puts in the token. On React Native and Next.js you may skip `setUserId` altogether.

#### Before your user signs in

You can initialize a client SDK before anyone is signed in. Have `tokenProvider` return `null` while there is no user (on iOS, complete with `.failure`). From version 0.2.2 the SDK then waits for a user token instead of failing:

- `getVariant` returns the default you pass. Flags return your default or, on Android, iOS and Flutter, the answer from the cached flag list.
- Nothing is sent for a user, and no error is reported.
- Events you track are kept on the device, up to 1,000.

`isAwaitingUserToken` is `true` while the SDK waits, and `onAwaitingUserToken` is called each time it starts waiting. When a token arrives, the SDK carries on by itself: it fetches the variants your app asked for and sends the kept events.

Tell the SDK when the user signs in or out. The calls have the same names in every client SDK:

| When | With a `tokenProvider` | Handing tokens over yourself |
|---|---|---|
| After sign-in | `refreshUserToken()` | `setUserToken(token)` |
| After sign-out | `clearUserId()` | `setUserToken(null)` (`nil` on iOS) |

Events are credited to the user in the token. Events recorded before sign-in are only sent if they were recorded for the same user ID that signs in (you called `setUserId` with that ID before tracking). Events recorded for an anonymous user are not credited to anyone and are dropped at sign-in.

#### Signing out and switching users

A sign-out, a `setUserId` call with a different ID, or a token for another user clears the previous user's variants, attributes, token and pending events before anything is done for the next user. Events of the previous user that are ready to send go out under that user's own token, never under another user's.

**Signed-out visitors** need a token too if you want them in an experiment. Either have your server mint one for an anonymous ID (for example a device or session ID you pass to `setUserId`), or run experiments only after sign-in. Without a token, the service records no assignments or events for that user.

<Callout kind="note" title="Keep it on the device">
A token is valid until it expires, so store it with the user's session (Keychain, Keystore or secure storage) and reuse it across app launches. Your app then only calls your backend when the token is close to expiry — not on every start.
</Callout>

<Callout kind="warn" title="Never ship the server secret">
The server secret stays on your server. Never put it in an app, a browser bundle, or a `NEXT_PUBLIC_` variable. Server-side code (the Node.js SDK) uses the server secret directly instead of a user token.
</Callout>

### All Features

Abrova A/B Testing provides a complete experimentation platform with these features.

<BestPracticeList columns={2} items={[
  ['A/B Testing', 'Run controlled experiments to optimize user experience'],
  ['Offline Support', 'Queue events when offline, sync automatically when back online'],
  ['Feature Flags', 'Toggle features on/off without deploying code'],
  ['Mutual Exclusion', 'Prevent users from being in conflicting experiments'],
  ['Holdout Groups', 'Measure cumulative impact of your experimentation program'],
  ['Real-time Analytics', 'Track conversions, views, and custom events'],
  ['Webhooks', 'Get notified when experiments start, pause, complete, or are archived'],
  ['Signed User Tokens', 'One token per user, shared with Abrova Chat, Sync and Push'],
]} />

### A/B Testing

Run controlled experiments to test different variations of your app and measure which performs better.

#### How it works

1. **Create an experiment** in the dashboard with multiple variants (e.g., control, variant-a, variant-b)
2. **Set traffic allocation** — decide what percentage of users should be in the experiment
3. **Get variant in your app** — the service decides which variant the user should see, and the SDK returns it and remembers it
4. **Track events** — log views, clicks, and conversions
5. **Analyze results** — see which variant performs better with statistical significance

#### Pseudocode Example

The basic experiment loop, in any client SDK (see each platform page for exact syntax):

```typescript
// 1. Initialize with your API key and a token provider
AbrovaAbTesting.init({
  apiKey: "YOUR_API_KEY",
  tokenProvider: () => fetchAbrovaTokenFromYourServer(),
})

// 2. Identify the signed-in user (on logout, call clearUserId())
AbrovaAbTesting.setUserId("user-123")

// 3. Get variant for the current user
const variant = await AbrovaAbTesting.getVariant(
  "checkout-button-color",
  "control"  // default until the service has assigned a variant
)

// 4. Apply variant in your UI
// Android and iOS return the variant key ("variant-a"); Flutter, React Native,
// Next.js and Node.js return the variant name from the Console ("Variant A")
if (variant === "variant-a") {
  button.color = "green"
  button.text = "Buy Now!"
} else if (variant === "variant-b") {
  button.color = "blue"
  button.text = "Add to Cart"
} else {
  button.color = "gray"      // control
  button.text = "Purchase"
}

// 5. Track when user views the experiment
AbrovaAbTesting.trackView("checkout-button-color")

// 6. Track conversion when user completes action
AbrovaAbTesting.trackConversion(
  "checkout-button-color",
  300000  // optional: revenue value
)
```

Variants are decided by the service only. When the service can't be asked (no network, or no user token yet), the SDKs return the assignment they cached earlier, or your default. No SDK works a variant out on the device.

On Android and iOS, the synchronous `getVariant` never blocks: it returns the stored variant, or your default while the assignment loads. Use `getVariantAsync` (Android) or the completion form (iOS) the first time a screen needs a variant, so the user doesn't briefly see the default.

<Callout kind="note" title="A/B Testing Best Practices">
- Always track views to accurately measure conversion rates.
- Run experiments for at least 2 weeks to account for weekly patterns.
- Aim for statistical significance (95%+) before making decisions.
- Only test one thing at a time for clear results.
</Callout>

### Offline Support

Abrova A/B Testing SDKs support offline mode, so your app keeps tracking events without a network connection.

<Callout kind="note" title="How It Works">
- Events are stored on the device while offline
- Automatic sync when network connectivity is restored
- Events persist across app restarts
- Each event carries a unique `clientEventId`, saved with the event
- Each event carries the time the app recorded it, so events sent together keep their order
- At most 1,000 events are kept on the device
- The SDKs send events in batches, and wait before retrying when the service is busy or your project has reached its usage limit
- The sync endpoint accepts up to 500 events per request
</Callout>

List cache (default 300 seconds) and send interval (default 30 seconds) are set in the Console; the SDKs keep up to 1,000 events and send 100 at a time.

#### Send interval and list cache

From version 0.2.3, every SDK follows two of your project's settings in the Abrova console (**A/B Testing › Settings › Defaults**):

- **Send interval** — how often queued events are sent. The SDKs follow it unless you set your own `flushInterval` in code; then your value wins. Each platform page says how to set it.
- **List cache** — how long an SDK reuses the experiment list before it asks the service again. There is no SDK option for it. Once the list is older than that, the SDK fetches it again in the background the next time your code reads a variant or tracks an event, without blocking the call.

A change you make in the console (a new experiment, changed weights or traffic) reaches running apps within the list cache time, without a restart. A user who already has a variant keeps it. A changed send interval is picked up at that same refresh. The SDKs keep both values within safe limits. Apps on SDK versions older than 0.2.3 keep their built-in behaviour.

#### Benefits

- No lost events due to network issues
- Works in subway, airplane, rural areas
- Reduces battery usage with batched syncs
- Survives app crashes and restarts

#### Flutter

```dart
import 'package:abrova_ab_testing/abrova_ab_testing.dart';

// Offline support is always on
await AbrovaAbTesting.init(AbrovaAbTestingConfig(
  apiKey: 'YOUR_API_KEY',
  tokenProvider: fetchAbrovaToken, // returns a token from your server, or null while signed out
));
await AbrovaAbTesting.instance.setUserId('user-123');

// Events are queued automatically when offline
await AbrovaAbTesting.instance.trackConversion('checkout-flow', value: 1000000);

// Send queued events now (optional - automatic sync runs on the send interval)
await AbrovaAbTesting.instance.flush();
```

#### Android

```kotlin
import ir.abrova.abtesting.AbrovaAbTesting
import ir.abrova.abtesting.AbrovaAbTestingConfig
import ir.abrova.abtesting.AbrovaTokenProvider

// Offline support is enabled by default
AbrovaAbTesting.init(
    context = applicationContext,
    config = AbrovaAbTestingConfig(
        apiKey = "YOUR_API_KEY",
        tokenProvider = AbrovaTokenProvider { myBackend.fetchAbrovaTokenBlocking() }
    )
)

// Events are queued automatically when offline
AbrovaAbTesting.trackConversion("checkout-flow", 1000000)

// Send queued events now (optional - automatic sync runs periodically)
AbrovaAbTesting.flush()
```

#### REST API

For custom SDK implementations, use the sync endpoint to batch upload events. Send the user's token in `x-user-token`; the events are recorded for the user the token names.

```bash
curl -X POST 'https://abtest.abrova.ir/public/sync' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'x-user-token: USER_TOKEN' \
  -d '{
    "events": [
      {
        "experimentId": "checkout-flow",
        "variantId": "",
        "userId": "user-123",
        "eventType": "conversion",
        "eventName": "purchase",
        "eventValue": 1000000,
        "metadata": { "product": "premium" },
        "timestamp": 1790505000000,
        "clientEventId": "client-event-abc123"
      }
    ],
    "deviceId": "device-xyz",
    "sdkVersion": "custom-1.0.0"
  }'

# Response:
{
  "success": true,
  "synced": 1,
  "failed": 0
}
```

`experimentId` accepts the experiment key. Leave `variantId` empty to use the variant the user is assigned to.

`timestamp` is optional: the time your app recorded the event, in epoch milliseconds (an ISO 8601 string is also accepted). It keeps the events of one request in the order they happened. An event without it is still recorded.

<Callout kind="tip" title="SDK Init Endpoint">
Use the `/public/init` endpoint to fetch experiments and configuration in a single call. It returns the project's running experiments and the list cache and send interval set in the Console. It needs only the API key.
</Callout>

### Feature Flags

Toggle features on or off without deploying new code. Perfect for gradual rollouts, kill switches, and beta features.

#### Use Cases

- **Gradual Rollouts** — Release to 5% users, then 25%, then 100%
- **Kill Switches** — Instantly disable problematic features
- **Beta Features** — Enable for specific user segments
- **Seasonal Features** — Toggle holiday themes on/off

#### Flag Properties

- **Key** — Unique identifier (e.g., `new-checkout-flow`)
- **Enabled** — Whether the flag is on or off
- **Rollout %** — Percentage of users who see the feature
- **Targeting** — Rules based on user attributes

#### Pseudocode Example

```typescript
// Check if a feature is enabled for the signed-in user
const isEnabled = await AbrovaAbTesting.isFeatureEnabled("new-checkout-flow")

if (isEnabled) {
  showNewCheckoutFlow()
} else {
  showLegacyCheckout()
}

// Get a feature flag value (for multivariate flags)
const value = await AbrovaAbTesting.getFeatureValue(
  "button-color",
  "blue"  // default value
)
button.color = value

// Feature flags with user targeting
// In dashboard, set rules like:
// - Enable for users where plan = "premium"
// - Enable for users where country in ["US", "CA"]
// - Enable for 10% of all other users
```

<Callout kind="tip" title="Dashboard Setup">
1. Open **Abrova Flags** in the sidebar and go to **Feature Flags** (the A/B Testing **Feature Flags** page links there)
2. Click **Create Flag**
3. Enter a key (e.g., `new-checkout-flow`) and name
4. Set rollout percentage (0-100%)
5. Check **Enable immediately** to turn it on
</Callout>

### Mutual Exclusion Groups

Prevent users from being enrolled in multiple conflicting experiments at the same time.

<Callout kind="warn" title="Why Use Mutual Exclusion?">
If you're running two experiments that both affect the checkout flow, a user being in both could skew your results. Mutual exclusion ensures clean, uncontaminated experiment data.
</Callout>

#### Example Scenario

You have two checkout experiments:

- Experiment A: Button color test
- Experiment B: Checkout flow redesign

If a user is in both, you can't tell which change caused the conversion.

#### How It Works

1. Create an exclusion group
2. Add experiments from the same project to the group
3. Set total traffic allocation for the group
4. Each user is assigned to ONE experiment in the group

#### Example

```typescript
// Exclusion Group: "Checkout Experiments"
// Traffic Allocation: 100% (all users eligible)
// Experiments in group:
//   - checkout-button-color
//   - checkout-flow-redesign

// A user is placed in only one of them - never both.

// In your app, just call getVariant normally:
const variant = await AbrovaAbTesting.getVariant("checkout-button-color")
```

<Callout kind="tip" title="Dashboard Setup">
1. Go to **Exclusion Groups** in the sidebar
2. Click **Create Group**
3. Name your group (e.g., "Checkout Experiments")
4. Set traffic allocation (% of users eligible for this group)
5. Select which experiments belong to this group
</Callout>

### Holdout Groups

Measure the cumulative impact of your entire experimentation program by excluding a percentage of users from ALL experiments.

<Callout kind="note" title="What is a Holdout Group?">
A holdout group is a percentage of users (typically 5-10%) who never see any experiments. They always get the control experience. By comparing the holdout group to users who participate in experiments, you can measure the overall value of your experimentation program.
</Callout>

<BestPracticeList columns={3} items={[
  ['Holdout Users', 'Always see the control experience. Never enrolled in any experiment.'],
  ['Experiment Users', 'Participate in experiments as normal. May be in control or variant groups.'],
  ['Comparison', 'Settings in the Console shows how many users are in the holdout and how many are in experiments.'],
]} />

#### In your app

Nothing changes in your code. For a holdout user, `getVariant()` returns the control variant for every experiment, so they see the default experience:

```typescript
const variant = await AbrovaAbTesting.getVariant("checkout-experiment")
applyVariant(variant) // the control variant for holdout users
```

Tracking calls are always safe to make: you don't need to check whether the user is in an experiment before you track. The service decides what counts, and events of a user who is kept out of an experiment never enter that experiment's results.

<Callout kind="tip" title="Dashboard Setup">
1. Go to **Settings** in the sidebar
2. Find **Holdout Group Configuration**
3. Toggle **Enable Holdout Group**
4. Set percentage (recommended: 5-10%)
5. Click **Save Holdout Settings**
</Callout>

### Webhooks

Get notified in real time when an experiment changes state. Each webhook belongs to one project and receives only that project's events.

#### Events

- `experiment.started` — Experiment goes live
- `experiment.paused` — Experiment paused
- `experiment.completed` — Experiment ends
- `experiment.archived` — Experiment archived

#### Use Cases

- Post to your team chat when experiments start or end
- Trigger CI/CD pipelines when an experiment completes
- Update external systems with experiment status

#### Webhook Payload Example

```text
POST https://your-server.com/webhooks/abrova-ab-testing
Content-Type: application/json
X-AbrovaAbTesting-Event: experiment.completed
X-AbrovaAbTesting-Webhook-Id: 7c1f…
X-AbrovaAbTesting-Timestamp: 2026-09-27T10:30:00.000Z
X-AbrovaAbTesting-Signature: 5d41402abc4b2a76b9719d911017c592…

{
  "event": "experiment.completed",
  "timestamp": "2026-09-27T10:30:00.000Z",
  "webhookId": "7c1f…",
  "experimentId": "…",
  "experimentKey": "checkout-button-color",
  "experimentName": "Checkout Button Color",
  "status": "completed",
  "endDate": "2026-09-27T10:30:00.000Z"
}
```

#### Verifying the signature

When you set a secret, `X-AbrovaAbTesting-Signature` is the hex HMAC-SHA256 of the raw request body, keyed with your secret:

```typescript
import { createHmac, timingSafeEqual } from 'crypto';

function isValid(rawBody: string, signature: string, secret: string) {
  const expected = createHmac('sha256', secret).update(rawBody).digest('hex');
  return expected.length === signature.length &&
    timingSafeEqual(Buffer.from(expected), Buffer.from(signature));
}
```

Webhook URLs must be public `http(s)` addresses. Failed deliveries are retried.

<Callout kind="tip" title="Dashboard Setup">
1. Pick your project in the sidebar and go to **Webhooks**
2. Click **Create Webhook**
3. Enter your endpoint URL
4. Select which events to receive
5. (Optional) Add a secret for signature verification
6. Click **Test** to verify it works
</Callout>

### REST API

Use the REST API directly for platforms without an SDK. Calls that act for a user need the user's token in `x-user-token` (see **User tokens** above); from your own server you can send `x-server-secret` instead.

#### Get Variant Assignment

```bash
curl -X POST 'https://abtest.abrova.ir/public/assign' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'x-user-token: USER_TOKEN' \
  -d '{
    "experimentKey": "checkout-button-color",
    "userId": "user-123",
    "userAttributes": {
      "plan": "premium",
      "country": "US"
    }
  }'

# Response:
{
  "data": {
    "experimentId": "…",
    "experimentKey": "checkout-button-color",
    "variantId": "…",
    "variantKey": "variant-a",
    "variantName": "Variant A",
    "config": { "buttonColor": "#22C55E", "buttonText": "Buy Now" },
    "isControl": false,
    "isNew": true
  }
}
```

#### Track Events

Send events with `/public/sync` (see **Offline Support** above). It accepts experiment keys and up to 500 events per request.

#### Evaluate a Feature Flag

```bash
curl -X POST 'https://abtest.abrova.ir/public/flag-evaluation' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'x-user-token: USER_TOKEN' \
  -d '{
    "flagKey": "new-checkout-flow",
    "userId": "user-123",
    "userAttributes": {
      "plan": "premium"
    }
  }'

# Response:
{
  "flagKey": "new-checkout-flow",
  "enabled": true,
  "value": "variant-b"
}
```

#### Errors

A request that acts for a user without a valid token is refused with `401` and a `code`:

- `token_required` — no user token was sent
- `token_expired` — the token expired; fetch a new one and retry
- `token_invalid` — the token is not valid for this project

### Where to next?

- **Platform SDK docs** — Android, iOS, Flutter, React Native, Next.js, Node.js — for install + code examples
- **Feature Flags SDK** — standalone feature flags package if you don't need experiments

All Abrova A/B Testing SDKs share the same dashboard, the same API key, and the same user token. Pick the SDK for your platform and you're up and running in minutes.

- AI assistants: https://abrova.ir/en/docs/ab-testing/ai-assistants

<Callout kind="soon" title="Coming soon">
Abrova does not have a docs server for AI assistants yet. This page describes how it will work and what you can use today.
</Callout>

When it is ready, you connect your AI assistant (any tool that supports MCP, the open standard AI tools use to connect to outside sources) once. Then, when you ask it to add Abrova A/B Testing to your project, it looks up the current SDK version, install lines and setup steps from these docs instead of answering from memory.

### What works today

- **Copy page for AI.** Every docs page has a **Copy page for AI** link. Paste the page into your assistant's chat before you ask it to write code.
- **Plain-text docs.** Give your assistant the address `https://abrova.ir/docs/llms.txt`. It lists every docs page as plain text that assistants read well.

Tell your assistant to follow the page you gave it, and to use the placeholder keys from the docs.

### What it will do

The docs server will have read-only tools. Your assistant chooses them by itself; you do not call them by hand.

<ConfigTable headers={['Tool', 'What it will do']} rows={[
  ['list_products', 'Lists the Abrova products, with the platforms that have an SDK and the docs link.'],
  ['search_docs', 'Searches the docs for a few words or a short question and returns the best pages.'],
  ['read_doc', 'Returns one docs page as text, with its link and last-updated date.'],
  ['get_sdk_info', 'Returns the SDK package for a product and platform: name, current version and install lines.'],
  ['get_setup_guide', 'Returns the ordered setup steps for a product and platform: install, keys, initialization and how to test.'],
]} />

Examples of what you will be able to ask:

- **"Run an A/B test on the paywall in my Flutter app and count purchases as the conversion."** It would answer from [Getting started](/docs/ab-testing/quick-start) and [Flutter SDK](/docs/ab-testing/flutter).
- **"Assign the variant on my Node.js server and track the purchase there."** It would answer from [Node.js SDK](/docs/ab-testing/nodejs).
- **"Use the feature-flags add-on in my Android app."** It would answer from [Android SDK](/docs/ab-testing/android) and [Feature flags SDK](/docs/ab-testing/feature-flags-sdk).

### Privacy

- **What it reads:** the public Abrova docs, the current SDK versions, and the words your assistant sends (the search words, the page it wants, the product and platform names).
- **What it never sees:** your code, your files, your Abrova project, your keys or your users. The tools have no input for them, and they cannot change any setting.

<Callout kind="warn" title="Keep your keys out of the chat">
Never paste a key into a chat with an AI assistant. Your assistant writes the placeholder from the docs (`ab_live_your_api_key`); you put the real value in your project's configuration yourself. The server secret (`ab_srv_...`) belongs only on your server, in an environment variable.
</Callout>

More about AI assistants and Abrova: [AI assistants](/ai-assistants). Questions? [Contact us](/contact).

- Android: https://abrova.ir/en/docs/ab-testing/android

<Callout kind="note" title="AbrovaAbTesting Android SDK v0.2.3">
Native Kotlin SDK for A/B testing, feature flags, and event tracking on Android. Server-side variant assignment, an offline-first event queue that survives app restarts, and 17 built-in event types. Anything done on behalf of a user needs a signed user token; you can initialize the SDK before sign-in and it waits for the token. Installs from Abrova Center.
</Callout>

<Callout kind="note" title="Requirements">
- Android SDK 21 (Lollipop) or higher.
- Kotlin 1.9.0 or higher.
- Android Gradle Plugin 8.0 or higher.
- A backend endpoint that returns an Abrova user token for the signed-in user (see step 3, User tokens).
</Callout>

<H2 id="installation" step={1}>Installation</H2>

Install from Abrova Center in two steps. First add the Abrova Center repository in `settings.gradle` (or the project `build.gradle`):

```groovy
repositories {
    google()
    mavenCentral()
    maven { url "https://center.abrova.ir/api/packages/abrova/maven" }
}
```

Then add the dependency in your app's `build.gradle.kts`:

```kotlin
dependencies {
    implementation("ir.abrova:abrova-ab-testing-android:0.2.3")
}
```

#### Add Internet permission

In your `AndroidManifest.xml`:

```xml
<uses-permission android:name="android.permission.INTERNET" />
```

<H2 id="initialization" step={2}>Initialization</H2>

Initialize AbrovaAbTesting once, in your `Application` class. Pass a `tokenProvider` so the SDK can get a user token from your backend.

```kotlin
import android.util.Log
import ir.abrova.abtesting.Experiment
import ir.abrova.abtesting.AbrovaAbTesting
import ir.abrova.abtesting.AbrovaAbTestingCallback
import ir.abrova.abtesting.AbrovaAbTestingConfig
import ir.abrova.abtesting.AbrovaAbTestingError
import ir.abrova.abtesting.AbrovaTokenProvider
import ir.abrova.abtesting.models.FeatureFlag

val config = AbrovaAbTestingConfig(
    apiKey = "YOUR_API_KEY",
    // Runs on a background thread, so a blocking call to your backend is fine.
    // Return null while no one is signed in.
    tokenProvider = AbrovaTokenProvider { myBackend.fetchAbrovaTokenBlocking() },
    debug = BuildConfig.DEBUG,
    // flushInterval = 10000L,  // Your own send interval in ms. Leave it out to follow the console
    maxQueueSize = 100       // Max events before auto-flush
)

AbrovaAbTesting.init(this, config, object : AbrovaAbTestingCallback {
    override fun onInitialized() {
        Log.d("Abrova", "SDK initialized")
    }

    override fun onExperimentAssigned(experimentKey: String, variantKey: String, config: Map<String, Any>?) {
        Log.d("Abrova", "Assigned: $experimentKey -> $variantKey")
    }

    override fun onExperimentsRefreshed(experiments: List<Experiment>) {
        Log.d("Abrova", "Refreshed ${experiments.size} experiments")
    }

    override fun onFeatureFlagsRefreshed(flags: List<FeatureFlag>) {
        Log.d("Abrova", "Refreshed ${flags.size} flags")
    }

    override fun onSyncCompleted(synced: Int, failed: Int, pending: Int) {
        Log.d("Abrova", "Synced: $synced, failed: $failed, pending: $pending")
    }

    override fun onOnlineMode() {
        Log.d("Abrova", "Back online")
    }

    override fun onOfflineMode() {
        Log.d("Abrova", "Offline")
    }

    override fun onError(error: AbrovaAbTestingError) {
        Log.e("Abrova", "Error: ${error.message}")
    }
})
```

The callback is optional and every method has an empty default, so override only what you need. Callbacks run on the main thread. You can add or remove listeners later with `addCallback()` and `removeCallback()`.

`onSyncCompleted` is called each time queued events have been sent: `synced` is the number the service stored, `failed` the number it turned down, and `pending` the number still waiting on the device.

No SDK method throws when you call it before `init`, before the first load has finished or before a user is signed in: getters return the default you pass and the `track…` methods do nothing. If the first load fails (no network), the SDK works from its cache and loads again when the network is back.

#### Configuration

<ConfigTable rows={[
  ['apiKey', 'String', '-', 'Your project API key (required)'],
  ['tokenProvider', 'AbrovaTokenProvider?', 'null', 'Returns a user token minted by your backend, or null while no one is signed in. Required for assigning variants, tracking and server flag evaluation'],
  ['userToken', 'String?', 'null', 'A token you already hold. Prefer tokenProvider: a fixed token stops working when it expires. Hand over a newer one with setUserToken()'],
  ['debug', 'Boolean', 'false', 'Log to Logcat. Logs never include your API key or request bodies'],
  ['flushInterval', 'Long', '30000', 'How often queued events are sent, in milliseconds. Left at the default, the SDK follows the Send interval set in the Abrova console (see below)'],
  ['maxQueueSize', 'Int', '100', 'Queued events that trigger a flush'],
]} />

#### Send interval and list cache

Two values come from your project's settings in the Abrova console (**A/B Testing › Settings › Defaults**):

- **Send interval** — how often queued events are sent. The SDK follows it unless you set your own `flushInterval`. On Android, any value other than the default, `AbrovaAbTestingConfig.DEFAULT_FLUSH_INTERVAL` (30 seconds), is your own and is always used. A config that sets exactly `30000L` is treated as the default and follows the console.
- **List cache** — how long the SDK uses the experiment list before it asks the service again. There is no SDK option for it. Once the list is older than that, the SDK fetches it again in the background the next time your code reads a variant or tracks an event. The call doesn't wait for it, and a failed refresh is not reported to `onError`.

A change you make in the console (a new experiment, changed weights or traffic) reaches running apps within the list cache time, without a restart. A user who already has a variant keeps it. A changed send interval is picked up at that same refresh. The SDK keeps the console's values within safe limits, and sends every 30 seconds until it knows the console's value. Apps on SDK versions older than 0.2.3 keep their built-in behaviour.

<H2 id="user-tokens" step={3}>User tokens</H2>

The API key ships inside your app, so it can't prove which user a request is for. A **user token** can. Your backend mints it with your project's server secret, the SDK sends it with each request, and Abrova takes the user from the token.

A token is **required** to get a variant from the server, track events and conversions, sync queued events, and evaluate flags on the server. Loading the experiment and flag lists needs only the API key, so your app can fetch them before anyone signs in.

#### Mint the token on your backend

Add one endpoint, protected by your own login, that calls Abrova and returns the token to the signed-in user:

```bash
curl -X POST https://auth.abrova.ir/users/token \
  -H "x-api-key: $ABROVA_API_KEY" \
  -H "x-server-secret: $ABROVA_SERVER_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"userId": "user-123", "expiresIn": 3600}'

# → { "token": "eyJhbGciOi…", "userId": "user-123", "expiresIn": 3600, "expiresAt": "…" }
```

`expiresIn` is in seconds: 3600 (1 hour) by default, 86400 (24 hours) maximum. The service takes the user from the token, so if you call `setUserId()` in the app, pass the same `userId`.

<Callout kind="warn" title="Never ship the server secret">
The server secret can mint a token for **any** user. Keep it on your server, out of your APK, app bundle and source code.
</Callout>

#### One token for A/B Testing, Chat and Sync

This is the same Abrova user token that Abrova Chat and Abrova Sync use. If your app uses more than one of them, mint **one** token and give it to every SDK's `tokenProvider` instead of fetching one per product.

#### Give the token to the SDK

`AbrovaTokenProvider.fetchToken()` runs on a background thread, so it may block (for example, a synchronous HTTP call to your backend). The SDK caches the token, asks for a new one shortly before it expires, and asks once more if Abrova reports it expired.

```kotlin
val tokenProvider = AbrovaTokenProvider {
    // No one signed in: return null (or throw). The SDK then waits for a token.
    val session = sessionStore.current() ?: return@AbrovaTokenProvider null
    myBackend.fetchAbrovaTokenBlocking(session)
}
```

If you would rather hand tokens over yourself, leave `tokenProvider` out and call `AbrovaAbTesting.setUserToken(token)` after sign-in and whenever you refresh the token. A token passed as `userToken` in the config works the same way: it isn't refreshed, so hand over a newer one before it expires.

#### Before your user signs in

You can call `init` before anyone is signed in. Without a token the SDK waits instead of failing:

- `AbrovaAbTesting.isAwaitingUserToken` is `true`, and `onAwaitingUserToken` is called once, on the main thread, each time the SDK starts waiting.
- `getVariant` and `getVariantAsync` return the default you pass.
- Nothing is sent for a user and no error is reported. Events you track are kept on the device (at most 1,000).

The SDK carries on by itself as soon as it has a token: it fetches the variants your app asked for (`onExperimentAssigned` is called for each) and sends the kept events.

```kotlin
AbrovaAbTesting.onAwaitingUserToken = { /* e.g. show the default experience */ }

// After sign-in
AbrovaAbTesting.refreshUserToken()      // with a tokenProvider: asks it again now
AbrovaAbTesting.setUserToken(token)     // without one: hand the token over

// After sign-out
AbrovaAbTesting.clearUserId()           // or setUserToken(null)
```

Events are credited to the user in the token. Events recorded before sign-in are only sent if they were recorded for the same user id that signs in, so call `setUserId()` with the id your backend puts in the token before you track. Events recorded for an anonymous user are not credited to anyone and are dropped at sign-in.

<Callout kind="note" title="Keep it on the device">
A token is valid until it expires, so store it with the user's session (Keystore or encrypted storage) and reuse it across app launches. Your `tokenProvider` then only calls your backend when the stored token is close to expiry, not on every start.
</Callout>

<H2 id="user-identification" step={4}>User Identification</H2>

The user token decides who the user is: once the SDK has a token, it acts as the user that token was minted for. Call `setUserId()` with that same ID when a user signs in, and `clearUserId()` when they sign out. Until there is a user, the SDK uses a random ID it generates on first launch.

```kotlin
// After login — use the same ID your backend mints the token for
AbrovaAbTesting.setUserId("user-123")
AbrovaAbTesting.refreshUserToken()   // or setUserToken(token) if you hand tokens over yourself

// After logout — forget the user and wait for the next token
AbrovaAbTesting.clearUserId()

// Get current user ID
val userId = AbrovaAbTesting.getUserId()

// Set user attributes for targeting rules
AbrovaAbTesting.setUserAttributes(mapOf(
    "plan" to "premium",
    "country" to "US",
    "age" to 25
))
```

A different user ID (`setUserId()`), a token for another user, or a sign-out (`clearUserId()`, `setUserToken(null)`) is a user switch. The SDK clears the previous user's variants, attributes, token and pending events before it does anything for the next user. Events of the previous user that are ready to send go out once more under that user's own token, never under another user's. Set the user attributes again after a switch.

<H2 id="experiments" step={5}>Experiments</H2>

Get the variant assigned to the current user for an experiment. The variant always comes from the service (this needs a user token) and is then kept on the device; the SDK never picks one itself.

```kotlin
// Asynchronous (recommended) — waits for the service's answer;
// the result is delivered on the main thread
AbrovaAbTesting.getVariantAsync("checkout-redesign") { variant ->
    when (variant) {
        "variant-a" -> showNewCheckout()
        "variant-b" -> showMinimalCheckout()
        else -> showOriginalCheckout()  // control
    }
}

// Synchronous — never blocks, safe on the main thread
val variant = AbrovaAbTesting.getVariant(
    experimentKey = "checkout-redesign",
    defaultVariant = "control"  // returned until the service has answered
)

// Get variant config (colors, text, etc.) — available once a variant is assigned
val config = AbrovaAbTesting.getVariantConfig("checkout-redesign")
val buttonColor = config?.get("button_color") as? String ?: "#6B7280"
val layout = config?.get("layout") as? String ?: "default"

// List all experiments (API key only)
val experiments = AbrovaAbTesting.getExperiments()

// Refresh from server
AbrovaAbTesting.refreshExperiments()
```

`getVariant` returns the variant the service assigned earlier. The first time you ask for an experiment it returns `defaultVariant` at once and fetches the assignment in the background; `onExperimentAssigned` tells you when it has arrived. Use `getVariantAsync` the first time a screen needs the variant, otherwise the user may briefly see the default before their real variant.

You get `defaultVariant` back when the experiment isn't running, the user doesn't match its targeting rules, there is no user token yet, or the service can't be reached and nothing is stored. A user the service keeps out of an experiment (targeting, traffic allocation) gets the control variant. Tracking calls are always safe to make: you don't need to check whether the user is in the experiment before you track. The SDK sends these events like any other and the service decides what counts; they never enter the experiment's results.

<H2 id="feature-flags" step={6}>Feature Flags</H2>

Toggle features remotely with targeting rules and rollout percentages.

```kotlin
// Local evaluation against the cached flag list
val darkMode = AbrovaAbTesting.isFeatureEnabled("dark-mode")

// Server-side evaluation (needs a user token; falls back to local evaluation)
AbrovaAbTesting.isFeatureEnabledAsync("dark-mode") { enabled ->
    if (enabled) enableDarkMode()
}

// Get feature flag value
val maxUpload = AbrovaAbTesting.getFeatureValue("max-upload-size", defaultValue = 10)

// Get all flags
val flags = AbrovaAbTesting.getFeatureFlags()
flags.forEach { flag ->
    Log.d("Abrova", "${flag.key}: enabled=${flag.enabled}, rollout=${flag.rolloutPercentage}%")
}

// Refresh flags from server
AbrovaAbTesting.refreshFeatureFlags()
```

<H2 id="event-tracking" step={7}>Event Tracking</H2>

Track user interactions with 17 built-in event types. Events are credited to the variant the user was assigned, so call `getVariant()` or `getVariantAsync()` for an experiment before tracking events for it. Events tracked while the assignment is still loading (or while the SDK waits for a user token) are kept and sent once the variant is known; events for an experiment you never asked a variant for are dropped.

#### Core Events

```kotlin
AbrovaAbTesting.trackView("experiment-key")
AbrovaAbTesting.trackClick("experiment-key")
AbrovaAbTesting.trackConversion("experiment-key", 500000.0)

AbrovaAbTesting.trackCustomEvent(
    "experiment-key",
    "button_hover",
    mapOf("duration_ms" to 1500, "element" to "cta_button")
)
```

#### Conversion Events

```kotlin
AbrovaAbTesting.trackAddToCart("experiment-key", 300000.0, "sku-123", mapOf("quantity" to 2))
AbrovaAbTesting.trackRemoveFromCart("experiment-key", 300000.0, "sku-123")
AbrovaAbTesting.trackBeginCheckout("experiment-key", 1500000.0)
AbrovaAbTesting.trackPurchase("experiment-key", 1250000.0, "txn-12345", mapOf("currency" to "Toman"))
```

#### Engagement Events

```kotlin
AbrovaAbTesting.trackScroll("experiment-key", 75.0)
AbrovaAbTesting.trackFormSubmit("experiment-key", "signup-form")
AbrovaAbTesting.trackSearch("experiment-key", "shoes")
AbrovaAbTesting.trackShare("experiment-key", "twitter")
```

#### Media & Auth Events

```kotlin
AbrovaAbTesting.trackVideoStart("experiment-key", "vid-001")
AbrovaAbTesting.trackVideoComplete("experiment-key", "vid-001")

AbrovaAbTesting.trackSignUp("experiment-key", "google")
AbrovaAbTesting.trackLogin("experiment-key", "email")
AbrovaAbTesting.trackLogout("experiment-key")
```

#### Generic Event

```kotlin
import ir.abrova.abtesting.models.EventType

AbrovaAbTesting.track(
    experimentKey = "experiment-key",
    eventType = EventType.CUSTOM,
    eventName = "page_load_time",
    eventValue = 2.3,
    properties = mapOf("page" to "/checkout", "cached" to false)
)
```

<H2 id="offline-support" step={8}>Offline Support</H2>

<Callout kind="note" title="Offline-First Architecture">
Events are queued when offline and synced when connectivity returns. Experiments, feature flags and assignments are cached locally. Queued events persist across app restarts via SharedPreferences.
</Callout>

The queue holds at most 1,000 events; when it is full, the oldest are dropped first. Events are sent 100 at a time. When the service can't be reached, asks the SDK to slow down, or your project has reached its usage limit, the SDK waits before it tries again. Each event carries the time your app recorded it, so events sent together keep their order.

```kotlin
// Check online status
val online = AbrovaAbTesting.isOnline

// Get pending event count
val pending = AbrovaAbTesting.getPendingEventCount()

// Force sync pending events
AbrovaAbTesting.flush()
```

<H2 id="lifecycle-sync" step={9}>Lifecycle & Sync</H2>

```kotlin
class MyActivity : AppCompatActivity() {
    override fun onStop() {
        super.onStop()
        AbrovaAbTesting.flush()  // Sync events when activity stops
    }

    override fun onResume() {
        super.onResume()
        AbrovaAbTesting.refreshExperiments()  // Refresh on resume
    }
}

// Clear cached experiments, flags, assignments and the token.
// Mainly for tests — call init() again before using the SDK.
AbrovaAbTesting.reset()

// Stop the event queue and network listener
AbrovaAbTesting.dispose()
```

To switch users, use `setUserId()` on login and `clearUserId()` on logout rather than `reset()`.

### EventType Enum

<ConfigTable rows={[
  ['VIEW', '-', '-', 'view'],
  ['CLICK', '-', '-', 'click'],
  ['CONVERSION', '-', '-', 'conversion'],
  ['CUSTOM', '-', '-', 'custom'],
  ['SCROLL', '-', '-', 'scroll'],
  ['FORM_SUBMIT', '-', '-', 'form_submit'],
  ['SEARCH', '-', '-', 'search'],
  ['SHARE', '-', '-', 'share'],
  ['ADD_TO_CART', '-', '-', 'add_to_cart'],
  ['REMOVE_FROM_CART', '-', '-', 'remove_from_cart'],
  ['BEGIN_CHECKOUT', '-', '-', 'begin_checkout'],
  ['PURCHASE', '-', '-', 'purchase'],
  ['VIDEO_START', '-', '-', 'video_start'],
  ['VIDEO_COMPLETE', '-', '-', 'video_complete'],
  ['SIGN_UP', '-', '-', 'sign_up'],
  ['LOGIN', '-', '-', 'login'],
  ['LOGOUT', '-', '-', 'logout'],
]} />

### API Reference

<ConfigTable rows={[
  ['init(context, config, callback?)', '-', '-', 'Initialize the SDK'],
  ['setUserId(id)', '-', '-', 'Set user ID; call on login'],
  ['clearUserId()', '-', '-', 'Sign-out: forget the user and wait for a token'],
  ['setUserToken(token)', '-', '-', 'Hand over a user token (null after sign-out)'],
  ['refreshUserToken()', '-', '-', 'Ask the tokenProvider again now (after sign-in or sign-out)'],
  ['isAwaitingUserToken', '-', '-', 'true while the SDK waits for a user token'],
  ['onAwaitingUserToken', '-', '-', 'Called once each time the SDK starts waiting'],
  ['getUserId()', '-', '-', 'Get current user ID'],
  ['setUserAttributes(attrs)', '-', '-', 'Set targeting attributes'],
  ['getVariant(key, default)', '-', '-', 'Get assigned variant (never blocks; default until the service has answered)'],
  ['getVariantAsync(key, default, cb)', '-', '-', 'Get assigned variant (waits for the service)'],
  ['getVariantConfig(key)', '-', '-', 'Get variant configuration'],
  ['isFeatureEnabled(key, default)', '-', '-', 'Check flag (local evaluation)'],
  ['isFeatureEnabledAsync(key, default, cb)', '-', '-', 'Check flag (server evaluation)'],
  ['getFeatureValue(key, default)', '-', '-', 'Get feature flag value'],
  ['getFeatureFlags()', '-', '-', 'Get all feature flags'],
  ['refreshFeatureFlags()', '-', '-', 'Refresh flags from server'],
  ['getExperiments()', '-', '-', 'Get all experiments'],
  ['refreshExperiments()', '-', '-', 'Refresh experiments from server'],
  ['track(key, type, name?, value?, props?)', '-', '-', 'Track any event type'],
  ['addCallback(cb) / removeCallback(cb)', '-', '-', 'Add or remove an SDK listener'],
  ['isOnline', '-', '-', 'Whether the device is online'],
  ['getPendingEventCount()', '-', '-', 'Number of queued events'],
  ['flush()', '-', '-', 'Force sync pending events'],
  ['reset()', '-', '-', 'Clear all state, cache and token'],
  ['dispose()', '-', '-', 'Release resources'],
]} />

### Complete Example

Full integration with user tokens, experiments, feature flags, and event tracking:

```kotlin
class MyApp : Application() {
    override fun onCreate() {
        super.onCreate()
        AbrovaAbTesting.init(this, AbrovaAbTestingConfig(
            apiKey = "YOUR_API_KEY",
            // Returns null while no one is signed in
            tokenProvider = AbrovaTokenProvider { myBackend.fetchAbrovaTokenBlocking() }
        ))
    }
}

// In your login flow, once your backend knows the user
fun onLoggedIn(user: User) {
    AbrovaAbTesting.setUserId(user.id)   // the ID your backend puts in the token
    AbrovaAbTesting.refreshUserToken()   // asks tokenProvider again now
    AbrovaAbTesting.setUserAttributes(mapOf("plan" to user.plan, "country" to user.country))
}

// In your logout flow
fun onLoggedOut() {
    AbrovaAbTesting.clearUserId()
}

class CheckoutActivity : AppCompatActivity() {

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_checkout)

        // Check feature flag
        if (AbrovaAbTesting.isFeatureEnabled("dark-mode")) applyDarkTheme()

        // Get experiment variant, then track the view
        AbrovaAbTesting.getVariantAsync("checkout-redesign") { variant ->
            val config = AbrovaAbTesting.getVariantConfig("checkout-redesign")
            setupCheckout(variant, config)
            AbrovaAbTesting.trackView("checkout-redesign")
        }
    }

    private fun setupCheckout(variant: String, config: Map<String, Any>?) {
        val button = findViewById<Button>(R.id.checkoutButton)
        button.text = config?.get("text") as? String ?: "Complete Purchase"

        val colorHex = config?.get("color") as? String ?: when (variant) {
            "variant-a" -> "#22C55E"
            "variant-b" -> "#3B82F6"
            else -> "#6B7280"
        }
        button.setBackgroundColor(Color.parseColor(colorHex))

        button.setOnClickListener {
            AbrovaAbTesting.trackClick("checkout-redesign")
            processCheckout()
        }
    }

    private fun processCheckout() {
        // ... checkout logic ...
        AbrovaAbTesting.trackPurchase("checkout-redesign", orderTotal, "txn-123")
    }

    override fun onStop() {
        super.onStop()
        AbrovaAbTesting.flush()
    }
}
```

### ProGuard / R8 Configuration

The SDK ships consumer rules that keep its classes, so most apps need no extra configuration. If your own rules strip generic signatures or annotations that Gson relies on, add:

```text
# Gson (used by AbrovaAbTesting)
-keepattributes Signature
-keepattributes *Annotation*
-keep class com.google.gson.** { *; }
```

- iOS: https://abrova.ir/en/docs/ab-testing/ios

<Callout kind="note" title="AbrovaAbTesting iOS SDK v0.2.3">
Native Swift SDK for A/B testing and feature flags on iOS. SwiftUI-friendly with delegate callbacks, 17 built-in event types, and an offline-first event queue. Anything done on behalf of a user needs a signed user token; you can initialize the SDK before sign-in and it waits for the token. Installs with Swift Package Manager.
</Callout>

<Callout kind="note" title="Requirements">
- iOS 13.0 or higher.
- Swift 5.7 or higher.
- Xcode 14.0 or higher.
- A backend endpoint that returns an Abrova user token for the signed-in user (see step 3, User tokens).
</Callout>

<H2 id="installation" step={1}>Installation</H2>

Install the SDK with Swift Package Manager.

In Xcode: **File → Add Package Dependencies**, enter the URL below and choose version **0.2.3**:

```text
https://github.com/Abrova-co/abrova-ab-testing-ios-sdk.git
```

Or add to your `Package.swift`:

```swift
dependencies: [
    .package(url: "https://github.com/Abrova-co/abrova-ab-testing-ios-sdk.git", from: "0.2.3")
]
```

Then import the module:

```swift
import AbrovaAbTesting
```

<H2 id="initialization" step={2}>Initialization</H2>

Initialize AbrovaAbTesting once, in your AppDelegate or App struct. Pass a `tokenProvider` so the SDK can get a user token from your backend.

```swift
import AbrovaAbTesting

let config = AbrovaAbTestingConfig(
    apiKey: "YOUR_API_KEY",
    debug: true,           // Log to the console (development only)
    // flushInterval: 10.0, // Your own send interval in seconds. Leave it out to follow the console
    maxQueueSize: 100,     // Max events before auto-flush (default: 100)
    tokenProvider: { completion in
        // Ask YOUR backend for an Abrova user token (see step 3).
        // Complete with .failure while no one is signed in.
        MyBackend.fetchAbrovaToken { result in completion(result) }
    }
)

AbrovaAbTesting.shared.initialize(config: config, delegate: self)
```

No SDK method stops your app when you call it before `initialize`, before the first load has finished or before a user is signed in: getters return the default you pass and the `track…` methods do nothing. If the first load fails (no network), the SDK works from its cache and loads again when the network is back.

#### Configuration

<ConfigTable rows={[
  ['apiKey', 'String', '-', 'Your project API key (required)'],
  ['tokenProvider', 'AbrovaTokenProvider?', 'nil', 'Returns a user token minted by your backend, or fails while no one is signed in. Required for assigning variants, tracking and server flag evaluation'],
  ['userToken', 'String?', 'nil', 'A token you already hold. Prefer tokenProvider: a fixed token stops working when it expires. Hand over a newer one with setUserToken(_:)'],
  ['debug', 'Bool', 'false', 'Log to the console. Logs never include your API key, tokens or request bodies'],
  ['flushInterval', 'TimeInterval?', 'nil', 'How often queued events are sent, in seconds. Leave it out (or pass nil) to follow the Send interval set in the Abrova console (see below)'],
  ['maxQueueSize', 'Int', '100', 'Queued events that trigger a flush'],
]} />

#### Send interval and list cache

Two values come from your project's settings in the Abrova console (**A/B Testing › Settings › Defaults**):

- **Send interval** — how often queued events are sent. The SDK follows it when you leave `flushInterval` out or pass `nil`. A value you pass is your own and is always used.
- **List cache** — how long the SDK uses the experiment list before it asks the service again. There is no SDK option for it. Once the list is older than that, the SDK fetches it again in the background the next time your code reads a variant or tracks an event. The call doesn't wait for it, and a failed refresh is not reported to the delegate's `didReceiveError`.

A change you make in the console (a new experiment, changed weights or traffic) reaches running apps within the list cache time, without a restart. A user who already has a variant keeps it. A changed send interval is picked up at that same refresh. The SDK keeps the console's values within safe limits, and sends every 30 seconds until it knows the console's value. Apps on SDK versions older than 0.2.3 keep their built-in behaviour.

<H2 id="user-tokens" step={3}>User tokens</H2>

The API key ships inside your app, so it can't prove which user a request is for. A **user token** can. Your backend mints it with your project's server secret, the SDK sends it with each request, and Abrova takes the user from the token.

A token is **required** to get a variant from the server, track events and conversions, sync queued events, and evaluate flags on the server. Loading the experiment and flag lists needs only the API key, so your app can fetch them before anyone signs in.

#### Mint the token on your backend

Add one endpoint, protected by your own login, that calls Abrova and returns the token to the signed-in user:

```bash
curl -X POST https://auth.abrova.ir/users/token \
  -H "x-api-key: $ABROVA_API_KEY" \
  -H "x-server-secret: $ABROVA_SERVER_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"userId": "user-123", "expiresIn": 3600}'

# → { "token": "eyJhbGciOi…", "userId": "user-123", "expiresIn": 3600, "expiresAt": "…" }
```

`expiresIn` is in seconds: 3600 (1 hour) by default, 86400 (24 hours) maximum. The service takes the user from the token, so if you call `setUserId(_:)` in the app, pass the same `userId`.

<Callout kind="warn" title="Never ship the server secret">
The server secret can mint a token for **any** user. Keep it on your server, out of your app binary and source code.
</Callout>

#### One token for A/B Testing, Chat and Sync

This is the same Abrova user token that Abrova Chat and Abrova Sync use. If your app uses more than one of them, mint **one** token and give it to every SDK's `tokenProvider` instead of fetching one per product.

#### Give the token to the SDK

`tokenProvider` is an `AbrovaTokenProvider`: a closure that receives a completion handler. Call `completion` with `.success(token)` or `.failure(error)`, from any thread. The SDK caches the token, asks for a new one shortly before it expires, and asks once more if Abrova reports it expired; requests made at the same time share one call. A provider that never calls `completion` counts as having no token after 15 seconds.

```swift
let tokenProvider: AbrovaTokenProvider = { completion in
    // No one signed in: complete with .failure. The SDK then waits for a token.
    guard let session = SessionStore.shared.current else {
        completion(.failure(AuthError.notSignedIn))
        return
    }
    MyBackend.fetchAbrovaToken(for: session) { result in
        completion(result) // Result<String, Error>
    }
}
```

If you would rather hand tokens over yourself, leave `tokenProvider` out and call `AbrovaAbTesting.shared.setUserToken(token)` after sign-in and whenever you refresh the token. A token passed as `userToken` in the config works the same way: it isn't refreshed, so hand over a newer one before it expires.

#### Before your user signs in

You can call `initialize` before anyone is signed in. Without a token the SDK waits instead of failing:

- `AbrovaAbTesting.shared.isAwaitingUserToken` is `true`, and `onAwaitingUserToken` is called once, on the main thread, each time the SDK starts waiting.
- Both forms of `getVariant` return the default you pass.
- Nothing is sent for a user and no error is reported. Events you track are kept on the device (at most 1,000).

The SDK carries on by itself as soon as it has a token: it fetches the variants your app asked for (the delegate's `didAssignVariant` is called for each) and sends the kept events.

```swift
AbrovaAbTesting.shared.onAwaitingUserToken = { /* e.g. show the default experience */ }

// After sign-in
AbrovaAbTesting.shared.refreshUserToken()      // with a tokenProvider: asks it again now
AbrovaAbTesting.shared.setUserToken(token)     // without one: hand the token over

// After sign-out
AbrovaAbTesting.shared.clearUserId()           // or setUserToken(nil)
```

Events are credited to the user in the token. Events recorded before sign-in are only sent if they were recorded for the same user id that signs in, so call `setUserId(_:)` with the id your backend puts in the token before you track. Events recorded for an anonymous user are not credited to anyone and are dropped at sign-in.

<Callout kind="note" title="Keep it on the device">
A token is valid until it expires, so store it with the user's session (Keychain) and reuse it across app launches. Your `tokenProvider` then only calls your backend when the stored token is close to expiry, not on every start.
</Callout>

<H2 id="user-identification" step={4}>User Identification</H2>

The user token decides who the user is: once the SDK has a token, it acts as the user that token was minted for. Call `setUserId(_:)` with that same ID when a user signs in, and `clearUserId()` when they sign out. Until there is a user, the SDK uses a random ID it generates on first launch.

```swift
// After login — use the same ID your backend mints the token for
AbrovaAbTesting.shared.setUserId("user-123")
AbrovaAbTesting.shared.refreshUserToken()   // or setUserToken(token) if you hand tokens over yourself

// After logout — forget the user and wait for the next token
AbrovaAbTesting.shared.clearUserId()

// Get current user ID
let userId = AbrovaAbTesting.shared.getUserId()

// Set attributes for targeting rules
AbrovaAbTesting.shared.setUserAttributes([
    "plan": "premium",
    "country": "US",
    "age": 28,
    "platform": "ios"
])
```

A different user ID (`setUserId(_:)`), a token for another user, or a sign-out (`clearUserId()`, `setUserToken(nil)`) is a user switch. The SDK clears the previous user's variants, attributes, token and pending events before it does anything for the next user. Events of the previous user that are ready to send go out once more under that user's own token, never under another user's. Set the user attributes again after a switch.

<H2 id="delegate-callbacks" step={5}>Delegate Callbacks</H2>

Implement `AbrovaAbTestingDelegate` to listen for SDK events. Every method is optional. The SDK holds delegates weakly, so keep a strong reference to yours; add more with `addDelegate(_:)` and remove them with `removeDelegate(_:)`.

```swift
extension AppDelegate: AbrovaAbTestingDelegate {
    func abrovaAbTestingDidInitialize() {
        print("SDK initialized")
    }

    func abrovaAbTesting(didAssignVariant variantKey: String,
                         forExperiment experimentKey: String,
                         config: [String: Any]?) {
        print("Assigned: \(experimentKey) -> \(variantKey)")
    }

    func abrovaAbTesting(didRefreshExperiments experiments: [Experiment]) {
        print("Refreshed \(experiments.count) experiments")
    }

    func abrovaAbTesting(didRefreshFeatureFlags flags: [FeatureFlag]) {
        print("Refreshed \(flags.count) flags")
    }

    func abrovaAbTesting(didReceiveError error: AbrovaAbTestingError) {
        print("Error: \(error.localizedDescription)")
    }
}
```

<H2 id="a-b-testing" step={6}>A/B Testing</H2>

#### Get Variant

The variant always comes from the service (this needs a user token) and is then kept on the device; the SDK never picks one itself.

```swift
// Asynchronous (recommended) — waits for the service's answer;
// completion runs on the main queue
AbrovaAbTesting.shared.getVariant(experimentKey: "checkout-redesign") { variant in
    switch variant {
    case "variant-a":
        self.showNewCheckout()
    default:
        self.showOriginalCheckout()
    }
}

// Synchronous — never blocks, safe on the main thread
let variant = AbrovaAbTesting.shared.getVariant(
    experimentKey: "checkout-redesign",
    defaultVariant: "control"  // returned until the service has answered
)
```

The synchronous `getVariant` returns the variant the service assigned earlier. The first time you ask for an experiment it returns `defaultVariant` at once and fetches the assignment in the background; the delegate's `didAssignVariant` tells you when it has arrived. Use the completion form the first time a screen needs the variant, otherwise the user may briefly see the default before their real variant.

You get the default variant back when the experiment isn't running, the user doesn't match its targeting rules, there is no user token yet, or the service can't be reached and nothing is stored. A user the service keeps out of an experiment (targeting, traffic allocation) gets the control variant. Tracking calls are always safe to make: you don't need to check whether the user is in the experiment before you track. The SDK sends these events like any other and the service decides what counts; they never enter the experiment's results.

#### Get Variant Config

Available once the user has a variant for the experiment.

```swift
let config = AbrovaAbTesting.shared.getVariantConfig(experimentKey: "checkout-redesign")
let buttonColor = config?["button_color"] as? String ?? "#7C3AED"
let layout = config?["layout"] as? String ?? "default"
```

#### List & Refresh Experiments

Needs only the API key.

```swift
// Get all experiments
let experiments = AbrovaAbTesting.shared.getExperiments()
for exp in experiments {
    print("\(exp.key) [\(exp.status.rawValue)] - \(exp.variants.count) variants")
}

// Refresh from server
AbrovaAbTesting.shared.refreshExperiments {
    print("Experiments refreshed")
}
```

<H2 id="feature-flags" step={7}>Feature Flags</H2>

#### Check Feature Flag (Local)

Evaluated on the device against the cached flag list.

```swift
let darkMode = AbrovaAbTesting.shared.isFeatureEnabled("dark-mode")
if darkMode {
    enableDarkMode()
}
```

#### Check Feature Flag (Server Evaluation)

Needs a user token. Without one, or if the server can't be reached, the SDK falls back to local evaluation. The completion runs on the main queue.

```swift
AbrovaAbTesting.shared.isFeatureEnabled("dark-mode", defaultValue: false) { enabled in
    if enabled {
        self.enableDarkMode()
    }
}
```

#### Get Feature Value

Returns `Any?`, so cast it to the type you expect.

```swift
let maxUpload = AbrovaAbTesting.shared.getFeatureValue("max-upload-size", defaultValue: 10) as? Int ?? 10
let buttonColor = AbrovaAbTesting.shared.getFeatureValue("button-color", defaultValue: "#7C3AED") as? String ?? "#7C3AED"
```

#### List & Refresh Flags

```swift
// Get all flags
let flags = AbrovaAbTesting.shared.getFeatureFlags()
for flag in flags {
    print("\(flag.key): enabled=\(flag.enabled), rollout=\(flag.rolloutPercentage)%")
}

// Refresh from server
AbrovaAbTesting.shared.refreshFeatureFlags {
    print("Flags refreshed")
}
```

<H2 id="event-tracking" step={8}>Event Tracking</H2>

Track user interactions with 17 built-in event types. Events are credited to the variant the user was assigned, so get a variant for an experiment before tracking events for it. Events tracked while the assignment is still loading (or while the SDK waits for a user token) are kept and sent once the variant is known; events for an experiment you never asked a variant for are dropped.

Queued events are saved to disk and sent when the device is back online. The queue holds at most 1,000 events; when it is full, the oldest are dropped first. Events are sent 100 at a time. When the service can't be reached, asks the SDK to slow down, or your project has reached its usage limit, the SDK waits before it tries again. Each event carries the time your app recorded it, so events sent together keep their order.

#### Core Events

```swift
AbrovaAbTesting.shared.trackView(experimentKey: "experiment-key")
AbrovaAbTesting.shared.trackClick(experimentKey: "experiment-key")
AbrovaAbTesting.shared.trackConversion(experimentKey: "experiment-key", value: 1000000)

// Custom event
AbrovaAbTesting.shared.trackCustomEvent(
    experimentKey: "experiment-key",
    eventName: "button_tap",
    properties: ["element": "cta_button", "duration_ms": 1500]
)
```

#### Conversion Events

```swift
AbrovaAbTesting.shared.trackAddToCart(experimentKey: "experiment-key", value: 300000, productId: "sku-123", properties: ["quantity": 2])
AbrovaAbTesting.shared.trackRemoveFromCart(experimentKey: "experiment-key", value: 300000, productId: "sku-123")
AbrovaAbTesting.shared.trackBeginCheckout(experimentKey: "experiment-key", value: 600000)
AbrovaAbTesting.shared.trackPurchase(experimentKey: "experiment-key", value: 890000, transactionId: "txn-456", properties: ["currency": "Toman"])
```

#### Engagement Events

```swift
AbrovaAbTesting.shared.trackScroll(experimentKey: "experiment-key", depth: 75.0)
AbrovaAbTesting.shared.trackFormSubmit(experimentKey: "experiment-key", formName: "signup")
AbrovaAbTesting.shared.trackSearch(experimentKey: "experiment-key", query: "shoes")
AbrovaAbTesting.shared.trackShare(experimentKey: "experiment-key", method: "twitter")
```

#### Media Events

```swift
AbrovaAbTesting.shared.trackVideoStart(experimentKey: "experiment-key", videoId: "vid-001")
AbrovaAbTesting.shared.trackVideoComplete(experimentKey: "experiment-key", videoId: "vid-001")
```

#### Auth Events

```swift
AbrovaAbTesting.shared.trackSignUp(experimentKey: "experiment-key", method: "apple")
AbrovaAbTesting.shared.trackLogin(experimentKey: "experiment-key", method: "biometric")
AbrovaAbTesting.shared.trackLogout(experimentKey: "experiment-key")
```

#### Generic Event

```swift
AbrovaAbTesting.shared.track(
    experimentKey: "experiment-key",
    eventType: .custom,
    eventName: "page_load_time",
    eventValue: 2.3,
    properties: ["page": "/checkout", "cached": false]
)
```

### EventType Enum

<ConfigTable rows={[
  ['.view', '-', '-', 'User viewed the experiment'],
  ['.click', '-', '-', 'User clicked/tapped'],
  ['.conversion', '-', '-', 'Conversion event'],
  ['.custom', '-', '-', 'Custom event with name'],
  ['.scroll', '-', '-', 'Scroll depth tracking'],
  ['.formSubmit', '-', '-', 'Form submission'],
  ['.search', '-', '-', 'Search query'],
  ['.share', '-', '-', 'Social share'],
  ['.addToCart', '-', '-', 'Add item to cart'],
  ['.removeFromCart', '-', '-', 'Remove item from cart'],
  ['.beginCheckout', '-', '-', 'Begin checkout flow'],
  ['.purchase', '-', '-', 'Completed purchase'],
  ['.videoStart', '-', '-', 'Video playback started'],
  ['.videoComplete', '-', '-', 'Video playback completed'],
  ['.signUp', '-', '-', 'User registration'],
  ['.login', '-', '-', 'User login'],
  ['.logout', '-', '-', 'User logout'],
]} />

### API Reference

<ConfigTable rows={[
  ['initialize(config:delegate:)', '-', '-', 'Initialize the SDK'],
  ['setUserId(_:)', '-', '-', 'Set user ID; call on login'],
  ['clearUserId()', '-', '-', 'Sign-out: forget the user and wait for a token'],
  ['setUserToken(_:)', '-', '-', 'Hand over a user token (nil after sign-out)'],
  ['refreshUserToken()', '-', '-', 'Ask the tokenProvider again now (after sign-in or sign-out)'],
  ['isAwaitingUserToken', '-', '-', 'true while the SDK waits for a user token'],
  ['onAwaitingUserToken', '-', '-', 'Called once each time the SDK starts waiting'],
  ['getUserId()', '-', '-', 'Get current user ID'],
  ['setUserAttributes(_:)', '-', '-', 'Set targeting attributes'],
  ['getVariant(experimentKey:defaultVariant:)', '-', '-', 'Get assigned variant (never blocks; default until the service has answered)'],
  ['getVariant(experimentKey:defaultVariant:completion:)', '-', '-', 'Get assigned variant (waits for the service)'],
  ['getVariantConfig(experimentKey:)', '-', '-', 'Get variant configuration'],
  ['isFeatureEnabled(_:defaultValue:)', '-', '-', 'Check feature flag (local)'],
  ['isFeatureEnabled(_:defaultValue:completion:)', '-', '-', 'Check flag (server eval)'],
  ['getFeatureValue(_:defaultValue:)', '-', '-', 'Get feature flag value'],
  ['getFeatureFlags()', '-', '-', 'Get all feature flags'],
  ['refreshFeatureFlags(completion:)', '-', '-', 'Refresh flags from server'],
  ['getExperiments()', '-', '-', 'Get all experiments'],
  ['refreshExperiments(completion:)', '-', '-', 'Refresh experiments from server'],
  ['track(experimentKey:eventType:eventName:eventValue:properties:)', '-', '-', 'Track any event type'],
  ['addDelegate(_:) / removeDelegate(_:)', '-', '-', 'Add or remove a delegate'],
  ['flush()', '-', '-', 'Force sync pending events'],
  ['reset()', '-', '-', 'Clear all state, cache and token'],
]} />

### Complete Example

Full SwiftUI integration with user tokens, experiments, feature flags, and event tracking:

```swift
import SwiftUI
import AbrovaAbTesting

@main
struct MyApp: App {
    init() {
        AbrovaAbTesting.shared.initialize(config: AbrovaAbTestingConfig(
            apiKey: "YOUR_API_KEY",
            tokenProvider: { completion in
                MyBackend.fetchAbrovaToken { result in completion(result) }
            }
        ))
    }

    var body: some Scene {
        WindowGroup { ContentView() }
    }
}

// In your login flow, once your backend knows the user
func onLoggedIn(_ user: User) {
    AbrovaAbTesting.shared.setUserId(user.id)   // the ID your backend puts in the token
    AbrovaAbTesting.shared.refreshUserToken()   // asks tokenProvider again now
    AbrovaAbTesting.shared.setUserAttributes(["plan": user.plan])
}

// In your logout flow
func onLoggedOut() {
    AbrovaAbTesting.shared.clearUserId()
}

struct ContentView: View {
    @State private var variant = "control"
    @State private var darkMode = false

    var body: some View {
        VStack(spacing: 20) {
            // Feature flag: dark mode
            Toggle("Dark Mode", isOn: $darkMode)
                .padding()

            // A/B test: checkout button
            Button(action: {
                AbrovaAbTesting.shared.trackClick(experimentKey: "checkout-button")
                checkout()
            }) {
                Text(variant == "variant-a" ? "Buy Now" : "Checkout")
                    .foregroundColor(.white)
                    .padding()
                    .frame(maxWidth: .infinity)
                    .background(variant == "variant-a" ? Color.green : Color.blue)
                    .cornerRadius(12)
            }
            .padding(.horizontal)
        }
        .onAppear {
            // Check feature flag
            darkMode = AbrovaAbTesting.shared.isFeatureEnabled("dark-mode")

            // Get variant, then track the view
            AbrovaAbTesting.shared.getVariant(experimentKey: "checkout-button") { v in
                self.variant = v
                AbrovaAbTesting.shared.trackView(experimentKey: "checkout-button")
            }
        }
    }

    func checkout() {
        AbrovaAbTesting.shared.trackConversion(experimentKey: "checkout-button", value: 500000)
        AbrovaAbTesting.shared.trackPurchase(experimentKey: "checkout-button", value: 500000, transactionId: "txn-123")
        AbrovaAbTesting.shared.flush()
    }
}
```

### Lifecycle

```swift
// Refresh experiments from server
AbrovaAbTesting.shared.refreshExperiments()

// Refresh feature flags from server
AbrovaAbTesting.shared.refreshFeatureFlags()

// Flush pending events
AbrovaAbTesting.shared.flush()

// Clear cached experiments, flags, assignments and the token.
// Mainly for tests — call initialize(config:) again before using the SDK.
AbrovaAbTesting.shared.reset()
```

To switch users, use `setUserId(_:)` on login and `clearUserId()` on logout rather than `reset()`.

- Flutter: https://abrova.ir/en/docs/ab-testing/flutter

<Callout kind="note" title="AbrovaAbTesting Flutter SDK v0.2.3">
- Pure Dart SDK for A/B testing and feature flags .
- works on all Flutter platforms (iOS, Android, Web, macOS, Linux, Windows). 
- Offline-first with SharedPreferences cache, variants assigned by the service, and 17 built-in event types. Installs from Abrova Center.
- Signed user tokens via `tokenProvider`, required for variants, tracking and flag evaluation. See step 3, User tokens.
- New in 0.2.2: you can initialize before sign-in. The SDK waits for the user token instead of failing.
</Callout>

<Callout kind="note" title="Requirements">
- Flutter 3.10 or higher. 
- Dart 3.0.0 or higher. Android SDK 21+ / iOS 13.0+. Pure Dart 
- works on all Flutter platforms.
</Callout>

<Callout kind="note" title="Only need Feature Flags?">
The same package ships a standalone `AbrovaFeatureFlags` class for apps that only need flags (see Feature Flags below). For a full feature-flag platform, see [Abrova Flags](/docs/flags/flutter).
</Callout>

<H2 id="installation" step={1}>Installation</H2>

Install from Abrova Center in two steps. Add the package to your `pubspec.yaml` with the Abrova Center address:

```yaml
dependencies:
  abrova_ab_testing:
    hosted: https://center.abrova.ir/api/packages/abrova/pub
    version: ^0.2.3
```

Then install:

```bash
flutter pub get
```

#### Platform-specific setup

**Android:** Add Internet permission in `android/app/src/main/AndroidManifest.xml`:

```xml
<uses-permission android:name="android.permission.INTERNET" />
```

**iOS / Web / Desktop:** No additional setup required.

<H2 id="initialization" step={2}>Initialization</H2>

Initialize AbrovaAbTesting in your main function before running the app. Pass a `tokenProvider` that fetches an Abrova user token from your backend (see User tokens below).

```dart
import 'dart:convert';

import 'package:flutter/material.dart';
import 'package:http/http.dart' as http;
import 'package:abrova_ab_testing/abrova_ab_testing.dart';

/// Calls YOUR backend, which mints the token with your server secret.
/// Returns null while no one is signed in.
Future<String?> fetchAbrovaToken() async {
  if (yourSessionToken == null) return null;
  final res = await http.post(
    Uri.parse('https://your-api.example.com/abrova-token'),
    headers: {'Authorization': 'Bearer $yourSessionToken'}, // your app's own login session
  );
  return jsonDecode(res.body)['token'] as String;
}

void main() async {
  WidgetsFlutterBinding.ensureInitialized();

  await AbrovaAbTesting.init(
    AbrovaAbTestingConfig(
      apiKey: 'YOUR_API_KEY',
      tokenProvider: fetchAbrovaToken, // required for variants, events and flags
      debug: true,                     // Enable debug logging
      // flushInterval: 10000,         // Your own send interval in ms. Leave it out to follow the console
      maxQueueSize: 100,               // Maximum events to queue
    ),
    callback: (event, data) {
      print('AbrovaAbTesting event: $event, data: $data');
    },
  );

  runApp(const MyApp());
}

// Call this after your user signs in
Future<void> onSignedIn(String userId) async {
  await AbrovaAbTesting.instance.setUserId(userId);   // the id your server puts in the token
  await AbrovaAbTesting.instance.refreshUserToken();  // asks tokenProvider again now
}

// Call this after your user signs out
Future<void> onSignedOut() async {
  await AbrovaAbTesting.instance.clearUserId();
}
```

`AbrovaAbTesting.instance` is available once `init` has completed. After that, `getVariant` and the `track…` methods never throw, with or without a signed-in user.

If you pass `baseUrl` to `init`, it must be an `https` URL. Plain `http` is accepted only for local development (`localhost`, `127.0.0.1`, `10.0.2.2`).

#### Configuration

<ConfigTable rows={[
  ['apiKey', 'String', 'required', 'Your project API key (`ab_live_…`).'],
  ['tokenProvider', 'AbrovaTokenProvider', '-', '`FutureOr<String?> Function()` that returns an Abrova user token from your backend, or `null` while no one is signed in.'],
  ['userToken', 'String?', '-', 'A token you already hold. Prefer `tokenProvider`: a fixed token stops working when it expires. Hand over a newer one with `setUserToken`.'],
  ['debug', 'bool', 'false', 'Print SDK logs.'],
  ['flushInterval', 'int?', '-', 'How often queued events are sent, in milliseconds (whole seconds are used). Leave it out to follow the Send interval set in the Abrova console (see below).'],
  ['maxQueueSize', 'int', '100', 'Accepted but not used: the SDK keeps up to 1,000 events and sends 100 at a time.'],
]} />

#### Send interval and list cache

Two values come from your project's settings in the Abrova console (**A/B Testing › Settings › Defaults**):

- **Send interval** — how often queued events are sent. The SDK follows it when you leave `flushInterval` out. A `flushInterval` you pass is your own and is always used.
- **List cache** — how long the SDK uses the experiment list before it asks the service again. There is no SDK option for it. Once the list is older than that, the SDK fetches it again in the background the next time your code reads a variant or tracks an event. The call doesn't wait for it, and a failed refresh is not reported to your callback as an `error`.

A change you make in the console (a new experiment, changed weights or traffic) reaches running apps within the list cache time, without a restart. A user who already has a variant keeps it. A changed send interval is picked up at that same refresh. The SDK keeps the console's values within safe limits, and sends every 30 seconds until it knows the console's value. Apps on SDK versions older than 0.2.3 keep their built-in behaviour.

From 0.2.3, a `flushInterval` set in code always wins.

<H2 id="user-tokens" step={3}>User tokens</H2>

Anything the SDK does for a user needs a signed Abrova user token: getting a variant from the server, tracking events and conversions, syncing queued events, and evaluating feature flags. Loading the experiment and flag lists works with the API key alone, so your app can fetch them before sign-in.

#### Mint the token on your server

Add one endpoint, protected by your own login, that returns a token for the signed-in user. It calls Abrova with your project's server secret:

```bash
curl -X POST https://auth.abrova.ir/users/token \
  -H "x-api-key: $ABROVA_API_KEY" \
  -H "x-server-secret: $ABROVA_SERVER_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"userId": "user-123", "expiresIn": 3600}'
# → { "token": "eyJhbGciOi…", "userId": "user-123", "expiresIn": 3600, "expiresAt": "…" }
```

`expiresIn` is in seconds: 3600 (1 hour) by default, 86400 (24 hours) maximum.

<Callout kind="warn" title="Never ship the server secret">
The server secret can mint a token for **any** user. Keep it on your server, out of your app bundle and source code.
</Callout>

#### One token for A/B Testing, Chat and Sync

This is the same Abrova user token that Abrova Chat and Abrova Sync use. Give that same token to every SDK's `tokenProvider` instead of fetching one per product.

<Callout kind="note" title="Keep it on the device">
A token is valid until it expires, so store it with the user's session (Keychain, Keystore or secure storage) and reuse it across app launches. Your app then only calls your backend when the token is close to expiry — not on every start.
</Callout>

#### How the SDK uses it

<BestPracticeList columns={2} items={[
  ['Cached and refreshed', 'The SDK calls `tokenProvider` at start, when it needs a token, again shortly before the token expires, and once more if the service reports it expired.'],
  ['Hand tokens over yourself', 'No `tokenProvider`? Call `setUserToken(token)` after `init` and whenever you refresh the token, and `setUserToken(null)` at sign-out. A token passed as `userToken` is not refreshed.'],
  ['The token decides the user', 'The service takes the user from the token, and so does the SDK: a token for a different user switches the SDK to that user.'],
  ['Match the user IDs', 'Mint the token for the same user ID you pass to `setUserId`.'],
]} />

#### Before your user signs in

You can call `init` before anyone is signed in. While there is no token (`tokenProvider` returned `null` or failed, or none was set) the SDK is **awaiting a user token**:

- `getVariant` returns the default variant.
- Flags come from the cached flag list, or return their default.
- Events are kept on the device (up to 1,000) and nothing is sent.
- No error is reported.

Once a token arrives, the SDK fetches the variants you asked for in the meantime (listen for the `experimentAssigned` event in the `init` callback) and sends the pending events.

```dart
final ab = AbrovaAbTesting.instance;

ab.isAwaitingUserToken;            // true while there is no user token
ab.onAwaitingUserToken(() { });    // called each time the SDK starts waiting

// After sign-in
await ab.refreshUserToken();       // with a tokenProvider: asks it again now
await ab.setUserToken(token);      // without one: hand the token over

// After sign-out
await ab.clearUserId();            // or setUserToken(null)
```

The `init` callback reports the same moment as an `awaitingUserToken` event. To add or remove the provider after `init`, call `setTokenProvider(provider)`; the provider is asked straight away.

Events are credited to the user in the token. Events recorded before sign-in are only sent if they were recorded for the same user id that signs in (you called `setUserId` with that id before tracking). Events recorded while no user was set belong to no one, are not credited, and are dropped at sign-in.

<H2 id="user-identification" step={4}>User Identification</H2>

Identify users and set attributes for targeting rules. Call `setUserId` on login with the same id your server puts in the token, and `clearUserId` on logout.

```dart
// Set user ID (e.g., after login)
await AbrovaAbTesting.instance.setUserId('user-123');

// Forget the user (after logout)
await AbrovaAbTesting.instance.clearUserId();

// Get current user ID
final userId = AbrovaAbTesting.instance.getUserId();

// Set user attributes for targeting
AbrovaAbTesting.instance.setUserAttributes({
  'plan': 'premium',
  'country': 'US',
  'age': 25,
  'is_beta_user': true,
});
```

Calling `setUserId` with a different user, handing over a token for a different user, or calling `clearUserId()` is a user switch. The SDK first sends the previous user's pending events under their own token, then drops their variants, attributes, token and remaining events before anything is sent for the next user. Set the user attributes again after a switch.

<H2 id="getting-experiment-variants" step={5}>Getting Experiment Variants</H2>

Get the variant assigned to the current user. The service decides the variant (this needs a user token) and the SDK remembers it, so the same user keeps the same variant. The SDK never works a variant out on the device.

The Flutter SDK returns the variant's **name** as it appears in Abrova Console (for example `Control` or `Variant B`), not its key (`control`, `variant-b`). `getVariant` never throws: without a user, a user token or a connection it returns the remembered variant, or `defaultVariant` when there is none.

```dart
// Get variant for an experiment
final variant = await AbrovaAbTesting.instance.getVariant(
  'checkout-button-color',
  defaultVariant: 'control', // returned while the service has not assigned one
);

// Use the variant
switch (variant) {
  case 'Variant A':
    buttonColor = Colors.green;
    break;
  case 'Variant B':
    buttonColor = Colors.blue;
    break;
  default:
    buttonColor = Colors.grey; // control
}
```

#### Getting Variant Configuration

```dart
// Get variant config as a Map
final config = await AbrovaAbTesting.instance.getVariantConfig('checkout-button-color');

// Access config values
final buttonText = config?['buttonText'] as String? ?? 'Buy Now';
final buttonColorHex = config?['buttonColor'] as String? ?? '#6B7280';

// Get all cached experiments
final experiments = AbrovaAbTesting.instance.getExperiments();
for (final experiment in experiments) {
  print('${experiment.key}: ${experiment.status}');
}
```

<H2 id="tracking-events" step={6}>Tracking Events</H2>

Track user interactions to measure experiment results. All 17 event types are supported. Events are queued locally and synced automatically with the current user's token. The `track…` methods never throw: without a signed-in user the event is kept, and it is only sent if that same user signs in.

#### Core Events

```dart
final sdk = AbrovaAbTesting.instance;

// Track view
await sdk.trackView('checkout-button-color');

// Track click
await sdk.trackClick('checkout-button-color');

// Track conversion with optional value
await sdk.trackConversion('checkout-button-color', value: 300000);

// Track custom event
await sdk.trackCustomEvent(
  'checkout-button-color',
  'add_to_cart',
  properties: {
    'product_id': 'SKU123',
    'quantity': 2,
  },
);
```

#### Conversion Events

```dart
final sdk = AbrovaAbTesting.instance;

// Add to cart
await sdk.trackAddToCart('checkout-flow', value: 200000, productId: 'SKU123');

// Remove from cart
await sdk.trackRemoveFromCart('checkout-flow', value: 200000, productId: 'SKU123');

// Begin checkout
await sdk.trackBeginCheckout('checkout-flow', value: 600000);

// Purchase
await sdk.trackPurchase('checkout-flow',
  value: 600000,
  transactionId: 'txn_abc123',
  properties: {'currency': 'Toman'},
);
```

#### Engagement Events

```dart
final sdk = AbrovaAbTesting.instance;

// Scroll tracking
await sdk.trackScroll('landing-page', depth: 75.0);

// Form submission
await sdk.trackFormSubmit('signup-flow', formName: 'registration');

// Search
await sdk.trackSearch('search-experiment', query: 'flutter sdk');

// Share
await sdk.trackShare('referral-test', method: 'email');
```

#### User Auth Events

```dart
final sdk = AbrovaAbTesting.instance;

// Sign up
await sdk.trackSignUp('onboarding-flow', method: 'google');

// Login
await sdk.trackLogin('auth-experiment', method: 'email');

// Logout
await sdk.trackLogout('auth-experiment');
```

#### Media Events

```dart
final sdk = AbrovaAbTesting.instance;

// Video start
await sdk.trackVideoStart('video-experiment', videoId: 'vid_123');

// Video complete
await sdk.trackVideoComplete('video-experiment', videoId: 'vid_123');
```

#### Generic Event Tracking

```dart
// Track any event type with full control
await AbrovaAbTesting.instance.track(
  'my-experiment',
  EventType.custom,
  eventName: 'my_custom_event',
  eventValue: 42.0,
  properties: {'key': 'value'},
);
```

<H2 id="feature-flags" step={7}>Feature Flags</H2>

The A/B testing SDK includes built-in feature flag support. Flags are evaluated server-side for the signed-in user (with their token). When the service can't be asked (offline, or no user token yet), the SDK uses the service's last answer, then the cached flag list, then your default.

```dart
final sdk = AbrovaAbTesting.instance;

// Check if feature is enabled
final isEnabled = await sdk.isFeatureEnabled('new-checkout-flow');

if (isEnabled) {
  return NewCheckoutPage();
} else {
  return OldCheckoutPage();
}

// Get feature flag value (for multivariate flags)
final bannerText = await sdk.getFeatureValue(
  'banner-text',
  defaultValue: 'Welcome!',
);

// Get all feature flags
final flags = await sdk.getFeatureFlags();
for (final flag in flags) {
  print('${flag.key}: ${flag.enabled}');
}

// Refresh flags from server
await sdk.refreshFeatureFlags();
```

#### Flags without experiments

If your app only needs flags, use `AbrovaFeatureFlags` from the same package. It takes the same `tokenProvider` and has the same `isAwaitingUserToken`, `onAwaitingUserToken`, `setUserToken`, `refreshUserToken` and `clearUserId` members:

```dart
await AbrovaFeatureFlags.init(
  AbrovaFeatureFlagsConfig(
    apiKey: 'YOUR_API_KEY',
    tokenProvider: fetchAbrovaToken,
  ),
);

await AbrovaFeatureFlags.instance.setUserId('user-123');

if (await AbrovaFeatureFlags.instance.isEnabled('dark-mode')) {
  // Show dark mode
}

final maxUpload = await AbrovaFeatureFlags.instance.getValue(
  'max-upload-size',
  defaultValue: 10,
);
```

<H2 id="offline-support" step={8}>Offline Support</H2>

<Callout kind="note" title="Built-in Offline Mode">
AbrovaAbTesting automatically handles offline scenarios. Experiments and feature flags are cached locally. Events are queued when offline and synced, with the user's token, when connectivity returns.
</Callout>

<BestPracticeList columns={2} items={[
  ['Automatic Event Queuing', 'Events are stored locally using SharedPreferences when offline and automatically synced when back online.'],
  ['Bounded Queue', 'The queue holds at most 1,000 events (the oldest are dropped first) and is sent in batches. The SDK waits before retrying when the service is busy or your project has reached its usage limit.'],
  ['Sticky Assignments', 'Once the service assigns a user a variant, the assignment is cached locally so they always see the same variant, even when offline. Without a cached assignment, `getVariant` returns your default.'],
  ['Event IDs', 'Each event has a unique ID, sent as `clientEventId` and saved with the event.'],
  ['Event Time', 'Each event carries the time your app recorded it, so events sent together keep their order.'],
]} />

<H2 id="lifecycle-sync" step={9}>Lifecycle & Sync</H2>

#### App Lifecycle Integration

```dart
class _MyAppState extends State<MyApp> with WidgetsBindingObserver {
  @override
  void initState() {
    super.initState();
    WidgetsBinding.instance.addObserver(this);
  }

  @override
  void didChangeAppLifecycleState(AppLifecycleState state) {
    if (state == AppLifecycleState.paused) {
      // Flush events before app goes to background
      AbrovaAbTesting.instance.flush();
    }
  }

  @override
  void dispose() {
    WidgetsBinding.instance.removeObserver(this);
    AbrovaAbTesting.instance.dispose();
    super.dispose();
  }
}
```

#### Manual Flush & Status

```dart
// Flush events immediately
await AbrovaAbTesting.instance.flush();

// Check pending event count
final pending = await AbrovaAbTesting.instance.getPendingEventCount();
print('Pending events: $pending');

// Check connectivity
final isOnline = AbrovaAbTesting.instance.isOnline;
print('Online: $isOnline');

// Refresh experiments from server
await AbrovaAbTesting.instance.refreshExperiments();

// Wipe all SDK state, including unsent events. You must call init() again afterwards.
// To switch users, call setUserId() on login and clearUserId() on logout instead.
await AbrovaAbTesting.instance.reset();
```

### Complete Example

A complete example showing initialization, experiments, events, and feature flags:

```dart
import 'package:flutter/material.dart';
import 'package:abrova_ab_testing/abrova_ab_testing.dart';

void main() async {
  WidgetsFlutterBinding.ensureInitialized();

  await AbrovaAbTesting.init(
    AbrovaAbTestingConfig(
      apiKey: 'YOUR_API_KEY',
      tokenProvider: fetchAbrovaToken, // see Initialization
      debug: true,
    ),
  );

  runApp(const MyApp());
}

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(home: const CheckoutPage());
  }
}

class CheckoutPage extends StatefulWidget {
  const CheckoutPage({super.key});

  @override
  State<CheckoutPage> createState() => _CheckoutPageState();
}

class _CheckoutPageState extends State<CheckoutPage> with WidgetsBindingObserver {
  String _variant = 'control';
  bool _newCheckoutEnabled = false;
  bool _loading = true;

  @override
  void initState() {
    super.initState();
    WidgetsBinding.instance.addObserver(this);
    _init();
  }

  @override
  void dispose() {
    WidgetsBinding.instance.removeObserver(this);
    super.dispose();
  }

  @override
  void didChangeAppLifecycleState(AppLifecycleState state) {
    if (state == AppLifecycleState.paused) {
      AbrovaAbTesting.instance.flush();
    }
  }

  Future<void> _init() async {
    final sdk = AbrovaAbTesting.instance;

    // Set the signed-in user (the token from fetchAbrovaToken is for this user)
    await sdk.setUserId('user-123');
    sdk.setUserAttributes({'plan': 'premium', 'country': 'US'});

    // Get experiment variant (the default until the service has assigned one)
    final variant = await sdk.getVariant(
      'checkout-button-style',
      defaultVariant: 'control',
    );

    // Check feature flag
    final newCheckout = await sdk.isFeatureEnabled('new-checkout-flow');

    setState(() {
      _variant = variant;
      _newCheckoutEnabled = newCheckout;
      _loading = false;
    });

    // Track view
    await sdk.trackView('checkout-button-style');
  }

  Future<void> _handleCheckout() async {
    final sdk = AbrovaAbTesting.instance;

    await sdk.trackClick('checkout-button-style');
    // ... process checkout ...
    await sdk.trackPurchase('checkout-button-style', value: 1000000, transactionId: 'txn_123');

    if (mounted) {
      ScaffoldMessenger.of(context).showSnackBar(
        const SnackBar(content: Text('Checkout complete!')),
      );
    }
  }

  @override
  Widget build(BuildContext context) {
    if (_loading) {
      return const Scaffold(body: Center(child: CircularProgressIndicator()));
    }

    return Scaffold(
      appBar: AppBar(title: const Text('Checkout')),
      body: Center(
        child: Column(
          mainAxisAlignment: MainAxisAlignment.center,
          children: [
            Text('Variant: $_variant'),
            Text('New checkout: $_newCheckoutEnabled'),
            const SizedBox(height: 24),
            ElevatedButton(
              onPressed: _handleCheckout,
              style: ElevatedButton.styleFrom(
                backgroundColor: _variant == 'Variant B' ? Colors.green : Colors.grey,
                padding: const EdgeInsets.symmetric(horizontal: 32, vertical: 16),
              ),
              child: const Text('Complete Purchase', style: TextStyle(fontSize: 18)),
            ),
          ],
        ),
      ),
    );
  }
}
```

### API Reference

```dart
// ── Initialization ──
static Future<AbrovaAbTesting> init(AbrovaAbTestingConfig config, {callback, baseUrl})
static AbrovaAbTesting get instance

// ── Configuration ──
AbrovaAbTestingConfig({required String apiKey, AbrovaTokenProvider? tokenProvider,
  String? userToken, bool debug, int? flushInterval, int maxQueueSize})
typedef AbrovaTokenProvider = FutureOr<String?> Function()   // null: no one signed in

// ── User Management ──
Future<void> setUserId(String userId)   // call on login
Future<void> clearUserId()              // call on logout
String? getUserId()
void setUserAttributes(Map<String, dynamic> attributes)

// ── User Token ──
bool get isAwaitingUserToken
void onAwaitingUserToken(void Function() callback)
Future<void> setUserToken(String? token)   // null = signed out
Future<void> refreshUserToken()            // ask tokenProvider again now
Future<void> setTokenProvider(AbrovaTokenProvider? provider)

// ── Experiments ──
Future<String> getVariant(String experimentKey, {String defaultVariant})
Future<Map<String, dynamic>?> getVariantConfig(String experimentKey)
Future<void> refreshExperiments()
List<Experiment> getExperiments()

// ── Event Tracking (17 types) ──
Future<void> trackView(String experimentKey)
Future<void> trackClick(String experimentKey)
Future<void> trackConversion(String experimentKey, {double? value})
Future<void> trackCustomEvent(String experimentKey, String eventName, {properties})
Future<void> trackScroll(String experimentKey, {double? depth, properties})
Future<void> trackFormSubmit(String experimentKey, {String? formName, properties})
Future<void> trackSearch(String experimentKey, {String? query, properties})
Future<void> trackShare(String experimentKey, {String? method, properties})
Future<void> trackAddToCart(String experimentKey, {double? value, String? productId})
Future<void> trackRemoveFromCart(String experimentKey, {double? value, String? productId})
Future<void> trackBeginCheckout(String experimentKey, {double? value, properties})
Future<void> trackPurchase(String experimentKey, {required double value, String? transactionId})
Future<void> trackVideoStart(String experimentKey, {String? videoId, properties})
Future<void> trackVideoComplete(String experimentKey, {String? videoId, properties})
Future<void> trackSignUp(String experimentKey, {String? method, properties})
Future<void> trackLogin(String experimentKey, {String? method, properties})
Future<void> trackLogout(String experimentKey, {properties})
Future<void> track(String experimentKey, EventType type, {eventName, eventValue, properties})

// ── Feature Flags ──
Future<bool> isFeatureEnabled(String featureKey, {bool defaultValue})
Future<dynamic> getFeatureValue(String featureKey, {dynamic defaultValue})
Future<List<FeatureFlag>> getFeatureFlags()
Future<void> refreshFeatureFlags()
AbrovaFeatureFlags get featureFlags

// ── Lifecycle ──
Future<void> flush()
Future<int> getPendingEventCount()
bool get isOnline
Future<void> reset()
void dispose()
```

### EventType Enum

```dart
enum EventType {
  view,           // 'view'
  click,          // 'click'
  conversion,     // 'conversion'
  custom,         // 'custom'
  scroll,         // 'scroll'
  formSubmit,     // 'form_submit'
  search,         // 'search'
  share,          // 'share'
  addToCart,       // 'add_to_cart'
  removeFromCart,  // 'remove_from_cart'
  beginCheckout,   // 'begin_checkout'
  purchase,        // 'purchase'
  videoStart,      // 'video_start'
  videoComplete,   // 'video_complete'
  signUp,          // 'sign_up'
  login,           // 'login'
  logout,          // 'logout'
}
```

- React Native: https://abrova.ir/en/docs/ab-testing/react-native

<Callout kind="note" title="AbrovaAbTesting React Native SDK v0.2.3">
Cross-platform TypeScript SDK for A/B testing and feature flags on React Native. AsyncStorage-backed offline cache, event listeners for SDK lifecycle, 17 built-in event types. Installs from Abrova Center.

Signed user tokens via `tokenProvider` are required for variants, tracking and flag evaluation. New in 0.2.2: you can initialize before sign-in, and the SDK waits for the user token instead of failing. See step 3, User tokens.
</Callout>

<Callout kind="note" title="Requirements">
- React Native 0.60.0 or higher. 
- React 16.8.0 or higher. Android SDK 21+ / iOS 12.0+.
</Callout>

<H2 id="installation" step={1}>Installation</H2>

#### Install the package

```bash
# 1. .npmrc in your project root: @abrova packages come from Abrova Center
@abrova:registry=https://center.abrova.ir/api/packages/abrova/npm/
```

```bash
# 2. Install
npm install @abrova/ab-testing-react-native@^0.2.3
```

Or with Yarn:

```bash
yarn add @abrova/ab-testing-react-native@^0.2.3
```

#### Install peer dependency

The SDK is pure TypeScript and uses AsyncStorage for offline persistence:

```bash
npm install @react-native-async-storage/async-storage
```

#### iOS setup

```bash
cd ios && pod install && cd ..
```

No additional setup is required for Android.

<H2 id="initialization" step={2}>Initialization</H2>

Initialize AbrovaAbTesting early in your app, typically in App.tsx or index.js. Pass a `tokenProvider` that fetches an Abrova user token from your backend (see User tokens below).

```typescript
import AbrovaAbTesting from '@abrova/ab-testing-react-native';

// Calls YOUR backend, which mints the token with your server secret.
// Returns null while no one is signed in.
async function fetchAbrovaToken(): Promise<string | null> {
  if (!yourSessionToken) return null;
  const res = await fetch('https://your-api.example.com/abrova-token', {
    method: 'POST',
    headers: { Authorization: `Bearer ${yourSessionToken}` }, // your app's own login session
  });
  return (await res.json()).token;
}

// Initialize the SDK
await AbrovaAbTesting.init({
  apiKey: 'YOUR_API_KEY',
  tokenProvider: fetchAbrovaToken, // required for variants, events and flags
  debug: __DEV__,                  // Enable debug logging in development
  // flushInterval: 10000,         // Your own send interval in ms. Leave it out to follow the console
  maxQueueSize: 100,               // Maximum events to queue
});

// Set the signed-in user (optional with a user token: the token says who the user is)
await AbrovaAbTesting.setUserId('user-123');
await AbrovaAbTesting.setUserAttributes({
  plan: 'premium',
  country: 'US',
});
```

`getVariant`, the flag getters and the `track…` methods never reject when you call them before `init()` or without a signed-in user: getters resolve with the default you pass, and tracking before `init()` does nothing.

#### Full App.tsx Example

```typescript
import React, { useEffect, useState } from 'react';
import { View, ActivityIndicator } from 'react-native';
import AbrovaAbTesting from '@abrova/ab-testing-react-native';

// fetchAbrovaToken() calls your backend — see above.

function App() {
  const [isReady, setIsReady] = useState(false);

  useEffect(() => {
    const initSDK = async () => {
      try {
        await AbrovaAbTesting.init({
          apiKey: 'YOUR_API_KEY',
          tokenProvider: fetchAbrovaToken,
          debug: __DEV__,
        });

        await AbrovaAbTesting.setUserId('user-123');
      } catch (error) {
        console.error('AbrovaAbTesting init error:', error);
      } finally {
        setIsReady(true);
      }
    };

    initSDK();

    // Listen for events
    const unsubError = AbrovaAbTesting.on('error', (event) => {
      console.error('AbrovaAbTesting error:', event.data);
    });

    return () => {
      unsubError();
    };
  }, []);

  if (!isReady) {
    return (
      <View style={{ flex: 1, justifyContent: 'center', alignItems: 'center' }}>
        <ActivityIndicator size="large" />
      </View>
    );
  }

  return <MainNavigator />;
}

export default App;
```

#### Configuration

<ConfigTable rows={[
  ['apiKey', 'string', 'required', 'Your project API key (`ab_live_…`).'],
  ['tokenProvider', '() => string | null | Promise<string | null>', '-', 'Returns an Abrova user token from your backend, or `null` while no one is signed in.'],
  ['userToken', 'string', '-', 'A token you already hold. Prefer `tokenProvider`: a fixed token stops working when it expires. Hand over a newer one with `setUserToken`.'],
  ['debug', 'boolean', 'false', 'Print SDK logs.'],
  ['flushInterval', 'number', '-', 'How often queued events are sent, in milliseconds. Leave it out to follow the Send interval set in the Abrova console (see below).'],
  ['maxQueueSize', 'number', '1000', 'Events kept while they cannot be sent. Default and maximum: 1000.'],
]} />

#### Send interval and list cache

Two values come from your project's settings in the Abrova console (**A/B Testing › Settings › Defaults**):

- **Send interval** — how often queued events are sent. The SDK follows it when you leave `flushInterval` out. A `flushInterval` you pass is your own and is always used.
- **List cache** — how long the SDK uses the experiment list before it asks the service again. There is no SDK option for it. Once the list is older than that, the SDK fetches it again in the background the next time your code reads a variant or tracks an event. The call doesn't wait for it, and a failed refresh does not emit an `error` event.

A change you make in the console (a new experiment, changed weights or traffic) reaches running apps within the list cache time, without a restart. A user who already has a variant keeps it. A changed send interval is picked up at that same refresh. The SDK keeps the console's values within safe limits, and sends every 30 seconds until it knows the console's value. Apps on SDK versions older than 0.2.3 keep their built-in behaviour.

From 0.2.3, a `flushInterval` set in code always wins.

<H2 id="user-tokens" step={3}>User tokens</H2>

Anything the SDK does for a user needs a signed Abrova user token: getting a variant from the server, tracking events and conversions, syncing queued events, and evaluating feature flags. Loading the experiment and flag lists works with the API key alone, so your app can fetch them before sign-in.

#### Mint the token on your server

Add one endpoint, protected by your own login, that returns a token for the signed-in user. It calls Abrova with your project's server secret:

```bash
curl -X POST https://auth.abrova.ir/users/token \
  -H "x-api-key: $ABROVA_API_KEY" \
  -H "x-server-secret: $ABROVA_SERVER_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"userId": "user-123", "expiresIn": 3600}'
# → { "token": "eyJhbGciOi…", "userId": "user-123", "expiresIn": 3600, "expiresAt": "…" }
```

`expiresIn` is in seconds: 3600 (1 hour) by default, 86400 (24 hours) maximum.

<Callout kind="warn" title="Never ship the server secret">
The server secret can mint a token for **any** user. Keep it on your server, out of your JavaScript bundle and source code.
</Callout>

#### One token for A/B Testing, Chat and Sync

This is the same Abrova user token that Abrova Chat and Abrova Sync use. Give that same token to every SDK's `tokenProvider` instead of fetching one per product.

<Callout kind="note" title="Keep it on the device">
A token is valid until it expires, so store it with the user's session (Keychain, Keystore or secure storage) and reuse it across app launches. Your app then only calls your backend when the token is close to expiry — not on every start.
</Callout>

#### How the SDK uses it

<BestPracticeList columns={2} items={[
  ['Cached and refreshed', 'The SDK caches the token, calls `tokenProvider` again shortly before it expires, and asks once more if the service reports it expired.'],
  ['Hand tokens over yourself', 'No `tokenProvider`? Call `setUserToken(token)` after sign-in and whenever you refresh the token, and `setUserToken(null)` at sign-out. A token passed as `userToken` is not refreshed.'],
  ['The token decides the user', 'The service takes the user from the token, so the SDK does too. You may skip `setUserId` and let the token say who the user is.'],
  ['Match the user IDs', 'If you do call `setUserId`, pass the same user ID the token was minted for.'],
]} />

#### Before your user signs in

You can start the SDK before anyone is signed in: return `null` from `tokenProvider` and call `refreshUserToken()` when the user signs in or out. If you hand tokens over yourself, call `setUserToken(token)` on sign-in and `setUserToken(null)` on sign-out.

Until it has a token, the SDK waits: `getVariant` and the flag getters return your defaults at once, nothing is sent, and nothing is reported as an error. When the token arrives, the SDK continues by itself.

```typescript
AbrovaAbTesting.isAwaitingUserToken;             // true while it waits
AbrovaAbTesting.onAwaitingUserToken(() => {});   // called each time it starts waiting; returns an unsubscribe function
AbrovaAbTesting.on('userTokenReady', () => {});  // a token arrived: read variants again

// After sign-in
await AbrovaAbTesting.refreshUserToken();        // with a tokenProvider: asks it again now
await AbrovaAbTesting.setUserToken(token);       // without one: hand the token over

// After sign-out
await AbrovaAbTesting.clearUserId();             // or setUserToken(null)
```

Because getters return defaults while the SDK waits, read your variants again when `userTokenReady` fires:

```typescript
useEffect(() => {
  const load = async () => setVariant(await AbrovaAbTesting.getVariant('checkout-style', 'control'));
  load();
  return AbrovaAbTesting.on('userTokenReady', load);
}, []);
```

Events tracked while the SDK waits are kept (up to 1,000, the oldest dropped first). After sign-in they are sent **only if they were recorded for that same user**, that is, `setUserId` was called with their ID before the token arrived. Events recorded while no user was set belong to nobody, are not credited to anyone, and are dropped when a user signs in.

<H2 id="getting-experiment-variants" step={4}>Getting Experiment Variants</H2>

Get the variant assigned to the current user for an experiment. The variant always comes from the service (this needs a user token) and is cached for the user; the SDK never works one out on the device.

The React Native SDK returns the variant's **name** as it appears in Abrova Console (for example `Control` or `Variant B`), not its key (`control`, `variant-b`).

```typescript
import AbrovaAbTesting from '@abrova/ab-testing-react-native';

// Get variant (with optional default)
const variant = await AbrovaAbTesting.getVariant(
  'checkout-button-color',
  'control'  // returned while there is no user token, or when the service
             // cannot be reached and nothing is cached
);

// Use the variant
switch (variant) {
  case 'Variant B':
    showNewCheckout();
    break;
  default:
    showOriginalCheckout();
}
```

#### Getting Variant Configuration

```typescript
// Get variant config (set in the Abrova dashboard)
const config = await AbrovaAbTesting.getVariantConfig('checkout-button-color');

const buttonText = config?.buttonText ?? 'Buy Now';
const buttonColor = config?.buttonColor ?? '#6B7280';
```

<H2 id="event-tracking" step={5}>Event Tracking</H2>

Track user interactions to measure experiment results. The SDK supports 17 built-in event types. Events are queued locally and sent in batches with the current user's token. The queue holds at most 1,000 events (the oldest are dropped first), and the SDK waits before retrying when the service is busy or your project has reached its usage limit. Each event carries the time your app recorded it, so events sent together keep their order.

#### Core Events

```typescript
// Track when user sees the experiment
await AbrovaAbTesting.trackView('experiment-key');

// Track click
await AbrovaAbTesting.trackClick('experiment-key');

// Track conversion with value
await AbrovaAbTesting.trackConversion('experiment-key', 300000);

// Track custom event
await AbrovaAbTesting.trackCustomEvent('experiment-key', 'button_hover', {
  duration_ms: 1500,
  element: 'cta_button',
});
```

#### Conversion Events

```typescript
await AbrovaAbTesting.trackAddToCart('experiment-key', 300000, 'sku-123', { quantity: 2 });
await AbrovaAbTesting.trackRemoveFromCart('experiment-key', 300000, 'sku-123');
await AbrovaAbTesting.trackBeginCheckout('experiment-key', 1500000, { coupon: 'SAVE10' });
await AbrovaAbTesting.trackPurchase('experiment-key', 1250000, 'txn-789', { currency: 'Toman' });
```

#### Engagement Events

```typescript
await AbrovaAbTesting.trackScroll('experiment-key', 75.0, { page: 'product' });
await AbrovaAbTesting.trackFormSubmit('experiment-key', 'signup_form');
await AbrovaAbTesting.trackSearch('experiment-key', 'search query', { results: 42 });
await AbrovaAbTesting.trackShare('experiment-key', 'twitter');
```

#### Media Events

```typescript
await AbrovaAbTesting.trackVideoStart('experiment-key', 'video-001');
await AbrovaAbTesting.trackVideoComplete('experiment-key', 'video-001');
```

#### Auth Events

```typescript
await AbrovaAbTesting.trackSignUp('experiment-key', 'google');
await AbrovaAbTesting.trackLogin('experiment-key', 'email');
await AbrovaAbTesting.trackLogout('experiment-key');
```

#### Generic Event

```typescript
import { EventType } from '@abrova/ab-testing-react-native';

await AbrovaAbTesting.trackEvent(
  'experiment-key',
  EventType.CUSTOM,
  'page_load_time',
  2.3,
  { page: '/checkout', cached: false }
);
```

<H2 id="feature-flags" step={6}>Feature Flags</H2>

Toggle features remotely without deploying new code. `isFeatureEnabled` and `getFeatureValue` are evaluated on the server for the signed-in user, so they need a user token too; while there is no token, or if the request fails, they return the default you pass.

```typescript
// Check if feature is enabled
const isDarkMode = await AbrovaAbTesting.isFeatureEnabled('dark-mode');

if (isDarkMode) {
  enableDarkTheme();
}

// Get feature value (string, number, JSON, etc.)
const maxUpload = await AbrovaAbTesting.getFeatureValue('max-upload-size', 10);

// Get all feature flags
const flags = await AbrovaAbTesting.getFeatureFlags();
flags.forEach((flag) => {
  console.log(`${flag.key}: enabled=${flag.enabled}, rollout=${flag.rolloutPercentage}%`);
});

// Refresh flags from server
await AbrovaAbTesting.refreshFeatureFlags();
```

<H2 id="user-identification" step={7}>User Identification</H2>

With a user token, the token says who the user is, so `setUserId` is optional. If you call it, do so on login with the ID the token is minted for, and call `clearUserId()` on logout.

When a user signs out (`clearUserId()`, `setUserToken(null)`) or another signs in (`setUserId` with their ID, or a token for another user), the previous user's variants, attributes, token and unsent events are dropped, on the device too, before anything is sent for the next one. Events still waiting go out under the previous user's own token, never under another user's.

```typescript
// Set user ID (e.g., after login)
await AbrovaAbTesting.setUserId('user-123');

// Sign the user out: drop their data, token and unsent events
await AbrovaAbTesting.clearUserId();

// Get current user ID
const userId = await AbrovaAbTesting.getUserId();

// Set user attributes for targeting
await AbrovaAbTesting.setUserAttributes({
  plan: 'premium',
  country: 'US',
  age: 25,
  platform: 'react-native',
});
```

<H2 id="event-listeners" step={8}>Event Listeners</H2>

Subscribe to SDK lifecycle events.

```typescript
// Listen for experiment assignments
const unsub1 = AbrovaAbTesting.on('experimentAssigned', (event) => {
  console.log('Assigned:', event.data);
});

// Listen for experiments refresh
const unsub2 = AbrovaAbTesting.on('experimentsRefreshed', (event) => {
  console.log('Experiments refreshed:', event.data);
});

// Listen for feature flag updates
const unsub3 = AbrovaAbTesting.on('featureFlagsRefreshed', (event) => {
  console.log('Feature flags refreshed');
});

// Listen for sync events
const unsub4 = AbrovaAbTesting.on('syncCompleted', (event) => {
  console.log('Sync:', event.data);
});

// Listen for errors
const unsub5 = AbrovaAbTesting.on('error', (event) => {
  console.error('Error:', event.data);
});

// The SDK started waiting for a user token / a token arrived
const unsub6 = AbrovaAbTesting.on('awaitingUserToken', () => {
  console.log('Waiting for sign-in');
});
const unsub7 = AbrovaAbTesting.on('userTokenReady', () => {
  console.log('User token ready: read variants again');
});

// Cleanup in useEffect
useEffect(() => {
  return () => {
    unsub1();
    unsub2();
    unsub3();
    unsub4();
    unsub5();
    unsub6();
    unsub7();
  };
}, []);
```

<H2 id="lifecycle" step={9}>Lifecycle</H2>

```typescript
// Refresh experiments from server
await AbrovaAbTesting.refreshExperiments();

// Get all experiments
const experiments = await AbrovaAbTesting.getExperiments();

// Flush pending events immediately
// (the SDK also sends queued events when the app goes to the background)
await AbrovaAbTesting.flush();

// Wipe all SDK state, including unsent events. You must call init() again afterwards.
// To sign a user out, call clearUserId() instead.
await AbrovaAbTesting.reset();
```

### EventType Enum

<ConfigTable rows={[
  ['EventType.VIEW', '-', '-', 'trackView()'],
  ['EventType.CLICK', '-', '-', 'trackClick()'],
  ['EventType.CONVERSION', '-', '-', 'trackConversion()'],
  ['EventType.CUSTOM', '-', '-', 'trackCustomEvent()'],
  ['EventType.SCROLL', '-', '-', 'trackScroll()'],
  ['EventType.FORM_SUBMIT', '-', '-', 'trackFormSubmit()'],
  ['EventType.SEARCH', '-', '-', 'trackSearch()'],
  ['EventType.SHARE', '-', '-', 'trackShare()'],
  ['EventType.ADD_TO_CART', '-', '-', 'trackAddToCart()'],
  ['EventType.REMOVE_FROM_CART', '-', '-', 'trackRemoveFromCart()'],
  ['EventType.BEGIN_CHECKOUT', '-', '-', 'trackBeginCheckout()'],
  ['EventType.PURCHASE', '-', '-', 'trackPurchase()'],
  ['EventType.VIDEO_START', '-', '-', 'trackVideoStart()'],
  ['EventType.VIDEO_COMPLETE', '-', '-', 'trackVideoComplete()'],
  ['EventType.SIGN_UP', '-', '-', 'trackSignUp()'],
  ['EventType.LOGIN', '-', '-', 'trackLogin()'],
  ['EventType.LOGOUT', '-', '-', 'trackLogout()'],
]} />

### API Reference

<ConfigTable rows={[
  ['init(config)', '-', '-', 'Initialize the SDK (pass `tokenProvider`)'],
  ['setUserId(id)', '-', '-', 'Set the signed-in user. Optional with a user token'],
  ['clearUserId()', '-', '-', 'Sign the user out: drop their data, token and unsent events'],
  ['isAwaitingUserToken', '-', '-', '`true` while the SDK waits for a user token'],
  ['onAwaitingUserToken(callback)', '-', '-', 'Called each time the SDK starts waiting; returns an unsubscribe function'],
  ['setUserToken(token)', '-', '-', 'Hand over a user token; `null` when the user signs out'],
  ['refreshUserToken()', '-', '-', 'Ask `tokenProvider` again (call on sign-in and sign-out)'],
  ['getUserId()', '-', '-', 'Get current user ID'],
  ['setUserAttributes(attrs)', '-', '-', 'Set targeting attributes'],
  ['getVariant(key, default?)', '-', '-', 'Get assigned variant'],
  ['getVariantConfig(key)', '-', '-', 'Get variant configuration'],
  ['isFeatureEnabled(key, default?)', '-', '-', 'Check if feature flag is on'],
  ['getFeatureValue(key, default?)', '-', '-', 'Get feature flag value'],
  ['getFeatureFlags()', '-', '-', 'Get all feature flags'],
  ['refreshFeatureFlags()', '-', '-', 'Refresh flags from server'],
  ['getExperiments()', '-', '-', 'Get all experiments'],
  ['refreshExperiments()', '-', '-', 'Refresh experiments from server'],
  ['trackEvent(key, type, ...)', '-', '-', 'Track generic event'],
  ['flush()', '-', '-', 'Force sync pending events'],
  ['reset()', '-', '-', 'Clear all state, cache and unsent events'],
  ['on(event, callback)', '-', '-', 'Subscribe to SDK events'],
  ['off(event, callback)', '-', '-', 'Unsubscribe from events'],
]} />

### Complete Example

A complete example showing A/B testing in a React Native checkout screen:

```typescript
import React, { useEffect, useState } from 'react';
import {
  View, Text, TouchableOpacity, StyleSheet,
  ActivityIndicator,
} from 'react-native';
import AbrovaAbTesting from '@abrova/ab-testing-react-native';

// fetchAbrovaToken() calls your backend — see Initialization.

function CheckoutScreen() {
  const [variant, setVariant] = useState<string | null>(null);
  const [loading, setLoading] = useState(true);
  const orderTotal = 1000000;

  useEffect(() => {
    const init = async () => {
      await AbrovaAbTesting.init({
        apiKey: 'YOUR_API_KEY',
        tokenProvider: fetchAbrovaToken,
        debug: __DEV__,
      });
      await AbrovaAbTesting.setUserId('user-123');

      const v = await AbrovaAbTesting.getVariant('checkout-style', 'control');
      setVariant(v);
      setLoading(false);

      await AbrovaAbTesting.trackView('checkout-style');
    };
    init();
  }, []);

  const handleCheckout = async () => {
    await AbrovaAbTesting.trackClick('checkout-style');
    await AbrovaAbTesting.trackConversion('checkout-style', orderTotal);
    console.log('Checkout completed!');
  };

  if (loading) {
    return (
      <View style={styles.center}>
        <ActivityIndicator size="large" />
      </View>
    );
  }

  const buttonColor = variant === 'Variant B' ? '#22C55E' : '#6B7280';

  return (
    <View style={styles.container}>
      <Text style={styles.title}>Order Summary</Text>
      <Text style={styles.total}>Total: ${orderTotal.toFixed(2)}</Text>

      <TouchableOpacity
        style={[styles.button, { backgroundColor: buttonColor }]}
        onPress={handleCheckout}
      >
        <Text style={styles.buttonText}>Complete Purchase</Text>
      </TouchableOpacity>
    </View>
  );
}

const styles = StyleSheet.create({
  container: { flex: 1, padding: 20, backgroundColor: '#fff' },
  center: { flex: 1, justifyContent: 'center', alignItems: 'center' },
  title: { fontSize: 24, fontWeight: 'bold', marginBottom: 16 },
  total: { fontSize: 18, color: '#6B7280', marginBottom: 32 },
  button: { padding: 16, borderRadius: 8, alignItems: 'center' },
  buttonText: { color: '#fff', fontSize: 18, fontWeight: '600' },
});

export default CheckoutScreen;
```

- Next.js: https://abrova.ir/en/docs/ab-testing/nextjs

<Callout kind="note" title="AbrovaAbTesting Next.js SDK v0.2.3">
Browser SDK for A/B testing and feature flags on Next.js and React. React Provider for context-based access, useVariant / useFeatureFlag / useFeatureValue hooks, compatible with both App Router and Pages Router. Installs from Abrova Center.
</Callout>

<Callout kind="note" title="Requirements">
- Next.js 13+ (App Router or Pages Router). 
- React 17.0.0 or higher. 
- TypeScript supported out of the box. 
- A backend route that mints Abrova user tokens (see step 2).
</Callout>

<Callout kind="warn" title="User tokens">
Signed user tokens are **required** for anything that acts for a user: assigning variants, tracking events and conversions, and evaluating feature flags. Add a `tokenProvider` to your config (see step 2). Reading the experiment and flag lists still works with the API key alone, so a page can load them before anyone signs in.

New in 0.2.2: you can start the SDK before sign-in. It waits for the user token instead of failing, and the hooks render again with the real values when the token arrives.
</Callout>

<H2 id="installation" step={1}>Installation</H2>

```bash
# 1. .npmrc in your project root: @abrova packages come from Abrova Center
@abrova:registry=https://center.abrova.ir/api/packages/abrova/npm/
```

```bash
# 2. Install
npm install @abrova/ab-testing-nextjs@^0.2.3
```

Or with Yarn:

```bash
yarn add @abrova/ab-testing-nextjs@^0.2.3
```

<H2 id="user-tokens" step={2}>User tokens</H2>

Anyone can read the API key out of your site, so on its own it can't prove which user a request is for. Your server can: it holds your project's **server secret** and mints a short-lived token for the signed-in user. The SDK sends that token, and the service takes the user from it.

#### Mint the token on your server

Call the Abrova auth endpoint from your backend with your API key and server secret:

```bash
curl -X POST https://auth.abrova.ir/users/token \
  -H "x-api-key: $ABROVA_API_KEY" \
  -H "x-server-secret: $ABROVA_SERVER_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"userId": "user-123", "expiresIn": 3600}'

# → { "token": "eyJhbGciOi…", "userId": "user-123", "expiresIn": 3600, "expiresAt": "…" }
```

`expiresIn` is in seconds: 3600 (1 hour) by default, 86400 (24 hours) maximum.

In a Next.js route handler, the [Node.js SDK](/docs/ab-testing/nodejs) makes the same call for you with `createUserToken`:

```typescript
// app/api/abrova-token/route.ts  (runs on your server)
import { AbrovaAbTesting } from '@abrova/ab-testing-node';

const ready = AbrovaAbTesting.init({
  apiKey: process.env.ABROVA_API_KEY!,
  serverSecret: process.env.ABROVA_SERVER_SECRET,
});

export async function POST() {
  const session = await getSession(); // your auth
  if (!session) return new Response(null, { status: 401 });

  await ready;
  return Response.json(await AbrovaAbTesting.createUserToken(session.user.id));
}
```

<Callout kind="warn" title="Keep the server secret on the server">
Never put the server secret in client code, a Client Component, or a `NEXT_PUBLIC_` variable. Only your route handler reads it; the browser only ever sees the user token.
</Callout>

#### One token for A/B Testing, Chat and Sync

The token is the same Abrova user token used by Abrova Chat and Abrova Sync. If your app uses them too, mint **one** token and give it to every SDK's `tokenProvider` instead of fetching one per product.

#### Give it to the SDK

Pass a `tokenProvider` that calls your route. The SDK caches the token, asks again shortly before it expires, and asks once more if the service reports it expired. Return `null` while no one is signed in.

```typescript
async function fetchAbrovaToken(): Promise<string | null> {
  const res = await fetch('/api/abrova-token', { method: 'POST' });
  if (res.status === 401) return null; // no one signed in: the SDK waits
  if (!res.ok) throw new Error('Could not get an Abrova token');
  return (await res.json()).token;
}
```

If you already hold a token, you can pass it as `userToken` instead, and hand over a newer one with `setUserToken(token)`. `tokenProvider` is preferred: a static token expires.

The service takes the user from the token, so the SDK does too: you may leave `userId` out and let the token say who the user is.

#### Before your user signs in

You can start the SDK before anyone is signed in: return `null` from `tokenProvider` and call `refreshUserToken()` when the user signs in or out. If you hand tokens over yourself, call `setUserToken(token)` on sign-in and `setUserToken(null)` on sign-out.

Until it has a token, the SDK waits: `getVariant`, the flag getters and the hooks return your defaults at once, nothing is sent, and nothing is reported as an error. When the token arrives, the SDK continues by itself and the hooks render again with the real values.

```typescript
AbrovaAbTesting.isAwaitingUserToken;             // true while it waits
AbrovaAbTesting.onAwaitingUserToken(() => {});   // called each time it starts waiting; returns an unsubscribe function
AbrovaAbTesting.on('userTokenReady', () => {});  // a token arrived: read variants again

// After sign-in
await AbrovaAbTesting.refreshUserToken();        // with a tokenProvider: asks it again now
await AbrovaAbTesting.setUserToken(token);       // without one: hand the token over

// After sign-out
await AbrovaAbTesting.clearUserId();             // or setUserToken(null)
```

If you pass `userId` to `AbrovaAbTestingProvider`, the provider makes the sign-in and sign-out calls for you when `userId` changes.

Events tracked while the SDK waits are kept (up to 1,000, the oldest dropped first). After sign-in they are sent **only if they were recorded for that same user**, that is, `setUserId` was called with their ID before the token arrived. Events recorded while no user was set belong to nobody, are not credited to anyone, and are dropped when a user signs in.

<Callout kind="note" title="Keep it for the session">
A token is valid until it expires. The SDK keeps it in memory and reuses it for every request, calling your route again only when it is close to expiry or after a full page reload. To avoid that call on reloads, your `tokenProvider` can return a token you kept with the user's session until it nears expiry.
</Callout>

<H2 id="initialization" step={3}>Initialization</H2>

The SDK runs in the browser. `init()` is ignored on the server, so no visitor's state is shared between requests. For server code (route handlers, Server Components, middleware), use the [Node.js SDK](/docs/ab-testing/nodejs).

#### Option 1: React Provider (Recommended)

```typescript
// app/providers.tsx
'use client';

import { AbrovaAbTestingProvider } from '@abrova/ab-testing-nextjs/react';

export function Providers({
  userId,
  children,
}: {
  userId?: string;
  children: React.ReactNode;
}) {
  return (
    <AbrovaAbTestingProvider
      config={{
        apiKey: 'YOUR_API_KEY',
        tokenProvider: fetchAbrovaToken,
        debug: process.env.NODE_ENV === 'development',
      }}
      userId={userId}
      userAttributes={{ plan: 'premium', country: 'US' }}
    >
      {children}
    </AbrovaAbTestingProvider>
  );
}

// app/layout.tsx
import { Providers } from './providers';

export default async function RootLayout({ children }: { children: React.ReactNode }) {
  const session = await getSession(); // your auth

  return (
    <html>
      <body>
        <Providers userId={session?.user.id}>{children}</Providers>
      </body>
    </html>
  );
}
```

The provider follows `userId`. When it changes to another user (a login, a switch of account), the SDK sends the previous user's pending events under their own token, then clears their variants, attributes, token and unsent events before loading the new user's. Clearing `userId` on sign-out does the same and leaves nothing of the user in the browser.

`userId` is optional when you use a user token: the SDK takes the user from the token. In that case, call `AbrovaAbTesting.refreshUserToken()` when the user signs in or out.

#### Option 2: Direct Import

```typescript
'use client';

import { AbrovaAbTesting } from '@abrova/ab-testing-nextjs';

// Initialize once, in the browser (for example in a useEffect)
await AbrovaAbTesting.init({
  apiKey: 'YOUR_API_KEY',
  tokenProvider: fetchAbrovaToken,
  debug: process.env.NODE_ENV === 'development',
  // flushInterval: 10000, // your own send interval in ms; leave it out to follow the console
  maxQueueSize: 1000,
});

// Optional with a user token: the token says who the user is
await AbrovaAbTesting.setUserId(session.user.id);
```

`getVariant`, the flag getters and the `track…` methods never reject when you call them before `init()` or without a signed-in user: getters resolve with the default you pass, and tracking before `init()` does nothing.

<Callout kind="note" title="Client Components only">
Use the SDK in Client Components (`'use client'`). It reads `localStorage` and the DOM only when `typeof window !== 'undefined'`, so importing it from a server-rendered file is safe, but it does nothing there.
</Callout>

#### Send interval and list cache

Two values come from your project's settings in the Abrova console (**A/B Testing › Settings › Defaults**):

- **Send interval** — how often queued events are sent. The SDK follows it when you leave `flushInterval` out. A `flushInterval` you pass is your own and is always used.
- **List cache** — how long the SDK uses the experiment list before it asks the service again. There is no SDK option for it. Once the list is older than that, the SDK fetches it again in the background the next time your code reads a variant or tracks an event. The call doesn't wait for it, and a failed refresh does not emit an `error` event.

A change you make in the console (a new experiment, changed weights or traffic) reaches open pages within the list cache time, without a restart. A user who already has a variant keeps it. A changed send interval is picked up at that same refresh. The SDK keeps the console's values within safe limits, and sends every 30 seconds until it knows the console's value. Apps on SDK versions older than 0.2.3 keep their built-in behaviour.

From 0.2.3, a `flushInterval` set in code always wins.

<H2 id="react-hooks" step={4}>React Hooks</H2>

Use built-in hooks for seamless React integration. Requires `AbrovaAbTestingProvider`. Each hook returns its default value until the provider is ready and the user is set. While there is no user token, the hooks return their defaults with `isLoading` false, and render again when the token arrives or the user changes.

#### useVariant

```typescript
'use client';

import { useVariant } from '@abrova/ab-testing-nextjs/react';

function CheckoutButton() {
  const { variant, isLoading } = useVariant('checkout-button-style', 'control');

  if (isLoading) return <div>Loading...</div>;

  const buttonColor =
    variant === 'Variant A' ? '#22C55E' :
    variant === 'Variant B' ? '#3B82F6' : '#6B7280';

  return (
    <button style={{ backgroundColor: buttonColor }}>
      Checkout
    </button>
  );
}
```

#### useFeatureFlag

```typescript
import { useFeatureFlag } from '@abrova/ab-testing-nextjs/react';

function CheckoutPage() {
  const { enabled, isLoading } = useFeatureFlag('new-checkout-flow');

  if (isLoading) return <LoadingSpinner />;

  return enabled ? <NewCheckoutFlow /> : <LegacyCheckout />;
}
```

#### useFeatureValue

```typescript
import { useFeatureValue } from '@abrova/ab-testing-nextjs/react';

function Banner() {
  const { value, isLoading } = useFeatureValue('banner-text', 'Welcome!');

  if (isLoading) return null;

  return <div className="banner">{value as string}</div>;
}
```

#### useAbrovaAbTesting

Direct SDK access. It throws until the provider is ready (SDK initialized and user set), so only render components that use it after that, for example behind a hook's `isLoading`. Elsewhere, import `AbrovaAbTesting` directly as in the complete example below.

```typescript
import { useAbrovaAbTesting } from '@abrova/ab-testing-nextjs/react';

function MyComponent() {
  const sdk = useAbrovaAbTesting();

  const handleClick = async () => {
    await sdk.trackClick('checkout-button-style');
  };

  return <button onClick={handleClick}>Buy Now</button>;
}
```

<H2 id="getting-experiment-variants" step={5}>Getting Experiment Variants</H2>

The variant always comes from the service (this needs a user token) and is cached for the user; the SDK never works one out in the browser. The assignment is sticky: the same user keeps the same variant.

`getVariant` and `useVariant` return the variant's **name** as it appears in Abrova Console (for example `Control` or `Variant B`), not its key (`control`, `variant-b`).

```typescript
import { AbrovaAbTesting } from '@abrova/ab-testing-nextjs';

// Get variant
const variant = await AbrovaAbTesting.getVariant(
  'checkout-button-color',
  'control'  // returned while there is no user token, or when the service
             // cannot be reached and nothing is cached
);

// Use the variant
switch (variant) {
  case 'Variant A':
    buttonColor = '#22C55E';  // green
    break;
  case 'Variant B':
    buttonColor = '#3B82F6';  // blue
    break;
  default:
    buttonColor = '#6B7280';  // gray (control)
}
```

#### Getting Variant Configuration

```typescript
const config = await AbrovaAbTesting.getVariantConfig('checkout-button-color');

const buttonText = config?.buttonText ?? 'Buy Now';
const buttonColor = config?.buttonColor ?? '#6B7280';
```

#### Listing Experiments

Reading the experiment list works with the API key alone.

```typescript
const experiments = await AbrovaAbTesting.getExperiments();
experiments.forEach((exp) => {
  console.log(`${exp.key}: ${exp.variants.length} variants`);
});
```

<H2 id="tracking-events" step={6}>Tracking Events</H2>

Track user interactions to measure experiment results. The SDK supports 17 event types. Events are queued in the browser and sent in batches with the user's token; if no valid token is available yet, they stay queued and are sent once one is (see "Before your user signs in" in step 2 for which events are credited). The queue holds at most 1,000 events (the oldest are dropped first), and the SDK waits before retrying when the service is busy or your project has reached its usage limit. Each event carries the time your app recorded it, so events sent together keep their order.

#### Core Events

```typescript
import { AbrovaAbTesting } from '@abrova/ab-testing-nextjs';

// Track view
await AbrovaAbTesting.trackView('checkout-button-color');

// Track click
await AbrovaAbTesting.trackClick('checkout-button-color');

// Track conversion with value
await AbrovaAbTesting.trackConversion('checkout-button-color', 300000);

// Track custom event
await AbrovaAbTesting.trackCustomEvent(
  'checkout-button-color',
  'add_to_cart',
  { product_id: 'SKU123', quantity: 2 }
);
```

#### Conversion Events

```typescript
await AbrovaAbTesting.trackAddToCart('experiment-key', 500000, 'prod-123', {
  category: 'electronics',
});

await AbrovaAbTesting.trackPurchase('experiment-key', 1250000, 'txn-789', {
  currency: 'Toman',
  items: 3,
});

await AbrovaAbTesting.trackBeginCheckout('experiment-key', 1500000);
await AbrovaAbTesting.trackRemoveFromCart('experiment-key', 500000, 'prod-123');
```

#### Engagement Events

```typescript
await AbrovaAbTesting.trackScroll('experiment-key', 75, { section: 'pricing' });
await AbrovaAbTesting.trackFormSubmit('experiment-key', 'checkout_form');
await AbrovaAbTesting.trackSearch('experiment-key', 'search query');
await AbrovaAbTesting.trackShare('experiment-key', 'twitter');
```

#### Auth & Media Events

```typescript
await AbrovaAbTesting.trackSignUp('experiment-key', 'google');
await AbrovaAbTesting.trackLogin('experiment-key', 'email');
await AbrovaAbTesting.trackLogout('experiment-key');

await AbrovaAbTesting.trackVideoStart('experiment-key', 'video-id');
await AbrovaAbTesting.trackVideoComplete('experiment-key', 'video-id');
```

<H2 id="user-identification" step={7}>User Identification</H2>

```typescript
// Set user ID (persisted in localStorage)
await AbrovaAbTesting.setUserId('user-123');

// Get current user ID
const userId = await AbrovaAbTesting.getUserId();

// On sign-out: send the user's events, then drop their data
await AbrovaAbTesting.clearUserId();

// Set user attributes for targeting
await AbrovaAbTesting.setUserAttributes({
  plan: 'premium',
  country: 'US',
  age: 25,
  is_beta_user: true,
});
```

With a user token, `setUserId` is optional: the token says who the user is. If you call it, the user ID must match the user your `tokenProvider` returns a token for.

When a user signs out (`clearUserId()`, `setUserToken(null)`) or another signs in (`setUserId` with their ID, or a token for another user), the previous user's variants, attributes, token and unsent events are dropped before anything is sent for the next one. Events still waiting go out under the previous user's own token, never under another user's.

<H2 id="feature-flags" step={8}>Feature Flags</H2>

Evaluating a flag for a user (`isFeatureEnabled`, `getFeatureValue`) needs the user token. Listing flags (`getFeatureFlags`) works with the API key alone. While there is no token, or if evaluation fails, you get the default value you passed.

```typescript
// Check if feature is enabled
const isEnabled = await AbrovaAbTesting.isFeatureEnabled('new-checkout-flow', false);

if (isEnabled) {
  showNewCheckout();
} else {
  showLegacyCheckout();
}

// Get feature value
const value = await AbrovaAbTesting.getFeatureValue('banner-text', 'Welcome');

// Get all feature flags
const flags = await AbrovaAbTesting.getFeatureFlags();
flags.forEach((flag) => {
  console.log(`${flag.key}: ${flag.enabled ? 'ON' : 'OFF'}`);
});

// Refresh flags from server (emits 'featureFlagsRefreshed')
await AbrovaAbTesting.refreshFeatureFlags();
```

<H2 id="advanced-usage" step={9}>Advanced Usage</H2>

#### Event Listeners

```typescript
const unsubscribe = AbrovaAbTesting.on('experimentAssigned', (event) => {
  const { experimentKey, variantKey } = event.data as { experimentKey: string; variantKey: string };
  console.log(`Assigned ${variantKey} for ${experimentKey}`);
});

AbrovaAbTesting.on('syncCompleted', (event) => {
  const { synced } = event.data as { synced: number };
  console.log(`Synced ${synced} events`);
});

// Also fires when the service rejects the user token (event.data.code says why)
AbrovaAbTesting.on('error', (event) => {
  console.error('SDK error:', (event.data as { message: string }).message);
});

// Cleanup
unsubscribe();
```

Available events: `initialized`, `error`, `experimentAssigned`, `experimentsRefreshed`, `featureFlagsRefreshed`, `syncCompleted`, `awaitingUserToken` (the SDK started waiting for a user token) and `userTokenReady` (a token arrived or the signed-in user changed: read variants again). (`offlineMode` and `onlineMode` are in the `AbrovaAbTestingEventType` type, but this SDK doesn't emit them.)

#### Manual Flush & Reset

```typescript
// Flush events immediately
await AbrovaAbTesting.flush();

// Refresh experiments from server
await AbrovaAbTesting.refreshExperiments();

// Reset SDK: clears the user, token, cached assignments and queued events.
// Call init() again before using the SDK afterwards.
await AbrovaAbTesting.reset();
```

#### Flush on Page Hide

The SDK automatically sends queued events on `visibilitychange` (page hide). No additional setup needed.

### Complete Example

A complete Next.js App Router example with the Provider pattern:

```typescript
// app/providers.tsx
'use client';

import { AbrovaAbTestingProvider } from '@abrova/ab-testing-nextjs/react';

async function fetchAbrovaToken(): Promise<string | null> {
  const res = await fetch('/api/abrova-token', { method: 'POST' });
  if (res.status === 401) return null; // no one signed in: the SDK waits
  if (!res.ok) throw new Error('Could not get an Abrova token');
  return (await res.json()).token;
}

export function Providers({
  userId,
  children,
}: {
  userId?: string;
  children: React.ReactNode;
}) {
  return (
    <AbrovaAbTestingProvider
      config={{
        apiKey: 'YOUR_API_KEY',
        tokenProvider: fetchAbrovaToken,
        debug: process.env.NODE_ENV === 'development',
      }}
      userId={userId}
    >
      {children}
    </AbrovaAbTestingProvider>
  );
}

// app/checkout/page.tsx
'use client';

import { useEffect } from 'react';
import {
  AbrovaAbTesting,
  useVariant,
  useFeatureFlag,
} from '@abrova/ab-testing-nextjs/react';

export default function CheckoutPage() {
  const { variant, isLoading } = useVariant('checkout-style', 'control');
  const { enabled: showBanner } = useFeatureFlag('promo-banner');

  useEffect(() => {
    // isLoading turns false once the SDK is ready and the user is set
    if (!isLoading) {
      AbrovaAbTesting.trackView('checkout-style');
    }
  }, [isLoading]);

  const handlePurchase = async (total: number) => {
    await AbrovaAbTesting.trackConversion('checkout-style', total);
    await AbrovaAbTesting.trackPurchase('checkout-style', total, 'txn-' + Date.now());
  };

  if (isLoading) return <div>Loading...</div>;

  return (
    <div>
      {showBanner && <div className="promo">Special Offer!</div>}

      <h1>Checkout ({variant})</h1>

      <button
        style={{
          backgroundColor: variant === 'Variant B' ? '#3B82F6' : '#6B7280',
        }}
        onClick={() => handlePurchase(1000000)}
      >
        Complete Purchase
      </button>
    </div>
  );
}
```

The token route is the `app/api/abrova-token/route.ts` handler from step 2.

### Best Practices

<BestPracticeList columns={2} items={[
  ['Mint tokens on your server', 'Only your backend holds the server secret. The browser calls your route and gets a short-lived user token back.'],
  ['One token for every Abrova SDK', 'The same user token works for A/B Testing, Chat and Sync. Fetch it once and share it.'],
  ['Follow sign-in and sign-out', 'Give the provider the same user your token route mints for and change it on login and logout, or leave `userId` out and call `refreshUserToken()`. Either way the last user\'s variants are cleared.'],
  ['Browser only', 'Use this SDK in Client Components. For route handlers and Server Components, use @abrova/ab-testing-node with forUser().'],
]} />

### TypeScript Types

The SDK includes full TypeScript support with exported types:

```typescript
import type {
  AbrovaAbTestingConfig,
  Experiment,
  Variant,
  Assignment,
  FeatureFlag,
  FlagVariant,
  AbrovaAbTestingEventType,
  AbrovaAbTestingEvent,
} from '@abrova/ab-testing-nextjs';
import { EventType } from '@abrova/ab-testing-nextjs';

interface AbrovaAbTestingConfig {
  apiKey: string;
  tokenProvider?: () => string | null | undefined | Promise<string | null | undefined>; // a user token minted by your server; null while no one is signed in
  userToken?: string;       // a token you already hold (tokenProvider is preferred)
  debug?: boolean;
  flushInterval?: number;   // ms between sends; leave it out to follow the console's Send interval
  maxQueueSize?: number;    // events kept while they cannot be sent (default and maximum: 1000)
}

interface Experiment {
  id: string;
  key: string;
  name: string;
  status: 'draft' | 'running' | 'paused' | 'completed' | 'archived';
  trafficAllocation: number;
  variants: Variant[];
}

interface FeatureFlag {
  key: string;
  enabled: boolean;
  rolloutPercentage: number;
  targetingRules?: Record<string, unknown>;
  variants?: FlagVariant[];
  defaultValue?: unknown;
}
```

- Node.js: https://abrova.ir/en/docs/ab-testing/nodejs

<Callout kind="note" title="AbrovaAbTesting Node.js SDK v0.2.3">
Server-side SDK for Node.js backends and APIs. One handle per request with `forUser()`, so users never see each other's variants. Proves it runs on your server with your project's server secret, mints user tokens for your apps with `createUserToken()`, and flushes pending events on graceful shutdown with `destroy()`. Zero dependencies.
</Callout>

<Callout kind="note" title="Requirements">
- Node.js 18 or newer (the SDK uses the built-in `fetch`). 
- TypeScript supported out of the box. 
- Your project's API key and server secret.
</Callout>

<Callout kind="warn" title="What to know">
- `forUser(userId, attributes)` returns a handle that acts for one user. Use one per request on a server.
- `serverSecret` in `init()`: required for anything that acts for a user (assigning variants, tracking events, evaluating flags). From 0.2.2, `init()` warns when it is missing.
- `createUserToken(userId, expiresIn?)` mints the user token your browser and mobile apps need.
- Variants are decided by the service only. When it can't be asked, `getVariant` returns the cached assignment or your default.
- `setUserId` remains for scripts and single-user processes only.
</Callout>

<Callout kind="note" title="Server-Side vs Client-Side">
- In-memory storage: assignments are kept in memory per user and experiment, not in localStorage
- Per-request users: `forUser()` handles carry their own user, so concurrent requests never overwrite each other
- Server secret instead of user tokens: your server is trusted with the user ids it passes
- `destroy()` method: flushes pending events before cleanup (use in graceful shutdown)
</Callout>

<H2 id="installation" step={1}>Installation</H2>

```bash
# 1. .npmrc in your project root: @abrova packages come from Abrova Center
@abrova:registry=https://center.abrova.ir/api/packages/abrova/npm/
```

```bash
# 2. Install
npm install @abrova/ab-testing-node@^0.2.3
```

Or with Yarn:

```bash
yarn add @abrova/ab-testing-node@^0.2.3
```

<H2 id="server-secret-and-user-tokens" step={2}>Server secret and user tokens</H2>

This SDK runs on your server, so it proves that with your project's **server secret** (`serverSecret` in `init`). The service then trusts the user ids you pass to `forUser()`. Listing experiments and flags works with the API key alone, but assigning variants, tracking events and evaluating flags are refused without the secret. `init()` prints a warning when `serverSecret` is missing; variants and flags then come back as your defaults, events stay in the queue (at most 1,000), and the refusal is reported once through the `error` event.

```typescript
import { AbrovaAbTesting } from '@abrova/ab-testing-node';

await AbrovaAbTesting.init({
  apiKey: process.env.ABROVA_API_KEY!,
  serverSecret: process.env.ABROVA_SERVER_SECRET, // from Abrova Console; server only
});
```

<Callout kind="warn" title="Keep the server secret on the server">
Never put the server secret in an app, a browser bundle, a `NEXT_PUBLIC_` variable, or a public repo. Load it from your server's environment or secret store.
</Callout>

#### Mint user tokens for your apps

Your browser and mobile apps can't hold the secret. They send a short-lived **user token** that your server mints for the signed-in user. `createUserToken` does that for you:

```typescript
app.post('/abrova-token', requireLogin, async (req, res) => {
  // expiresIn is optional: seconds, 3600 by default, 86400 max
  res.json(await AbrovaAbTesting.createUserToken(req.session.userId, 3600));
});
// → { "token": "eyJhbGciOi…", "userId": "user-123", "expiresIn": 3600, ... }
```

It calls the Abrova auth endpoint with your API key and server secret. From any other backend language, make the same call directly:

```bash
curl -X POST https://auth.abrova.ir/users/token \
  -H "x-api-key: $ABROVA_API_KEY" \
  -H "x-server-secret: $ABROVA_SERVER_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"userId": "user-123", "expiresIn": 3600}'

# → { "token": "eyJhbGciOi…", "userId": "user-123", "expiresIn": 3600, "expiresAt": "…" }
```

Only mint a token for the user who is signed in on that request. Your app's SDK gets it through its `tokenProvider`, which calls this endpoint.

#### One token for A/B Testing, Chat and Sync

The token is the same Abrova user token used by Abrova Chat and Abrova Sync. If your app uses them too, mint **one** token from this endpoint and give it to every SDK's `tokenProvider` instead of minting one per product.

<Callout kind="note" title="Keep it on the device">
A token is valid until it expires, so your app should store it with the user's session and reuse it. The app SDKs cache the token and only call your endpoint again shortly before it expires, not on every request.
</Callout>

<H2 id="initialization" step={3}>Initialization</H2>

Initialize once, when your server starts. Use the default singleton or create your own instances.

#### Singleton (Simple)

```typescript
import { AbrovaAbTesting } from '@abrova/ab-testing-node';

await AbrovaAbTesting.init({
  apiKey: process.env.ABROVA_API_KEY!,
  serverSecret: process.env.ABROVA_SERVER_SECRET,
  debug: process.env.NODE_ENV !== 'production',
  // flushInterval: 10000, // your own send interval in ms; leave it out to follow the console
});
```

#### Multiple Instances (Multi-Tenant)

```typescript
import { AbrovaAbTestingSDK } from '@abrova/ab-testing-node';

// Create separate instances per project
const tenantA = new AbrovaAbTestingSDK();
await tenantA.init({ apiKey: 'ab_live_tenant_a_key', serverSecret: process.env.TENANT_A_SECRET });

const tenantB = new AbrovaAbTestingSDK();
await tenantB.init({ apiKey: 'ab_live_tenant_b_key', serverSecret: process.env.TENANT_B_SECRET });

const user = tenantA.forUser('user-123');
```

#### Send interval and list cache

Two values come from your project's settings in the Abrova console (**A/B Testing › Settings › Defaults**):

- **Send interval** — how often queued events are sent. The SDK follows it when you leave `flushInterval` out. A `flushInterval` you pass is your own and is always used.
- **List cache** — how long the SDK uses the experiment list before it asks the service again. There is no SDK option for it. Once the list is older than that, the SDK fetches it again in the background the next time your code reads a variant or tracks an event. The call doesn't wait for it, and a failed refresh does not emit an `error` event.

A change you make in the console (a new experiment, changed weights or traffic) reaches running servers within the list cache time, without a restart. A user who already has a variant keeps it. A changed send interval is picked up at that same refresh. The SDK keeps the console's values within safe limits, and sends every 30 seconds until it knows the console's value. Apps on SDK versions older than 0.2.3 keep their built-in behaviour.

From 0.2.3, a `flushInterval` set in code always wins.

<H2 id="user-management" step={4}>User Management</H2>

A server answers many users at once. Always go through `forUser(userId, attributes)`: each handle carries its own user and attributes, and assignments are cached per user and experiment, so one user's variant is never served to another. Handles are cheap: create one per request.

```typescript
import { AbrovaAbTesting } from '@abrova/ab-testing-node';

const user = AbrovaAbTesting.forUser('user-123', {
  plan: 'premium',
  country: 'US',
  app_version: '2.0.0',
});

user.userId; // 'user-123'

const variant = await user.getVariant('checkout-flow', 'control');
```

#### Express.js Middleware Example

```typescript
import express from 'express';
import { AbrovaAbTesting } from '@abrova/ab-testing-node';

const app = express();

// Initialize once at startup
await AbrovaAbTesting.init({
  apiKey: process.env.ABROVA_API_KEY!,
  serverSecret: process.env.ABROVA_SERVER_SECRET,
});

// Per-request handle
app.use((req, res, next) => {
  if (req.user) {
    res.locals.ab = AbrovaAbTesting.forUser(req.user.id, {
      plan: req.user.plan,
      country: req.headers['cf-ipcountry'] || 'unknown',
    });
  }
  next();
});

app.get('/checkout', async (req, res) => {
  const variant = await res.locals.ab.getVariant('checkout-flow', 'control');
  res.json({ variant });
});
```

<Callout kind="warn" title="setUserId is for single-user processes">
`setUserId()` / `setUserAttributes()` set the SDK's own user and still work for scripts, workers and CLIs that act for one user. On a server, two requests would overwrite each other's user, so don't use them there.
</Callout>

<H2 id="getting-experiment-variants" step={5}>Getting Experiment Variants</H2>

The examples below use `user = AbrovaAbTesting.forUser(userId)`. `getVariant` returns the variant's **name** as it appears in Abrova Console (for example `Control` or `Variant B`), not its key (`control`, `variant-b`). The variant always comes from the service and is cached in memory per user and experiment; the SDK never works one out itself. If the service doesn't return an assignment (it can't be reached, or `serverSecret` is missing) and nothing is cached, you get your default.

```typescript
// Get variant for this user
const variant = await user.getVariant(
  'checkout-button-color',
  'control'  // returned when the service refuses or cannot be reached and nothing is cached
);

// Use in your response
if (variant === 'Variant B') {
  return { layout: 'modern', color: '#22C55E' };
} else {
  return { layout: 'classic', color: '#6B7280' };
}

// Get variant configuration
const config = await user.getVariantConfig('checkout-button-color');

// Get all experiments (not user specific, synchronous)
const experiments = AbrovaAbTesting.getExperiments();
```

<H2 id="tracking-events" step={6}>Tracking Events</H2>

Track server-side events. All 17 event types are supported. Events are queued in memory and sent in batches. The queue holds at most 1,000 events, and the SDK waits before retrying when the service is busy or your project has reached its usage limit. Events the service refuses (for example, no `serverSecret`) stay in the queue and are reported once through the `error` event. Each event carries the time your server recorded it, so events sent together keep their order.

```typescript
import { EventType } from '@abrova/ab-testing-node';

// Core events
await user.trackView('checkout-flow');
await user.trackClick('checkout-flow');
await user.trackConversion('checkout-flow', 1000000);
await user.trackCustomEvent('checkout-flow', 'api_call', {
  endpoint: '/api/checkout',
  duration_ms: 250,
});

// Conversion
await user.trackPurchase('checkout-flow', 1250000, 'txn-123', {
  currency: 'Toman',
});

// Auth events
await user.trackSignUp('onboarding-flow', 'google');
await user.trackLogin('onboarding-flow', 'email');

// Generic event
await user.trackEvent(
  'checkout-flow',
  EventType.CUSTOM,
  'page_load',
  1.5,
  { route: '/checkout' }
);
```

<H2 id="feature-flags" step={7}>Feature Flags</H2>

Evaluating a flag for a user goes through the user handle and needs the server secret. Listing flags is not user specific and works with the API key alone.

```typescript
// Check if feature is enabled for this user
const isEnabled = await user.isFeatureEnabled(
  'new-checkout-flow',
  false  // default value
);

// Get feature value for this user
const maxRetries = await user.getFeatureValue(
  'max-retries',
  3  // default
);

// Get all flags
const flags = await AbrovaAbTesting.getFeatureFlags();

// Refresh flags from server (emits 'featureFlagsRefreshed')
await AbrovaAbTesting.refreshFeatureFlags();
```

<H2 id="lifecycle-graceful-shutdown" step={8}>Lifecycle & Graceful Shutdown</H2>

Important for server applications: flush events before shutting down.

```typescript
import { AbrovaAbTesting } from '@abrova/ab-testing-node';

// Flush events immediately
await AbrovaAbTesting.flush();

// Graceful shutdown: flushes pending events, then cleans up
await AbrovaAbTesting.destroy();

// Use with process signals
process.on('SIGTERM', async () => {
  console.log('Shutting down...');
  await AbrovaAbTesting.destroy();
  process.exit(0);
});

process.on('SIGINT', async () => {
  await AbrovaAbTesting.destroy();
  process.exit(0);
});
```

#### Reset (without flush)

```typescript
// Reset immediately: clears state without flushing
AbrovaAbTesting.reset();
```

<H2 id="event-listeners" step={9}>Event Listeners</H2>

```typescript
const unsubscribe = AbrovaAbTesting.on('experimentAssigned', (event) => {
  const { variantKey } = event.data as { variantKey: string };
  console.log(`User assigned to ${variantKey}`);
});

AbrovaAbTesting.on('syncCompleted', (event) => {
  const { synced, pending } = event.data as { synced: number; pending: number };
  console.log(`Synced ${synced} events, ${pending} pending`);
});

AbrovaAbTesting.on('error', (event) => {
  console.error('AbrovaAbTesting error:', (event.data as { message: string }).message);
});

// Cleanup
unsubscribe();
```

Available events: `initialized`, `error`, `experimentAssigned`, `experimentsRefreshed`, `featureFlagsRefreshed`, `syncCompleted`.

### Complete Express.js Example

```typescript
import express from 'express';
import { AbrovaAbTesting } from '@abrova/ab-testing-node';

const app = express();
app.use(express.json());

// Initialize SDK
await AbrovaAbTesting.init({
  apiKey: process.env.ABROVA_API_KEY!,
  serverSecret: process.env.ABROVA_SERVER_SECRET,
  debug: process.env.NODE_ENV !== 'production',
  flushInterval: 15000, // your own send interval; leave it out to follow the console
});

// One handle per request, for the signed-in user (your auth sets req.user)
app.use((req, res, next) => {
  if (!req.user) return res.sendStatus(401);
  res.locals.ab = AbrovaAbTesting.forUser(req.user.id, {
    plan: req.user.plan || 'free',
  });
  next();
});

// Mint an Abrova user token for your web and mobile apps
app.post('/api/abrova-token', async (req, res) => {
  res.json(await AbrovaAbTesting.createUserToken(req.user.id));
});

// Get variant for checkout experiment
app.get('/api/checkout-variant', async (req, res) => {
  const variant = await res.locals.ab.getVariant('checkout-flow', 'control');
  const config = await res.locals.ab.getVariantConfig('checkout-flow');
  res.json({ variant, config });
});

// Track purchase
app.post('/api/purchase', async (req, res) => {
  const { total, transactionId } = req.body;
  await res.locals.ab.trackPurchase('checkout-flow', total, transactionId);
  await res.locals.ab.trackConversion('checkout-flow', total);
  res.json({ success: true });
});

// Check feature flag
app.get('/api/feature/:key', async (req, res) => {
  const enabled = await res.locals.ab.isFeatureEnabled(req.params.key, false);
  const value = await res.locals.ab.getFeatureValue(req.params.key);
  res.json({ key: req.params.key, enabled, value });
});

// Graceful shutdown
const server = app.listen(3000, () => {
  console.log('Server running on :3000');
});

process.on('SIGTERM', async () => {
  await AbrovaAbTesting.destroy();
  server.close();
});
```

### Best Practices

<BestPracticeList columns={2} items={[
  ['One handle per request', 'Call forUser() with the request\'s user. Never share setUserId() across concurrent requests.'],
  ['Secret stays on the server', 'Pass serverSecret from your environment. Apps get short-lived user tokens from createUserToken(), never the secret.'],
  ['One token for every Abrova SDK', 'The token you mint works for A/B Testing, Chat and Sync. Your apps fetch it once and share it.'],
  ['Flush on shutdown', 'Call destroy() on SIGTERM so queued events are sent before the process exits.'],
]} />

### TypeScript Types

```typescript
import type {
  AbrovaAbTestingConfig,
  AbrovaAbTestingUser,
  UserToken,
  Experiment,
  Variant,
  Assignment,
  FeatureFlag,
  FlagVariant,
  AbrovaAbTestingEventType,
  AbrovaAbTestingEvent,
} from '@abrova/ab-testing-node';
import { EventType } from '@abrova/ab-testing-node';

interface AbrovaAbTestingConfig {
  apiKey: string;
  serverSecret?: string;          // your project's server secret (server only); required for variants, events, flags and createUserToken
  debug?: boolean;
  flushInterval?: number;         // ms between sends; leave it out to follow the console's Send interval
  maxQueueSize?: number;          // events kept while waiting to send (default and maximum: 1000)
  maxCachedAssignments?: number;  // (user, experiment) assignments kept in memory (default: 10000)
}

interface UserToken {
  token: string;
  userId: string;
  expiresIn: number;              // seconds until the token expires
}

// EventType enum
enum EventType {
  VIEW = 'view',
  CLICK = 'click',
  CONVERSION = 'conversion',
  CUSTOM = 'custom',
  SCROLL = 'scroll',
  FORM_SUBMIT = 'form_submit',
  SEARCH = 'search',
  SHARE = 'share',
  ADD_TO_CART = 'add_to_cart',
  REMOVE_FROM_CART = 'remove_from_cart',
  BEGIN_CHECKOUT = 'begin_checkout',
  PURCHASE = 'purchase',
  VIDEO_START = 'video_start',
  VIDEO_COMPLETE = 'video_complete',
  SIGN_UP = 'sign_up',
  LOGIN = 'login',
  LOGOUT = 'logout',
}
```

- Feature flags SDK: https://abrova.ir/en/docs/ab-testing/feature-flags-sdk

<Callout kind="note" title="Looking for standalone Feature Flags?">
This page documents `AbrovaFeatureFlags`, the **standalone Flutter feature flags client** that ships in the A/B Testing package `abrova_ab_testing`. If you want full feature flag platform support with iOS, Android, React Native, Node.js, and Next.js SDKs, see the dedicated [Abrova Flags](/docs/flags/flutter) service instead. This page is for apps that use (or plan to use) the A/B Testing SDK and just need lightweight feature flags in Flutter. The other A/B Testing SDKs expose flags as methods on the main client (`isFeatureEnabled`, `getFeatureValue`, `getFeatureFlags`); see their SDK pages.
</Callout>

<Callout kind="tip" title="Lightweight & Independent">
`AbrovaFeatureFlags` is a standalone class for feature flag management. No experiment setup, no event tracking: just feature flags. Use it if you only need feature flags without experiments. It is initialized on its own and does not need `AbrovaAbTesting.init()`.
</Callout>

<Callout kind="warn" title="User tokens">
Evaluating a flag for a user (`isEnabled`, `getValue`) needs a signed **user token**, minted by your backend. Add a `tokenProvider` to your config (step 3). Listing flags (`getAll`, `refresh`) works with the API key alone, so the app can load them before sign-in.

New in 0.2.2: you can initialize before sign-in. The SDK waits for the user token instead of failing (see step 3).
</Callout>

<Callout kind="note" title="Requirements">
- Dart 3.0.0 or higher (Flutter 3.10+). 
- Pure Dart: works on Android, iOS, Web, macOS, Windows and Linux. 
- A backend endpoint that mints Abrova user tokens (see step 3).
</Callout>

<H2 id="installation" step={1}>Installation</H2>

The add-on ships in `abrova_ab_testing`. Install it from Abrova Center: add the package to your `pubspec.yaml` with the Abrova Center address:

```yaml
dependencies:
  abrova_ab_testing:
    hosted: https://center.abrova.ir/api/packages/abrova/pub
    version: ^0.2.3
```

Install:

```bash
flutter pub get
```

#### Platform-specific setup

**Android:** Add Internet permission in `android/app/src/main/AndroidManifest.xml`:

```xml
<uses-permission android:name="android.permission.INTERNET" />
```

<H2 id="quick-start" step={2}>Quick Start</H2>

Get up and running in a few lines of code:

```dart
import 'package:abrova_ab_testing/abrova_ab_testing.dart';

// Initialize
final flags = await AbrovaFeatureFlags.init(
  AbrovaFeatureFlagsConfig(
    apiKey: 'YOUR_API_KEY',
    tokenProvider: fetchAbrovaToken, // returns a user token from your backend (step 3)
  ),
);

// Set the signed-in user
await flags.setUserId('user-123');

// Check a flag
if (await flags.isEnabled('dark-mode')) {
  // Feature is enabled
}
```

<H2 id="user-tokens" step={3}>User tokens</H2>

Anyone can read the API key out of your app, so on its own it can't prove which user a request is for. Your backend can: it holds your project's **server secret** and mints a short-lived token for the signed-in user. The SDK sends that token, and the service takes the user from it.

#### Mint the token on your server

```bash
curl -X POST https://auth.abrova.ir/users/token \
  -H "x-api-key: $ABROVA_API_KEY" \
  -H "x-server-secret: $ABROVA_SERVER_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"userId": "user-123", "expiresIn": 3600}'

# → { "token": "eyJhbGciOi…", "userId": "user-123", "expiresIn": 3600, "expiresAt": "…" }
```

`expiresIn` is in seconds: 3600 (1 hour) by default, 86400 (24 hours) maximum. On a Node.js backend, `createUserToken(userId)` from the [Node.js SDK](/docs/ab-testing/nodejs) makes this call for you. Never put the server secret in the app.

#### One token for A/B Testing, Chat and Sync

The token is the same Abrova user token used by Abrova Chat and Abrova Sync. If your app uses them too, mint **one** token and give it to every SDK's `tokenProvider` instead of fetching one per product.

#### Give it to the SDK

Pass a `tokenProvider` that calls your backend. The SDK caches the token, asks again shortly before it expires, and asks once more if the service reports it expired. Return `null` while no one is signed in.

```dart
import 'dart:convert';
import 'package:http/http.dart' as http;

Future<String?> fetchAbrovaToken() async {
  if (sessionToken == null) return null; // no one signed in: the SDK waits
  // Call YOUR backend, authenticated as the signed-in user
  final res = await http.post(
    Uri.parse('https://your-api.example.com/abrova-token'),
    headers: {'Authorization': 'Bearer $sessionToken'}, // your app's own session
  );
  if (res.statusCode != 200) throw Exception('Could not get an Abrova token');
  return jsonDecode(res.body)['token'] as String;
}
```

If you already hold a token, you can pass it as `userToken` instead, and hand over a newer one with `setUserToken(token)`. `tokenProvider` is preferred: a static token expires.

#### Before your user signs in

You can call `init` before anyone is signed in. While there is no token (`tokenProvider` returned `null` or failed, or none was set) the SDK is **awaiting a user token**: flags are answered from the cached flag list, or your default is returned, and nothing is sent. No error is reported.

```dart
final flags = AbrovaFeatureFlags.instance;

flags.isAwaitingUserToken;            // true while there is no user token
flags.onAwaitingUserToken(() { });    // called each time the SDK starts waiting

// After sign-in
await flags.refreshUserToken();       // with a tokenProvider: asks it again now
await flags.setUserToken(token);      // without one: hand the token over

// After sign-out
await flags.clearUserId();            // or setUserToken(null)
```

The `init` callback reports the same moment as an `awaitingUserToken` event. To add or remove the provider after `init`, call `setTokenProvider(provider)`.

<Callout kind="note" title="Keep it on the device">
A token is valid until it expires, so store it with the user's session (Keychain, Keystore or secure storage) and return it from your `tokenProvider` across app launches. Your app then only calls your backend when the token is close to expiry, not on every start.
</Callout>

<H2 id="initialization" step={4}>Initialization</H2>

Initialize the SDK in your app's main function. The SDK uses a singleton pattern — initialize once, access anywhere.

```dart
import 'package:flutter/material.dart';
import 'package:abrova_ab_testing/abrova_ab_testing.dart';

void main() async {
  WidgetsFlutterBinding.ensureInitialized();

  // Initialize with full config
  await AbrovaFeatureFlags.init(
    AbrovaFeatureFlagsConfig(
      apiKey: 'YOUR_API_KEY',
      tokenProvider: fetchAbrovaToken, // User token from your backend
      debug: true,              // Enable debug logging
      enableOfflineCache: true, // Cache flags for offline use (default: true)
    ),
    callback: (event, data) {
      print('FeatureFlags event: $event, data: $data');
    },
  );

  runApp(const MyApp());
}

// Access the instance anywhere after init
final flags = AbrovaFeatureFlags.instance;
```

#### Configuration Options

<ConfigTable rows={[
  ['apiKey', 'String', 'required', 'Your project API key'],
  ['baseUrl', 'String', 'https://abtest.abrova.ir', 'API base URL. Must be https; plain http is accepted only for localhost, 127.0.0.1 and 10.0.2.2'],
  ['tokenProvider', 'FutureOr<String?> Function()', 'null', 'Returns a user token minted by your backend, or null while no one is signed in. Needed to evaluate flags for a user'],
  ['userToken', 'String', 'null', 'A token you already hold (tokenProvider is preferred: a static token expires)'],
  ['debug', 'bool', 'false', 'Enable debug logging'],
  ['enableOfflineCache', 'bool', 'true', 'Cache flags locally for offline use'],
]} />

<H2 id="user-identification" step={5}>User Identification</H2>

Set a user ID for rollout percentage targeting and user-based flag evaluation. Set user attributes for advanced targeting rules. The service takes the user from the token, so the user ID must match the user your `tokenProvider` returns a token for.

```dart
final flags = AbrovaFeatureFlags.instance;

// Set user ID (persisted across sessions)
await flags.setUserId('user-123');

// Forget the user at sign-out
await flags.clearUserId();

// Get current user ID
final userId = flags.getUserId();

// Set user attributes for targeting rules
flags.setUserAttributes({
  'plan': 'premium',
  'country': 'US',
  'age': 25,
  'is_beta_user': true,
});
```

Calling `setUserId` with a different user, handing over a token for a different user, or calling `clearUserId()` clears the previous user's attributes and token. The next evaluation asks your `tokenProvider` for the new user's token, so set the new user's attributes after the switch.

<H2 id="checking-feature-flags" step={6}>Checking Feature Flags</H2>

#### Boolean Flags (isEnabled)

Check if a feature flag is enabled. Returns the server-evaluated result for the user (sent with the user token). If the service can't be asked (offline, or no user token yet), the SDK uses the service's last answer for that user, then the cached flag list, and returns your default when the flag isn't cached.

```dart
final flags = AbrovaFeatureFlags.instance;

// Simple check
if (await flags.isEnabled('dark-mode')) {
  enableDarkMode();
}

// With default value (returned if flag not found)
final showBanner = await flags.isEnabled('promo-banner', defaultValue: false);
```

#### Value Flags (getValue)

Get the value of a feature flag. Useful for multivariate flags that return strings, numbers, or JSON.

```dart
final flags = AbrovaFeatureFlags.instance;

// Get a string value
final buttonColor = await flags.getValue('button-color', defaultValue: 'blue');

// Get a numeric value
final maxRetries = await flags.getValue('max-retries', defaultValue: 3);

// Get a JSON config value
final config = await flags.getValue('onboarding-config', defaultValue: {});
```

#### Get All Flags

```dart
// Fetch all flags (server call with cache fallback; API key only)
final allFlags = await AbrovaFeatureFlags.instance.getAll();

for (final flag in allFlags) {
  print('${flag.key}: enabled=${flag.enabled}, value=${flag.defaultValue}');
  if (flag.variants != null) {
    for (final variant in flag.variants!) {
      print('  variant ${variant.key}: ${variant.value} (weight: ${variant.weight})');
    }
  }
}
```

<H2 id="targeting-rules" step={7}>Targeting Rules</H2>

Feature flags support advanced targeting rules based on user attributes. Rules are configured in the dashboard and evaluated by the service. When the service can't be asked, the SDK falls back to the cached flag list.

#### Supported Operators

<ConfigTable rows={[
  ['equals', '-', '-', 'Exact match: {"country": {"equals": "US"}}'],
  ['notEquals', '-', '-', 'Not equal: {"plan": {"notEquals": "free"}}'],
  ['in', '-', '-', 'Value in list: {"country": {"in": ["US", "CA"]}}'],
  ['notIn', '-', '-', 'Value not in list: {"plan": {"notIn": ["free"]}}'],
  ['greaterThan', '-', '-', 'Numeric comparison: {"age": {"greaterThan": 18}}'],
  ['lessThan', '-', '-', 'Numeric comparison: {"age": {"lessThan": 65}}'],
  ['greaterThanOrEqual', '-', '-', 'Numeric comparison: {"age": {"greaterThanOrEqual": 18}}'],
  ['lessThanOrEqual', '-', '-', 'Numeric comparison: {"age": {"lessThanOrEqual": 65}}'],
  ['contains', '-', '-', 'String contains: {"email": {"contains": "@company.com"}}'],
  ['regex', '-', '-', 'Regex match: {"email": {"regex": ".*@company\\.com$"}}'],
  ['exists', '-', '-', 'Attribute exists: {"premium": {"exists": true}}'],
]} />

#### Setting Attributes for Targeting

```dart
// Set attributes that match your targeting rules
AbrovaFeatureFlags.instance.setUserAttributes({
  'country': 'US',
  'plan': 'premium',
  'age': 25,
  'email': 'user@company.com',
});

// Flag with targeting rule {"country": {"in": ["US", "CA"]}}
// will be enabled for this user
final enabled = await AbrovaFeatureFlags.instance.isEnabled('us-feature');
```

<H2 id="rollout-percentage" step={8}>Rollout Percentage</H2>

Feature flags support gradual rollouts using percentage-based targeting. Rollout is decided per user, so the same user always gets the same result.

```dart
// User ID is required for rollout percentage to work
await AbrovaFeatureFlags.instance.setUserId('user-123');

// A flag with 25% rollout will be enabled for ~25% of users
// The same user always gets the same result
final enabled = await AbrovaFeatureFlags.instance.isEnabled('new-feature');
```

<H2 id="multivariate-flags" step={9}>Multivariate Flags</H2>

Feature flags can have multiple variants with weighted distribution. Use `getValue()` to get the assigned variant value.

```dart
// A flag with variants: blue (50%), green (30%), red (20%)
final buttonColor = await AbrovaFeatureFlags.instance.getValue(
  'button-color',
  defaultValue: 'blue',
);

// Use the value
switch (buttonColor) {
  case 'green':
    return Colors.green;
  case 'red':
    return Colors.red;
  default:
    return Colors.blue;
}
```

### Offline Support

<Callout kind="note" title="Built-in Offline Support">
The service decides every flag. When it can't be asked (offline, or no user token yet), the SDK uses the service's last answer for that user, then the flag list it cached after the last fetch. The cached answer is an approximation; the service's own answer is used whenever there is one.
</Callout>

#### How It Works

<BestPracticeList columns={2} items={[
  ['Server-First Evaluation', 'When online, flags are evaluated server-side for the signed-in user, using their user token.'],
  ['Cached Fallback', 'When the service can\'t be asked, the SDK answers from the cached flag list, and returns your default for a flag that isn\'t cached.'],
  ['Persistent Cache', 'Flags are cached using SharedPreferences, surviving app restarts.'],
  ['Consistent Results', 'The same user always gets the same flag value from the service.'],
]} />

```dart
final flags = AbrovaFeatureFlags.instance;

// Check connectivity status
print('Online: ${flags.isOnline}');

// Access cached flags directly (no server call)
final cached = flags.cachedFlags;
print('Cached flags: ${cached.length}');

// Force refresh from server
await flags.refresh();
```

### Event Callbacks

Listen for SDK events using the callback parameter during initialization.

```dart
await AbrovaFeatureFlags.init(
  AbrovaFeatureFlagsConfig(
    apiKey: 'YOUR_API_KEY',
    tokenProvider: fetchAbrovaToken,
  ),
  callback: (event, data) {
    switch (event) {
      case 'initialized':
        print('SDK ready, offline: ${data?['offline']}');
        break;
      case 'featureFlagsRefreshed':
        print('Fetched ${data?['count']} flags');
        break;
      case 'awaitingUserToken':
        print('Waiting for a user token');
        break;
      case 'error':
        print('Error: ${data?['message']}');
        break;
    }
  },
);
```

### Advanced Usage

#### Refresh Flags

```dart
// Manually refresh flags from server
await AbrovaFeatureFlags.instance.refresh();
```

#### Reset State

```dart
// Clear cached flags, user and token, and reset the SDK.
// Call AbrovaFeatureFlags.init() again before using it afterwards.
// To sign a user out, call clearUserId() instead.
await AbrovaFeatureFlags.instance.reset();
```

#### Dispose

```dart
// Clean up resources when done (currently a no-op: nothing to release)
AbrovaFeatureFlags.instance.dispose();
```

### Complete Example

A complete example showing the Feature Flags SDK in a Flutter app:

```dart
import 'package:flutter/material.dart';
import 'package:abrova_ab_testing/abrova_ab_testing.dart';

void main() async {
  WidgetsFlutterBinding.ensureInitialized();

  await AbrovaFeatureFlags.init(
    AbrovaFeatureFlagsConfig(
      apiKey: 'YOUR_API_KEY',
      tokenProvider: fetchAbrovaToken, // see step 3
      debug: true,
    ),
  );

  runApp(const MyApp());
}

class HomePage extends StatefulWidget {
  const HomePage({super.key});

  @override
  State<HomePage> createState() => _HomePageState();
}

class _HomePageState extends State<HomePage> {
  bool _darkMode = false;
  String _bannerText = 'Welcome!';
  bool _loading = true;

  @override
  void initState() {
    super.initState();
    _loadFlags();
  }

  Future<void> _loadFlags() async {
    final flags = AbrovaFeatureFlags.instance;

    // Set user for targeting
    await flags.setUserId('user-123');
    flags.setUserAttributes({
      'plan': 'premium',
      'country': 'US',
    });

    // Check flags
    final darkMode = await flags.isEnabled('dark-mode');
    final bannerText = await flags.getValue(
      'banner-text',
      defaultValue: 'Welcome!',
    ) as String;

    setState(() {
      _darkMode = darkMode;
      _bannerText = bannerText;
      _loading = false;
    });
  }

  @override
  Widget build(BuildContext context) {
    if (_loading) {
      return const Scaffold(
        body: Center(child: CircularProgressIndicator()),
      );
    }

    return Theme(
      data: _darkMode ? ThemeData.dark() : ThemeData.light(),
      child: Scaffold(
        appBar: AppBar(title: const Text('My App')),
        body: Center(
          child: Column(
            mainAxisAlignment: MainAxisAlignment.center,
            children: [
              Text(
                _bannerText,
                style: const TextStyle(fontSize: 24, fontWeight: FontWeight.bold),
              ),
              const SizedBox(height: 16),
              Text('Dark mode: ${_darkMode ? "ON" : "OFF"}'),
            ],
          ),
        ),
      ),
    );
  }
}
```

### AbrovaFeatureFlags vs AbrovaAbTesting

Both classes ship in the `abrova_ab_testing` package. Choose the one that fits your needs:

<ConfigTable rows={[
  ['Feature flags', '-', '-', 'Both have it'],
  ['A/B testing', '-', '-', 'Only AbrovaAbTesting'],
  ['Event tracking', '-', '-', 'Only AbrovaAbTesting'],
  ['Offline caching', '-', '-', 'Both have it'],
  ['Targeting rules', '-', '-', 'Both have it'],
  ['Rollout %', '-', '-', 'Both have it'],
  ['User token', '-', '-', 'Both need one to act for a user (tokenProvider)'],
  ['Lightweight', '-', '-', 'AbrovaFeatureFlags is minimal; AbrovaAbTesting is the full SDK'],
]} />

Use `AbrovaFeatureFlags` if you only need feature flags. Use `AbrovaAbTesting` if you also need experiments and event tracking. Each is initialized on its own, and both take the same user token.

For a multi-platform feature flag service (iOS, Android, React Native, Node.js, Next.js), use the dedicated [Abrova Flags](/docs/flags/flutter) service instead — it has its own SDKs across all platforms.


## Abrova Storage (coming soon)

- Overview: https://abrova.ir/en/docs/storage/overview

AbrovaStorage is file storage for your apps: buckets, uploads and downloads, public and signed links, access rules, and on-the-fly image transformations.

#### Capabilities

- **Uploads** — Multipart uploads straight into a bucket.
- **Public and signed links** — A public link for files in a public bucket, no key needed; time-limited signed links, made by your server, for private files.
- **Image Transforms** — Resize, format conversion and quality settings, also for iPhone and Android HEIC photos; for public files straight from a link such as `…?w=600&f=webp`.
- **Access Rules** — Per-bucket rules for read, write, delete and list, checked against a verified user.

Using an AI assistant? See [AI assistants](/docs/storage/ai-assistants) for how to give it these docs.

### Available SDKs

AbrovaStorage ships SDKs for every major platform:

- **Node.js** — `@abrova/storage-node` — server-side: buckets, access rules, signed links, user tokens.
- **Flutter** — `abrova_storage` — Dart SDK for mobile and web.
- **Web** — `@abrova/storage-web` — browser SDK for React/Vue/Svelte/vanilla.
- **Android** — `ir.abrova:abrova-storage` — Kotlin SDK with coroutines.
- **iOS** — `AbrovaStorage` — Swift SDK with async/await + completion handler APIs.
- **React Native** — `@abrova/storage-react-native` — same API as Web SDK.
- **Next.js** — combines `@abrova/storage-node` (server) + `@abrova/storage-web` (client).
- **REST API** — direct HTTP, base URL `https://storage.abrova.ir`.

Every SDK installs from Abrova Center in two steps: add the Abrova Center registry, then install the package. Each SDK page shows both lines.

<Callout kind="wallet" title="What it will cost">
Free every month: 1 GB stored, 5 GB bandwidth and 500 image transforms. Usage above that will cost from your prepaid wallet; the price is set at launch. See [Pricing](/pricing).
</Callout>

### Authentication

AbrovaStorage uses three credentials. Each one proves something different.

<ConfigTable headers={['Credential', 'Where it lives', 'What it proves']} rows={[
  ['API key (ab_live_…)', 'Inside your app. Public.', 'Which project the request belongs to.'],
  ['Server secret (ab_srv_…)', 'Your server only. Never in an app.', 'That a request comes from your backend. Requests with it skip access rules.'],
  ['User token', 'Your app, one per signed-in user.', 'Which user is acting. Access rules see this user.'],
]} />

What each credential can do is fixed; no setting changes it:

<ConfigTable headers={['Action', 'From an app (API key + user token)', 'From your server (server secret)']} rows={[
  ['Upload, read, list, delete files (incl. deleteMany), image transforms', 'Yes, following your access rules. A signed user token is required (401 token_required without one).', 'Yes, access rules skipped. No user token needed.'],
  ['List and read buckets, get a file\'s public link', 'Yes, API key alone. No user token needed.', 'Yes'],
  ['Create, update, delete buckets', 'No (403 server_secret_required)', 'Yes'],
  ['Create, update, delete access rules, apply a template', 'No (403 server_secret_required)', 'Yes'],
  ['Signed download and upload links', 'No (403 server_secret_required)', 'Yes'],
]} />

Public links of files in a public bucket (`https://storage.abrova.ir/public/…`) need no key and no token at all.

<Callout kind="note" title="Server secret is server-only">
Never put your `serverSecret` in client-side code, mobile apps, or frontend applications. Use it only on your backend server, from an environment variable.
</Callout>

### Sign users in (one token for every Abrova product)

Every file request from an app carries a signed **Abrova user token**. This is always required: there is no setting to turn it on or off. Your app cannot say who the user is by itself: the API key it ships with is public, so the server has no reason to believe a user id that comes from a client. Instead, your server mints a short-lived token with the server secret (or Abrova Auth signs the user in), and the SDK sends it on every request. Access rules such as `users/{userId}/**` and `authenticated: true` see the user in that token.

<Callout kind="note" title="Requires the Storage SDK 0.2.1 or newer">
Use Storage SDK 0.2.1 or newer on every platform. An app that doesn't send a user token can't read or write files.
</Callout>

#### 1. Your server mints the token

With the Node.js SDK it is one call:

```typescript
import { AbrovaStorage } from '@abrova/storage-node';

const storage = new AbrovaStorage({
  apiKey: process.env.ABROVA_API_KEY!,
  serverSecret: process.env.ABROVA_SERVER_SECRET!, // server only
});

// Your own endpoint, behind your own session check
app.post('/abrova-token', async (req, res) => {
  const { token, expiresAt } = await storage.createUserToken(req.session.userId);
  res.json({ token, expiresAt });
});
```

Or call the Abrova auth endpoint from any backend:

```bash
curl -X POST https://auth.abrova.ir/users/token \
  -H "x-api-key: $ABROVA_API_KEY" \
  -H "x-server-secret: $ABROVA_SERVER_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"userId": "u_4821", "expiresIn": 3600}'

# → { "token": "eyJhbGciOi…", "userId": "u_4821", "expiresIn": 3600, "expiresAt": "2026-10-21T10:00:00.000Z" }
```

`expiresIn` is in seconds: 3600 (1 hour) by default, 86400 (24 hours) maximum. It is the same token Abrova Sync, Chat, Push and A/B Testing accept, so one endpoint serves every SDK. Using **Abrova Auth**? Its sign-in token is this same token: pass its token provider as is, no endpoint of your own needed.

#### 2. The app gives the SDK a token provider

```typescript
// Web (React Native is the same)
const storage = new AbrovaStorage({
  apiKey: 'ab_live_xxxxxxxxxxxx',
  tokenProvider: async () => {
    const res = await fetch('/abrova-token', { method: 'POST' });
    return res.ok ? (await res.json()).token : null; // null = no one signed in
  },
});
```

The SDK sends the token as the `x-user-token` header, asks the provider before the first request, renews it shortly before it expires, and if the server answers `token_expired` or `token_invalid` it asks once more and retries the request once. Call `refreshUserToken()` when the user signs in or out. Each platform page shows its own syntax.

#### Without a user token

Without a token, file calls (upload, list, get, download, delete) are not sent and do not fail: they **wait**. `isAwaitingUserToken` is `true` meanwhile, and `onAwaitingUserToken` tells you when calls start waiting, so you can show your sign-in screen. Once the provider returns a token (call `refreshUserToken()`) or you call `setUserToken(token)`, the waiting calls go on in order. Set `userTokenWaitTimeout` to make a waiting call fail with `token_required` instead. Bucket reads (`listBuckets`, `getBucket`, `getBucketByName`) and public links never wait.

A file call made before sign-in finishes only after sign-in, so don't wait for it in code the user is waiting on (a button handler, a startup check). With Abrova Auth, the sign-in method you use (for example Anonymous) must be on in **Abrova Auth › Sign-in methods**; if it is off, sign-in fails with `METHOD_DISABLED` and file calls wait without an error.

<ConfigTable headers={['401 code', 'Meaning', 'What the SDK does']} rows={[
  ['token_required', 'The request had no user token.', 'Waits for a token (or fails after userTokenWaitTimeout).'],
  ['token_expired', 'The token has expired.', 'Asks the provider again and retries once.'],
  ['token_invalid', 'Bad signature, wrong project, or not an Abrova user token.', 'Asks the provider again and retries once; then throws.'],
]} />

#### Defaults to keep

- Leave `userTokenWaitTimeout` unset: by default file calls wait until a user signs in. Set it only when a screen waits for the answer and can send the user to sign-in.
- Don't add your own timeouts or retries around file calls for a missing user. Show sign-in instead; the waiting calls go on by themselves.
- While developing, log from `onAwaitingUserToken`, so a call that waits for a user is easy to spot.

### Errors

Every refused request answers JSON with a `statusCode`, a `message` you can show, and a `code` you can switch on, for example `{ "statusCode": 400, "code": "type_not_allowed", "message": "…" }`. The SDKs expose `code` as constants (`StorageErrorCode`). Answers contain only the documented fields of a file, bucket or rule — see [REST API](/docs/storage/rest) for the full list of codes.

### Bucket Visibility

When creating a bucket, you can choose between two visibility modes that control how files can be accessed.

- `private` (default) — Files are read through the API (with your API key, following your access rules) or through a signed link your server makes. Best for user documents, invoices, receipts, contracts, personal audio recordings, and sensitive data.
- `public` — Each file also has a public link that needs no key. Anyone with the link can view or download the file. Best for user avatars, profile pictures, product images, public assets, and shared content.

#### Showing a file in an image or a page

For a file in a **public** bucket, use its public link. It needs no key, token or header, so it goes straight into `<img src>`, `srcset`, `Image.network(url)` or an e-mail. Add image options to get a resized or converted image:

```dart
// Public bucket: the public link, optionally with image options
final link = await storage.getPublicUrl(fileId);
// https://storage.abrova.ir/public/<bucketId>/<path>
final thumb = await storage.getPublicUrl(fileId,
    transforms: const ImageTransforms(width: 600, format: 'webp'));
// https://storage.abrova.ir/public/<bucketId>/<path>?w=600&f=webp
Image.network(thumb);

// Private bucket: download the bytes in the app...
final bytes = await storage.download(fileId);
Image.memory(bytes);

// ...or have your server make a time-limited signed link
// (Node.js SDK, server secret): await storage.getSignedUrl(fileId, { expiresIn: 600 })
```

`getPublicUrl()` fails with 403 for a file in a private bucket, and a `/public/…` link of a private file answers 404. `getUrl()`, `getDownloadUrl()` and `getTransformUrl()` return API addresses that need the `x-api-key` and `x-user-token` headers, so don't put them in a plain `<img src>`. See [Image Transforms](/docs/storage/image-transforms).

<Callout kind="note" title="Visibility is mutable">
You can change a bucket's visibility at any time from the dashboard. When a bucket becomes private, its public links stop working, but browsers and other caches that already cached a file may keep showing it for up to a day. Don't rely on it to revoke a file someone already has. Signed links keep working until they expire.
</Callout>

- AI assistants: https://abrova.ir/en/docs/storage/ai-assistants

<Callout kind="soon" title="Coming soon">
Abrova does not have a docs server for AI assistants yet. This page describes how it will work and what you can use today.
</Callout>

When it is ready, you connect your AI assistant (any tool that supports MCP, the open standard AI tools use to connect to outside sources) once. Then, when you ask it to add Abrova Storage to your project, it looks up the current SDK version, install lines and setup steps from these docs instead of answering from memory.

### What works today

- **Copy page for AI.** Every docs page has a **Copy page for AI** link. Paste the page into your assistant's chat before you ask it to write code.
- **Plain-text docs.** Give your assistant the address `https://abrova.ir/docs/llms.txt`. It lists every docs page as plain text that assistants read well.

Tell your assistant to follow the page you gave it, and to use the placeholder keys from the docs.

### What it will do

The docs server will have read-only tools. Your assistant chooses them by itself; you do not call them by hand.

<ConfigTable headers={['Tool', 'What it will do']} rows={[
  ['list_products', 'Lists the Abrova products, with the platforms that have an SDK and the docs link.'],
  ['search_docs', 'Searches the docs for a few words or a short question and returns the best pages.'],
  ['read_doc', 'Returns one docs page as text, with its link and last-updated date.'],
  ['get_sdk_info', 'Returns the SDK package for a product and platform: name, current version and install lines.'],
  ['get_setup_guide', 'Returns the ordered setup steps for a product and platform: install, keys, initialization and how to test.'],
]} />

Examples of what you will be able to ask:

- **"Upload a profile photo from my Flutter app and show a 200-pixel thumbnail."** It would answer from [Flutter SDK](/docs/storage/flutter) and [Image transforms](/docs/storage/image-transforms).
- **"Let each user read and write only their own folder."** It would answer from [Bucket policies](/docs/storage/bucket-policies) and [Security best practices](/docs/storage/security).
- **"Give my web app a link to a private file that expires in an hour."** It would answer from [Overview](/docs/storage/overview) and [Web SDK](/docs/storage/web).

### Privacy

- **What it reads:** the public Abrova docs, the current SDK versions, and the words your assistant sends (the search words, the page it wants, the product and platform names).
- **What it never sees:** your code, your files, your Abrova project, your keys or your users. The tools have no input for them, and they cannot change any setting.

<Callout kind="warn" title="Keep your keys out of the chat">
Never paste a key into a chat with an AI assistant. Your assistant writes the placeholder from the docs (`ab_live_your_api_key`); you put the real value in your project's configuration yourself. The server secret (`ab_srv_...`) belongs only on your server, in an environment variable.
</Callout>

More about AI assistants and Abrova: [AI assistants](/ai-assistants). Questions? [Contact us](/contact).

- Web: https://abrova.ir/en/docs/storage/web

Client-side SDK for browser applications. Works with any framework (React, Vue, Svelte, vanilla JS). TypeScript support included. This page describes `@abrova/storage-web` **0.2.1**.

<H2 id="installation" step={1}>Installation</H2>

```bash
# 1. .npmrc in your project root: @abrova packages come from Abrova Center
@abrova:registry=https://center.abrova.ir/api/packages/abrova/npm/
```

```bash
# 2. Install
npm install @abrova/storage-web
# or
yarn add @abrova/storage-web
```

<H2 id="initialization" step={2}>Initialization</H2>

```typescript
import { AbrovaStorage } from '@abrova/storage-web';

const storage = new AbrovaStorage({
  apiKey: 'ab_live_xxxxxxxxxxxx',
  tokenProvider: () => auth.getToken(), // the signed-in user's Abrova user token, see step 3
});
```

<Callout kind="note" title="Client-side only">
The Web SDK is for client-side use only. Never put a server secret in browser code. Managing buckets, access rules and signed links is for your server (Node.js SDK); from an app it is refused with `server_secret_required` (403).
</Callout>

<H2 id="sign-users-in-one-token-for-every-abrova-product" step={3}>Sign users in (one token for every Abrova product)</H2>

Every file request from an app needs a signed **Abrova user token**, so your access rules (`{userId}`, `authenticated`) see a user nobody can fake. The SDK sends it as `x-user-token`. It is the same token Abrova Sync, Chat, Push and A/B Testing accept.

**With Abrova Auth** (`@abrova/auth-web`), its sign-in token is the Abrova user token. No server needed:

```typescript
import { createAbrovaAuth } from '@abrova/auth-web';
import { AbrovaStorage } from '@abrova/storage-web';

const auth = createAbrovaAuth({ apiKey: 'ab_live_xxxxxxxxxxxx' });

const storage = new AbrovaStorage({
  apiKey: 'ab_live_xxxxxxxxxxxx',
  tokenProvider: () => auth.getToken(), // null while signed out: file calls wait
});

// After a sign-in, sign-out or switch of user, ask the provider again
auth.onAuthStateChanged(() => {
  storage.refreshUserToken();
});
```

**With your own users**, your server mints the token with the server secret (`createUserToken(userId)` in the [Node.js SDK](/docs/storage/nodejs), or `POST https://auth.abrova.ir/users/token`), and the provider fetches it:

```typescript
const storage = new AbrovaStorage({
  apiKey: 'ab_live_xxxxxxxxxxxx',
  tokenProvider: async () => {
    const res = await fetch('/abrova-token', { method: 'POST' });
    return res.ok ? (await res.json()).token : null; // null = no one signed in
  },
});
```

Call `await storage.refreshUserToken()` when the user signs in or out, or pass a token you already hold with `await storage.setUserToken(token)` (`null` clears it).

The SDK asks the provider before the first file request, keeps the token, replaces it shortly before it expires, and on `token_expired` / `token_invalid` asks once more and retries the request once. Concurrent requests share one provider call.

#### File calls wait for a signed-in user

Without a token, file calls (`upload`, `listFiles`, `getFile`, `getFileByPath`, `download`, `delete`, `deleteByPath`, `deleteMany`) are not sent and do not fail: they **wait** until your app signs a user in. This is by design: show your sign-in screen meanwhile.

```typescript
const stop = storage.onAwaitingUserToken(() => showSignIn()); // returns a function that removes the callback
if (storage.isAwaitingUserToken) showSignIn();
```

After sign-in, `refreshUserToken()` or `setUserToken(token)` lets every waiting call go on, in order. Bucket calls (`listBuckets`, `getBucket`, `getBucketByName`) and `getPublicUrl` never wait.

Signed user tokens are always required for file calls from the browser. There is no setting to turn this off.

**Don't wait on file calls before sign-in.** A file call made while no one is signed in finishes only after sign-in. Don't wait for it in code the user is waiting on (a button handler, a startup check): start it in the background, or after sign-in.

**Leave the timeout unset.** By default a call waits until sign-in, which is right for background work. Set `userTokenWaitTimeout` only when a screen waits for the answer and can send the user to sign-in:

```typescript
const storage = new AbrovaStorage({
  apiKey: 'ab_live_xxxxxxxxxxxx',
  tokenProvider: () => auth.getToken(),
  userTokenWaitTimeout: 30000, // ms; then fails with token_required
});
```

A call that waited that long fails with `token_required` (401). The `timeout` option is a different setting: it limits each network request (default 30 seconds) and never covers the wait for a user.

**With Abrova Auth**, turn on the sign-in method you use (for example Anonymous) in **Abrova Auth › Sign-in methods**. If it is off, sign-in fails with `METHOD_DISABLED`, no one is signed in, and file calls wait without an error. While developing, log from `onAwaitingUserToken` (`console.debug('Storage: waiting for a user')`) so a silent wait is easy to spot.

Upgrading from 0.2.0: `userId` / `setUserId()` are removed. Use `tokenProvider`.

### Upload

```typescript
// Upload from a File input, with progress
const input = document.querySelector<HTMLInputElement>('#file-input')!;
const selected = input.files![0];
const bar = document.querySelector('progress')!;

const file = await storage.upload('my-bucket', `uploads/${selected.name}`, selected, {
  metadata: { source: 'web-app' },
  onProgress: ({ bytesSent, totalBytes }) => {
    bar.max = totalBytes;
    bar.value = bytesSent;
  },
});
console.log('Uploaded:', file.id);

// Upload from string or Uint8Array
await storage.upload('my-bucket', 'notes/readme.txt', 'Hello World!');
await storage.upload('my-bucket', 'images/photo.png', bytes, { contentType: 'image/png' });
```

`onProgress` is called at most every 50 ms or every 1%, and always once at the end with `bytesSent === totalBytes`. `totalBytes` is the whole request, so it is a little larger than the file.

Without `contentType`, the SDK picks the type from the path's extension (`.md` → `text/markdown`, `.heic` → `image/heic`, …); `contentTypeForPath(path)` returns the type it would send. Paths are encoded for you (spaces, `#`, `?` and non-Latin characters are fine). A new path can't contain `?`, `#`, `%` or a `.` / `..` part: it is refused with `invalid_path` before anything is sent.

### List, Download &amp; Delete

All of these follow the bucket's access rules.

```typescript
// List files with pagination ({ files, nextCursor }; nextCursor is null on the last page)
const result = await storage.listFiles('my-bucket', { prefix: 'images/', limit: 50 });
if (result.nextCursor) {
  const next = await storage.listFiles('my-bucket', { cursor: result.nextCursor });
}

// Download file as ArrayBuffer
const data = await storage.download(fileId);

// Delete
await storage.delete(fileId);
await storage.deleteByPath('my-bucket', 'uploads/old-file.txt');
const { deleted } = await storage.deleteMany(['file1', 'file2', 'file3']);
```

A `StorageFile` has `id`, `bucketId`, `path`, `fileName`, `mimeType`, `size`, `checksum`, `metadata`, `uploadedBy`, `uploadedAt`, `createdAt` and `updatedAt` (dates are ISO 8601 strings). A `Bucket` has `id`, `name`, `description`, `visibility`, `allowedMimeTypes`, `maxFileSize`, `blockExecutables`, `createdAt` and `updatedAt`.

### Showing Files &amp; Image Transforms

For a file in a **public** bucket, `getPublicUrl` returns a link that needs no key, token or header, so it goes straight into `<img src>`, `srcset` or CSS. Pass image options to get a resized or converted image:

```typescript
import { publicImageUrl } from '@abrova/storage-web';

// A 600 px wide WebP, straight into <img>
img.src = await storage.getPublicUrl(fileId, { width: 600, format: 'webp' });

// From a public link you saved earlier: same URL, no request
const at = (width: number) => publicImageUrl(savedLink, { width, format: 'webp' });
img.srcset = `${at(600)} 600w, ${at(1200)} 1200w`;
```

- The same options always give the same URL, and each size is cached: repeated views don't count as a new transform.
- Use a few fixed sizes (for example 200, 600 and 1200 wide). One image keeps at most 50 variants; a new one beyond that answers `too_many_variants` (429).
- When the month's 500 free transforms are used up and your wallet cannot pay for more, an image URL with options answers `plan_feature_locked` (403). The plain public link always works.
- Options are checked before the URL is built (`invalid_transform`): `format` `jpeg`/`png`/`webp`/`avif`, `fit` `cover`/`contain`/`fill`/`inside`/`outside`, `width`/`height` up to 4096, `quality` 1-100, `blur` 0-20, `sharpen` 0-10, `rotate` in degrees.

A **private** bucket has no public link (`getPublicUrl` fails with 403). `getUrl()`, `getDownloadUrl()` and `getTransformUrl()` return API addresses that need the `x-api-key` and `x-user-token` headers, so a plain `<img src>` can't load them. Download the bytes instead, or ask your server for a signed link:

```typescript
const buffer = await storage.download(fileId);
img.src = URL.createObjectURL(new Blob([buffer]));
```

See [Image Transforms](/docs/storage/image-transforms) for transform errors.

### Handling errors

A refused request throws an `AbrovaStorageException` with the server's `message`, the HTTP `statusCode` and a `code`. Compare `code` with the constants in `StorageErrorCode`:

```typescript
import { AbrovaStorageException, StorageErrorCode } from '@abrova/storage-web';

try {
  await storage.upload('my-bucket', 'notes/today.md', '# Today');
} catch (e) {
  if (!(e instanceof AbrovaStorageException)) throw e;
  if (e.code === StorageErrorCode.TypeNotAllowed) console.warn(e.message);
}
```

| Status | `code` | When |
| --- | --- | --- |
| 400 | `type_not_allowed`, `file_too_large`, `executable_blocked` | The bucket's settings refuse the upload |
| 400 | `invalid_path`, `invalid_transform` | A path or image option isn't allowed (nothing is sent) |
| 409 | `path_taken` | A file already exists at this path |
| 401 | `token_required` | No signed-in user within `userTokenWaitTimeout` |
| 401 | `token_expired`, `token_invalid` | The user token is expired or not valid |
| 403 | `access_denied` | The bucket's access rules refused it |
| 403 | `server_secret_required` | A server-only action (buckets, rules, signed links) |

The SDK never follows a redirect.

- React Native: https://abrova.ir/en/docs/storage/react-native

Cross-platform mobile SDK for React Native. Same API as the Web SDK, written in plain TypeScript (no native modules). This page describes `@abrova/storage-react-native` **0.2.1**.

<H2 id="installation" step={1}>Installation</H2>

```bash
# 1. .npmrc in your project root: @abrova packages come from Abrova Center
@abrova:registry=https://center.abrova.ir/api/packages/abrova/npm/
```

```bash
# 2. Install
npm install @abrova/storage-react-native
# or
yarn add @abrova/storage-react-native
```

<H2 id="usage" step={2}>Usage</H2>

```typescript
import { AbrovaStorage } from '@abrova/storage-react-native';

const storage = new AbrovaStorage({
  apiKey: 'ab_live_xxxxxxxxxxxx',
  tokenProvider: () => auth.getToken(), // the signed-in user's Abrova user token, see step 3
});

// Upload, with progress (iOS and Android)
const file = await storage.upload('avatars', `users/${userId}/avatar.png`, imageBytes, {
  contentType: 'image/png',
  onProgress: ({ bytesSent, totalBytes }) => setProgress(bytesSent / totalBytes), // 0 to 1
});

// List files ({ files, nextCursor })
const result = await storage.listFiles('avatars', { prefix: `users/${userId}/`, limit: 20 });

// Download
const data = await storage.download(file.id);

// Delete (follows the bucket's delete rules)
await storage.delete(file.id);
```

`upload` takes a `Uint8Array` or a `string`. Without `contentType`, the type comes from the path's extension (`contentTypeForPath(path)` shows it). A new path can't contain `?`, `#`, `%` or a `.` / `..` part (`invalid_path`, nothing is sent).

<H2 id="sign-users-in-one-token-for-every-abrova-product" step={3}>Sign users in (one token for every Abrova product)</H2>

Every file request from an app needs a signed **Abrova user token**, so access rules (`{userId}`, `authenticated`) see a user nobody can fake. It is the same token Abrova Sync, Chat, Push and A/B Testing accept, so one provider can serve every Abrova SDK.

**With Abrova Auth** (`@abrova/auth-react-native`), its sign-in token is the Abrova user token:

```typescript
import * as Keychain from 'react-native-keychain';
import { createAbrovaAuth, keychainStorage } from '@abrova/auth-react-native';
import { AbrovaStorage } from '@abrova/storage-react-native';

const auth = createAbrovaAuth({ apiKey: 'ab_live_xxxxxxxxxxxx', storage: keychainStorage(Keychain) });

const storage = new AbrovaStorage({
  apiKey: 'ab_live_xxxxxxxxxxxx',
  tokenProvider: () => auth.getToken(), // null while signed out: file calls wait
});

auth.onAuthStateChanged(() => {
  storage.refreshUserToken(); // after sign-in, sign-out or a switch of user
});
```

**With your own users**, your server mints the token with the server secret (`createUserToken(userId)` in the [Node.js SDK](/docs/storage/nodejs)) and your `tokenProvider` fetches it, returning `null` when no one is signed in. Call `await storage.refreshUserToken()` when the user signs in or out, or pass a token you hold with `await storage.setUserToken(token)` (`null` clears it).

The SDK sends the token as `x-user-token`, renews it shortly before it expires, and on `token_expired` / `token_invalid` asks once more and retries the request once.

**No token yet: file calls wait.** They are not sent and do not fail until your app signs a user in, so show your sign-in screen meanwhile. `storage.isAwaitingUserToken` is `true` while calls wait, and `storage.onAwaitingUserToken(callback)` tells you when they start waiting (it returns a function that removes the callback). Bucket calls and `getPublicUrl` never wait.

Signed user tokens are always required for file calls from apps. There is no setting to turn this off.

**Don't wait on file calls before sign-in.** A file call made while no one is signed in finishes only after sign-in. Don't wait for it in code the user is waiting on (a button handler, a startup check): start it in the background, or after sign-in.

**Leave the timeout unset.** By default a call waits until sign-in, which is right for background work. Set `userTokenWaitTimeout` only when a screen waits for the answer and can send the user to sign-in:

```typescript
const storage = new AbrovaStorage({
  apiKey: 'ab_live_xxxxxxxxxxxx',
  tokenProvider: () => auth.getToken(),
  userTokenWaitTimeout: 30000, // ms; then fails with token_required
});
```

A call that waited that long fails with `token_required` (401). The `timeout` option is a different setting: it limits each network request (default 30 seconds) and never covers the wait for a user.

**With Abrova Auth**, turn on the sign-in method you use (for example Anonymous) in **Abrova Auth › Sign-in methods**. If it is off, sign-in fails with `METHOD_DISABLED`, no one is signed in, and file calls wait without an error. While developing, log from `onAwaitingUserToken` (`console.log('Storage: waiting for a user')`) so a silent wait is easy to spot.

Upgrading from 0.2.0: `userId` / `setUserId()` are removed. Use `tokenProvider`.

### Showing images

For a file in a **public** bucket, `getPublicUrl` returns a link that needs no key, token or header. Pass image options for a resized or converted image:

```tsx
import { Image } from 'react-native';
import { publicImageUrl } from '@abrova/storage-react-native';

const url = await storage.getPublicUrl(fileId, { width: 600, format: 'webp' });
<Image source={{ uri: url }} style={{ width: 300, height: 200 }} />

// From a public link you saved earlier: same URL, no request
const thumb = publicImageUrl(savedLink, { width: 200, height: 200, fit: 'cover', format: 'webp' });
```

The same options always give the same, cached URL. Use a few fixed sizes: one image keeps at most 50 variants (`too_many_variants`, 429). When the month's 500 free transforms are used up and your wallet cannot pay for more, image URLs answer `plan_feature_locked` (403); the plain public link always works. Invalid options throw `invalid_transform` before any request.

A **private** bucket has no public link (403). `getTransformUrl()`, `getUrl()` and `getDownloadUrl()` return API addresses that need headers: pass them in `<Image source={{ uri, headers: { 'x-api-key': 'ab_live_xxxxxxxxxxxx', 'x-user-token': userToken } }} />`, or ask your server for a signed link (`getSignedUrl(fileId, { expiresIn })` in the Node.js SDK). See [Image Transforms](/docs/storage/image-transforms) for transform errors.

### Handling errors

A refused request throws an `AbrovaStorageException` with `message`, `statusCode` and `code`; compare `code` with `StorageErrorCode`:

```typescript
import { AbrovaStorageException, StorageErrorCode } from '@abrova/storage-react-native';

try {
  await storage.upload('avatars', 'users/u_4821/notes.md', '# Notes');
} catch (e) {
  if (e instanceof AbrovaStorageException && e.code === StorageErrorCode.TypeNotAllowed) {
    showError(e.message);
  } else throw e;
}
```

Common codes: `type_not_allowed`, `file_too_large`, `executable_blocked` (400, the bucket's settings), `invalid_path`, `invalid_transform` (400, nothing sent), `path_taken` (409), `token_required`, `token_expired`, `token_invalid` (401), `access_denied` (403, access rules) and `server_secret_required` (403, a server-only action).

<Callout kind="note" title="Same API as Web">
The React Native SDK has the same API as the [Web SDK](/docs/storage/web): uploads, downloads, lists, deletes, public links, transforms and user tokens work identically, except that `upload` takes a `Uint8Array` or `string` (not a `File`/`Blob`).
</Callout>

- Node.js: https://abrova.ir/en/docs/storage/nodejs

Server-side TypeScript SDK for Node.js. Includes complete type definitions. This page describes `@abrova/storage-node` **0.2.1**.

This is the SDK for **your server**: it always runs with your server secret. Apps use the [Web](/docs/storage/web), [React Native](/docs/storage/react-native) or mobile SDKs with a signed user token.

<H2 id="installation" step={1}>Installation</H2>

```bash
# 1. .npmrc in your project root: @abrova packages come from Abrova Center
@abrova:registry=https://center.abrova.ir/api/packages/abrova/npm/
```

```bash
# 2. Install
npm install @abrova/storage-node
# or
yarn add @abrova/storage-node
# or
pnpm add @abrova/storage-node
```

<H2 id="initialization" step={2}>Initialization</H2>

```typescript
import { AbrovaStorage } from '@abrova/storage-node';

const storage = new AbrovaStorage({
  apiKey: process.env.ABROVA_API_KEY!,             // ab_live_...
  serverSecret: process.env.ABROVA_SERVER_SECRET!, // ab_srv_..., server only, never in an app
});
```

Optional: `timeout` limits each network request, in milliseconds (default 30000):

```typescript
const storage = new AbrovaStorage({
  apiKey: process.env.ABROVA_API_KEY!,
  serverSecret: process.env.ABROVA_SERVER_SECRET!,
  timeout: 60000,
});
```

`serverSecret` is required: without it the constructor throws `INVALID_ARGUMENT`, and it refuses to run in a browser. Calls made with the server secret skip bucket access rules, so check in your own code that the user may do what you do on their behalf.

<Callout kind="tip" title="Tip">
Use environment variables for credentials and never commit them to version control. The SDK keeps the secret in a private field, so it never shows up in `console.log(storage)` or error reports.
</Callout>

Upgrading from 0.2.0: `serverSecret` is now required and the `userId` option is removed.

### Sign users in (one token for every Abrova product)

File requests from your app always need a signed **Abrova user token**, so access rules (`{userId}`, `authenticated`) see a user nobody can fake. Your server mints it and hands it to the app, whose SDK takes it through its `tokenProvider` option.

```typescript
// Express example, behind your own session check
app.post('/abrova-token', async (req, res) => {
  const { token, expiresAt } = await storage.createUserToken(req.session.userId);
  // optional lifetime in seconds: createUserToken(userId, 900)
  res.json({ token, expiresAt });
});
```

`createUserToken(userId, expiresIn?)` returns `{ token, userId, expiresIn, expiresAt }`. `expiresIn` is in seconds: 1 hour by default, 24 hours maximum. It posts to `https://auth.abrova.ir/users/token` (set the `authUrl` option to change it).

The token is the same one Abrova Sync, Chat, Push and A/B Testing accept, so this one endpoint serves every Abrova SDK in your app. Apps that sign users in with **Abrova Auth** need no endpoint: its sign-in token is the same Abrova user token. Both kinds work; keep one source of user ids per app.

### Buckets

```typescript
const bucket = await storage.createBucket('user-uploads', {
  visibility: 'private',            // or 'public' for header-free public links
  allowedMimeTypes: ['image/*'],
  maxFileSize: 10 * 1024 * 1024,
});

const buckets = await storage.listBuckets();
const byName = await storage.getBucketByName('user-uploads');
```

A `Bucket` has `id`, `name`, `description`, `visibility`, `allowedMimeTypes` (`null` = every type), `maxFileSize`, `blockExecutables`, `createdAt` and `updatedAt`.

### Upload Files

```typescript
import fs from 'fs';

// Upload from Buffer, with progress
const buffer = fs.readFileSync('./image.jpg');
const file = await storage.upload('my-bucket', 'images/photo.jpg', buffer, {
  contentType: 'image/jpeg',
  metadata: { category: 'profile' },
  onProgress: ({ bytesSent, totalBytes }) => {
    console.log(`${Math.round((bytesSent / totalBytes) * 100)}%`);
  },
});

console.log('Uploaded:', file.id);

// Upload from string (content type from the extension: text/markdown)
await storage.upload('documents', 'notes/readme.md', '# Hello');
```

Without `contentType`, the SDK picks the type from the path's extension; `contentTypeForPath(path)` returns the type it would send. Paths are encoded for you. A new path can't contain `?`, `#`, `%` or a `.` / `..` part: it is refused with `invalid_path` before anything is sent.

A `StorageFile` has `id`, `bucketId`, `path`, `fileName`, `mimeType`, `size`, `checksum`, `metadata`, `uploadedBy`, `uploadedAt`, `createdAt` and `updatedAt` (dates are ISO 8601 strings).

### Download Files

```typescript
// Download file content as Buffer
const buffer = await storage.download(fileId);

// Save to file
fs.writeFileSync('./downloaded.jpg', buffer);
```

### List Files

```typescript
const result = await storage.listFiles('my-bucket', {
  prefix: 'images/',  // Filter by path prefix
  limit: 50,          // 1-1000, default 100
});

console.log('Files:', result.files);

// Pagination: nextCursor is null on the last page
if (result.nextCursor) {
  const nextPage = await storage.listFiles('my-bucket', {
    prefix: 'images/',
    cursor: result.nextCursor,
  });
}
```

### Delete Files

```typescript
// Delete single file
await storage.delete(fileId);
await storage.deleteByPath('my-bucket', 'uploads/old-file.txt');

// Delete multiple files (up to 1000 ids)
const result = await storage.deleteMany(['file_id_1', 'file_id_2', 'file_id_3']);
console.log(`Deleted ${result.deleted} files`);
```

### Signed URLs

Signed links need no headers, so they work in `<img src>`, an image view or a download link. They stay valid until they expire.

#### Generate Signed Download URL

```typescript
// Time-limited download URL for a private file
const signedUrl = await storage.getSignedUrl(fileId, {
  expiresIn: 3600, // seconds; default 3600, max 86400 (24 hours)
});

res.json({ downloadUrl: signedUrl });
```

#### Generate Signed Upload URL

```typescript
app.post('/api/get-upload-url', async (req, res) => {
  const { filename, contentType } = req.body;

  // Returns { url, uploadId, path, expiresAt, maxSize }
  const { url, expiresAt } = await storage.createSignedUploadUrl(
    'user-uploads',
    `uploads/${Date.now()}-${filename}`,
    {
      contentType,    // must be allowed by the bucket
      expiresIn: 300, // seconds; default 300, at most 900 (15 minutes)
    }
  );

  res.json({ uploadUrl: url, expiresAt });
});

// The app then uploads directly, with the same Content-Type:
// await fetch(uploadUrl, { method: 'PUT', headers: { 'Content-Type': file.type }, body: file })
```

An upload link is valid for at most 15 minutes. The bucket's type and size limits apply to the uploaded file.

### Image Transformations

For a file in a **public** bucket, `getPublicUrl` returns a link that needs no key or header, ready for the `<img src>` of the pages, e-mails or API answers your server sends. Pass image options for a resized or converted image:

```typescript
import { publicImageUrl } from '@abrova/storage-node';

const url = await storage.getPublicUrl(fileId, { width: 600, format: 'webp' });
html += `<img src="${url}" width="600" alt="">`;

// From a public link you saved earlier: same URL, no request
const thumb = publicImageUrl(savedLink, { width: 200, height: 200, fit: 'cover', format: 'webp' });
```

- The same options always give the same URL, and each size is cached: repeated views don't count as a new transform.
- Use a few fixed sizes (for example 200, 600 and 1200 wide). One image keeps at most 50 variants; a new one beyond that answers `too_many_variants` (429).
- When the month's 500 free transforms are used up and your wallet cannot pay for more, an image URL with options answers `plan_feature_locked` (403). The plain public link always works.
- A file in a private bucket has no public link (403): use `getSignedUrl()` or `download()`.

`getTransformUrl()`, `getUrl()` and `getDownloadUrl()` build API addresses that need the `x-api-key` header, so they can't go straight into a browser's `<img src>`. Fetch them from your server with your headers:

```typescript
const thumbnailUrl = storage.getTransformUrl(fileId, {
  width: 800,        // 1-4096 (larger values are sent as 4096)
  height: 600,
  fit: 'contain',    // cover, contain, fill, inside, outside
  format: 'avif',    // jpeg (default), png, webp, avif
  quality: 85,       // 1-100
  blur: 2,           // 0-20
  sharpen: 1,        // 0-10
  rotate: 90,        // degrees
});
```

Any other value throws `invalid_transform` before the URL is built. See [Image Transforms](/docs/storage/image-transforms) for transform errors.

### Bucket Policies

```typescript
// Create custom policy rules
await storage.createPolicy('my-bucket', [
  {
    name: 'Allow authenticated read',
    action: 'read',
    condition: { authenticated: true },
    effect: 'allow',
    priority: 10,
  },
  {
    name: 'Users can only access their own folder',
    action: '*',
    condition: {
      authenticated: true,
      pathPattern: 'users/{userId}/**',
      matchUserId: true,
    },
    effect: 'allow',
    priority: 20,
  },
  {
    name: 'Limit upload size for images',
    action: 'write',
    condition: {
      authenticated: true,
      allowedMimeTypes: ['image/jpeg', 'image/png', 'image/webp'],
      maxSize: 5 * 1024 * 1024, // 5MB
    },
    effect: 'allow',
  },
]);

// Or apply a pre-built template
await storage.applyPolicyTemplate('my-bucket', 'userFolders');

// Available templates:
// - 'publicRead'   - Public read, authenticated write
// - 'private'      - Authenticated only
// - 'userFolders'  - Users can only access users/{userId}/**
// - 'imagesOnly'   - Image uploads up to 5MB by authenticated users
// - 'closed'       - Server only: apps are denied everything, the server secret still works
```

`{userId}` and `authenticated` come from the app's Abrova user token. A rule that isn't valid is refused with `invalid_rules`.

### Complete Example: Next.js API Routes

```typescript
// lib/storage.ts
import { AbrovaStorage } from '@abrova/storage-node';

export const storage = new AbrovaStorage({
  apiKey: process.env.ABROVA_API_KEY!,
  serverSecret: process.env.ABROVA_SERVER_SECRET!,
});

// app/api/upload/route.ts
import { NextRequest, NextResponse } from 'next/server';
import { storage } from '@/lib/storage';
import { getServerSession } from 'next-auth';

export async function POST(req: NextRequest) {
  const session = await getServerSession();
  if (!session?.user) {
    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
  }

  const { filename, contentType } = await req.json();

  const { url, expiresAt } = await storage.createSignedUploadUrl(
    'user-uploads',
    `users/${session.user.id}/${Date.now()}-${filename}`,
    { contentType, expiresIn: 300 }
  );

  return NextResponse.json({ uploadUrl: url, expiresAt });
}

// app/api/files/[id]/route.ts
export async function DELETE(
  req: NextRequest,
  { params }: { params: { id: string } }
) {
  const session = await getServerSession();
  if (!session?.user) {
    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
  }
  // The server secret skips access rules: check that this user owns the file
  const file = await storage.getFile(params.id);
  if (!file.path.startsWith(`users/${session.user.id}/`)) {
    return NextResponse.json({ error: 'Forbidden' }, { status: 403 });
  }

  await storage.delete(params.id);
  return NextResponse.json({ success: true });
}
```

See [Next.js Integration](/docs/storage/nextjs) for the browser side.

### Error Handling

A refused request throws an `AbrovaStorageError` with the server's `message`, the HTTP `statusCode` and a `code`. Compare `code` with the constants in `StorageErrorCode`:

```typescript
import { AbrovaStorageError, StorageErrorCode } from '@abrova/storage-node';

try {
  await storage.upload('bucket', 'file.jpg', buffer);
} catch (error) {
  if (!(error instanceof AbrovaStorageError)) throw error;

  switch (error.code) {
    case StorageErrorCode.FileTooLarge:
    case StorageErrorCode.TypeNotAllowed:
      console.warn(error.message);
      break;
    case StorageErrorCode.PathTaken:
      // a file already exists at this path
      break;
    default:
      console.error(error.statusCode, error.code, error.message);
  }
}
```

| Status | `code` | When |
| --- | --- | --- |
| 400 | `type_not_allowed`, `file_too_large`, `executable_blocked` | The bucket's settings refuse the upload |
| 400 | `invalid_path`, `invalid_transform` | A path or image option isn't allowed (nothing is sent) |
| 400 | `invalid_rules`, `invalid_ids` | A policy rule or a `deleteMany` list isn't valid |
| 409 | `path_taken` | A file already exists at this path |
| 403 | `server_secret_required` | A server-only action without a valid server secret |

The SDK never follows a redirect.

- Next.js: https://abrova.ir/en/docs/storage/nextjs

Next.js uses two SDKs: `@abrova/storage-node` on the server (route handlers, server components) and `@abrova/storage-web` in the browser (client components). This page describes version **0.2.1** of both.

<H2 id="installation" step={1}>Installation</H2>

```bash
# 1. .npmrc in your project root: @abrova packages come from Abrova Center
@abrova:registry=https://center.abrova.ir/api/packages/abrova/npm/
```

```bash
# 2. Install
npm install @abrova/storage-node @abrova/storage-web
```

<H2 id="server-side-api-routes" step={2}>Server-Side (API Routes)</H2>

The Node.js SDK always needs your server secret and skips access rules, so check who the user is in your route before you act.

```typescript
// lib/storage.ts — shared server instance (never import this from a client component)
import { AbrovaStorage } from '@abrova/storage-node';

export const storage = new AbrovaStorage({
  apiKey: process.env.ABROVA_API_KEY!,
  serverSecret: process.env.ABROVA_SERVER_SECRET!,
});

// app/api/upload/route.ts
import { NextRequest, NextResponse } from 'next/server';
import { storage } from '@/lib/storage';
import { getServerSession } from 'next-auth';

export async function POST(req: NextRequest) {
  const session = await getServerSession();
  if (!session?.user) {
    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
  }

  const formData = await req.formData();
  const file = formData.get('file') as File;
  const buffer = Buffer.from(await file.arrayBuffer());

  const uploaded = await storage.upload(
    'user-uploads',
    `users/${session.user.id}/${file.name}`,
    buffer,
    { contentType: file.type }
  );

  return NextResponse.json({ fileId: uploaded.id });
}

// app/api/files/[id]/route.ts — signed download URL (no headers needed, usable in <img>)
export async function GET(req: NextRequest, { params }: { params: { id: string } }) {
  const session = await getServerSession();
  if (!session?.user) {
    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
  }
  // Check here that this user may see this file
  const signedUrl = await storage.getSignedUrl(params.id, { expiresIn: 3600 });
  return NextResponse.json({ url: signedUrl });
}
```

For a file in a **public** bucket, a server component can render the public image link directly. It needs no headers:

```tsx
// components/ProductImage.tsx (a server component)
import { storage } from '@/lib/storage';

export async function ProductImage({ fileId }: { fileId: string }) {
  const src = await storage.getPublicUrl(fileId, { width: 600, format: 'webp' });
  return <img src={src} width={600} alt="" />;
}
```

<H2 id="sign-users-in-one-token-for-every-abrova-product" step={3}>Sign users in (one token for every Abrova product)</H2>

File requests from the browser always need a signed **Abrova user token**, so access rules (`{userId}`, `authenticated`) see a user nobody can fake. It is the same token Abrova Sync, Chat, Push and A/B Testing accept.

Using **Abrova Auth**? Its sign-in token is this token: use `tokenProvider: () => auth.getToken()` and skip this route. Otherwise a route handler mints it with the server secret:

```typescript
// app/api/abrova-token/route.ts
import { NextResponse } from 'next/server';
import { getServerSession } from 'next-auth';
import { storage } from '@/lib/storage';

export async function POST() {
  const session = await getServerSession();
  if (!session?.user?.id) {
    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
  }
  const { token, expiresAt } = await storage.createUserToken(session.user.id);
  return NextResponse.json({ token, expiresAt });
}
```

While no user is signed in, the Web SDK's file calls wait instead of failing (see [Web SDK](/docs/storage/web)); they go on once the provider returns a token.

### Client-Side (React Components)

```tsx
'use client';
import { useEffect, useState } from 'react';
import { AbrovaStorage } from '@abrova/storage-web';
import { useSession } from 'next-auth/react';

const storage = new AbrovaStorage({
  apiKey: process.env.NEXT_PUBLIC_ABROVA_API_KEY!,
  tokenProvider: async () => {
    const res = await fetch('/api/abrova-token', { method: 'POST' });
    return res.ok ? (await res.json()).token : null; // null = no one signed in: file calls wait
  },
});

export function UploadButton() {
  const { data: session } = useSession();
  const [progress, setProgress] = useState(0);

  // Ask the provider again when the user signs in or out
  useEffect(() => {
    storage.refreshUserToken();
  }, [session?.user?.id]);

  const handleUpload = async (e: React.ChangeEvent<HTMLInputElement>) => {
    const file = e.target.files?.[0];
    if (!file || !session?.user?.id) return;

    const uploaded = await storage.upload('my-bucket', `users/${session.user.id}/${file.name}`, file, {
      onProgress: ({ bytesSent, totalBytes }) => setProgress(bytesSent / totalBytes),
    });
    console.log('Uploaded:', uploaded.id);
  };

  return (
    <>
      <input type="file" onChange={handleUpload} />
      <progress value={progress} max={1} />
    </>
  );
}

// Private files: getTransformUrl() / getUrl() need headers, so ask your server for signed links
export function ImageGallery({ fileIds }: { fileIds: string[] }) {
  const [urls, setUrls] = useState<Record<string, string>>({});

  useEffect(() => {
    Promise.all(
      fileIds.map(async (id) => {
        const { url } = await fetch(`/api/files/${id}`).then((r) => r.json());
        return [id, url] as const;
      }),
    ).then((pairs) => setUrls(Object.fromEntries(pairs)));
  }, [fileIds]);

  return (
    <div className="grid grid-cols-3 gap-4">
      {fileIds.map((id) => urls[id] && <img key={id} src={urls[id]} alt="" />)}
    </div>
  );
}
```

For **public** buckets, use `getPublicUrl(fileId, { width, format })` in either SDK, or `publicImageUrl(savedLink, { width: 400, format: 'webp' })` to build a size from a public link you saved, with no request. Use a few fixed sizes: one image keeps at most 50 variants (`too_many_variants`), and when the free monthly transforms are used up and the wallet cannot pay for more, image URLs answer `plan_feature_locked`. See [Image Transforms](/docs/storage/image-transforms).

Errors from either SDK carry `code` and `statusCode` (`AbrovaStorageError` on the server, `AbrovaStorageException` in the browser), with constants in `StorageErrorCode`.

<Callout kind="warn" title="Environment variables">
Use the `NEXT_PUBLIC_` prefix only for the public API key. Never expose the server secret: read `ABROVA_SERVER_SECRET` only in route handlers and server components.
</Callout>

- Flutter: https://abrova.ir/en/docs/storage/flutter

Native Dart SDK for Flutter mobile and web applications. Covers file uploads, downloads and image transformations.

<H2 id="installation" step={1}>Installation</H2>

Install from Abrova Center in two steps.

```yaml
# 1. pubspec.yaml: install from Abrova Center
dependencies:
  abrova_storage:
    hosted: https://center.abrova.ir/api/packages/abrova/pub
    version: ^0.2.1
```

```bash
# 2. Install
flutter pub get
```

<H2 id="initialization" step={2}>Initialization</H2>

```dart
import 'package:abrova_storage/abrova_storage.dart';

final storage = AbrovaStorage(
  apiKey: 'ab_live_xxxxxxxxxxxx',
  // The signed-in user's Abrova user token, see "Sign users in" below.
  // Return null when no one is signed in.
  tokenProvider: () => myBackend.fetchAbrovaToken(),
);

// Dispose when done (e.g., in your State's dispose())
@override
void dispose() {
  storage.dispose(); // calls still waiting for a user fail with code 'disposed'
  super.dispose();
}
```

<Callout kind="note" title="Client-side only">
The Flutter SDK uses only the `apiKey`. File upload, read, list and delete work from the app and follow the bucket's access rules. Creating and changing buckets and access rules, and making signed links, belong on your backend (Node.js SDK with `serverSecret`). The SDK always connects to Abrova Storage over HTTPS; there is no `baseUrl` option.
</Callout>

### Sign users in (one token for every Abrova product)

File requests from apps always need a signed **Abrova user token**. There is no setting to turn this off. Bucket rules that use `{userId}` match the user in that token. It is the same token Abrova Sync, Chat, Push and A/B Testing accept.

**With Abrova Auth**, no backend is needed. Its token is this token:

```dart
final auth = AbrovaAuth.instance;
final storage = AbrovaStorage(
  apiKey: 'ab_live_xxxxxxxxxxxx',
  tokenProvider: auth.tokenProvider,
);

// After sign-in or sign-out
auth.authStateChanges.listen((_) => storage.refreshUserToken());
```

**With your own server**, your backend mints the token with `POST https://auth.abrova.ir/users/token` and your server secret (it never ships in an app), and `tokenProvider` fetches it, as in step 2.

```dart
// When the user signs in or out
await storage.refreshUserToken();

// Or pass a token you already hold (null signs out)
await storage.setUserToken(token);

// Or set / replace the provider later
await storage.setTokenProvider(() => myBackend.fetchAbrovaToken());
```

The SDK sends the token as `x-user-token`, asks the provider before the first request, and asks again (retrying the request once) when the token has expired or is refused.

#### Waiting for a user

With no token (no one signed in), file calls (upload, list, get, download, delete) are not sent and do not fail: they **wait**. They go on by themselves, in order, once a user signs in. This is by design: show your sign-in screen while they wait. Bucket reads (`listBuckets`, `getBucket`, `getBucketByName`) and `getPublicUrl` need no user and never wait.

```dart
final storage = AbrovaStorage(
  apiKey: 'ab_live_xxxxxxxxxxxx',
  tokenProvider: auth.tokenProvider,
);
storage.onAwaitingUserToken(() => showSignIn()); // once per wait
storage.isAwaitingUserToken; // true while file calls wait for a user
```

A token the server keeps refusing throws the same exception with `token_expired` or `token_invalid`.

**Don't wait on file calls before sign-in.** A file call made while no one is signed in finishes only after sign-in. Don't wait for it in code the user is waiting on (a button handler, a startup check): start it in the background, or after sign-in.

**Leave the timeout unset.** By default a call waits until sign-in, which is right for background work. Set `userTokenWaitTimeout` only when a screen waits for the answer and can send the user to sign-in:

```dart
final storage = AbrovaStorage(
  apiKey: 'ab_live_xxxxxxxxxxxx',
  tokenProvider: auth.tokenProvider,
  userTokenWaitTimeout: const Duration(seconds: 30), // throws token_required after 30 s
);
```

A call that waited that long throws an `AbrovaStorageTokenException` with `code == 'token_required'` (status 401). The `timeout` option is a different setting: it limits each network request (default 30 seconds) and never covers the wait for a user.

**With Abrova Auth**, turn on the sign-in method you use (for example Anonymous) in **Abrova Auth › Sign-in methods**. If it is off, sign-in fails with `METHOD_DISABLED`, no one is signed in, and file calls wait without an error. While developing, log from `onAwaitingUserToken` (`debugPrint('Storage: waiting for a user')`) so a silent wait is easy to spot.

Upgrading from 0.2.0: `userId` / `setUserId()` are removed. Use `tokenProvider`.

### Upload Files

```dart
import 'dart:io';
import 'dart:typed_data';
import 'package:abrova_storage/abrova_storage.dart';

// Upload from Uint8List (bytes)
final Uint8List imageBytes = await File('path/to/image.jpg').readAsBytes();

final file = await storage.upload(
  'my-bucket',
  'images/photo.jpg',
  imageBytes,
  options: UploadOptions(
    contentType: 'image/jpeg',
    metadata: {'source': 'camera'},
  ),
  // Optional: about every 50 ms or 1%; the last call has sent == total
  onProgress: (sent, total) => setState(() => _progress = sent / total),
);

print('Uploaded: ${file.id}');
print('Size: ${file.size} bytes');
```

`total` is the whole upload request: your file plus a few hundred bytes of form fields. On Flutter web the browser takes the whole file at once, so progress jumps to 100% when the upload starts. When you pass no `contentType`, the SDK sends the type for the file's extension (`photo.HEIC` as `image/heic`, `notes.md` as `text/markdown`).

**Paths.** Pass paths as you write them: spaces, `#`, `?` and non-Latin characters are encoded for you. A `.` or `..` part is refused with `invalid_path` before anything is sent, and a new file's path can't contain `?`, `#` or `%`.

### Download Files

```dart
// Download file content as Uint8List
final Uint8List bytes = await storage.download(fileId);

// Save to local file
final file = File('${directory.path}/downloaded.jpg');
await file.writeAsBytes(bytes);

// Or display directly
Image.memory(bytes);
```

### List Files

```dart
// List files in a bucket
final result = await storage.listFiles(
  'my-bucket',
  options: ListFilesOptions(
    prefix: 'images/',
    limit: 50,
  ),
);

for (final file in result.files) {
  print('${file.path}: ${file.size} bytes');
}

// Pagination: nextCursor is null on the last page
if (result.nextCursor != null) {
  final nextPage = await storage.listFiles(
    'my-bucket',
    options: ListFilesOptions(cursor: result.nextCursor),
  );
}
```

A `StorageFile` has `id`, `bucketId`, `path`, `fileName`, `mimeType`, `size`, `checksum`, `metadata`, `uploadedBy`, `uploadedAt`, `createdAt` and `updatedAt` (`checksum`, `metadata`, `uploadedBy` and `uploadedAt` are `null` when empty). A `Bucket` has `id`, `name`, `description`, `visibility`, `allowedMimeTypes` (`null` = every type), `maxFileSize`, `blockExecutables`, `createdAt` and `updatedAt`. Dates are `DateTime` (UTC).

### Delete Files

```dart
// Deletes follow the bucket's delete rules
// Delete a file by ID
await storage.delete(fileId);

// Delete a file by path
await storage.deleteByPath('my-bucket', 'images/photo.jpg');

// Delete multiple files at once
final result = await storage.deleteMany([
  'file_id_1',
  'file_id_2',
  'file_id_3',
]);
print('Deleted ${result.deleted} files');
```

### Show Images

For a file in a **public** bucket, `getPublicUrl` returns a link that needs no key, token or header. With image options it returns a resized or converted image, ready for a bare `Image.network(url)`:

```dart
// A 600 px wide WebP, straight into Image.network
final url = await storage.getPublicUrl(file.id,
    transforms: const ImageTransforms(width: 600, format: 'webp'));
Image.network(url);

// A public link you stored earlier: the same URL, no request
final thumb = AbrovaStorage.publicImageUrl(savedLink,
    transforms: const ImageTransforms(width: 200, height: 200, fit: 'cover', format: 'webp'));
```

- **Cached, so use a few fixed sizes.** The same options always give the same URL, made once and then served from the cache. One image keeps at most 50 variants; a new one beyond that is refused with `too_many_variants` (429). Pick a few sizes (for example 200, 600 and 1200 wide).
- **Usage.** When the month's 500 free transforms are used up and your wallet cannot pay for more, an image URL with options answers `plan_feature_locked` (403). The plain public link always works.
- **Busy.** `transform_busy` (503) comes with a `Retry-After` header in seconds. `Image.network` calls its `errorBuilder`: load the image again after that (for example on a retry tap).
- **Private buckets** have no public link (`getPublicUrl` fails with 403). `download` the bytes, or load `getTransformUrl` with your headers:

```dart
// The transform address needs the key and user token headers
final thumbnailUrl = storage.getTransformUrl(
  fileId,
  transforms: const ImageTransforms(width: 200, height: 200, fit: 'cover', format: 'webp'),
);
Image.network(
  thumbnailUrl,
  headers: {
    'x-api-key': 'ab_live_xxxxxxxxxxxx',
    'x-user-token': userToken, // the signed-in user's token
  },
);

// All available options
const options = ImageTransforms(
  width: 800,      // 1 or more (above 4096 sent as 4096)
  height: 600,
  fit: 'contain',  // cover, contain, fill, inside, outside
  format: 'webp',  // jpeg (default), png, webp, avif
  quality: 85,     // 1-100
  blur: 5,         // 0-20
  sharpen: 2,      // 0-10
  rotate: 90,      // degrees (multiples of 90 recommended)
);
```

`getTransformUrl` and `publicImageUrl` throw `invalid_transform` for any other value, before a URL is built. A signed link for a private file comes from your server (`getSignedUrl` in the Node.js SDK).

### Complete Example: Profile Image Upload

```dart
import 'package:flutter/material.dart';
import 'package:image_picker/image_picker.dart';
import 'package:abrova_storage/abrova_storage.dart';

class ProfileService {
  final AbrovaStorage _storage;

  ProfileService(String apiKey, AbrovaStorageTokenProvider tokenProvider)
      : _storage = AbrovaStorage(apiKey: apiKey, tokenProvider: tokenProvider);

  // Uploads to the public "avatars" bucket and returns a 200 px thumbnail link
  Future<String?> uploadProfileImage(String userId) async {
    final picker = ImagePicker();
    final pickedFile = await picker.pickImage(
      source: ImageSource.gallery,
      maxWidth: 1024,
      maxHeight: 1024,
      imageQuality: 85,
    );
    if (pickedFile == null) return null;

    final bytes = await pickedFile.readAsBytes();
    final file = await _storage.upload(
      'avatars',
      'users/$userId/avatar.jpg',
      bytes,
      options: UploadOptions(contentType: 'image/jpeg'),
    );

    return _storage.getPublicUrl(
      file.id,
      transforms: const ImageTransforms(width: 200, height: 200, fit: 'cover', format: 'webp'),
    );
  }

  // No headers needed for a public link
  Widget avatar(String url) => Image.network(url);

  void dispose() {
    _storage.dispose();
  }
}
```

### Error Handling

Every `AbrovaStorageException` has the server's `message`, the HTTP `statusCode` and, when the server named the reason, its `code` (constants in `StorageErrorCode`). `code` is null when the server gave no reason (a `404`, a `429`), and `statusCode` is null when no answer arrived.

```dart
try {
  await storage.upload('photos', 'clips/a.mov', bytes);
} on AbrovaStorageTokenException catch (e) {
  // token_required / token_expired / token_invalid: send the user to sign in
  print('Sign-in needed: ${e.code}');
} on AbrovaStorageException catch (e) {
  if (e.isTypeNotAllowed) {
    showError("This bucket doesn't take this file type");
  } else if (e.isFileTooLarge) {
    showError('The file is too big');
  } else if (e.code == StorageErrorCode.pathTaken) {
    showError('A file with this name already exists');
  } else if (e.code == StorageErrorCode.accessDenied) {
    showError("You can't write here");
  } else {
    showError(e.message);
  }
}
```

<ConfigTable headers={['Status', 'code', 'When']} rows={[
  ['401', 'token_required', 'No user signed in within userTokenWaitTimeout.'],
  ['401', 'token_expired, token_invalid', 'The user token was refused and the provider had no other one.'],
  ['403', 'access_denied', "The bucket's access rules refused the request."],
  ['400', 'type_not_allowed, file_too_large, executable_blocked', "The upload doesn't fit the bucket's file settings."],
  ['409', 'path_taken', 'A file already exists at this path.'],
  ['400', 'invalid_path', 'The path was refused (see Upload Files).'],
  ['400', 'invalid_transform', 'An image option is not allowed.'],
  ['403', 'plan_feature_locked', "No transforms left: the free monthly transforms are used up and the wallet cannot pay for more."],
  ['429', 'too_many_variants', 'This image already has 50 sizes / formats.'],
  ['503', 'transform_busy', 'Image processing is busy. Retry after Retry-After seconds.'],
  ['-', 'disposed', 'dispose() was called while the call waited for a user.'],
]} />

### API Reference

<ConfigTable rows={[
  ['listBuckets()', '-', '-', 'List all buckets in the project'],
  ['getBucket(id)', '-', '-', 'Get bucket by ID'],
  ['getBucketByName(name)', '-', '-', 'Get bucket by name'],
  ['upload(bucket, path, data, options:, onProgress:)', '-', '-', 'Upload a file to a bucket, with optional progress'],
  ['listFiles(bucket, options:)', '-', '-', 'List files in a bucket'],
  ['getFile(id)', '-', '-', 'Get file metadata by ID'],
  ['getFileByPath(bucket, path)', '-', '-', 'Get file metadata by path'],
  ['download(id)', '-', '-', 'Download file content as bytes'],
  ['delete(id)', '-', '-', 'Delete a file by ID'],
  ['deleteByPath(bucket, path)', '-', '-', 'Delete a file by path'],
  ['deleteMany(ids)', '-', '-', 'Delete multiple files at once'],
  ['getPublicUrl(id, transforms:)', '-', '-', 'Public link (public buckets only), optionally a resized / converted image; needs no headers'],
  ['AbrovaStorage.publicImageUrl(publicUrl, transforms:)', '-', '-', 'Build the image link from a saved public link, without a request'],
  ['getUrl(id)', '-', '-', 'Address of the public-link endpoint; needs x-api-key and answers { url } for files in a public bucket'],
  ['getTransformUrl(id, transforms:)', '-', '-', 'Transform address; needs the x-api-key and x-user-token headers'],
  ['getDownloadUrl(id)', '-', '-', 'Download address; needs the x-api-key and x-user-token headers'],
  ['refreshUserToken()', '-', '-', 'Ask the token provider again (call on sign-in / sign-out)'],
  ['setUserToken(token)', '-', '-', 'Use this Abrova user token; null signs out'],
  ['setTokenProvider(provider)', '-', '-', 'Set or replace the token provider'],
  ['isAwaitingUserToken', '-', '-', 'True while file calls wait for a user'],
  ['onAwaitingUserToken(callback)', '-', '-', 'Called once each time file calls start waiting for a user'],
  ['dispose()', '-', '-', 'Close the HTTP client; waiting calls fail with code disposed'],
]} />

- Android: https://abrova.ir/en/docs/storage/android

Native Kotlin SDK for Android applications. Uses coroutines for async operations and OkHttp for networking.

<H2 id="installation" step={1}>Installation</H2>

Install from Abrova Center in two steps.

```groovy
// 1. settings.gradle (or the project build.gradle): add Abrova Center
repositories {
    google()
    mavenCentral()
    maven { url "https://center.abrova.ir/api/packages/abrova/maven" }
}
```

```kotlin
// 2. build.gradle.kts (app module)
dependencies {
    implementation("ir.abrova:abrova-storage:0.2.1")
}
```

Add `<uses-permission android:name="android.permission.INTERNET" />` to `AndroidManifest.xml`.

<H2 id="usage" step={2}>Usage</H2>

```kotlin
import ir.abrova.storage.*

val storage = AbrovaStorage.builder("ab_live_xxxxxxxxxxxx")
    // The signed-in user's Abrova user token, see step 3.
    // Called on a background thread. Return null when no one is signed in.
    .userTokenProvider { myBackend.fetchAbrovaToken() }
    .build()

// Upload a file, with an optional progress callback (main thread)
val file = storage.upload(
    bucketId = "my-bucket",
    path = "photos/avatar.jpg",
    data = imageBytes,         // ByteArray
    options = UploadOptions(contentType = "image/jpeg"),
    onProgress = { p -> progressBar.progress = (p.fraction * 100).toInt() },
)
println("Uploaded: ${file.id}")

// List files
val result = storage.listFiles(
    bucketId = "my-bucket",
    options = ListFilesOptions(prefix = "photos/", limit = 20),
)
result.files.forEach { println("  - ${it.path} (${it.size} bytes)") }

// Download
val bytes = storage.download(fileId = file.id)

// Delete (follows the bucket's delete rules)
storage.delete(fileId = file.id)
```

<Callout kind="note" title="Coroutines">
All network methods are `suspend` functions. Call them from a coroutine scope (e.g., `viewModelScope.launch { ... }`).
</Callout>

The last progress call has `bytesSent == totalBytes`. `totalBytes` is the whole upload request: your file plus a few hundred bytes of form fields.

<H2 id="sign-users-in-one-token-for-every-abrova-product" step={3}>Sign users in (one token for every Abrova product)</H2>

File requests from apps always need a signed **Abrova user token**. There is no setting to turn this off. Bucket rules that use `{userId}` match the user in that token. It is the same token Abrova Sync, Chat, Push and A/B Testing accept.

**With Abrova Auth**, no backend is needed. Its token is this token:

```kotlin
val auth = AbrovaAuth.shared
val storage = AbrovaStorage.builder("ab_live_xxxxxxxxxxxx")
    // Called off the main thread, so the blocking provider is the right one.
    .userTokenProvider(auth.blockingTokenProvider)
    .onAwaitingUserToken { showSignIn() }           // optional; once per wait, background thread
    .build()

// After sign-in or sign-out
auth.addAuthStateListener { storage.refreshUserToken() }
```

**With your own server**, your backend mints the token with `POST https://auth.abrova.ir/users/token` and your server secret (it never ships in an app), and `userTokenProvider { myBackend.fetchAbrovaToken() }` fetches it. Call `storage.refreshUserToken()` when the user signs in or out, or pass a token you hold with `storage.setUserToken(token)` (`null` signs out). The SDK sends the token as `x-user-token` and gets a new one (retrying the request once, uploads included) when it has expired or is refused.

**Waiting for a user.** With no token (no one signed in), file calls (upload, list, get, download, delete) are not sent and do not fail: they wait, and go on by themselves, in order, once a user signs in. This is by design: show your sign-in screen while they wait (`storage.isAwaitingUserToken` is `true` meanwhile). Bucket reads (`listBuckets`, `getBucket`, `getBucketByName`) and `getPublicUrl` never wait. Cancelling the coroutine also ends the wait. A refused token with no replacement throws `UserTokenRejectedException`.

**Don't wait on file calls before sign-in.** A file call made while no one is signed in finishes only after sign-in. Don't wait for it in code the user is waiting on (a button handler, a startup check): start it in the background, or after sign-in.

**Leave the timeout unset.** By default a call waits until sign-in, which is right for background work. Set `userTokenWaitTimeout` only when a screen waits for the answer and can send the user to sign-in:

```kotlin
val storage = AbrovaStorage.builder("ab_live_xxxxxxxxxxxx")
    .userTokenProvider(auth.blockingTokenProvider)
    .userTokenWaitTimeout(30, TimeUnit.SECONDS) // fails with UserTokenRequiredException after 30 s
    .build()
```

A call that waited that long throws `AbrovaStorageException.UserTokenRequiredException` (`token_required`). The `timeout` option is a different setting: it limits each network request (default 30 seconds) and never covers the wait for a user.

**With Abrova Auth**, turn on the sign-in method you use (for example Anonymous) in **Abrova Auth › Sign-in methods**. If it is off, sign-in fails with `METHOD_DISABLED`, no one is signed in, and file calls wait without an error. While developing, log from `onAwaitingUserToken` (`Log.d("Storage", "waiting for a user")`) so a silent wait is easy to spot.

Upgrading from 0.2.0: `userId` / `setUserId()` are removed. Use the token provider.

### Showing images

For a file in a **public** bucket, `getPublicUrl` returns a link that needs no key, token or header. With image options it returns a resized or converted image, ready for Coil or Glide:

```kotlin
// A 600 px wide WebP, straight into Coil (Compose)
val url = storage.getPublicUrl(file.id, ImageTransforms(width = 600, format = "webp"))
AsyncImage(model = url, contentDescription = null)
// Views + Glide: Glide.with(imageView).load(url).into(imageView)

// A public link you stored earlier: the same URL, no request
val thumb = AbrovaStorage.publicImageUrl(
    savedLink,
    ImageTransforms(width = 200, height = 200, fit = "cover", format = "webp"),
)
```

- **Cached, so use a few fixed sizes.** The same options always give the same URL, made once and then served from the cache. One image keeps at most 50 variants; a new one beyond that is refused with `too_many_variants` (429). Pick a few sizes (for example 200, 600 and 1200 wide).
- **Usage.** When the month's 500 free transforms are used up and your wallet cannot pay for more, an image URL with options answers `plan_feature_locked` (403). The plain public link always works.
- **Busy.** `transform_busy` (503) comes with a `Retry-After` header in seconds: load the image again after that.
- **Private buckets** have no public link (`getPublicUrl` fails with 403). Download the bytes, or load `getTransformUrl` with your headers:

```kotlin
// Private file: download the bytes and decode them
val bytes = storage.download(fileId = file.id)
imageView.setImageBitmap(BitmapFactory.decodeByteArray(bytes, 0, bytes.size))

// Or the transform address, which needs the key and user token headers
val thumbnailUrl = storage.getTransformUrl(
    fileId = file.id,
    transforms = ImageTransforms(width = 200, height = 200, fit = "cover", format = "webp"),
)
imageView.load(thumbnailUrl) {
    addHeader("x-api-key", "ab_live_xxxxxxxxxxxx")
    addHeader("x-user-token", userToken) // the signed-in user's token
}
```

Image options: `format` `jpeg` (default), `png`, `webp` or `avif`; `fit` `cover`, `contain`, `fill`, `inside` or `outside`; `width` / `height` 1 or more (above 4096 sent as 4096); `quality` 1-100; `blur` 0-20; `sharpen` 0-10; `rotate` degrees. Anything else throws `invalid_transform` before a URL is built. A signed link for a private file comes from your server (`getSignedUrl` in the Node.js SDK).

### Handling errors

Every `AbrovaStorageException` the server caused carries its HTTP `statusCode` and, when the server named the reason, its `code` (constants in `StorageErrorCode`):

```kotlin
try {
    storage.upload("photos", "clips/a.mov", bytes)
} catch (e: AbrovaStorageException) {
    when {
        e.isTypeNotAllowed -> showError("This bucket doesn't take this file type")
        e.isFileTooLarge -> showError("The file is too big")
        e.code == StorageErrorCode.PATH_TAKEN -> showError("A file with this name already exists")
        e.code == StorageErrorCode.ACCESS_DENIED -> showError("You can't write here")
        else -> showError(e.message ?: "Upload failed")
    }
}
```

`code` is null when the server gave no reason (a `404`, a `429`), and `statusCode` is null when no answer arrived (`NetworkException`).

<ConfigTable headers={['Status', 'code', 'When']} rows={[
  ['401', 'token_required', 'No user signed in within userTokenWaitTimeout.'],
  ['401', 'token_expired, token_invalid', 'The user token was refused and the provider had no other one.'],
  ['403', 'access_denied', "The bucket's access rules refused the request."],
  ['400', 'type_not_allowed, file_too_large, executable_blocked', "The upload doesn't fit the bucket's file settings."],
  ['409', 'path_taken', 'A file already exists at this path.'],
  ['400', 'invalid_path', 'The path was refused (see below).'],
  ['400', 'invalid_transform', 'An image option is not allowed.'],
  ['403', 'plan_feature_locked', "No transforms left: the free monthly transforms are used up and the wallet cannot pay for more."],
  ['429', 'too_many_variants', 'This image already has 50 sizes / formats.'],
  ['503', 'transform_busy', 'Image processing is busy. Retry after Retry-After seconds.'],
]} />

### Files, buckets and paths

- A `StorageFile` has `id`, `bucketId`, `path`, `fileName`, `mimeType`, `size` (`Long`), `checksum`, `metadata`, `uploadedBy`, `uploadedAt`, `createdAt` and `updatedAt` (`checksum`, `metadata`, `uploadedBy` and `uploadedAt` are `null` when empty). Dates are `java.util.Date`.
- A `Bucket` has `id`, `name`, `description`, `visibility`, `allowedMimeTypes` (`null` = every type), `maxFileSize`, `blockExecutables`, `createdAt` and `updatedAt`.
- `listFiles` answers `files` and `nextCursor` (`null` on the last page).
- **Paths.** Pass paths as you write them: spaces, `#`, `?` and non-Latin characters are encoded for you. A `.` or `..` part is refused with `invalid_path` before anything is sent, and a new file's path can't contain `?`, `#` or `%`.
- When you pass no `contentType`, the SDK sends the type for the file's extension (`photo.HEIC` as `image/heic`, `notes.md` as `text/markdown`).
- The SDK always connects to Abrova Storage over HTTPS; there is no `baseUrl` option.

- iOS: https://abrova.ir/en/docs/storage/ios

Native Swift SDK for iOS/macOS. Supports async/await (iOS 13+) and completion handler APIs (iOS 11+). No third-party dependencies.

<H2 id="installation" step={1}>Installation</H2>

Install with Swift Package Manager. In Xcode: **File → Add Package Dependencies…**, paste `https://github.com/Abrova-co/abrova-storage-ios-sdk.git` and choose the version. Or in `Package.swift`:

```swift
dependencies: [
    .package(url: "https://github.com/Abrova-co/abrova-storage-ios-sdk.git", from: "0.2.1")
]
```

<H2 id="usage-async-await" step={2}>Usage (async/await)</H2>

```swift
import AbrovaStorage

// The signed-in user's Abrova user token, see step 3.
// Return nil when no one is signed in.
let storage = AbrovaStorage(apiKey: "ab_live_xxxxxxxxxxxx") {
    try await myBackend.fetchAbrovaToken()
}

// Upload a file, with an optional progress callback (main queue)
let file = try await storage.upload(
    bucketId: "my-bucket",
    path: "photos/avatar.jpg",
    data: imageData,
    options: UploadOptions(contentType: "image/jpeg"),
    progress: { p in progressView.progress = Float(p.fraction) }
)
print("Uploaded: \(file.id)")

// List files
let result = try await storage.listFiles(
    bucketId: "my-bucket",
    options: ListFilesOptions(prefix: "photos/", limit: 20)
)
for file in result.files {
    print("  - \(file.path) (\(file.size) bytes)")
}

// Download
let data = try await storage.download(fileId: file.id)

// Delete (follows the bucket's delete rules)
try await storage.delete(fileId: file.id)
```

The last progress call has `bytesSent == totalBytes`. `totalBytes` is the whole request, so it is a little larger than the file.

<H2 id="sign-users-in-one-token-for-every-abrova-product" step={3}>Sign users in (one token for every Abrova product)</H2>

File requests from apps always need a signed **Abrova user token**. There is no setting to turn this off. Bucket rules that use `{userId}` match the user in that token. It is the same token Abrova Sync, Chat, Push and A/B Testing accept.

**With Abrova Auth**, no backend is needed. Its token is this token:

```swift
let auth = AbrovaAuth.shared
let storage = AbrovaStorage(apiKey: "ab_live_xxxxxxxxxxxx", userTokenProvider: auth.tokenProvider)
storage.onAwaitingUserToken = { showSignIn() }          // optional; once per wait, background queue

// After sign-in or sign-out
let listener = auth.addAuthStateListener { _ in storage.refreshUserToken() }
```

**With your own server**, your backend mints the token with `POST https://auth.abrova.ir/users/token` and your server secret (it never ships in an app), and the provider fetches it, as in step 2. On an existing instance set `storage.userTokens.provider = { try await myBackend.fetchAbrovaToken() }`; apps that support iOS 11/12 use the callback form:

```swift
storage.userTokens.setProvider { completion in
    myBackend.fetchAbrovaToken { token in completion(.success(token)) } // .success(nil) = signed out
}
storage.refreshUserToken()   // when the user signs in or out
storage.setUserToken(token)  // or pass a token you already hold (nil signs out)
```

The SDK sends the token as `x-user-token` and gets a new one (retrying the request once, uploads included) when it has expired or is refused.

**Waiting for a user.** With no token (no one signed in), file calls (upload, list, get, download, delete) are not sent and do not fail: they wait, and go on by themselves, in order, once a user signs in. This is by design: show your sign-in screen while they wait (`storage.isAwaitingUserToken` is `true` meanwhile). Bucket reads (`listBuckets`, `getBucket`, `getBucketByName`) and `getPublicUrl` never wait. A refused token with no replacement fails with `.userTokenRejected(code:message:)`.

**Don't wait on file calls before sign-in.** A file call made while no one is signed in finishes only after sign-in. Don't wait for it in code the user is waiting on (a button handler, a startup check): start it in the background, or after sign-in.

**Leave the timeout unset.** By default a call waits until sign-in, which is right for background work. Set `userTokenWaitTimeout` only when a screen waits for the answer and can send the user to sign-in:

```swift
let storage = AbrovaStorage(apiKey: "ab_live_xxxxxxxxxxxx",
                            userTokenWaitTimeout: 30, // seconds; then fails with .userTokenRequired
                            userTokenProvider: auth.tokenProvider)
```

A call that waited that long fails with `AbrovaStorageError.userTokenRequired` (`token_required`). The `timeout` option is a different setting: it limits each network request (default 30 seconds) and never covers the wait for a user.

**With Abrova Auth**, turn on the sign-in method you use (for example Anonymous) in **Abrova Auth › Sign-in methods**. If it is off, sign-in fails with `METHOD_DISABLED`, no one is signed in, and file calls wait without an error. While developing, log from `onAwaitingUserToken` (`print("Storage: waiting for a user")`) so a silent wait is easy to spot.

Upgrading from 0.2.0: `userId` / `setUserId(_:)` are removed. Use the token provider.

### Showing images

For a file in a **public** bucket, `getPublicUrl` returns a link that needs no key, token or header. With image options it returns a resized or converted image, ready for `AsyncImage`:

```swift
// A 600 px wide WebP, straight into SwiftUI
let url = try await storage.getPublicUrl(fileId: file.id, transforms: ImageTransforms(width: 600, format: "webp"))
AsyncImage(url: URL(string: url)) { image in
    image.resizable().scaledToFit()
} placeholder: {
    ProgressView()
}

// A public link you stored earlier: the same URL, no request
let thumb = try AbrovaStorage.publicImageUrl(
    savedLink,
    transforms: ImageTransforms(width: 200, height: 200, fit: "cover", format: "webp")
)
```

- **Cached, so use a few fixed sizes.** The same options always give the same URL, made once and then served from the cache. One image keeps at most 50 variants; a new one beyond that is refused with `too_many_variants` (429). Pick a few sizes (for example 200, 600 and 1200 wide).
- **Usage.** When the month's 500 free transforms are used up and your wallet cannot pay for more, an image URL with options answers `plan_feature_locked` (403). The plain public link always works.
- **Busy.** `transform_busy` (503) comes with a `Retry-After` header in seconds: load the image again after that (for example with a new `.id` on the `AsyncImage`).
- **Private buckets** have no public link (`getPublicUrl` fails with 403). Download the bytes, or load `getTransformUrl` with your headers:

```swift
// Private file: download and show
let data = try await storage.download(fileId: file.id)
let image = UIImage(data: data)

// Or the transform address, which needs the key and user token headers
let transforms = ImageTransforms(width: 200, height: 200, fit: "cover", format: "webp")
try transforms.validate() // invalid_transform before the URL is built
let thumbnailUrl = storage.getTransformUrl(fileId: file.id, transforms: transforms)
var request = URLRequest(url: URL(string: thumbnailUrl)!)
request.setValue("ab_live_xxxxxxxxxxxx", forHTTPHeaderField: "x-api-key")
request.setValue(userToken, forHTTPHeaderField: "x-user-token") // the signed-in user's token
let (thumbData, _) = try await URLSession.shared.data(for: request)
```

Image options: `format` `jpeg` (default), `png`, `webp` or `avif`; `fit` `cover`, `contain`, `fill`, `inside` or `outside`; `width` / `height` 1 or more (above 4096 sent as 4096); `quality` 1-100; `blur` 0-20; `sharpen` 0-10; `rotate` degrees. `getTransformUrl` can't throw, so call `transforms.validate()` to catch a bad value first. A signed link for a private file comes from your server (`getSignedUrl` in the Node.js SDK).

### Handling errors

Each `AbrovaStorageError` the server caused has its HTTP `statusCode` and, when the server named the reason, its `code` (constants in `StorageErrorCode`):

```swift
do {
    let file = try await storage.upload(bucketId: "photos", path: "clips/a.mov", data: data)
} catch let error as AbrovaStorageError {
    if error.isTypeNotAllowed {
        showError("This bucket doesn't take this file type")
    } else if error.isFileTooLarge {
        showError("The file is too big")
    } else if error.code == StorageErrorCode.pathTaken {
        showError("A file with this name already exists")
    } else if error.code == StorageErrorCode.accessDenied {
        showError("You can't write here")
    } else {
        showError(error.localizedDescription)
    }
}
```

`code` is nil when the server gave no reason (a `404`, a `429`), and `statusCode` is nil when no answer arrived (`.networkError`).

<ConfigTable headers={['Status', 'code', 'When']} rows={[
  ['401', 'token_required', 'No user signed in within userTokenWaitTimeout.'],
  ['401', 'token_expired, token_invalid', 'The user token was refused and the provider had no other one.'],
  ['403', 'access_denied', "The bucket's access rules refused the request."],
  ['400', 'type_not_allowed, file_too_large, executable_blocked', "The upload doesn't fit the bucket's file settings."],
  ['409', 'path_taken', 'A file already exists at this path.'],
  ['400', 'invalid_path', 'The path was refused (see below).'],
  ['400', 'invalid_transform', 'An image option is not allowed.'],
  ['403', 'plan_feature_locked', "No transforms left: the free monthly transforms are used up and the wallet cannot pay for more."],
  ['429', 'too_many_variants', 'This image already has 50 sizes / formats.'],
  ['503', 'transform_busy', 'Image processing is busy. Retry after Retry-After seconds.'],
]} />

### Files, buckets and paths

- A `StorageFile` has `id`, `bucketId`, `path`, `fileName`, `mimeType`, `size`, `checksum`, `metadata`, `uploadedBy`, `uploadedAt`, `createdAt` and `updatedAt` (`checksum`, `metadata`, `uploadedBy` and `uploadedAt` are `nil` when empty). Dates are `Date`.
- A `Bucket` has `id`, `name`, `description`, `visibility`, `allowedMimeTypes` (`nil` = every type), `maxFileSize`, `blockExecutables`, `createdAt` and `updatedAt`.
- `listFiles` answers `files` and `nextCursor` (`nil` on the last page).
- **Paths.** Pass paths as you write them: spaces, `#`, `?` and non-Latin characters are encoded for you. A `.` or `..` part is refused with `invalid_path` before anything is sent, and a new file's path can't contain `?`, `#` or `%`.
- When you pass no `contentType`, the SDK sends the type for the file's extension (`photo.HEIC` as `image/heic`, `notes.md` as `text/markdown`).

### Completion Handlers (iOS 11+)

For older iOS versions or callback-based code. The completion form of `upload` takes the same `progress:` argument.

```swift
storage.listBuckets { result in
    switch result {
    case .success(let buckets):
        print("Found \(buckets.count) buckets")
    case .failure(let error):
        print("Error: \(error.localizedDescription)")
    }
}

storage.upload(
    bucketId: "my-bucket",
    path: "photo.jpg",
    data: imageData,
    options: UploadOptions(contentType: "image/jpeg")
) { result in
    switch result {
    case .success(let file):
        print("Uploaded: \(file.id)")
    case .failure(let error):
        print("Upload failed: \(error)")
    }
}
```

- REST API: https://abrova.ir/en/docs/storage/rest

Use the REST API directly without an SDK. All requests go to `https://storage.abrova.ir`.

<H2 id="authentication-headers" step={1}>Authentication Headers</H2>

```bash
# Required for all /api/v1 requests
x-api-key: ab_live_xxxxxxxxxxxx

# From apps: the signed Abrova user token of the signed-in user.
# Required on every file and transform request from an app
# (minted by your server or Abrova Auth, see "Sign users in" on the Overview page)
x-user-token: eyJhbGciOi...

# From your server only. Skips access rules; no user token needed.
# Required for bucket and access-rule changes and signed links
x-server-secret: ab_srv_xxxxxxxxxxxx

# Content type for JSON requests
Content-Type: application/json
```

Listing and reading buckets and getting a file's public link need only `x-api-key`. Public links (`/public/…`) need no headers at all.

#### Error codes

Every error answers `{ "statusCode": 401, "code": "token_expired", "message": "…", "timestamp": "…" }`. Switch on `code`; show `message` to your users. The SDKs expose the codes as `StorageErrorCode` constants.

<ConfigTable headers={['Status', 'code', 'Meaning']} rows={[
  ['400', 'invalid_path', 'The path was refused (a .. segment, control characters, a name starting or ending with a space, too long; new paths also can\'t contain ?, # or %).'],
  ['400', 'type_not_allowed', 'The bucket doesn\'t allow this file\'s type.'],
  ['400', 'file_too_large', 'The file is larger than the bucket\'s size limit.'],
  ['400', 'executable_blocked', 'The bucket blocks executable files and this one is (by name or content).'],
  ['400', 'file_required', 'The upload had no file part.'],
  ['400', 'invalid_ids', 'delete-many needs a list of 1 to 1,000 file ids.'],
  ['400', 'invalid_rules', 'An access rule is wrong (the message names the first problem).'],
  ['400', 'upload_rejected', 'confirm-upload: the signed upload was refused (size, type, rules or usage).'],
  ['401', 'token_required', 'An app file or transform request had no x-user-token.'],
  ['401', 'token_expired', 'The user token has expired. Get a new one and retry.'],
  ['401', 'token_invalid', 'The user token is not valid (bad signature, another project, not an Abrova user token).'],
  ['403', 'access_denied', 'The bucket\'s access rules refused the request.'],
  ['403', 'server_secret_required', 'Bucket, rule and signed-link actions need x-server-secret; call them from your server.'],
  ['404', '—', 'Not found (also a /public link of a private or unknown file).'],
  ['409', 'path_taken', 'A file already exists at this path.'],
  ['409', 'upload_missing, upload_expired', 'confirm-upload: nothing was uploaded yet, or the link expired.'],
  ['429', '—', 'Too many requests. Wait and retry.'],
]} />

Image transforms have their own codes, listed under Transform errors below.

<H2 id="bucket-endpoints" step={2}>Bucket Endpoints</H2>

#### List buckets

```bash
# GET /api/v1/buckets
curl -X GET "https://storage.abrova.ir/api/v1/buckets" \
  -H "x-api-key: ab_live_xxx"

# Response
[
  {
    "id": "8f0c6d1e-…",
    "name": "my-bucket",
    "description": null,
    "visibility": "private",
    "allowedMimeTypes": ["image/*"],
    "maxFileSize": 10485760,
    "blockExecutables": true,
    "createdAt": "2026-10-23T09:15:02.123Z",
    "updatedAt": "2026-10-23T09:15:02.123Z"
  }
]
```

`allowedMimeTypes` is `null` when every type is allowed. `GET /api/v1/buckets/:id`, `GET /api/v1/buckets/name/:name` and `GET /api/v1/buckets/:id/stats` (`{ "fileCount": 12, "totalSize": 4096000 }`) work the same way.

#### Create bucket

Needs `x-server-secret` (otherwise 403 `server_secret_required`). The project comes from the API key.

```bash
# POST /api/v1/buckets
curl -X POST "https://storage.abrova.ir/api/v1/buckets" \
  -H "x-api-key: ab_live_xxx" \
  -H "x-server-secret: ab_srv_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "user-uploads",
    "visibility": "private",
    "allowedMimeTypes": ["image/*", "application/pdf"],
    "maxFileSize": 10485760
  }'
```

`PUT /api/v1/buckets/:id` (update) and `DELETE /api/v1/buckets/:id` follow the same rule.

<H2 id="file-endpoints" step={3}>File Endpoints</H2>

From an app, file upload, read, list and delete need `x-api-key` and `x-user-token`, and follow the bucket's access rules (a bucket with no rules allows everything to any signed-in user). From your server, send `x-server-secret` instead of a user token.

#### Upload (multipart/form-data)

```bash
# POST /api/v1/buckets/:bucketId/files
curl -X POST "https://storage.abrova.ir/api/v1/buckets/BUCKET_ID/files" \
  -H "x-api-key: ab_live_xxx" \
  -H "x-user-token: $USER_TOKEN" \
  -F "file=@/path/to/image.jpg" \
  -F "path=images/photo.jpg" \
  -F 'metadata={"category":"profile"}'

# Response
{
  "id": "3b9e2a7c-…",
  "bucketId": "8f0c6d1e-…",
  "path": "images/photo.jpg",
  "fileName": "photo.jpg",
  "mimeType": "image/jpeg",
  "size": 2048576,
  "checksum": "9e107d9d372bb6826bd81d3542a419d6",
  "metadata": { "category": "profile" },
  "uploadedBy": "u_4821",
  "uploadedAt": "2026-10-23T09:15:02.123Z",
  "createdAt": "2026-10-23T09:15:02.123Z",
  "updatedAt": "2026-10-23T09:15:02.123Z"
}
```

`mimeType` is read from the file's content. `uploadedBy` is the user in the token (`null` for server uploads without one). Fields that are empty are `null`.

#### List and get

```bash
# GET /api/v1/buckets/:bucketId/files?prefix=images/&limit=100&cursor=…
# → { "files": [ … ], "nextCursor": "…" }   (nextCursor is null on the last page; limit 1-1000, default 100)

# GET /api/v1/files/:fileId                       → the file
# GET /api/v1/buckets/:bucketId/files/<path>      → the file at that path
```

#### Download

```bash
# GET /api/v1/files/:fileId/download
curl -X GET "https://storage.abrova.ir/api/v1/files/FILE_ID/download" \
  -H "x-api-key: ab_live_xxx" \
  -H "x-user-token: $USER_TOKEN" \
  -o downloaded_file.jpg
```

This address needs the headers, so it can't be used as a plain `<img src>` or link.

#### Public link (public buckets)

```bash
# GET /api/v1/files/:fileId/url
curl "https://storage.abrova.ir/api/v1/files/FILE_ID/url" \
  -H "x-api-key: ab_live_xxx"

# Response (file in a public bucket; a private bucket answers 403)
{ "url": "https://storage.abrova.ir/public/<bucketId>/images/photo.jpg" }
```

The returned `url` needs no key, token or header: use it in `<img src>`, `Image.network` or a share link. Each path segment is percent-encoded. Add image options to the same URL for a resized or converted image (see Public image URLs below). Once a bucket is private, its `/public` links answer 404.

#### Signed download link

Needs `x-server-secret`.

```bash
# POST /api/v1/files/:fileId/signed-url   (expiresIn in seconds, max 86400, default 3600)
curl -X POST "https://storage.abrova.ir/api/v1/files/FILE_ID/signed-url" \
  -H "x-api-key: ab_live_xxx" \
  -H "x-server-secret: ab_srv_xxx" \
  -H "Content-Type: application/json" \
  -d '{"expiresIn": 600}'

# Response
{ "url": "https://…" }
```

#### Signed upload link

Needs `x-server-secret`. The bucket's allowed types apply to `contentType`.

```bash
# POST /api/v1/buckets/:bucketId/files/signed-upload-url   (expiresIn default 300, at most 900)
curl -X POST "https://storage.abrova.ir/api/v1/buckets/BUCKET_ID/files/signed-upload-url" \
  -H "x-api-key: ab_live_xxx" \
  -H "x-server-secret: ab_srv_xxx" \
  -H "Content-Type: application/json" \
  -d '{"path": "uploads/photo.jpg", "contentType": "image/jpeg", "expiresIn": 300}'

# Response
{ "url": "https://…", "uploadId": "…", "path": "uploads/photo.jpg", "expiresAt": "…", "maxSize": 10485760 }

# The client then uploads with the same Content-Type:
# curl -X PUT "$URL" -H "Content-Type: image/jpeg" --data-binary @photo.jpg
```

The file is registered when it is first read or listed; the bucket's size and type limits and your access rules are checked again against the real file, and a file that fails is deleted. To register it at once and get the file back, call `POST /api/v1/buckets/:bucketId/files/confirm-upload` with `{ "path": "uploads/photo.jpg" }` → `{ "id", "path", "size", "mimeType" }`.

#### Delete

```bash
# DELETE /api/v1/files/:fileId
curl -X DELETE "https://storage.abrova.ir/api/v1/files/FILE_ID" \
  -H "x-api-key: ab_live_xxx" \
  -H "x-user-token: $USER_TOKEN"

# Response
{ "success": true, "message": "File deleted" }

# DELETE /api/v1/buckets/:bucketId/files/<path>   → the same answer
# POST /api/v1/files/delete-many  body: { "ids": ["…", "…"] }  → { "deleted": 2 }
```

All follow the bucket's `delete` rules; with `x-server-secret` instead of a user token, rules are skipped.

<H2 id="transform-endpoint" step={4}>Transform Endpoint</H2>

```bash
# GET /api/v1/transform/:fileId
# Get a 200x200 thumbnail in WebP format
curl "https://storage.abrova.ir/api/v1/transform/FILE_ID?w=200&h=200&fit=cover&f=webp&q=80" \
  -H "x-api-key: ab_live_xxx" \
  -H "x-user-token: $USER_TOKEN" \
  -o thumb.webp

# Query Parameters
# w       - Width in pixels, 1-4096 (larger values are cut to 4096)
# h       - Height in pixels, 1-4096
# fit     - cover (default), contain, fill, inside, outside
# f       - jpeg (default), png, webp, avif
# q       - Quality 1-100 (default 80)
# blur    - Blur amount 0-20
# sharpen - Sharpen amount 0-10
# rotate  - Degrees (multiples of 90 recommended)

# GET /api/v1/transform/:fileId/metadata
# → { "width": 4032, "height": 3024, "format": "jpeg", "size": 2048576 }
```

Transforms follow the bucket's `read` rules and need the headers, so load them with a client that can send headers. Inputs: JPEG, PNG, WebP, GIF, AVIF, HEIC / HEIF, TIFF and SVG. For public files, use a public image URL (below) instead.

#### Public image URLs

```text
https://storage.abrova.ir/public/<bucketId>/<path>?w=600&f=webp
```

The file's public link plus any of the options above. No key or token: public buckets only. The same options always give the same image, in any order (`?w=300&f=webp` = `?f=webp&w=300&q=80`); other query parameters are ignored. One image keeps at most 50 different option sets. See [Image Transforms](/docs/storage/image-transforms).

#### Transform errors

<ConfigTable headers={['Status', 'code', 'Meaning']} rows={[
  ['400', 'invalid_transform', 'An option isn\'t allowed (the message names it).'],
  ['400', 'not_an_image', 'The file isn\'t an image.'],
  ['415', 'image_format_not_supported', 'The image format can\'t be resized (for example BMP, PSD, JPEG XL, RAW).'],
  ['413', 'image_too_large', 'The image has more than 50 megapixels.'],
  ['413', 'source_too_large', 'The image file is over 25 MB.'],
  ['422', 'image_damaged', 'The image is damaged or incomplete.'],
  ['403', 'plan_feature_locked', 'No transforms left: the free monthly transforms are used up and the wallet cannot pay for more.'],
  ['429', 'too_many_variants', 'Public image URLs: this image already has 50 sizes / formats. Use one you already use.'],
  ['503', 'transform_busy', 'Image processing is busy. Retry after the Retry-After header\'s seconds.'],
]} />

- Image transforms: https://abrova.ir/en/docs/storage/image-transforms

Transform images on the fly with resizing, format conversion, and quality optimization. The original file is never changed. Each size / format of an image is made once and kept: later requests for the same options are served from the cache and don't count as a new transform.

<Callout kind="note" title="Use WebP or AVIF">
Use WebP or AVIF formats for modern browsers to reduce file sizes by up to 30% compared to JPEG. Ask for them explicitly with `f=webp` or `f=avif`.
</Callout>

### Transform Parameters

<ConfigTable rows={[
  ['width (w)', 'Integer', '-', 'Target width in pixels, 1-4096 (larger values are cut to 4096)'],
  ['height (h)', 'Integer', '-', 'Target height in pixels, 1-4096'],
  ['fit', 'String', 'cover', 'Resize mode: cover, contain, fill, inside, outside'],
  ['format (f)', 'String', 'jpeg', 'Output format: jpeg, png, webp, avif'],
  ['quality (q)', 'Integer', '80', 'Compression quality, 1-100'],
  ['blur', 'Number', '-', 'Blur effect, 0-20'],
  ['sharpen', 'Number', '-', 'Sharpen effect, 0-10'],
  ['rotate', 'Integer', '-', 'Rotation in degrees (multiples of 90 recommended)'],
]} />

Any other value for `f` or `fit`, or `blur` / `sharpen` out of range, is refused with `invalid_transform`. The SDKs check the options before they build a URL.

#### Which images can be transformed

JPEG, PNG, WebP, GIF, AVIF, **HEIC / HEIF** (iPhone and Android camera photos), TIFF and SVG. For animated GIF and PNG, the first frame is used. The orientation a phone stores is applied, so portrait photos come out upright. Images up to 25 MB and 50 megapixels can be transformed.

### Showing a transformed image

#### Public buckets: a link with no headers

Add the options to the file's public link:

```text
https://storage.abrova.ir/public/<bucketId>/<path>?w=600&f=webp
```

It needs no key, token or header, so it goes straight into `<img src>`, `srcset`, CSS, e-mails or `Image.network(url)`. The SDKs build it for you with `getPublicUrl(fileId, …options)`, and `publicImageUrl(link, …options)` builds it from a public link you stored earlier, without a request:

```typescript
// Web (React Native and Node.js are the same)
import { publicImageUrl } from '@abrova/storage-web';

img.src = await storage.getPublicUrl(file.id, { width: 600, format: 'webp' });

const at = (width: number) => publicImageUrl(savedLink, { width, format: 'webp' });
img.srcset = `${at(600)} 600w, ${at(1200)} 1200w`;
```

```dart
// Flutter
final url = await storage.getPublicUrl(file.id,
    transforms: const ImageTransforms(width: 600, format: 'webp'));
Image.network(url);
```

- **Same options, same URL.** Options are read in any order with defaults applied, so `?w=300&f=webp` and `?f=webp&w=300&q=80` are the same image. Other query parameters are ignored.
- **Cached.** Browsers and other caches may keep an image for up to a day. When you replace a file's content, new requests get the new image; copies already cached can show the old one until they expire.
- **Use a few fixed sizes.** One image keeps at most 50 different option sets. A new set beyond that is refused with `too_many_variants` (429); the existing ones keep working. Pick a few sizes (for example 200, 600 and 1200 wide) instead of the exact size of every view.
- **Private buckets** have no public link: `getPublicUrl` fails with 403, and a `/public` link answers 404.

#### Private buckets: send the headers

`getTransformUrl()` returns `https://storage.abrova.ir/api/v1/transform/<fileId>?…`. That address needs the `x-api-key` and `x-user-token` headers and follows the bucket's `read` rules, so a plain `<img src>` or `Image.network(url)` without headers is refused. Load it with something that sends headers:

```dart
// Flutter: Image.network can send headers
Image.network(
  storage.getTransformUrl(fileId, transforms: ImageTransforms(width: 200, height: 200, fit: 'cover', format: 'webp')),
  headers: {'x-api-key': 'ab_live_xxxxxxxxxxxx', 'x-user-token': userToken},
);
```

```typescript
// Browser: fetch with headers, then show the bytes
const res = await fetch(storage.getTransformUrl(fileId, { width: 200, height: 200, fit: 'cover', format: 'webp' }), {
  headers: { 'x-api-key': 'ab_live_xxxxxxxxxxxx', 'x-user-token': userToken },
});
img.src = URL.createObjectURL(await res.blob());
```

React Native's `<Image source={{ uri, headers }}>`, and Coil or Glide on Android, can send the same headers. You can also `download()` the file, or show it from a signed link your server makes.

### Usage and billing

500 transforms are free every month; the price above that is set at launch and will be paid from your prepaid wallet. When the free transforms are used up and the wallet cannot pay for more, transform requests answer `plan_feature_locked` (403); the plain file and its public link always work. Transforms count each new size / format of an image once; showing it again doesn't count as a new transform. Bandwidth counts the bytes of the transformed image.

### Transform errors

When an image can't be made, the answer is JSON instead of an image, with `statusCode`, `code` and a `message` you can show to your users. The SDKs expose the codes as `StorageErrorCode` constants.

<ConfigTable headers={['Status', 'code', 'Meaning']} rows={[
  ['400', 'invalid_transform', 'An option isn\'t allowed (the message names it).'],
  ['400', 'not_an_image', 'The file isn\'t an image.'],
  ['415', 'image_format_not_supported', 'The image format can\'t be resized (for example BMP, ICO, PSD, JPEG 2000, JPEG XL, RAW / DNG).'],
  ['413', 'image_too_large', 'The image has more than 50 megapixels.'],
  ['413', 'source_too_large', 'The image file is over 25 MB.'],
  ['422', 'image_damaged', 'The image is damaged or incomplete (it may not have finished uploading).'],
  ['403', 'plan_feature_locked', 'No transforms left: the free monthly transforms are used up and the wallet cannot pay for more.'],
  ['429', 'too_many_variants', 'Public image URLs: this image already has 50 sizes / formats.'],
  ['503', 'transform_busy', 'Image processing is busy. Retry after the Retry-After header\'s seconds. An img element fires error: set its src again after a short wait.'],
]} />

### Common Use Cases

```text
// Avatar thumbnail (100x100, square crop)
?w=100&h=100&fit=cover&f=webp&q=80

// Responsive image (max 800px wide, maintain ratio)
?w=800&f=webp&q=85

// Low-quality placeholder (tiny, blurred - for lazy loading)
?w=20&blur=10&f=webp&q=30

// Product image (exact size, white background for contain)
?w=600&h=600&fit=contain&f=jpeg&q=90

// Gallery preview (medium size, optimized)
?w=400&h=300&fit=cover&f=webp&q=75

// Hero image (large, high quality)
?w=1920&h=1080&fit=cover&f=webp&q=90
```

### Fit Modes Explained

- `cover` — Resize to cover the target dimensions, cropping if necessary. Best for avatars and thumbnails.
- `contain` — Resize to fit within dimensions, preserving aspect ratio. May add padding.
- `fill` — Stretch to exactly match dimensions. May distort the image.
- `inside` — Resize to fit inside dimensions without upscaling.
- `outside` — Resize to cover dimensions without downscaling.

- Bucket policies: https://abrova.ir/en/docs/storage/bucket-policies

Define access rules for your buckets, similar to Firebase Storage Rules. Control who can read, write, delete and list files based on the signed-in user, paths, and file properties.

<Callout kind="warn" title="No rules = open to every signed-in user">
A bucket with no rules lets any signed-in user of your app read, upload, delete and list every file in it. Rules apply as soon as a bucket has any — there is no separate switch to turn them on. Requests carrying your server secret skip rules.
</Callout>

### Policy Rule Structure

```json
{
  "name": "Rule name (optional)",
  "action": "read" | "write" | "delete" | "list" | "*",
  "condition": {
    "authenticated": true,           // A verified user is acting
    "pathPattern": "users/{userId}/**",  // Path matching
    "matchUserId": true,             // {userId} must equal the acting user's id
    "maxSize": 5242880,              // Max file size in bytes
    "allowedMimeTypes": ["image/*"], // Allowed MIME types
    "validAfter": "2024-01-01",      // Time-based access
    "validBefore": "2024-12-31",
    "allowedIPs": ["203.0.113.7"]    // Exact addresses only (no CIDR ranges)
  },
  "effect": "allow" | "deny",
  "priority": 10               // Higher = evaluated first
}
```

How rules are evaluated:

- Rules from all of a bucket's policies are merged and sorted by `priority` (higher first; at the same priority, `deny` comes before `allow`).
- The first rule whose action and conditions all match decides: `allow` permits, `deny` blocks.
- If the bucket has rules and none match, the request is **denied**.
- `allowedIPs` matches exact addresses only; don't use it to identify end-user devices.

### Who the user is

`authenticated` and `{userId}` with `matchUserId` look at the acting user:

<ConfigTable headers={['Request', 'Acting user']} rows={[
  ['App request with a valid Abrova user token (x-user-token)', 'The token\'s user, verified by Abrova.'],
  ['App request with a bad or expired token', 'None: refused with 401 token_invalid / token_expired.'],
  ['App request without a token', 'None: refused with 401 token_required. The SDKs wait for a token instead of sending it.'],
  ['Server secret', 'Rules are skipped.'],
]} />

File requests from apps always need a signed user token (Storage SDK 0.2.1 or newer), so `users/{userId}/**` always means the verified user. See [Overview](/docs/storage/overview) for how to sign users in, and [Security](/docs/storage/security).

A request the rules refuse answers **403** with code `access_denied`.

### Path Patterns

Path patterns support wildcards similar to Firebase:

- `{userId}` — Captures a single segment; with `matchUserId: true` it must equal the acting user's id.
- `*` — Matches a single path segment.
- `**` — Matches multiple path segments.

```text
// Examples
"users/{userId}/**"     // Matches: users/123/photos/vacation/beach.jpg
"public/*"              // Matches: public/logo.png (not subdirectories)
"documents/**/*.pdf"    // Not supported - use allowedMimeTypes instead
```

### Pre-built Templates

Use these templates for common access patterns:

- `publicRead` — Any signed-in user can read and list; only authenticated users can write and delete.
- `private` — Only authenticated users can access (read/write/delete/list).
- `userFolders` — Authenticated users can read and list; they can only write and delete in their own folder (`users/{userId}/**`).
- `imagesOnly` — Authenticated users can upload JPEG, PNG, GIF or WebP up to 5 MB; read and list are open.
- `closed` — Server only: an explicit deny for every action from apps. Your server (server secret) still works.

```bash
// Apply a template using Node.js SDK
await storageServer.applyPolicyTemplate('my-bucket', 'userFolders');

// Or via API
curl -X POST "https://storage.abrova.ir/api/v1/buckets/bucket_xxx/policies/templates/apply" \
  -H "x-api-key: ab_live_xxx" \
  -H "x-server-secret: ab_srv_xxx" \
  -H "Content-Type: application/json" \
  -d '{"template": "userFolders", "name": "User folders policy"}'
```

Creating, changing and deleting rules and applying templates always need the server secret; with the API key alone the API answers 403 `server_secret_required`. A wrong rule is refused with 400 `invalid_rules` (the message names the first problem).

### Custom Policy Example

```typescript
// Create a custom policy for a social media app
await storageServer.createPolicy('user-uploads', [
  // Allow users to read their own files
  {
    name: 'Users can read own files',
    action: 'read',
    condition: {
      authenticated: true,
      pathPattern: 'users/{userId}/**',
      matchUserId: true,
    },
    effect: 'allow',
    priority: 20,
  },

  // Allow users to upload images to their folder (max 5MB)
  {
    name: 'Users can upload images',
    action: 'write',
    condition: {
      authenticated: true,
      pathPattern: 'users/{userId}/**',
      matchUserId: true,
      allowedMimeTypes: ['image/jpeg', 'image/png', 'image/webp'],
      maxSize: 5 * 1024 * 1024,
    },
    effect: 'allow',
    priority: 20,
  },

  // Allow users to delete their own files
  {
    name: 'Users can delete own files',
    action: 'delete',
    condition: {
      authenticated: true,
      pathPattern: 'users/{userId}/**',
      matchUserId: true,
    },
    effect: 'allow',
    priority: 20,
  },

  // Public folder is readable by everyone
  {
    name: 'Public folder is public',
    action: 'read',
    condition: {
      pathPattern: 'public/**',
    },
    effect: 'allow',
    priority: 10,
  },

  // Everything else is denied (the bucket has rules and none match)
]);
```

- Security best practices: https://abrova.ir/en/docs/storage/security

Keep your files and credentials secure with these AbrovaStorage best practices.

### Never Expose Server Secret

<Callout kind="note" title="Critical">
The `serverSecret` must never be included in client-side code, mobile apps, or frontend applications. Requests with it skip your access rules and can manage every bucket in the project.
</Callout>

#### Don't do this

```javascript
// In React/Vue/Angular component
const storage = new AbrovaStorage({
  apiKey: 'ab_live_xxx',
  serverSecret: 'ab_srv_xxx', // NEVER!
});
```

#### Do this

```javascript
// Call your backend API, which holds the server secret
const { uploadUrl } = await fetch(
  '/api/get-upload-url',
  { method: 'POST', body: JSON.stringify({ filename, contentType }) }
).then(r => r.json());
```

### Buckets and Rules Are Server-Only

The API key ships inside your app, so treat it as public. For every project:

- creating, updating and deleting buckets, creating, updating and deleting access rules, applying a rule template, and making signed download and upload links need the server secret; the API key alone (with or without a user token) gets **403** with code `server_secret_required`;
- uploading, reading, listing and deleting files (including `deleteMany`) and image transforms work with the API key plus a signed user token, and follow your access rules.

There is no setting to change this. Do bucket and rule work from your server (Node.js SDK or REST with the server secret) or in the Console.

### Write Access Rules

A bucket with **no access rules** lets any signed-in user of your app read, upload, delete and list every file in it. Add rules to every bucket an app can reach — see [Bucket Policies](/docs/storage/bucket-policies). For a bucket only your server should touch, apply the `closed` template: apps are denied everything, and your server (server secret) still works.

### Sign users in (one token for every Abrova product)

Every file request from an app needs a signed **Abrova user token**, and rules that use `{userId}` or `authenticated` see the user in it. A plain user id from the app is never trusted.

<Callout kind="note" title="Requires the Storage SDK 0.2.1 or newer">
Use Storage SDK 0.2.1 or newer in every app. An app that doesn't send a user token can't read or write files.
</Callout>

<ConfigTable headers={['Credential', 'Where it lives', 'What it proves']} rows={[
  ['API key (ab_live_…)', 'Inside your app. Public.', 'Which project the request belongs to.'],
  ['Server secret (ab_srv_…)', 'Your server only. Never in an app.', 'That a request comes from your backend.'],
  ['User token', 'Your app, one per signed-in user.', 'Which user is acting. This is the user access rules see.'],
]} />

Your backend mints the token with the server secret:

```typescript
// Node.js SDK
const { token, expiresAt } = await storage.createUserToken(session.userId); // optional 2nd arg: lifetime in seconds
```

```bash
# Any backend
curl -X POST https://auth.abrova.ir/users/token \
  -H "x-api-key: $ABROVA_API_KEY" \
  -H "x-server-secret: $ABROVA_SERVER_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"userId": "u_4821", "expiresIn": 3600}'

# → { "token": "eyJhbGciOi…", "userId": "u_4821", "expiresIn": 3600, "expiresAt": "…" }
```

It is the same token Abrova Sync, Chat, Push and A/B Testing accept; Abrova Auth's sign-in token is this same token too. The app hands it to the SDK through its token provider, and the SDK sends it as `x-user-token` and refreshes it when it expires — see the platform pages.

<Callout kind="note" title="Keep it on the device">
A token is valid until it expires, so store it with the user's session (Keychain, Keystore or secure storage) and reuse it across app launches. Storage has no revocation, so keep the lifetime short if a signed-out user must lose access quickly.
</Callout>

Without a token (no one signed in), the SDKs don't send file requests: they wait until your app signs a user in (`isAwaitingUserToken`). A request without a token gets **401** `token_required`; a bad or expired token gets **401** `token_invalid` / `token_expired`.

### Use Short-Lived Signed URLs

Set appropriate expiration times for signed URLs based on your use case:

- Upload URLs — 5 minutes by default, at most 15 minutes (a longer `expiresIn` is cut to 15 minutes).
- Download URLs (normal) — 1 hour.
- Download URLs (sensitive) — 5-15 minutes.
- Maximum for download URLs — 24 hours.

### Validate File Types and Sizes

```typescript
// Server-side validation before generating upload URL
app.post('/api/upload-url', async (req, res) => {
  const { filename, contentType, size } = req.body;

  // Validate file type
  const allowedTypes = ['image/jpeg', 'image/png', 'image/webp', 'application/pdf'];
  if (!allowedTypes.includes(contentType)) {
    return res.status(400).json({ error: 'File type not allowed' });
  }

  // Validate file size (10MB max)
  if (size > 10 * 1024 * 1024) {
    return res.status(400).json({ error: 'File too large' });
  }

  // Validate filename (prevent path traversal)
  if (filename.includes('..') || filename.includes('/')) {
    return res.status(400).json({ error: 'Invalid filename' });
  }

  // Signed upload URL: the bucket's allowed types apply to contentType
  const { url } = await storage.createSignedUploadUrl(
    'user-uploads',
    `uploads/${Date.now()}-${sanitize(filename)}`,
    { contentType, expiresIn: 300 }
  );

  res.json({ uploadUrl: url });
});
```

A file uploaded through a signed link is registered when it is first read or listed. Abrova Storage then checks the bucket's size limit and allowed types, and your access rules, again against the real file; a file that fails is deleted. Checking type and size on your server first still gives your users a clear answer before they upload.

#### Let the bucket check too

- **Allowed types and size.** Set them in Console › Storage › your bucket › Settings. The type is read from the file's content, not only from its name or declared type, and a refused upload gets 400 `type_not_allowed` or `file_too_large`.
- **Block executable files.** **Block executable files** is on for new buckets; turn it on in bucket Settings for older buckets that take user uploads. Executable files (by name or content, also inside ZIP files) are then refused with 400 `executable_blocked`.

### Serve Files Safely

Files are served with `X-Content-Type-Options: nosniff` and a sandbox content security policy, so an uploaded HTML or SVG file can't run scripts on an Abrova address. From a public link, images (except SVG), video, audio, PDF and plain text open in the browser; every other type, including HTML and SVG, is sent as a download.

### Environment Variables

```bash
# .env.local (never commit to git!)
ABROVA_STORAGE_API_KEY=ab_live_xxxxxxxxxxxx
ABROVA_STORAGE_SERVER_SECRET=ab_srv_xxxxxxxxxxxx

# Add to .gitignore
.env
.env.local
.env.*.local
```

<Callout kind="warn" title="Test vs live keys">
Use a separate project for development, so its data and usage stay apart from production. Each project has its own `ab_live_xxx` key.
</Callout>