# Abrova docs (fa)

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

## ابرووا تریس

- SDK فلاتر: https://abrova.ir/docs/trace/flutter-sdk

<BestPracticeList columns={2} items={[
  ['راه‌اندازی ساده', 'راه‌اندازی تنها با چند خط کد'],
  ['چندسکویی', 'روی وب، Android، iOS و افزونه‌های Chrome کار می‌کند'],
  ['ثبت خودکار خطا', 'خطاهای مدیریت‌نشده را خودکار می‌گیرد'],
  ['گزارش دستی خطا', 'ثبت خطاها و پیام‌های دلخواه'],
  ['تشخیص پلتفرم', 'پلتفرمی را که اپ روی آن اجرا می‌شود خودکار تشخیص می‌دهد'],
  ['قابل تنظیم', 'گزینه‌های پیکربندی انعطاف‌پذیر'],
  ['زمینه‌ی کامل', 'افزودن داده‌ی دلخواه، تگ و اطلاعات کاربر به خطاها'],
  ['Breadcrumbها', 'ثبت کارهای کاربر و رویدادهای پیش از خطا'],
  ['لاگ', 'دریافت لاگ ساخت‌یافته با ارسال دسته‌ای و سطح‌بندی'],
  ['پایش عملکرد', 'اندازه‌گیری درخواست‌های HTTP و عملیات دلخواه'],
  ['تشخیص کرش نیتیو', 'کرش‌های نیتیو را در iOS و Android ثبت می‌کند و در اجرای بعدی اپ گزارش می‌دهد'],
]} />

از دستیار هوش مصنوعی استفاده می‌کنید؟ از دکمه‌ی **Copy page for AI** در بالای همین صفحه استفاده کنید و متن را در گفت‌وگو جای‌گذاری کنید. [دستیارهای هوش مصنوعی](/docs/trace/ai-assistants) را ببینید.

### پلتفرم‌های پشتیبانی‌شده

- **Flutter Web** — پشتیبانی کامل همراه با گرفتن خطاهای JS
- **افزونه‌ی Chrome** — بهینه‌شده برای محیط افزونه
- **Android** — خطاهای Dart به‌علاوه‌ی ثبت کرش نیتیو (SDK نیتیو ابرووا تریس همراه پکیج است)
- **iOS** — خطاهای Dart به‌علاوه‌ی ثبت کرش نیتیو (SDK نیتیو ابرووا تریس همراه پکیج است)
- **دسکتاپ** — Windows، macOS و Linux (فقط خطاهای Dart؛ کرش نیتیو ثبت نمی‌شود)

<H2 id="installation" step={1}>نصب</H2>

پکیج از Abrova Center می‌آید، پس به هیچ مخزن پکیج دیگری نیاز ندارید. دو مرحله دارد: پروژه را به مخزن ابرووا وصل کنید و بعد نصب کنید.

**۱. پکیج را از مخزن ابرووا اضافه کنید** در `pubspec.yaml`:

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

**۲. منبع SDKهای نیتیو را اضافه کنید.** این پلاگین برای ثبت کرش از SDKهای نیتیو Android و iOS استفاده می‌کند.

در Android، مخزن Maven ابرووا را در `android/build.gradle` اضافه کنید (یا در `android/settings.gradle`، هر جا که پروژه‌ی شما مخزن‌ها را فهرست می‌کند):

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

در iOS، این خط را داخل target اپ در `ios/Podfile` اضافه کنید:

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

سپس نصب کنید:

```bash
flutter pub get
```

**پیش‌نیازها**: Dart SDK نسخه‌ی 3.8.1 یا بالاتر. Android: نسخه‌ی API 19 (Android 4.4) یا بالاتر. iOS: نسخه‌ی 12.0 یا بالاتر، ساخته‌شده با Xcode 15.3+ (Swift 5.10). در وب، خطاهای Dart، پیام‌ها، لاگ‌ها و عملکرد کار می‌کنند؛ ثبت کرش نیتیو فقط در Android و iOS است.

<Callout kind="note" title="کدام کلید؟">
  از کلید عمومی پروژه، یعنی `ab_live_…`، در کنسول ابرووا استفاده کنید. قرار دادن آن داخل اپ امن است. هرگز کلید سرور `ab_srv_…` را در اپ قرار ندهید.
</Callout>

<H2 id="quick-start" step={2}>شروع سریع</H2>

#### راه‌اندازی پایه

```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());
}
```

#### روش پیشنهادی: راه‌اندازی با Zone (گرفتن بهتر خطاها)

<Callout kind="note" title="پیشنهادی">
  با initWithZone خطاهای async هم گرفته می‌شوند که در غیر این صورت از دست می‌روند. این روش پیشنهادی برای اپ‌های production است.
</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}>ثبت خطاها</H2>

#### ثبت Exceptionها

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

#### ثبت پیام‌ها

```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="پیام‌ها کجا نمایش داده می‌شوند">
پیام‌ها در کنسول، در بخش **ابرووا تریس › پیام‌ها**، همراه با سطح، پلتفرم، داده‌های اضافه و breadcrumbها نمایش داده می‌شوند. پیام‌ها هیچ‌وقت مشکل (issue) نمی‌سازند. سطح‌ها: `MessageLevel.debug`، `info` (پیش‌فرض)، `warning` و `error`. پیام‌ها را برای چیزهایی به کار ببرید که اپ عمداً گزارش می‌دهد («پرداخت شروع شد»، «همگام‌سازی تمام شد»)؛ برای داده‌های عیب‌یابی پرحجم از لاگ‌ها استفاده کنید.
</Callout>

#### زمینه‌ی دلخواه برای خطا

```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}>اطلاعات کاربر</H2>

خطاها و لاگ‌ها را به کاربر مشخصی نسبت دهید و metadata دلخواه اضافه کنید. اگر از [Abrova Auth](/docs/auth/flutter) استفاده می‌کنید، شناسه‌ی کاربرِ واردشده را بدهید.

#### تعیین شناسه‌ی کاربر

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

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

#### داده‌ی اضافه‌ی دلخواه

```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();
```

#### تگ‌ها

```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}>Breadcrumbها</H2>

Breadcrumbها کارهای کاربر و رویدادهای منتهی به خطا را ثبت می‌کنند تا بفهمید پیش از کرش چه اتفاقی افتاده است.

```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}>ثبت خودکار لمس‌ها (Breadcrumbهای ژست)</H2>

هر لمس کاربر را خودکار به‌صورت breadcrumb ثبت کنید. این قابلیت روی همه‌ی targetهای Flutter کار می‌کند — وب، Android، iOS، macOS، Windows و Linux — چون به pointer router خود فریم‌ورک وصل می‌شود، نه به کد پلتفرم.

وقتی خطایی رخ می‌دهد، جزئیات مشکل نشان می‌دهد کاربر درست پیش از آن روی کدام ویجت زده است — معمولاً همین برای بازتولید باگ کافی است، حتی بدون stack trace کامل. این مخصوصاً در Flutter Web مفید است، چون به‌خاطر inline شدن کد توسط dart2js ممکن است stack traceهای production فقط تا حدی symbolicate شوند.

#### فعال‌سازی

یک بار بعد از init و بعد از `WidgetsFlutterBinding.ensureInitialized()` صدا بزنید. این متد idempotent است — چند بار صدا زدنش مشکلی ندارد.

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

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

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

#### چه چیزی ثبت می‌شود

هر لمس روی یک ویجت تعاملیِ شناخته‌شده، breadcrumbی مثل این می‌سازد:

```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 }
  }
}
```

فیلد `route` وقتی پر می‌شود که `AbrovaTraceNavigatorObserver()` را به `navigatorObservers` اپ اضافه کنید (این observer breadcrumbهای جابه‌جایی بین صفحه‌ها را هم خودکار ثبت می‌کند).

#### ویجت‌های شناخته‌شده

ردیاب این نوع ویجت‌ها را بدون تنظیم اضافه تشخیص می‌دهد (نوع‌های مشخص‌تر اولویت دارند):

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

#### نکته: به ویجت‌های مهم ValueKey بدهید

Breadcrumb برچسب را به این ترتیب پیدا می‌کند: فرزند `Text` ← `Semantics.label` ← `Tooltip.message` ← `Icon.semanticLabel`.

برای ویجت‌های بدون متن (مثل `IconButton`) یک `ValueKey` اضافه کنید تا بتوانید آن را در کدتان جست‌وجو کنید:

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

#### غیرفعال‌سازی

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

<Callout kind="note" title="حریم خصوصی">
  ردیاب برچسب قابل مشاهده‌ی ویجت را ثبت می‌کند — معمولاً متن دکمه‌ای مثل «Pay» یا «Add to Cart». مقدار فیلدهای فرم، محتوای text field یا هر چیزی که کاربر وارد کرده ثبت نمی‌شود. `ValueKey` علاوه بر برچسب گزارش می‌شود، نه به‌جای آن؛ پس متن حساس را در برچسب ویجت‌های قابل لمس نگذارید.
</Callout>

<H2 id="logging" step={7}>لاگ</H2>

دریافت لاگ ساخت‌یافته با ارسال دسته‌ای خودکار و آگاه از چرخه‌ی حیات اپ موبایل. یک بار فعالش کنید و بعد از هر جای اپ از متدهای سطح‌بندی استفاده کنید:

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

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

برای جزئیات کامل — ارسال دسته‌ای، سطح‌های لاگ، ارسال در پس‌زمینه، flush دستی و پیکربندی — صفحه‌ی [لاگ در Flutter SDK](/docs/trace/flutter-logging) را ببینید.

<H2 id="performance-tracking" step={8}>پایش عملکرد</H2>

زمان پاسخ درخواست‌های HTTP و عملیات دلخواه را برای APM اندازه بگیرید.

#### کلاینت HTTP خودکار

```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()` همان گزینه‌های `PerformanceHttpClient` (پایین‌تر) را می‌گیرد و کلید API، آدرس API، environment، release و پلتفرم را از پیکربندی پر می‌کند: `inner`، `addBreadcrumbs` (پیش‌فرض `true`)، `excludedHosts` و `minDurationMs` (پیش‌فرض `0`).

#### PerformanceHttpClient

کلاس `PerformanceHttpClient` یک `http.BaseClient` (از `package:http`) است که زمان هر درخواست را اندازه می‌گیرد و آن را به‌صورت یک span از نوع `http` گزارش می‌دهد. وقتی می‌خواهید یک کلاینت موجود را بپوشانید یا خودتان آن را بسازید، مستقیم از آن استفاده کنید:

```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();
```

Spanها بافر می‌شوند و در دسته‌های ۱۰تایی یا هر ۱۰ ثانیه ارسال می‌شوند. درخواست‌ها به hostهای ابرووا هیچ‌وقت اندازه‌گیری نمی‌شوند. در آدرس breadcrumbها، پارامترهای حساس query (token، password، api_key و …) با `[REDACTED]` جایگزین می‌شوند. Spanها در بخش **ابرووا تریس › عملکرد** نمایش داده می‌شوند.

#### اندازه‌گیری عملیات دلخواه

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

#### گزارش دستی span

```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}>استفاده بر اساس پلتفرم</H2>

#### افزونه‌ی Chrome

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

  runApp(MyExtensionApp());
}
```

#### اپ موبایل

```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());
}
```

#### اپ وب

```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}>تشخیص کرش</H2>

ابرووا تریس برای هر اپ Flutter، فارغ از کتابخانه‌ها یا کد نیتیوی که استفاده می‌کنید، تشخیص کامل خطا فراهم می‌کند.

- **Exceptionهای Dart** — به‌صورت لحظه‌ای ثبت می‌شوند
- **خطاهای async** — به‌صورت لحظه‌ای ثبت می‌شوند (با initWithZone)
- **Exceptionهای پلتفرم** — به‌صورت لحظه‌ای ثبت می‌شوند
- **کرش‌های نیتیو** — فقط در iOS و Android؛ در اجرای بعدی اپ گزارش می‌شوند

#### تشخیص کرش نیتیو چطور کار می‌کند

این پلاگین SDKهای نیتیو ابرووا تریس را برای iOS و Android همراه خود دارد و آن‌ها را هنگام `init()` / `initWithZone()` راه‌اندازی می‌کند:

1. **iOS** — کتابخانه‌ی PLCrashReporter کرش‌های ناشی از signal و Mach exception را روی دیسک ذخیره می‌کند
2. **Android** — یک handler برای exceptionهای مدیریت‌نشده، به‌علاوه‌ی `ApplicationExitInfo` (Android 11 / API 30+) برای کرش‌های نیتیو و ANRها
3. در اجرای بعدی، SDK نیتیو گزارش ذخیره‌شده را می‌خواند و آن را به‌صورت یک مشکل به ابرووا تریس می‌فرستد

به کد اضافه‌ای نیاز نیست. کرش‌ها در اجرای *بعدی* ارسال می‌شوند، پس کرش بعد از این‌که کاربر اپ را دوباره باز کند ظاهر می‌شود.

<Callout kind="note" title="خاموش کردن">
  متد `AbrovaTrace.close()` لاگ‌های در صف را ارسال می‌کند و SDK را آزاد می‌کند. برای تشخیص کرش لازم نیست. بعد از `close()`، فراخوانی‌هایی مثل `captureException()` خطا می‌دهند تا وقتی که دوباره `init()` را صدا بزنید؛ پس فقط وقتی صدایش بزنید که اپ واقعاً در حال بسته شدن است.
</Callout>

<H2 id="configuration-options" step={11}>گزینه‌های پیکربندی</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', 'بله', 'کلید API پروژه'],
  ['environment', 'String', 'خیر', 'نام محیط (پیش‌فرض: "production")'],
  ['release', 'String', 'خیر', 'شناسه‌ی نسخه‌ی اپ'],
  ['captureUncaughtErrors', 'bool', 'خیر', 'گرفتن خودکار خطاهای مدیریت‌نشده (پیش‌فرض: true)'],
  ['enabled', 'bool', 'خیر', 'فعال/غیرفعال کردن SDK (پیش‌فرض: true)'],
  ['debug', 'bool', 'خیر', 'فعال کردن لاگ‌های debug (پیش‌فرض: false)'],
  ['timeout', 'int', 'خیر', 'مهلت درخواست HTTP بر حسب ثانیه (پیش‌فرض: 30)'],
  ['sampleRate', 'double', 'خیر', 'نرخ نمونه‌برداری ثبت خطا بین 0.0 تا 1.0 (پیش‌فرض: 1.0)'],
  ['maxBreadcrumbs', 'int', 'خیر', 'حداکثر تعداد breadcrumbهای نگه‌داشته‌شده (پیش‌فرض: 20)'],
  ['enableOfflineStorage', 'bool', 'خیر', 'خطاهایی را که به‌خاطر آفلاین بودن دستگاه ارسال نمی‌شوند نگه می‌دارد و بعداً می‌فرستد (پیش‌فرض: true؛ نه در وب). بخش «ذخیره‌سازی آفلاین» در پایین را ببینید'],
  ['collectDeviceInfo', 'bool', 'خیر', 'افزودن اطلاعات دستگاه، سیستم‌عامل و اپ به خطاها و پیام‌ها (پیش‌فرض: true)'],
  ['apiUrl', 'String', 'خیر', 'تغییر آدرس API (پیش‌فرض: https://trace.abrova.ir)'],
  ['logHandler', 'AbrovaTraceLogCallback', 'خیر', 'دریافت خطوط لاگ داخلی SDK (level، message، error، stackTrace)'],
]} />

#### ذخیره‌سازی آفلاین

وقتی `enableOfflineStorage` روشن باشد (پیش‌فرض)، خطاهایی که به‌خاطر آفلاین بودن دستگاه ارسال نمی‌شوند روی دستگاه نگه داشته می‌شوند و بعداً ارسال می‌شوند. فقط خطاها نگه داشته می‌شوند — پیام‌ها، لاگ‌ها و داده‌های عملکرد روی دیسک ذخیره نمی‌شوند.

- **خطاهای نیتیو (Android، iOS)** — این گزینه به SDKهای نیتیو همراه پکیج داده می‌شود که تا ۱۰۰ خطای ارسال‌نشده را نگه می‌دارند و بعداً می‌فرستند. به نسخه‌ی 0.2.5 یا بالاتر نیاز دارد.
- **خطاهای Dart** — وقتی ارسال با خطای شبکه یا timeout شکست بخورد، خطا در یک فایل ذخیره می‌شود (تا ۱۰۰ مورد؛ قدیمی‌ترها اول حذف می‌شوند) و دفعه‌ی بعد که اپ اجرا شود دوباره ارسال می‌شود؛ هم با `AbrovaTrace.init()` و هم با `AbrovaTrace.initWithZone()` (برای `initWithZone()` نسخه‌ی 0.2.5 یا بالاتر لازم است). خطای ذخیره‌شده‌ای که سرور برای همیشه رد کند، به‌جای تلاش دوباره در هر اجرا، حذف می‌شود؛ اما اگر سرور بخواهد بعداً دوباره تلاش شود (HTTP 408، 429) یا خودش مشکل داشته باشد (5xx)، نگه داشته می‌شود.
- **وب** — چیزی ذخیره نمی‌شود.

پیش از نسخه‌ی 0.2.6، SDK ممکن بود هنگام شروع، وقتی از `initWithZone()` همراه با `WidgetsFlutterBinding.ensureInitialized()` داخل تابع اپ استفاده می‌کردید، پیام `AbrovaTrace: Failed to initialize offline storage: Binding has not yet been initialized` را چاپ کند. این پیام بی‌خطر بود و نسخه‌ی 0.2.6 دیگر آن را چاپ نمی‌کند: ذخیره‌سازی آفلاین بعد از شروع اپ خودش راه می‌افتد.

<H2 id="error-information-captured" step={12}>اطلاعاتی که همراه خطا ثبت می‌شود</H2>

SDK این اطلاعات را خودکار همراه هر خطا ثبت می‌کند:

- **پیام خطا** — پیام exception یا پیام دلخواه
- **Stack trace** — stack trace کامل برای عیب‌یابی
- **پلتفرم** — پلتفرم تشخیص‌داده‌شده (flutter_web، flutter_android و …)
- **محیط** — نام محیط (production، development و …)
- **Release** — شناسه‌ی نسخه/release اپ
- **زمان** — زمان وقوع خطا
- **شناسه‌ی کاربر، شناسه‌ی نشست، extraها، تگ‌ها و breadcrumbها** — هر چیزی که روی SDK تنظیم کرده‌اید
- **اطلاعات دستگاه** — مدل دستگاه، سیستم‌عامل و نسخه‌ی آن، نسخه و build اپ (وقتی `collectDeviceInfo` روشن است؛ در وب فقط locale و منطقه‌ی زمانی)
- **User Agent** — نسخه‌ی SDK، پلتفرم و release (در وب، user agent مرورگر)
- **URL** — آدرس صفحه‌ی فعلی (فقط وب)

### نمونه‌ی کامل

```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'),
        ),
      ),
    );
  }
}
```

### توصیه‌ها

<BestPracticeList items={[
  ['زود راه‌اندازی کنید', 'ابرووا تریس را پیش از runApp() راه‌اندازی کنید تا همه‌ی خطاها از لحظه‌ی شروع اپ گرفته شوند'],
  ['از initWithZone استفاده کنید', 'در اپ‌های production برای گرفتن بهتر خطاهای async از initWithZone استفاده کنید'],
  ['close() را فقط هنگام بسته شدن صدا بزنید', 'متد close() لاگ‌ها را ارسال و SDK را خاموش می‌کند؛ تشخیص کرش نیتیو به آن وابسته نیست'],
  ['شناسه‌ی کاربر را بعد از ورود تنظیم کنید', 'بعد از ورود، setUserId() را صدا بزنید تا خطاها به کاربران نسبت داده شوند'],
  ['Breadcrumb اضافه کنید', 'برای کارهای مهم کاربر (خرید، جابه‌جایی بین صفحه‌ها، ارسال فرم) breadcrumb اضافه کنید'],
  ['Breadcrumbهای ژست را فعال کنید', 'برای ثبت خودکار لمس‌ها enableGestureBreadcrumbs() را صدا بزنید. در Flutter Web که stack traceها ممکن است ناقص باشند، این کار حیاتی است'],
  ['به ویجت‌های مهم ValueKey بدهید', 'دکمه‌های پرداخت، فیلدهای پرداخت و کارهای کلیدی را با ValueKey مشخص کنید تا در breadcrumbهای لمس قابل شناسایی باشند'],
  ['برای فیلتر کردن از تگ استفاده کنید', 'تگ‌هایی مثل team، module یا feature تنظیم کنید تا خطاها را در داشبورد راحت فیلتر کنید'],
  ['لاگ را زود فعال کنید', 'لاگ را بلافاصله بعد از init() فعال کنید تا همه‌ی رویدادها از شروع اپ ثبت شوند'],
  ['محیط‌ها را جدا کنید', 'با تنظیم environment، خطاهای production، staging و development را از هم جدا کنید'],
  ['حالت debug را در توسعه روشن کنید', 'در زمان توسعه debug: true را تنظیم کنید تا لاگ‌های SDK را ببینید و درستی یکپارچگی را بررسی کنید'],
]} />

- SDK نود: https://abrova.ir/docs/trace/nodejs-sdk

<BestPracticeList columns={2} items={[
  ['ردیابی خطای سمت سرور', 'پایش کامل خطاها در برنامه‌های Node.js'],
  ['ثبت خودکار خطا', 'exceptionهای مدیریت‌نشده و promiseهای rejectشده‌ی بی‌پاسخ را می‌گیرد'],
  ['Middleware برای Express.js', 'middleware داخلی برای مدیریت درخواست‌ها و خطاها در Express.js'],
  ['Breadcrumb', 'رویدادهای پیش از خطا را برای درک بهتر شرایط ثبت می‌کند'],
  ['Context محدود', 'با withScope برای یک بلوک کد به‌طور موقت context تعیین کنید'],
  ['اطلاعات کاربر', 'خطاها را به اطلاعات کاربر مرتبط کنید'],
  ['فیلتر کردن خطا', 'با beforeSend، ignoredExceptions و ignoredPaths رویدادها را فیلتر یا اصلاح کنید'],
  ['پشتیبانی از TypeScript', 'تعریف‌های کامل TypeScript همراه بسته است'],
]} />

<H2 id="installation" step={1}>نصب</H2>

بسته‌ها از Abrova Center نصب می‌شوند. دو مرحله دارد:

**۱. رجیستری ابرووا را اضافه کنید** به فایل `.npmrc` در ریشه‌ی پروژه (npm، yarn و pnpm همگی آن را می‌خوانند):

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

**۲. بسته را نصب کنید:**

```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}>شروع سریع</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}>ثبت خطاها</H2>

#### ثبت exceptionها

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

#### ثبت پیام‌ها

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

<Callout kind="note" title="پیام‌ها کجا نمایش داده می‌شوند">
پیام‌ها در کنسول، در بخش **ابرووا تریس › پیام‌ها** همراه با سطح، پلتفرم، داده‌های اضافه و breadcrumbها نمایش داده می‌شوند. پیام هیچ‌وقت مشکل (issue) نمی‌سازد. سطح `'warn'` به‌صورت `warning`، سطح `'fatal'` به‌صورت `error` و سطح `'trace'` به‌صورت `debug` فرستاده می‌شود؛ هر مقدار دیگری `info` می‌شود. پیام را برای چیزهایی به کار ببرید که برنامه عمداً گزارش می‌دهد («checkout شروع شد»، «همگام‌سازی تمام شد»)؛ برای عیب‌یابی پرحجم از Logs استفاده کنید.
</Callout>

<H2 id="breadcrumbs" step={4}>Breadcrumbها</H2>

Breadcrumbها رویدادهای پیش از خطا را ثبت می‌کنند تا بفهمید قبل از وقوع خطا چه اتفاقی افتاده است.

#### Breadcrumb دستی

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

#### توابع کمکی Breadcrumb

```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}>اطلاعات کاربر</H2>

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

<H2 id="scoped-context" step={6}>Context محدود به یک بلوک</H2>

با context محدود می‌توانید کاربر و مقادیر اضافه را فقط برای یک بلوک کد همگام (synchronous) تعیین کنید. وقتی callback برمی‌گردد، کاربر و مقادیر اضافه به حالت قبل برمی‌گردند؛ breadcrumbهایی که داخل بلوک اضافه شده‌اند باقی می‌مانند.

```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</H2>

middleware داخلی برای ردیابی خودکار درخواست‌ها و مدیریت خطا در برنامه‌های Express.js.

```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="مهم: جای error handler">
  middleware مدیریت خطا باید بعد از همه‌ی routeها اضافه شود. Express لازم می‌داند که middlewareهای مدیریت خطا آخر از همه تعریف شوند. پیش از `AbrovaTrace.expressMiddleware()` تابع `AbrovaTrace.init()` را صدا بزنید: middlewareی که پیش از `init()` ساخته شود هیچ کاری نمی‌کند.
</Callout>

خطاهایی که `errorHandler()` گزارش می‌دهد شامل متد درخواست، URL، path، route منطبق (مثلاً `/api/users/:id`)، پارامترهای query و route، user agent، آدرس IP و وضعیت پاسخ هستند (اگر `err.status` / `err.statusCode` در محدوده‌ی 4xx یا 5xx باشد همان، وگرنه 500). headerها و body درخواست هرگز فرستاده نمی‌شوند. پارامترهای query و route که نامشان حساس به نظر برسد (password، token، secret، auth، API key، session، cookie، signature، OTP، code) به‌صورت `[REDACTED]` فرستاده می‌شوند. همین قاعده برای آدرس درخواستی که همراه خطاها و breadcrumbها فرستاده می‌شود هم برقرار است: مقدار پارامترهای query حساس در آن با `[REDACTED]` جایگزین می‌شود (مثلاً `/reset?token=[REDACTED]&page=2`)، اما نام پارامترها و بقیه‌ی مقادیر حفظ می‌شوند (از نسخه‌ی 0.2.3).

<H2 id="database-query-tracking" step={8}>ردیابی کوئری‌های پایگاه داده</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}>فیلتر کردن خطاها</H2>

با hook به نام beforeSend می‌توانید رویدادها را پیش از ارسال به ابرووا تریس فیلتر یا اصلاح کنید. این hook برای exceptionها و رویدادهای `captureMessage()` اجرا می‌شود؛ برای حذف یک رویداد `null` برگردانید. برای نادیده گرفتن کامل یک کلاس exception یا یک path درخواست، به‌جای آن از گزینه‌های `ignoredExceptions` و `ignoredPaths` استفاده کنید.

```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}>خاموش شدن تمیز</H2>

خطاها، پیام‌ها، لاگ‌ها و spanهای عملکرد در پس‌زمینه فرستاده می‌شوند. تابع `flush()` هر چیزی را که هنوز در صف است می‌فرستد؛ پس پیش از پایان پروسه صدایش بزنید: قبل از `process.exit()`، در پایان handler یک تابع serverless و در handlerهای خاموش شدن.

```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)` یک timeout بر حسب میلی‌ثانیه می‌گیرد (پیش‌فرض: 5000) و یک `Promise<boolean>` برمی‌گرداند: اگر ارسال در مهلت تمام شود `true` و اگر مهلت زودتر تمام شود `false`. این Promise هیچ‌وقت reject نمی‌شود. `close()` هم یک Promise برمی‌گرداند؛ لاگ‌ها و spanهای عملکردِ در بافر را می‌فرستد، اما منتظر خطاها و پیام‌هایی که هنوز در حال ارسال‌اند نمی‌ماند؛ پس اول `flush()` را صدا بزنید. بعد از `close()`، پیش از استفاده‌ی دوباره از SDK باید `init()` را دوباره صدا بزنید.

در یک تابع serverless، پیش از برگشتن handler عمل flush را انجام دهید:

```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 mapها</H2>

اگر از TypeScript، bundlerها (webpack، esbuild) یا Babel استفاده می‌کنید، برای stack trace دقیق source mapها را فعال کنید:

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

یا از داخل کد برنامه:

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

<H2 id="logging" step={12}>لاگ‌گیری</H2>

لاگ ساختاریافته‌ی سمت سرور، به‌صورت دسته‌ای و با backoff نمایی و بدون هیچ وابستگی. لاگ‌ها به **ابرووا تریس › Logs** می‌روند و از `captureMessage()` (بخش پیام‌ها) جدا هستند. بعد از `init()`، یک بار لاگ‌گیری را فعال کنید و از هر جای برنامه لاگ بنویسید:

```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' });
```

برای جزئیات کامل این مسیر — سطح‌های لاگ، یکپارچگی با Express، ارسال دسته‌ای و خاموش شدن تمیز — صفحه‌ی [لاگ‌گیری در SDK برای Node.js](/docs/trace/nodejs-logging) را ببینید.

<H2 id="configuration-options" step={13}>گزینه‌های پیکربندی</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', 'بله', 'کلید API پروژه (ab_live_xxx)'],
  ['serverSecret', 'string', 'بله', 'کلید سرور (ab_srv_xxx)؛ فقط روی سرور نگهش دارید'],
  ['environment', 'string', 'خیر', 'نام محیط (پیش‌فرض: NODE_ENV یا "development")'],
  ['release', 'string', 'خیر', 'نسخه‌ی برنامه (پیش‌فرض: npm_package_version یا "1.0.0")'],
  ['enabled', 'boolean', 'خیر', 'روشن/خاموش کردن ردیابی (پیش‌فرض: true)'],
  ['debug', 'boolean', 'خیر', 'فعال کردن لاگ عیب‌یابی (پیش‌فرض: false)'],
  ['timeout', 'number', 'خیر', 'مهلت HTTP بر حسب میلی‌ثانیه، 1000 تا 30000 (پیش‌فرض: 5000)'],
  ['captureUncaughtExceptions', 'boolean', 'خیر', 'ثبت خودکار exceptionهای مدیریت‌نشده (پیش‌فرض: true)'],
  ['captureUnhandledRejections', 'boolean', 'خیر', 'ثبت خودکار rejectionهای مدیریت‌نشده (پیش‌فرض: true)'],
  ['maxBreadcrumbs', 'number', 'خیر', 'حداکثر تعداد breadcrumbهای نگه‌داشته‌شده، تا ۱۰۰ (پیش‌فرض: 50). ۱۰ مورد آخر همراه هر رویداد فرستاده می‌شوند'],
  ['sampleRate', 'number', 'خیر', 'سهم رویدادهای captureException() و captureMessage() که فرستاده می‌شوند، 0.0 تا 1.0 (پیش‌فرض: 1.0)'],
  ['ignoredExceptions', 'array', 'خیر', 'exceptionهایی که captureException() و error handler مربوط به Express گزارش نمی‌کنند: یک کلاس خطا (با instanceof مقایسه می‌شود)، رشته‌ای برابر با error.name، یا یک RegExp که روی error.name آزموده می‌شود. exceptionهای مدیریت‌نشده و rejectionهای مدیریت‌نشده همیشه گزارش می‌شوند'],
  ['ignoredPaths', 'array', 'خیر', 'pathهای درخواستی که middleware مربوط به Express از آن‌ها می‌گذرد: glob، path دقیق یا RegExp'],
  ['beforeSend', 'function', 'خیر', 'hook برای فیلتر یا اصلاح خطاها و پیام‌ها پیش از ارسال؛ برای حذف، null برگردانید'],
]} />

### آمار SDK

```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

SDK تعریف‌های کامل TypeScript را همراه دارد. هر typeی را که لازم دارید import کنید:

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

### پیش‌نیازها

- **Node.js** — >= 14.0.0
- **Express (اختیاری)** — >= 4.0.0

### مرجع API

#### AbrovaTrace

- `init(config)` — راه‌اندازی SDK
- `captureException(error, options?)` — ثبت یک خطا
- `captureMessage(message, options?)` — ارسال پیام به ابرووا تریس › پیام‌ها (`options`: `level`، `extra`، `tags`)
- `addBreadcrumb(breadcrumb)` — افزودن یک breadcrumb
- `setUser(user)` — تعیین اطلاعات کاربر
- `setRequestContext(context)` — تعیین context درخواست که به رویدادهای ثبت‌شده پیوست می‌شود
- `withScope(callback)` — اجرای کد با scope جداگانه
- `expressMiddleware()` — گرفتن middleware برای Express.js
- `flush(timeout?)` — ارسال خطاها، پیام‌ها، لاگ‌ها و spanهای عملکرد در صف؛ `timeout` بر حسب میلی‌ثانیه (پیش‌فرض: 5000). خروجی `Promise<boolean>` است: اگر مهلت زودتر تمام شود `false`
- `close()` — ارسال لاگ‌ها و spanهای عملکرد و سپس پاک‌سازی (یک Promise برمی‌گرداند)
- `getStats()` — گرفتن آمار SDK
- `enableLogging(options?)`، `log()`، `trace()`، `logDebug()`، `info()`، `warn()`، `logError()`، `fatal()`، `flushLogs()` — لاگ‌گیری (صفحه‌ی [لاگ‌گیری در SDK برای Node.js](/docs/trace/nodejs-logging) را ببینید)
- `trackOperation(name, fn, options?)`، `reportPerformanceSpan(span)`، `reportPerformanceSpanBatch(spans)`، `flushPerformance()` — spanهای عملکرد

#### توابع کمکی Breadcrumb

- `Breadcrumb.http(method, url, status?, duration?)` — breadcrumb برای درخواست HTTP
- `Breadcrumb.database(query, duration, error?)` — breadcrumb برای کوئری پایگاه داده
- `Breadcrumb.user(action, data?)` — breadcrumb برای کار کاربر
- `Breadcrumb.console(level, message, ...args)` — breadcrumb برای خروجی console
- `Breadcrumb.navigation(from, to, method?)` — breadcrumb برای جابه‌جایی بین صفحه‌ها
- `Breadcrumb.custom(message, category, data?)` — breadcrumb با دسته‌بندی دلخواه

#### Middleware برای Express

- `requestHandler()` — middleware ردیابی درخواست را برمی‌گرداند
- `errorHandler()` — middleware مدیریت خطا را برمی‌گرداند
- `userMiddleware()` — اطلاعات کاربر را از `req.user` (id، email، username) تعیین می‌کند
- `transactionMiddleware(name)` — برای یک route نام‌دار، breadcrumbهای شروع و پایان (مدت و وضعیت) اضافه می‌کند

### نمونه‌ی کامل

```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'));
```

### توصیه‌ها

<BestPracticeList items={[
  ['زود راه‌اندازی کنید', 'ابرووا تریس را در ابتدای نقطه‌ی ورود برنامه راه‌اندازی کنید تا همه‌ی خطاها ثبت شوند'],
  ['از middleware برای Express استفاده کنید', 'برای ردیابی کامل در Express.js، request handler را اول و error handler را آخر اضافه کنید'],
  ['اطلاعات کاربر را تعیین کنید', 'خطاها را به اطلاعات کاربر مرتبط کنید تا عیب‌یابی آسان‌تر شود'],
  ['از context محدود استفاده کنید', 'با withScope برای یک بلوک همگام context موقت تعیین کنید؛ context در SDK برای کل پروسه مشترک است، برای همین وقتی callback برمی‌گردد به حالت قبل برمی‌گردد'],
  ['Breadcrumb اضافه کنید', 'کارهای مهم (کوئری‌های پایگاه داده، درخواست‌های HTTP، کارهای کاربر) را به‌صورت breadcrumb ثبت کنید'],
  ['خاموش شدن تمیز', 'در SIGTERM/SIGINT منتظر flush() و close() بمانید تا خطاها، لاگ‌ها و spanهای در صف فرستاده شوند'],
  ['Source mapها را فعال کنید', 'برای stack trace دقیق در برنامه‌های TypeScript یا bundleشده از --enable-source-maps استفاده کنید'],
  ['از beforeSend استفاده کنید', 'خطاهای پرسروصدا را فیلتر کنید و داده‌ی خطا را با context دلخواه غنی کنید'],
]} />

- SDK نکست: https://abrova.ir/docs/trace/nextjs-sdk

<BestPracticeList columns={2} items={[
  ['ثبت خطا', 'ثبت خودکار خطاهای مدیریت‌نشده، promise rejectionها و خطاهای React'],
  ['تشخیص کرش', 'تشخیص کرش و از کار افتادن تب مرورگر'],
  ['Breadcrumbها', 'ثبت کارهای کاربر و رویدادها برای فهمیدن زمینه‌ی خطا'],
  ['Source map', 'پشتیبانی خودکار از source map برای stack traceهای خوانا'],
  ['بهینه برای Next.js', 'ساخته‌شده برای App Router و Pages Router'],
  ['یکپارچگی با React', 'error boundary، hookها و کامپوننت‌ها'],
  ['همه‌جا', 'در مرورگر و Node.js (API routeها و server componentها) کار می‌کند'],
  ['زمینه‌ی کامل', 'ثبت جابه‌جایی بین صفحه‌ها، نشست‌های کاربر و metadata دلخواه'],
  ['قابل تنظیم', 'نمونه‌برداری، فیلتر و hookها'],
]} />

<H2 id="installation" step={1}>نصب</H2>

پکیج‌ها از Abrova Center می‌آیند. دو مرحله:

**۱. مخزن ابرووا را اضافه کنید** به فایل `.npmrc` در ریشه‌ی پروژه (npm، yarn و pnpm همه آن را می‌خوانند):

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

**۲. پکیج را نصب کنید:**

```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}>شروع سریع</H2>

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

فایل `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()` از `useSearchParams()` استفاده می‌کند. اگر `next build` درباره‌ی نبودن Suspense boundary خطا داد، آن را به‌جای این‌جا از یک کامپوننت کوچک داخل `<Suspense>` صدا بزنید (`NavigationTracker` را در بخش «ثبت جابه‌جایی بین صفحه‌ها» در پایین ببینید).

فایل `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 و قبل‌تر)

فایل `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>

کامپوننت‌ها را داخل error boundary قرار دهید تا خطاهای React خودکار گرفته و گزارش شوند:

#### استفاده‌ی پایه

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

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

#### همراه با تابع reset

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

#### همراه با handler خطا

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

#### Fallback پیش‌فرض

بدون `fallback`، این boundary یک پنل داخلی نمایش می‌دهد: عنوان «Something went wrong»، یک پیام کوتاه و دکمه‌ی **Try again** که boundary را reset می‌کند. از نسخه‌ی 0.1.8، پیام خطا، stack trace و component stack دیگر در production نمایش داده نمی‌شوند: این‌ها فقط وقتی `showErrorDetails` برابر `true` باشد در یک بخش جمع‌شونده‌ی «Error details» نمایش داده می‌شوند، و مقدار پیش‌فرض آن `process.env.NODE_ENV !== 'production'` است (در development نمایش داده می‌شود و در buildهای production پنهان است). اگر `fallback` دلخواه بدهید، همان‌طور که نوشته‌اید نمایش داده می‌شود و `showErrorDetails` روی آن اثری ندارد.

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

#### Propها

<ConfigTable rows={[
  ['children', 'ReactNode', 'بله', 'کامپوننت‌هایی که باید محافظت شوند'],
  ['fallback', 'ReactNode | function', 'خیر', 'رابط کاربری دلخواه بعد از خطا: یک element، یا تابعی با ورودی (error, errorInfo, resetError) که یک element برمی‌گرداند. جایگزین fallback پیش‌فرض می‌شود'],
  ['onError', 'function', 'خیر', 'بعد از گزارش خطا با (error, errorInfo) صدا زده می‌شود'],
  ['showDefaultFallback', 'boolean', 'خیر', 'وقتی fallback داده نشده، fallback داخلی نمایش داده شود (پیش‌فرض: true). با false چیزی نمایش داده نمی‌شود'],
  ['fallbackMessage', 'string', 'خیر', 'پیام fallback داخلی (پیش‌فرض: "An unexpected error occurred. Our team has been notified.")'],
  ['showErrorDetails', 'boolean', 'خیر', 'نمایش پیام خطا و stack trace در fallback داخلی (پیش‌فرض: در development برابر true و در production برابر false)'],
]} />

<H2 id="manual-error-capture" step={4}>ثبت دستی خطا</H2>

#### با hookها

```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>;
}
```

#### استفاده‌ی مستقیم از API

```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="پیام‌ها کجا نمایش داده می‌شوند">
پیام‌ها در کنسول، در بخش **ابرووا تریس › پیام‌ها**، همراه با سطح، پلتفرم، داده‌های اضافه و breadcrumbها نمایش داده می‌شوند. پیام‌ها هیچ‌وقت مشکل (issue) نمی‌سازند. سطح‌ها: `'debug'`، `'info'` (پیش‌فرض)، `'warning'` و `'error'`. پیام‌ها را برای چیزهایی به کار ببرید که اپ عمداً گزارش می‌دهد («پرداخت شروع شد»، «همگام‌سازی تمام شد»)؛ برای داده‌های عیب‌یابی پرحجم از لاگ‌ها استفاده کنید.
</Callout>

<H2 id="breadcrumbs" step={5}>Breadcrumbها</H2>

Breadcrumbها کارهای کاربر را ثبت می‌کنند و زمینه‌ی خطاها را فراهم می‌کنند. جابه‌جایی بین صفحه‌ها (بعد از استفاده از یکی از hookهای navigation) و فراخوانی‌های `console.error` / `console.warn` خودکار ثبت می‌شوند.

#### Breadcrumbهای دستی

```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');
```

#### با hookها

```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}>تشخیص کرش</H2>

SDK با یک سیستم heartbeat مبتنی بر localStorage، کرش و از کار افتادن تب مرورگر را تشخیص می‌دهد.

- **کرش تب** — کرش تب مرورگر را تشخیص می‌دهد
- **تب بدون پاسخ** — تب‌های هنگ‌کرده را تشخیص می‌دهد
- **بستن اجباری** — حالت‌های بستن اجباری را تشخیص می‌دهد
- **گزارش پس از وقوع** — گزارش در اجرای بعدی

#### چطور کار می‌کند

1. اپ شروع می‌شود — یک نشانگر کرش در localStorage ساخته می‌شود
2. heartbeat هر ۵ ثانیه اجرا می‌شود
3. اپ به‌طور عادی بسته می‌شود — نشانگر حذف می‌شود
4. اپ کرش می‌کند — نشانگر باقی می‌ماند
5. نشست بعدی — کرش تشخیص داده و گزارش می‌شود

<H2 id="api-routes-server-components" step={7}>API Routeها و Server Componentها</H2>

فراخوانی `init()` در `Providers` / `_app.tsx` فقط در مرورگر اجرا می‌شود، پس روی سرور تا وقتی SDK را آن‌جا هم راه‌اندازی نکنید، `AbrovaTrace.getInstance()` مقدار `null` برمی‌گرداند. یک helper کوچک سمت سرور بسازید (اگر نمونه‌ای از قبل راه‌اندازی شده باشد، `init()` همان را برمی‌گرداند):

```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 Routeها

```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 Componentها (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 Mapها</H2>

برای داشتن stack traceهای خوانا، source mapهای production را در `next.config.js` فعال کنید:

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

بعد از build اپ، فایل‌های `.map` را با [CLI ابرووا تریس](/docs/trace/upload-source-maps) آپلود کنید و همان `release` را بدهید که به `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}>گزینه‌های پیکربندی</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', 'بله', 'کلید API پروژه'],
  ['environment', 'string', 'خیر', 'نام محیط (پیش‌فرض: "production")'],
  ['release', 'string', 'خیر', 'شناسه‌ی نسخه‌ی اپ'],
  ['captureUncaughtErrors', 'boolean', 'خیر', 'گرفتن خودکار خطاهای مدیریت‌نشده (پیش‌فرض: true)'],
  ['enabled', 'boolean', 'خیر', 'فعال/غیرفعال کردن SDK (پیش‌فرض: true)'],
  ['debug', 'boolean', 'خیر', 'فعال کردن لاگ‌های debug (پیش‌فرض: false)'],
  ['timeout', 'number', 'خیر', 'مهلت درخواست HTTP بر حسب ثانیه (پیش‌فرض: 10)'],
  ['enableServerSide', 'boolean', 'خیر', 'ثبت خودکار خطاهای مدیریت‌نشده و unhandled rejectionها روی سرور (پیش‌فرض: true)'],
  ['enableClientSide', 'boolean', 'خیر', 'ثبت خودکار خطاهای مدیریت‌نشده و unhandled rejectionها در مرورگر (پیش‌فرض: true)'],
  ['enableCrashDetection', 'boolean', 'خیر', 'فعال کردن تشخیص کرش (پیش‌فرض: true)'],
  ['maxBreadcrumbs', 'number', 'خیر', 'حداکثر تعداد breadcrumbهای نگه‌داشته‌شده (پیش‌فرض: 20)'],
  ['sampleRate', 'number', 'خیر', 'نرخ نمونه‌برداری خطاها و پیام‌ها بین 0.0 تا 1.0 (پیش‌فرض: 1.0)'],
  ['tags', 'object', 'خیر', 'تگ‌های دلخواه که به همه‌ی خطاها اضافه می‌شوند'],
  ['ignoreErrors', 'array', 'خیر', 'پیام‌های خطایی که نادیده گرفته می‌شوند (رشته یا RegExp)'],
  ['ignoreUrls', 'array', 'خیر', 'رشته یا RegExp که با stack trace خطا مقایسه می‌شود؛ در صورت تطابق، خطا کنار گذاشته می‌شود'],
  ['beforeSend', 'function', 'خیر', 'hook برای تغییر یا فیلتر خطاها پیش از ارسال؛ با برگرداندن null یا false خطا کنار گذاشته می‌شود'],
  ['apiUrl', 'string', 'خیر', 'آدرس پایه‌ی Trace API (پیش‌فرض: "https://trace.abrova.ir"). فقط برای نسخه‌ی self-hosted تنظیمش کنید'],
]} />

<H2 id="user-identification" step={10}>شناسایی کاربر</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}>ثبت جابه‌جایی بین صفحه‌ها</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} />;
}
```

#### ثبت دستی

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

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

<H2 id="context-tags" step={12}>زمینه و تگ‌ها</H2>

metadata ماندگار را به همه‌ی خطاها و پیام‌ها اضافه کنید. تگ‌ها برای فیلتر کردن بر اساس دسته‌اند؛ extraها داده‌ی غنی‌تری برای هر رویدادند. (لاگ‌ها، spanها و Web Vitals این‌ها را همراه ندارند.)

#### Extraهای سراسری

```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();
```

#### تگ‌ها

```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();
```

#### شناسه‌ی نشست

هنگام راه‌اندازی SDK یک شناسه‌ی نشست یکتا خودکار ساخته می‌شود (۱۶ بایت تصادفی hex) و به همه‌ی خطاها و پیام‌ها اضافه می‌شود تا در کنسول ابرووا بر اساس نشست گروه‌بندی شوند:

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

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

Core Web Vitals را با کتابخانه‌ی رسمی گوگل، `web-vitals`، اندازه بگیرید (فقط در مرورگر). این معیارها در کنسول ابرووا، در بخش **ابرووا تریس › عملکرد**، کنار spanهای HTTP نمایش داده می‌شوند.

```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
});
```

**معیارهای اندازه‌گیری‌شده:**

<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 خودکار نوع دستگاه (mobile/tablet/desktop)، نوع اتصال، آدرس صفحه و اطلاعات route را همراه دارند.

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

این SDK با TypeScript نوشته شده و تعریف کامل typeها را همراه دارد. وقتی برای اشیای پیکربندی یا payload رویدادها annotation صریح لازم دارید، typeها را import کنید:

```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}>لاگ</H2>

لاگ ساخت‌یافته‌ی سمت سرور که در App Router، Pages Router و API Routeها کار می‌کند. لاگ از یک نمونه‌ی جداگانه‌ی `LogService` استفاده می‌کند — آن را در `lib/logger.ts` بسازید و از هر جا import کنید:

```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 });
```

می‌توانید از طریق نمونه‌ی SDK هم لاگ بفرستید که از پیکربندی `init()` استفاده می‌کند: `AbrovaTrace.getInstance()?.info('Users fetched', { count: 42 })` (جدول «لاگ» را در «مرجع API» پایین ببینید). لاگ‌ها از `captureMessage()` جدا هستند: به‌صورت دسته‌ای ارسال می‌شوند و در بخش **ابرووا تریس › لاگ‌ها** نمایش داده می‌شوند.

برای جزئیات کامل — App Router، Pages Router، API Routeها، سطح‌های لاگ و middleware درخواست — صفحه‌ی [لاگ در Next.js SDK](/docs/trace/nextjs-logging) را ببینید.

### مرجع API

#### `AbrovaTrace` — راه‌اندازی و چرخه‌ی حیات

<ConfigTable rows={[
  ['init(config)', '-', '-', 'راه‌اندازی SDK'],
  ['getInstance()', '-', '-', 'گرفتن نمونه‌ی singleton از SDK'],
  ['close()', '-', '-', 'پاک‌سازی SDK و ارسال داده‌های در صف'],
]} />

#### ثبت خطا

<ConfigTable rows={[
  ['captureException(error, message?, extra?, level?, callback?)', '-', '-', 'ثبت یک خطا / exception'],
  ['captureMessage(message, level?, extra?, callback?)', '-', '-', 'ارسال پیام به ابرووا تریس › پیام‌ها (مشکل ساخته نمی‌شود)'],
]} />

#### کاربر و نشست

<ConfigTable rows={[
  ['setUserId(userId)', '-', '-', 'تعیین شناسه‌ی کاربر فعلی'],
  ['getUserId()', '-', '-', 'گرفتن شناسه‌ی کاربر فعلی'],
  ['getSessionId()', '-', '-', 'گرفتن شناسه‌ی نشستی که خودکار ساخته شده'],
]} />

#### زمینه‌ی سراسری (extraها)

<ConfigTable rows={[
  ['setExtra(key, value)', '-', '-', 'تعیین یک extra'],
  ['setExtras(extras)', '-', '-', 'تعیین چند extra به‌طور هم‌زمان'],
  ['getExtra(key)', '-', '-', 'گرفتن مقدار یک extra'],
  ['getExtras()', '-', '-', 'گرفتن همه‌ی extraها'],
  ['clearExtras()', '-', '-', 'پاک کردن همه‌ی extraها'],
]} />

#### تگ‌ها

<ConfigTable rows={[
  ['setTag(key, value)', '-', '-', 'تعیین یک تگ'],
  ['setTags(tags)', '-', '-', 'تعیین چند تگ به‌طور هم‌زمان'],
  ['getTag(key)', '-', '-', 'گرفتن مقدار یک تگ'],
  ['getTags()', '-', '-', 'گرفتن همه‌ی تگ‌ها'],
  ['clearTags()', '-', '-', 'پاک کردن همه‌ی تگ‌ها'],
]} />

#### پایش عملکرد

<ConfigTable rows={[
  ['enablePerformanceTracking(options?)', '-', '-', 'روشن کردن گزارش عملکرد؛ در مرورگر همه‌ی فراخوانی‌های fetch را هم اندازه می‌گیرد. گزینه‌ها: batchSize (پیش‌فرض: 5) و flushInterval بر حسب میلی‌ثانیه (پیش‌فرض: 5000)'],
  ['enableWebVitals(options?)', '-', '-', 'روشن کردن اندازه‌گیری Web Vitals'],
  ['reportPerformanceSpan(span)', '-', '-', 'گزارش یک span'],
  ['reportPerformanceSpanBatch(spans)', '-', '-', 'گزارش چند span به‌طور هم‌زمان'],
  ['trackOperation(operation, fn, options?)', '-', '-', 'اندازه‌گیری زمان و گزارش یک عملیات async'],
  ['createPerformanceFetch()', '-', '-', 'ساخت یک wrapper برای fetch که برای هر درخواست یک span گزارش می‌دهد. فقط بعد از فراخوانی enablePerformanceTracking()، trackOperation() یا reportPerformanceSpan() گزارش می‌دهد'],
  ['flushPerformance()', '-', '-', 'ارسال فوری داده‌های عملکرد بافرشده'],
]} />

#### لاگ

<ConfigTable rows={[
  ['enableLogging(options?)', '-', '-', 'روشن کردن مسیر ارسال لاگ'],
  ['log(message, level?, metadata?)', '-', '-', 'لاگ با سطح مشخص'],
  ['trace(message, metadata?)', '-', '-', 'لاگ در سطح trace'],
  ['logDebug(message, metadata?)', '-', '-', 'لاگ در سطح debug'],
  ['info(message, metadata?)', '-', '-', 'لاگ در سطح info'],
  ['warn(message, metadata?)', '-', '-', 'لاگ در سطح warn'],
  ['logError(message, metadata?)', '-', '-', 'لاگ در سطح error'],
  ['fatal(message, metadata?)', '-', '-', 'لاگ در سطح fatal'],
  ['flushLogs()', '-', '-', 'ارسال فوری لاگ‌های بافرشده'],
  ['pendingLogCount', '-', '-', 'تعداد لاگ‌هایی که هنوز در بافر هستند'],
]} />

#### `BreadcrumbService`

<ConfigTable rows={[
  ['add(message, type, data?, level?)', '-', '-', 'افزودن یک breadcrumb عمومی'],
  ['addNavigation(from, to, data?)', '-', '-', 'افزودن breadcrumb جابه‌جایی بین صفحه‌ها'],
  ['addUser(action, data?)', '-', '-', 'افزودن breadcrumb کار کاربر'],
  ['addHttp(method, url, status?, data?)', '-', '-', 'افزودن breadcrumb HTTP'],
  ['addState(message, data?)', '-', '-', 'افزودن breadcrumb تغییر state'],
  ['getAll()', '-', '-', 'گرفتن همه‌ی breadcrumbها'],
  ['clear()', '-', '-', 'پاک کردن همه‌ی breadcrumbها'],
]} />

#### `RouterIntegration`

<ConfigTable rows={[
  ['trackAppRouterNavigation(pathname, searchParams?)', '-', '-', 'ثبت دستی جابه‌جایی در App Router'],
  ['initializePagesRouter(router)', '-', '-', 'راه‌اندازی ثبت جابه‌جایی در Pages Router'],
  ['setCurrentRoute(route)', '-', '-', 'جایگزین کردن route فعلی'],
  ['getCurrentRoute()', '-', '-', 'گرفتن route فعلی'],
  ['getNavigationContext()', '-', '-', 'گرفتن زمینه‌ی فعلی navigation'],
]} />

#### `CrashDetector`

<ConfigTable rows={[
  ['enable()', '-', '-', 'روشن کردن تشخیص کرش'],
  ['disable()', '-', '-', 'خاموش کردن تشخیص کرش'],
  ['didCrashLastSession()', '-', '-', 'اگر نشست قبلی با کرش تمام شده باشد true برمی‌گرداند'],
  ['getCrashReport()', '-', '-', 'گرفتن جزئیات کرش قبلی'],
]} />

#### هوک‌های React

<ConfigTable rows={[
  ['useAbrovaTrace()', '-', '-', 'برمی‌گرداند: { captureException, captureMessage, setUserId, setExtra, setExtras, setTag, setTags }'],
  ['useAbrovaTraceNavigation()', '-', '-', 'ثبت خودکار جابه‌جایی در App Router'],
  ['useAbrovaTracePagesRouter()', '-', '-', 'ثبت خودکار جابه‌جایی در Pages Router'],
  ['useBreadcrumbs()', '-', '-', 'برمی‌گرداند: { addBreadcrumb, addNavigation, addHttp, addState }'],
]} />

#### کامپوننت‌های React

<ConfigTable rows={[
  ['ErrorBoundary', '-', '-', 'error boundary برای React با گزارش خودکار خطا (نام دیگر: AbrovaTraceErrorBoundary)'],
]} />

### توصیه‌ها

<BestPracticeList items={[
  ['زود راه‌اندازی کنید', 'ابرووا تریس را تا جای ممکن زود در چرخه‌ی حیات اپ راه‌اندازی کنید تا همه‌ی خطاها گرفته شوند'],
  ['شناسه‌ی کاربر را تنظیم کنید', 'بعد از احراز هویت، شناسه‌ی کاربر را تنظیم کنید تا خطاها به کاربران نسبت داده شوند'],
  ['از error boundary استفاده کنید', 'بخش‌های اصلی اپ را داخل error boundary قرار دهید تا خطاهای React خودکار ثبت شوند'],
  ['به خطاها زمینه اضافه کنید', 'هنگام ثبت خطا، شناسه‌ی کاربر، مبالغ و داده‌های مرتبط را همراهش بفرستید'],
  ['از breadcrumb استفاده کنید', 'برای کارهای مهم کاربر breadcrumb اضافه کنید تا زمینه‌ی خطا روشن باشد'],
  ['پیکربندی جدا برای هر محیط', 'برای production و development پیکربندی جدا داشته باشید (حالت debug، نرخ نمونه‌برداری)'],
  ['هنگام unmount پاک‌سازی کنید', 'برای عملکرد درست تشخیص کرش، هنگام پاک‌سازی AbrovaTrace.getInstance()?.close() را صدا بزنید'],
]} />

- SDK اندروید: https://abrova.ir/docs/trace/android-sdk

<BestPracticeList columns={2} items={[
  ['SDK نیتیو Kotlin', 'با Kotlin ساخته شده و از API 19 به بالا (Android 4.4 به بالا) پشتیبانی می‌کند'],
  ['تشخیص خودکار کرش', 'exceptionهای مدیریت‌نشده را می‌گیرد، و روی Android 11 به بالا کرش‌های نیتیو را هم'],
  ['تشخیص ANR', 'مشکل‌های «برنامه پاسخ نمی‌دهد» (Application Not Responding) را تشخیص می‌دهد'],
  ['Breadcrumb و ناوبری', 'مسیر کاربر را پیش از وقوع خطا ثبت می‌کند'],
  ['Interceptor برای OkHttp', 'ردیابی خودکار درخواست‌های HTTP'],
  ['مانیتورینگ عملکرد', 'ردیابی تأخیر API با interceptorهای OkHttp'],
  ['اطلاعات کامل دستگاه', 'جمع‌آوری خودکار اطلاعات دستگاه، سیستم‌عامل و برنامه'],
]} />

<H2 id="installation" step={1}>نصب</H2>

SDK از Abrova Center نصب می‌شود. در دو مرحله:

**۱. مخزن ابرووا را اضافه کنید** در `settings.gradle.kts` (یا `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" }`

**۲. وابستگی را اضافه کنید** به `build.gradle.kts` برنامه:

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

سپس پروژه را با فایل‌های Gradle همگام (sync) کنید. پیش‌نیازها: Android 4.4 (API 19) یا بالاتر؛ گزارش کرش‌های نیتیو به Android 11 (API 30) یا بالاتر نیاز دارد.

<H2 id="quick-start" step={2}>شروع سریع</H2>

AbrovaTrace را در کلاس `Application` راه‌اندازی کنید:

```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="بستن درست SDK">
  متد `onTerminate()` روی دستگاه واقعی هیچ‌وقت صدا زده نمی‌شود؛ پس close() را در Activity اصلی هم صدا بزنید. close() لاگ‌های بافرشده را می‌فرستد، watchdog مربوط به ANR را متوقف می‌کند و کلاینت شبکه را می‌بندد. کلید API باید با `ab_live_` شروع شود؛ در غیر این صورت config خطا می‌دهد.
</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}>ثبت خطاها</H2>

#### ثبت exceptionها

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

#### ثبت با اطلاعات تکمیلی

```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")
)
```

#### ثبت پیام‌ها

```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="پیام‌ها کجا نمایش داده می‌شوند">
پیام‌ها در کنسول، در بخش **ابرووا تریس › پیام‌ها**، همراه با سطح، پلتفرم، داده‌های تکمیلی و breadcrumbها نمایش داده می‌شوند. پیام هیچ‌وقت مشکل (issue) نمی‌سازد. سطح‌ها: `MessageLevel.DEBUG`، `INFO` (پیش‌فرض)، `WARNING` و `ERROR`. سطح `FATAL` هم پذیرفته می‌شود و با سطح `error` ذخیره می‌شود. پیام را برای چیزهایی به کار ببرید که برنامه عمداً گزارش می‌دهد («پرداخت شروع شد»، «همگام‌سازی تمام شد»)؛ برای عیب‌یابی پرحجم از لاگ‌ها استفاده کنید.
</Callout>

<H2 id="breadcrumbs" step={4}>Breadcrumbها</H2>

Breadcrumbها کمک می‌کنند بفهمید پیش از وقوع خطا چه اتفاقی افتاده است. برای جابه‌جایی بین Activityها، رفتن برنامه به پیش‌زمینه و پس‌زمینه، و رویدادهای سیستم به‌طور خودکار اضافه می‌شوند.

```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</H2>

درخواست‌های HTTP را به‌طور خودکار به‌صورت breadcrumb ثبت کنید و خطاهای HTTP را بگیرید:

#### راه‌اندازی پایه

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

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

#### همراه با ثبت خطا

```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` هر پاسخ 5xx را به‌صورت یک **پیام** با سطح `error` می‌فرستد (ابرووا تریس › پیام‌ها). پاسخ‌های 4xx به‌طور پیش‌فرض خاموش‌اند؛ با `AbrovaTraceErrorInterceptor(captureClientErrors = true)` روشنشان کنید (با سطح `warning` فرستاده می‌شوند). خطاهای شبکه (وقتی پاسخی نمی‌رسد) به‌صورت exception ثبت می‌شوند.

<H2 id="crash-detection" step={6}>تشخیص کرش</H2>

ابرووا تریس کرش‌ها را درون خود برنامه تشخیص می‌دهد و روی Android 11 به بالا، از سوابق خروج خود سیستم هم می‌خواند.

- **exceptionهای Java/Kotlin**: به‌صورت لحظه‌ای با یک handler برای exceptionهای مدیریت‌نشده (`captureUncaughtExceptions`) گرفته می‌شوند. گزارش پیش از بسته شدن برنامه، روی هر threadی از جمله main thread، فرستاده می‌شود؛ اگر سرور ظرف ۲ ثانیه آن را نپذیرد، روی دستگاه نگه داشته می‌شود و در اجرای بعدی فرستاده می‌شود. به نسخه‌ی 0.2.2 یا جدیدتر نیاز دارد.
- **رویدادهای ANR**: یک thread نگهبان (watchdog) تشخیص می‌دهد که main thread بیش از `anrTimeoutMs` مسدود مانده است (`captureAnr`)
- **کرش‌های نیتیو**: سیگنال‌هایی مثل SIGSEGV و SIGABRT که در اجرای بعدی گزارش می‌شوند (فقط Android 11 / API 30 به بالا، `captureSignalCrashes`)

#### نحوه‌ی کار

1. در هر اجرا (API 30 به بالا)، ابرووا تریس سوابق `ApplicationExitInfo` اندروید را برای برنامه‌ی شما می‌خواند
2. خروج‌هایی که از اجرای قبلی تا حالا با دلیل کرش JVM، کرش نیتیو یا ANR رخ داده‌اند به گزارش کرش تبدیل می‌شوند؛ برای کرش‌های نیتیو، tombstone هم ضمیمه می‌شود
3. زمان آخرین رکورد فرستاده‌شده ذخیره می‌شود تا هر کرش فقط یک بار گزارش شود؛ اگر ارسال ناموفق باشد، در اجرای بعدی دوباره تلاش می‌شود. کرش Java/Kotlinی که handler درون برنامه قبلاً گزارش داده، اینجا نادیده گرفته می‌شود
4. روی Android 10 و پایین‌تر این مرحله کاری انجام نمی‌دهد؛ کرش‌های JVM همچنان با handler درون برنامه گرفته می‌شوند

<H2 id="performance-monitoring-apm" step={7}>مانیتورینگ عملکرد (APM)</H2>

تأخیر API و عملکرد درخواست‌های HTTP را به‌طور خودکار ردیابی کنید.

#### ردیابی خودکار عملکرد HTTP با 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()
}
```

#### استفاده با 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
```

#### ردیابی عملیات دلخواه

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

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

#### گزارش دستی span

```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}>لاگ‌ها</H2>

ارسال لاگ ساخت‌یافته با دسته‌بندی (batching) و تلاش مجدد خودکار. یک بار فعالش کنید و سپس از هر جای برنامه از متدهای سطح‌ها استفاده کنید:

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

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

برای جزئیات کامل این مسیر (دسته‌بندی، سطح‌های لاگ، مدیریت چرخه‌ی عمر، ارسال دستی و تنظیمات) صفحه‌ی [لاگ‌ها در Android SDK](/docs/trace/android-logging) را ببینید.

<H2 id="configuration-options" step={9}>گزینه‌های تنظیمات</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', 'بله', 'کلید API پروژه (باید با ab_live_ شروع شود)'],
  ['environment', 'String', 'خیر', 'نام محیط (پیش‌فرض: "production")'],
  ['release', 'String', 'خیر', 'شناسه‌ی نسخه‌ی برنامه'],
  ['debug', 'Boolean', 'خیر', 'فعال کردن لاگ‌های debug (پیش‌فرض: false)'],
  ['enabled', 'Boolean', 'خیر', 'فعال/غیرفعال کردن SDK (پیش‌فرض: true)'],
  ['sampleRate', 'Float', 'خیر', 'نرخ نمونه‌برداری ۰٫۰ تا ۱٫۰ برای captureException (پیش‌فرض: 1.0)'],
  ['maxBreadcrumbs', 'Int', 'خیر', 'حداکثر تعداد breadcrumbهای نگه‌داشته‌شده (پیش‌فرض: 20)'],
  ['httpTimeout', 'Int', 'خیر', 'مهلت درخواست HTTP به ثانیه (پیش‌فرض: 30)'],
  ['enableOfflineStorage', 'Boolean', 'خیر', 'خطاهایی را که هنگام آفلاین بودن دستگاه فرستاده نشده‌اند (تا ۱۰۰ مورد) نگه می‌دارد و بعداً می‌فرستد (پیش‌فرض: true)'],
  ['captureUncaughtExceptions', 'Boolean', 'خیر', 'گرفتن exceptionهای مدیریت‌نشده (پیش‌فرض: true)'],
  ['captureSignalCrashes', 'Boolean', 'خیر', 'گزارش کرش‌های نیتیو و دیگر کرش‌ها و ANRهایی که سیستم ثبت کرده، در اجرای بعدی، API 30 به بالا (پیش‌فرض: true)'],
  ['captureAnr', 'Boolean', 'خیر', 'تشخیص رویدادهای ANR (پیش‌فرض: true)'],
  ['anrTimeoutMs', 'Long', 'خیر', 'مهلت تشخیص ANR به میلی‌ثانیه (پیش‌فرض: 5000)'],
  ['apiUrl', 'String', 'خیر', 'آدرس سرور Trace (پیش‌فرض: "https://trace.abrova.ir")'],
]} />

<Callout kind="note" title="ذخیره‌سازی آفلاین">
وقتی خطایی به دلیل قطع بودن اتصال دستگاه فرستاده نشود، SDK آن را در فضای خصوصی برنامه نگه می‌دارد و بعداً می‌فرستد: در اجرای بعدی، و به محض اینکه خطای دیگری با موفقیت فرستاده شود. حداکثر ۱۰۰ خطا نگه داشته می‌شود؛ با رسیدن به این سقف، قدیمی‌ترین‌ها حذف می‌شوند. این فقط شامل خطاهاست: `captureException`، exceptionهای مدیریت‌نشده و گزارش‌های ANR. پیام‌ها، لاگ‌ها و داده‌های عملکرد ذخیره نمی‌شوند. اگر نمی‌خواهید چیزی روی دستگاه بماند، `enableOfflineStorage(false)` را تنظیم کنید.
</Callout>

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

قوانین ProGuard به‌طور خودکار همراه SDK هستند. اگر به قوانین سفارشی نیاز دارید، آن‌ها را به `proguard-rules.pro` اضافه کنید:

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

<H2 id="device-compatibility" step={11}>سازگاری با دستگاه‌ها</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 و تگ‌ها</H2>

متادیتای ثابت را به همه‌ی خطاها و پیام‌هایی که SDK ثبت می‌کند پیوست کنید (تگ‌ها به spanهای عملکرد هم اضافه می‌شوند). این کار برای فیلتر کردن بر اساس تیم، منطقه، پرچم ویژگی یا گروه آزمایش در کنسول ابرووا مفید است. گزارش‌های ANR و گزارش‌های کرشی که در اجرای بعدی از سیستم خوانده می‌شوند این اطلاعات را ندارند.

#### extraهای سراسری

extraها جفت‌های کلید/مقدار دلخواه هستند (کلید رشته‌ای، هر مقدار قابل serialize) که به‌طور خودکار در همه‌ی رویدادها ادغام می‌شوند:

```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()
```

#### تگ‌ها

تگ‌ها جفت‌های کلید/مقدار فقط رشته‌ای هستند که به همه‌ی خطاها و پیام‌ها پیوست می‌شوند:

```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="تفاوت تگ و extra">
از **تگ‌ها** برای فیلترهای دسته‌ای با تنوع کم (تیم، منطقه، build flavor) استفاده کنید. از **extraها** برای context غنی‌تر هر رویداد (شناسه‌ی کاربر، بدنه‌ی درخواست، مقادیر محاسبه‌شده).
</Callout>

### مرجع API

فهرست کامل متدهای `AbrovaTrace` و `PerformanceSpan`. امضای متدها به سبک Kotlin نوشته شده و پارامترهای اختیاری با `?` مشخص شده‌اند.

#### `AbrovaTrace`: راه‌اندازی و چرخه‌ی عمر

<ConfigTable rows={[
  ['init(context, config)', '-', '-', 'راه‌اندازی SDK با یک AbrovaTraceConfig کامل'],
  ['init(context, apiKey)', '-', '-', 'راه‌اندازی SDK فقط با کلید API (با مقادیر پیش‌فرض)'],
  ['isInitialized()', '-', '-', 'اگر SDK راه‌اندازی شده باشد true برمی‌گرداند'],
  ['close()', '-', '-', 'ارسال لاگ‌های بافرشده، توقف watchdog مربوط به ANR و بستن کلاینت شبکه'],
]} />

#### ثبت خطا

<ConfigTable rows={[
  ['captureException(throwable, message?, extra?, tags?, callback?)', '-', '-', 'ثبت یک exception با متادیتای اختیاری'],
  ['captureMessage(message, level?, extra?, tags?, callback?)', '-', '-', 'ارسال یک پیام با سطح مشخص به ابرووا تریس › پیام‌ها (مشکل نمی‌سازد)'],
]} />

#### کاربر و نشست

<ConfigTable rows={[
  ['setUserId(id)', '-', '-', 'تنظیم شناسه‌ی کاربر فعلی'],
  ['getUserId()', '-', '-', 'دریافت شناسه‌ی کاربر فعلی'],
]} />

#### context سراسری (extraها)

<ConfigTable rows={[
  ['setExtra(key, value)', '-', '-', 'تنظیم یک extra'],
  ['setExtras(extras)', '-', '-', 'تنظیم چند extra به‌صورت یک‌جا'],
  ['clearExtras()', '-', '-', 'پاک کردن همه‌ی extraها'],
]} />

#### تگ‌ها

<ConfigTable rows={[
  ['setTag(key, value)', '-', '-', 'تنظیم یک تگ'],
  ['setTags(tags)', '-', '-', 'تنظیم چند تگ به‌صورت یک‌جا'],
  ['clearTags()', '-', '-', 'پاک کردن همه‌ی تگ‌ها'],
]} />

#### Breadcrumbها

<ConfigTable rows={[
  ['addBreadcrumb(message, type?, data?)', '-', '-', 'افزودن یک breadcrumb عمومی'],
  ['addNavigationBreadcrumb(from, to)', '-', '-', 'افزودن یک breadcrumb ناوبری'],
  ['addUserBreadcrumb(action, data?)', '-', '-', 'افزودن یک breadcrumb برای اقدام کاربر'],
  ['addHttpBreadcrumb(method, url, statusCode?, duration?)', '-', '-', 'افزودن یک breadcrumb برای HTTP'],
  ['clearBreadcrumbs()', '-', '-', 'پاک کردن همه‌ی breadcrumbها'],
]} />

#### مانیتورینگ عملکرد

<ConfigTable rows={[
  ['reportPerformanceSpan(method, url, statusCode, durationMs, startTime, errorMessage?, tags?)', '-', '-', 'گزارش یک span برای HTTP'],
  ['reportPerformanceSpan(span, callback?)', '-', '-', 'گزارش یک PerformanceSpan ساخته‌شده'],
  ['reportPerformanceSpanBatch(spans, callback?)', '-', '-', 'گزارش چند span به‌صورت یک‌جا'],
  ['trackOperation(operation, operationType?, tags?, block)', '-', '-', 'زمان‌گیری یک بلوک و گزارش آن به‌صورت span'],
  ['performanceInterceptor(minDurationMs?)', '-', '-', 'ساخت یک interceptor برای OkHttp جهت زمان‌سنجی HTTP'],
]} />

#### لاگ‌ها

<ConfigTable rows={[
  ['enableLogging(sourceId?, sourceName?, batchSize?, flushIntervalMs?)', '-', '-', 'روشن کردن مسیر ارسال لاگ'],
  ['log(message, level?, metadata?)', '-', '-', 'لاگ با سطح مشخص'],
  ['trace(message, metadata?)', '-', '-', 'لاگ با سطح trace'],
  ['logDebug(message, metadata?)', '-', '-', 'لاگ با سطح debug'],
  ['info(message, metadata?)', '-', '-', 'لاگ با سطح info'],
  ['warn(message, metadata?)', '-', '-', 'لاگ با سطح warn'],
  ['logError(message, metadata?)', '-', '-', 'لاگ با سطح error'],
  ['fatal(message, metadata?)', '-', '-', 'لاگ با سطح fatal'],
  ['flushLogs(callback?)', '-', '-', 'ارسال فوری لاگ‌های بافرشده'],
  ['getPendingLogCount()', '-', '-', 'تعداد لاگ‌هایی که هنوز در بافر مانده‌اند'],
]} />

#### متدهای سازنده‌ی `PerformanceSpan`

<ConfigTable rows={[
  ['PerformanceSpan.fromHttpRequest(...)', '-', '-', 'ساخت span از یک درخواست/پاسخ HTTP'],
  ['PerformanceSpan.forDbQuery(...)', '-', '-', 'ساخت span برای یک کوئری پایگاه داده'],
  ['PerformanceSpan.custom(...)', '-', '-', 'ساخت یک span کاملاً سفارشی'],
  ['PerformanceSpan.generateTraceId()', '-', '-', 'تولید یک trace ID تصادفی'],
  ['PerformanceSpan.generateSpanId()', '-', '-', 'تولید یک span ID تصادفی'],
]} />

### نمونه‌ی کامل

```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() { /* ... */ }
}
```

### توصیه‌ها

<BestPracticeList items={[
  ['راه‌اندازی در کلاس Application', 'ابرووا تریس را در متد onCreate() کلاس Application راه‌اندازی کنید تا همه‌ی خطاها از لحظه‌ی شروع برنامه گرفته شوند'],
  ['صدا زدن close() هنگام خروج', 'لاگ‌های بافرشده را می‌فرستد و watchdog مربوط به ANR را متوقف می‌کند'],
  ['افزودن context به خطاها', 'شناسه‌ی کاربر، نام صفحه و داده‌های مرتبط را در پارامتر extra بگذارید'],
  ['استفاده از محیط‌های جدا', 'خطاهای production، staging و development را با تنظیم environment از هم جدا کنید'],
  ['فعال کردن حالت debug در توسعه', 'در زمان توسعه debug(true) را تنظیم کنید تا لاگ‌های SDK را ببینید و درستی یکپارچگی را بررسی کنید'],
  ['استفاده از interceptorهای OkHttp', 'برای breadcrumbهای HTTP از AbrovaTraceInterceptor و برای گزارش خطاهای HTTP از AbrovaTraceErrorInterceptor استفاده کنید'],
  ['فعال کردن زودهنگام لاگ‌ها', 'enableLogging() را بلافاصله بعد از init() صدا بزنید تا همه‌ی رویدادهای برنامه ثبت شوند'],
]} />

- SDK آی‌اواس: https://abrova.ir/docs/trace/ios-sdk

<BestPracticeList columns={2} items={[
  ['SDK نیتیو Swift', 'با Swift ساخته شده و از iOS 12 به بالا، macOS 10.14 به بالا و tvOS 12 به بالا پشتیبانی می‌کند (tvOS فقط از طریق Swift Package Manager)'],
  ['تشخیص خودکار کرش', 'exceptionهای مدیریت‌نشده، و همچنین کرش‌های سیگنال نیتیو (SIGSEGV، SIGABRT و …) و Mach exceptionها را با PLCrashReporter می‌گیرد'],
  ['تشخیص ANR', 'رویدادهای «برنامه پاسخ نمی‌دهد» (مسدود شدن main thread) را تشخیص می‌دهد'],
  ['Breadcrumb و ناوبری', 'مسیر کاربر را پیش از وقوع خطا ثبت می‌کند'],
  ['ردیابی HTTP', 'ساخت خودکار spanهای عملکرد و breadcrumbهای HTTP'],
  ['پیام‌های دلخواه', 'ارسال پیام با سطح debug، info، warning و error'],
  ['مانیتورینگ عملکرد', 'ردیابی تأخیر API با URLSession و Alamofire'],
  ['اطلاعات کامل دستگاه', 'جمع‌آوری خودکار اطلاعات دستگاه، سیستم‌عامل و برنامه'],
]} />

<H2 id="installation" step={1}>نصب</H2>

#### Swift Package Manager (پیشنهادی)

در Xcode از منوی **File → Add Packages** آدرس Abrova Center را وارد کنید:

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

نسخه‌ی `0.2.4` یا بالاتر را انتخاب کنید.

یا آن را به `Package.swift` اضافه کنید:

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

#### CocoaPods

این خط را به `Podfile` اضافه کنید:

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

سپس اجرا کنید:

```bash
pod install
```

<Callout kind="note" title="Abrova Center و GitHub">
نسخه‌ها از Abrova Center نصب می‌شوند که داخل ایران کار می‌کند. کد منبع روی GitHub است ([Abrova-co/abrova-trace-ios-sdk](https://github.com/Abrova-co/abrova-trace-ios-sdk)) با همان tagهای نسخه؛ پس هرجا GitHub در دسترس باشد `https://github.com/Abrova-co/abrova-trace-ios-sdk.git` هم کار می‌کند.
</Callout>

<H2 id="quick-start" step={2}>شروع سریع</H2>

#### راه‌اندازی در UIKit

ابرووا تریس را در `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

```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}>ثبت خطاها</H2>

#### ثبت خطاهای Swift

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

برای مقادیر `Error` در Swift از `captureError(_:)` و برای `NSException` از `captureException(_:)` استفاده کنید.

#### ثبت همراه با context

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

#### ثبت پیام‌ها

```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="پیام‌ها کجا نمایش داده می‌شوند">
پیام‌ها در کنسول، در بخش **ابرووا تریس › پیام‌ها**، همراه با سطح، پلتفرم، داده‌های تکمیلی و breadcrumbها نمایش داده می‌شوند. پیام هیچ‌وقت مشکل (issue) نمی‌سازد. سطح‌ها: `.debug`، `.info` (پیش‌فرض)، `.warning` و `.error`. سطح `.fatal` هم پذیرفته می‌شود و با سطح `error` ذخیره می‌شود. پیام را برای چیزهایی به کار ببرید که برنامه عمداً گزارش می‌دهد («پرداخت شروع شد»، «همگام‌سازی تمام شد»)؛ برای عیب‌یابی پرحجم از لاگ‌ها استفاده کنید.
</Callout>

<H2 id="breadcrumbs" step={4}>Breadcrumbها</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}>ردیابی خودکار HTTP</H2>

#### ردیابی سراسری HTTP

ردیابی خودکار درخواست‌های URLSession را فعال کنید. هر درخواست به‌صورت یک span عملکرد گزارش می‌شود و به‌عنوان breadcrumb از نوع HTTP اضافه می‌شود:

```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

```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="حریم خصوصی">
  spanهای عملکردی که <code>enablePerformanceTracking()</code> می‌سازد آدرس کامل درخواست را، همراه با query string، ثبت می‌کنند؛ پس اطلاعات محرمانه را در URL نگذارید یا آن hostها را با <code>setPerformanceExcludedHosts(_:)</code> مستثنا کنید. متد جداگانه‌ی <code>AbrovaTraceHttpBreadcrumbProtocol.enable()</code> breadcrumbهای HTTP را با پنهان کردن پارامترهای حساس query (token، api_key، apikey، key، secret، password، pwd، auth، authorization، access_token، refresh_token، session) اضافه می‌کند و پاسخ‌های 5xx و درخواست‌های ناموفق را به‌صورت پیام گزارش می‌دهد.
</Callout>

<H2 id="crash-detection" step={6}>تشخیص کرش</H2>

ابرووا تریس کرش‌ها را با یک نسخه‌ی تعبیه‌شده از PLCrashReporter ثبت می‌کند:

- **NSExceptionهای مدیریت‌نشده**: بلافاصله و پیش از بسته شدن برنامه فرستاده می‌شوند (`captureUncaughtExceptions`)
- **رویدادهای ANR**: مسدود ماندن main thread بیش از `anrTimeoutMs` (`captureAnr`)
- **کرش‌های نیتیو**: سیگنال‌های POSIX (SIGSEGV، SIGABRT، SIGBUS، SIGILL، SIGFPE، SIGTRAP) و Mach exceptionها (`captureSignalCrashes`)

1. هنگام راه‌اندازی، ابرووا تریس handlerهای async-signal-safe مربوط به PLCrashReporter را نصب می‌کند
2. وقتی برنامه کرش می‌کند، یک گزارش کرش روی دیسک، داخل sandbox برنامه، نوشته می‌شود
3. در اجرای بعدی، `initialize` گزارش در انتظار را می‌خواند و آن را در پس‌زمینه به ابرووا تریس می‌فرستد؛ بنابراین اجرای برنامه هیچ‌وقت منتظر شبکه نمی‌ماند. گزارش فقط پس از تحویل موفق حذف می‌شود؛ اگر سرور یا شبکه خطا بدهد، نگه داشته می‌شود و در اجرای بعدی فرستاده می‌شود. به نسخه‌ی 0.2.3 یا جدیدتر نیاز دارد.

<Callout kind="note" title="مهم">
  کرش‌های نیتیو در اجرای <em>بعدی</em> گزارش می‌شوند، پس فقط وقتی می‌رسند که کاربر دوباره برنامه را باز کند. SDK با دریافت اعلان will-terminate برنامه، خودش <code>AbrovaTrace.shared.close()</code> را صدا می‌زند؛ صدا زدن آن توسط شما اختیاری است و لاگ‌های بافرشده را می‌فرستد.
</Callout>

<H2 id="performance-monitoring-apm" step={7}>مانیتورینگ عملکرد (APM)</H2>

تأخیر API و عملکرد درخواست‌های HTTP را ردیابی کنید.

#### ردیابی خودکار HTTP با 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
```

#### استفاده با 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
}
```

#### ردیابی عملیات دلخواه

```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)
```

#### گزارش دستی span

```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}>لاگ‌ها</H2>

ارسال لاگ ساخت‌یافته با دسته‌بندی (batching) و تلاش مجدد خودکار. یک بار فعالش کنید و سپس از هر جای برنامه از متدهای سطح‌ها استفاده کنید:

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

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

برای جزئیات کامل این مسیر (دسته‌بندی، سطح‌های لاگ، مدیریت چرخه‌ی عمر، ارسال دستی و تنظیمات) صفحه‌ی [لاگ‌ها در iOS SDK](/docs/trace/ios-logging) را ببینید.

<H2 id="configuration-options" step={9}>گزینه‌های تنظیمات</H2>

<ConfigTable rows={[
  ['apiKey', 'String', 'بله', 'کلید API پروژه (باید با ab_live_ شروع شود)'],
  ['environment', 'String', 'خیر', 'نام محیط (پیش‌فرض: "production")'],
  ['release', 'String?', 'خیر', 'شناسه‌ی نسخه‌ی برنامه (پیش‌فرض: CFBundleShortVersionString)'],
  ['debug', 'Bool', 'خیر', 'فعال کردن لاگ‌های debug (پیش‌فرض: false)'],
  ['enabled', 'Bool', 'خیر', 'فعال/غیرفعال کردن SDK (پیش‌فرض: true)'],
  ['sampleRate', 'Double', 'خیر', 'نرخ نمونه‌برداری ثبت خطا، ۰٫۰ تا ۱٫۰ (پیش‌فرض: 1.0)'],
  ['maxBreadcrumbs', 'Int', 'خیر', 'حداکثر تعداد breadcrumbهای نگه‌داشته‌شده (پیش‌فرض: 20)'],
  ['httpTimeout', 'TimeInterval', 'خیر', 'مهلت درخواست HTTP به ثانیه (پیش‌فرض: 30)'],
  ['enableOfflineStorage', 'Bool', 'خیر', 'خطاهایی را که به دلیل آفلاین بودن دستگاه فرستاده نشده‌اند روی دیسک نگه می‌دارد (تا ۱۰۰ مورد، با حذف قدیمی‌ترین‌ها) و در اجرای بعدی یا به محض ارسال موفق خطای دیگری می‌فرستد. فقط خطاها: پیام‌ها، لاگ‌ها و داده‌های عملکرد ذخیره نمی‌شوند. با false چیزی روی دیسک نمی‌ماند (پیش‌فرض: true)'],
  ['captureUncaughtExceptions', 'Bool', 'خیر', 'گرفتن exceptionهای مدیریت‌نشده (پیش‌فرض: true)'],
  ['captureSignalCrashes', 'Bool', 'خیر', 'تشخیص کرش‌های سیگنال (پیش‌فرض: true)'],
  ['captureAnr', 'Bool', 'خیر', 'تشخیص هنگ کردن main thread (پیش‌فرض: true)'],
  ['anrTimeoutMs', 'Int64', 'خیر', 'مهلت تشخیص ANR به میلی‌ثانیه (پیش‌فرض: 5000)'],
  ['apiUrl', 'String', 'خیر', 'آدرس پایه‌ی API، برای نصب self-hosted (پیش‌فرض: "https://trace.abrova.ir")'],
]} />

<H2 id="upload-debug-symbols-dsym" step={10}>آپلود نمادهای debug (dSYM)</H2>

برای دیدن نام فایل‌ها و شماره‌ی خط‌ها در stack traceهای iOS، فایل‌های dSYM برنامه را آپلود کنید. هر build فایل‌های dSYM مخصوص خودش را می‌سازد؛ برای هر نسخه‌ی release یک dSYM جدید آپلود کنید.

#### ۱. فایل‌های dSYM را پیدا کنید

پس از build برنامه در Xcode، فایل‌های dSYM در خروجی‌های build قرار دارند:

```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/
```

#### ۲. بسته‌ی dSYM را zip کنید

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

#### ۳. از طریق داشبورد آپلود کنید

در کنسول ابرووا به **ابرووا تریس › Source maps** بروید و تب **iOS dSYMs** را باز کنید. فایل zip را رها کنید، در صورت تمایل نسخه‌ی release را وارد کنید و روی Upload کلیک کنید. آپلود به نقش member یا بالاتر نیاز دارد و حذف dSYMهای آپلودشده به نقش admin یا owner؛ صفحه‌ی [نقش‌ها و دسترسی‌ها](/docs/trace/error-dashboard#roles) را ببینید.

endpoint آپلود dSYM فقط نشست ورود به کنسول را می‌پذیرد (نه کلید API و نه personal access token)، و `@abrova-trace/cli` فقط source map آپلود می‌کند؛ بنابراین dSYMها را از کنسول آپلود کنید.

<Callout kind="note" title="مهم">
  هر بار که برنامه را دوباره build می‌کنید، UUIDهای dSYM تغییر می‌کنند. اگر stack traceها نام توابع را نشان می‌دهند اما فایل و شماره‌ی خط ندارند، باید dSYM مربوط به همان build را آپلود کنید.
</Callout>

<H2 id="platform-support" step={11}>پلتفرم‌های پشتیبانی‌شده</H2>

- **iOS**: نسخه‌ی 12.0 به بالا
- **macOS**: نسخه‌ی 10.14 به بالا
- **tvOS**: نسخه‌ی 12.0 به بالا (فقط Swift Package Manager؛ spec مربوط به CocoaPods فقط iOS و macOS را پوشش می‌دهد)

از watchOS پشتیبانی نمی‌شود. build کردن SDK به Swift 5.10 یا بالاتر (Xcode 15.3 به بالا) نیاز دارد.

<H2 id="context-tags" step={12}>Context و تگ‌ها</H2>

متادیتای ثابت را به همه‌ی خطاها و پیام‌هایی که SDK ثبت می‌کند پیوست کنید (گزارش‌های کرش نیتیو و ANR، لاگ‌ها و spanهای عملکرد این اطلاعات را ندارند). این کار برای فیلتر کردن بر اساس تیم، منطقه، پرچم ویژگی یا گروه آزمایش در کنسول ابرووا مفید است.

#### extraهای سراسری

extraها جفت‌های کلید/مقدار دلخواه هستند (کلید رشته‌ای، هر مقدار قابل serialize) که به‌طور خودکار در همه‌ی رویدادها ادغام می‌شوند:

```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()
```

#### تگ‌ها

تگ‌ها جفت‌های کلید/مقدار فقط رشته‌ای برای دسته‌بندی رویدادها هستند:

```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="تفاوت تگ و extra">
از **تگ‌ها** برای فیلترهای دسته‌ای با تنوع کم (تیم، منطقه، build flavor) استفاده کنید. از **extraها** برای context غنی‌تر هر رویداد (شناسه‌ی کاربر، بدنه‌ی درخواست، مقادیر محاسبه‌شده).
</Callout>

<H2 id="swiftui-integration" step={13}>یکپارچگی با SwiftUI</H2>

SDK بدون مشکل با نقطه‌ی ورود `@main` در SwiftUI کار می‌کند. آن را در `init()` مربوط به struct `App` راه‌اندازی کنید تا خطاها از همان لحظه‌ی ساخته شدن سلسله‌مراتب viewها ثبت شوند:

```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؟">
در برنامه‌های UIKit، SDK را در `application(_:didFinishLaunchingWithOptions:)` داخل `AppDelegate` راه‌اندازی کنید؛ نمونه‌ی کامل پایین صفحه را ببینید.
</Callout>

### مرجع API

فهرست کامل متدهای `AbrovaTrace.shared` و `PerformanceSpan`. selectorها به سبک Swift نوشته شده‌اند و پارامترهای اختیاری در توضیح با `?` مشخص شده‌اند.

#### `AbrovaTrace.shared`: راه‌اندازی و چرخه‌ی عمر

<ConfigTable rows={[
  ['initialize(config:)', '-', '-', 'راه‌اندازی SDK با یک AbrovaTraceConfig کامل'],
  ['initialize(apiKey:)', '-', '-', 'راه‌اندازی SDK فقط با کلید API (با مقادیر پیش‌فرض)'],
  ['isReady', '-', '-', 'پس از راه‌اندازی SDK برابر true است'],
  ['close()', '-', '-', 'پاک‌سازی SDK و ارسال داده‌های در انتظار'],
]} />

#### ثبت خطا

<ConfigTable rows={[
  ['captureError(_:message:extra:tags:completion:)', '-', '-', 'ثبت یک Error در Swift'],
  ['captureException(_:message:extra:tags:completion:)', '-', '-', 'ثبت یک NSException'],
  ['captureMessage(_:level:extra:tags:completion:)', '-', '-', 'ارسال یک پیام به ابرووا تریس › پیام‌ها (مشکل نمی‌سازد)'],
]} />

#### کاربر و نشست

<ConfigTable rows={[
  ['setUserId(_:)', '-', '-', 'تنظیم شناسه‌ی کاربر فعلی'],
  ['getUserId()', '-', '-', 'دریافت شناسه‌ی کاربر فعلی'],
]} />

#### context سراسری (extraها)

<ConfigTable rows={[
  ['setExtra(_:value:)', '-', '-', 'تنظیم یک extra'],
  ['setExtras(_:)', '-', '-', 'تنظیم چند extra به‌صورت یک‌جا'],
  ['clearExtras()', '-', '-', 'پاک کردن همه‌ی extraها'],
]} />

#### تگ‌ها

<ConfigTable rows={[
  ['setTag(_:value:)', '-', '-', 'تنظیم یک تگ'],
  ['setTags(_:)', '-', '-', 'تنظیم چند تگ به‌صورت یک‌جا'],
  ['clearTags()', '-', '-', 'پاک کردن همه‌ی تگ‌ها'],
]} />

#### Breadcrumbها

<ConfigTable rows={[
  ['addBreadcrumb(_:type:data:)', '-', '-', 'افزودن یک breadcrumb عمومی'],
  ['addNavigationBreadcrumb(from:to:)', '-', '-', 'افزودن یک breadcrumb ناوبری'],
  ['addUserBreadcrumb(_:data:)', '-', '-', 'افزودن یک breadcrumb برای اقدام کاربر'],
  ['addHttpBreadcrumb(method:url:statusCode:duration:)', '-', '-', 'افزودن یک breadcrumb برای HTTP'],
  ['clearBreadcrumbs()', '-', '-', 'پاک کردن همه‌ی breadcrumbها'],
]} />

#### مانیتورینگ عملکرد

<ConfigTable rows={[
  ['reportPerformanceSpan(_:completion:)', '-', '-', 'گزارش یک PerformanceSpan ساخته‌شده'],
  ['reportPerformanceSpanBatch(_:completion:)', '-', '-', 'گزارش چند span به‌صورت یک‌جا'],
  ['trackHttpRequest(request:response:startTime:error:)', '-', '-', 'ردیابی یک درخواست HTTP منفرد'],
  ['enablePerformanceTracking()', '-', '-', 'روشن کردن ردیابی خودکار HTTP'],
  ['disablePerformanceTracking()', '-', '-', 'خاموش کردن ردیابی خودکار HTTP'],
  ['performanceSessionConfiguration(baseConfiguration:)', '-', '-', 'یک URLSessionConfiguration با ردیابی فعال برمی‌گرداند'],
  ['setPerformanceExcludedHosts(_:)', '-', '-', 'مستثنا کردن hostها از ردیابی خودکار'],
  ['setPerformanceMinDuration(_:)', '-', '-', 'تنظیم حداقل مدت span برای ثبت'],
]} />

#### لاگ‌ها

<ConfigTable rows={[
  ['enableLogging(sourceId:sourceName:batchSize:flushInterval:)', '-', '-', 'روشن کردن مسیر ارسال لاگ'],
  ['log(_:level:metadata:)', '-', '-', 'لاگ با سطح مشخص'],
  ['trace(_:metadata:)', '-', '-', 'لاگ با سطح trace'],
  ['logDebugMessage(_:metadata:)', '-', '-', 'لاگ با سطح debug'],
  ['info(_:metadata:)', '-', '-', 'لاگ با سطح info'],
  ['warn(_:metadata:)', '-', '-', 'لاگ با سطح warn'],
  ['logErrorMessage(_:metadata:)', '-', '-', 'لاگ با سطح error'],
  ['fatal(_:metadata:)', '-', '-', 'لاگ با سطح fatal'],
  ['flushLogs(completion:)', '-', '-', 'ارسال فوری لاگ‌های بافرشده'],
  ['pendingLogCount', '-', '-', 'تعداد لاگ‌هایی که هنوز در بافر مانده‌اند'],
]} />

#### متدهای سازنده‌ی `PerformanceSpan`

<ConfigTable rows={[
  ['PerformanceSpan.fromHttpRequest(...)', '-', '-', 'ساخت span از یک درخواست/پاسخ HTTP'],
  ['PerformanceSpan.forDbQuery(...)', '-', '-', 'ساخت span برای یک کوئری پایگاه داده'],
  ['PerformanceSpan.custom(...)', '-', '-', 'ساخت یک span کاملاً سفارشی'],
  ['PerformanceSpan.generateTraceId()', '-', '-', 'تولید یک trace ID تصادفی'],
  ['PerformanceSpan.generateSpanId()', '-', '-', 'تولید یک span ID تصادفی'],
]} />

### نمونه‌ی کامل

```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 { /* ... */ }
}
```

### توصیه‌ها

<BestPracticeList items={[
  ['راه‌اندازی در AppDelegate یا init برنامه', 'ابرووا تریس را هرچه زودتر راه‌اندازی کنید تا همه‌ی خطاها از لحظه‌ی شروع برنامه گرفته شوند'],
  ['close() هنگام بسته شدن برنامه', 'SDK با اعلان will-terminate خودش close() را صدا می‌زند تا لاگ‌ها فرستاده شوند؛ فقط برای مسیرهای خاموش شدن سفارشی خودتان صدایش بزنید'],
  ['فعال کردن ردیابی HTTP', 'برای breadcrumbهای خودکار HTTP و مانیتورینگ عملکرد، enablePerformanceTracking() را صدا بزنید'],
  ['افزودن context به خطاها', 'شناسه‌ی کاربر، نام صفحه و داده‌های مرتبط را در پارامتر extra بگذارید'],
  ['استفاده از محیط‌های جدا', 'خطاهای production، staging و development را با تنظیم environment از هم جدا کنید'],
  ['فعال کردن حالت debug در توسعه', 'در زمان توسعه debug: true را تنظیم کنید تا لاگ‌های SDK را ببینید و درستی یکپارچگی را بررسی کنید'],
  ['فعال کردن زودهنگام لاگ‌ها', 'enableLogging() را بلافاصله بعد از راه‌اندازی صدا بزنید تا همه‌ی رویدادهای برنامه ثبت شوند'],
]} />

- SDK لاراول: https://abrova.ir/docs/trace/laravel-sdk

<BestPracticeList columns={2} items={[
  ['ردیابی خطای سمت سرور', 'پایش کامل خطاها در برنامه‌های Laravel'],
  ['ثبت خودکار exceptionها', 'از طریق reportable() با exception handler در Laravel یکپارچه می‌شود'],
  ['Middleware برای Laravel', 'middleware داخلی HTTP برای ردیابی درخواست و پاسخ'],
  ['Breadcrumb', 'رویدادهای پیش از خطا را برای درک بهتر شرایط ثبت می‌کند'],
  ['ردیابی کوئری‌های پایگاه داده', 'breadcrumb خودکار و تشخیص کوئری‌های کند از طریق QueryExecuted'],
  ['اطلاعات کاربر', 'خطاها را خودکار به کاربرِ واردشده در Laravel مرتبط می‌کند'],
  ['یکپارچگی با Monolog', "برای لاگ ساختاریافته از Log::channel('abrovatrace') استفاده کنید"],
  ['پایش عملکرد', 'درخواست‌های HTTP، کوئری‌های پایگاه داده و عملیات دلخواه را ردیابی کنید'],
]} />

<H2 id="installation" step={1}>نصب</H2>

بسته از Abrova Center نصب می‌شود. دو مرحله دارد:

**۱. مخزن ابرووا را اضافه کنید** به فایل `composer.json`:

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

**۲. بسته را نصب کنید:**

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

فایل پیکربندی را publish کنید:

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

<H2 id="quick-start" step={2}>شروع سریع</H2>

کلیدها را به `.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">
  این SDK از قابلیت auto-discovery بسته‌ها در Laravel استفاده می‌کند. نیازی به ثبت دستی service provider یا facade نیست. facade آن `AbrovaTrace\Laravel\AbrovaTraceFacade` است (که خودکار با نام مستعار `AbrovaTrace` ثبت می‌شود). تا وقتی هر دو متغیر `ABROVATRACE_API_KEY` و `ABROVATRACE_SERVER_SECRET` تنظیم نشده باشند، SDK غیرفعال می‌ماند.
</Callout>

<H2 id="capture-errors" step={3}>ثبت خطاها</H2>

#### ثبت خودکار

همه‌ی exceptionهای مدیریت‌نشده خودکار از طریق exception handler در Laravel ثبت می‌شوند. نیازی به تغییر کد نیست.

exception همچنان در لاگ خود برنامه (`laravel.log` یا کانال‌های لاگ تنظیم‌شده) نوشته می‌شود، پس لازم نیست تنظیمات لاگ‌گیری را تغییر دهید. نسخه‌های پیش از 0.2.3، لاگ پیش‌فرض Laravel را برای exceptionهای ثبت‌شده متوقف می‌کردند.

#### ثبت دستی

```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'],
]);
```

هر exception فقط یک بار گزارش می‌شود. اگر آن را با `captureException()` ثبت کنید و دوباره throw کنید، ثبت خودکار آن را بار دوم نمی‌فرستد (از نسخه‌ی 0.2.3).

<Callout kind="note" title="پیام‌ها کجا نمایش داده می‌شوند">
پیام‌ها در کنسول، در بخش **ابرووا تریس › پیام‌ها** همراه با سطح، پلتفرم، داده‌های اضافه و breadcrumbها نمایش داده می‌شوند. پیام هیچ‌وقت مشکل (issue) نمی‌سازد. سطح `'warn'` به‌صورت `warning`؛ سطح‌های `'fatal'`، `'critical'`، `'alert'` و `'emergency'` به‌صورت `error`؛ سطح `'trace'` به‌صورت `debug` و هر مقدار دیگری به‌صورت `info` فرستاده می‌شود. پیام را برای چیزهایی به کار ببرید که برنامه عمداً گزارش می‌دهد («checkout شروع شد»، «همگام‌سازی تمام شد»)؛ برای عیب‌یابی پرحجم از Logs استفاده کنید.
</Callout>

<H2 id="breadcrumbs" step={4}>Breadcrumbها</H2>

Breadcrumbها رویدادهای پیش از خطا را ثبت می‌کنند. درخواست‌های HTTP و کوئری‌های پایگاه داده خودکار ثبت می‌شوند.

#### Breadcrumb دستی

```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="Breadcrumbهای خودکار">
  SDK به‌طور خودکار breadcrumbهای درخواست و پاسخ HTTP را از طریق middleware و breadcrumbهای کوئری پایگاه داده را از طریق listener رویداد QueryExecuted ثبت می‌کند. نیازی به تنظیم دستی نیست.
</Callout>

<H2 id="user-context" step={5}>اطلاعات کاربر</H2>

اطلاعات کاربر خودکار از کاربرِ واردشده و از طریق middleware برداشته می‌شود. می‌توانید آن را دستی هم تعیین کنید:

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

<H2 id="scoped-context" step={6}>Context محدود به یک بلوک</H2>

با context محدود می‌توانید اطلاعات کاربر و درخواست را برای هر عملیات جدا کنید. هر دو بعد از آن خودکار به حالت قبل برمی‌گردند (breadcrumbهایی که داخل closure اضافه شده‌اند باقی می‌مانند). closure نمونه‌ی SDK را دریافت می‌کند.

```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}>Middleware برای Laravel</H2>

middleware خودکار روی گروه‌های web و api ثبت می‌شود و این کارها را انجام می‌دهد:

- **ردیابی درخواست** — درخواست ورودی را به‌صورت breadcrumb (متد و path) ثبت می‌کند و context درخواست (متد، URL، path، route، IP، user agent) را تعیین می‌کند
- **ردیابی پاسخ** — breadcrumb پاسخ را با کد وضعیت و مدت زمان ثبت می‌کند
- **برداشتن اطلاعات کاربر** — اطلاعات کاربر (id، email، name) را خودکار از کاربرِ واردشده تعیین می‌کند (`middleware.track_user`)
- **Spanهای عملکرد** — برای هر درخواست یک span عملکرد HTTP می‌سازد (وقتی `performance.enabled` برابر true باشد)

برای تغییر pathهای نادیده‌گرفته‌شده، فایل `config/abrovatrace.php` را ویرایش کنید:

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

<H2 id="database-query-tracking" step={8}>ردیابی کوئری‌های پایگاه داده</H2>

کوئری‌های پایگاه داده خودکار از طریق رویداد QueryExecuted در Laravel ردیابی می‌شوند (`performance.track_db_queries`). هر کوئری یک breadcrumb می‌شود؛ کوئری‌هایی که مدتشان برابر یا بیشتر از آستانه باشد (پیش‌فرض ۵۰۰ میلی‌ثانیه) span عملکرد هم می‌سازند.

```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</H2>

لاگ‌ها را با سیستم لاگ‌گیری داخلی Laravel به ابرووا تریس بفرستید:

```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">
  می‌توانید abrovatrace را به یک کانال stack اضافه کنید تا لاگ‌ها هم‌زمان به چند مقصد فرستاده شوند.
</Callout>

برای رفتار ارسال دسته‌ای، سطح‌های لاگ و flush دستی، صفحه‌ی [لاگ‌گیری در SDK برای Laravel](/docs/trace/laravel-logging) را ببینید.

<H2 id="performance-tracking" step={10}>ردیابی عملکرد</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}>گزینه‌های پیکربندی</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', 'بله', 'کلید API پروژه (ab_live_xxx)'],
  ['server_secret', 'string', 'بله', 'کلید سرور (ab_srv_xxx)'],
  ['enabled', 'boolean', 'خیر', 'روشن/خاموش کردن ردیابی (پیش‌فرض: true)'],
  ['environment', 'string', 'خیر', 'نام محیط (پیش‌فرض: APP_ENV، وگرنه "production")'],
  ['release', 'string', 'خیر', 'شناسه‌ی نسخه‌ی برنامه (پیش‌فرض: "0.1.0")'],
  ['sample_rate', 'float', 'خیر', 'نرخ نمونه‌برداری برای خطاها و پیام‌ها، 0.0 تا 1.0 (پیش‌فرض: 1.0)'],
  ['before_send', 'callable', 'خیر', 'هر خطا (AbrovaTraceError) یا پیام (AbrovaTraceMessage) را دریافت می‌کند؛ برای ارسال، همان را (یا نسخه‌ی اصلاح‌شده را) برگردانید و برای حذف null. آن را از یک service provider تعیین کنید، چون closure نمی‌تواند در config کش‌شده قرار بگیرد'],
  ['debug', 'boolean', 'خیر', 'فعال کردن لاگ عیب‌یابی (پیش‌فرض: false)'],
  ['timeout', 'integer', 'خیر', 'مهلت HTTP بر حسب ثانیه (پیش‌فرض: 5، حداکثر: 30)'],
  ['max_breadcrumbs', 'integer', 'خیر', 'حداکثر تعداد breadcrumbهای نگه‌داشته‌شده، 0 تا 100 (پیش‌فرض: 50)'],
]} />

<H2 id="ignored-exceptions" step={12}>exceptionهای نادیده‌گرفته‌شده</H2>

SDK برای exceptionهایی که برنامه‌های Laravel معمولاً نمی‌خواهند به‌عنوان خطا ببینند، پیش‌فرض‌های معقولی دارد. به‌طور پیش‌فرض این‌ها گزارش **نمی‌شوند**:

- `AuthenticationException` — درخواست‌های بدون احراز هویت
- `ValidationException` — خطاهای اعتبارسنجی فرم
- `NotFoundHttpException` — خطاهای 404
- همه‌ی exceptionهای HTTP با کد 4xx

از طریق `config/abrovatrace.php` تغییرشان دهید:

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

فهرست `ignored_exceptions` که تعیین می‌کنید جای فهرست پیش‌فرض را می‌گیرد؛ پس مواردی از پیش‌فرض را که هنوز می‌خواهید نادیده گرفته شوند، در فهرست نگه دارید.

<Callout kind="note" title="چرا 4xx به‌طور پیش‌فرض کنار گذاشته می‌شود">
پاسخ‌های 4xx خطای سمت کلاینت هستند و ثبت دوباره‌شان به‌عنوان exception، فهرست خطاها را شلوغ می‌کند. اگر واقعاً می‌خواهید ثبت شوند (مثلاً برای تحلیل)، `report_4xx` را `true` کنید.
</Callout>

### مرجع API

#### Facade ابرووا تریس

- `captureException($e, $options?)` — ثبت یک exception
- `captureMessage($msg, $options?)` — ارسال پیام به ابرووا تریس › پیام‌ها (`$options`: `level`، `extra`، `tags`)
- `addBreadcrumb($breadcrumb)` — افزودن یک breadcrumb
- `setUser($user)` — تعیین اطلاعات کاربر
- `setRequestContext($context)` — تعیین context درخواست
- `withScope($callback)` — اجرای کد با context جداگانه‌ی کاربر و درخواست
- `log($message, $level?, $metadata?)` — ارسال یک لاگ (شناسه‌ی کاربر از `setUser()` گرفته می‌شود)
- `trace()`، `logDebug()`، `info()`، `warn()`، `logError()`، `fatal()` — لاگ در یک سطح مشخص (`$message, $metadata?`)
- `trackOperation($name, $callback, $options?)` — ردیابی عملیات با زمان‌سنجی خودکار (`$options`: `operationType`، `tags`)
- `reportPerformanceSpan($span)` — گزارش یک span عملکرد
- `flush()` — ارسال لاگ‌ها و spanهای عملکرد در بافر (هنگام خاموش شدن هم خودکار اجرا می‌شود)
- `isEnabled()` — بررسی فعال بودن SDK
- `getStats()` — گرفتن آمار SDK

#### توابع کمکی Breadcrumb

- `Breadcrumb::http($method, $url, $status?, $duration?)` — breadcrumb برای درخواست HTTP
- `Breadcrumb::database($query, $duration, $error?)` — breadcrumb برای کوئری پایگاه داده
- `Breadcrumb::user($action, $data?)` — breadcrumb برای کار کاربر
- `Breadcrumb::navigation($from, $to, $method?)` — breadcrumb برای جابه‌جایی بین صفحه‌ها
- `Breadcrumb::custom($message, $category, $data?)` — breadcrumb دلخواه

### پیش‌نیازها

- **PHP** — >= 8.1
- **Laravel** — 10.x / 11.x / 12.x
- **Guzzle** — >= 7.0 (همراه Laravel نصب است)

### نمونه‌ی کامل

```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);
});
```

### توصیه‌ها

<BestPracticeList items={[
  ['از متغیرهای محیطی استفاده کنید', 'کلید API و کلید سرور را در .env نگه دارید و هرگز آن‌ها را commit نکنید'],
  ['از auto-discovery بهره ببرید', 'service provider خودکار ثبت می‌شود و نیازی به ثبت دستی نیست'],
  ['از کانال Monolog استفاده کنید', "برای لاگ متمرکز، لاگ‌های ساختاریافته را با Log::channel('abrovatrace') بفرستید"],
  ['اطلاعات کاربر را تعیین کنید', 'اطلاعات کاربر خودکار از Auth برداشته می‌شود، اما در احراز هویت با توکن API آن را دستی تعیین کنید'],
  ['Breadcrumb اضافه کنید', 'breadcrumbهای HTTP و پایگاه داده خودکارند؛ برای منطق کسب‌وکار breadcrumb دلخواه اضافه کنید'],
  ['pathهای نادیده‌گرفته‌شده را تنظیم کنید', 'health checkها و routeهای debug را از ردیابی middleware کنار بگذارید'],
  ['کوئری‌های کند را ردیابی کنید', 'مقدار slow_query_threshold_ms را تعیین کنید تا افت عملکرد را زود ببینید'],
  ['از trackOperation() استفاده کنید', 'درخواست‌های API خارجی و عملیات سنگین را برای پایش عملکرد داخل آن قرار دهید'],
]} />

- نصب داخل ایران: https://abrova.ir/docs/trace/install-in-iran

SDKهای ابرووا از [Abrova Center](https://center.abrova.ir) نصب می‌شوند که داخل ایران است. هر SDK چند پکیج رایج دیگر هم لازم دارد (مثلاً AndroidX، OkHttp یا `http` برای Dart). این‌ها از مخزن‌های عمومی می‌آیند؛ بعضی‌شان به آدرس‌های ایرانی جواب نمی‌دهند یا با قطع اینترنت بین‌الملل از دسترس خارج می‌شوند. این صفحه نشان می‌دهد چطور آن‌ها را از mirrorهای داخل ایران بگیرید.

<Callout kind="note" title="آزموده از داخل ایران">
  همه‌ی آدرس‌های این صفحه در ۵ آبان ۱۴۰۵ از یک سرور داخل ایران و با همان پکیج‌هایی که SDKهای ابرووا لازم دارند بررسی شده‌اند. این mirrorها را شرکت‌های ایرانی دیگری اداره می‌کنند، نه ابرووا؛ پس ممکن است آدرسشان تغییر کند.
</Callout>

| پلتفرم | SDK ابرووا | وابستگی‌ها، داخل ایران |
|---|---|---|
| Android | Abrova Center | mirror مِیوِن مایکت: پکیج‌های Google و Maven Central و پلاگین Gradle اندروید |
| iOS | Abrova Center | لازم نیست: SDK وابستگی دیگری ندارد |
| Node.js، Next.js، CLI | Abrova Center | mirror npm رانفلر |
| Flutter | Abrova Center | mirror داخل ایران ندارد: pub.dev به آدرس‌های ایرانی جواب نمی‌دهد (پایین‌تر) |
| Laravel / PHP | Abrova Center | mirror داخل ایران ندارد: Packagist امروز از ایران در دسترس است |

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

در `settings.gradle`، mirror ایرانی را پیش از Google و Maven Central بیاورید؛ هم برای پلاگین‌ها و هم برای کتابخانه‌ها:

```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 مخزن‌ها را به همین ترتیب امتحان می‌کند؛ پس `google()` و `mavenCentral()` فقط برای پکیجی به کار می‌روند که mirror ندارد.

خود Gradle برای هر نسخه یک بار از `services.gradle.org` دانلود می‌شود (`distributionUrl` در `gradle/wrapper/gradle-wrapper.properties`). آن فایل را روی سیستمتان نگه دارید، یا روی سروری که در اختیار دارید بگذارید و `distributionUrl` را به آن اشاره دهید.

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

کار اضافه‌ای لازم نیست: SDK آی‌اواس از Abrova Center نصب می‌شود و هر چه لازم دارد همراهش است. خط‌های Swift Package Manager و CocoaPods را در [SDK آی‌اواس](/docs/trace/ios-sdk) ببینید.

<H2 id="nodejs" step={3}>Node.js، Next.js و CLI</H2>

در فایل `.npmrc` پروژه، mirror ایرانی npm را برای همه‌ی پکیج‌ها و Abrova Center را برای پکیج‌های ابرووا بگذارید:

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

سپس مثل همیشه نصب کنید (`npm install`، `pnpm install` یا `yarn`).

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

پکیج Flutter ابرووا از Abrova Center می‌آید. وابستگی‌هایش (`http`، `path_provider`، `device_info_plus` و چند پکیج دیگر) از pub.dev می‌آیند و **pub.dev به آدرس‌های ایرانی جواب نمی‌دهد**. mirror برای pub داخل ایران پیدا نکردیم. راه‌هایی که کار می‌کنند:

- `flutter pub get` را یک بار از اتصالی اجرا کنید که به pub.dev می‌رسد. پکیج‌ها در pub cache می‌مانند و بیلدهای بعدی بدون pub.dev کار می‌کنند.
- `pubspec.lock` را در git نگه دارید تا همه‌ی سیستم‌ها و CI همان نسخه‌ها را از cache بگیرند.
- یا `PUB_HOSTED_URL=https://pub.flutter-io.cn` را تنظیم کنید (mirror عمومی که جامعه‌ی Flutter در چین اداره می‌کند). از ایران جواب می‌دهد، ولی خارج از ایران است؛ پس با قطع اینترنت بین‌الملل کار نمی‌کند.

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

پکیج ابرووا از Abrova Center می‌آید. وابستگی‌هایش (`guzzlehttp/guzzle` و `illuminate/*`) از Packagist می‌آیند که امروز از ایران جواب می‌دهد؛ mirror داخل ایران برای Packagist پیدا نکردیم. Composer هر چه دانلود کند در cache خودش نگه می‌دارد و `composer.lock` نسخه‌ها را ثابت می‌کند.

<H2 id="when-the-internet-is-cut" step={6}>وقتی اینترنت بین‌الملل قطع است</H2>

- **کار می‌کند:** Abrova Center، mirrorهای مایکت و رانفلر، و هر چه از قبل در cache سیستمتان هست.
- **کار نمی‌کند:** pub.dev، Packagist، CocoaPods trunk، GitHub و `services.gradle.org`.

فایل‌های lock (`pubspec.lock`، `package-lock.json`، `composer.lock`، `Package.resolved`، `Podfile.lock`) را در git نگه دارید تا یک checkout تازه کمترین دانلود را لازم داشته باشد.

- دستیارهای هوش مصنوعی (به‌زودی): https://abrova.ir/docs/trace/ai-assistants

<Callout kind="soon" title="به‌زودی">
ابرووا هنوز سرور مستندات برای دستیارهای هوش مصنوعی ندارد. این صفحه توضیح می‌دهد که این سرور چطور کار خواهد کرد و امروز از چه چیزی می‌توانید استفاده کنید.
</Callout>

وقتی آماده شود، دستیار هوش مصنوعی خود را (هر ابزاری که از MCP، استاندارد باز اتصال ابزارهای هوش مصنوعی به منابع بیرونی، پشتیبانی کند) یک بار به آن وصل می‌کنید. از آن به بعد، وقتی از دستیار بخواهید ابرووا تریس را به پروژه‌تان اضافه کند، نسخه‌ی فعلی SDK، دستور نصب و مراحل راه‌اندازی را از همین مستندات می‌خواند و از حافظه‌ی خودش جواب نمی‌دهد.

### آنچه امروز کار می‌کند

- **Copy page for AI.** هر صفحه‌ی مستندات یک لینک **Copy page for AI** دارد. پیش از آنکه از دستیار بخواهید کد بنویسد، صفحه را در گفتگو با او جای‌گذاری کنید.
- **مستندات متنی.** آدرس `https://abrova.ir/docs/llms.txt` را به دستیار خود بدهید. این آدرس همه‌ی صفحه‌های مستندات را به‌صورت متن ساده فهرست می‌کند؛ قالبی که دستیارها به‌خوبی می‌خوانند.

به دستیار بگویید از صفحه‌ای که به او داده‌اید پیروی کند، SDK را همان‌طور که صفحه نشان می‌دهد از Abrova Center نصب کند و از کلیدهای نمونه‌ی مستندات استفاده کند.

### چه کاری خواهد کرد

سرور مستندات ابزارهایی فقط‌خواندنی خواهد داشت. دستیار شما خودش آن‌ها را انتخاب می‌کند؛ لازم نیست دستی صدایشان بزنید.

<ConfigTable headers={['ابزار', 'چه کاری خواهد کرد']} rows={[
  ['list_products', 'محصولات ابرووا را همراه با پلتفرم‌هایی که SDK دارند و لینک مستندات فهرست می‌کند.'],
  ['search_docs', 'مستندات را برای چند کلمه یا یک سؤال کوتاه جستجو می‌کند و بهترین صفحه‌ها را برمی‌گرداند.'],
  ['read_doc', 'یک صفحه‌ی مستندات را به‌صورت متن، همراه با لینک و تاریخ آخرین به‌روزرسانی برمی‌گرداند.'],
  ['get_sdk_info', 'بسته‌ی SDK یک محصول و پلتفرم را برمی‌گرداند: نام، نسخه‌ی فعلی و دستورهای نصب.'],
  ['get_setup_guide', 'مراحل راه‌اندازی یک محصول و پلتفرم را به ترتیب برمی‌گرداند: نصب، کلیدها، مقداردهی اولیه و روش آزمایش.'],
]} />

نمونه‌هایی از چیزهایی که می‌توانید بپرسید:

- **«ابرووا تریس را در این پروژه‌ی Next.js راه‌اندازی کن و source mapها را آپلود کن.»** پاسخ از صفحه‌های [SDK برای Next.js](/docs/trace/nextjs-sdk) و [آپلود source map](/docs/trace/upload-source-maps) می‌آید.
- **«ابرووا تریس را به اپ Laravel من اضافه کن و قبل از فراخوانی پرداخت یک breadcrumb ثبت کن.»** پاسخ از صفحه‌های [SDK برای Laravel](/docs/trace/laravel-sdk) و [Breadcrumbها](/docs/trace/breadcrumbs) می‌آید.
- **«به cron شبانه‌ام یک check-in اضافه کن و هشدارهای ابرووا تریس را به تلگرام بفرست.»** پاسخ از [مانیتورینگ cron](/docs/trace/cron-monitoring) و [تلگرام](/docs/trace/telegram) می‌آید.
- **«لاگ همه‌ی کانتینرهای Docker سرورم را به ابرووا تریس بفرست.»** پاسخ از [ایجنت ابرووا تریس](/docs/trace/agent) می‌آید.
- **«کدام کلید ابرووا در اپ قرار می‌گیرد و کدام روی سرور می‌ماند؟»** پاسخ از [کلید سرور و مسیرهای سرور](/docs/trace/server-secret) می‌آید.

### حریم خصوصی

- **آنچه می‌خواند:** مستندات عمومی ابرووا، نسخه‌های فعلی SDKها و کلماتی که دستیار شما می‌فرستد (کلمات جستجو، صفحه‌ای که می‌خواهد، نام محصول و پلتفرم).
- **آنچه هرگز نمی‌بیند:** کد، فایل‌ها، پروژه‌ی ابرووا، کلیدها یا کاربران شما. ابزارها هیچ ورودی‌ای برای این‌ها ندارند و نمی‌توانند هیچ تنظیمی را تغییر دهند.

<Callout kind="warn" title="کلیدهایتان را در گفتگو نگذارید">
هرگز کلیدی را در گفتگو با دستیار هوش مصنوعی جای‌گذاری نکنید. دستیار شما کلید نمونه‌ی مستندات (`ab_live_your_api_key`) را می‌نویسد و مقدار واقعی را خودتان در تنظیمات پروژه قرار می‌دهید. کلید سرور (`ab_srv_...`) فقط روی سرور شما و در یک متغیر محیطی جا دارد.
</Callout>

اطلاعات بیشتر درباره‌ی دستیارهای هوش مصنوعی و ابرووا: [دستیارهای هوش مصنوعی](/ai-assistants). سؤالی دارید؟ [با ما تماس بگیرید](/contact).

- معرفی APM: https://abrova.ir/docs/trace/apm

APM ابرووا تریس عملکرد همه‌ی اپلیکیشن‌های شما را به‌صورت لحظه‌ای مانیتور می‌کند. تأخیر درخواست‌های HTTP، کوئری‌های دیتابیس و عملیات سفارشی را با صدک‌های p50، p95 و p99 دنبال کنید. برای اپ‌های وب، Core Web Vitals (یعنی LCP، INP و CLS و همچنین TTFB و FCP) را هم مانیتور کنید.

<BestPracticeList columns={2} items={[
  ['ردیابی تأخیر API', 'زمان درخواست و پاسخ HTTP را با صدک‌های p50، p95 و p99 مانیتور کنید'],
  ['Core Web Vitals', 'معیارهای LCP، INP، CLS، TTFB و FCP برای پلتفرم‌های وب'],
  ['عملیات سفارشی', 'هر عملیات async را با اندازه‌گیری خودکار مدت‌زمان دنبال کنید'],
  ['تحلیل صدک‌ها', 'معیارهای تأخیر p50، p95 و p99 برای دیدی دقیق'],
  ['ارسال دسته‌ای', 'آپلود دسته‌ای و بهینه‌ی spanها برای کم کردن بار شبکه'],
  ['چندپلتفرمی', 'روی Next.js، Flutter، Android، iOS، Node.js و Laravel کار می‌کند'],
]} />

<Callout kind="wallet" title="بدون هزینه‌ی اضافه">
  APM بدون هزینه‌ی اضافه جزو ابرووا تریس است. spanها و Web Vitals مشکل جدید حساب نمی‌شوند، پس از سهمیه‌ی رایگان ماهانه یا کیف پول شما کم نمی‌کنند.
</Callout>

### نگهداری داده

spanها و Web Vitals به اندازه‌ی دوره‌ی نگهداری داده‌ی پروژه‌ی شما نگه داشته می‌شوند: ۷ روز رایگان، یا ۳۰ روز با ۵۰٬۰۰۰ تومان برای هر پروژه در ماه، هزینه از کیف پول. جزئیات در [قیمت‌ها](/pricing).

### ساختار Performance Span

هر عملیاتی که دنبال می‌شود یک Performance Span با این فیلدها می‌سازد:

```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;
}
```

### شروع سریع برای هر 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' }
);
```

### دیدن داده‌ها در داشبورد

بعد از فعال شدن ردیابی، در کنسول ابرووا به **ابرووا تریس &rarr; Performance** بروید تا این‌ها را ببینید:

- **آمار کلی**: تعداد درخواست‌ها، نرخ خطا و تأخیر p50، p95 و p99
- **تأخیر**: p50، p95 و p99 در طول زمان، به‌همراه تعداد درخواست‌ها در طول زمان با خطاهای روی هم
- **عملیات**: هر عملیات با نوع، تعداد درخواست، صدک‌های تأخیر و خطاهایش
- کارت‌های **کدهای وضعیت، Web Vitals و درخواست‌های ناموفق**
- **فیلتر**: بازه‌ی زمانی (۱ ساعت، ۲۴ ساعت، ۷ روز، ۳۰ روز یا دلخواه)، پلتفرم، محیط و release

### Endpointهای API

SDKها spanها را به این endpointها می‌فرستند:

<div>
  <table>
    <thead>
      <tr>
        {['Endpoint', 'متد', 'توضیح'].map((h) => (
          <th key={h}>{h}</th>
        ))}
      </tr>
    </thead>
    <tbody>
      {[
        ['/api/performance/spans', 'POST', 'ارسال یک span'],
        ['/api/performance/spans/batch', 'POST', 'ارسال دسته‌ای (حداکثر ۵۰)'],
        ['/api/performance/web-vitals', 'POST', 'ارسال داده‌های Web Vitals'],
      ].map(([endpoint, method, desc]) => (
        <tr key={endpoint}>
          <td>{endpoint}</td>
          <td>{method}</td>
          <td>{desc}</td>
        </tr>
      ))}
    </tbody>
  </table>
</div>

### بهترین روش‌ها

<BestPracticeList items={[
  ['نام‌های معنادار برای عملیات', 'به‌جای نام‌های کلی از نام‌های گویا مثل «GET /api/users» استفاده کنید تا راحت‌تر شناخته شوند'],
  ['تگ سفارشی اضافه کنید', 'تگ‌هایی مثل شناسه‌ی کاربر، شناسه‌ی tenant یا feature flag اضافه کنید تا داده‌ها را فیلتر و تفکیک کنید'],
  ['محیط را درست تنظیم کنید', 'همیشه محیط (production، staging، development) را تنظیم کنید تا داده‌ها از هم جدا بمانند'],
  ['به p95/p99 نگاه کنید، نه فقط میانگین', 'میانگین تأخیر موارد پرت را پنهان می‌کند؛ برای بدترین تجربه‌ی کاربر روی p95 و p99 تمرکز کنید'],
  ['از ارسال دسته‌ای استفاده کنید', 'SDKها به‌طور پیش‌فرض spanها را دسته‌ای می‌فرستند؛ تا جای ممکن spanها را تک‌تک ارسال نکنید'],
  ['endpointهای health check را کنار بگذارید', 'endpointهای پرسروصدا مثل /health یا /ping را از ردیابی حذف کنید'],
]} />

- ردیابی تأخیر API: https://abrova.ir/docs/trace/api-latency

ردیابی تأخیر API زمان‌بندی همه‌ی درخواست‌های HTTP اپلیکیشن شما را ثبت می‌کند. SDK کلاینت‌های HTTP را به‌طور خودکار ابزارگذاری می‌کند، مدت هر درخواست را می‌سنجد و این داده را برای تحلیل با صدک‌های p50، p95 و p99 به ابرووا تریس می‌فرستد.

<BestPracticeList columns={2} items={[
  ['متد HTTP', 'GET، POST، PUT، DELETE، PATCH و غیره'],
  ['URL و Host درخواست', 'URL کامل و host برای گروه‌بندی'],
  ['کد وضعیت پاسخ', '200، 404، 500 و غیره'],
  ['مدت‌زمان', 'مدت درخواست بر حسب میلی‌ثانیه'],
  ['پیام‌های خطا', 'جزئیات خطا اگر درخواست ناموفق باشد'],
  ['تگ‌های سفارشی', 'هر متادیتای اضافه‌ای که خودتان ضمیمه کنید'],
]} />

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

#### ردیابی خودکار

رهگیری خودکار fetch را فعال کنید تا همه‌ی درخواست‌های HTTP دنبال شوند:

```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)
});
```

#### ردیابی دستی عملیات

```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' }
  }
);
```

#### Wrapper برای fetch

```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();
```

این wrapper فقط وقتی span می‌فرستد که قبلاً `enablePerformanceTracking()`، `trackOperation()` یا `reportPerformanceSpan()` صدا زده شده باشد. در مرورگر، `enablePerformanceTracking()` خودش همه‌ی `fetch`ها را دنبال می‌کند، پس wrapper را سمت سرور به کار ببرید.

#### ارسال دستی span

```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>

#### کلاینت HTTP عملکرد

با PerformanceHttpClient همه‌ی درخواست‌های HTTP خودکار دنبال می‌شوند:

```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();
```

#### ردیابی عملیات سفارشی

```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>

#### Interceptor عملکرد برای OkHttp

```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()
}
```

#### همراه با 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
```

#### ارسال دستی span

```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>

#### ردیابی خودکار URLSession

```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)
```

#### پیکربندی

```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
```

#### ردیابی دستی

```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>

#### ردیابی عملیات

در SDK مربوط به Node.js ثبت خودکار span برای HTTP وجود ندارد. کاری را که می‌خواهید زمان‌سنجی شود داخل `trackOperation` بگذارید، یا spanها را خودتان با `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);
});
```

#### Middleware برای Express.js

این middleware هر درخواست (متد، URL، وضعیت و مدت) را به‌صورت یک **breadcrumb** از نوع HTTP ثبت می‌کند که به خطاها ضمیمه می‌شود، نه به‌صورت Performance span:

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

// Your routes

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

#### ردیابی کوئری‌های دیتابیس

```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;
  }
}
```

### نمای داشبورد

داشبورد عملکرد داده‌های تأخیر را در این نماها نشان می‌دهد:

<div>
  {[
    ['آمار کلی', ['تعداد درخواست‌ها', 'نرخ خطا', 'تأخیر p50', 'تأخیر p95 / p99']],
    ['تأخیر', ['p50، p95 و p99 در طول زمان', 'تعداد درخواست‌ها در طول زمان، با خطاهای روی هم']],
    ['عملیات', ['نام و نوع عملیات', 'تعداد درخواست و صدک‌های تأخیر', 'تعداد خطا', 'کارت‌های کدهای وضعیت، Web Vitals و درخواست‌های ناموفق']],
    ['فیلتر', ['بازه‌ی زمانی (۱ ساعت، ۲۴ ساعت، ۷ روز، ۳۰ روز یا دلخواه)', 'پلتفرم', 'محیط', 'Release']],
  ].map(([title, items]) => (
    <div key={title}>
      <h4>{title}</h4>
      <ul>
        {items.map((item) => (
          <li key={item}>&#8226; {item}</li>
        ))}
      </ul>
    </div>
  ))}
</div>

### بهترین روش‌ها

<BestPracticeList items={[
  ['نام‌های معنادار برای عملیات', 'به‌جای نام‌های کلی از نام‌های گویا مثل «GET /api/users» استفاده کنید تا راحت‌تر شناخته شوند'],
  ['تگ سفارشی اضافه کنید', 'تگ‌هایی مثل شناسه‌ی کاربر، شناسه‌ی tenant یا feature flag اضافه کنید تا داده‌ها را در داشبورد فیلتر و تفکیک کنید'],
  ['محیط را درست تنظیم کنید', 'همیشه محیط (production، staging، development) را تنظیم کنید تا داده‌ی deployهای مختلف از هم جدا بماند'],
  ['به p95/p99 نگاه کنید، نه فقط میانگین', 'میانگین تأخیر موارد پرت را پنهان می‌کند؛ برای بدترین تجربه‌ی کاربر روی p95 و p99 تمرکز کنید'],
  ['نویز را حذف کنید', 'endpointهای health check و فراخوانی‌های داخلی SDK را از ردیابی کنار بگذارید'],
  ['از ارسال دسته‌ای استفاده کنید', 'بگذارید SDK spanها را دسته‌ای بفرستد؛ اگر خودتان span زیادی می‌فرستید از reportPerformanceSpanBatch استفاده کنید'],
]} />

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

Core Web Vitals مجموعه‌ای از معیارهای تعریف‌شده توسط Google است که تجربه‌ی واقعی کاربر را در سرعت بارگذاری، پاسخ‌گویی و پایداری بصری می‌سنجد. این معیارها مستقیم روی رتبه‌ی SEO و رضایت کاربر اثر می‌گذارند. ابرووا تریس برای سنجش دقیق از کتابخانه‌ی رسمی **web-vitals** گوگل استفاده می‌کند.

<Callout kind="note" title="فقط مرورگر">
  Web Vitals معیارهای مخصوص مرورگر هستند. فعلاً فقط SDK مربوط به Next.js (`@abrova-trace/nextjs-sdk`) آن‌ها را می‌فرستد. برای اپ‌های موبایل (iOS، Android، Flutter) به‌جای آن از ردیابی تأخیر API استفاده کنید.
</Callout>

### توضیح معیارها

<div>
  <div>
    <div>
      <div>
        <h4>LCP &mdash; Largest Contentful Paint</h4>
        <p>
          سرعت بارگذاری را می‌سنجد. لحظه‌ای را نشان می‌دهد که بزرگ‌ترین عنصر محتوا (تصویر، ویدیو یا بلوک متن) دیده می‌شود.
        </p>
      </div>
    </div>
    <div>
      <div>
        <div></div>
        <div>خوب</div>
        <div>&le;2.5s</div>
      </div>
      <div>
        <div></div>
        <div>نیاز به بهبود</div>
        <div>2.5&ndash;4s</div>
      </div>
      <div>
        <div></div>
        <div>ضعیف</div>
        <div>&gt;4s</div>
      </div>
    </div>
  </div>

  <div>
    <div>
      <div>
        <h4>INP &mdash; Interaction to Next Paint</h4>
        <p>
          پاسخ‌گویی کلی صفحه را می‌سنجد. همه‌ی تعامل‌ها را زیر نظر می‌گیرد و بدترین تأخیر را گزارش می‌کند.
        </p>
      </div>
    </div>
    <div>
      <div>
        <div></div>
        <div>خوب</div>
        <div>&le;200ms</div>
      </div>
      <div>
        <div></div>
        <div>نیاز به بهبود</div>
        <div>200&ndash;500ms</div>
      </div>
      <div>
        <div></div>
        <div>ضعیف</div>
        <div>&gt;500ms</div>
      </div>
    </div>
  </div>

  <div>
    <div>
      <div>
        <h4>CLS &mdash; Cumulative Layout Shift</h4>
        <p>
          پایداری بصری را می‌سنجد. مجموع همه‌ی جابه‌جایی‌های غیرمنتظره‌ی چیدمان در طول عمر صفحه است.
        </p>
      </div>
    </div>
    <div>
      <div>
        <div></div>
        <div>خوب</div>
        <div>&le;0.1</div>
      </div>
      <div>
        <div></div>
        <div>نیاز به بهبود</div>
        <div>0.1&ndash;0.25</div>
      </div>
      <div>
        <div></div>
        <div>ضعیف</div>
        <div>&gt;0.25</div>
      </div>
    </div>
  </div>

  <div>
    {[
      ['TTFB', 'Time to First Byte', 'زمان پاسخ سرور', '≤800ms'],
      ['FCP', 'First Contentful Paint', 'سرعت بارگذاری از نگاه کاربر', '≤1.8s'],
    ].map(([abbr, name, desc, good]) => (
      <div key={abbr}>
        <h4>{abbr}</h4>
        <p>{name}</p>
        <p>{desc}</p>
        <p>خوب: {good}</p>
      </div>
    ))}
  </div>
</div>

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

#### راه‌اندازی پایه

```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;
```

#### گزینه‌های پیشرفته

```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}>ساختار داده</H2>

داده‌های Web Vitals با این ساختار ارسال می‌شوند:

```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}>نمای داشبورد</H2>

در کنسول ابرووا، صفحه‌ی **ابرووا تریس ← Performance** کارت جداگانه‌ای برای Web Vitals دارد: صدک ۷۵ام (p75) هر معیار در بازه‌ی انتخاب‌شده، با رتبه‌ی خوب / نیاز به بهبود / ضعیف بر اساس آستانه‌های بالا.

<div>
  <h4>کارت Core Web Vitals</h4>
  <div>
    {[
      ['LCP', '1.8s', 'خوب', 'green'],
      ['INP', '120ms', 'خوب', 'green'],
      ['CLS', '0.15', 'نیاز به بهبود', 'yellow'],
      ['FCP', '1.2s', 'خوب', '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}>بهتر کردن امتیازها</H2>

<div>
  <div>
    <h4>بهبود LCP</h4>
    <ul>
      <li>&#8226; تصاویر را بهینه و فشرده کنید</li>
      <li>&#8226; برای فایل‌های استاتیک از CDN استفاده کنید</li>
      <li>&#8226; منابع حیاتی را preload کنید</li>
      <li>&#8226; جاوااسکریپتی را که جلوی رندر را می‌گیرد به حداقل برسانید</li>
    </ul>
  </div>
  <div>
    <h4>بهبود INP</h4>
    <ul>
      <li>&#8226; taskهای طولانی جاوااسکریپت را بشکنید</li>
      <li>&#8226; محاسبات سنگین را به web worker بسپارید</li>
      <li>&#8226; event handlerها را بهینه کنید</li>
      <li>&#8226; جاوااسکریپت غیرضروری را با تأخیر بارگذاری کنید</li>
    </ul>
  </div>
  <div>
    <h4>بهبود CLS</h4>
    <ul>
      <li>&#8226; همیشه برای تصاویر ویژگی‌های اندازه را بگذارید</li>
      <li>&#8226; برای محتوای پویا از قبل جا رزرو کنید</li>
      <li>&#8226; محتوا را بالای محتوای موجود اضافه نکنید</li>
      <li>&#8226; به‌جای تغییر چیدمان از انیمیشن‌های transform استفاده کنید</li>
    </ul>
  </div>
</div>

### بهترین روش‌ها

<BestPracticeList items={[
  ['زود فعال کنید', 'ردیابی Web Vitals را تا جای ممکن زود در چرخه‌ی عمر اپ فعال کنید تا سنجش دقیق باشد'],
  ['از داده‌ی production استفاده کنید', 'Web Vitals از کاربران واقعی production بیشترین معنا را دارد؛ داده‌ی محیط توسعه ممکن است گمراه‌کننده باشد'],
  ['بر اساس route مانیتور کنید', 'Web Vitals را برای هر route یا صفحه دنبال کنید تا بفهمید کدام صفحه‌ها بهینه‌سازی لازم دارند'],
  ['در طول زمان دنبال کنید', 'از روندهای داشبورد استفاده کنید تا ببینید deployها چه اثری روی عملکرد دارند'],
  ['روی INP تمرکز کنید', 'INP معیار Core Web Vitals برای پاسخ‌گویی است؛ بهبود پاسخ‌گویی را در اولویت بگذارید'],
  ['هدف واقع‌بینانه بگذارید', 'هدف را رسیدن به آستانه‌ی «خوب» در صدک ۷۵ام بارگذاری صفحه‌ها بگذارید'],
]} />

- امتیاز عملکرد: https://abrova.ir/docs/trace/performance-score

وضعیت Core Web Vitals اپلیکیشن شما در کارت **Web Vitals** در صفحه‌ی **ابرووا تریس ← Performance** نمایش داده می‌شود. هر معیار با **p75** خودش در بازه‌ی زمانی انتخاب‌شده خلاصه می‌شود و بر اساس آستانه‌های استاندارد Google رتبه‌ی **خوب**، **نیاز به بهبود** یا **ضعیف** می‌گیرد، تا افت عملکرد را با یک نگاه ببینید.

<Callout kind="note" title="امتیاز ترکیبی واحد وجود ندارد">
  کنسول ابرووا فعلاً معیارها را در یک امتیاز ۰ تا ۱۰۰ ترکیب نمی‌کند. به‌جای آن رتبه‌ی هر معیار را بخوانید؛ از معیاری شروع کنید که بدترین رتبه را دارد.
</Callout>

<Callout kind="note" title="فقط مرورگر">
  Web Vitals مخصوص مرورگر است و از SDK مرورگر می‌آید (در SDK مربوط به Next.js یا وب، `enableWebVitals()` را صدا بزنید). SDKهای موبایل و بک‌اند فقط تأخیر درخواست‌ها را می‌فرستند، پس برای پروژه‌های غیروب این کارت پیام «Web Vitals به SDK مرورگر نیاز دارد» را نشان می‌دهد.
</Callout>

### رتبه‌بندی معیارها

p75 هر معیار با آستانه‌های استاندارد Google مقایسه می‌شود: اگر برابر یا کمتر از ستون **خوب** باشد «خوب» است، اگر بیشتر از ستون **ضعیف** باشد «ضعیف» است، و هر مقدار بین این دو «نیاز به بهبود» است.

<div>
  <table>
    <thead>
      <tr>
        {['معیار', 'نام', 'خوب', 'ضعیف'].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>

معیارهایی که هنوز داده‌ای برایشان نرسیده نمایش داده نمی‌شوند.

### بازه‌های رتبه

<BestPracticeList columns={3} items={[
  ['خوب', 'سالم. بیشتر بارگذاری‌های صفحه به آستانه می‌رسند'],
  ['نیاز به بهبود', 'وضعیت متوسط. این معیار را بررسی کنید و اصلاحی هدفمند منتشر کنید'],
  ['ضعیف', 'بسیاری از بارگذاری‌ها در این معیار رد می‌شوند. SEO و ماندگاری کاربر در خطر است'],
]} />

### آنچه در داشبورد می‌بینید

کارت Web Vitals در صفحه‌ی عملکرد این‌ها را نشان می‌دهد:

- **سرتیتر**: «p75 · N بارگذاری صفحه · فقط SDK مرورگر»
- **تفکیک هر معیار**: همه‌ی معیارهای ارسال‌شده با مقدار p75، آیکون رتبه و برچسب
- **تقسیم خوب / نیاز به بهبود / ضعیف**: هر بارگذاری صفحه در هر معیار چه رتبه‌ای گرفته است

### خواندن تفکیک

ردیف‌های تفکیک نشان می‌دهند *چه چیزی* مشکل دارد. ردیف‌ها این شکلی‌اند:

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

آیکون‌های رتبه را مرور کنید: اول ردیف‌های «ضعیف» را درست کنید، بعد «نیاز به بهبود».

### بهترین روش‌ها

<BestPracticeList items={[
  ['معیارها را در طول زمان دنبال کنید', 'با انتخابگر بازه‌ی زمانی، ۱ ساعت و ۲۴ ساعت و ۷ روز را مقایسه کنید؛ تغییر ناگهانی معمولاً به یک deploy برمی‌گردد'],
  ['اول بدترین معیار را درست کنید', 'رساندن یک معیار «ضعیف» به «خوب» بیشتر از صیقل دادن معیاری که الان «خوب» است به کاربر کمک می‌کند'],
  ['بر اساس release مقایسه کنید', 'در init مربوط به SDK نسخه‌ی release را تنظیم کنید و از فیلتر Release استفاده کنید تا افت عملکرد را به deploy مشخصی نسبت دهید'],
  ['همراه با تأخیر درخواست‌ها ببینید', 'Web Vitals رندر فرانت‌اند را پوشش می‌دهد و کارت‌های تأخیر و عملیات تأخیر درخواست‌ها را. این دو با هم تصویر کاملی از تجربه‌ی کاربر می‌دهند'],
]} />

- امتیاز Apdex: https://abrova.ir/docs/trace/apdex

Apdex (**Application Performance Index**) یک شاخص استاندارد صنعتی است که تأخیر را در یک عدد بین **۰٫۰۰ و ۱٫۰۰** خلاصه می‌کند. برخلاف صدک‌ها، نشان می‌دهد چه سهمی از کاربران واقعاً از زمان پاسخ *راضی* بوده‌اند، نه فقط این‌که کندترین درخواست‌ها چقدر کند بوده‌اند. ابرووا تریس این امتیاز را روی همه‌ی performance spanهای بازه‌ی زمانی انتخاب‌شده حساب می‌کند.

<Callout kind="note" title="تأخیر بک‌اند، نه Web Vitals">
  Apdex مدت درخواست‌ها را می‌سنجد و مکمل Web Vitals است (که رندر فرانت‌اند را می‌سنجد). برای تصویر کامل از تجربه‌ی کاربر هر دو را کنار هم ببینید.
</Callout>

### نحوه‌ی محاسبه

هر span نسبت به یک تأخیر هدف **T** (`T = 500ms`) در یکی از این دسته‌ها قرار می‌گیرد:

<div>
  <table>
    <thead>
      <tr>
        {['دسته', 'بازه', 'وزن', 'معنی'].map((h) => (
          <th key={h}>{h}</th>
        ))}
      </tr>
    </thead>
    <tbody>
      {[
        ['راضی (Satisfied)', 'duration ≤ T (≤500ms)', '1.0', 'کاربر پاسخ فوری گرفته است'],
        ['قابل‌تحمل (Tolerating)', 'T < duration ≤ 4T (500ms-2s)', '0.5', 'کند اما قابل‌استفاده'],
        ['ناامید (Frustrated)', 'duration > 4T (>2s)', '0.0', 'کاربر احتمالاً رها کرده یا دوباره تلاش کرده است'],
      ].map(([bucket, range, weight, meaning]) => (
        <tr key={bucket}>
          <td>{bucket}</td>
          <td>{range}</td>
          <td>{weight}</td>
          <td>{meaning}</td>
        </tr>
      ))}
    </tbody>
  </table>
</div>

سپس امتیاز این‌طور حساب می‌شود:

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

### بازه‌های امتیاز (راهنما)

<BestPracticeList columns={4} items={[
  ['۰٫۹۴ تا ۱٫۰۰ عالی', 'در سطح صنعتی. کاربران تأخیر را به‌سختی حس می‌کنند'],
  ['۰٫۸۵ تا ۰٫۹۴ خوب', 'سالم. بیشتر تیم‌ها این بازه را حداقل هدف خود می‌گذارند'],
  ['۰٫۷۰ تا ۰٫۸۵ متوسط', 'اصطکاک قابل‌مشاهده. تأخیر درخواست‌های کند باید بهتر شود'],
  ['کمتر از ۰٫۷۰ ضعیف', 'سهم قابل‌توجهی از درخواست‌ها کاربران را ناامید می‌کند؛ همین حالا بررسی کنید'],
]} />

### چرا Apdex (و نه فقط p95)؟

صدک‌ها به این سؤال جواب می‌دهند که «کندترین درخواست‌ها چقدر کندند؟» و Apdex به این‌که «چند کاربر تجربه‌ی بدی داشته‌اند؟». دو مثال:

- **سرویس A**: p95 = 1.8s اما p50 = 50ms. Apdex ≈ 0.93. بیشتر کاربران راضی‌اند؛ فقط تعدادی درخواست کند وجود دارد.
- **سرویس B**: p95 = 1.8s و p50 = 1.7s. Apdex ≈ 0.51. *نیمی* از کاربران ناامیدند.

p95 یکسان، اما واقعیت کاربر کاملاً متفاوت. Apdex مورد دوم را فوراً نشان می‌دهد.

### خواندن امتیاز

Apdex از همان فیلترهای بازه‌ی زمانی، پلتفرم، محیط و release پیروی می‌کند که بقیه‌ی صفحه‌ی **ابرووا تریس ← Performance** دارد. کنار امتیاز، تعداد درخواست‌های راضی، قابل‌تحمل و ناامید پشت آن را هم می‌بینید. اگر در بازه‌ی انتخاب‌شده هیچ spanی نباشد، امتیازی هم نیست.

### تغییر آستانه

T روی **500ms** ثابت است، چون با SLA استاندارد وب برای «حس فوری بودن» هم‌خوان است. برای هر پروژه قابل‌تنظیم نیست. اگر کار شما واقعاً کندتر است (مثلاً inference یادگیری ماشین یا transcode ویدیو)، امتیاز بدبینانه به نظر می‌رسد؛ در این حالت روی **روند** امتیاز تمرکز کنید، نه مقدار مطلق آن.

### بهترین روش‌ها

<BestPracticeList items={[
  ['به امتیاز نگاه کنید، نه آستانه', 'حتی اگر T=500ms با SLA شما جور نباشد، روند امتیاز معنادار است؛ Apdex نزولی یعنی تجربه‌ی کاربر بدتر می‌شود'],
  ['با نرخ خطا مقایسه کنید', 'Apdex بالا با نرخ خطای بالا یعنی شکست‌های سریع. Apdex پایین با نرخ خطای پایین یعنی موفقیت‌های کند. هر دو به شکل متفاوتی به تجربه‌ی کاربر آسیب می‌زنند'],
  ['مراقب افت Apdex باشید', 'رفتن Apdex از ۰٫۹۴ به ۰٫۸۵ کوچک‌تر از دو برابر شدن p95 به نظر می‌رسد، اما همان درد را برای کاربر نشان می‌دهد. برای هشدار، در «ابرووا تریس ← هشدارها» یک قانون هشدار برای تأخیر p95 بسازید'],
  ['تأخیر هر عملیات را ببینید', 'Apdex کلی ۰٫۹۲ برای کل سایت می‌تواند یک endpoint گیرکرده روی ۰٫۴۰ را پنهان کند. کارت عملیات در صفحه‌ی عملکرد p95 هر عملیات را برای بررسی دقیق‌تر نشان می‌دهد'],
]} />

- تفکیک پلتفرم: https://abrova.ir/docs/trace/platform-breakdown

تفکیک پلتفرم نشان می‌دهد داده‌های عملکرد شما بین SDKها (iOS، Android، وب، Node، Flutter، Laravel) چطور تقسیم شده است، تا سریع ببینید *کدام* پلتفرم ترافیک را می‌سازد و *عملکردش نسبت به بقیه چطور است*. ابرووا تریس هر span را بر اساس فیلد `platform` که هر SDK روی spanهایش می‌گذارد گروه‌بندی می‌کند.

<Callout kind="note" title="پیدا کردن افت عملکرد در یک پلتفرم">
  اگر p95 کلی اپ بعد از یک release بالا رفت، تفکیک پلتفرم سریع‌ترین راه است تا بفهمید عامل آن آپدیت iOS است، انتشار Android یا build جدید وب.
</Callout>

### آنچه در داشبورد می‌بینید

در کنسول ابرووا، در صفحه‌ی **ابرووا تریس &rarr; Performance**، با فیلتر **پلتفرم** در نوار ابزار همه‌ی کارت‌ها (آمار، تأخیر، عملیات، کدهای وضعیت، درخواست‌های ناموفق) را به یک پلتفرم محدود کنید. بین پلتفرم‌ها جابه‌جا شوید تا تعداد درخواست، تأخیر و نرخ خطای آن‌ها را کنار هم مقایسه کنید.

### پلتفرم چطور تشخیص داده می‌شود

فیلد `platform` را SDK روی هر spanی که می‌فرستد تنظیم می‌کند:

<div>
  <table>
    <thead>
      <tr>
        {['SDK', 'پلتفرم ارسالی', 'منبع'].map((h) => (
          <th key={h}>{h}</th>
        ))}
      </tr>
    </thead>
    <tbody>
      {[
        ['Next.js / Web', 'nextjs', 'ثابت، توسط SDK'],
        ['Flutter', 'flutter_android / flutter_ios / flutter_web_* …', 'در زمان اجرا از طریق AbrovaTrace.createPerformanceClient / trackOperation تشخیص داده می‌شود؛ یک PerformanceHttpClient مستقل مقدار flutter (یا web) را می‌فرستد مگر این‌که platform را خودتان بدهید، و spanهایی که خودتان برای reportPerformanceSpan می‌سازید فقط همان پلتفرمی را دارند که تنظیم کرده‌اید'],
        ['Android', 'android', 'ثابت، توسط SDK'],
        ['iOS', 'ios', 'ثابت، توسط SDK'],
        ['Node.js', 'nodejs', 'ثابت، توسط SDK'],
        ['Laravel', 'laravel', 'ثابت، توسط SDK'],
      ].map(([sdk, platform, source]) => (
        <tr key={sdk}>
          <td>{sdk}</td>
          <td>{platform}</td>
          <td>{source}</td>
        </tr>
      ))}
    </tbody>
  </table>
</div>

اگر spanی بدون تگ پلتفرم برسد (span سفارشی، SDK قدیمی و غیره)، در دسته‌ی **«unknown»** قرار می‌گیرد.

### جدا کردن محصولات

گزینه‌ای در init برای تغییر پلتفرم وجود ندارد. اگر یک پروژه هم اپ وب مشتریان و هم پنل مدیریت شما را دریافت می‌کند، آن‌ها را با یک `environment` جداگانه (که در صفحه‌ی عملکرد فیلتر دارد) یا با تگ روی spanهایی که خودتان می‌فرستید از هم جدا کنید:

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

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

### بهترین روش‌ها

<BestPracticeList items={[
  ['بزرگ‌ترین سهم را زیر نظر بگیرید', 'افت عملکرد معمولاً در بزرگ‌ترین سهم پنهان می‌شود، فقط چون بیشترین نمونه را دارد. p95 آن را با بقیه مقایسه کنید'],
  ['پروژه‌های چندمحصولی را تفکیک کنید', 'اگر یک پروژه هم ابزار مدیریت و هم اپ مشتری را دریافت می‌کند، به هر کدام environment جداگانه بدهید تا بتوانید فیلترشان کنید'],
  ['به جهش‌های «unknown» توجه کنید', 'رشد ناگهانی دسته‌ی unknown معمولاً یعنی نسخه‌ی جدیدی از SDK تگ پلتفرم را نمی‌فرستد؛ ارزش بررسی دارد'],
  ['موبایل و وب را مقایسه کنید', 'ترافیک موبایل معمولاً پرحرف‌تر است (همگام‌سازی پس‌زمینه) و ترافیک وب انفجاری. نسبت سالم است وقتی با ترکیب کاربران فعال شما جور باشد'],
]} />

- کندترین سرویس‌ها: https://abrova.ir/docs/trace/top-hosts

Hostهای پرتکرار نشان می‌دهد اپ شما بیشتر با کدام hostهای خارجی ارتباط دارد: APIهای خودتان، سرویس‌های ثالث مثل درگاه پرداخت و سرویس پیامک، CDNها و endpointهای آنالیتیکس. هر host بر اساس حجم درخواست رتبه می‌گیرد و تأخیر p95 و تعداد خطایش را نشان می‌دهد، تا فوراً سرویس ثالثی را پیدا کنید که بی‌صدا تجربه‌ی کاربر را خراب می‌کند.

<Callout kind="note" title="فقط HTTP خروجی">
  فقط درخواست‌های HTTP خروجی اینجا دیده می‌شوند. کوئری‌های دیتابیس، عملیات سفارشی و spanهای cache اینجا نمایش داده نمی‌شوند.
</Callout>

### آنچه می‌بینید

برای هر host:

- **Host**: مثلاً `api.payments.example.com` یا `cdn.example.com`
- **درخواست‌ها**: مجموع در بازه‌ی زمانی انتخاب‌شده (hostها بر اساس همین رتبه می‌گیرند)
- تأخیر **میانگین** و **p95** بر حسب میلی‌ثانیه
- **خطاها**: درخواست‌هایی که HTTP 400 یا بالاتر برگردانده‌اند

برای بررسی دقیق فراخوانی‌های خروجی کند یا ناموفق، از کارت‌های **عملیات** و **درخواست‌های ناموفق** در صفحه‌ی **ابرووا تریس ← Performance** در کنسول ابرووا استفاده کنید.

### چه چیزی host حساب می‌شود

همه‌ی SDKهای رسمی host را خودکار از URL درخواست استخراج می‌کنند. مثلاً درخواستی به `https://api.payments.example.com/v1/charges` زیر `api.payments.example.com` قرار می‌گیرد. تفاوت مسیرها در این سطح اهمیتی ندارد؛ برای آن [عملکرد URL](/docs/trace/url-performance) را ببینید.

### الگوهای رایجی که باید زیر نظر بگیرید

<BestPracticeList columns={2} items={[
  ['یک host غالب است', 'اگر API خودتان باشد سالم است. اگر سرویس ثالث باشد مشکوک است؛ ممکن است طوفان retry یا polling بیش از حد باشد'],
  ['host ثالث کند', 'p95 برابر 1.5s برای host پرداخت یا احراز هویت یعنی پرداخت یا ورود کاربر منتظر آن می‌ماند. اگر می‌شود cache یا async کنید'],
  ['host جدید ناگهان ظاهر می‌شود', 'معمولاً ویژگی جدیدی منتشر شده که سرویس ناآشنایی را صدا می‌زند. مطمئن شوید که انتظارش را داشتید؛ ممکن است SDKی اشتباه پیکربندی شده باشد'],
  ['CDN خطا دارد', 'تعداد کمی خطا از CDN اغلب نشانه‌ی قطعی منطقه‌ای است که کاربران قبل از این‌که شما در لاگ‌ها ببینید گزارشش می‌کنند'],
]} />

### یک نمونه‌ی واقعی

سناریوی رایج: p95 کلی اپ شما یک‌شبه از 300ms به 1.1s می‌رسد. نمودار تأخیر این را تأیید می‌کند، اما کارت عملیات عادی به نظر می‌رسد؛ همه‌ی عملیات به یک اندازه کند شده‌اند. Hostهای پرتکرار فوراً مقصر را نشان می‌دهد: p95 مربوط به `api.thirdparty.com` از 200ms به 2.4s رسیده است. حادثه‌ی *آن‌ها* حالا حادثه‌ی *شما* است، اما دست‌کم می‌دانید مشکل از کد شما نیست و می‌توانید به‌جای دنبال کردن یک شبح، اثرش را کم کنید (cache، async، fallback).

### بهترین روش‌ها

<BestPracticeList items={[
  ['برای hostهای ثالث SLO در نظر بگیرید', 'p95 آن‌ها را مثل p95 سرویس‌های خودتان دنبال کنید. درگاه پرداخت یا سرویس پیامک کند، از لحظه‌ای که کاربر متوجه شود مشکل شماست'],
  ['با درخواست‌های ناموفق مقایسه کنید', 'Hostهای پرتکرار سلامت کلی را نشان می‌دهد و درخواست‌های ناموفق خطاهای مشخص را. هر دو را با هم به کار ببرید'],
  ['به hostهای کند از قبل وصل شوید', 'برای hostهایی که TTFB بالای ثابت اما p95 پایین دارند، یک <link rel="preconnect"> می‌تواند ۱۰۰ تا ۲۰۰ میلی‌ثانیه از اولین فراخوانی کم کند'],
  ['مراقب hostهای جدید باشید', 'hostی کاملاً جدید که نزدیک بالای فهرست ظاهر می‌شود معمولاً یا یک انتشار برنامه‌ریزی‌شده است یا خطر نشت داده؛ در هر دو حالت بررسی کنید'],
]} />

- عملکرد آدرس‌ها: https://abrova.ir/docs/trace/url-performance

عملکرد URL جدولی از تأخیر هر URL است که درخواست‌ها را بر اساس **URL کامل HTTP** گروه‌بندی می‌کند (نه بر اساس نام منطقی عملیات). مکمل کارت **عملیات** ([تأخیر API](/docs/trace/api-latency)) است: عملیات بر اساس نام عملیات جمع می‌شوند (`GET /users/:id`)، اما URLها بر اساس چیزی که مرورگر کاربر واقعاً درخواست کرده (`/users/4710`). وقتی لازم دارید بدانید *کدام صفحه‌های مشخص* کندند، نه فقط کدام routeها، از این استفاده کنید.

<Callout kind="note" title="کِی این و کِی عملیات">
  برای routeهای بک‌اند (مسیرهای پارامتری) از عملیات استفاده کنید. برای فراخوانی‌های سمت کلاینت در هر صفحه، یا وقتی اصلاً قالب route ندارید (مثل فایل‌های استاتیک و فراخوانی‌های ثالث)، از عملکرد URL استفاده کنید.
</Callout>

### داده‌ها شامل چه چیزی است

هر ردیف این ستون‌ها را دارد:

<div>
  <table>
    <thead>
      <tr>
        {['ستون', 'توضیح'].map((h) => (
          <th key={h}>{h}</th>
        ))}
      </tr>
    </thead>
    <tbody>
      {[
        ['method', 'متد HTTP (GET، POST، PUT، PATCH، DELETE و …)'],
        ['url', 'URL کامل درخواست'],
        ['request_count', 'تعداد کل درخواست‌ها برای این URL در بازه‌ی زمانی انتخاب‌شده'],
        ['avg_duration', 'میانگین مدت (ms)؛ تقریبی، اما کنار p95 مفید است'],
        ['p50', 'میانه؛ تجربه‌ی یک کاربر معمولی'],
        ['p95', 'دنباله‌ی کند؛ ۵٪ کندترین درخواست‌ها. بیشتر دردسر کاربر همین‌جاست'],
        ['max_duration', 'کندترین درخواست در این بازه؛ برای پیدا کردن موارد پرت'],
        ['error_count', 'تعداد پاسخ‌هایی با وضعیت HTTP 400 یا بالاتر'],
      ].map(([col, desc]) => (
        <tr key={col}>
          <td>{col}</td>
          <td>{desc}</td>
        </tr>
      ))}
    </tbody>
  </table>
</div>

ردیف‌ها بر اساس **p95 نزولی** مرتب می‌شوند تا کندترین‌ها بالا بیایند.

### تفاوت URL و عملیات

این تفاوت موقع خواندن جدول مهم است:

- **عملیات** یک قالب منطقی route است؛ `GET /api/users/:id` در کارت عملیات فقط یک ردیف است، هر شناسه‌ی کاربری که صدا زده شده باشد.
- **URL** همان رشته‌ای است که SDK دیده؛ `https://api.example.com/users/4710` و `/users/4711` اینجا دو ردیف جدا هستند.

اگر بک‌اند شما URLهای با تنوع بالا دارد (هر شناسه‌ی کاربر یک ردیف جدا)، جدول عملکرد URL خیلی زود شلوغ می‌شود. این عمدی است: به شما می‌گوید *کدام کاربر، رکورد یا صفحه‌ی مشخصی* کند است. برای مانیتورینگ کلی در سطح route، کارت عملیات را ترجیح دهید.

### الگوهای رایجی که باید زیر نظر بگیرید

<BestPracticeList columns={2} items={[
  ['یک URL بر دنباله‌ی کند غالب است', 'یک URL پرتکرار با p95 خیلی بالاتر از بقیه معمولاً یعنی رکورد مشخصی باعث کوئری N+1 یا ردیف داغ شده است'],
  ['URLهای زیاد با الگوی یکسان', 'اگر GET /users/4710، /users/4711 و /users/4712 همه کندند، خود route کند است؛ به کارت عملیات بروید'],
  ['بیشینه‌ی بالا، p95 پایین', 'یک درخواست فاجعه‌بار در میان ترافیک سالم؛ معمولاً کوئری افسارگسیخته یا cache miss نادر. ارزش بررسی دارد'],
  ['URLهای فایل استاتیک کندند', 'اگر URLهای .js / .css / .png مقدار p95 بالایی دارند، نرخ hit در cache مربوط به CDN پایین آمده است. origin shielding را بررسی کنید'],
]} />

### بهترین روش‌ها

<BestPracticeList items={[
  ['همراه با عملیات ببینید', 'عملیات جواب می‌دهد «آیا این route به‌طور میانگین کند است؟» و عملکرد URL جواب می‌دهد «کندترین درخواست مشخص کدام بود؟»'],
  ['URLهای پرتنوع را یکدست کنید', 'اگر هر شناسه‌ی کاربر URL جدای خودش باشد، جدول طولانی می‌شود. وقتی خودتان span می‌فرستید، نام عملیات را به شکل قالب route بدهید (مثلاً GET /users/:id) تا در کارت عملیات جمع شوند؛ http_url همچنان مسیر خام را نگه می‌دارد'],
  ['با درخواست‌های ناموفق مقایسه کنید', 'URL کند را در کارت درخواست‌های ناموفق پیدا کنید تا موارد خطای مشخص را ببینید'],
  ['بیشینه را نشانه‌ی بررسی بدانید', 'یک بیشینه‌ی ۸ ثانیه یا بیشتر ارزش بررسی دقیق دارد؛ اغلب باگی را نشان می‌دهد که p95 به‌تنهایی نمی‌بیند'],
  ['حجم × p95 را در نظر بگیرید', 'URLی با ۱۰٬۰۰۰ درخواست و p95 برابر 300ms بیشتر از URLی با ۵۰ درخواست و p95 برابر 1.5s روی کاربران اثر دارد. هر دو مهم‌اند؛ بر اساس دامنه‌ی اثر وزن بدهید'],
]} />

- داشبورد خطا: https://abrova.ir/docs/trace/error-dashboard

داشبورد خطاهای ابرووا تریس همان صفحه‌ی **ابرووا تریس ← مشکلات** در کنسول ابرووا است. این صفحه خطاهای گروه‌بندی‌شده از همه‌ی پلتفرم‌های پروژه‌ی شما را با فیلترهای قدرتمند، مدیریت وضعیت و جزئیات کامل هر خطا نشان می‌دهد.

<div>
  {[['ردیابی لحظه‌ای', 'خطاها به محض رسیدن در قالب مشکل گروه‌بندی می‌شوند'], ['فیلتر قدرتمند', 'فیلتر بر اساس وضعیت، تکرار، بازه‌ی زمانی، پلتفرم، محیط، release و متن'], ['مدیریت وضعیت', 'خطاها را از کشف تا حل شدن دنبال کنید']].map(([t, d]) => (
    <div key={t}>
      <strong>{t}</strong>
      <p>{d}</p>
    </div>
  ))}
</div>

### اجزای داشبورد

#### زبانه‌های وضعیت

هر زبانه‌ی وضعیت نشان می‌دهد چند مشکل در آن است:

<div>
  {[
    { label: 'باز', value: '۱۲', color: 'text-red-600' },
    { label: 'در حال بررسی', value: '۳', color: 'text-zinc-50' },
    { label: 'حل‌شده', value: '۱۵', color: 'text-emerald-400' },
    { label: 'همه', value: '۲۴۷', color: 'text-zinc-50' },
  ].map((s) => (
    <div key={s.label}>
      <p>{s.value}</p>
      <p>{s.label}</p>
    </div>
  ))}
</div>

#### فیلترها

- **وضعیت:** باز (پیش‌فرض)، در حال بررسی، حل‌شده، نادیده‌گرفته، بایگانی‌شده، همه
- **تکرار:** ۱ تا ۱۰، ۱۱ تا ۵۰، ۵۱ تا ۱۰۰، و بیش از ۱۰۰ رویداد
- **بازه‌ی زمانی:** ۱ ساعت، ۲۴ ساعت، ۷ روز، ۳۰ روز (پیش‌فرض) یا بازه‌ی دلخواه
- **پلتفرم، محیط، Release**

#### فهرست خطاها

هر مشکل در فهرست، پلتفرم، پیام خطا، وضعیت، تعداد رویدادها و آخرین زمان دیده شدنش را نشان می‌دهد. بین نمای **فهرست** و **خط زمانی** جابه‌جا شوید.

### نمای جزئیات خطا

روی هر خطا کلیک کنید تا جزئیات کاملش را ببینید:

- **پیام خطا و stack trace**: stack trace کامل (اگر source map یا dSYM آپلود شده باشد، از حالت مبهم خارج می‌شود)
- **خط زمانی breadcrumbها**: ترتیب رویدادهایی که به خطا رسیدند
- **داده‌های اضافه**: داده‌های سفارشی که با پارامتر extra ضمیمه شده‌اند
- **اطلاعات محیط**: پلتفرم، سیستم‌عامل، مرورگر و نسخه‌ی release
- **آمار رخدادها**: اولین و آخرین زمان دیده شدن، تعداد کل و تاریخچه‌ی وضعیت

### مدیریت وضعیت

<div>
  {[
    ['باز', 'خطای جدیدی که باید بررسی شود', 'bg-blue-900/20 text-blue-300'],
    ['در حال بررسی', 'در حال بررسی یا رفع است', 'bg-yellow-900/20 text-yellow-300'],
    ['حل‌شده', 'رفع آن منتشر شده است', 'bg-green-900/20 text-green-300'],
    ['بایگانی‌شده', 'بسته شده و دیگر فعال نیست', 'bg-zinc-800 bg-zinc-700 text-zinc-400'],
    ['نادیده‌گرفته', 'مشکل شناخته‌شده‌ای که رفع نمی‌شود', 'bg-zinc-800 bg-zinc-700 text-zinc-400'],
  ].map(([status, desc, cls]) => (
    <div key={status}>
      <span>{status}</span>
      <span>{desc}</span>
    </div>
  ))}
</div>

**تغییر گروهی:** چند مشکل را انتخاب کنید تا یک‌جا آن‌ها را حل‌شده، در حال بررسی، نادیده‌گرفته یا بایگانی‌شده کنید یا دوباره باز کنید، یا از منوی **⋯** همه‌ی مشکل‌های باز را حل‌شده کنید. تغییر وضعیت دست‌کم نقش member می‌خواهد؛ حذف مشکل‌ها نقش admin یا owner. جزئیات در [نقش‌ها و دسترسی‌ها](/docs/trace/error-dashboard#roles).

<div id="roles" />

### نقش‌ها و دسترسی‌ها

کاری که در ابرووا تریس می‌توانید انجام دهید به نقش شما بستگی دارد. نقش‌ها در کنسول ابرووا (تنظیمات سازمان و پروژه) داده می‌شوند؛ ابرووا تریس فهرست نقش جداگانه‌ای ندارد. هر نقش همه‌ی اختیارات نقش بالاتر از خود در جدول را هم دارد.

<ConfigTable headers={['نقش', 'سطح', 'کارهایی که در ابرووا تریس می‌تواند انجام دهد']} rows={[
  ['Viewer', 'خواندن', 'دیدن همه‌چیز در پروژه: مشکل‌ها و تاریخچه‌شان، پیام‌ها، لاگ‌ها و جست‌وجوهای ذخیره‌شده، عملکرد، قوانین نادیده‌گیری، قوانین هشدار و رویدادهایشان، مانیتورهای cron و check-inها، کانتینرها و آمارشان، یکپارچگی‌ها و لاگ ارسالشان، source mapها و debug symbolهای آپلودشده'],
  ['Member', 'رسیدگی', 'تغییر وضعیت مشکل (یک مشکل، چند مشکل با هم، یا «حل کردن همه‌ی مشکل‌های باز»)؛ تأیید، بی‌صدا کردن و برداشتن بی‌صدایی هشدارها؛ ذخیره‌ی جست‌وجوی لاگ و ویرایش یا حذف جست‌وجوهایی که خودش ذخیره کرده؛ آپلود source map و debug symbol (dSYM)'],
  ['Admin', 'مدیریت', 'حذف داده (مشکل‌ها، پیام‌ها، لاگ‌ها و منابع لاگ، نشانگرهای deploy، داده‌های عملکرد، source mapها و debug symbolهای آپلودشده)؛ ساختن، ویرایش، روشن و خاموش کردن و حذف قوانین نادیده‌گیری، قوانین هشدار و مانیتورهای cron؛ افزودن، ویرایش، روشن و خاموش کردن، حذف و تست یکپارچگی‌ها؛ شروع، توقف، راه‌اندازی دوباره و حذف کانتینرها؛ ویرایش یا حذف هر جست‌وجوی ذخیره‌شده‌ی لاگ؛ تغییرات در سطح پروژه'],
  ['Owner', 'مدیریت', 'همه‌ی کارهای admin. «منطقه‌ی خطر» در ابرووا تریس ← تنظیمات (حذف همه‌ی داده‌های یک نوع) فقط به owner نشان داده می‌شود'],
]} />

- **فقط پروژه‌های خودتان را می‌بینید.** memberها و viewerها پروژه‌هایی را می‌بینند که به آن‌ها اختصاص داده شده‌اند؛ پروژه‌های دیگر سازمان برایشان در ابرووا تریس نمایش داده نمی‌شوند.
- **فقط به یک پروژه اضافه شده‌اید؟** کسی که بدون نقش در سازمان فقط به یک پروژه اضافه شده، آنجا مثل viewer فقط دسترسی خواندن دارد.
- **کارهای غیرمجاز.** کنترل‌هایی که نمی‌توانید استفاده کنید غیرفعال نشان داده می‌شوند. اگر درخواستی نقش بالاتری بخواهد، API پاسخ `403` با `"code": "forbidden_role"` برمی‌گرداند.
- **اپ‌ها و سرورها جدا هستند.** نقش‌ها برای افرادی است که از داشبورد استفاده می‌کنند. SDKها، log agent و check-inهای cron با کلیدهای پروژه احراز هویت می‌شوند؛ [کلید سرور و routeهای سرور](/docs/trace/server-secret) را ببینید.

### سهمیه‌ی رایگان و کیف پول

ابرووا تریس **رویدادهای خطا در هر ماه** را برای سازمان شما می‌شمارد: هر خطایی که می‌رسد، از جمله تکرارِ یک مشکلِ شناخته‌شده. روی صفحه، رویدادهای یک علت در یک مشکل گروه‌بندی می‌شوند تا فهرست خوانا بماند.

هر ماه **۵۰٬۰۰۰ رویداد خطا رایگان** است. بیشتر از آن، هر **۱٬۰۰۰ رویدادِ شروع‌شده ۳٬۰۰۰ تومان** هزینه دارد که روزی یک بار از کیف پول پیش‌پرداخت سازمان کم می‌شود؛ [قیمت‌ها](/pricing) را ببینید. اشتراکی در کار نیست. در طرح رایگان، تا **۱٬۰۰۰ مشکل جدید** در ماه هم ذخیره می‌شود.

وقتی سهم رایگان تمام شده و کیف پول موجودی ندارد (پس از صفر شدن موجودی، پرداخت به اندازه‌ی مصرف ۳ روز دیگر فعال می‌ماند):

- **رویدادهای جدید ذخیره نمی‌شوند** تا وقتی سهم رایگان در شروع ماه بعد تازه شود، یا کیف پول را شارژ کنید.
- **چیزی از داده‌های قبلی پاک نمی‌شود.**
- **اپ‌های شما هیچ‌وقت مختل نمی‌شوند.** API همچنان پاسخ موفق (`200`) می‌دهد، با بدنه‌ای که می‌گوید رویداد ذخیره نشده، پس هیچ SDKی دوباره تلاش نمی‌کند، صف نمی‌کند یا خطا لاگ نمی‌کند:

```json
{
  "status": "dropped",
  "code": "plan_limit_reached",
  "metric": "error_events_monthly",
  "limit": 50000,
  "used": 50000,
  "resets_at": "2026-11-01T00:00:00.000Z"
}
```

(`limit` و `used` مقدارهای نمونه‌اند؛ سهم رایگان و مصرف این ماهِ سازمان شما را نشان می‌دهند.)

پایش عملکرد (spanها و Web Vitals) بخشی از پرداخت به اندازه‌ی مصرف است و جزو رویدادهای خطا شمرده نمی‌شود.

### جست‌وجو و فیلتر

- **جست‌وجوی متنی**: جست‌وجو در پیام‌های خطا، پلتفرم و محیط
- **فیلترهای ترکیبی**: ترکیب وضعیت، تکرار، بازه‌ی زمانی، پلتفرم، محیط، release و جست‌وجوی متنی
- **صفحه‌بندی**: پیمایش راحت در فهرست‌های بزرگ خطا

### بهترین روش‌ها

<BestPracticeList items={[
  ['هر روز سر بزنید', 'دست‌کم روزی یک بار خطاهای جدید را مرور کنید تا مشکل‌ها را زود بگیرید'],
  ['بر اساس تکرار اولویت بدهید', 'اول روی مشکل‌هایی تمرکز کنید که بیشترین رویداد را دارند (بیش از ۱۰۰، و ۵۱ تا ۱۰۰)'],
  ['وضعیت را مرتب به‌روز کنید', 'وضعیت خطاها را به‌روز نگه دارید تا تیم در جریان باشد'],
  ['روندها را زیر نظر بگیرید', 'از نمای خط زمانی و صفحه‌ی نمای کلی برای دیدن جهش‌ها یا الگوها استفاده کنید'],
  ['از breadcrumbها استفاده کنید', 'breadcrumbها را مرور کنید تا مسیر کاربر پیش از خطا را بفهمید'],
]} />

- استک‌تریس و source map: https://abrova.ir/docs/trace/stack-traces

stack trace ترتیب دقیق فراخوانی توابعی را که به خطا رسیده‌اند نشان می‌دهد: **کجا** خطا رخ داد، کد **چطور** به آنجا رسید و **چه** توابعی صدا زده شدند.

### ثبت خودکار stack trace

پیکربندی اضافه‌ای لازم نیست. ابرووا تریس stack trace را خودکار از این‌ها ثبت می‌کند:

- exceptionهای مدیریت‌نشده (با `captureUncaughtErrors: true`)
- ثبت دستی exception (با `captureException()`)
- خطاهای async (با `initWithZone()`)
- exceptionهای پلتفرم از کد نیتیو

```dart
try {
  await riskyOperation();
} catch (e, stackTrace) {
  await AbrovaTrace.captureException(
    e,
    stackTrace: stackTrace, // Always include this!
    message: 'Operation failed',
    extra: {'user_id': 'user_123'},
  );
}
```

### خواندن stack trace

<div>
  <p>Exception: FormatException: Invalid input</p>
  <p>{"  "}at Parser.parse (lib/parser.dart:42:15) {'←'} <span>محل رخ دادن خطا</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>

- **خط اول:** جایی که خطا رخ داده است
- **خطوط بعدی:** call stack (کد چطور به آنجا رسیده)
- **مسیر فایل‌ها و شماره‌ی خطوط:** برای پیدا کردن جای دقیق مشکل

### stack trace در هر پلتفرم

<div>
  {[
    ['Flutter موبایل', 'stackهای کامل Dart با شماره‌ی خط و نام متدها'],
    ['Flutter وب', 'stackهای خطای جاوااسکریپت همراه با اطلاعات مرورگر؛ برای خوانا شدن ممکن است source map لازم باشد'],
    ['Flutter دسکتاپ', 'اطلاعات کامل debug با stackهای کامل و جزئیات پلتفرم'],
    ['افزونه‌ی Chrome', 'اطلاعات context افزونه همراه با نسخه‌ی Chrome و context پس‌زمینه یا popup'],
  ].map(([platform, desc]) => (
    <div key={platform}>
      <strong>{platform}</strong>
      <p>{desc}</p>
    </div>
  ))}
</div>

### افزودن context به stack trace

```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,
    },
  );
}
```

### stack trace کرش‌های نیتیو

کرش‌های نیتیو در اجرای بعدی اپ شناسایی می‌شوند. وقتی کرش اپ را می‌بندد، اپ نمی‌تواند همان لحظه گزارش بدهد؛ برای همین ابرووا تریس کرش را هنگام اجرای دوباره پیدا می‌کند.

<Callout kind="note" title="مهم">ثبت کرش نیتیو هنگام مقداردهی اولیه‌ی SDK (<code>AbrovaTrace.initWithZone()</code> یا <code>AbrovaTrace.init()</code>) نصب می‌شود و فراخوانی اضافه‌ای لازم نیست. <code>AbrovaTrace.close()</code> فقط داده‌های در انتظار را می‌فرستد و SDK را می‌بندد.</Callout>

### آپلود source map

برای پلتفرم‌های وب (Next.js، Flutter Web) فایل‌های `.map` را آپلود کنید تا stack traceهای production به فایل‌ها و شماره‌ی خطوط اصلی کد شما برگردند.

#### کجا آپلود کنیم

- **کنسول ابرووا**: در `console.abrova.ir` &rarr; پروژه‌ی شما &rarr; **ابرووا تریس &rarr; Source map و symbol**. نسخه‌ی release را تنظیم کنید و فایل‌های `.map` را (چند فایل با هم) آپلود کنید.
- **Abrova CLI**: از build یا CI با `abrova-trace sourcemaps upload` آپلود کنید. [آپلود source map](/docs/trace/upload-source-maps) را ببینید.
- [اپ دسکتاپ](/desktop) ابرووا هم وقتی منتشر شود همین امکان آپلود را خواهد داشت (به‌زودی).

نسخه‌ی release باید با فیلد `release` که هنگام init به SDK می‌دهید یکی باشد؛ بک‌اند از همین راه map درست را به هر خطا وصل می‌کند.

آپلود دست‌کم نقش member می‌خواهد؛ حذف فایل‌های آپلودشده نقش admin یا owner. [نقش‌ها و دسترسی‌ها](/docs/trace/error-dashboard#roles) را ببینید.

#### Next.js

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

بعد از `next build`، فایل‌های `.map` را کنار chunkها در `.next/static/chunks/` پیدا می‌کنید. در هر آپلود تا ۵۰۰ فایل `.map` پذیرفته می‌شود، پس می‌توانید همه را یک‌جا بیندازید (فایل‌هایی که `.map` نیستند نادیده گرفته می‌شوند).

#### Flutter Web

با source map فعال build بگیرید، سپس تنها فایل `main.dart.js.map` را آپلود کنید:

```bash
flutter build web --source-maps
```

فایل map در `build/web/main.dart.js.map` قرار می‌گیرد.

<Callout kind="note" title="Flutter Web: از traceهای بازگردانده‌شده چه انتظاری داشته باشیم">
  <p>
    dart2js (کامپایلری که Dart را به جاوااسکریپت تبدیل می‌کند) در buildهای <code>--release</code> به‌شدت inline می‌کند. بعضی frameها تمیز به فایل‌های <code>.dart</code> شما برمی‌گردند. بعضی دیگر به بخش‌های داخلی فریم‌ورک (<code>js_helper.dart</code>، <code>dart:async</code>) می‌رسند یا minified می‌مانند (<code>a3v.$0</code>)، چون فایل <code>.map</code> برای آن بایت‌های JS اصلاً نگاشتی ندارد.
  </p>
  <p>
    این ویژگی خروجی dart2js است، نه مشکل resolver. از اول می‌گوییم چون بیشتر تیم‌ها در production به آن برمی‌خورند و فکر می‌کنند تنظیماتشان خراب است. خراب نیست.
  </p>
  <p>
    <strong>جایی که ابرووا جلو می‌افتد context است.</strong> breadcrumbهای gesture را فعال کنید (<code>AbrovaTrace.enableGestureBreadcrumbs()</code>) تا هر مشکل ویجتی را که کاربر درست پیش از خطا لمس کرده نشان دهد، به‌همراه route، آخرین فراخوانی HTTP و هر breadcrumb سفارشی. همراه با trace نیمه‌بازگردانده‌شده، گزارش باگی قابل‌بازتولید خواهید داشت.
  </p>
  <p><strong>فقط برای QA / staging</strong> می‌توانید بهینه‌سازی کمتری را اجبار کنید تا traceهای کاملاً بازگردانده‌شده بگیرید:</p>
  <CodeBlock language="bash" code={`flutter build web --source-maps --dart2js-optimization=O1`} />
  <p>حجم bundle حدود ۳۰٪ بیشتر می‌شود؛ برای staging مناسب است، برای production توصیه نمی‌شود.</p>
</Callout>

### بهترین روش‌ها

<BestPracticeList items={[
  ['همیشه stack trace را بفرستید', 'در ثبت دستی exception پارامتر stackTrace را بدهید'],
  ['context معنادار اضافه کنید', 'شناسه‌ی کاربر، نام صفحه و داده‌های مرتبط را در فیلد extra بگذارید'],
  ['از نسخه‌ی release استفاده کنید', 'نسخه‌ی release را تنظیم کنید تا خطاها را به deployها ربط دهید'],
  ['همراه با breadcrumbها', 'breadcrumbها نشان می‌دهند کاربر چه کرد و stack trace نشان می‌دهد کد کجا شکست خورد'],
  ['در محیط توسعه تست کنید', 'debug: true را فعال کنید تا در زمان توسعه stack traceها را در کنسول ببینید'],
]} />

- آپلود source map (CLI): https://abrova.ir/docs/trace/upload-source-maps

ابزار `@abrova-trace/cli` فایل‌های source map را از pipeline مربوط به CI/CD به ابرووا تریس آپلود می‌کند. هر خطایی که **بعد از** آپلود ثبت شود، در داشبورد با نام واقعی فایل‌ها و شماره‌ی خطوط نمایش داده می‌شود؛ دیگر خبری از stackهای minified مثل `4d240bf7.js:1:16945` نیست.

<Callout kind="note" title="کِی به این نیاز دارید؟">
  <p>
    هر بار که build مربوط به production را با minification منتشر می‌کنید (Next.js، Vite، webpack، Rollup).
    بدون source mapهای آپلودشده، هر خطا در داشبورد ابرووا تریس stack فشرده‌شده را نشان می‌دهد که برای debug به کاری نمی‌آید.
  </p>
</Callout>

<H2 id="prerequisites" step={1}>پیش‌نیازها</H2>

سه چیز لازم دارید:

- **Node.js 18+** روی ماشینی که آپلود را اجرا می‌کند (runner مربوط به CI یا سیستم توسعه‌ی خودتان)
- **یک توکن دسترسی شخصی** با دسترسی `sourcemaps:write`
- **DSN پروژه** از بخش **ابرووا تریس ← Source map و symbol** در کنسول ابرووا

<H2 id="install-the-cli" step={2}>نصب CLI</H2>

این CLI از Abrova Center می‌آید. یک بار رجیستری را اضافه کنید، سپس آن را به‌عنوان 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
```

آن را از داخل پروژه با `npx abrova-trace` اجرا کنید (مثلاً `npx abrova-trace --help`). نام دستور `abrova-trace` است.

<H2 id="create-a-personal-access-token" step={3}>ساختن توکن دسترسی شخصی</H2>

توکن‌های دسترسی شخصی (PAT) اعتبارنامه‌هایی بلندمدت و وابسته به کاربرند؛ همان الگویی که بسیاری از CLIهای توسعه‌دهندگان به کار می‌برند. در جریان‌های خودکار، جای توکن نشست کاربر را می‌گیرند.

1. کنسول ابرووا را باز کنید: **[Account → Personal Access Tokens](https://console.abrova.ir/dashboard/account/tokens)**
2. روی **token جدید** کلیک کنید
3. یک نام به آن بدهید (مثلاً `CI upload — production`)
4. دسترسی **`sourcemaps:write`** را فعال کنید
5. تاریخ انقضا را انتخاب کنید (برای CI بدون انقضا هم مشکلی ندارد؛ ۹۰ روز یک حد وسط رایج است)
6. روی **ساخت token** کلیک کنید
7. **مقدار `ab_pat_xxx` را همان لحظه کپی کنید**؛ فقط یک بار نمایش داده می‌شود

این مقدار را در محیط CI به‌عنوان secret با نام `ABROVA_TRACE_TOKEN` ذخیره کنید.

<Callout kind="note" title="امنیت توکن">
  <ul>
    <li>توکن‌ها در سمت ما به‌صورت hash ذخیره می‌شوند؛ توکن گم‌شده را نمی‌توانیم بازیابی کنیم، فقط می‌شود آن را باطل کرد و توکن تازه ساخت.</li>
    <li>خود توکن اعتبارنامه است؛ هر کسی آن را داشته باشد می‌تواند در هر کدام از پروژه‌های شما source map آپلود کند.</li>
    <li>اگر لو رفت، از همان صفحه فوراً باطلش کنید. همه‌ی کارهای CLI/CI که از آن استفاده می‌کنند همان لحظه از کار می‌افتند.</li>
    <li>هرگز توکن را در git commit نکنید. از secretهای سرویس CI خود استفاده کنید (GitHub Actions Secrets، متغیرهای GitLab CI و غیره).</li>
  </ul>
</Callout>

<H2 id="find-your-project-id" step={4}>پیدا کردن شناسه‌ی پروژه</H2>

«project ID» در این CLI همان **DSN پروژه** برای پلتفرم وبی است که mapها به آن تعلق دارند (در یک پروژه‌ی ابرووا، هر پلتفرم DSN جداگانه‌ی خودش را دارد).

1. کنسول ابرووا را باز کنید و پروژه‌تان را انتخاب کنید
2. به **ابرووا تریس ← Source map و symbol** بروید (زبانه‌ی **Source maps**)
3. در کارت **آپلود از CI**، اگر پروژه بیش از یک پلتفرم دارد پلتفرم وب را انتخاب کنید، سپس **DSN پروژه برای CLI** را کپی کنید

این مقدار را با نام `ABROVA_TRACE_PROJECT` در محیط CI ذخیره کنید (CLI متغیر قدیمی `ABROVA_TRACE_DSN` را هم همچنان می‌خواند).

<H2 id="upload-from-ci" step={5}>آپلود از CI</H2>

این دو خط را **درست بعد از build مربوط به production** که فایل‌های source map را می‌سازد، به pipeline اضافه کنید:

```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"
```

همین. CLI همه‌ی فایل‌های `.map` را در پوشه‌ی داده‌شده و زیرپوشه‌هایش پیدا می‌کند، همه را در یک درخواست آپلود می‌کند و با نسخه‌ی release برچسب می‌زند تا ابرووا تریس بتواند آن‌ها را با خطاهای همان نسخه جور کند.

<H2 id="example-upload-next-js-source-maps" step={6}>مثال: آپلود source mapهای Next.js</H2>

در Next.js ساخت source map را در `next.config.js` فعال کنید:

```js
module.exports = {
  productionBrowserSourceMaps: true,
};
```

سپس در اسکریپت CI:

```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}>یکسان بودن نسخه‌ی release</H2>

مقدار فلگ `--release` باید با نسخه‌ای که SDK هنگام ارسال خطا می‌فرستد یکی باشد. اگر SDK مربوط به Next.js این‌طور مقداردهی شده است:

```typescript
AbrovaTrace.init({
  apiKey: process.env.NEXT_PUBLIC_ABROVA_TRACE_API_KEY!,
  release: process.env.NEXT_PUBLIC_APP_VERSION, // e.g. "1.2.3"
});
```

با این دستور آپلود کنید:

```bash
npx abrova-trace sourcemaps upload \
  --release "$NEXT_PUBLIC_APP_VERSION" \
  ./sourcemaps
```

اگر رشته‌های release یکی نباشند، ابرووا تریس source map را برای خطا پیدا نمی‌کند و همان stack فشرده‌شده را نشان می‌دهد.

<Callout kind="note" title="دلیل رایج stackهای بازنگشته">
  <p>
    «source mapها را آپلود کردم اما خطاها هنوز stack فشرده‌شده نشان می‌دهند.»
  </p>
  <p>
    معمولاً رشته‌ی release در آپلود با چیزی که SDK می‌فرستد یکی نیست. نسخه‌ی release را در صفحه‌ی جزئیات خطا در داشبورد ابرووا تریس ببینید، سپس دقیقاً با همان رشته دوباره آپلود کنید.
  </p>
</Callout>

<H2 id="cli-options" step={8}>گزینه‌های CLI</H2>

<BestPracticeList columns={1} items={[
  ['--project <id>', 'DSN پروژه (یا متغیر محیطی ABROVA_TRACE_PROJECT را تنظیم کنید). --dsn <id> نام دیگر همین گزینه است'],
  ['--release <version>', 'الزامی. نسخه‌ی releaseی که این bundle به آن تعلق دارد'],
  ['--token <token>', 'توکن دسترسی شخصی (یا متغیر محیطی ABROVA_TRACE_TOKEN را تنظیم کنید)'],
  ['--api-url <url>', 'آدرس پایه‌ی Trace API (یا متغیر محیطی ABROVA_TRACE_API_URL را تنظیم کنید). پیش‌فرض: https://trace.abrova.ir'],
  ['--dry-run', 'پیش‌نمایش فایل‌هایی که آپلود می‌شوند، بدون ارسال آن‌ها'],
]} />

فلگ بر متغیر محیطی متناظرش اولویت دارد. کلید API پروژه (`ab_live_…`) اینجا کار نمی‌کند؛ CLI توکن دسترسی شخصی لازم دارد.

<H2 id="self-hosted-abrova-trace" step={9}>ابرووا تریس روی سرور خودتان</H2>

<Callout kind="soon">نسخه‌ی self-hosted ابرووا تریس به‌زودی می‌آید. [Self-Hosted](/docs/trace/self-hosted) را ببینید.</Callout>

وقتی ابرووا تریس را روی زیرساخت خودتان اجرا می‌کنید، CLI را به API خودتان وصل کنید:

```bash
export ABROVA_TRACE_API_URL=https://trace.mycompany.com

npx abrova-trace sourcemaps upload \
  --release "1.2.3" \
  ./sourcemaps
```

CLI روی نسخه‌ی self-hosted دقیقاً همان کار را می‌کند؛ بدون تغییر کد، فقط با تغییر URL.

<H2 id="exit-codes" step={10}>کدهای خروج</H2>

- **`0`**: موفق
- **`1`**: هر خطایی (توکن نامعتبر، خطای شبکه، رد شدن آپلود و غیره)

مناسب برای این‌که deploy فقط بعد از آپلود موفق انجام شود:

```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}>محدودیت‌های آپلود</H2>

- **بیشینه‌ی حجم bundle:** ۱۱۰ مگابایت در هر آپلود (کل درخواست multipart)
- **بیشینه‌ی حجم فایل:** ۵۰ مگابایت برای هر فایل `.map`
- **بیشینه‌ی تعداد فایل در هر آپلود:** ۵۰۰

این مقادیر پیش‌فرض سخاوتمندانه‌اند و برای buildهای معمول Next.js، Vite و webpack کافی‌اند. فایل‌های بزرگ‌تر با HTTP 413 رد می‌شوند. اگر bundle شما از ۱۱۰ مگابایت بیشتر است، آن را در چند آپلود با همان `--release` تقسیم کنید (مثلاً هر بار یک پوشه)، یا [با ما تماس بگیرید](/contact).

<H2 id="ios-dsyms" step={12}>dSYMهای iOS</H2>

CLI فقط source mapهای جاوااسکریپت را آپلود می‌کند. debug symbolهای iOS (dSYM) در کنسول ابرووا آپلود می‌شوند:

1. در Xcode به **Organizer › Archives › Download Debug Symbols** بروید، سپس پوشه‌ی `.dSYM` را zip کنید
2. **ابرووا تریس ← Source map و symbol** را باز کنید و زبانه‌ی **dSYMهای iOS** را انتخاب کنید
3. release را انتخاب کنید و فایل `.zip` را رها کنید (در هر آپلود یک `.zip`، تا ۱۰ مگابایت)

آپلود دست‌کم نقش member می‌خواهد؛ حذف فایل‌های آپلودشده نقش admin یا owner. [نقش‌ها و دسترسی‌ها](/docs/trace/error-dashboard#roles) را ببینید.

<H2 id="troubleshooting" step={13}>عیب‌یابی</H2>

<BestPracticeList columns={1} items={[
  ['HTTP 401: Invalid token', 'توکن وجود ندارد، منقضی یا باطل شده، یا دسترسی sourcemaps:write را ندارد. در Account → Personal Access Tokens یک توکن تازه بسازید.'],
  ['HTTP 404: Project not found', 'شناسه‌ی پروژه وجود ندارد یا صاحب توکن به آن دسترسی ندارد. آن را دوباره از ابرووا تریس ← Source map و symbol (DSN پروژه برای CLI) کپی کنید.'],
  ['HTTP 413: Content Too Large', 'حجم bundle از ۱۱۰ مگابایت یا حجم یک فایل .map از ۵۰ مگابایت بیشتر است. به آپلودهای کوچک‌تر تقسیم کنید یا با ما تماس بگیرید.'],
  ['خطاها هنوز stack فشرده‌شده نشان می‌دهند', 'رشته‌ی release یکی نیست. مقدار --release باید با چیزی که SDK می‌فرستد یکی باشد. صفحه‌ی جزئیات خطا را در داشبورد ببینید.'],
  ['هیچ فایل .map پیدا نشد', 'build هیچ source mapی نساخته است. در Next.js مقدار productionBrowserSourceMaps: true را در next.config.js تنظیم کنید.'],
]} />

- گروه‌بندی خطا: https://abrova.ir/docs/trace/error-grouping

گروه‌بندی خطاها خطاهای یکسان را خودکار در یک گروه جمع می‌کند؛ به‌جای دیدن ۱٬۰۰۰ خطای جدا برای یک باگ، یک خطا با شمارش ۱٬۰۰۰ می‌بینید. این کار نویز را کم می‌کند و کمک می‌کند روی مشکل‌های متمایز تمرکز کنید.

<div>
  {[['نویز کمتر', 'خطاهای یکسان با هم گروه‌بندی می‌شوند'], ['ردیابی تکرار', 'تعداد رخدادها و روندشان را ببینید'], ['خودکار', 'پیکربندی لازم ندارد']].map(([t, d]) => (
    <div key={t}>
      <strong>{t}</strong>
      <p>{d}</p>
    </div>
  ))}
</div>

### خطاها چطور گروه‌بندی می‌شوند

خطاهایی که پیام، stack trace و پلتفرم یکسان دارند در یک مشکل گروه‌بندی می‌شوند. هر تفاوتی در متن پیام یا stack trace یک مشکل جدید می‌سازد.

### چه زمانی خطاها با هم گروه می‌شوند

<div>
  <div>
    <strong>با هم گروه می‌شوند</strong>
    <ul>
      <li>خطای یکسان در نشست‌های مختلف کاربران</li>
      <li>خطای تکراری از یک کاربر</li>
      <li>خطای یکسان در محیط‌ها و releaseهای مختلف (اگر پلتفرم یکی باشد)</li>
    </ul>
  </div>
  <div>
    <strong>با هم گروه نمی‌شوند</strong>
    <ul>
      <li>پیام‌های خطای متفاوت</li>
      <li>stack traceهای متفاوت (حتی با تغییر یک شماره‌ی خط)</li>
      <li>پلتفرم‌های متفاوت (flutter_web در برابر flutter_android)</li>
    </ul>
  </div>
</div>

### آشنایی با گروه‌های خطا

هر گروه این‌ها را نگه می‌دارد:

<div>
  {[
    { label: 'تعداد رخداد', value: '۱٬۲۴۷' },
    { label: 'اولین بار دیده‌شده', value: '2025-11-10' },
    { label: 'آخرین بار دیده‌شده', value: '2025-11-12' },
    { label: 'وضعیت', value: 'باز' },
  ].map((item) => (
    <div key={item.label}>
      <p>{item.value}</p>
      <p>{item.label}</p>
    </div>
  ))}
</div>

### دسته‌های تکرار

هر گروه بر اساس تعداد رویدادهایش در یک دسته‌ی تکرار قرار می‌گیرد (فیلتر **تکرار** در صفحه‌ی مشکل‌ها؛ در API به آن `severity` می‌گویند):

<div>
  <table>
    <thead>
      <tr>
        {['تکرار', 'رویدادها', 'رنگ'].map((h) => (
          <th key={h}>{h}</th>
        ))}
      </tr>
    </thead>
    <tbody>
      {[
        ['بسیار پرتکرار', 'بیش از ۱۰۰', 'bg-red-900/30 text-red-400'],
        ['پرتکرار', '۵۱ تا ۱۰۰', 'bg-orange-900/30 text-orange-300'],
        ['تکرارشونده', '۱۱ تا ۵۰', 'bg-yellow-900/30 text-yellow-300'],
        ['نادر', '۱ تا ۱۰', '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>

### مدیریت گروه‌های خطا

- **مدیریت وضعیت:** باز، در حال بررسی، حل‌شده، بایگانی‌شده، نادیده‌گرفته
- **عملیات گروهی:** چند گروه را انتخاب کنید تا وضعیتشان را تغییر دهید یا حذفشان کنید
- **فیلتر:** گروه‌ها را بر اساس وضعیت، تکرار، بازه‌ی زمانی، پلتفرم، محیط، release یا متن جست‌وجو فیلتر کنید

### بهترین روش‌ها

<BestPracticeList items={[
  ['اول خطاهای پرتعداد', 'گروه‌هایی با ۵۱ رویداد یا بیشتر معمولاً روی بیشترین کاربران اثر دارند'],
  ['از مدیریت وضعیت استفاده کنید', 'وضعیت خطاها را برای هماهنگی تیم به‌روز نگه دارید'],
  ['اولین و آخرین زمان دیده شدن را ببینید', 'دنبال کنید خطاها کِی ظاهر می‌شوند و آیا بعد از رفع دوباره برمی‌گردند (گروه‌های حل‌شده خودکار دوباره باز نمی‌شوند)'],
  ['از نسخه‌ی release استفاده کنید', 'گروه‌های خطا را به deployهای مشخص ربط دهید'],
  ['خطاهای قدیمی را بایگانی کنید', 'مشکل‌هایی را که دیگر انتظار دیدنشان را ندارید بایگانی کنید تا داشبورد مرتب بماند'],
]} />

- Breadcrumbs: https://abrova.ir/docs/trace/breadcrumbs

breadcrumbها ردی از رویدادهایی هستند که پیش از رخ دادن خطا اتفاق افتاده‌اند. کمک می‌کنند بفهمید کاربر وقتی مشکل پیش آمد مشغول چه کاری بود.

<div>
  <p><strong>نمونه‌ی مسیر کاربر:</strong></p>
  <div>
    {['کاربر اپ را باز کرد', '← به /checkout رفت', '← روی «پرداخت» کلیک کرد', '← \u{1F4A5} پرداخت ناموفق بود'].map((step, i) => (
      <span key={i}>{step}</span>
    ))}
  </div>
</div>

### Flutter

#### ثبت خودکار ناوبری

```dart
MaterialApp(
  navigatorObservers: [
    AbrovaTraceNavigatorObserver(), // Tracks all screen changes
  ],
  home: HomePage(),
)
```

#### ثبت خودکار لمس‌ها

با یک فراخوانی، برای هر لمس روی دکمه، سوییچ، ردیف فهرست یا هر ویجت تعاملی breadcrumb ثبت می‌شود؛ در Web، Android، iOS، macOS، Windows و Linux. هر breadcrumb نوع ویجت، برچسب، `ValueKey` (اختیاری)، route فعلی و مختصات لمس را ثبت می‌کند.

```dart
// Call once after AbrovaTrace.init() and WidgetsFlutterBinding.ensureInitialized()
AbrovaTrace.enableGestureBreadcrumbs();
```

برای فهرست کامل ویجت‌های شناخته‌شده، ترتیب استخراج برچسب و نکات حریم خصوصی، صفحه‌ی SDK فلاتر را ببینید.

### افزودن breadcrumb دستی

#### 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

<div>
  <table>
    <thead>
      <tr>
        {['نوع', 'توضیح'].map((h) => (
          <th key={h}>{h}</th>
        ))}
      </tr>
    </thead>
    <tbody>
      {[
        ['BreadcrumbType.user', 'کارهای کاربر (کلیک، لمس، کشیدن)'],
        ['BreadcrumbType.navigation', 'تغییر صفحه (با observer خودکار)'],
        ['BreadcrumbType.http', 'فراخوانی‌های API و درخواست‌های شبکه'],
        ['BreadcrumbType.state', 'تغییرات وضعیت اپ'],
        ['BreadcrumbType.info', 'رویدادهای اطلاعاتی عمومی'],
        ['BreadcrumbType.error', 'رویدادهای خطا'],
        ['BreadcrumbType.system', 'رویدادهای SDK و سیستم'],
      ].map(([type, desc]) => (
        <tr key={type}>
          <td><code>{type}</code></td>
          <td>{desc}</td>
        </tr>
      ))}
    </tbody>
  </table>
</div>

### مثال کامل

```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'),
    );
  }
}
```

### دیدن breadcrumbها

breadcrumbها هنگام دیدن جزئیات هر خطا خودکار در داشبورد نمایش داده می‌شوند. یک خط زمانی نشان می‌دهند: رویدادهای ناوبری، کلیک‌های کاربر، درخواست‌های API و در آخر خود خطا.

### بهترین روش‌ها

<BestPracticeList items={[
  ['پیش از کارهای مهم اضافه کنید', 'پیش از پرداخت، تغییر داده و جریان‌های ورود breadcrumb ثبت کنید'],
  ['پیام‌های گویا بنویسید', '«کاربر روی checkout کلیک کرد» بهتر از «دکمه کلیک شد» است'],
  ['داده‌های مرتبط را بگذارید', 'شناسه‌ها، مبالغ و context را اضافه کنید، اما از اطلاعات حساس پرهیز کنید'],
  ['زیاده‌روی نکنید', 'breadcrumb زیاد می‌تواند پرسروصدا شود؛ روی رویدادهای معنادار تمرکز کنید'],
]} />

- معرفی لاگ‌ها: https://abrova.ir/docs/trace/logs

لاگ‌های کانتینرهای Docker، SDKها و ارسال مستقیم از API را یک‌جا جمع و تحلیل کنید. لاگ‌ها را به‌صورت بلادرنگ ببینید، جستجو و فیلتر کنید.

<BestPracticeList columns={2} items={[
  ['ایجنت برای Docker', 'با اجرای فقط یک کانتینر، لاگ همه‌ی کانتینرهای Docker به‌طور خودکار ارسال می‌شود'],
  ['لاگ‌گیری با SDK', 'SDKهای native برای Flutter، Node.js، Next.js، Android، iOS و Laravel با ارسال دسته‌ای و تلاش دوباره'],
  ['ارسال از API', 'لاگ‌ها را از هر اپلیکیشن، زبان یا فریم‌ورکی مستقیم با REST API بفرستید'],
  ['جستجو و فیلتر', 'جستجوی متن کامل با فیلتر سطح (error، warn، info، debug، trace) و فیلتر منبع'],
  ['داشبورد بلادرنگ', 'مشاهده‌ی بلادرنگ لاگ‌ها با به‌روزرسانی خودکار، کارت‌های آمار و نمایشگر جزئیات لاگ'],
  ['پشتیبانی از ارسال دسته‌ای', 'ارسال دسته‌ای کارآمد برای حجم بالای لاگ'],
]} />

### شروع سریع: ایجنت برای Docker

```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
```

از کلید سرور پروژه (`ab_srv_...`) در کنسول ابرووا استفاده کنید. لاگ همه‌ی کانتینرها در **ابرووا تریس › Logs** نمایش داده می‌شود. راه‌اندازی روی چند host، مدیریت کانتینرها و همه‌ی گزینه‌ها: [ایجنت ابرووا تریس](/docs/trace/agent).

### شروع سریع: لاگ‌گیری با SDK

با SDKهای native، لاگ‌ها به‌طور خودکار دسته‌ای ارسال می‌شوند، تلاش دوباره با فاصله‌ی افزایشی (exponential backoff) انجام می‌شود و چرخه‌ی حیات اپ موبایل در نظر گرفته می‌شود.

#### 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:** تلاش دوباره با فاصله‌ی افزایشی (حداکثر ۶۰ ثانیه بین تلاش‌ها)، بافر با سقف ۱٬۰۰۰ لاگ، تایمرهای تنبل (در حالت بیکار باتری مصرف نمی‌شود)، و hookهای چرخه‌ی حیات موبایل (ارسال خودکار هنگام رفتن اپ به پس‌زمینه). جزئیات در هر SDK فرق دارد؛ صفحه‌ی لاگ‌گیری هر SDK را ببینید.

### شروع سریع: ارسال از API

فهرست کامل فیلدها و نمونه‌ها به زبان‌های دیگر: [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"
  }'
```

### ارسال دسته‌ای

```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" }
    ]
  }'
```

### سطح‌های لاگ

- **fatal** — خطاهای بحرانی و غیرقابل بازیابی
- **error** — خطاهایی که باید بررسی شوند
- **warn** — هشدار درباره‌ی مشکلات احتمالی
- **info** — اطلاعات عمومی اپلیکیشن
- **debug** — اطلاعات دقیق برای دیباگ
- **trace** — دیباگ بسیار جزئی در سطح trace

### سقف‌ها و هزینه‌ها

<Callout kind="wallet">
رایگان در هر ماه: ۱ گیگابایت لاگ. بیش از آن، هزینه از کیف پول: هر گیگابایت ۱۵٬۰۰۰ تومان. لاگ‌ها ۳۰ روز نگه داشته می‌شوند. [قیمت‌ها](/pricing) را ببینید.
</Callout>

ارسال لاگ برای هر کلید و هر آدرس کلاینت سقف درخواست بالایی دارد. کلاینتی که از این سقف بگذرد پاسخ HTTP `429` با هدر `Retry-After` می‌گیرد؛ با ارسال دسته‌ای لاگ‌ها بسیار پایین‌تر از این سقف می‌مانید.

- ایجنت ابرووا تریس (Docker): https://abrova.ir/docs/trace/agent

ایجنت ابرووا تریس لاگ همه‌ی کانتینرهای Docker روی سرور شما را استریم می‌کند؛ همراه با مدیریت لحظه‌ای کانتینرها، پشتیبانی از چند سرور و تشخیص خودکار سطح لاگ. برای راه‌اندازی فقط یک دستور `docker run` لازم است.

<Callout kind="note" title="ایجنت چه چیزهایی به شما می‌دهد">
  <ul>
    <li>لاگ زنده‌ی Docker در کنسول ابرووا — همه‌ی کانتینرها و همه‌ی سرورها در یک فید</li>
    <li>مدیریت کانتینر از کنسول: start، stop، restart و حذف</li>
    <li>آمار زنده‌ی CPU، حافظه و شبکه برای هر کانتینر</li>
    <li>چند سرور: یک collector لاگ ایجنت‌های راه دور روی سرورهای دیگر را جمع می‌کند</li>
    <li>تشخیص خودکار سطح لاگ، یکی کردن خروجی چندخطی (هر stack trace یک ورودی می‌شود) و پوشاندن اطلاعات محرمانه پیش از خروج هر چیزی از سرور</li>
  </ul>
</Callout>

<Callout kind="wallet">
لاگ کانتینرها جزو لاگ‌های ابرووا تریس شما حساب می‌شود: ۱ گیگابایت رایگان در هر ماه، و بعد از آن هر گیگابایت ۱۵٬۰۰۰ تومان هزینه از کیف پول. [قیمت‌ها](/pricing) را ببینید.
</Callout>

### نحوه‌ی کار

ایجنت از معماری **collector + ایجنت راه دور** استفاده می‌کند:

1. **collector** روی سرور اصلی شما اجرا می‌شود. کانتینرهای محلی را زیر نظر می‌گیرد، به ایجنت‌های راه دور وصل می‌شود و لاگ‌ها را دسته‌دسته از طریق HTTPS به ابرووا تریس می‌فرستد.
2. **ایجنت‌های راه دور** روی سرورهای دیگر اجرا می‌شوند و لاگ کانتینرهایشان را از طریق WebSocket به collector استریم می‌کنند.
3. همه‌ی کانتینرها (در حال اجرا و متوقف) در پروژه‌ی شما ثبت می‌شوند تا بتوانید آن‌ها را ببینید و مدیریت کنید.
4. ارتباط دوطرفه است، پس دستورهای کانتینر (start، stop، restart، حذف، آمار) به هر سروری می‌رسند.

اگر فقط یک سرور دارید، همان collector کافی است؛ حالت پیش‌فرض هم همین است.

<ConfigTable headers={['حالت', 'دستور', 'کارکرد']} rows={[
  ['پیش‌فرض (collector)', '(none)', 'Docker محلی را زیر نظر می‌گیرد و به ایجنت‌های راه دور وصل می‌شود؛ لاگ‌ها را به ابرووا تریس می‌فرستد. به کلید نیاز دارد'],
  ['ایجنت', 'agent', 'سرور WebSocket که لاگ کانتینرهای این سرور را به یک collector استریم می‌کند. کلید لازم ندارد'],
  ['فقط collector', 'collector', 'فقط به ایجنت‌های راه دور وصل می‌شود و Docker محلی را زیر نظر نمی‌گیرد. به کلید نیاز دارد'],
]} />

<H2 id="deploy-manually-single-server" step={1}>راه‌اندازی روی یک سرور</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="ایمیج از کجا می‌آید">
  ایمیج ایجنت از `ghcr.io` (رجیستری کانتینر GitHub) دریافت می‌شود، پس سرور باید به آن دسترسی داشته باشد. اگر دسترسی ندارد، ایمیج را روی دستگاهی که دسترسی دارد pull کنید و بعد با `docker save ghcr.io/abrova-co/abrova-trace-agent:latest -o agent.tar` و `docker load -i agent.tar` منتقلش کنید.
</Callout>

این volume بافر دیسک ایجنت و موقعیت‌های خوانده‌شده را هنگام ساخت دوباره‌ی کانتینر نگه می‌دارد تا هیچ خطی گم نشود یا دو بار فرستاده نشود.

<Callout kind="secret" title="کدام کلید؟">
  **کلید سرور** پروژه (`ab_srv_...`) را در `ABROVA_TRACE_API_KEY` به ایجنت بدهید. کلید اپ (`ab_live_...`) هم تا وقتی تنظیم پروژه‌ی **Server routes require the server secret** خاموش است کار می‌کند، اما این کلید داخل اپ‌های شما منتشر می‌شود و نباید ایجنت با آن اجرا شود. [کلید سرور و مسیرهای سرور](/docs/trace/server-secret) را ببینید.
</Callout>

ایجنت ظرف چند ثانیه همه‌ی کانتینرهای در حال اجرا و متوقف را در پروژه‌ی شما ثبت می‌کند. در کنسول ابرووا، **ابرووا تریس › Logs** را باز کنید تا رسیدن لاگ‌ها را ببینید.

<H2 id="multi-host-setup" step={2}>راه‌اندازی چند سرور</H2>

برای چند سرور، روی هر سرور اضافه یک **ایجنت راه دور** راه بیندازید و یک **collector** را به آن‌ها وصل کنید.

#### ایجنت راه دور (روی هر سرور اضافه)

```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 (روی سرور اصلی)

```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
```

مقدار `ABROVA_TRACE_REMOTE_AGENTS` فهرستی از `name:host:port` است که با کاما جدا شده‌اند. هر ایجنت راه دور لاگ‌ها را از طریق WebSocket به collector استریم می‌کند و پس از قطع ارتباط خودش دوباره وصل می‌شود (هر ۵ ثانیه).

<Callout kind="soon" title="راه‌اندازی از اپ دسکتاپ">
  [اپ دسکتاپ ابرووا](/desktop) (به‌زودی) ایجنت را از طریق SSH برایتان روی سرورها راه می‌اندازد: سرور را اضافه کنید، کلید میزبانش را تأیید کنید و راه‌اندازی کنید. تا آن زمان از دستورهای `docker run` همین صفحه استفاده کنید.
</Callout>

<H2 id="what-you-can-do-from-the-console" step={3}>مدیریت کانتینرها از کنسول</H2>

در کنسول ابرووا، **ابرووا تریس › Logs** را باز کنید. پنل **منبع‌ها** همه‌ی سرورها و کانتینرهایشان را فهرست می‌کند؛ منوی کنار هر کانتینر این گزینه‌ها را دارد:

- **مشاهدهٔ آمار** — پنجره‌ای زنده با درصد CPU، حافظه‌ی مصرفی / سقف حافظه و درصد حافظه، و RX / TX شبکه (بایت‌های دریافتی و ارسالی روی همه‌ی رابط‌های شبکه)
- **شروع** — اجرای یک کانتینر متوقف
- **restart** — راه‌اندازی دوباره در همان جا
- **توقف** — توقف آرام یک کانتینر در حال اجرا
- **حذف** — توقف و حذف کانتینر

دستورها از طریق ابرووا تریس به WebSocket ایجنت می‌رسند، پس فرقی نمی‌کند کانتینر روی سرور اصلی باشد یا روی سروری با ایجنت راه دور.

برای start، stop، restart و حذف، نقش **admin** یا **owner** لازم است؛ همه‌ی نقش‌ها می‌توانند کانتینرها، لاگ‌ها و آمار را ببینند. [نقش‌ها و دسترسی‌ها](/docs/trace/error-dashboard#roles) را ببینید.

<H2 id="configuration-reference" step={4}>مرجع پیکربندی</H2>

#### متغیرهای محیطی collector

<ConfigTable rows={[
  ['ABROVA_TRACE_API_KEY', 'string', 'بله', 'کلید سرور پروژه (ab_srv_...، پیشنهادی). کلید اپ (ab_live_...) فقط تا وقتی تنظیم «Server routes require the server secret» خاموش است کار می‌کند'],
  ['ABROVA_TRACE_URL', 'string', 'خیر', 'آدرس API ابرووا تریس (پیش‌فرض: https://trace.abrova.ir)'],
  ['ABROVA_TRACE_EXCLUDE', 'string', 'خیر', 'نام کانتینرهایی که کنار گذاشته می‌شوند، جداشده با کاما (پیش‌فرض: abrova-trace-agent)'],
  ['ABROVA_TRACE_INCLUDE', 'string', 'خیر', 'نام کانتینرهایی که زیر نظر گرفته می‌شوند، جداشده با کاما (خالی = همه)'],
  ['ABROVA_TRACE_LABEL_FILTER', 'string', 'خیر', 'فقط کانتینرهایی با این label زیر نظر گرفته می‌شوند (مثلاً abrova-trace.project=abc123)؛ بر include/exclude اولویت دارد'],
  ['ABROVA_TRACE_REMOTE_AGENTS', 'string', 'خیر', 'ایجنت‌های راه دور با قالب name:host:port، جداشده با کاما'],
  ['ABROVA_TRACE_HOSTNAME', 'string', 'خیر', 'نامی که این سرور با آن نمایش داده می‌شود (پیش‌فرض: نام میزبان Docker)'],
]} />

#### متغیرهای محیطی ایجنت راه دور

<ConfigTable rows={[
  ['ABROVA_TRACE_AGENT_PORT', 'number', 'خیر', 'پورت WebSocket ایجنت (پیش‌فرض: 7008)'],
  ['ABROVA_TRACE_HOSTNAME', 'string', 'خیر', 'نامی که این سرور با آن نمایش داده می‌شود (پیش‌فرض: نام میزبان سیستم)'],
  ['ABROVA_TRACE_EXCLUDE', 'string', 'خیر', 'نام کانتینرهایی که کنار گذاشته می‌شوند، جداشده با کاما (پیش‌فرض: abrova-trace-agent)'],
  ['ABROVA_TRACE_INCLUDE', 'string', 'خیر', 'نام کانتینرهایی که زیر نظر گرفته می‌شوند، جداشده با کاما (خالی = همه)'],
  ['ABROVA_TRACE_LABEL_FILTER', 'string', 'خیر', 'فقط کانتینرهایی با این label زیر نظر گرفته می‌شوند'],
]} />

#### پردازش لاگ (همه‌ی حالت‌ها)

<ConfigTable rows={[
  ['ABROVA_TRACE_MULTILINE', 'boolean', 'خیر', 'stack traceها و خروجی چندخطی در یک ورودی یکی می‌شوند (پیش‌فرض: true)'],
  ['ABROVA_TRACE_REDACT', 'boolean', 'خیر', 'پوشاندن اطلاعات محرمانه: توکن‌ها، رمزهای عبور، کلیدهای API و اطلاعات ورود داخل URLها (پیش‌فرض: true)'],
  ['ABROVA_TRACE_REDACT_PII', 'boolean', 'خیر', 'پوشاندن آدرس‌های ایمیل و شماره‌تلفن‌ها (پیش‌فرض: true)'],
  ['ABROVA_TRACE_HEALTH_SAMPLE', 'number', 'خیر', 'از هر N خط health check موفق یکی نگه داشته می‌شود؛ 1 = همه، 0 = هیچ‌کدام (پیش‌فرض: 20)'],
  ['ABROVA_TRACE_DROP', 'string', 'خیر', 'عبارت‌های منظم که با || جدا می‌شوند؛ ورودی‌های منطبق فرستاده نمی‌شوند'],
  ['ABROVA_TRACE_DATA_DIR', 'string', 'خیر', 'بافر دیسک و موقعیت‌های خوانده‌شده (پیش‌فرض: /var/lib/abrova-trace-agent؛ برای نگه داشتنشان یک volume وصل کنید)'],
  ['ABROVA_TRACE_SPOOL_MB', 'number', 'خیر', 'سقف بافر دیسک به مگابایت؛ بیش از آن، قدیمی‌ترین دسته‌های ارسال‌نشده دور ریخته می‌شوند (پیش‌فرض: 50)'],
  ['ABROVA_TRACE_CATCHUP_SECONDS', 'number', 'خیر', 'پس از راه‌اندازی دوباره، اگر آخرین خط خوانده‌شده تا این حد تازه باشد، ادامه از همان‌جا (پیش‌فرض: 900)'],
]} />

<H2 id="log-level-detection" step={5}>تشخیص سطح لاگ</H2>

ایجنت برای هر ورودی یک سطح تعیین می‌کند تا فیلترهای سطح در کنسول بدون تغییر کد کار کنند:

- **نشانه‌های صریح مقدم‌اند** — `[ERROR]`، `ERROR:`، `level=warn`، `[debug]` و موارد مشابه در ابتدای خط، همان سطحی را می‌گیرند که نوشته شده. `critical` و `panic` **fatal** حساب می‌شوند، `notice` **info** و `verbose` **trace**.
- **لاگ‌های JSON** — فیلد `level`، `severity`، `lvl` یا `loglevel` استفاده می‌شود، از جمله سطح‌های عددی pino و bunyan.
- **خط‌های NestJS** (`[Nest] PID - TIMESTAMP LEVEL ...`) سطحی را می‌گیرند که NestJS چاپ کرده.
- **در غیر این صورت، کلیدواژه‌ها** — `fatal` یا `panic` ← fatal؛ `error`، `exception`، `failed`، `unhandled`، `uncaught`، `ECONNREFUSED`، `ETIMEDOUT` ← error؛ `warn`، `warning`، `deprecated` ← warn؛ `debug`، `dbg` ← debug.
- **info** — پیش‌فرض وقتی هیچ‌کدام منطبق نباشد؛ پس `info: 0 errors found` همان info می‌ماند.

<H2 id="what-an-entry-carries" step={6}>هر ورودی چه چیزهایی دارد</H2>

هر ورودی لاگ یک *رویداد* است، نه یک خط. علاوه بر پیام و سطح، فیلدهای اضافه‌ای در `metadata` دارد:

<ConfigTable headers={['فیلد', 'معنا']} rows={[
  ['fingerprint / template', 'پیام با شناسه‌ها، عددها و تاریخ‌هایی که با جای‌نگهدار جایگزین شده‌اند، و یک hash از آن، تا مشکل‌های یکسان کنار هم گروه شوند'],
  ['attributes', 'فیلدهایی که از لاگ‌های JSON، جفت‌های key=value و خط‌های دسترسی HTTP استخراج شده‌اند (method، path، status، durationMs)'],
  ['traceId', 'شناسه‌ی درخواست یا trace که در ورودی پیدا شده، برای دنبال کردن یک درخواست در چند کانتینر'],
  ['lines', 'تعداد خط‌های خامی که یکی شده‌اند (stack traceها، شیءهای چاپ‌شده)'],
  ['kind: container_event', 'یک رویداد چرخه‌ی عمر Docker (start، کد خروج، kill به‌خاطر کمبود حافظه، restart، health check) که در همان خط زمانی نوشته می‌شود'],
  ['sampled', 'این خط health check نماینده‌ی N خط است'],
  ['hostname', 'میزبان Docker'],
]} />

<H2 id="how-log-delivery-works" step={7}>دسته‌بندی و ارسال</H2>

- **ارسال دسته‌ای** — لاگ‌ها در دسته‌های حداکثر ۱۰۰ ورودی یا هر ۵ ثانیه، هر کدام زودتر برسد، فرستاده می‌شوند.
- **تلاش دوباره هنگام خطا** — دسته‌های ناموفق دوباره در صف قرار می‌گیرند و ارسالشان تکرار می‌شود؛ برای هر منبع تا ۵٬۰۰۰ ورودی در انتظار در حافظه نگه داشته می‌شود (بیش از آن، قدیمی‌ترین‌ها دور ریخته می‌شوند).
- **بافر دیسک** — اگر ابرووا تریس در دسترس نباشد، دسته‌ها در `ABROVA_TRACE_DATA_DIR` نوشته می‌شوند و وقتی دوباره در دسترس شد به ترتیب ارسال می‌شوند (تا سقف `ABROVA_TRACE_SPOOL_MB`).
- **ادامه پس از راه‌اندازی دوباره** — ایجنت آخرین خط خوانده‌شده‌ی هر کانتینر را به خاطر می‌سپارد و از همان‌جا ادامه می‌دهد.
- **خاموش شدن آرام** — `docker stop abrova-trace-agent` پیش از خروج، دسته‌های در انتظار را می‌فرستد.

### ویژگی‌های اصلی

<BestPracticeList items={[
  ['کشف خودکار', 'کانتینرهای جدید به محض اجرا شناسایی و زیر نظر گرفته می‌شوند'],
  ['ثبت کانتینرها', 'همه‌ی کانتینرها (در حال اجرا و متوقف) هنگام شروع در پروژه‌ی شما ثبت می‌شوند'],
  ['گزارش وضعیت', 'رویدادهای start، stop، die و kill کانتینرها همان لحظه گزارش می‌شوند'],
  ['پشتیبانی از چند سرور', 'کانتینرهای چند سرور را از یک جا مانیتور کنید'],
  ['اتصال دوباره‌ی خودکار', 'ارتباط ایجنت‌های راه دور پس از قطع شدن خودش برقرار می‌شود (با ۵ ثانیه تأخیر)'],
  ['پوشاندن اطلاعات محرمانه', 'توکن‌ها، رمزهای عبور، کلیدهای API، آدرس‌های ایمیل و شماره‌تلفن‌ها پیش از خروج هر چیزی از سرور پوشانده می‌شوند'],
]} />

### مدل امنیتی

<BestPracticeList items={[
  ['دسترسی به سوکت Docker', 'ایجنت /var/run/docker.sock را mount می‌کند. پرچم :ro فقط از فایل سوکت محافظت می‌کند، نه از API داکر؛ پس با ایجنت مثل هر کانتینر دیگری که به Docker دسترسی دارد رفتار کنید. ایجنت فقط وقتی روی کانتینرها کاری انجام می‌دهد که دستور start / stop / restart / remove / stats از ابرووا تریس برسد، و ابرووا تریس آن را با اعتبارنامه‌ی پروژه‌ی شما احراز هویت می‌کند.'],
  ['ایجنت را با کلید سرور اجرا کنید', 'برای ایجنت از کلید سرور (ab_srv_...) استفاده کنید و «Server routes require the server secret» را در تنظیمات پروژه › محصولات › ابرووا تریس روشن کنید. کلید اپ داخل اپ‌های شما منتشر می‌شود؛ با روشن بودن این تنظیم، دیگر نمی‌توان با آن به‌عنوان ایجنت وصل شد یا کانتینر ثبت کرد.'],
  ['کلید را بیرون از فایل‌ها نگه دارید', 'کلید را با متغیر محیطی یا Docker secrets بدهید؛ هرگز آن را مستقیم در فایل compose که commit می‌کنید ننویسید.'],
  ['مجوز دستورها بر اساس نقش', 'دستورهای کانتینر را owner یا admin واردشده‌ی پروژه می‌دهد؛ این دستورها از ابرووا تریس می‌گذرند و بعد از طریق WebSocket به ایجنت می‌رسند. ایجنت هرگز از جای دیگری دستور نمی‌پذیرد.'],
  ['پورت ایجنت راه دور (7008)', 'فقط باید از collector شما در دسترس باشد. فایروال را طوری تنظیم کنید که فقط آدرس collector بتواند وصل شود.'],
]} />

### عیب‌یابی

<TroubleshootItem title="کانتینر ایجنت مدام restart می‌شود">
  لاگ ایجنت را بررسی کنید: `docker logs abrova-trace-agent`. علت‌های رایج: کلید نامعتبر، در دسترس نبودن آدرس API یا mount نشدن سوکت Docker.
</TroubleshootItem>

<TroubleshootItem title="لاگ‌ها می‌رسند، اما کانتینرها دیده نمی‌شوند یا قابل کنترل نیستند">
  اگر تنظیم پروژه‌ی **Server routes require the server secret** روشن باشد و ایجنت با کلید اپ اجرا شود، خط‌های لاگ همچنان می‌رسند، اما ایجنت نمی‌تواند کانتینرها را ثبت کند، وضعیتشان را گزارش دهد یا دستور بگیرد. ایجنت را دوباره با مقدار کلید سرور (`ab_srv_...`) برای `ABROVA_TRACE_API_KEY` راه‌اندازی کنید. [کلید سرور و مسیرهای سرور](/docs/trace/server-secret) را ببینید.
</TroubleshootItem>

<TroubleshootItem title="کانتینرها در کنسول نمایش داده نمی‌شوند">
  ایجنت کانتینرها را هنگام شروع ثبت می‌کند. اگر ایجنت را بعد از اجرای کانتینرها اضافه کرده‌اید و هنوز دیده نمی‌شوند، ایجنت را restart کنید: `docker restart abrova-trace-agent`.
</TroubleshootItem>

<TroubleshootItem title="پنجره‌ی آمار صفر نشان می‌دهد یا به‌روز نمی‌شود">
  آمار از daemon محلی Docker ایجنتی خوانده می‌شود که کانتینر روی آن است. سروری که فقط در حالت `agent` اجرا می‌شود، لاگ‌هایش را به collector خودش استریم می‌کند؛ اگر آمار کانتینرهای آن خالی می‌ماند، بررسی کنید collector به آن وصل باشد (مورد بعدی را ببینید).
</TroubleshootItem>

<TroubleshootItem title="ایجنت راه دور وصل نمی‌شود">
  مطمئن شوید پورت 7008 از سمت collector در دسترس است، مثلاً `ufw allow from COLLECTOR_IP to any port 7008`. قالب `ABROVA_TRACE_REMOTE_AGENTS` را دوباره بررسی کنید: `name:host:port`، جداشده با کاما.
</TroubleshootItem>

<TroubleshootItem title="هیچ لاگی نمایش داده نمی‌شود">
  بررسی کنید کانتینرهایتان در فهرست کنارگذاشته‌ها (`ABROVA_TRACE_EXCLUDE`) نباشند و اگر `ABROVA_TRACE_INCLUDE` / `ABROVA_TRACE_LABEL_FILTER` را تنظیم کرده‌اید، با آن‌ها منطبق باشند. درست بودن کلید و دسترسی ایجنت به آدرس API را بررسی کنید. لاگ‌ها دسته‌ای فرستاده می‌شوند — تا ۵ ثانیه برای نمایششان صبر کنید.
</TroubleshootItem>

<TroubleshootItem title="خطی که لازم دارم وجود ندارد">
  `ABROVA_TRACE_DROP` (ورودی‌های منطبق فرستاده نمی‌شوند) و `ABROVA_TRACE_HEALTH_SAMPLE` را بررسی کنید (به‌طور پیش‌فرض از هر ۲۰ خط health check موفق فقط یکی نگه داشته می‌شود؛ برای نگه داشتن همه، آن را `1` بگذارید).
</TroubleshootItem>

- لاگ در SDK فلاتر: https://abrova.ir/docs/trace/flutter-logging

لاگ‌گیری کم‌مصرف برای اپ‌های Flutter با ارسال دسته‌ای خودکار، تلاش دوباره با فاصله‌ی افزایشی (exponential backoff) و توجه به چرخه‌ی حیات موبایل. لاگ‌ها در بافر نگه داشته و به‌صورت دسته‌ای ارسال می‌شوند تا مصرف شبکه کم بماند.

<Callout kind="note" title="لاگ‌ها در برابر پیام‌ها">
لاگ‌ها (`AbrovaTrace.info()`، `warn()`، `logError()`، ...) در بافر نگه داشته، دسته‌ای ارسال و در **ابرووا تریس › Logs** نمایش داده می‌شوند. این‌ها از `AbrovaTrace.captureMessage()` جدا هستند؛ آن متد یک رویداد را همان لحظه به **ابرووا تریس › پیام‌ها** می‌فرستد. هیچ‌کدام مشکل (issue) نمی‌سازند؛ برای این کار از `captureException()` استفاده کنید.
</Callout>

<BestPracticeList columns={2} items={[
  ['ارسال دسته‌ای خودکار', 'لاگ‌ها در بافر نگه داشته و دسته‌ای ارسال می‌شوند (پیش‌فرض: ۵۰)'],
  ['فاصله‌ی افزایشی', 'دسته‌های ناموفق با تأخیر فزاینده دوباره ارسال می‌شوند (۲ ثانیه، ۴ ثانیه، ۸ ثانیه... تا ۶۰ ثانیه، حداکثر ۱۰ بار)'],
  ['Hookهای چرخه‌ی حیات', 'هنگام رفتن اپ به پس‌زمینه خودکار ارسال می‌کند و در حالت غیرفعال متوقف می‌شود'],
  ['سقف اندازه‌ی بافر', 'وقتی بافر از ۱٬۰۰۰ بیشتر شود، قدیمی‌ترین لاگ‌ها حذف می‌شوند تا مشکل حافظه پیش نیاید'],
  ['تایمر تنبل', 'تایمر فقط وقتی بافر لاگ دارد اجرا می‌شود؛ در حالت بیکار باتری مصرف نمی‌شود'],
  ['اطلاعات کاربر', 'شناسه‌ی کاربری که با AbrovaTrace.setUserId() تنظیم شده خودکار ضمیمه می‌شود'],
]} />

<H2 id="enable-logging" step={1}>فعال‌سازی لاگ‌گیری</H2>

پس از مقداردهی اولیه‌ی AbrovaTrace، سرویس لاگ‌گیری را فعال کنید:

```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),
);
```

اگر یکی از متدهای لاگ را پیش از `enableLogging()` صدا بزنید، لاگ‌گیری خودکار با مقادیر پیش‌فرض و بدون `sourceId` فعال می‌شود. لاگ‌گیری به Flutter binding نیاز دارد، پس آن را پس از `WidgetsFlutterBinding.ensureInitialized()` فعال کنید (یا اولین لاگ را بعد از آن بفرستید).

<H2 id="sending-logs" step={2}>ارسال لاگ‌ها</H2>

#### متدهای کمکی

```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',
});
```

#### متد عمومی لاگ

```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}>سطح‌های لاگ</H2>

- **trace** — `AbrovaTrace.trace()` — دیباگ بسیار جزئی در سطح trace
- **debug** — `AbrovaTrace.debug()` — اطلاعات دیباگ هنگام توسعه
- **info** — `AbrovaTrace.info()` — اطلاعات عمومی اپلیکیشن
- **warn** — `AbrovaTrace.warn()` — هشدار درباره‌ی مشکلات احتمالی
- **error** — `AbrovaTrace.logError()` — خطاهایی که باید بررسی شوند
- **fatal** — `AbrovaTrace.fatal()` — خطاهای بحرانی و غیرقابل بازیابی

<H2 id="mobile-lifecycle-behavior" step={4}>رفتار در چرخه‌ی حیات موبایل</H2>

سرویس لاگ‌گیری رویدادهای چرخه‌ی حیات اپ را خودکار مدیریت می‌کند:

- **توقف اپ / رفتن به پس‌زمینه** — همه‌ی لاگ‌های بافر را فوراً ارسال می‌کند
- **بازگشت اپ** — شمارنده‌ی تلاش دوباره را صفر می‌کند و کار عادی ادامه پیدا می‌کند
- **جدا شدن اپ (detached)** — لاگ‌ها را ارسال می‌کند و ارسال را متوقف می‌کند
- **پر شدن بافر** — وقتی از سقف بافر (۱٬۰۰۰) بیشتر شود، قدیمی‌ترین لاگ‌ها حذف می‌شوند

<H2 id="manual-operations" step={5}>عملیات دستی</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}>پیکربندی</H2>

<ConfigTable rows={[
  ['sourceId', 'String?', 'خیر', 'شناسه‌ی این منبع لاگ (مثلاً "my-flutter-app"). برای ارسال دسته‌ای لازم است؛ بدون آن هر لاگ در یک درخواست جدا ارسال می‌شود و ارسال‌های ناموفق دوباره تلاش نمی‌شوند'],
  ['sourceName', 'String?', 'خیر', 'نام خوانا برای این منبع'],
  ['batchSize', 'int', 'خیر', 'وقتی بافر به این اندازه برسد ارسال می‌شود (پیش‌فرض: ۵۰)'],
  ['flushInterval', 'Duration', 'خیر', 'حداکثر زمان پیش از ارسال (پیش‌فرض: ۵ ثانیه)'],
]} />

بافر حداکثر ۱٬۰۰۰ لاگ نگه می‌دارد (قدیمی‌ترین‌ها اول حذف می‌شوند). این سقف ثابت است و با `enableLogging()` تغییر نمی‌کند.

### توصیه‌ها

<BestPracticeList items={[
  ['زود فعال کنید', 'لاگ‌گیری را درست بعد از AbrovaTrace.init() فعال کنید تا همه‌ی رویدادها ثبت شوند'],
  ['از sourceId استفاده کنید', 'یک sourceId معنادار تنظیم کنید تا لاگ‌های این اپ در داشبورد قابل تشخیص باشند'],
  ['metadata اضافه کنید', 'metadata ساخت‌یافته (شناسه‌ی کاربر، نام صفحه و ...) بگذارید تا دیباگ آسان‌تر شود'],
  ['سطح مناسب را انتخاب کنید', 'برای رویدادهای عادی info، برای مشکلات احتمالی warn و برای خطاها error'],
  ['پیش از بستن ارسال کنید', 'پیش از بسته شدن اپ AbrovaTrace.flushLogs() را صدا بزنید تا همه‌ی لاگ‌ها ارسال شوند'],
  ['زیاده‌روی نکنید', 'در حلقه‌های فشرده لاگ نزنید؛ بافر سقف دارد و قدیمی‌ترین لاگ‌ها را حذف می‌کند'],
]} />

- لاگ در SDK اندروید: https://abrova.ir/docs/trace/android-logging

لاگ‌گیری ساختاریافته برای اپ‌های Android با ارسال دسته‌ای خودکار، تلاش مجدد با فاصله‌ی افزایشی (exponential backoff) و آگاهی از چرخه‌ی حیات اپ. لاگ‌ها بافر می‌شوند و دسته‌ای فرستاده می‌شوند تا مصرف اینترنت و باتری کم بماند.

<BestPracticeList columns={2} items={[
  ['ارسال دسته‌ای خودکار', 'لاگ‌ها بافر می‌شوند و دسته‌ای فرستاده می‌شوند (پیش‌فرض: ۵۰)'],
  ['تلاش مجدد با فاصله‌ی افزایشی', 'دسته‌های ناموفق با فاصله‌های بیشترشونده دوباره فرستاده می‌شوند (۲ ثانیه، ۴ ثانیه، ۸ ثانیه... تا ۶۰ ثانیه)'],
  ['حداکثر اندازه‌ی بافر', 'وقتی بافر از ۱۰۰۰ لاگ بگذرد، قدیمی‌ترین لاگ‌ها حذف می‌شوند تا حافظه پر نشود'],
  ['تایمر تنبل', 'تایمر فقط وقتی کار می‌کند که بافر لاگ داشته باشد — در حالت بیکار باتری مصرف نمی‌شود'],
  ['اطلاعات کاربر', 'شناسه‌ی کاربری که با AbrovaTrace.setUserId() تنظیم شده خودکار پیوست می‌شود'],
  ['Kotlin بومی', 'با Kotlin ساخته شده و از API 19 به بالا (Android 4.4 به بالا) پشتیبانی می‌کند'],
]} />

<H2 id="enable-logging" step={1}>فعال کردن لاگ‌گیری</H2>

بعد از راه‌اندازی AbrovaTrace در کلاس `Application`، سرویس لاگ‌گیری را فعال کنید:

```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}>ارسال لاگ</H2>

#### متدهای میان‌بر

```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"
))
```

#### متد عمومی log

```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}>سطح‌های لاگ</H2>

- **trace** — `AbrovaTrace.trace()` — دیباگ بسیار جزئی در سطح trace
- **debug** — `AbrovaTrace.logDebug()` — اطلاعات دیباگ در زمان توسعه
- **info** — `AbrovaTrace.info()` — اطلاعات عمومی اپ
- **warn** — `AbrovaTrace.warn()` — هشدار درباره‌ی مشکلات احتمالی
- **error** — `AbrovaTrace.logError()` — خطاهایی که باید بررسی شوند
- **fatal** — `AbrovaTrace.fatal()` — خطاهای بحرانی و غیرقابل‌بازیابی

<H2 id="usage-with-activities" step={4}>استفاده در Activityها</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}>عملیات دستی</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}>پیکربندی</H2>

<ConfigTable rows={[
  ['sourceId', 'String?', 'خیر', 'شناسه برای ارسال دسته‌ای (مثلاً "my-android-app")'],
  ['sourceName', 'String?', 'خیر', 'نام خوانا برای این منبع'],
  ['batchSize', 'Int', 'خیر', 'وقتی بافر به این اندازه برسد flush می‌شود (پیش‌فرض: ۵۰)'],
  ['flushIntervalMs', 'Long', 'خیر', 'حداکثر زمان تا flush به میلی‌ثانیه (پیش‌فرض: ۵۰۰۰)'],
]} />

اگر پیش از `enableLogging()` یکی از متدهای لاگ را صدا بزنید، لاگ‌گیری خودکار با پیش‌فرض‌های بالا (بدون `sourceId`) روشن می‌شود. بدون `sourceId` هر لاگ جداگانه به `/api/logs/ingest` فرستاده می‌شود و ارسال ناموفق دوباره امتحان نمی‌شود؛ با آن، لاگ‌های بافرشده در یک درخواست به `/api/logs/ingest/batch` می‌روند و دسته‌ی ناموفق دوباره فرستاده می‌شود. وقتی اپ به پس‌زمینه می‌رود هم لاگ‌ها flush می‌شوند. تا وقتی اپ در پس‌زمینه است تایمر flush کار نمی‌کند: لاگ‌ها وقتی فرستاده می‌شوند که به اندازه‌ی دسته برسند یا اپ به پیش‌زمینه برگردد.

### توصیه‌ها

<BestPracticeList items={[
  ['زود فعالش کنید', 'لاگ‌گیری را درست بعد از AbrovaTrace.init() فعال کنید تا همه‌ی رویدادها ثبت شوند'],
  ['از شناسه‌ی منبع استفاده کنید', 'یک sourceId معنادار بگذارید تا لاگ‌های این اپ در داشبورد مشخص باشد'],
  ['متادیتا اضافه کنید', 'متادیتای ساختاریافته (شناسه‌ی کاربر، نام صفحه و…) بفرستید تا دیباگ ساده‌تر شود'],
  ['سطح مناسب را انتخاب کنید', 'برای رویدادهای عادی info، برای مشکلات احتمالی warn و برای شکست‌ها error'],
  ['هنگام بستن flush کنید', 'پیش از بسته شدن اپ AbrovaTrace.flushLogs() را صدا بزنید تا همه‌ی لاگ‌ها فرستاده شوند'],
  ['زیاده‌روی نکنید', 'در حلقه‌های پرتکرار لاگ نگیرید — بافر حداکثر اندازه دارد و قدیمی‌ترین لاگ‌ها را حذف می‌کند'],
]} />

- لاگ در SDK آی‌اواس: https://abrova.ir/docs/trace/ios-logging

لاگ‌گیری ساخت‌یافته برای اپ‌های iOS با ارسال دسته‌ای خودکار، backoff نمایی و آگاهی از چرخه‌ی عمر اپ. لاگ‌ها بافر می‌شوند و دسته‌دسته فرستاده می‌شوند تا مصرف شبکه و باتری کم بماند.

<BestPracticeList columns={2} items={[
  ['ارسال دسته‌ای خودکار', 'لاگ‌ها بافر می‌شوند و دسته‌دسته فرستاده می‌شوند (پیش‌فرض: ۵۰)'],
  ['backoff نمایی', 'دسته‌های ناموفق با تأخیرهای رو به افزایش دوباره فرستاده می‌شوند (۲ ثانیه، ۴ ثانیه، ۸ ثانیه... تا ۶۰ ثانیه، حداکثر ۱۰ بار)'],
  ['حداکثر اندازه‌ی بافر', 'لاگ‌ها فقط در حافظه بافر می‌شوند (enableOfflineStorage برای خطاهاست، نه لاگ‌ها)؛ وقتی بافر از ۱۰۰۰ بیشتر شود، قدیمی‌ترین‌ها دور ریخته می‌شوند'],
  ['تایمر تنبل', 'تایمر فقط وقتی بافر لاگ دارد اجرا می‌شود — در حالت بیکار باتری مصرف نمی‌شود'],
  ['اطلاعات کاربر', 'شناسه‌ی کاربری که با AbrovaTrace.shared.setUserId() تنظیم شده، خودکار پیوست می‌شود'],
  ['Swift بومی', 'با Swift ساخته شده و از iOS 12+، macOS 10.14+ و tvOS 12+ پشتیبانی می‌کند'],
]} />

<H2 id="enable-logging" step={1}>فعال کردن لاگ‌گیری</H2>

پس از مقداردهی AbrovaTrace، سرویس لاگ‌گیری را فعال کنید. (اگر بدون فعال کردن، یکی از متدهای لاگ را صدا بزنید، لاگ‌گیری خودکار و بدون `sourceId` روشن می‌شود.) لاگ‌ها در کنسول زیر **ابرووا تریس › Logs** نمایش داده می‌شوند؛ این‌ها از `captureMessage` جدا هستند که به **پیام‌ها** می‌رود.

#### 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}>ارسال لاگ</H2>

#### متدهای میان‌بر

```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"
])
```

#### متد عمومی log

```swift
// Generic log with explicit level
AbrovaTrace.shared.log("Custom event", level: .info, metadata: ["key": "value"])
```

<H2 id="log-levels" step={3}>سطح‌های لاگ</H2>

- **trace** — `AbrovaTrace.shared.trace()` — دیباگ بسیار جزئی در سطح trace
- **debug** — `AbrovaTrace.shared.logDebugMessage()` — اطلاعات دیباگ در زمان توسعه
- **info** — `AbrovaTrace.shared.info()` — اطلاعات عمومی اپ
- **warn** — `AbrovaTrace.shared.warn()` — هشدار درباره‌ی مشکل‌های احتمالی
- **error** — `AbrovaTrace.shared.logErrorMessage()` — خطاهایی که باید بررسی شوند
- **fatal** — `AbrovaTrace.shared.fatal()` — خطاهای بحرانی یا غیرقابل بازیابی

<H2 id="usage-with-viewcontrollers" step={4}>استفاده در ViewControllerها</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

```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}>عملیات دستی</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}>پیکربندی</H2>

<ConfigTable rows={[
  ['sourceId', 'String?', 'خیر', 'شناسه برای ارسال دسته‌ای (مثلاً "my-ios-app"). بدون آن، هر لاگ بافرشده با یک درخواست جدا فرستاده می‌شود و ارسال‌های ناموفق دوباره تکرار نمی‌شوند'],
  ['sourceName', 'String?', 'خیر', 'نام خوانا برای این منبع'],
  ['batchSize', 'Int', 'خیر', 'وقتی بافر به این اندازه برسد، ارسال انجام می‌شود (پیش‌فرض: 50)'],
  ['flushInterval', 'TimeInterval', 'خیر', 'حداکثر زمان پیش از ارسال، به ثانیه (پیش‌فرض: 5.0)'],
]} />

### بهترین روش‌ها

<BestPracticeList items={[
  ['زود فعال کنید', 'لاگ‌گیری را درست بعد از مقداردهی AbrovaTrace فعال کنید تا همه‌ی رویدادها ثبت شوند'],
  ['از sourceId استفاده کنید', 'یک sourceId معنادار بگذارید تا لاگ‌های این اپ در داشبورد قابل تشخیص باشند'],
  ['metadata اضافه کنید', 'metadata ساخت‌یافته (شناسه‌ی کاربر، نام صفحه و…) اضافه کنید تا دیباگ ساده‌تر شود'],
  ['سطح مناسب را انتخاب کنید', 'برای رویدادهای عادی info، برای مشکل‌های احتمالی warn و برای شکست‌ها error'],
  ['هنگام خاموش شدن ارسال کنید', 'لاگ‌ها وقتی اپ به پس‌زمینه می‌رود و هنگام terminate خودکار فرستاده می‌شوند؛ برای مسیرهای دیگرِ بسته شدن، AbrovaTrace.shared.flushLogs() را صدا بزنید'],
  ['زیاده‌روی نکنید', 'در حلقه‌های فشرده لاگ نگیرید — بافر سقف دارد و قدیمی‌ترین لاگ‌ها را دور می‌ریزد'],
]} />

- لاگ در SDK لاراول: https://abrova.ir/docs/trace/laravel-logging

لاگ‌گیری ساخت‌یافته برای Laravel از طریق کانال Monolog، با ارسال دسته‌ای و تلاش دوباره. لاگ‌ها زیر **ابرووا تریس › Logs** نمایش داده می‌شوند؛ این‌ها از `AbrovaTrace::captureMessage()` جدا هستند که به پیام‌ها می‌رود.

<BestPracticeList columns={2} items={[
  ['کانال Monolog', 'از facade بومی Log در Laravel با یک درایور کانال سفارشی abrovatrace استفاده کنید.'],
  ['ارسال دسته‌ای', 'لاگ‌ها بافر می‌شوند و وقتی بافر به batch_size برسد، و هنگام پایان اجرا، فرستاده می‌شوند.'],
  ['تلاش دوباره با backoff', 'کلاینت HTTP خطاهای اتصال و پاسخ‌های 5xx را تا ۳ بار، با انتظار ۱، ۲ و سپس ۳ ثانیه، دوباره امتحان می‌کند.'],
  ['نگاشت سطح‌ها', 'سطح‌های Monolog خودکار به سطح‌های AbrovaTrace (debug، info، warn، error، fatal) نگاشت می‌شوند.'],
]} />

<H2 id="installation" step={1}>نصب</H2>

مخزن ابرووا را به `composer.json` اضافه کنید و بعد نصب کنید ([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
```

کانال لاگ را به `config/logging.php` اضافه کنید:

```php
'channels' => [
    // ... other channels

    'abrovatrace' => [
        'driver' => 'custom',
        'via' => AbrovaTrace\Laravel\Logging\AbrovaTraceLogChannel::class,
    ],
],
```

<H2 id="basic-usage" step={2}>استفاده‌ی پایه</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}>سطح‌های لاگ</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="نگاشت سطح‌ها">
  سطح‌های Monolog این‌طور به سطح‌های AbrovaTrace نگاشت می‌شوند: DEBUG=debug، INFO/NOTICE=info، WARNING=warn، ERROR=error، CRITICAL/ALERT/EMERGENCY=fatal.
</Callout>

<H2 id="direct-sdk-logging" step={4}>لاگ‌گیری مستقیم با SDK</H2>

می‌توانید مستقیم از طریق 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</H2>

با اضافه کردن abrovatrace به یک کانال stack، لاگ‌ها را به چند مقصد بفرستید:

```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]);
```

لاراول exceptionهای گزارش‌شده را در کانال لاگ پیش‌فرض شما می‌نویسد و از نسخه‌ی 0.2.3 به بعد، SDK دیگر جلوی این کار را نمی‌گیرد. اگر `abrovatrace` در stack پیش‌فرض باشد، هر exception علاوه بر گزارش به‌عنوان خطا، به‌شکل یک ورودی لاگ هم در لاگ‌ها می‌رسد.

<H2 id="metadata-context" step={6}>metadata و اطلاعات زمینه</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}>پیکربندی</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', 'خیر', 'شناسه‌ی منبع لاگ (مثلاً "api-server"). با آن، هر ارسال یک درخواست دسته‌ای است؛ بدون آن، برای هر لاگ یک درخواست'],
  ['logging.source_name', 'string', 'خیر', 'نام نمایشی خوانا برای منبع'],
  ['logging.batch_size', 'integer', 'خیر', 'وقتی بافر به این اندازه برسد، ارسال انجام می‌شود (پیش‌فرض: 50)'],
  ['api_key', 'string', 'بله', 'کلید API پروژه (ab_live_xxx)'],
  ['server_secret', 'string', 'خیر', 'کلید سرور شما (ab_srv_xxx). وقتی تنظیم پروژه‌ی «مسیرهای سرور به کلید سرور نیاز دارند» روشن باشد لازم است'],
  ['debug', 'boolean', 'خیر', 'فعال کردن خروجی دیباگ (پیش‌فرض: false)'],
]} />

### بهترین روش‌ها

<BestPracticeList items={[
  ['از کانال Monolog استفاده کنید', "برای یکپارچگی با لاگ‌گیری بومی Laravel از Log::channel('abrovatrace') استفاده کنید"],
  ['stack برای چند مقصد', 'برای لاگ هم‌زمان در فایل محلی و فضای ابری، abrovatrace را به یک کانال stack اضافه کنید'],
  ['metadata ساخت‌یافته', 'metadata ساخت‌یافته (شناسه‌ها، مدت‌زمان‌ها، شمارش‌ها) اضافه کنید تا فیلتر کردن در داشبورد بهتر شود'],
  ['لاگ‌ها را به کاربر وصل کنید', 'لاگ‌ها شناسه‌ی کاربری را که با AbrovaTrace::setUser() تنظیم شده همراه دارند (برای درخواست‌های احرازشده خودکار تنظیم می‌شود)'],
  ['سطح مناسب را انتخاب کنید', 'برای کارهای عادی info، برای وضعیت افت‌کرده warn و برای شکست‌ها error'],
  ['اطلاعات حساس را لاگ نکنید', 'هرگز رمز عبور، توکن یا اطلاعات شخصی را در metadata لاگ نکنید'],
]} />

- لاگ در SDK نود: https://abrova.ir/docs/trace/nodejs-logging

لاگ‌گیری سمت سرور با تلاش مجدد با فاصله‌ی افزایشی (exponential backoff)، بدون هیچ وابستگی و با یکپارچگی Express.js. لاگ‌ها در **ابرووا تریس › Logs** نمایش داده می‌شوند و از `AbrovaTrace.captureMessage()` جدا هستند؛ آن متد به بخش Messages می‌رود.

<BestPracticeList columns={2} items={[
  ['تلاش مجدد با فاصله‌ی افزایشی', 'دسته‌ای که ارسالش ناموفق باشد بعد از ۲ ثانیه ← ۴ ثانیه ← ۸ ثانیه ← ... تا حداکثر ۶۰ ثانیه دوباره ارسال می‌شود. بعد از ۱۰ تلاش ناموفق، لاگ‌ها تا لاگ بعدی یا flush بعدی در بافر می‌مانند.'],
  ['حداکثر اندازه‌ی بافر', 'پیش‌فرض ۱۰۰۰ لاگ. وقتی از این حد بگذرد، قدیمی‌ترین لاگ‌ها حذف می‌شوند تا حافظه پر نشود.'],
  ['تایمر تنبل', 'تابع setTimeout فقط وقتی اجرا می‌شود که بافر لاگ داشته باشد. در حالت بیکار هیچ بار پردازشی ندارد.'],
  ['بدون وابستگی', 'از ماژول‌های داخلی http/https خود Node.js استفاده می‌کند. هیچ پکیج خارجی لازم نیست.'],
]} />

<H2 id="installation" step={1}>نصب</H2>

رجیستری ابرووا را به `.npmrc` اضافه کنید و سپس نصب کنید (نگاه کنید به [SDK Node.js](/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}>استفاده‌ی پایه</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);
});
```

اگر از قبل `AbrovaTrace.init()` را صدا می‌زنید، به‌جای ساختن یک `LogService` می‌توانید از همان برای لاگ‌گیری استفاده کنید. این روش کلید API، environment و release را از `init()` برمی‌دارد و کاربری را که با `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
```

پیش از بسته شدن پروسه، `await AbrovaTrace.flush()` را صدا بزنید. این متد لاگ‌های بافرشده را همراه با خطاها، پیام‌ها و spanهای عملکرد در انتظار می‌فرستد و اگر زمان انتظارش (پیش‌فرض: ۵۰۰۰ میلی‌ثانیه) زودتر تمام شود، مقدار `false` برمی‌گرداند. متد `AbrovaTrace.close()` هم لاگ‌های بافرشده را می‌فرستد و سپس SDK را ریست می‌کند.

<H2 id="log-levels" step={3}>سطح‌های لاگ</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</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}>متادیتا و اطلاعات کاربر</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}>عملیات دستی</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}>پیکربندی</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', 'بله', 'کلید API پروژه‌ی شما'],
  ['serverSecret', 'string', 'خیر', 'کلید سرور شما (ab_srv_xxx) که با هر درخواست لاگ فرستاده می‌شود؛ آن را فقط روی سرور نگه دارید'],
  ['apiUrl', 'string', 'خیر', 'آدرس پایه‌ی API تریس؛ فقط برای API تریس خودمیزبان تنظیمش کنید (پیش‌فرض: "https://trace.abrova.ir")'],
  ['sourceId', 'string', 'خیر', 'شناسه‌ی منبع (مثلاً "api-server"). بدون آن، هر لاگ با یک درخواست جدا فرستاده می‌شود و ارسال‌های ناموفق دوباره امتحان نمی‌شوند'],
  ['sourceName', 'string', 'خیر', 'نام نمایشی خوانا برای این منبع'],
  ['platform', 'string', 'خیر', 'شناسه‌ی پلتفرم (پیش‌فرض: "nodejs")'],
  ['environment', 'string', 'خیر', 'نام محیط (پیش‌فرض: "production")'],
  ['release', 'string', 'خیر', 'شناسه‌ی نسخه‌ی اپ'],
  ['batchSize', 'number', 'خیر', 'وقتی بافر به این اندازه برسد flush می‌شود (پیش‌فرض: ۵۰)'],
  ['flushIntervalMs', 'number', 'خیر', 'حداکثر زمان تا flush به میلی‌ثانیه (پیش‌فرض: ۳۰۰۰۰)'],
  ['maxBufferSize', 'number', 'خیر', 'با گذشتن از این حد، قدیمی‌ترین لاگ‌ها حذف می‌شوند (پیش‌فرض: ۱۰۰۰)'],
  ['debug', 'boolean', 'خیر', 'نمایش خروجی دیباگ در کنسول (پیش‌فرض: false)'],
]} />

### توصیه‌ها

<BestPracticeList items={[
  ['از شناسه‌ی منبع استفاده کنید', 'برای sourceId مقدارهای معنادار بگذارید تا منبع لاگ‌ها در داشبورد مشخص باشد'],
  ['خاموش شدن تمیز', 'همیشه روی SIGTERM/SIGINT متد dispose() را صدا بزنید تا لاگ‌های باقی‌مانده فرستاده شوند (اگر از طریق AbrovaTrace لاگ می‌گیرید، AbrovaTrace.flush() را)'],
  ['middleware لاگ درخواست‌ها', 'middleware لاگ درخواست‌ها را در ابتدای pipeline اکسپرس اضافه کنید'],
  ['middleware خطا در آخر', 'middleware لاگ خطا را بعد از همه‌ی routeها اضافه کنید تا همه‌چیز را پوشش دهد'],
  ['متادیتای ساختاریافته', 'متادیتای ساختاریافته (شناسه‌ها، مدت‌زمان‌ها، مسیرها) بفرستید تا فیلتر کردن ساده‌تر شود'],
  ['کاربر را مشخص کنید', 'شناسه‌ی کاربر را به لاگ‌ها بدهید تا دیباگ مشکلات مخصوص یک کاربر ساده‌تر شود'],
]} />

- لاگ در SDK نکست: https://abrova.ir/docs/trace/nextjs-logging

لاگ‌گیری فول‌استک با TypeScript برای اپ‌های Next.js، با پشتیبانی از App Router و Pages Router.

<H2 id="installation" step={1}>نصب</H2>

رجیستری ابرووا را به `.npmrc` اضافه کنید و سپس نصب کنید (نگاه کنید به [SDK Next.js](/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}>راه‌اندازی logger</H2>

فایل `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)</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 Routeها)

```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}>سطح‌های لاگ</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</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}>لاگ‌گیری سمت کلاینت</H2>

<Callout kind="note" title="دو راه">در مرورگر می‌توانید مستقیماً با همان نمونه‌ی SDK که راه‌اندازی کرده‌اید لاگ بگیرید، مثلاً `AbrovaTrace.getInstance()?.info('Button clicked', { buttonId: 'submit-form' })`. اگر ترجیح می‌دهید لاگ‌های کلاینت اول روی سرور خودتان بررسی یا فیلتر شوند، آن‌ها را مثل نمونه‌ی زیر از یک API route بفرستید. لاگ‌ها بافر می‌شوند (به‌طور پیش‌فرض بعد از ۵۰ لاگ یا ۳۰ ثانیه فرستاده می‌شوند) و با بسته شدن صفحه خودکار ارسال نمی‌شوند؛ پس هر وقت لاگی باید همان لحظه برود، `AbrovaTrace.getInstance()?.flushLogs()` را صدا بزنید.</Callout>

یک route واسط (proxy) بسازید:

```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 });
}
```

کامپوننت کلاینت:

```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}>پیکربندی</H2>

<ConfigTable rows={[
  ['apiKey', 'string', 'بله', 'کلید API پروژه‌ی شما'],
  ['sourceId', 'string', 'خیر', 'شناسه‌ی منبع لاگ. با آن، لاگ‌ها دسته‌ای فرستاده می‌شوند (/api/logs/ingest/batch)؛ بدون آن، هر لاگ بافرشده با یک درخواست جدا فرستاده می‌شود'],
  ['sourceName', 'string', 'خیر', 'نام نمایشی این منبع'],
  ['platform', 'string', 'بله', 'شناسه‌ی پلتفرم، مثلاً "nextjs" (مقدار پیش‌فرض ندارد)'],
  ['environment', 'string', 'بله', 'نام محیط، مثلاً "production" (مقدار پیش‌فرض ندارد)'],
  ['release', 'string', 'خیر', 'نسخه‌ی اپ که به هر لاگ پیوست می‌شود'],
  ['batchSize', 'number', 'خیر', 'وقتی بافر به این اندازه برسد flush می‌شود (پیش‌فرض: ۵۰)'],
  ['flushIntervalMs', 'number', 'خیر', 'حداکثر زمان تا flush به میلی‌ثانیه (پیش‌فرض: ۳۰۰۰۰)'],
  ['maxBufferSize', 'number', 'خیر', 'با گذشتن از این حد، قدیمی‌ترین لاگ‌ها حذف می‌شوند (پیش‌فرض: ۱۰۰۰)'],
  ['debug', 'boolean', 'خیر', 'چاپ خروجی دیباگ SDK در کنسول (پیش‌فرض: false)'],
  ['apiUrl', 'string', 'خیر', 'آدرس پایه‌ی API تریس (پیش‌فرض: "https://trace.abrova.ir"). فقط برای نسخه‌ی خودمیزبان تنظیمش کنید'],
]} />

### توصیه‌ها

<BestPracticeList items={[
  ['یک logger مرکزی', 'یک نمونه‌ی logger در lib/logger.ts بسازید و همه‌جا همان را import کنید'],
  ['فیلتر لاگ‌های کلاینت', 'وقتی می‌خواهید لاگ‌های کلاینت پیش از رسیدن به ابرووا تریس بررسی یا فیلتر شوند، از route واسط استفاده کنید'],
  ['لاگ در API Routeها', 'به همه‌ی API Routeها لاگ اضافه کنید تا همه‌ی درخواست‌ها دیده شوند'],
  ['اطلاعات درخواست را اضافه کنید', 'متد، مسیر و مدت‌زمان را در لاگ درخواست‌ها بیاورید'],
  ['لاگ‌های کلاینت را اعتبارسنجی کنید', 'سطح و متن لاگی را که از route واسط سمت کلاینت می‌رسد پاک‌سازی و اعتبارسنجی کنید'],
  ['از middleware استفاده کنید', 'یک middleware اضافه کنید تا درخواست‌ها و پاسخ‌های API Routeها خودکار لاگ شوند'],
]} />

- REST API لاگ: https://abrova.ir/docs/trace/logs-rest-api

لاگ‌ها را از هر اپلیکیشن، زبان یا فریم‌ورکی با HTTPS بفرستید. هر درخواست در هدر `x-api-key` به یک کلید پروژه نیاز دارد: وقتی از سرور می‌فرستید کلید سرور (`ab_srv_...`)، و وقتی از اپ می‌فرستید کلید اپ (`ab_live_...`).

<Callout kind="secret" title="کدام کلید؟">
کلید اپ داخل اپ‌های موبایل و وب منتشر می‌شود، پس آن را عمومی در نظر بگیرید. روی سرورهای خودتان از **کلید سرور** در یک متغیر محیطی استفاده کنید و آن را از کد سمت کلاینت دور نگه دارید. هر دو کلید، صرف‌نظر از تنظیمات پروژه، روی دو endpoint زیر پذیرفته می‌شوند. [کلید سرور و مسیرهای سرور](/docs/trace/server-secret) را ببینید.
</Callout>

<Callout kind="wallet">
لاگ‌ها تا ۱ گیگابایت در ماه رایگان هستند؛ بیش از آن، هزینه از کیف پول: هر گیگابایت ۱۵٬۰۰۰ تومان. لاگ‌ها ۳۰ روز نگه داشته می‌شوند. [قیمت‌ها](/pricing) را ببینید.
</Callout>

<H2 id="post-api-logs-ingest-single-log" step={1}>ارسال یک لاگ</H2>

<Endpoint method="POST" url="https://trace.abrova.ir/api/logs/ingest" />

<ConfigTable rows={[
  ['message', 'string', 'بله', 'متن خط لاگ (تا ۱۰٬۰۰۰ نویسه نگه داشته می‌شود)'],
  ['level', 'string', 'خیر', 'fatal، error، warn، info، debug یا trace (پیش‌فرض: info)'],
  ['sourceId', 'string', 'خیر', 'شناسه‌ی منبع لاگ (مثلاً "api-server"). پیش‌فرض: "<platform>-default" یا "unknown-default"'],
  ['sourceName', 'string', 'خیر', 'نام خوانای منبع'],
  ['timestamp', 'string', 'خیر', 'زمان با قالب ISO 8601 (پیش‌فرض: زمان دریافت)'],
  ['metadata', 'object', 'خیر', 'جفت‌های کلید-مقدار اضافه'],
  ['platform', 'string', 'خیر', 'برچسب پلتفرم که در نمای Logs نشان داده می‌شود'],
  ['environment', 'string', 'خیر', 'Environment (پیش‌فرض: production)'],
  ['release', 'string', 'خیر', 'نسخه‌ی release'],
  ['userId', 'string', 'خیر', 'کاربری که لاگ به او مربوط است'],
]} />

```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"
    }
  }'
```

پاسخ (`201`): <code>{`{"status": "created", "id": 12345}`}</code>

<H2 id="post-api-logs-ingest-batch-batch-logs" step={2}>ارسال دسته‌ای</H2>

<Endpoint method="POST" url="https://trace.abrova.ir/api/logs/ingest/batch" />

برای حجم بالای لاگ کارآمدتر است: چندین مورد را در یک درخواست، به‌صورت آرایه‌ی JSON زیر `logs` بفرستید. اینجا `sourceId` **الزامی** است؛ هر مورد در `logs` همان فیلدهای یک لاگ تکی را می‌پذیرد (به‌جز `sourceId` / `sourceName`). از هر درخواست حداکثر ۱٬۰۰۰ مورد ذخیره می‌شود؛ بیشتر از آن را در چند دسته بفرستید.

```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)" }
    ]
  }'
```

پاسخ (`201`): <code>{`{"status": "created", "count": 3, "projectId": "..."}`}</code>

<H2 id="code-examples" step={3}>نمونه کدها</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',
});`} />

در اپ‌های Node.js، [SDK برای Node.js](/docs/trace/nodejs-logging) ارسال دسته‌ای و تلاش دوباره را برایتان انجام می‌دهد.

#### 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

در اپ‌های Laravel از [کانال لاگ در SDK برای Laravel](/docs/trace/laravel-logging) استفاده کنید. برای 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}>کدهای پاسخ</H2>

- **201** — ساخته شد
- **400** — بدنه‌ی درخواست نامعتبر است (`message` نیامده؛ در ارسال دسته‌ای، `logs` خالی است یا `sourceId` نیامده)
- **401** — کلید نیامده یا نامعتبر است، یا ابرووا تریس برای پروژه فعال نیست
- **429** — درخواست‌ها بیش از حد است. برای هر کلید و هر آدرس کلاینت سقف بالایی وجود دارد؛ کلاینتی که از آن بگذرد پاسخ `429` با هدر `Retry-After` (به ثانیه) می‌گیرد. به‌جای لاگ تکی دسته‌ای بفرستید و پیش از تلاش دوباره صبر کنید.
- **500** — خطای سرور؛ بعداً دوباره تلاش کنید.

- فیلتر و جست‌وجوی لاگ: https://abrova.ir/docs/trace/log-search

در صفحه‌ی **ابرووا تریس › Logs** در کنسول ابرووا، لاگ‌ها را با فیلترهای قدرتمند سریع پیدا کنید. سطح لاگ، منبع، environment، بازه‌ی زمانی و جستجوی متنی را با هم ترکیب کنید تا دقیقاً به آنچه لازم دارید برسید.

### فیلتر بر اساس سطح لاگ

برای نمایش یا پنهان کردن هر سطح، روی دکمه‌های سطح بالای فهرست لاگ کلیک کنید؛ دست‌کم یک سطح همیشه روشن می‌ماند. هر دکمه نشان می‌دهد چند خط از آن سطح در بازه‌ی فعلی هست.

- **fatal** — کرش‌ها و خطاهای غیرقابل بازیابی
- **error** — خطاهایی که باید فوراً بررسی شوند
- **warning** — هشدار درباره‌ی مشکلات احتمالی (با نام `warn` ذخیره می‌شود)
- **info** — اطلاعات عمومی درباره‌ی رفتار اپلیکیشن
- **debug** — اطلاعات دقیق برای دیباگ
- **trace** — لاگ‌های بسیار جزئی برای دیباگ عمیق

### فیلتر بر اساس منبع

در پنل **منبع‌ها** یک منبع را انتخاب کنید تا فقط خط‌های آن را ببینید؛ با ⌘/Ctrl-کلیک منبع‌های بیشتری به انتخاب اضافه می‌شود (در گوشی از دکمه‌ی **همهٔ منبع‌ها** استفاده کنید). منبع‌ها با رسیدن لاگ به‌طور خودکار ساخته می‌شوند.

نمونه‌ی منبع‌ها: `nginx`، `api-server`، `worker`، `database`، `cache`.

### جستجوی متنی

جستجو به بزرگی و کوچکی حروف حساس نیست و با هر بخشی از پیام لاگ، metadata یا منبع آن تطبیق پیدا می‌کند. اگر بخواهید پیام را با یک عبارت باقاعده (regex) تطبیق دهید، گزینه‌ی regex را در کادر جستجو روشن کنید (به بزرگی و کوچکی حروف حساس نیست و در مرورگر شما روی خط‌هایی که قبلاً بارگذاری شده‌اند اعمال می‌شود).

- `timeout` — همه‌ی لاگ‌هایی که «timeout» در آن‌ها آمده
- `user_123` — لاگ‌های یک کاربر مشخص
- `500` — خطاهای HTTP 500
- `connection refused` — خطاهای اتصال

### بازه‌ی زمانی

برای محدود کردن جستجو یکی از بازه‌های آماده را انتخاب کنید:

- **۱ ساعت اخیر** (پیش‌فرض)
- **۲۴ ساعت اخیر**
- **۷ روز اخیر**
- **۳۰ روز اخیر**

لاگ‌ها ۷ روز نگه داشته می‌شوند، مگر اینکه نگهداری ۳۰ روزه را اضافه کنید (برای هر پروژه ماهانه ۵۰٬۰۰۰ تومان اضافه، هزینه از کیف پول)؛ بنابراین بازه‌های طولانی‌تر فقط لاگ‌هایی را نشان می‌دهند که هنوز نگه داشته شده‌اند.

برای محدود کردن به یک environment از منوی **Environment** استفاده کنید.

### قابلیت‌های داشبورد

- **تعداد هر سطح** — هر دکمه‌ی سطح، تعداد خط‌های آن سطح را در یک نگاه نشان می‌دهد
- **پخش زنده** — خط‌های جدید همان لحظه‌ی رسیدن نمایش داده می‌شوند (۱٬۰۰۰ خط آخر روی صفحه می‌ماند)؛ برای اسکرول و بارگذاری خط‌های قدیمی‌تر، پخش را متوقف کنید
- **نمای یکپارچه و ستونی** — یک جریان ادغام‌شده را بخوانید، یا تا ۴ منبع را کنار هم مقایسه کنید
- **جزئیات لاگ** — روی هر لاگ کلیک کنید تا پیام کامل و metadata آن را ببینید

ذخیره‌ی یک جستجو به نقش member یا بالاتر نیاز دارد؛ حذف لاگ‌ها یا منبع‌ها به نقش admin یا owner نیاز دارد. [نقش‌ها و دسترسی‌ها](/docs/trace/error-dashboard#roles) را ببینید.

- قوانین نادیده‌گرفتن: https://abrova.ir/docs/trace/ignore-rules

<BestPracticeList columns={2} items={[
  ['قوانین نادیده‌گیری چیست؟', 'قوانین نادیده‌گیری خطاهایی را که هرگز نمی‌خواهید ببینید (مثل «ResizeObserver loop limit exceeded» یا نویز افزونه‌های مرورگر) پیش از رسیدن به صندوق مشکل‌ها حذف می‌کنند.'],
]} />

<Callout kind="wallet" title="بدون هزینه">قوانین نادیده‌گیری برای همه‌ی پروژه‌ها رایگان است. خطاهای حذف‌شده هیچ‌وقت مشکل جدید نمی‌شوند، پس از سهمیه‌ی رایگان یا کیف پول شما کم نمی‌کنند.</Callout>

### قوانین نادیده‌گیری

هر قانون الگویی است که روی **پیام خطای** هر خطای جدیدی که SDKها می‌فرستند آزموده می‌شود. قوانین متعلق به پروژه‌ی ابرووا هستند، پس هر قانون روی همه‌ی پلتفرم‌های آن (iOS، Android، Flutter، وب، سرور) اعمال می‌شود.

#### ساختن قانون نادیده‌گیری

1. در کنسول ابرووا، **ابرووا تریس ← قوانین نادیده‌گرفتن** را باز کنید
2. روی **«قانون جدید»** کلیک کنید
3. یک نوع **تطبیق** انتخاب کنید (شامل، دقیق یا Regex) و **الگوی پیام** را بنویسید
4. پیش‌نمایش را بررسی کنید: نشان می‌دهد این الگو با چند مشکل از ۳۰ روز گذشته جور می‌شد (در مرورگر شما روی آخرین مشکل‌هایتان آزموده می‌شود)
5. روی **«ذخیرهٔ قانون»** کلیک کنید

مدیریت قوانین (افزودن، ویرایش، روشن و خاموش کردن، حذف) نقش **admin** یا **owner** می‌خواهد؛ همه‌ی نقش‌ها می‌توانند آن‌ها را ببینند. [نقش‌ها و دسترسی‌ها](/docs/trace/error-dashboard#roles) را ببینید.

#### انواع تطبیق

تطبیق به بزرگی و کوچکی حروف حساس نیست.

<div>
  <table>
    <thead>
      <tr>
        {['نوع', 'توضیح', 'مثال'].map((h) => (
          <th key={h}>{h}</th>
        ))}
      </tr>
    </thead>
    <tbody>
      {[
        ['شامل (Contains)', 'الگو هر جایی از پیام بیاید', 'ResizeObserver loop matches "ResizeObserver loop limit exceeded"'],
        ['دقیق (Exact)', 'کل پیام باید با الگو برابر باشد', 'Network Error matches only "Network Error"'],
        ['Regex', 'عبارت باقاعده‌ی جاوااسکریپت که روی پیام آزموده می‌شود', '^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>

قوانین فقط با پیام خطا تطبیق داده می‌شوند. تطبیق بر اساس URL، پلتفرم یا محیط در کنسول پشتیبانی نمی‌شود.

#### مدیریت قوانین نادیده‌گیری

- **روشن و خاموش کردن:** هر قانون یک سوییچ دارد، پس می‌توانید بدون حذف غیرفعالش کنید.
- **ویرایش:** نوع تطبیق یا الگوی قانون را تغییر دهید.
- **حذف:** قانون را حذف کنید؛ خطاهایی که با آن جور بودند دوباره به صندوق شما می‌رسند.

<Callout kind="note" title="نکته">خطاهای نادیده‌گرفته همان لحظه‌ی دریافت حذف می‌شوند: ذخیره نمی‌شوند، مشکلی نمی‌سازند یا به‌روز نمی‌کنند و هشداری هم ایجاد نمی‌کنند. قوانین فقط روی خطاهای جدید اثر دارند و مشکل‌های موجود حذف نمی‌شوند. پیام‌هایی که با captureMessage فرستاده می‌شوند تحت تأثیر قرار نمی‌گیرند.</Callout>

- حل‌کردن همه: https://abrova.ir/docs/trace/mark-all-resolved

<BestPracticeList columns={2} items={[
  ['«حل کردن همه» چیست؟', 'یک اقدام سریع برای این‌که همه‌ی خطاهای فعال را با یک کلیک حل‌شده علامت بزنید. مناسب برای بعد از deploy یا وقتی چند مشکل را با هم رفع کرده‌اید.'],
]} />

<Callout kind="wallet" title="بدون هزینه">«حل کردن همه» برای همه‌ی پروژه‌ها رایگان است.</Callout>

### حل کردن همه

یک اقدام سریع برای این‌که همه‌ی خطاهای فعال را با یک کلیک حل‌شده علامت بزنید؛ مناسب برای بعد از deploy یا وقتی چند مشکل را با هم رفع کرده‌اید.

#### نحوه‌ی استفاده

1. در کنسول ابرووا، **ابرووا تریس ← مشکلات** را باز کنید
2. منوی **عملیات بیشتر** (**⋯**) کنار عنوان صفحه را باز کنید و **«حل همه مشکلات باز…»** را انتخاب کنید
3. پنجره‌ی تأیید باز می‌شود؛ روی **«حل همه»** کلیک کنید
4. همه‌ی مشکل‌های باز و در حال بررسی پروژه (در همه‌ی پلتفرم‌ها) حل‌شده علامت می‌خورند. فیلترهای فعلی فهرست اعمال نمی‌شوند.

این اقدام دست‌کم نقش member می‌خواهد؛ viewerها آن را نمی‌بینند. [نقش‌ها و دسترسی‌ها](/docs/trace/error-dashboard#roles) را ببینید.

#### آشنایی با وضعیت خطاها

<div>
  {[
    { state: 'باز / در حال بررسی', color: 'bg-red-900/20 border-red-200', desc: 'مشکل‌هایی که باید بررسی شوند. مشکل‌های جدید با وضعیت باز شروع می‌شوند و در نمای پیش‌فرض مشکل‌ها دیده می‌شوند.' },
    { state: 'حل‌شده', color: 'bg-emerald-900/20 border-emerald-800', desc: 'مشکل‌هایی که رفع شده‌اند. رویدادهای جدید همچنان شمارششان را بالا می‌برند، اما مشکل حل‌شده باقی می‌ماند.' },
    { state: 'نادیده‌گرفته / بایگانی‌شده', color: 'bg-orange-900/20 border-orange-800', desc: 'مشکل‌هایی که کنار گذاشته‌اید. هر مشکلی را می‌توانید از منوی وضعیتش دوباره باز کنید.' },
  ].map((s) => (
    <div key={s.state}>
      <strong>{s.state}</strong>
      <p>{s.desc}</p>
    </div>
  ))}
</div>

#### چه زمانی استفاده کنیم

<BestPracticeList items={[
  ['بعد از deploy', 'وقتی رفع چند خطا را deploy کرده‌اید، همه را حل‌شده علامت بزنید تا از نو شروع کنید.'],
  ['پاک‌سازی پایان sprint', 'در پایان sprint، همه‌ی خطاهایی را که در طول توسعه رفع شده‌اند حل‌شده کنید.'],
  ['شروع تازه', 'وارد مرحله‌ی جدیدی می‌شوید؟ خطاهای قدیمی را حل‌شده کنید تا روی موارد جدید تمرکز کنید.'],
  ['پایان مهاجرت', 'بعد از تمام شدن یک مهاجرت یا refactor بزرگ، صفحه را پاک کنید.'],
]} />

#### وقتی همه را حل‌شده می‌کنید چه اتفاقی می‌افتد؟

<ul>
  <li><span>{'✓'}</span> همه‌ی مشکل‌های باز و در حال بررسی به وضعیت «حل‌شده» می‌روند</li>
  <li><span>{'✓'}</span> اعلان‌های یکپارچگی‌ها (Slack، ایمیل و غیره) فقط برای مشکل‌های کاملاً جدید فرستاده می‌شوند، پس مشکل‌های حل‌شده دوباره اعلان نمی‌دهند</li>
  <li><span>{'✓'}</span> تاریخچه‌ی خطا و تعداد رخدادها حفظ می‌شود</li>
  <li><span>{'✓'}</span> مشکل‌های حل‌شده را با فیلتر وضعیت در صفحه‌ی مشکل‌ها می‌توانید ببینید</li>
  <li><span>!</span> اگر خطا دوباره رخ دهد، شمارش و زمان آخرین دیده شدنش به‌روز می‌شود اما خودکار دوباره باز نمی‌شود؛ در صورت نیاز خودتان بازش کنید</li>
</ul>

#### حل کردن تکی در برابر گروهی

<div>
  <table>
    <thead>
      <tr>
        {['اقدام', 'کِی استفاده کنیم', 'چطور'].map((h) => (
          <th key={h}>{h}</th>
        ))}
      </tr>
    </thead>
    <tbody>
      <tr>
        <td>حل کردن یک خطا</td>
        <td>یک مشکل مشخص را رفع کرده‌اید</td>
        <td>مشکل را باز کنید ← «حل شد» (میان‌بر R)</td>
      </tr>
      <tr>
        <td>حل کردن همه</td>
        <td>چند رفع با هم deploy شده‌اند</td>
        <td>مشکل‌ها ← ⋯ ← «حل همه مشکلات باز…»</td>
      </tr>
    </tbody>
  </table>
</div>

#### بهترین روش‌ها

<BestPracticeList items={[
  ['پیش از حل کردن مرور کنید', 'فهرست را سریع مرور کنید تا مطمئن شوید مشکل حیاتی رسیدگی‌نشده‌ای نمانده است'],
  ['آخرین زمان دیده شدن را ببینید', 'مشکل‌های حل‌شده خودکار دوباره باز نمی‌شوند؛ در فیلتر حل‌شده دنبال مشکل‌هایی بگردید که آخرین زمان دیده شدنشان بعد از حل کردن آن‌هاست'],
  ['همراه با قوانین نادیده‌گیری', 'آن را با قوانین نادیده‌گیری ترکیب کنید تا نویز شناخته‌شده پیش از تبدیل شدن به مشکل حذف شود'],
]} />

- گزارش هفتگی ایمیلی: https://abrova.ir/docs/trace/weekly-digest

<BestPracticeList columns={2} items={[
  ['گزارش هفتگی چیست؟', 'هر دوشنبه ساعت ۹ صبح به وقت نیویورک (۱۶:۳۰ به وقت تهران، و ۱۷:۳۰ وقتی نیویورک در ساعت زمستانی است) خلاصه‌ای ایمیلی از خطاهای هفته‌ی گذشته می‌گیرید. بدون این‌که مدام داشبورد را چک کنید، از سلامت اپلیکیشن خود باخبر بمانید.'],
]} />

<Callout kind="wallet" title="بدون هزینه‌ی اضافه">گزارش هفتگی ایمیلی بدون هزینه‌ی اضافه جزو ابرووا تریس است. [قیمت‌ها](/pricing) را ببینید.</Callout>

### گزارش هفتگی ایمیلی

هر دوشنبه ساعت ۹ صبح به وقت نیویورک، خلاصه‌ای ایمیلی از خطاهای هفته‌ی گذشته می‌گیرید: مشکل‌های جدید، حل‌شده و باز، تعداد رخدادها، روند نسبت به هفته‌ی قبل و پرتکرارترین خطاها. بدون این‌که مدام داشبورد را چک کنید، از سلامت اپلیکیشن خود باخبر بمانید.

#### در گزارش چه هست؟

<BestPracticeList items={[
  ['خطاهای جدید', 'مشکل‌هایی که اولین بار در ۷ روز گذشته دیده شده‌اند'],
  ['حل‌شده', 'مشکل‌هایی که در ۷ روز گذشته حل‌شده علامت خورده‌اند'],
  ['باز', 'مشکل‌هایی که الان باز هستند'],
  ['رخدادها', 'مجموع رویدادهای مشکل‌هایی که در ۷ روز گذشته دیده شده‌اند'],
  ['مقایسه‌ی روند', 'خطاهای جدید در مقایسه با هفته‌ی قبل'],
  ['پرتکرارترین خطاها', '۵ مشکل پرتکرار این هفته، مرتب‌شده بر اساس تعداد کل رویدادها، همراه با وضعیتشان'],
]} />

#### نمونه‌ی ایمیل گزارش

<div>
  <div>
    <p><strong>موضوع:</strong> {'\u{1F4CA}'} گزارش هفتگی خطاهای شما - ۱۵ دسامبر</p>
  </div>
  <div>
    <h4>{'\u{1F4CA}'} گزارش هفتگی خطاهای شما</h4>
    <p>هفته‌ی ۱۵ دسامبر ۲۰۲۵</p>
    <div>
      <div>
        <p>۸</p>
        <p>خطای جدید</p>
      </div>
      <div>
        <p>۱۲</p>
        <p>حل‌شده</p>
      </div>
      <div>
        <p>۵</p>
        <p>باز</p>
      </div>
      <div>
        <p>۴۷</p>
        <p>رخداد</p>
      </div>
    </div>
    <p>{'↑'} ۳۳٪ بیشتر از هفته‌ی قبل</p>
    <div>
      <p>پرتکرارترین خطاهای این هفته:</p>
      <div>
        <p>۱. TypeError: Cannot read 'map' of undefined — <strong>۲۳</strong> · باز</p>
        <p>۲. NetworkError: Failed to fetch — <strong>۱۵</strong> · حل‌شده</p>
        <p>۳. ReferenceError: user is not defined — <strong>۹</strong> · باز</p>
      </div>
    </div>
  </div>
</div>

#### چطور کار می‌کند

1. **جمع‌آوری خودکار:** ابرووا تریس در طول هفته همه‌ی داده‌های خطا را خودکار جمع می‌کند
2. **پردازش هفتگی:** هر دوشنبه ساعت ۹ صبح به وقت نیویورک (بعدازظهر به وقت تهران) آمار خطاهای همه‌ی پروژه‌های شما جمع‌بندی می‌شود
3. **ارسال ایمیل:** خلاصه‌ای قالب‌بندی‌شده به آدرس ایمیل صاحب پروژه فرستاده می‌شود

#### مدیریت گزارش

گزارش خودکار فرستاده می‌شود؛ در کنسول ابرووا تنظیم جداگانه‌ای برای روشن یا خاموش کردنش وجود ندارد.

<Callout kind="note" title="نکته">گزارش حتی در هفته‌ای آرام هم فرستاده می‌شود؛ اگر خطایی نبوده باشد، بخش پرتکرارترین خطاها همین را می‌گوید.</Callout>

- هشدار جهش: https://abrova.ir/docs/trace/spike-detection

<BestPracticeList columns={2} items={[
  ['تشخیص جهش چیست؟', 'ابرووا تریس سرعت ظاهر شدن مشکل‌های جدید را زیر نظر دارد و وقتی این نرخ بالاتر از حد معمول جهش کند، خودکار آن را تشخیص می‌دهد. با تشخیص جهش، هشداری به یکپارچگی‌های فعال پروژه فرستاده می‌شود تا پیش از این‌که کاربران بیشتری درگیر شوند بررسی کنید.'],
]} />

<Callout kind="wallet" title="بدون هزینه‌ی اضافه">هشدار جهش خطا بدون هزینه‌ی اضافه جزو ابرووا تریس است. [قیمت‌ها](/pricing) را ببینید.</Callout>

### تشخیص جهش

وقتی تعداد مشکل‌های جدید در یک ساعت گذشته به ۲۰۰٪ (۲ برابر) میانگین ساعتی یا بیشتر برسد، خودکار تشخیص داده می‌شود و هشداری از طریق یکپارچگی‌های پروژه فرستاده می‌شود؛ تا پیش از این‌که جهش روی کاربران بیشتری اثر بگذارد بررسی کنید.

#### چطور کار می‌کند

1. **پایش مداوم**: ابرووا تریس هر ۱۵ دقیقه مشکل‌های جدید (خطاهایی که اولین بار دیده می‌شوند) را برای هر پروژه و پلتفرم می‌شمارد.
2. **مقایسه با میانگین**: تعداد مشکل‌های جدید در یک ساعت گذشته با میانگین ساعتی ۲۳ ساعت پیش از آن مقایسه می‌شود.
3. **تشخیص جهش**: اگر در یک ساعت گذشته دست‌کم ۳ مشکل جدید باشد و به ۲۰۰٪ (۲ برابر) میانگین یا بیشتر برسد، جهش تشخیص داده می‌شود. اگر اصلاً میانگینی وجود نداشته باشد، بیش از ۵ مشکل جدید در یک ساعت گذشته جهش حساب می‌شود.
4. **ارسال هشدار**: اعلانی به همه‌ی یکپارچگی‌های فعال پروژه (ایمیل، Slack، Discord، Telegram، Webhook، GitHub) فرستاده می‌شود. اگر هیچ یکپارچگی‌ای تنظیم نکرده باشید، هشداری فرستاده نمی‌شود.

#### نمونه‌ی تصویری

مشکل‌های جدید در یک ساعت گذشته ناگهان به ۵ می‌رسند، در حالی که میانگین ۱ در ساعت بوده است:

<div>
  <div>
    {[
      { label: '۰۹:۰۰', h: 20, spike: false },
      { label: '۱۰:۰۰', h: 20, spike: false },
      { label: '۱۱:۰۰', h: 20, spike: false },
      { label: '۱۲:۰۰', h: 20, spike: false },
      { label: '۱۳:۰۰', h: 100, spike: true },
    ].map((bar) => (
      <div key={bar.label}>
        {bar.spike && <span>جهش!</span>}
        <div style={{ height: `${bar.h}%` }} />
        <span>{bar.label}</span>
      </div>
    ))}
  </div>
  <div>
    <div><div /> عادی (حدود ۱ در ساعت)</div>
    <div><div /> جهش (۵ در ساعت)</div>
  </div>
</div>

<Callout kind="note" title="جهش تشخیص داده شد!">۵ مشکل جدید در یک ساعت گذشته یعنی ۵۰۰٪ میانگین (۱ در ساعت). چون این از آستانه‌ی ۲۰۰٪ بیشتر است، هشدار فعال می‌شود.</Callout>

#### پیش‌نمایش ایمیل هشدار (یکپارچگی ایمیل)

<div>
  <div>
    <p><strong>موضوع:</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>

#### پیکربندی

تشخیص جهش برای همه‌ی پروژه‌ها خودکار اجرا می‌شود. چیزی برای روشن کردن وجود ندارد. تنظیمات فعلی:

<ConfigTable rows={[
  ['فاصله‌ی بررسی', '-', '-', 'هر ۱۵ دقیقه'],
  ['آستانه‌ی جهش', '-', '-', '۲۰۰٪ (۲ برابر) میانگین، با دست‌کم ۳ مشکل جدید'],
  ['بازه‌ی مقایسه', '-', '-', 'یک ساعت گذشته'],
  ['بازه‌ی میانگین', '-', '-', 'میانگین ساعتی ۲۳ ساعت قبل'],
  ['روش هشدار', '-', '-', 'یکپارچگی‌های فعال پروژه'],
]} />

آستانه، بازه یا کانال‌های خودتان را می‌خواهید؟ در **ابرووا تریس ← هشدارها** یک قانون **جهش خطا** بسازید. مدیریت قوانین هشدار نقش admin یا owner می‌خواهد؛ memberها می‌توانند هشدارها را تأیید و بی‌صدا کنند. [نقش‌ها و دسترسی‌ها](/docs/trace/error-dashboard#roles) را ببینید.

#### بهترین روش‌ها

<BestPracticeList items={[
  ['سریع واکنش نشان دهید', 'وقتی هشدار جهش گرفتید، فوراً بررسی کنید. deployهای اخیر، سرویس‌های ثالث یا مشکلات زیرساخت را چک کنید.'],
  ['یکپارچگی تنظیم کنید', 'هشدارهای جهش فقط به یکپارچگی‌ها می‌روند؛ در ابرووا تریس ← یکپارچه‌سازی‌ها ایمیل یا Webhook تنظیم کنید. ایمیل و webhook بدون اتصال به خارج از ایران کار می‌کنند.'],
  ['همراه با قوانین نادیده‌گیری', 'آن را با قوانین نادیده‌گیری ترکیب کنید تا خطاهای شناخته‌شده فیلتر شوند و هشدارهای جهش اشتباه کم شوند.'],
]} />

#### عیب‌یابی

<TroubleshootItem title="هشدار جهش نرسید؟">
  <ul>
    <li>مطمئن شوید پروژه دست‌کم یک یکپارچگی دارد و در ابرووا تریس ← یکپارچه‌سازی‌ها روشن است</li>
    <li>با «ارسال تست» روی یکپارچگی مطمئن شوید پیام را می‌رساند</li>
    <li>جهش‌ها <strong>مشکل‌های جدید</strong> را می‌شمارند، نه رویدادهای تکراری مشکلی که از قبل دارید؛ سیلی از یک خطای یکسان جهش حساب نمی‌شود</li>
    <li>در یک ساعت گذشته دست‌کم ۳ مشکل جدید لازم است. پروژه‌ی کاملاً تازه هنوز میانگینی ندارد؛ در این حالت بیش از ۵ مشکل جدید در یک ساعت گذشته جهش حساب می‌شود</li>
    <li>یکپارچگی‌هایی که به Slack، Discord، Telegram یا GitHub می‌فرستند به در دسترس بودن این سرویس‌ها نیاز دارند؛ صفحه‌ی هر یکپارچگی را ببینید</li>
  </ul>
</TroubleshootItem>

- مانیتور کران‌جاب: https://abrova.ir/docs/trace/cron-monitoring

<BestPracticeList columns={2} items={[
  ['مانیتورینگ cron', 'کارهای زمان‌بندی‌شده و cron jobهای خود را مانیتور کنید. وقتی check-inی نرسد، ابرووا تریس از طریق یکپارچگی‌هایی که تنظیم کرده‌اید خبرتان می‌کند و اجراهای ناموفق را ثبت می‌کند. SDK لازم نیست؛ هر کلاینت HTTP می‌تواند check-in بفرستد.'],
]} />

<Callout kind="wallet" title="مانیتورهای رایگان">
  ۳ مانیتور cron رایگان در هر ماه. هر مانیتور اضافه ماهانه ۲٬۰۰۰ تومان هزینه از کیف پول دارد؛ [قیمت‌ها](/pricing) را ببینید. خود check-inها هزینه‌ای ندارند.
</Callout>

<Callout kind="secret">check-inها کلید سرور شما (`ab_srv_…`) را در هدر `X-API-Key` می‌فرستند. آن‌ها را از سرور یا CI و با یک متغیر محیطی اجرا کنید؛ هرگز از داخل اپ.</Callout>

### مانیتورینگ cron

کارهای زمان‌بندی‌شده و cron jobها را با check-inهای HTTP مانیتور کنید. برای check-inهای نرسیده از طریق ایمیل، webhook یا یکپارچگی‌های دیگر باخبر می‌شوید؛ اجراهای ناموفق ثبت و روی مانیتور نمایش داده می‌شوند. SDK لازم نیست؛ هر کلاینت HTTP می‌تواند check-in بفرستد.

#### چطور کار می‌کند

1. **ساختن مانیتور**: در کنسول ابرووا یک مانیتور cron با slug یکتا، زمان‌بندی (عبارت cron یا فاصله‌ی زمانی) و مهلت اضافه تعریف کنید.
2. **ارسال check-in**: cron job شما هر بار که اجرا می‌شود یک HTTP POST به API مربوط به check-in می‌فرستد. SDK لازم نیست؛ فقط یک فراخوانی ساده‌ی HTTP.
3. **تشخیص کارهای اجرانشده**: ابرووا تریس هر ۵ دقیقه همه‌ی مانیتورها را بررسی می‌کند. اگر check-in دیر شده باشد (بیشتر از فاصله‌ی مورد انتظار به‌علاوه‌ی مهلت اضافه)، وضعیت مانیتور به «missed» تغییر می‌کند.
4. **دریافت اعلان**: وقتی کاری اجرا نشده باشد، اعلان به یکپارچگی‌هایی که روی مانیتور انتخاب کرده‌اید (ایمیل، Webhook و غیره) فرستاده می‌شود.

#### ساختن مانیتور (داشبورد)

1. در کنسول ابرووا، پروژه‌تان را باز کنید ← **ابرووا تریس ← Crons**
2. روی **«مانیتور جدید»** کلیک کنید
3. جزئیات مانیتور را پر کنید (پیکربندی پایین را ببینید)
4. در صورت تمایل، کانال‌های اعلان را از میان یکپارچگی‌های فعال انتخاب کنید
5. برای ذخیره روی **«ساخت مانیتور»** کلیک کنید

مدیریت مانیتورها (ساختن، ویرایش، توقف موقت، حذف) نقش **admin** یا **owner** می‌خواهد؛ همه‌ی نقش‌ها می‌توانند مانیتورها و تاریخچه‌ی check-inهایشان را ببینند. [نقش‌ها و دسترسی‌ها](/docs/trace/error-dashboard#roles) را ببینید.

#### پیکربندی مانیتور

<ConfigTable rows={[
  ['Name', 'string', 'بله', 'نام توصیفی (مثلاً «Daily Database Backup»)'],
  ['Slug', 'string', 'بله', 'شناسه‌ی یکتایی که در API مربوط به check-in استفاده می‌شود (مثلاً «daily-backup»). خودکار از روی نام ساخته می‌شود.'],
  ['Schedule', 'string', 'خیر', 'عبارت cron (مثلاً «0 2 * * *»). اگر تنظیم شود، فاصله‌ی مورد انتظار را همین تعیین می‌کند.'],
  ['Expected Interval', 'number', 'بله', 'هر چند وقت یک بار کار باید اجرا شود، بر حسب دقیقه (پیش‌فرض: ۶۰). وقتی عبارت cron تنظیم نشده باشد استفاده می‌شود.'],
  ['Grace Period', 'number', 'بله', 'دقیقه‌های اضافه‌ی انتظار پیش از missed حساب کردن (پیش‌فرض: ۵)'],
  ['Environment', 'string', 'خیر', 'فیلتر بر اساس محیط (مثلاً production)'],
  ['Notification Channels', 'multi-select', 'خیر', 'از میان یکپارچگی‌های فعال خود انتخاب کنید'],
]} />

#### ارسال check-in از کارها

وقتی cron job اجرا می‌شود، یک HTTP POST به endpoint مربوط به check-in بفرستید. با **کلید سرور** پروژه (`ab_srv_...`) در هدر `X-API-Key` احراز هویت کنید. اگر slug هنوز وجود نداشته باشد، مانیتور **خودکار ساخته می‌شود**.

<Callout kind="note" title="کدام کلید؟">
  cron jobها روی سرورهای شما اجرا می‌شوند، پس از کلید سرور استفاده کنید. کلید اپ (<code>ab_live_...</code>) هم تا وقتی تنظیم پروژه‌ی <strong>server routeها به server secret نیاز دارند</strong> خاموش است پذیرفته می‌شود؛ اما این کلید داخل اپ‌های شما منتشر می‌شود، پس هر کسی آن را استخراج کند می‌تواند check-in جعلی «ok» بفرستد. وقتی کارهایتان از کلید سرور استفاده کردند، این تنظیم را روشن کنید. <a href="/docs/trace/server-secret">کلید سرور و routeهای سرور</a> را ببینید.
</Callout>

<Callout kind="note" title="ساخت خودکار مانیتور">
  اگر check-inی با slugی بفرستید که وجود ندارد، ابرووا تریس خودکار مانیتوری با تنظیمات پیش‌فرض (فاصله‌ی ۶۰ دقیقه، مهلت اضافه‌ی ۵ دقیقه) می‌سازد. بعد می‌توانید آن را در داشبورد شخصی‌سازی کنید.
</Callout>

#### API مربوط به check-in

<Endpoint method="POST" url="https://trace.abrova.ir/api/cron-monitors/check-in" />

<div>
  <table>
    <thead>
      <tr>
        {['فیلد', 'نوع', 'الزامی', 'توضیح'].map((h) => (
          <th key={h}>{h}</th>
        ))}
      </tr>
    </thead>
    <tbody>
      {[
        ['monitor_slug', 'string', 'بله', 'slug یکتای مانیتور'],
        ['status', 'string', 'بله', '"ok"، "error" یا "in_progress"'],
        ['check_in_id', 'string', 'خیر', 'UUID برای دنبال کردن کارهای چندمرحله‌ای (به‌صورت `id` از in_progress برگردانده می‌شود)'],
        ['duration_ms', 'number', 'خیر', 'مدت اجرای کار بر حسب میلی‌ثانیه'],
        ['environment', 'string', 'خیر', 'نام محیط (مثلاً "production")'],
        ['message', 'string', 'خیر', 'پیام یا جزئیات خطا (اختیاری)'],
      ].map(([field, type, required, desc]) => (
        <tr key={field}>
          <td><code>{field}</code></td>
          <td>{type}</td>
          <td>{required === 'بله' ? <span>بله</span> : <span>خیر</span>}</td>
          <td>{desc}</td>
        </tr>
      ))}
    </tbody>
  </table>
</div>

#### مثال‌ها

#### check-in ساده (curl)

وقتی کار با موفقیت تمام شد، یک check-in با وضعیت «ok» بفرستید:

```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
  }'
```

#### گزارش خطا (curl)

اگر کار شکست خورد، آن را با وضعیت «error» گزارش کنید:

```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"
  }'
```

#### کار چندمرحله‌ای (curl)

برای کارهای طولانی، با «in_progress» شروع کنید و با «ok» یا «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)

<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

هر cron jobی را با یک فراخوانی ساده‌ی check-in در انتها بپوشانید:

```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
```

#### وضعیت‌های مانیتور

<div>
  {[
    { status: 'OK', color: 'bg-emerald-900/20 border-emerald-800 text-emerald-400', desc: 'آخرین check-in موفق بوده است' },
    { status: 'Error', color: 'bg-red-900/20 border-red-800 text-red-400', desc: 'آخرین check-in خطا گزارش کرده است' },
    { status: 'Missed', color: 'bg-amber-900/20 border-amber-800 text-amber-400', desc: 'در زمان مورد انتظار هیچ check-inی نرسیده است' },
    { status: 'Disabled', color: 'bg-white/[0.05] border-white/[0.08] text-zinc-500', desc: 'مانیتور موقتاً متوقف است' },
  ].map((s) => (
    <div key={s.status}>
      <strong>{s.status}</strong>
      <p>{s.desc}</p>
    </div>
  ))}
</div>

#### مرجع API

cron job شما check-inها را به یک endpoint عمومی می‌فرستد:

```
POST /api/cron-monitors/check-in
```

این endpoint یک اعتبارنامه‌ی پروژه را در هدر `X-API-Key` می‌گیرد: **کلید سرور** (توصیه‌شده)، یا کلید اپ تا وقتی تنظیم «server routeها به server secret نیاز دارند» خاموش است.

مانیتورها را در کنسول ابرووا مدیریت کنید. این‌که کاربر واردشده آنجا چه کارهایی می‌تواند بکند به نقشش بستگی دارد؛ <a href="/docs/trace/error-dashboard#roles">نقش‌ها و دسترسی‌ها</a> را ببینید.

#### بهترین روش‌ها

<BestPracticeList items={[
  ['slugهای گویا انتخاب کنید', 'slugهایی مثل «daily-backup»، «hourly-sync» یا «weekly-report» انتخاب کنید که کار را به‌روشنی معرفی کنند.'],
  ['مهلت اضافه‌ی مناسب بگذارید', 'برای نوسان طبیعی مدت اجرای کار فاصله‌ی کافی بگذارید. مهلت ۵ دقیقه برای بیشتر کارها کافی است؛ برای کارهایی با زمان اجرای متغیر مهلت بیشتری بدهید.'],
  ['خطا را هم گزارش کنید، نه فقط موفقیت', 'وقتی کاری شکست می‌خورد همیشه check-inی با وضعیت «error» بفرستید. این‌طور هم کارهای اجرانشده و هم کارهای ناموفق را می‌بینید.'],
  ['مدت را ثبت کنید', 'duration_ms را در check-inها بفرستید تا افت عملکرد را در طول زمان ببینید.'],
  ['برای کارهای طولانی از حالت چندمرحله‌ای استفاده کنید', 'برای کارهایی که دقیقه‌ها یا ساعت‌ها طول می‌کشند، الگوی in_progress و سپس ok/error را به کار ببرید. این‌طور می‌توانید «هنوز در حال اجرا» را از «اجرانشده» تشخیص دهید.'],
  ['اعلان‌ها را تنظیم کنید', 'دست‌کم یک یکپارچگی وصل کنید (ایمیل یا Webhook بدون اتصال به خارج از ایران کار می‌کنند) تا وقتی کاری اجرا نشد هشدار بگیرید.'],
]} />

#### عیب‌یابی

<TroubleshootItem title="مانیتور missed نشان می‌دهد اما کار اجرا شده است؟">
  <ul>
    <li>مطمئن شوید کلید درست و فعال است؛ وضعیت HTTP پاسخ check-in را ببینید؛ 401 یعنی رد شده است</li>
    <li>مطمئن شوید <code>monitor_slug</code> دقیقاً یکی است</li>
    <li>مطمئن شوید درخواست check-in به سرور می‌رسد (شبکه و firewall را بررسی کنید)</li>
    <li>فاصله‌ی مورد انتظار را بازبینی کنید؛ اگر کار هر ۲۴ ساعت اجرا می‌شود، فاصله را ۱۴۴۰ دقیقه بگذارید</li>
    <li>مهلت اضافه را بررسی کنید؛ اگر زمان شروع کار متغیر است آن را بیشتر کنید</li>
  </ul>
</TroubleshootItem>

<TroubleshootItem title="اعلان کارهای اجرانشده نمی‌رسد؟">
  <ul>
    <li>مطمئن شوید روی مانیتور کانال اعلان انتخاب شده است</li>
    <li>مطمئن شوید یکپارچگی‌های انتخاب‌شده فعال‌اند (در ابرووا تریس ← یکپارچه‌سازی‌ها تستشان کنید)</li>
    <li>تشخیص کارهای اجرانشده هر ۵ دقیقه انجام می‌شود؛ ممکن است کمی تأخیر باشد</li>
    <li>مطمئن شوید مانیتور فعال است (غیرفعال یا خاموش نشده باشد)</li>
  </ul>
</TroubleshootItem>

<TroubleshootItem title="API مربوط به check-in خطای 401 می‌دهد؟">
  <ul>
    <li>مطمئن شوید کلید با <code>ab_srv_</code> (یا <code>ab_live_</code>) شروع می‌شود</li>
    <li>اگر پاسخ <code>server_credential_required</code> می‌گوید، تنظیم پروژه‌ی <strong>server routeها به server secret نیاز دارند</strong> روشن است و کار کلید اپ را فرستاده؛ از کلید سرور استفاده کنید</li>
    <li>مطمئن شوید کلید در هدر <code>X-API-Key</code> فرستاده می‌شود</li>
    <li>مطمئن شوید کلید API متعلق به پروژه‌ی فعالی است که ابرووا تریس در آن فعال است</li>
  </ul>
</TroubleshootItem>

<TroubleshootItem title="نمی‌توانید مانیتور دیگری بسازید؟">
  <ul>
    <li>۳ مانیتور رایگان است؛ مانیتورهای بیشتر از کیف پول سازمان پرداخت می‌شوند (ماهانه ۲٬۰۰۰ تومان برای هر مانیتور اضافه)</li>
    <li>کیف پول را در کنسول ابرووا شارژ کنید، یا مانیتوری را که دیگر لازم ندارید حذف کنید</li>
  </ul>
</TroubleshootItem>

<TroubleshootItem title="مانیتور خودکارساخته تنظیمات اشتباه دارد؟">
  <ul>
    <li>مانیتورهای خودکارساخته از مقادیر پیش‌فرض استفاده می‌کنند (فاصله‌ی ۶۰ دقیقه، مهلت ۵ دقیقه)</li>
    <li>در کنسول ابرووا به ابرووا تریس ← Crons بروید و مانیتور را ویرایش کنید</li>
    <li>یا از اول مانیتور را با تنظیمات دلخواه در داشبورد بسازید</li>
  </ul>
</TroubleshootItem>

- کلید سرور و مسیرهای سرور: https://abrova.ir/docs/trace/server-secret

هر پروژه‌ی ابرووا دو اعتبارنامه دارد. این صفحه توضیح می‌دهد هر کدام کجا به کار می‌رود، و چطور routeهایی را که فقط سرورهای شما استفاده می‌کنند طوری تنظیم کنید که فقط کلید سرور را بپذیرند.

### دو اعتبارنامه

<ConfigTable headers={['اعتبارنامه', 'شکل آن', 'جای آن']} rows={[
  ['کلید اپ', 'ab_live_...', 'داخل اپ‌های موبایل و وب شما. همراه اپ منتشر می‌شود، پس هر کسی اپ را داشته باشد می‌تواند آن را استخراج کند.'],
  ['کلید سرور', 'ab_srv_...', 'فقط روی سرورهای شما: log agent، cron jobها، اسکریپت‌های deploy و SDKهای بک‌اند. هرگز آن را داخل اپ یا کدی که در مرورگر اجرا می‌شود نگذارید.'],
]} />

هر دو در کنسول ابرووا در **تنظیمات پروژه ← کلیدها** هستند. کلید سرور فقط یک بار نمایش داده می‌شود، وقتی آن را می‌سازید یا عوض می‌کنید؛ آن را در secret manager یا محیط سرور خود نگه دارید.

### این تنظیم چه می‌کند

**server routeها به server secret نیاز دارند** یک سوییچ برای هر پروژه است که در کنسول ابرووا در **تنظیمات پروژه ← محصولات ← ابرووا تریس** قرار دارد. به‌طور **پیش‌فرض خاموش** است.

وقتی **روشن** باشد، routeهایی که فقط سرورها و agentها صدا می‌زنند فقط کلید سرور را می‌پذیرند. درخواستی که فقط کلید اپ را دارد آنجا با `401` رد می‌شود:

<ConfigTable headers={['Route', 'استفاده‌کننده', 'با روشن بودن تنظیم']} rows={[
  ['اتصال log agent', 'Abrova Trace Agent', 'کلید سرور لازم است'],
  ['ثبت کانتینر و وضعیت آن', 'Abrova Trace Agent', 'کلید سرور لازم است'],
  ['POST /api/cron-monitors/check-in', 'cron jobهای شما', 'کلید سرور لازم است'],
  ['POST /api/logs/deploys', 'اسکریپت‌های deploy شما', 'کلید سرور لازم است'],
  ['POST /api/logs/ingest و /api/logs/ingest/batch', 'اپ‌ها، سرورها و agent', 'بی‌تأثیر؛ کلید اپ همچنان کار می‌کند'],
  ['خطاها، پیام‌ها و داده‌های عملکرد', 'اپ‌ها و SDKهای شما', 'بی‌تأثیر؛ کلید اپ همچنان کار می‌کند'],
]} />

برای اپ‌های شما چیزی تغییر نمی‌کند: خطاها، پیام‌ها، داده‌های عملکرد و لاگ‌هایی که با کلید اپ فرستاده می‌شوند، چه این تنظیم روشن باشد چه خاموش، کار می‌کنند.

### چرا روشنش کنیم

کلید اپ ذاتاً عمومی است. بدون این تنظیم، کسی که آن را از اپ شما استخراج کرده می‌تواند:

- یک check-in جعلی cron با پیام «کار موفق بود» بفرستد و کاری را که شکست می‌خورد یا اجرا نمی‌شود پنهان کند،
- نشانگرهای deploy جعلی بنویسد،
- به‌عنوان یک log agent جعلی وصل شود.

با روشن بودن این تنظیم، کلید اپ برای هیچ‌کدام از این کارها کافی نیست.

**وقتی روشنش کنید که** log agent اجرا می‌کنید، از مانیتورینگ cron استفاده می‌کنید یا نشانگر deploy می‌فرستید. پروژه‌ای که فقط از SDKهای موبایل و وب استفاده می‌کند به آن نیازی ندارد.

<H2 id="give-your-servers-the-server-secret" step={1}>کلید سرور را به سرورهایتان بدهید</H2>

دو راه برای فرستادن کلید سرور روی HTTP وجود دارد. هر دو روی همه‌ی routeهای جدول بالا کار می‌کنند:

- کلید سرور را **به‌جای کلید** بفرستید: `x-api-key: ab_srv_...`
- کلید اپ را در `x-api-key` نگه دارید و کلید سرور را در هدر دوم بفرستید: `x-server-secret: ab_srv_...`

#### Log agent

agent یک اعتبارنامه می‌گیرد، در `ABROVA_TRACE_API_KEY`. آن را روی کلید سرور بگذارید و agent را دوباره deploy کنید:

```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
```

در چیدمان چندسروری فقط collector اعتبارنامه را نگه می‌دارد؛ agentهای راه دور به تغییری نیاز ندارند. [اپ دسکتاپ](/desktop) ابرووا (به‌زودی) هم agent را deploy خواهد کرد و همین کلید را از شما می‌خواهد. [Abrova Trace Agent](/docs/trace/agent) را ببینید.

#### check-inهای cron

```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"}'
```

[مانیتورینگ cron](/docs/trace/cron-monitoring) را ببینید.

#### نشانگرهای deploy

نشانگر deploy به ابرووا تریس می‌گوید «همین الان یک deploy انجام شد»، تا صفحه‌ی لاگ‌ها بتواند نشان دهد از آخرین deploy چه چیزی جدید است. آن را در انتهای اسکریپت deploy صدا بزنید. همه‌ی فیلدها اختیاری‌اند:

```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', 'خیر', 'نسخه یا commitی که deploy کرده‌اید'],
  ['environment', 'string', 'خیر', 'محیط (پیش‌فرض: production)'],
  ['source', 'string', 'خیر', 'چه چیزی deploy شده، مثلاً نام سرویس'],
  ['description', 'string', 'خیر', 'متن آزاد'],
  ['deployedAt', 'string', 'خیر', 'زمان به قالب ISO 8601 (پیش‌فرض: همین الان)'],
]} />

پاسخ (`201`): <code>{`{"success": true, "deploy": { ... }}`}</code>

#### لاگ‌هایی که از سرورها فرستاده می‌شوند

[Logs REST API](/docs/trace/logs-rest-api) هیچ‌وقت به‌خاطر این تنظیم رد نمی‌شود، اما سرور بهتر است همچنان با کلید سرور احراز هویت کند، نه با کلید اپ. SDKهای Node.js و Laravel همین حالا کلید سروری را که با آن پیکربندی‌شان کرده‌اید می‌فرستند.

<H2 id="check-that-nothing-still-uses-the-app-key" step={2}>مطمئن شوید چیزی هنوز از کلید اپ استفاده نمی‌کند</H2>

در کنسول ابرووا، **تنظیمات پروژه ← محصولات ← ابرووا تریس** را باز کنید. خط زیر سوییچ نشان می‌دهد درخواست‌های اخیر روی routeهای سرور (در ۳۰ روز گذشته) چطور احراز هویت شده‌اند:

- **«در ۳۰ روز گذشته، N درخواست در server routeها از کلید برنامه استفاده کرده‌اند.»**: چیزی هنوز کلید اپ را می‌فرستد. اول آن را پیدا کنید و به کلید سرور منتقل کنید.
- **«آماده: در ۳۰ روز گذشته همهٔ درخواست‌های server routeها از server secret استفاده کرده‌اند.»**: روشن کردن امن است.
- **«در ۳۰ روز گذشته هیچ درخواستی در server routeها نبوده است.»**: هنوز چیزی از این routeها استفاده نمی‌کند؛ روشن کردن روی کسی اثر ندارد.

<H2 id="switch-it-on" step={3}>روشن کردن</H2>

**server routeها به server secret نیاز دارند** را روشن کنید و ذخیره کنید. از آن به بعد، درخواستی روی route سرور که کلید سرور ندارد این پاسخ را می‌گیرد:

```json
{
  "error": "Server credential required",
  "code": "server_credential_required"
}
```

درخواستی که `x-server-secret` اشتباه بفرستد `401` با `"code": "server_credential_invalid"` می‌گیرد.

هر وقت بخواهید می‌توانید این تنظیم را دوباره خاموش کنید؛ در این صورت کلید اپ مثل قبل روی این routeها پذیرفته می‌شود.

### عیب‌یابی

<TroubleshootItem title="بعد از روشن کردن، check-inهای cron یا نشانگرهای deploy خطای 401 می‌دهند">
  <p>کار هنوز کلید اپ را می‌فرستد. در هدر <code>X-API-Key</code> آن را با کلید سرور (<code>ab_srv_...</code>) عوض کنید، یا هدر <code>x-server-secret</code> را اضافه کنید. تا آن موقع مانیتور کار را اجرانشده نشان می‌دهد.</p>
</TroubleshootItem>

<TroubleshootItem title="بعد از روشن کردن، کانتینرها به‌روز نمی‌شوند یا قابل کنترل نیستند">
  <p>agent هنوز با کلید اپ اجرا می‌شود. خطوط لاگ همچنان می‌رسند، اما agent دیگر نمی‌تواند کانتینرها را ثبت کند، وضعیتشان را بفرستد یا دستور بگیرد. آن را با مقدار کلید سرور در <code>ABROVA_TRACE_API_KEY</code> دوباره deploy کنید.</p>
</TroubleshootItem>

<TroubleshootItem title="کلید سرور را عوض کردم">
  <p>آن را همه‌جا به‌روز کنید: agent، cron jobها، اسکریپت‌های deploy و پیکربندی SDK بک‌اند. کلید قدیمی همان لحظه‌ی عوض کردن از کار می‌افتد.</p>
</TroubleshootItem>

- ایمیل: https://abrova.ir/docs/trace/email

هشدارهای خطا را در صندوق ایمیل خود بگیرید. گیرندگان اعلان‌های ایمیلی ابرووا تریس را تنظیم کنید.

<Callout kind="note" title="چه چیزهایی لازم دارید">
  <ul>
    <li>آدرس‌های ایمیلی که اعلان‌ها را دریافت می‌کنند</li>
    <li>دسترسی owner یا admin به پروژه</li>
  </ul>
</Callout>

<Callout kind="tip" title="داخل ایران کار می‌کند">ایمیل کانال پیش‌فرض خوبی در ایران است: به هیچ سرویس پیام‌رسانی بیرون از کشور نیاز ندارد و با هر صندوق ایمیلی که تیم شما استفاده می‌کند، از جمله سرویس‌های ایمیل ایرانی، کار می‌کند.</Callout>

این‌که پروژه‌ی شما از کدام کانال‌ها می‌تواند استفاده کند، در صفحه‌ی **ابرووا تریس ← یکپارچه‌سازی‌ها** در کنسول ابرووا نمایش داده می‌شود.

<H2 id="set-up-email-integration" step={1}>راه‌اندازی یکپارچگی ایمیل</H2>

1. در کنسول ابرووا، **ابرووا تریس ← یکپارچه‌سازی‌ها** را باز کنید (یکپارچگی‌ها متعلق به پروژه‌ی انتخاب‌شده‌اند)
2. روی **«افزودن یکپارچه‌سازی»** کلیک کنید و **ایمیل** را انتخاب کنید (یا روی کارت ایمیل **«اتصال»** را بزنید)
3. یک **نام** وارد کنید و فیلدهای پیکربندی را پر کنید
4. روی **«ذخیرهٔ کانال»** کلیک کنید، یا **«ذخیره و ارسال تست»** را بزنید تا ذخیره و بررسی شود

<ConfigTable rows={[
  ['Name', 'string', 'بله', 'نامی آشنا (مثلاً «تیم کشیک»)'],
  ['Recipients', 'string', 'بله', 'یک یا چند آدرس (تا ۵۰ آدرس)؛ بعد از هر آدرس Enter یا ویرگول بزنید'],
]} />

مدیریت یکپارچگی‌ها (افزودن، ویرایش، روشن و خاموش کردن، حذف، تست) نقش **admin** یا **owner** می‌خواهد؛ همه‌ی نقش‌ها می‌توانند آن‌ها و لاگ ارسالشان را ببینند. [نقش‌ها و دسترسی‌ها](/docs/trace/error-dashboard#roles) را ببینید.

### نمونه‌های پیکربندی

- **یک گیرنده**: گیرنده: `dev@company.com`
- **چند گیرنده**: گیرندگان: `dev@co.com`، `ops@co.com`، `team@co.com`
- **فهرست توزیع**: گیرنده: `alerts@company.com`

### قالب ایمیل

هر ایمیل اعلان شامل این‌هاست:

- **موضوع**: `[AbrovaTrace] New Error: TypeError: Cannot read property 'map' of undefined`
- پیام خطا و stack trace
- نام پروژه و محیط
- زمان اولین رخداد خطا
- تعداد رخدادها
- URL صفحه و user agent، اگر خطا آن‌ها را داشته باشد
- لینکی برای دیدن خطا

ایمیل‌های خطای جدید اولین باری که خطا دیده می‌شود فرستاده می‌شوند. تشخیص جهش هم به همین گیرندگان ایمیل می‌زند، و قوانین هشدار و مانیتورهای cron هم وقتی این کانال را برایشان انتخاب کنید.

### بهترین روش‌ها

<BestPracticeList items={[
  ['از فهرست توزیع تیمی استفاده کنید', 'به‌جای آدرس‌های تکی از team@company.com استفاده کنید'],
  ['بر اساس موضوع فیلتر کنید', 'موضوع همه‌ی ایمیل‌ها با [AbrovaTrace] شروع می‌شود و ساختن قانون در صندوق ایمیل را ساده می‌کند'],
  ['فیلتر ایمیل بسازید', 'در برنامه‌ی ایمیل خود فیلتر بسازید تا اعلان‌های ابرووا تریس مرتب شوند'],
  ['چند یکپارچگی برای تیم‌ها', 'برای تیم فرانت‌اند، تیم بک‌اند و غیره یکپارچگی‌های جداگانه بسازید'],
]} />

### عیب‌یابی

<TroubleshootItem title="ایمیلی نمی‌رسد؟">
  <ul>
    <li>پوشه‌ی spam یا junk را بررسی کنید</li>
    <li>مطمئن شوید آدرس‌های ایمیل درست‌اند (بدون غلط تایپی)</li>
    <li>مطمئن شوید یکپارچگی در ابرووا تریس ← یکپارچه‌سازی‌ها روشن است</li>
    <li>یکپارچگی را با دکمه‌ی «ارسال تست» تست کنید</li>
  </ul>
</TroubleshootItem>

<TroubleshootItem title="آدرسی قرمز شده است؟">
  <ul>
    <li>هر گیرنده باید آدرس معتبری باشد، مثلاً <code>email1@domain.com</code></li>
    <li>بعد از هر آدرس Enter بزنید یا ویرگول تایپ کنید تا اضافه شود</li>
    <li>پیش از ذخیره، آدرس‌های قرمزشده را اصلاح یا حذف کنید</li>
  </ul>
</TroubleshootItem>

- وب‌هوک دلخواه: https://abrova.ir/docs/trace/webhooks

داده‌های خطا را با webhookهای سفارشی به هر endpoint مربوط به HTTP بفرستید. با ابزارهای مدیریت حادثه، سیستم‌های داخلی یا هر چیزی که درخواست POST می‌پذیرد یکپارچه شوید.

<Callout kind="note" title="چه چیزهایی لازم دارید">
  <ul>
    <li>یک endpoint مربوط به HTTP که درخواست POST بپذیرد</li>
    <li>(اختیاری) یک کلید امضا برای بررسی درخواست‌ها</li>
    <li>دسترسی owner یا admin به پروژه</li>
  </ul>
</Callout>

<Callout kind="tip" title="داخل ایران کار می‌کند">webhook کانال پیش‌فرض خوبی در ایران است: آن را به سرور خودتان (یا ابزاری داخلی که روی اینترنت عمومی در دسترس است) وصل کنید تا هیچ سرویسی بیرون از کشور درگیر نشود.</Callout>

این‌که پروژه‌ی شما از کدام کانال‌ها می‌تواند استفاده کند، در صفحه‌ی **ابرووا تریس ← یکپارچه‌سازی‌ها** در کنسول ابرووا نمایش داده می‌شود.

<H2 id="set-up-webhook-integration" step={1}>راه‌اندازی یکپارچگی Webhook</H2>

1. در کنسول ابرووا، **ابرووا تریس ← یکپارچه‌سازی‌ها** را باز کنید (یکپارچگی‌ها متعلق به پروژه‌ی انتخاب‌شده‌اند)
2. روی **«افزودن یکپارچه‌سازی»** کلیک کنید و **Webhook** را انتخاب کنید (یا روی کارت Webhook **«اتصال»** را بزنید)
3. یک **نام** وارد کنید و فیلدهای پیکربندی را پر کنید
4. روی **«ذخیرهٔ کانال»** کلیک کنید، یا **«ذخیره و ارسال تست»** را بزنید تا ذخیره و بررسی شود

<ConfigTable rows={[
  ['Name', 'string', 'بله', 'نامی برای شناسایی (مثلاً «Incident bridge»)'],
  ['URL', 'string', 'بله', 'URL مربوط به endpoint شما. باید با https:// شروع شود و روی اینترنت عمومی در دسترس باشد (مثلاً https://your-server.com/api/abrova-trace-webhook)'],
  ['Signing secret', 'string', 'خیر', 'برای امضای هر درخواست، تا سرور شما بتواند آن را بررسی کند'],
]} />

#### قواعد URL

- URL باید از `https://` استفاده کند و نباید نام کاربری یا رمز عبور داشته باشد.
- host باید آدرس عمومی باشد. آدرس‌های خصوصی، loopback و دیگر آدرس‌های داخلی (مثلاً `localhost`، `10.x.x.x`، `192.168.x.x`) هنگام ذخیره رد می‌شوند و هرگز فراخوانی نمی‌شوند.
- redirectها دنبال نمی‌شوند: اگر endpoint شما با `3xx` پاسخ دهد، ارسال ناموفق حساب می‌شود. URL نهایی را وارد کنید.

#### بعد از ذخیره

مدیریت یکپارچگی‌ها (افزودن، ویرایش، روشن و خاموش کردن، حذف، تست) نقش **admin** یا **owner** می‌خواهد؛ همه‌ی نقش‌ها می‌توانند آن‌ها و لاگ ارسالشان را ببینند. [نقش‌ها و دسترسی‌ها](/docs/trace/error-dashboard#roles) را ببینید.

URL و کلید امضا بعد از ذخیره دیگر هرگز نمایش داده نمی‌شوند: فرم آن‌ها را «تنظیم‌شده» نشان می‌دهد (برای URL فقط scheme و host). فیلد را دست نزنید تا مقدار ذخیره‌شده بماند، یا **جایگزینی** را بزنید تا مقدار تازه‌ای وارد کنید.

اگر URL را به host دیگری تغییر دهید (یا scheme یا port را عوض کنید)، کلید امضا را هم دوباره وارد کنید؛ کلید ذخیره‌شده هرگز خودبه‌خود به مقصد جدیدی فرستاده نمی‌شود. تغییر فقط مسیر روی همان host آن را نگه می‌دارد.

### قالب payload

وقتی خطایی اولین بار دیده می‌شود، ابرووا تریس یک درخواست POST از نوع JSON با این ساختار می‌فرستد:

<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 ..."
  }
}`} />

قوانین هشدار و مانیتورهای cron که به این webhook وصل‌اند به‌جای آن رویدادهای `alert.triggered` / `alert.resolved` می‌فرستند، با `data` شامل `rule_name`، `rule_type`، `metric_value`، `threshold`، `operator`، `window_minutes`، `project` و `environment`.

#### امضا

وقتی کلید امضا تنظیم شده باشد، هر درخواست این‌ها را دارد:

- `X-AbrovaTrace-Signature: sha256=<hex>`: مقدار HMAC-SHA256 بدنه‌ی JSON با کلید شما
- `X-AbrovaTrace-Timestamp`: زمان ارسال بر حسب میلی‌ثانیه

### بهترین روش‌ها

<BestPracticeList items={[
  ['امضاها را بررسی کنید', 'با کلید امضا مطمئن شوید درخواست‌های ورودی از ابرووا تریس آمده‌اند'],
  ['سریع پاسخ دهید', 'ظرف ۱۰ ثانیه پاسخ 2xx برگردانید؛ پاسخ کندتر، redirect (3xx) یا هر پاسخ غیر 2xx ناموفق حساب می‌شود'],
  ['لاگ ارسال را بررسی کنید', 'ارسال‌های ناموفق دوباره تلاش نمی‌شوند؛ در لاگ ارسال یکپارچگی به‌صورت ناموفق نمایش داده می‌شوند'],
]} />

- Telegram: https://abrova.ir/docs/trace/telegram

هشدارهای خطا را فوراً با ربات Telegram بگیرید. یک ربات بسازید، chat ID خود را پیدا کنید و در چند دقیقه دریافت اعلان‌ها را شروع کنید.

<Callout kind="warn" title="دسترسی به Telegram از ایران">
  Telegram سرویسی بیرون از ایران است و ممکن است از برخی شبکه‌های داخل ایران در دسترس نباشد. برای راه‌اندازی و خواندن هشدارها به اتصالی نیاز دارید که به Telegram برسد، و پیام‌ها فقط وقتی می‌رسند که api.telegram.org پاسخ دهد؛ ارسال‌های ناموفق در لاگ ارسال یکپارچگی نمایش داده می‌شوند. اگر این برای تیم شما مشکل است، به‌جای آن یا در کنارش از یکپارچگی [ایمیل](/docs/trace/email) یا [Webhook](/docs/trace/webhooks) استفاده کنید.
</Callout>

این‌که پروژه‌ی شما از کدام کانال‌ها می‌تواند استفاده کند، در صفحه‌ی **ابرووا تریس ← یکپارچه‌سازی‌ها** در کنسول ابرووا نمایش داده می‌شود.

<H2 id="create-a-telegram-bot" step={1}>ساختن ربات Telegram</H2>

1. Telegram را باز کنید و **@BotFather** را جست‌وجو کنید
2. دستور `/newbot` را بفرستید
3. یک نام برای ربات وارد کنید (مثلاً **«AbrovaTrace Alerts»**)
4. یک نام کاربری وارد کنید (باید با «bot» تمام شود، مثلاً **«MyAbrovaTrace_bot»**)
5. **Bot Token** را که BotFather می‌دهد کپی کنید

قالب توکن: `1234567890:ABCdefGHIjklMNOpqrsTUVwxyz123456789`

<Callout kind="note" title="نکته‌ی امنیتی">توکن ربات را محرمانه نگه دارید. هر کسی توکن را داشته باشد می‌تواند ربات شما را کنترل کند.</Callout>

<H2 id="get-your-chat-id" step={2}>پیدا کردن Chat ID</H2>

#### گزینه‌ی الف: گفت‌وگوی شخصی

1. با ربات خود گفت‌وگو را شروع کنید (با نام کاربری جست‌وجویش کنید)
2. هر پیامی به ربات بفرستید
3. این URL را در مرورگر باز کنید:

<CodeBlock language="text" code="https://api.telegram.org/bot{YOUR_BOT_TOKEN}/getUpdates" />

Chat ID را در پاسخ JSON زیر `message.chat.id` پیدا کنید.

#### گزینه‌ی ب: گروه

1. یک گروه جدید بسازید یا از گروهی موجود استفاده کنید
2. ربات را به گروه اضافه کنید
3. در گروه یک پیام بفرستید
4. از همان URL مربوط به `getUpdates` در بالا استفاده کنید

Chat ID گروه‌ها عدد منفی است (مثلاً `-1001234567890`).

<H2 id="configure-in-abrovatrace" step={3}>پیکربندی در ابرووا تریس</H2>

1. در کنسول ابرووا، **ابرووا تریس ← یکپارچه‌سازی‌ها** را باز کنید (یکپارچگی‌ها متعلق به پروژه‌ی انتخاب‌شده‌اند)
2. روی **«افزودن یکپارچه‌سازی»** کلیک کنید و **Telegram** را انتخاب کنید (یا روی کارت Telegram **«اتصال»** را بزنید)
3. یک **نام**، Bot token و Chat ID را وارد کنید
4. روی **«ذخیره و ارسال تست»** کلیک کنید تا ذخیره و بررسی شود (یا **«ذخیرهٔ کانال»**)

<ConfigTable rows={[
  ['Name', 'string', 'بله', 'نامی آشنا (مثلاً Ops chat)'],
  ['Bot token', 'string', 'بله', 'توکنی که BotFather داده است (1234567890:ABC...)'],
  ['Chat ID', 'string', 'بله', 'Chat ID شخصی یا گروه (یک عدد، مثلاً -1001234567890) یا @channelname'],
]} />

#### بعد از ذخیره

مدیریت یکپارچگی‌ها (افزودن، ویرایش، روشن و خاموش کردن، حذف، تست) نقش **admin** یا **owner** می‌خواهد؛ همه‌ی نقش‌ها می‌توانند آن‌ها و لاگ ارسالشان را ببینند. [نقش‌ها و دسترسی‌ها](/docs/trace/error-dashboard#roles) را ببینید.

توکن ربات بعد از ذخیره دیگر هرگز نمایش داده نمی‌شود: فرم آن را «تنظیم‌شده» نشان می‌دهد. دست نزنید تا توکن ذخیره‌شده بماند، یا **جایگزینی** را بزنید تا توکن تازه‌ای وارد کنید.

اگر Chat ID را تغییر دهید، توکن ربات را هم دوباره وارد کنید؛ توکن ذخیره‌شده هرگز خودبه‌خود برای گفت‌وگوی دیگری استفاده نمی‌شود.

### قالب اعلان

پیام‌های Telegram از ابرووا تریس شامل این‌هاست:

- سرتیتر **🚨 New Error Detected**
- پیام خطا در یک بلوک monospace
- پروژه، محیط، تعداد رخدادها و زمان اولین دیده شدن
- ۵۰۰ کاراکتر اول stack trace
- لینک **View in Dashboard**

### عیب‌یابی

<TroubleshootItem title="ربات پیام نمی‌فرستد؟">
  <ul>
    <li>اول باید با ربات گفت‌وگو را شروع کرده باشید</li>
    <li>مطمئن شوید Bot Token درست است</li>
    <li>مطمئن شوید Chat ID دقیق است</li>
    <li>در گروه‌ها، مطمئن شوید ربات عضو گروه است</li>
    <li>لاگ ارسال یکپارچگی را ببینید: timeout یا خطای اتصال یعنی Telegram در دسترس نبوده است</li>
  </ul>
</TroubleshootItem>

<TroubleshootItem title="Chat ID در getUpdates دیده نمی‌شود؟">
  <ul>
    <li>بعد از ساختن ربات به آن پیام بفرستید</li>
    <li>چند ثانیه صبر کنید و URL را دوباره بارگذاری کنید</li>
    <li>در گروه‌ها، بعد از اضافه کردن ربات پیام بفرستید</li>
  </ul>
</TroubleshootItem>

<TroubleshootItem title='خطای «Unauthorized»؟'>
  <ul>
    <li>ممکن است Bot Token نامعتبر یا باطل شده باشد</li>
    <li>با دستور <code>/revoke</code> در BotFather توکن تازه بسازید</li>
    <li>یکپارچگی را در ابرووا تریس ← یکپارچه‌سازی‌ها ویرایش کنید و روی توکن ربات «جایگزینی» را بزنید</li>
  </ul>
</TroubleshootItem>

- Discord: https://abrova.ir/docs/trace/discord

اعلان‌های لحظه‌ای خطا را با webhook در کانال‌های Discord بگیرید. پیام‌های embed غنی با جزئیات خطا، اطلاعات محیط و لینک مستقیم به داشبورد.

<Callout kind="note" title="چه چیزهایی لازم دارید">
  <ul>
    <li>یک سرور Discord که در آن دسترسی admin دارید</li>
    <li>یک کانال برای اعلان‌های خطا</li>
    <li>حدود ۵ دقیقه برای راه‌اندازی</li>
  </ul>
</Callout>

<Callout kind="warn" title="دسترسی به Discord از ایران">
  Discord سرویسی بیرون از ایران است و ممکن است از برخی شبکه‌های داخل ایران در دسترس نباشد. برای راه‌اندازی و خواندن هشدارها به اتصالی نیاز دارید که به Discord برسد، و پیام‌ها فقط وقتی می‌رسند که discord.com پاسخ دهد؛ ارسال‌های ناموفق در لاگ ارسال یکپارچگی نمایش داده می‌شوند. اگر این برای تیم شما مشکل است، به‌جای آن یا در کنارش از یکپارچگی [ایمیل](/docs/trace/email) یا [Webhook](/docs/trace/webhooks) استفاده کنید.
</Callout>

این‌که پروژه‌ی شما از کدام کانال‌ها می‌تواند استفاده کند، در صفحه‌ی **ابرووا تریس ← یکپارچه‌سازی‌ها** در کنسول ابرووا نمایش داده می‌شود.

<H2 id="create-a-discord-webhook" step={1}>ساختن webhook در Discord</H2>

1. سرور Discord خود را باز کنید و به کانال مورد نظر بروید
2. روی کانال راست‌کلیک کنید ← **Edit Channel**
3. به زبانه‌ی **Integrations** بروید
4. روی **«Create Webhook»** یا **«New Webhook»** کلیک کنید
5. در صورت تمایل نام webhook را عوض کنید (مثلاً **«AbrovaTrace»**)؛ در هر حال پیام‌ها با نام و آواتار AbrovaTrace فرستاده می‌شوند
6. روی **«Copy Webhook URL»** کلیک کنید
7. روی **«Save Changes»** کلیک کنید

<H2 id="configure-in-abrovatrace" step={2}>پیکربندی در ابرووا تریس</H2>

1. در کنسول ابرووا، **ابرووا تریس ← یکپارچه‌سازی‌ها** را باز کنید (یکپارچگی‌ها متعلق به پروژه‌ی انتخاب‌شده‌اند)
2. روی **«افزودن یکپارچه‌سازی»** کلیک کنید و **Discord** را انتخاب کنید (یا روی کارت Discord **«اتصال»** را بزنید)
3. یک **نام** وارد کنید و فیلدهای پیکربندی را پر کنید
4. روی **«ذخیرهٔ کانال»** کلیک کنید، یا **«ذخیره و ارسال تست»** را بزنید تا ذخیره و بررسی شود

<ConfigTable rows={[
  ['Name', 'string', 'بله', 'نامی آشنا برای شناسایی (مثلاً #errors)'],
  ['Webhook URL', 'string', 'بله', 'URL مربوط به webhook در Discord. باید روی discord.com باشد (https://discord.com/api/webhooks/...)'],
]} />

#### بعد از ذخیره

مدیریت یکپارچگی‌ها (افزودن، ویرایش، روشن و خاموش کردن، حذف، تست) نقش **admin** یا **owner** می‌خواهد؛ همه‌ی نقش‌ها می‌توانند آن‌ها و لاگ ارسالشان را ببینند. [نقش‌ها و دسترسی‌ها](/docs/trace/error-dashboard#roles) را ببینید.

URL مربوط به webhook بعد از ذخیره دیگر هرگز نمایش داده نمی‌شود: فرم آن را «تنظیم‌شده» نشان می‌دهد و فقط scheme و host آن دیده می‌شود. دست نزنید تا URL ذخیره‌شده بماند، یا **جایگزینی** را بزنید تا URL تازه‌ای جای‌گذاری کنید. فقط آدرس‌های webhook خود Discord پذیرفته می‌شوند (`discord.com`، و `discordapp.com`، `ptb.discord.com` یا `canary.discord.com`).

### نمونه‌های پیکربندی

- **هشدارهای production**: نام `#prod-errors`، با webhook در کانال production
- **اعلان‌های توسعه**: نام `#dev-errors`، با webhook در کانال توسعه

پیام‌ها با نام کاربری **Abrova Trace** فرستاده می‌شوند.

### قالب اعلان

پیام‌های Discord از ابرووا تریس شامل این‌هاست:

- عنوان **🚨 New Error: &lt;error message&gt;** (اولین باری که خطا دیده می‌شود فرستاده می‌شود)
- پروژه، محیط و تعداد رخدادها، با زمان اولین دیده شدن به‌عنوان timestamp مربوط به embed
- لینکی روی عنوان که به خطا برمی‌گردد

تشخیص جهش هم اینجا پیام می‌گذارد، و قوانین هشدار و مانیتورهای cron هم وقتی این کانال را برایشان انتخاب کنید.

### بهترین روش‌ها

<BestPracticeList items={[
  ['کانال‌های اختصاصی بسازید', 'برای خطاهای prod/dev/staging کانال‌های جداگانه داشته باشید'],
  ['از دسترسی‌های کانال استفاده کنید', 'با دسترسی‌های Discord کنترل کنید چه کسی اعلان‌های خطا را می‌بیند'],
  ['پیام راه‌اندازی را pin کنید', 'پیام راه‌اندازی را در کانال pin کنید تا راحت در دسترس باشد'],
  ['نام‌های گویا بگذارید', 'هر یکپارچگی را به نام کانالش نام‌گذاری کنید، مثلاً «#prod-errors»'],
]} />

### عیب‌یابی

<TroubleshootItem title="پیامی نمی‌رسد؟">
  <ul>
    <li>مطمئن شوید URL مربوط به webhook درست و کامل است</li>
    <li>مطمئن شوید webhook در Discord حذف نشده است</li>
    <li>مطمئن شوید یکپارچگی در ابرووا تریس ← یکپارچه‌سازی‌ها روشن است</li>
    <li>یکپارچگی را با دکمه‌ی «ارسال تست» تست کنید</li>
    <li>دسترسی‌های سرور و کانال را بررسی کنید</li>
    <li>لاگ ارسال یکپارچگی را ببینید: timeout یا خطای اتصال یعنی Discord در دسترس نبوده است</li>
  </ul>
</TroubleshootItem>

<TroubleshootItem title="webhook حذف شده یا نامعتبر است؟">
  <ul>
    <li>در تنظیمات کانال Discord یک webhook تازه بسازید</li>
    <li>یکپارچگی را در ابرووا تریس ← یکپارچه‌سازی‌ها ویرایش کنید و روی URL مربوط به webhook «جایگزینی» را بزنید</li>
    <li>URLهای webhook را عمومی به اشتراک نگذارید</li>
  </ul>
</TroubleshootItem>

<TroubleshootItem title="پیام‌ها به کانال اشتباه می‌روند؟">
  <ul>
    <li>هر webhook به یک کانال مشخص وصل است</li>
    <li>در کانال درست یک webhook تازه بسازید</li>
    <li>یکپارچگی را در ابرووا تریس ← یکپارچه‌سازی‌ها ویرایش کنید و روی URL مربوط به webhook «جایگزینی» را بزنید</li>
  </ul>
</TroubleshootItem>

<TroubleshootItem title="مشکل محدودیت نرخ (rate limit)؟">
  <ul>
    <li>Discord برای webhookها محدودیت نرخ دارد</li>
    <li>از گروه‌بندی خطاها برای کم کردن تکرار استفاده کنید</li>
    <li>با قوانین نادیده‌گیری، خطاهای پرسروصدا را پیش از ارسال اعلان حذف کنید</li>
  </ul>
</TroubleshootItem>

- GitHub issues: https://abrova.ir/docs/trace/github

از خطاهای ابرووا تریس خودکار issue در GitHub بسازید. هر خطای جدید یک issue با جزئیات خطا و stack trace کامل می‌سازد.

<Callout kind="note" title="چه چیزهایی لازم دارید">
  <ul>
    <li>یک حساب GitHub</li>
    <li>یک مخزن GitHub برای پیگیری issueها</li>
    <li>یک GitHub Personal Access Token</li>
  </ul>
</Callout>

<Callout kind="warn" title="دسترسی به GitHub از ایران">
  GitHub سرویسی بیرون از ایران است و ممکن است از برخی شبکه‌های داخل ایران در دسترس نباشد. برای راه‌اندازی و خواندن هشدارها به اتصالی نیاز دارید که به GitHub برسد، و issueها فقط وقتی ساخته می‌شوند که github.com و api.github.com پاسخ دهند؛ ارسال‌های ناموفق در لاگ ارسال یکپارچگی نمایش داده می‌شوند. اگر این برای تیم شما مشکل است، به‌جای آن یا در کنارش از یکپارچگی [ایمیل](/docs/trace/email) یا [Webhook](/docs/trace/webhooks) استفاده کنید.
</Callout>

این‌که پروژه‌ی شما از کدام کانال‌ها می‌تواند استفاده کند، در صفحه‌ی **ابرووا تریس ← یکپارچه‌سازی‌ها** در کنسول ابرووا نمایش داده می‌شود.

<H2 id="create-a-github-personal-access-token" step={1}>ساختن GitHub Personal Access Token</H2>

1. به **GitHub → Settings → Developer settings → Personal access tokens → Tokens (classic)** بروید
2. روی **«Generate new token»** ← **«Generate new token (classic)»** کلیک کنید
3. توکن را پیکربندی کنید:
   - **Note:** «AbrovaTrace Integration»
   - **Expiration:** ۹۰ روز توصیه می‌شود
   - **Scopes:** گزینه‌ی `repo` را انتخاب کنید (کنترل کامل مخزن‌های خصوصی)
4. روی **«Generate token»** کلیک کنید و توکن را همان لحظه کپی کنید

<Callout kind="note" title="مهم">بعد از ترک صفحه دیگر نمی‌توانید توکن را ببینید. آن را جای امنی ذخیره کنید.</Callout>

<H2 id="configure-in-abrovatrace" step={2}>پیکربندی در ابرووا تریس</H2>

1. در کنسول ابرووا، **ابرووا تریس ← یکپارچه‌سازی‌ها** را باز کنید (یکپارچگی‌ها متعلق به پروژه‌ی انتخاب‌شده‌اند)
2. روی **«افزودن یکپارچه‌سازی»** کلیک کنید و **GitHub** را انتخاب کنید (یا روی کارت GitHub **«اتصال»** را بزنید)
3. یک **نام** وارد کنید و فیلدهای پیکربندی را پر کنید
4. روی **«ذخیرهٔ کانال»** کلیک کنید، یا **«ذخیره و ارسال تست»** را بزنید تا ذخیره و بررسی شود

<ConfigTable rows={[
  ['Name', 'string', 'بله', 'نامی آشنا (مثلاً «acme/web issues»)'],
  ['Personal access token', 'string', 'بله', 'توکنی که با ghp_ شروع می‌شود، از مرحله‌ی ۱؛ باید اجازه‌ی ساختن issue داشته باشد'],
  ['Repository owner', 'string', 'بله', 'کاربر یا سازمان (مثلاً myorg)'],
  ['Repository name', 'string', 'بله', 'مخزن (مثلاً my-app)'],
]} />

#### بعد از ذخیره

مدیریت یکپارچگی‌ها (افزودن، ویرایش، روشن و خاموش کردن، حذف، تست) نقش **admin** یا **owner** می‌خواهد؛ همه‌ی نقش‌ها می‌توانند آن‌ها و لاگ ارسالشان را ببینند. [نقش‌ها و دسترسی‌ها](/docs/trace/error-dashboard#roles) را ببینید.

توکن دسترسی شخصی بعد از ذخیره دیگر هرگز نمایش داده نمی‌شود: فرم آن را «تنظیم‌شده» نشان می‌دهد. دست نزنید تا توکن ذخیره‌شده بماند، یا **جایگزینی** را بزنید تا توکن تازه‌ای وارد کنید.

اگر صاحب یا نام مخزن را تغییر دهید، توکن را هم دوباره وارد کنید؛ توکن ذخیره‌شده هرگز خودبه‌خود برای مخزن دیگری استفاده نمی‌شود.

### چه چیزی ساخته می‌شود

وقتی خطای جدیدی شناسایی می‌شود (اولین باری که دیده می‌شود)، ابرووا تریس خودکار یک issue در GitHub با این محتوا می‌سازد:

- **عنوان**: `[AbrovaTrace] <error message>` (مثلاً `[AbrovaTrace] TypeError: Cannot read property 'map' of undefined`)
- **جزئیات خطا**: پروژه، محیط، زمان اولین دیده شدن و تعداد رخدادها
- **Stack trace**: stack کامل از رویداد خطا
- **اطلاعات بیشتر**: URL صفحه و user agent

تشخیص جهش هم اینجا issue باز می‌کند، و قوانین هشداری که به این کانال وصل می‌کنید، وقتی فعال شوند issueی با عنوان `[AbrovaTrace Alert] <rule name>` و برچسب `abrovatrace-alert` باز می‌کنند.

### بهترین روش‌ها

<BestPracticeList items={[
  ['از مخزن اختصاصی یا فیلتر استفاده کنید', 'عنوان issueها با «[AbrovaTrace] …» شروع می‌شود، پس با فیلتر جست‌وجو راحت پیدا می‌شوند'],
  ['برای انقضای توکن یادآور بگذارید', 'پیش از منقضی شدن توکن یک یادآور در تقویم بگذارید'],
  ['برای هر مخزن یکپارچگی جدا', 'برای هر مخزنی که می‌خواهید issueها در آن ساخته شوند یک یکپارچگی GitHub اضافه کنید'],
]} />

### عیب‌یابی

<TroubleshootItem title="issueها ساخته نمی‌شوند؟">
  <ul>
    <li>مطمئن شوید توکن دسترسی شخصی درست است</li>
    <li>مطمئن شوید توکن دسترسی «repo» را دارد</li>
    <li>مطمئن شوید صاحب و نام مخزن درست‌اند</li>
    <li>مطمئن شوید مخزن وجود دارد و به آن دسترسی دارید</li>
    <li>یکپارچگی را با دکمه‌ی «ارسال تست» تست کنید</li>
    <li>لاگ ارسال یکپارچگی را ببینید: timeout یا خطای اتصال یعنی GitHub در دسترس نبوده است</li>
  </ul>
</TroubleshootItem>

<TroubleshootItem title="خطای احراز هویت؟">
  <ul>
    <li>ممکن است توکن منقضی شده باشد؛ توکن تازه بسازید، سپس یکپارچگی را ویرایش کنید و روی توکن «جایگزینی» را بزنید</li>
    <li>توکن دسترسی کافی ندارد</li>
    <li>ممکن است به مخزن دسترسی نداشته باشید</li>
    <li>توکن را با دسترسی «repo» دوباره بسازید</li>
  </ul>
</TroubleshootItem>

<TroubleshootItem title="مخزن اشتباه؟">
  <ul>
    <li>صاحب و نام مخزن را در فیلدهای جداگانه وارد کنید</li>
    <li>«github.com» یا «https://» را ننویسید</li>
    <li>درست: صاحب <code>myorg</code>، نام <code>abrova-trace</code></li>
    <li>نادرست: <code>github.com/myorg/abrova-trace</code></li>
  </ul>
</TroubleshootItem>

- Slack: https://abrova.ir/docs/trace/slack

اعلان‌های لحظه‌ای خطا را در workspace مربوط به Slack بگیرید. یاد بگیرید چطور webhook بسازید، آن را وصل کنید و اعلان‌ها چه شکلی دارند.

<Callout kind="note" title="چه چیزهایی یاد می‌گیرید">
  <ul>
    <li>ساختن incoming webhook در Slack</li>
    <li>پیکربندی اعلان‌های Slack در ابرووا تریس</li>
    <li>محتوای اعلان‌ها</li>
    <li>تست یکپارچگی Slack</li>
  </ul>
</Callout>

<Callout kind="warn" title="دسترسی به Slack از ایران">
  Slack سرویسی بیرون از ایران است و ممکن است از برخی شبکه‌های داخل ایران در دسترس نباشد. برای راه‌اندازی و خواندن هشدارها به اتصالی نیاز دارید که به Slack برسد، و پیام‌ها فقط وقتی می‌رسند که hooks.slack.com پاسخ دهد؛ ارسال‌های ناموفق در لاگ ارسال یکپارچگی نمایش داده می‌شوند. اگر این برای تیم شما مشکل است، به‌جای آن یا در کنارش از یکپارچگی [ایمیل](/docs/trace/email) یا [Webhook](/docs/trace/webhooks) استفاده کنید.
</Callout>

این‌که پروژه‌ی شما از کدام کانال‌ها می‌تواند استفاده کند، در صفحه‌ی **ابرووا تریس ← یکپارچه‌سازی‌ها** در کنسول ابرووا نمایش داده می‌شود.

<H2 id="create-a-slack-webhook" step={1}>ساختن webhook در Slack</H2>

1. به **api.slack.com/apps** بروید
2. روی **«Create New App»** ← **«From scratch»** کلیک کنید
3. نام اپ را **«AbrovaTrace»** بگذارید و workspace خود را انتخاب کنید
4. در نوار کناری به **«Incoming Webhooks»** بروید
5. **«Activate Incoming Webhooks»** را روشن کنید
6. روی **«Add New Webhook to Workspace»** کلیک کنید
7. کانالی را که می‌خواهید اعلان‌ها به آن بروند انتخاب کنید
8. URL مربوط به webhook را کپی کنید

URL مربوط به webhook شما این شکلی است: `https://hooks.slack.com/services/...`

<H2 id="configure-in-abrovatrace" step={2}>پیکربندی در ابرووا تریس</H2>

1. در کنسول ابرووا، **ابرووا تریس ← یکپارچه‌سازی‌ها** را باز کنید (یکپارچگی‌ها متعلق به پروژه‌ی انتخاب‌شده‌اند)
2. روی **«افزودن یکپارچه‌سازی»** کلیک کنید و **Slack** را انتخاب کنید (یا روی کارت Slack **«اتصال»** را بزنید)
3. یک **نام** وارد کنید و URL مربوط به webhook را جای‌گذاری کنید
4. روی **«ذخیره و ارسال تست»** کلیک کنید تا ذخیره و بررسی شود (یا **«ذخیرهٔ کانال»**)

<ConfigTable rows={[
  ['Name', 'string', 'بله', 'نامی آشنا (مثلاً #alerts)'],
  ['Incoming webhook URL', 'string', 'بله', 'URL کامل webhook در Slack از مرحله‌ی ۱. باید روی hooks.slack.com باشد (https://hooks.slack.com/...)'],
]} />

#### بعد از ذخیره

مدیریت یکپارچگی‌ها (افزودن، ویرایش، روشن و خاموش کردن، حذف، تست) نقش **admin** یا **owner** می‌خواهد؛ همه‌ی نقش‌ها می‌توانند آن‌ها و لاگ ارسالشان را ببینند. [نقش‌ها و دسترسی‌ها](/docs/trace/error-dashboard#roles) را ببینید.

URL مربوط به webhook بعد از ذخیره دیگر هرگز نمایش داده نمی‌شود: فرم آن را «تنظیم‌شده» نشان می‌دهد و فقط `https://hooks.slack.com/…` دیده می‌شود. دست نزنید تا URL ذخیره‌شده بماند، یا **جایگزینی** را بزنید تا URL تازه‌ای جای‌گذاری کنید. فقط آدرس‌های webhook خود Slack (`https://hooks.slack.com/...`) پذیرفته می‌شوند.

### قالب اعلان

پیام‌های Slack از ابرووا تریس شامل این‌هاست:

- **سرتیتر**: نام کاربری ربات AbrovaTrace همراه با آیکون ⚠️
- **عنوان هشدار**: `New Error: <error message>`، با لینک به خطا
- **متادیتا**: پروژه، محیط، زمان اولین دیده شدن و تعداد رخدادها

پیام‌های خطای جدید اولین باری که خطا دیده می‌شود فرستاده می‌شوند. تشخیص جهش هم اینجا پیام می‌گذارد، و قوانین هشدار و مانیتورهای cron هم وقتی این کانال را برایشان انتخاب کنید.

### بهترین روش‌ها

<BestPracticeList items={[
  ['کانال‌های اختصاصی بسازید', 'برای محیط‌های مختلف کانال‌های جداگانه داشته باشید (#prod-errors، #dev-errors)'],
  ['نویز را با قوانین نادیده‌گیری کم کنید', 'خطاهای پرسروصدای شناخته‌شده را حذف کنید تا هرگز اعلان ندهند'],
  ['از پاسخ در thread استفاده کنید', 'بحث درباره‌ی خطاها را در threadهای Slack مرتب نگه دارید'],
]} />

### عیب‌یابی

<TroubleshootItem title="اعلانی نمی‌رسد؟">
  <ul>
    <li>مطمئن شوید URL مربوط به webhook درست است؛ باید با https://hooks.slack.com/ شروع شود</li>
    <li>مطمئن شوید یکپارچگی در ابرووا تریس ← یکپارچه‌سازی‌ها روشن است</li>
    <li>مطمئن شوید اپ Slack در workspace شما نصب است</li>
    <li>دوباره دکمه‌ی «ارسال تست» را امتحان کنید</li>
    <li>لاگ ارسال یکپارچگی را ببینید: timeout یا خطای اتصال یعنی Slack در دسترس نبوده است</li>
  </ul>
</TroubleshootItem>

<TroubleshootItem title="پیام‌ها به کانال اشتباه می‌روند؟">
  <ul>
    <li>URL مربوط به webhook کانال را تعیین می‌کند</li>
    <li>برای کانال درست یک webhook تازه بسازید</li>
    <li>یکپارچگی را در ابرووا تریس ← یکپارچه‌سازی‌ها ویرایش کنید و روی URL مربوط به webhook «جایگزینی» را بزنید</li>
  </ul>
</TroubleshootItem>

<TroubleshootItem title="به محدودیت نرخ می‌خورید؟">
  <ul>
    <li>Slack برای incoming webhookها محدودیت نرخ دارد</li>
    <li>از گروه‌بندی خطاها برای کم کردن تعداد اعلان‌ها استفاده کنید</li>
    <li>با قوانین نادیده‌گیری، خطاهای پرسروصدا را حذف کنید</li>
  </ul>
</TroubleshootItem>

- معرفی و راه‌اندازی: https://abrova.ir/docs/trace/self-hosted

<Callout kind="soon" title="به‌زودی">
  نسخه‌ی self-hosted ابرووا تریس هنوز در دسترس نیست. این صفحه توضیح می‌دهد چطور کار خواهد کرد. برای این‌که هنگام انتشار باخبر شوید، یا برای گفت‌وگو درباره‌ی اجرای ابرووا تریس روی سرورهای خودتان، [با ما تماس بگیرید](/contact).
</Callout>

### نسخه‌ی Self-Hosted: معرفی و راه‌اندازی

ابرووا تریس را روی زیرساخت خودتان اجرا کنید. همان امکانات نسخه‌ی ابری، و کنترل داده‌ها دست شماست.

<Callout kind="note" title="همان SDKها، همان داشبورد">
  نسخه‌ی self-hosted دقیقاً از همان SDKها و داشبورد نسخه‌ی ابری استفاده می‌کند. تنها تفاوت جای ذخیره‌ی داده‌هاست.
</Callout>

<H3 id="what-you-get">چه چیزی می‌گیرید</H3>

- ردیابی خطا، لاگ‌ها، APM، breadcrumbها و تشخیص کرش
- داشبوردی با همه‌ی امکانات نسخه‌ی ابری
- ۶ SDK: Flutter، Next.js، Node.js، Android، iOS، Laravel
- source map و symbolication با dSYM
- قوانین هشدار، مانیتورهای cron و یکپارچگی‌ها (ایمیل، Webhook و غیره)
- داده‌ها روی سرور شما می‌مانند

<H2 id="prerequisites" step={1}>پیش‌نیازها</H2>

- Docker و Docker Compose
- ۵۱۲ مگابایت RAM (کنسول) به‌علاوه‌ی ۱ گیگابایت RAM (تریس)
- روی یک VPS کوچک یا سیستم محلی کار می‌کند

<H2 id="install-Abrova-console" step={2}>نصب کنسول ابرووا</H2>

کنسول داشبورد مشترک همه‌ی سرویس‌های self-hosted ابرووا است. به‌صورت یک stack در Docker Compose اجرا می‌شود: داشبورد کنسول، API آن و دیتابیس خودش، همه روی سرور شما.

1. فایل‌های راه‌اندازی self-hosted را دانلود کنید (هنگام انتشار self-hosted منتشر می‌شوند). این فایل‌ها یک `docker-compose.yml` آماده برای کنسول دارند.
2. کنار آن یک فایل `.env` بسازید و secretهای تصادفی و رمز دیتابیس خودتان را تنظیم کنید؛ فایل‌های راه‌اندازی همه‌ی متغیرها را فهرست کرده‌اند.
3. اجرایش کنید:

```bash
docker compose up -d
```

`http://localhost:3000` را باز کنید و حساب خود را ثبت کنید (اولین کاربر صاحب سرور می‌شود).

<H2 id="install-abrovatrace" step={3}>نصب ابرووا تریس</H2>

ابرووا تریس به‌صورت stack دوم Compose اجرا می‌شود: Trace API با دیتابیس و cache خودش.

1. از `docker-compose.trace.yml` در همان فایل‌های راه‌اندازی استفاده کنید.
2. یک فایل `.env.trace` بسازید: secretهای تصادفی و رمز دیتابیس خودتان، آدرس Console API (مثلاً `http://host.docker.internal:3004`) و آدرسی که داشبورد روی آن باز می‌شود (مثلاً `http://localhost:3000`).
3. اجرایش کنید:

```bash
docker compose -f docker-compose.trace.yml --env-file .env.trace up -d
```

به کنسول (`http://localhost:3000`) بروید و در نوار کناری روی **Abrova Trace** کلیک کنید.

<H2 id="connect-your-sdk" step={4}>وصل کردن SDK</H2>

با افزودن `apiUrl` هر SDK را به Trace API روی سرور خودتان وصل کنید. برای هر ۶ SDK صفحه‌ی [پیکربندی SDK](/docs/trace/self-hosted-sdk) را ببینید.

<H3 id="ports">پورت‌ها</H3>

stackها روی سرور شما روی این پورت‌ها گوش می‌دهند:

- **3000**: داشبورد کنسول
- **3004**: Console Auth API
- **3001**: Trace API ابرووا

<H3 id="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">لایسنس</H3>

self-hosting با یک سطح رایگان شروع می‌شود که کلید لایسنس لازم ندارد. [لایسنس Self-Hosted](/docs/trace/licensing) را ببینید.

- پیکربندی SDK: https://abrova.ir/docs/trace/self-hosted-sdk

<Callout kind="soon" title="به‌زودی">
  نسخه‌ی self-hosted ابرووا تریس هنوز در دسترس نیست. این صفحه نشان می‌دهد SDKها چطور به سرور خودتان وصل خواهند شد. برای سرویس ابری ابرووا `apiUrl` را نگذارید؛ SDKها به‌طور پیش‌فرض از `https://trace.abrova.ir` استفاده می‌کنند. سؤالی دارید؟ [با ما تماس بگیرید](/contact).
</Callout>

### پیکربندی SDK برای Self-Hosted

هر ۶ SDK با نسخه‌ی self-hosted کار می‌کنند. فقط `apiUrl` را به آدرس سرور خودتان اضافه کنید. بقیه‌ی چیزها همان می‌ماند.

### 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

این را به `.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">نکته‌ها</H3>

- به‌جای `your-server:3001` آدرس IP یا دامنه‌ی واقعی سرور خود را بگذارید
- برای توسعه‌ی محلی از `http://localhost:3001` استفاده کنید
- برای production از HTTPS پشت یک reverse proxy (nginx، Caddy) استفاده کنید
- کلید API را از داشبورد کنسول self-hosted بگیرید
- کلید اپ (`ab_live_...`) داخل اپ‌های موبایل و وب قرار می‌گیرد؛ کلید سرور (`ab_srv_...`) فقط روی سرورهای شما. [کلید سرور و routeهای سرور](/docs/trace/server-secret) را ببینید
- همه‌ی امکانات (breadcrumbها، APM، لاگ‌ها، تشخیص کرش) دقیقاً مثل نسخه‌ی ابری کار می‌کنند

- مجوز: https://abrova.ir/docs/trace/licensing

<Callout kind="soon" title="به‌زودی">
  نسخه‌ی self-hosted ابرووا تریس هنوز در دسترس نیست و قیمت لایسنس‌ها هم تعیین نشده است. این صفحه توضیح می‌دهد لایسنس چطور کار خواهد کرد. برای گفت‌وگو درباره‌ی لایسنس برای شرکت خود، [با ما تماس بگیرید](/contact).
</Callout>

### لایسنس

نسخه‌ی self-hosted از همان ابتدا با یک سطح رایگان کار می‌کند. کلید لایسنس ابرووا سقف‌ها را بالا می‌برد و امکانات بزرگ‌تر را فعال می‌کند.

<Callout kind="note" title="سطح رایگان لایسنس لازم ندارد">
  فقط کانتینرهای Docker را اجرا کنید و ردیابی خطا را شروع کنید. بدون ثبت‌نام، بدون کلید لایسنس، بدون پرداخت.
</Callout>

<H3 id="plan-comparison">لایسنس چه چیزی را تغییر می‌دهد</H3>

| امکان                  | سطح رایگان | با لایسنس |
|------------------------|-----------|----------------|
| پروژه‌ها               | ۱         | بیشتر، طبق لایسنس شما |
| مشکل جدید در ماه       | ۵۰        | بیشتر، طبق لایسنس شما |
| اعضای تیم              | ۲         | بیشتر، طبق لایسنس شما |
| ردیابی خطا و لاگ‌ها    | بله       | بله |
| APM و Web Vitals       | خیر       | بله |
| source map / dSYM      | خیر       | بله |
| قوانین هشدار سفارشی    | ۱         | بیشتر، طبق لایسنس شما |
| مانیتورهای cron        | ۱         | بیشتر، طبق لایسنس شما |
| یکپارچگی‌ها            | ایمیل     | کانال‌های بیشتر |
| تشخیص جهش              | خیر       | بله |

لایسنس‌ها به تومان پرداخت می‌شوند. برای قیمت و لایسنس شرکت خود [با ما تماس بگیرید](/contact).

### وقتی به سقف می‌رسید چه می‌شود

«مشکل جدید در ماه» در جدول بالا یعنی تعداد مشکل‌های جدید در هر ماه. هر خطا اولین باری که دیده می‌شود و مشکل جدیدی می‌سازد شمرده می‌شود. رویدادهای بعدی مشکلی که از قبل وجود دارد شمرده نمی‌شوند.

وقتی سقف ماهانه پر شود:

- **مشکل‌های جدید ذخیره نمی‌شوند** تا وقتی سقف در شروع ماه بعد تازه شود.
- **رویدادهای مشکل‌های موجود همچنان آن‌ها را به‌روز می‌کنند**؛ تعدادها و زمان آخرین دیده شدن به‌روز می‌مانند.
- **اپ‌های شما هیچ‌وقت مختل نمی‌شوند.** API همچنان پاسخ موفق (`200`) می‌دهد، با بدنه‌ای که می‌گوید رویداد ذخیره نشده، پس هیچ SDKی دوباره تلاش نمی‌کند، صف نمی‌کند یا خطا لاگ نمی‌کند:

```json
{
  "status": "dropped",
  "code": "plan_limit_reached",
  "metric": "errors_monthly",
  "limit": 50,
  "used": 50,
  "resets_at": "2026-11-01T00:00:00.000Z"
}
```

(مقادیر `limit` و `used` نمونه‌اند و لایسنس شما را نشان می‌دهند.)

مانیتورینگ عملکرد به لایسنسی نیاز دارد که آن را شامل شود. بدون آن، spanها و Web Vitalsی که اپ‌های شما می‌فرستند به همان شکل پاسخ می‌گیرند (`200`، `"status": "dropped"`، `"code": "feature_not_in_plan"`) و ذخیره نمی‌شوند.

سقف پروژه، قانون هشدار و مانیتور cron هنگام ساختن اعمال می‌شود: ساختن بیش از سقف رد می‌شود.

### فعال کردن لایسنس

1. [با ما تماس بگیرید](/contact) تا کلید لایسنس شرکت خود را بگیرید
2. کنسول self-hosted خود را باز کنید ← Dashboard ← License
3. کلید را جای‌گذاری کنید و روی **Activate** کلیک کنید

### لایسنس چطور کار می‌کند

- کلید لایسنس به حساب شما گره خورده است، نه به یک سرور مشخص
- سرور شما هر ۲۴ ساعت لایسنس را بررسی می‌کند
- اگر سرور شما به ابرووا دسترسی نداشته باشد، از سقف‌هایی که ذخیره کرده استفاده می‌کند (مهلت ۷ روزه)
- وقتی لایسنس تمام شود، ۷ روز فرصت دارید و بعد سرور به سطح رایگان برمی‌گردد
- برگشت آرام است؛ داده‌های موجود حفظ می‌شوند و فقط سقف‌ها کم می‌شوند

### وقتی لایسنس تمام می‌شود چه می‌شود

- پروژه‌های بیشتر از سقف رایگان **فقط‌خواندنی** می‌شوند (جدیدترین‌ها فعال می‌مانند)
- اعضای بیشتر از سقف همچنان می‌توانند وارد شوند اما نمی‌توان آن‌ها را به پروژه‌ها اضافه کرد
- امکانات لایسنس‌دار (APM، source map) از کار می‌افتند؛ داده‌های عملکردی که اپ‌های شما می‌فرستند دیگر ذخیره نمی‌شوند
- همه‌ی داده‌های موجود حفظ می‌شوند؛ چیزی حذف نمی‌شود
- فعال کردن دوباره‌ی لایسنس فوراً همه‌ی امکانات را برمی‌گرداند

- راهبردهای مدیریت خطا: https://abrova.ir/docs/trace/error-handling

بهترین روش‌ها برای پیاده‌سازی ردیابی مؤثر خطا در اپلیکیشن شما. این ۱۰ راهکار را دنبال کنید تا بیشترین بهره را از ابرووا تریس ببرید.

### ۱. برای گرفتن همه‌ی خطاها از initWithZone() استفاده کنید

همه‌ی انواع خطا را می‌گیرد، از جمله exceptionهای Dart، خطاهای async، rejectهای Future و exceptionهای پلتفرم.

<div>
  <div>
    <p>✓ توصیه‌شده</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>✗ ساده (خطاهای async را از دست می‌دهد)</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>

### ۲. همیشه stack trace را بفرستید

وقتی exception را دستی ثبت می‌کنید، همیشه پارامتر stack trace را بدهید؛ این context برای debug حیاتی است.

```dart
try {
  await riskyOperation();
} catch (e, stackTrace) {
  await AbrovaTrace.captureException(
    e,
    stackTrace: stackTrace, // Always include this!
    message: 'Failed to complete operation',
  );
}
```

### ۳. context معنادار اضافه کنید

با پارامتر `extra` داده‌های مرتبط را بفرستید تا شرایط رخ دادن خطا را بفهمید.

```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="نکته">داده‌هایی بفرستید که به بازتولید خطا کمک کنند، اما از اطلاعات حساس مثل رمز عبور یا شماره‌ی کارت بانکی پرهیز کنید.</Callout>

### ۴. خطاها را با breadcrumbها همراه کنید

کارهای کاربر را تا لحظه‌ی خطا ثبت کنید تا یک خط زمانی کامل داشته باشید.

```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',
  );
}
```

### ۵. تشخیص کرش

ثبت کرش نیتیو روی iOS و Android خودکار است: SDK فلاتر SDKهای نیتیو ابرووا تریس را همراه خود دارد و آن‌ها را هنگام `init()` / `initWithZone()` راه‌اندازی می‌کند. کد اضافه‌ای لازم نیست.

نحوه‌ی کار: روی iOS، کتابخانه‌ی PLCrashReporter کرش‌های signal و Mach exception را روی دیسک ذخیره می‌کند؛ روی Android، یک uncaught exception handler به‌همراه `ApplicationExitInfo` (API 30+) کرش‌ها و ANRها را ثبت می‌کنند. گزارش در اجرای بعدی اپ فرستاده می‌شود و به‌صورت یک مشکل نمایش داده می‌شود. دسکتاپ و وب ثبت کرش نیتیو ندارند.

برای تشخیص کرش به `AbrovaTrace.close()` نیازی نیست. این متد لاگ‌های در انتظار را می‌فرستد و SDK را می‌بندد، پس فقط وقتی صدایش بزنید که اپ واقعاً در حال بسته شدن است.

### ۶. برای هر محیط پیکربندی جداگانه داشته باشید

```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());
    },
  );
}
```

### ۷. وضعیت خطاها را در داشبورد مدیریت کنید

- **باز:** خطاهای جدیدی که باید بررسی شوند
- **در حال بررسی:** خطاهایی که الان رویشان کار می‌کنید
- **حل‌شده:** خطاهای رفع‌شده (اگر دوباره رخ دادند، دوباره بازشان کنید)
- **نادیده‌گرفته:** مشکل‌های شناخته‌شده‌ای که تصمیم گرفته‌اید رفعشان نکنید
- **بایگانی‌شده:** خطاهای قدیمی که می‌خواهید نگه دارید اما در فهرست فعال نبینید

### ۸. خطاهای async را درست مدیریت کنید

```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',
      );
    },
  );
}
```

### ۹. بیش از حد گزارش نکنید

<div>
  <div>
    <strong>گزارش نکنید</strong>
    <ul>
      <li>خطاهای اعتبارسنجی مورد انتظار</li>
      <li>لغو کردن کاربر</li>
      <li>timeoutهای شبکه در حالت آفلاین</li>
      <li>رد شدن مجوزها</li>
    </ul>
  </div>
  <div>
    <strong>گزارش کنید</strong>
    <ul>
      <li>exceptionهای غیرمنتظره (null reference، index out of bounds)</li>
      <li>خطاهای API (خطای 500 سرور، پاسخ‌های بدشکل)</li>
      <li>خراب شدن داده‌ها</li>
      <li>کرش‌های نیتیو</li>
    </ul>
  </div>
</div>

### ۱۰. ردیابی خطا را تست کنید

پیش از deploy به production، مطمئن شوید ردیابی خطا کار می‌کند (رویداد در **ابرووا تریس ← مشکلات** دیده می‌شود):

```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'),
  );
}
```

SDK خطای یکسانی (با همان پیام و پلتفرم) را که ظرف یک دقیقه دوباره فرستاده شود کنار می‌گذارد، پس اگر چند بار پشت سر هم تست می‌کنید پیام را تغییر دهید.

### چک‌لیست خلاصه

<div>
  <ul>
    <li><span>✓</span><span>برای گرفتن همه‌ی خطاها از initWithZone() استفاده کنید</span></li>
    <li><span>✓</span><span>در ثبت دستی همیشه stack trace را بفرستید</span></li>
    <li><span>✓</span><span>با پارامتر extra context معنادار اضافه کنید</span></li>
    <li><span>✓</span><span>خطاها را با breadcrumbها همراه کنید تا مسیر کاربر را ببینید</span></li>
    <li><span>✓</span><span>روی build واقعی iOS/Android تست کنید تا کرش‌های نیتیو ثبت شوند</span></li>
    <li><span>✓</span><span>برای هر محیط پیکربندی جداگانه داشته باشید</span></li>
    <li><span>✓</span><span>وضعیت خطاها را در داشبورد به‌خوبی مدیریت کنید</span></li>
    <li><span>✓</span><span>خطاهای async را درست مدیریت کنید</span></li>
    <li><span>✓</span><span>فقط خطاهایی را گزارش کنید که قابل‌اقدام‌اند</span></li>
    <li><span>✓</span><span>پیش از production ردیابی خطا را تست کنید</span></li>
  </ul>
</div>


## Abrova Auth

- معرفی و شروع سریع: https://abrova.ir/docs/auth/quick-start

با Abrova Auth کاربران اپ شما بدون سرورِ خودتان وارد می‌شوند. اپ با کلید API عمومی‌اش SDK را صدا می‌زند؛ ابرووا اطلاعات ورود را بررسی می‌کند، نشست را نگه می‌دارد و یک **توکن کاربر** به اپ می‌دهد. این همان توکن کاربر ابرووا است: ابرووا تریس از همین امروز می‌تواند کاربرِ واردشده را به خطاها وصل کند، و Sync، Chat، Push، Storage و A/B Testing هم وقتی راه بیفتند همین توکن را می‌پذیرند؛ به این ترتیب قوانین امنیتی‌شان می‌دانند کاربر کیست (`auth.uid`) بی‌آنکه سرور شما چیزی بسازد.

<BestPracticeList columns={2} items={[
  ['بدون سرور', 'فقط کلید API عمومی. هیچ چیز محرمانه‌ای داخل اپ شما نمی‌رود'],
  ['شش روش ورود', 'ناشناس، ایمیل و رمز عبور، لینک یک‌بارمصرف، کد تلگرام، Apple و Google'],
  ['یک کاربر در همه‌جا', 'همان شناسه‌ی کاربر امروز در ابرووا تریس، و در محصولات دیگر ابرووا وقتی راه بیفتند'],
  ['مهمان‌های قابل ارتقا', 'ناشناس شروع کنید و بعداً رمز عبور، Apple یا Google را وصل کنید: همان شناسه‌ی کاربر'],
  ['مدیریت نشست', 'access token یک‌ساعته و refresh token چرخشی که SDK خودش تمدید می‌کند'],
  ['حذف حساب', 'با یک فراخوانی، همان‌طور که App Store برای اپ‌های دارای ورود می‌خواهد'],
]} />

<Callout kind="tip" title="کاربران داخل ایران">
ناشناس، ایمیل و رمز عبور، لینک یک‌بارمصرف و کد تلگرام را در اولویت بگذارید. ورود با Apple و Google به اتصال به Apple یا Google (و در Android به Google Play services) نیاز دارد که بعضی کاربران در ایران ندارند. آن‌ها را ارائه کنید، اما تنها راه ورود نباشند.
</Callout>

از دستیار هوش مصنوعی استفاده می‌کنید؟ این صفحه را با **Copy page for AI** به آن بدهید، یا همه‌ی مستندات را به‌صورت متن ساده از [/docs/llms.txt](/docs/llms.txt) بگیرید. [دستیارهای هوش مصنوعی](/docs/auth/ai-assistants) را ببینید.

### SDKهای موجود

همه‌ی پکیج‌ها از Abrova Center (`center.abrova.ir`) می‌آیند؛ SDK iOS با Swift Package Manager از GitHub نصب می‌شود.

| پلتفرم | پکیج | مستندات |
|---|---|---|
| Flutter | `abrova_auth` | [SDK Flutter](/docs/auth/flutter) |
| iOS | `AbrovaAuth` (Swift Package Manager) | [SDK iOS](/docs/auth/ios) |
| Android | `ir.abrova:abrova-auth` | [SDK Android](/docs/auth/android) |
| Web | `@abrova/auth-web` | [SDK Web](/docs/auth/web) |
| React Native | `@abrova/auth-react-native` | [SDK React Native](/docs/auth/react-native) |

هر پنج SDK همان فراخوانی‌ها را با نام‌گذاری مخصوص هر پلتفرم دارند. Abrova Auth برای اپ‌هاست: SDK سرور ندارد و نیازی هم به آن نیست.

<H2 id="turn-on-abrova-auth" step={1}>Abrova Auth را روشن کنید</H2>

1. در [کنسول ابرووا](https://console.abrova.ir)، **تنظیمات › محصولات** پروژه را باز کنید و **Abrova Auth** را روشن کنید.
2. **Abrova Auth › روش‌های ورود** را باز کنید و روش‌هایی را که اپ شما ارائه می‌دهد روشن کنید: ناشناس، ایمیل و رمز عبور، لینک یک‌بارمصرف، کد تلگرام، Apple و Google. همه‌ی روش‌ها تا وقتی روشنشان نکنید خاموش‌اند.
3. برای Apple و Google، شناسه‌های اپ را در همان صفحه اضافه کنید. برای لینک‌های ایمیلی، **آدرس‌های لینک** را در **Abrova Auth › تنظیمات** اضافه کنید. برای تلگرام، ربات‌تان را وصل کنید. صفحه‌ی هر روش می‌گوید به چه چیزی نیاز دارد.

<H2 id="keys" step={2}>کلیدها</H2>

Abrova Auth فقط به **کلید API عمومی** پروژه (`ab_live_...`) نیاز دارد که در **Abrova Auth › راه‌اندازی** نمایش داده می‌شود. قرار دادنش در اپ امن است: فقط پروژه را مشخص می‌کند و نمی‌تواند به جای هیچ کاربری عمل کند.

| اعتبارنامه | کجا نگه‌داری می‌شود | چه چیزی را ثابت می‌کند |
|---|---|---|
| **کلید API** (`ab_live_…`) | اپ شما، عمومی | کدام پروژه |
| **access token** (یک ساعت) | حافظه‌ی دستگاه | کدام کاربر وارد شده است |
| **refresh token** | حافظه‌ی امن دستگاه | اینکه این دستگاه اجازه دارد access token جدید بگیرد |

SDK هر دو توکن را برای شما نگه می‌دارد. هیچ‌وقت لازم نیست خودتان با refresh token کار کنید.

<Callout kind="warn" title="کلید سرور را هرگز در اپ نگذارید">
Abrova Auth از کلید سرور (`ab_srv_...`) استفاده نمی‌کند. آن را فقط روی سرور خودتان نگه دارید، بیرون از اپ‌ها و bundleهای مرورگر.
</Callout>

<H2 id="install-and-sign-in" step={3}>نصب و ورود</H2>

کوتاه‌ترین مسیر، کاربر ناشناس است: بدون صفحه، با یک فراخوانی. اول **ناشناس** را در کنسول روشن کنید.

پکیج را با رجیستری ابرووا به‌عنوان منبع اضافه کنید:

<Code file="pubspec.yaml" lang="YAML">{`dependencies:
  abrova_auth:
    hosted: https://center.abrova.ir/api/packages/abrova/pub
    version: ^0.1.1`}</Code>

بعد `flutter pub get` را اجرا کنید و وارد شوید:

```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_...
```

کاربر از اولین اجرا یک شناسه‌ی پایدار و یک توکن کاربر می‌گیرد. بعداً یک روش ورود را به همان کاربر وصل کنید — داده‌هایش مال خودش می‌ماند:

```dart
await auth.linkPassword(email: 'sara@example.com', password: password);
```

روی وب هم همین‌طور است، بعد از اینکه scope `@abrova` را در `.npmrc` به Abrova Center ارجاع دادید:

<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_...
```

صفحه‌ی هر پلتفرم راه‌اندازی کامل را دارد: [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}>استفاده از کاربر در محصولات دیگر ابرووا</H2>

امروز شناسه‌ی کاربر را به ابرووا تریس بدهید تا خطاها نشان دهند برای کدام کاربر رخ داده‌اند:

```dart
AbrovaTrace.setUserId(auth.currentUser!.id);
```

<Callout kind="soon">Abrova Sync، Chat، Push، Storage و A/B Testing به‌زودی می‌آیند. وقتی راه بیفتند، token provider مربوط به SDK Auth را مثل نمونه‌ی زیر به آن‌ها می‌دهید؛ فعلاً قابل استفاده نیستند.</Callout>

SDKهای دیگر ابرووا هر وقت به توکن نیاز داشته باشند آن را از token provider می‌خواهند، و SDK Auth پیش از انقضا تمدیدش می‌کند.

```dart
await AbrovaSync.init(AbrovaSyncConfig(
  apiKey: 'ab_live_your_api_key',
  tokenProvider: AbrovaAuth.instance.tokenProvider,
));
```

در این حالت قوانین امنیتی Sync کاربرِ واردشده را به‌صورت `auth.uid` می‌بینند. برای همه‌ی محصولات و پلتفرم‌ها [استفاده با محصولات دیگر ابرووا](/docs/auth/other-products) را ببینید.

### چطور کار می‌کند

<NumberedPipeline steps={[
  { title: 'اپ وارد می‌شود', body: 'SDK اطلاعات ورود (ایمیل و رمز عبور، یک کد، یا ID token مربوط به Apple یا Google) را همراه کلید عمومی شما می‌فرستد.' },
  { title: 'Abrova Auth آن را بررسی می‌کند', body: 'فقط در محدوده‌ی پروژه‌ی شما: روش‌هایش، شناسه‌های اپ Apple و Google آن، و کاربرانش.' },
  { title: 'اپ یک نشست می‌گیرد', body: 'یک access token یک‌ساعته (توکن کاربر ابرووا) و یک refresh token که SDK آن را امن ذخیره می‌کند.' },
  { title: 'محصولات ابرووا به آن اعتماد می‌کنند', body: 'هر محصول توکن را بررسی می‌کند و شناسه‌ی کاربر را از آن می‌خواند.' },
]} />

### قیمت‌گذاری

هزینه‌ی Abrova Auth بر اساس **کاربر فعال ماهانه** است: هر کاربری که در یک ماه تقویمی وارد شود یا نشستش را تمدید کند، در آن ماه یک بار شمرده می‌شود، هر چقدر هم از اپ استفاده کند. پلن وجود ندارد: برای مصرفِ بیشتر از سهمیه‌ی رایگان، از کیف پول تومانیِ پیش‌پرداخت هزینه می‌کنید.

| | رایگان در هر ماه | بیشتر از آن |
|---|---|---|
| کاربر فعال ماهانه | ۱٬۰۰۰ | ۱۰٬۰۰۰ تومان برای هر ۱٬۰۰۰، هزینه از کیف پول |
| کاربر ناشناس جدید در روز | ۲۰۰ | سقف روزانه |
| روش‌های ورود و گزارش فعالیت | همه شامل است | شامل است |

وقتی کیف پول خالی باشد و ۱٬۰۰۰ کاربر رایگان هم مصرف شده باشد، کاربرانِ جدیدِ آن ماه منتظر می‌مانند (`MAU_LIMIT`)؛ کاربرانی که قبلاً شمرده شده‌اند همچنان وارد می‌شوند. [کاربر فعال ماهانه و سقف‌ها](/docs/auth/mau) و [صفحه‌ی قیمت‌ها](/pricing) را ببینید. برای کاربران فعال روزانه و کاربران بازگشتی، [آمار استفاده](/docs/auth/usage-insights) را روشن کنید.

### اشتباه‌های رایج

- **روش ورود روشن نیست.** هر روش ورود خاموش شروع می‌شود. فراخوانیِ روشی که خاموش است با `METHOD_DISABLED` شکست می‌خورد. `getMethods()` را صدا بزنید و فقط دکمه‌هایی را نشان دهید که برمی‌گرداند.
- **Abrova Auth برای پروژه روشن نیست.** تا وقتی آن را در **تنظیمات › محصولات** روشن نکنید، فراخوانی‌ها با `PRODUCT_DISABLED` شکست می‌خورند.
- **فقط Apple یا Google ارائه شده است.** بعضی کاربران در ایران به Apple یا Google دسترسی ندارند. ناشناس، ایمیل، لینک یک‌بارمصرف یا کد تلگرام را هم ارائه کنید.
- **Apple یا Google می‌گوید ID token نامعتبر است.** bundle ID، Services ID یا Google client ID شما در کنسول نیست، یا nonce‌ای که به ارائه‌دهنده دادید SHA-256 همان nonce خامی نیست که به ابرووا دادید. [ورود با Apple](/docs/auth/apple) و [ورود با Google](/docs/auth/google) را ببینید.
- **لینک‌های ایمیلی رد می‌شوند.** `redirectUrl` باید با یکی از آدرس‌های لینک در **Abrova Auth › تنظیمات** شروع شود.
- **ورود دوباره در هر بار اجرا.** SDK نشست ذخیره‌شده را هنگام اجرا بازیابی می‌کند. پیش از ورود دوباره بررسی کنید کاربر فعلی وجود دارد یا نه، وگرنه هر اجرا یک کاربر ناشناس جدید می‌سازد.
- **استفاده از `currentUser` پیش از بازیابی نشست.** روی وب و React Native، بعد از reload منتظر `ready()` (یا اولین callback وضعیت ورود) بمانید.

- SDK فلاتر: https://abrova.ir/docs/auth/flutter

<BestPracticeList columns={2} items={[
  ['امن برای کلاینت', 'فقط از کلید API عمومی استفاده می‌کند. قرار دادنش در اپ امن است'],
  ['بازیابی هنگام شروع', 'initialize() نشست ذخیره‌شده را بدون درخواست شبکه بارگذاری می‌کند'],
  ['حافظه‌ی امن', 'refresh token در Keychain / حافظه‌ی متکی به Keystore'],
  ['token provider', 'tokenProvider و chatTokenProvider برای SDKهای دیگر ابرووا'],
  ['همه‌ی روش‌ها', 'ناشناس، Apple، Google، ایمیل، لینک یک‌بارمصرف، تلگرام'],
  ['ارتقای مهمان‌ها', 'linkApple، linkGoogle و linkPassword شناسه‌ی کاربر را حفظ می‌کنند'],
]} />

<Callout kind="note" title="SDK Flutter برای Abrova Auth نسخه‌ی v0.1.1">
این صفحه `abrova_auth` نسخه‌ی 0.1.1 را توضیح می‌دهد.
</Callout>

<Callout kind="note" title="پیش‌نیازها">
Flutter 3.13 یا بالاتر. Dart 3.0 یا بالاتر. برای نشست از `flutter_secure_storage` استفاده می‌کند.
</Callout>

از دستیار هوش مصنوعی استفاده می‌کنید؟ این صفحه را با **Copy page for AI** به آن بدهید، یا همه‌ی مستندات را به‌صورت متن ساده از [/docs/llms.txt](/docs/llms.txt) بگیرید. [دستیارهای هوش مصنوعی](/docs/auth/ai-assistants) را ببینید.

<H2 id="installation" step={1}>نصب</H2>

پکیج‌ها از Abrova Center می‌آیند، پس محدودیت‌های دسترسی به pub.dev مشکلی ایجاد نمی‌کند. پکیج را با رجیستری ابرووا به‌عنوان منبع `hosted` در `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>

سپس نصبش کنید:

```bash
flutter pub get
```

در کنسول ابرووا، **Abrova Auth** را برای پروژه (**تنظیمات › محصولات**) و روش‌های ورود دلخواه را (**Abrova Auth › روش‌های ورود**) روشن کنید.

<H2 id="initialization" step={2}>مقداردهی اولیه</H2>

`AbrovaAuth.initialize` را یک بار، پیش از `runApp`، با کلید API عمومی (`ab_live_...`) صدا بزنید. این تابع نشست ذخیره‌شده روی دستگاه را بدون درخواست شبکه بازیابی می‌کند، پس `currentUser` بلافاصله آماده است.

```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());
}
```

سپس هر جا خواستید از `AbrovaAuth.instance` استفاده کنید.

<ConfigTable headers={['گزینه', 'پیش‌فرض', 'توضیح']} rows={[
  ['apiKey', '-', 'کلید API عمومی شما (ab_live_...). هرگز کلید سرور نه.'],
  ['timeout', '۱۵ ثانیه', 'مهلت درخواست.'],
  ['refreshMargin', '۲ دقیقه', 'وقتی کمتر از این مقدار از اعتبار access token مانده، تمدیدش کن.'],
  ['storage', 'SecureAbrovaAuthStorage()', 'محل نگه‌داری نشست. MemoryAbrovaAuthStorage چیزی نگه نمی‌دارد (برای تست).'],
]} />

<H2 id="sign-in" step={3}>ورود</H2>

فقط روش‌هایی را نشان دهید که پروژه‌تان روشن کرده، و فقط وقتی کسی هنوز وارد نشده ورود را انجام دهید:

```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()` همان کاربر فعلی را برمی‌گرداند.

<H2 id="use-the-user-with-other-abrova-sdks" step={4}>استفاده از کاربر با SDKهای دیگر ابرووا</H2>

<Callout kind="soon">Abrova Sync، Chat، Push، Storage و A/B Testing به‌زودی می‌آیند. فراخوانی‌های زیر نشان می‌دهند کاربر Auth را چطور خواهند گرفت؛ امروز کاربر را با `AbrovaTrace.setUserId(auth.currentUser!.id)` به ابرووا تریس وصل کنید.</Callout>

token provider را بدهید. SDK دیگر هر وقت به توکن نیاز داشت آن را از provider می‌خواهد؛ Abrova Auth توکن را پیش از انقضا تمدید می‌کند و درخواست‌کننده‌های هم‌زمان در یک تمدید شریک می‌شوند.

```dart
await AbrovaSync.init(AbrovaSyncConfig(
  apiKey: 'ab_live_your_api_key',
  tokenProvider: AbrovaAuth.instance.tokenProvider, // null while signed out
));
```

Abrova Chat، `AbrovaAuth.instance.chatTokenProvider` را می‌گیرد (به جای برگرداندن null خطا می‌دهد) و `currentUser.id` را به‌عنوان شناسه‌ی کاربر. بعد از ورود یا خروج، متد refresh آن SDK را صدا بزنید، مثلاً `AbrovaSync.refreshUserToken()`. [استفاده با محصولات دیگر ابرووا](/docs/auth/other-products) را ببینید.

### روش‌های ورود

هر روش صفحه‌ی خودش را با راه‌اندازی کنسول دارد: [ناشناس](/docs/auth/anonymous)، [Apple](/docs/auth/apple)، [Google](/docs/auth/google)، [ایمیل و رمز عبور](/docs/auth/email-password)، [لینک یک‌بارمصرف](/docs/auth/magic-link)، [تلگرام](/docs/auth/telegram).

#### ایمیل و رمز عبور

```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');
```

لینک‌ها `redirectUrl` شما را با `?token=...` باز می‌کنند. این آدرس باید با یکی از آدرس‌های لینک در **Abrova Auth › تنظیمات** شروع شود.

#### لینک یک‌بارمصرف

```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']!);
```

#### تلگرام

```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 و Google

پلاگین بومی ارائه‌دهنده را با nonce **هش‌شده** اجرا کنید و nonce **خام** را به ابرووا بدهید:

```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);
```

اول bundle IDها و Google client IDهایتان را در کنسول اضافه کنید. هر nonce فقط یک بار کار می‌کند.

ورود با Google به اتصال به Google، و در Android به Google Play services هم، نیاز دارد؛ بعضی کاربران در ایران هیچ‌کدام را ندارند. ناشناس، ایمیل و رمز عبور، لینک یک‌بارمصرف و کد تلگرام بدون Google کار می‌کنند، پس دست‌کم یکی از آن‌ها را هم ارائه کنید. [ورود با Google](/docs/auth/google) را ببینید.

### ارتقای کاربر ناشناس

وصل کردن شناسه‌ی کاربر را حفظ می‌کند، پس داده‌های کاربر مال خودش می‌ماند:

```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.
}
```

[کاربران ناشناس و ارتقا](/docs/auth/upgrading) را ببینید.

### کاربر فعلی

```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={['فیلد', 'نوع', 'توضیح']} rows={[
  ['id', 'String', 'شناسه‌ی کاربر (ru_...)'],
  ['anonymous', 'bool', 'تا وقتی روشی وصل نشده true است'],
  ['emailVerified', 'bool', 'وقتی ایمیل ثابت شده باشد true است'],
  ['createdAt', 'DateTime?', 'زمان ساخت کاربر'],
  ['providers', 'List<String>', 'روش‌های وصل‌شده، مثلاً apple، password'],
]} />

### خروج و حذف حساب

```dart
await auth.signOut();           // this device; never fails
await auth.signOutEverywhere(); // every device
await auth.deleteAccount();     // deletes the user, then signs out
```

Apple از اپ‌های دارای ورود می‌خواهد امکان حذف حساب را داخل اپ ارائه کنند. [امنیت و داده‌ها](/docs/auth/security) را ببینید.

### مدیریت خطاها

همه‌ی فراخوانی‌ها `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` یکی از `AbrovaAuthErrorCode` است؛ `message` یک راهنمای انگلیسی برای توسعه‌دهنده است، نه برای کاربر. `isNetworkError` و `isSessionEnded` در حالت‌های رایج کمک می‌کنند. خطای شبکه هرگز کاربر را خارج نمی‌کند؛ وقتی نشست پایان می‌یابد (لغوشده، منقضی، حساب غیرفعال)، SDK خارج می‌شود و `authStateChanges` مقدار `null` می‌فرستد. همه‌ی کدها: [کدهای خطا](/docs/auth/error-codes).

### عیب‌یابی

<TroubleshootItem title="METHOD_DISABLED یا PRODUCT_DISABLED">
  <p>Abrova Auth را در تنظیمات › محصولات و روش را در Abrova Auth › روش‌های ورود روشن کنید. با getMethods() فقط روش‌هایی را نشان دهید که روشن‌اند.</p>
</TroubleshootItem>

<TroubleshootItem title="کاربر ناشناس جدید در هر بار اجرا">
  <p>پیش از خواندن currentUser، initialize() را صدا بزنید و فقط وقتی currentUser برابر null است وارد شوید.</p>
</TroubleshootItem>

<TroubleshootItem title="خطای INVALID_ID_TOKEN از Apple یا Google">
  <p>بررسی کنید bundle ID، Services ID یا client ID در کنسول باشد، و به ارائه‌دهنده AbrovaAuthNonce.sha256Hex(raw) و به ابرووا مقدار خام را داده باشید.</p>
</TroubleshootItem>

<TroubleshootItem title="SDKهای دیگر ابرووا هنوز به جای کاربر قبلی عمل می‌کنند">
  <p>آن‌ها توکن‌شان را cache می‌کنند. متد refresh آن‌ها (مثلاً AbrovaSync.refreshUserToken()) را از listener مربوط به authStateChanges صدا بزنید.</p>
</TroubleshootItem>

- SDK آی‌اواس: https://abrova.ir/docs/auth/ios

<BestPracticeList columns={2} items={[
  ['امن برای کلاینت', 'فقط از کلید API عمومی استفاده می‌کند. قرار دادنش در اپ امن است'],
  ['Apple در یک فراخوانی', 'signInWithAppleNative() صفحه‌ی Apple را اجرا می‌کند، همراه nonce'],
  ['Keychain', 'refresh token فقط روی همین دستگاه؛ access token در حافظه'],
  ['token providerها', 'tokenProvider و strictTokenProvider برای SDKهای دیگر ابرووا'],
  ['Swift Concurrency', 'API مبتنی بر async/await'],
  ['ارتقای مهمان‌ها', 'linkApple، linkGoogle و linkPassword شناسه‌ی کاربر را حفظ می‌کنند'],
]} />

<Callout kind="note" title="SDK iOS برای Abrova Auth نسخه‌ی v0.1.1">
این صفحه `AbrovaAuth` نسخه‌ی 0.1.1 را توضیح می‌دهد.
</Callout>

<Callout kind="note" title="پیش‌نیازها">
iOS 13 یا بالاتر، یا macOS 12 یا بالاتر. Swift 5.7 یا بالاتر.
</Callout>

از دستیار هوش مصنوعی استفاده می‌کنید؟ این صفحه را با **Copy page for AI** به آن بدهید، یا همه‌ی مستندات را به‌صورت متن ساده از [/docs/llms.txt](/docs/llms.txt) بگیرید. [دستیارهای هوش مصنوعی](/docs/auth/ai-assistants) را ببینید.

<H2 id="installation" step={1}>نصب</H2>

با Swift Package Manager نصب کنید. در Xcode: **File → Add Packages** → آدرس مخزن را وارد کنید:

```text
https://github.com/Abrova-co/abrova-auth-ios-sdk
```

یا آن را به `Package.swift` اضافه کنید:

```swift
dependencies: [
    .package(url: "https://github.com/Abrova-co/abrova-auth-ios-sdk.git", from: "0.1.1")
]
```

سپس `AbrovaAuth` را به وابستگی‌های target اضافه کنید.

در کنسول ابرووا، **Abrova Auth** را برای پروژه (**تنظیمات › محصولات**) و روش‌های ورود دلخواه را (**Abrova Auth › روش‌های ورود**) روشن کنید.

<H2 id="initialization" step={2}>مقداردهی اولیه</H2>

SDK را یک بار هنگام شروع اپ، پیش از هر فراخوانی دیگر، با کلید API عمومی (`ab_live_...`) پیکربندی کنید. نشستی که در اجرای قبلی ذخیره شده بازیابی می‌شود.

```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={['پارامتر', 'پیش‌فرض', 'توضیح']} rows={[
  ['apiKey', '-', 'کلید API عمومی شما (ab_live_...). هرگز کلید سرور نه.'],
  ['keychainAccessGroup', 'nil', 'نشست را با app extensionهای شما به اشتراک می‌گذارد.'],
]} />

Keychain بعد از حذف اپ هم باقی می‌ماند، به همین دلیل SDK نشستی را که از نصب قبلی مانده فراموش می‌کند: نصب تازه در حالت خارج‌شده شروع می‌شود.

<H2 id="sign-in" step={3}>ورود</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_...
```

فقط دکمه‌های روش‌هایی را نشان دهید که `methods.isEnabled(...)` برایشان true است: `anonymous`، `apple`، `google`، `password`، `magicLink`، `telegram`.

<H2 id="use-the-user-with-other-abrova-sdks" step={4}>استفاده از کاربر با SDKهای دیگر ابرووا</H2>

<Callout kind="soon">Abrova Sync، Chat، Push، Storage و A/B Testing به‌زودی می‌آیند. فراخوانی‌های زیر نشان می‌دهند کاربر Auth را چطور خواهند گرفت؛ امروز کاربر را با `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` مقدار `nil` برمی‌گرداند؛ `strictTokenProvider` خطا می‌دهد. هر دو توکنی برمی‌گردانند که پیش از انقضا تمدید شده است. بعد از ورود یا خروج، متد refresh آن SDK را صدا بزنید (مثلاً `sync.refreshUserToken()`). Abrova A/B Testing و موارد دیگر: [استفاده با محصولات دیگر ابرووا](/docs/auth/other-products).

### روش‌های ورود

هر روش صفحه‌ی خودش را با راه‌اندازی کنسول دارد: [ناشناس](/docs/auth/anonymous)، [Apple](/docs/auth/apple)، [Google](/docs/auth/google)، [ایمیل و رمز عبور](/docs/auth/email-password)، [لینک یک‌بارمصرف](/docs/auth/magic-link)، [تلگرام](/docs/auth/telegram).

#### ورود با Apple

قابلیت **Sign in with Apple** را به اپ و bundle ID را در **Abrova Auth › روش‌های ورود › Apple** اضافه کنید. سپس:

```swift
try await AbrovaAuth.shared.signInWithAppleNative()
```

SDK صفحه‌ی Apple را با یک nonce اجرا می‌کند و کد authorization (تا حذف حساب بتواند ورود با Apple را لغو کند) و نامی را که Apple در اولین ورود می‌دهد ارسال می‌کند. وقتی کاربر صفحه را ببندد، خطای `.canceled` می‌دهد. اگر درخواست Apple را خودتان اجرا می‌کنید:

```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)
```

#### ورود با Google

ID token مربوط به Google را با `AbrovaNonce.sha256(rawNonce)` به‌عنوان nonce درخواست کنید، سپس:

```swift
try await auth.signInWithGoogle(idToken: idToken, rawNonce: rawNonce)
```

ورود با Google به اتصال به Google نیاز دارد که بعضی کاربران در ایران ندارند. ناشناس، ایمیل و رمز عبور، لینک یک‌بارمصرف و کد تلگرام بدون Google کار می‌کنند، پس دست‌کم یکی از آن‌ها را هم ارائه کنید. [ورود با Google](/docs/auth/google) را ببینید.

#### ایمیل و رمز عبور

```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)` مقدار `token` را از لینکی که اپ با آن باز شده می‌خواند.

#### لینک یک‌بارمصرف

```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)
```

#### تلگرام

```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")
```

### ارتقای کاربر ناشناس

وصل کردن شناسه‌ی کاربر را حفظ می‌کند، پس هر چه ساخته مال خودش می‌ماند:

```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.
}
```

### کاربر فعلی

```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
```

### خروج و حذف حساب

```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
```

برای اینکه حذف چه چیزهایی را پاک می‌کند، [امنیت و داده‌ها](/docs/auth/security) را ببینید.

### مدیریت خطاها

همه‌ی خطاها از نوع `AbrovaAuthError` هستند. بر اساس `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` یک راهنمای انگلیسی برای توسعه‌دهنده است. SDK علاوه بر کدهای سرور از `.network`، `.canceled` (کاربر صفحه‌ی Apple را بست)، `.notSignedIn` و `.sdkNotConfigured` (اول `configure` را صدا بزنید) استفاده می‌کند. خطای شبکه هرگز کاربر را خارج نمی‌کند. همه‌ی کدها: [کدهای خطا](/docs/auth/error-codes).

### عیب‌یابی

<TroubleshootItem title="SDK_NOT_CONFIGURED">
  <p>AbrovaAuth.shared.configure(apiKey:) را هنگام شروع اپ، پیش از هر فراخوانی دیگر، صدا بزنید.</p>
</TroubleshootItem>

<TroubleshootItem title="ورود با Apple با INVALID_ID_TOKEN شکست می‌خورد">
  <p>bundle ID اپ را در Abrova Auth › روش‌های ورود › Apple، و قابلیت Sign in with Apple را به target اضافه کنید.</p>
</TroubleshootItem>

<TroubleshootItem title="METHOD_DISABLED یا PRODUCT_DISABLED">
  <p>Abrova Auth را در تنظیمات › محصولات و روش را در Abrova Auth › روش‌های ورود روشن کنید.</p>
</TroubleshootItem>

- SDK اندروید: https://abrova.ir/docs/auth/android

<BestPracticeList columns={2} items={[
  ['امن برای کلاینت', 'فقط از کلید API عمومی استفاده می‌کند. قرار دادنش در اپ امن است'],
  ['Coroutineها', 'همه‌ی فراخوانی‌ها تابع suspend هستند'],
  ['Keystore', 'refresh token با کلیدی رمزگذاری می‌شود که هرگز از Android Keystore خارج نمی‌شود'],
  ['token providerها', 'providerهای suspend، strict و blocking برای SDKهای دیگر ابرووا'],
  ['StateFlow', 'authState برای Compose و coroutineها، یا یک listener کلاسیک'],
  ['ارتقای مهمان‌ها', 'linkApple، linkGoogle و linkPassword شناسه‌ی کاربر را حفظ می‌کنند'],
]} />

<Callout kind="note" title="SDK Android برای Abrova Auth نسخه‌ی v0.1.1">
این صفحه `ir.abrova:abrova-auth` نسخه‌ی 0.1.1 را توضیح می‌دهد.
</Callout>

<Callout kind="note" title="پیش‌نیازها">
Android API 23 (Android 6.0) یا بالاتر. Kotlin coroutines.
</Callout>

از دستیار هوش مصنوعی استفاده می‌کنید؟ این صفحه را با **Copy page for AI** به آن بدهید، یا همه‌ی مستندات را به‌صورت متن ساده از [/docs/llms.txt](/docs/llms.txt) بگیرید. [دستیارهای هوش مصنوعی](/docs/auth/ai-assistants) را ببینید.

<H2 id="installation" step={1}>نصب</H2>

SDK از Abrova Center می‌آید. اول مخزن Maven ابرووا را در `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>

سپس وابستگی را در `build.gradle.kts` اپ اضافه کنید:

```kotlin
dependencies {
    implementation("ir.abrova:abrova-auth:0.1.1")
}
```

در کنسول ابرووا، **Abrova Auth** را برای پروژه (**تنظیمات › محصولات**) و روش‌های ورود دلخواه را (**Abrova Auth › روش‌های ورود**) روشن کنید.

<H2 id="initialization" step={2}>مقداردهی اولیه</H2>

SDK را یک بار، در `Application.onCreate`، با کلید API عمومی (`ab_live_...`) پیکربندی کنید. نشستی که در اجرای قبلی ذخیره شده بازیابی می‌شود.

```kotlin
import ir.abrova.auth.AbrovaAuth

class MyApp : Application() {
    override fun onCreate() {
        super.onCreate()
        AbrovaAuth.shared.configure(this, "ab_live_your_api_key")
    }
}
```

همه‌ی فراخوانی‌های ورود تابع `suspend` هستند: آن‌ها را از داخل یک coroutine صدا بزنید (مثلاً `lifecycleScope.launch { ... }`).

<H2 id="sign-in" step={3}>ورود</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_...
```

فقط دکمه‌های روش‌هایی را نشان دهید که `methods.isEnabled(...)` برایشان true است: `anonymous`، `apple`، `google`، `password`، `magicLink`، `telegram`.

<H2 id="use-the-user-with-other-abrova-sdks" step={4}>استفاده از کاربر با SDKهای دیگر ابرووا</H2>

<Callout kind="soon">Abrova Sync، Chat، Push، Storage و A/B Testing به‌زودی می‌آیند. فراخوانی‌های زیر نشان می‌دهند کاربر Auth را چطور خواهند گرفت؛ امروز کاربر را با `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', 'نوع', 'وقتی کسی وارد نشده']} rows={[
  ['tokenProvider', 'suspend () -> String?', 'null برمی‌گرداند'],
  ['strictTokenProvider', 'suspend () -> String', 'خطای NOT_SIGNED_IN می‌دهد'],
  ['blockingTokenProvider', '() -> String?', 'null برمی‌گرداند. thread فراخواننده را block می‌کند: هرگز آن را روی main thread صدا نزنید'],
]} />

همه توکنی برمی‌گردانند که پیش از انقضا تمدید شده است. بعد از ورود یا خروج، متد refresh آن SDK را صدا بزنید (مثلاً `sync.userTokens.refresh()`). Abrova A/B Testing و موارد دیگر: [استفاده با محصولات دیگر ابرووا](/docs/auth/other-products).

### روش‌های ورود

هر روش صفحه‌ی خودش را با راه‌اندازی کنسول دارد: [ناشناس](/docs/auth/anonymous)، [Apple](/docs/auth/apple)، [Google](/docs/auth/google)، [ایمیل و رمز عبور](/docs/auth/email-password)، [لینک یک‌بارمصرف](/docs/auth/magic-link)، [تلگرام](/docs/auth/telegram).

#### ورود با Google

از Credential Manager با client ID **وب** خودتان و یک nonce هش‌شده استفاده کنید. `androidx.credentials:credentials`، `androidx.credentials:credentials-play-services-auth` و `com.google.android.libraries.identity.googleid:googleid` را به اپ اضافه کنید:

```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)
```

client ID وب را در **Abrova Auth › روش‌های ورود › Google** اضافه کنید.

ورود با Google به اتصال به Google، و در Android به Google Play services هم، نیاز دارد؛ بعضی کاربران در ایران هیچ‌کدام را ندارند. ناشناس، ایمیل و رمز عبور، لینک یک‌بارمصرف و کد تلگرام بدون Google کار می‌کنند، پس دست‌کم یکی از آن‌ها را هم ارائه کنید. [ورود با Google](/docs/auth/google) را ببینید.

#### ورود با Apple

ورود وب Apple را با **Services ID** خودتان و `AbrovaNonce.sha256(rawNonce)` به‌عنوان nonce اجرا کنید، سپس `id_token` و `code` را که Apple برمی‌گرداند بفرستید:

```kotlin
auth.signInWithApple(idToken, rawNonce, authorizationCode = code)
```

#### ایمیل و رمز عبور

```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")
```

#### لینک یک‌بارمصرف

```kotlin
auth.sendMagicLink(email, redirectUrl = "myapp://auth/magic")
// In the activity the link opens:
AbrovaAuth.tokenFromLink(intent.dataString ?: "")?.let { auth.signInWithMagicLink(it) }
```

#### تلگرام

```kotlin
val code = auth.requestTelegramCode("+989121234567")
if (!code.sent) startActivity(Intent(Intent.ACTION_VIEW, Uri.parse(code.botUrl)))
auth.verifyTelegramCode("+989121234567", "123456")
```

### ارتقای کاربر ناشناس

وصل کردن شناسه‌ی کاربر را حفظ می‌کند، پس هر چه ساخته مال خودش می‌ماند:

```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.
    }
}
```

### کاربر فعلی

```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
```

### خروج و حذف حساب

```kotlin
auth.signOut()            // this device; never fails
auth.signOutEverywhere()  // every device
auth.deleteAccount()      // deletes the user, then signs out
```

برای اینکه حذف چه چیزهایی را پاک می‌کند، [امنیت و داده‌ها](/docs/auth/security) را ببینید.

### مدیریت خطاها

همه‌ی خطاها از نوع `AbrovaAuthException` هستند. بر اساس `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` یک راهنمای انگلیسی برای توسعه‌دهنده است. SDK علاوه بر کدهای سرور از `NETWORK_ERROR`، `NOT_SIGNED_IN` و `SDK_NOT_CONFIGURED` (اول `configure` را صدا بزنید) استفاده می‌کند. خطای شبکه هرگز کاربر را خارج نمی‌کند. همه‌ی کدها: [کدهای خطا](/docs/auth/error-codes).

### عیب‌یابی

<TroubleshootItem title="SDK_NOT_CONFIGURED">
  <p>AbrovaAuth.shared.configure(context, apiKey) را در Application.onCreate صدا بزنید.</p>
</TroubleshootItem>

<TroubleshootItem title="ورود با Google با INVALID_ID_TOKEN شکست می‌خورد">
  <p>Credential Manager، ID token را برای client ID وبی صادر می‌کند که به‌عنوان serverClientId می‌دهید. همان client ID وب را در کنسول اضافه کنید و AbrovaNonce.sha256(rawNonce) را به‌عنوان nonce بدهید.</p>
</TroubleshootItem>

<TroubleshootItem title="اپ وقتی Sync توکن می‌خواهد قفل می‌شود">
  <p>blockingTokenProvider thread خودش را block می‌کند. آن را فقط به SDKهایی بدهید که بیرون از main thread صدایش می‌زنند، و هرگز خودتان آن را روی main thread صدا نزنید.</p>
</TroubleshootItem>

- SDK وب: https://abrova.ir/docs/auth/web

<BestPracticeList columns={2} items={[
  ['امن برای کلاینت', 'فقط از کلید API عمومی استفاده می‌کند. قرار دادنش در bundle مرورگر امن است'],
  ['هر فریم‌ورکی', 'TypeScript ساده: React، Vue، Svelte، کد سمت کلاینت Next.js، یا بدون فریم‌ورک'],
  ['پیش‌فرض در حافظه', 'تا خودتان نخواهید چیزی ذخیره نمی‌شود'],
  ['token provider', 'tokenProvider و getToken() برای SDKهای دیگر ابرووا'],
  ['تابع کمکی nonce', 'createNonce() برای Apple JS و Google Identity Services'],
  ['ارتقای مهمان‌ها', 'linkApple، linkGoogle و linkPassword شناسه‌ی کاربر را حفظ می‌کنند'],
]} />

<Callout kind="note" title="SDK Web برای Abrova Auth نسخه‌ی v0.1.1">
این صفحه `@abrova/auth-web` نسخه‌ی 0.1.1 را توضیح می‌دهد.
</Callout>

<Callout kind="note" title="پیش‌نیازها">
مرورگری با `fetch` و `crypto.getRandomValues` (همه‌ی مرورگرهای فعلی). فقط در کد سمت کلاینت اجرا می‌شود؛ Abrova Auth SDK سرور ندارد.
</Callout>

از دستیار هوش مصنوعی استفاده می‌کنید؟ این صفحه را با **Copy page for AI** به آن بدهید، یا همه‌ی مستندات را به‌صورت متن ساده از [/docs/llms.txt](/docs/llms.txt) بگیرید. [دستیارهای هوش مصنوعی](/docs/auth/ai-assistants) را ببینید.

<H2 id="installation" step={1}>نصب</H2>

پکیج از Abrova Center می‌آید. اول در `.npmrc` پروژه، scope `@abrova` را به رجیستری ابرووا ارجاع دهید:

<Code file=".npmrc" lang="INI">{`@abrova:registry=https://center.abrova.ir/api/packages/abrova/npm/`}</Code>

سپس نصب کنید:

```bash
npm install @abrova/auth-web
```

یا در `package.json`:

```json
{
  "dependencies": {
    "@abrova/auth-web": "^0.1.1"
  }
}
```

در کنسول ابرووا، **Abrova Auth** را برای پروژه (**تنظیمات › محصولات**) و روش‌های ورود دلخواه را (**Abrova Auth › روش‌های ورود**) روشن کنید.

<H2 id="initialization" step={2}>مقداردهی اولیه</H2>

برای اپ یک کلاینت با کلید API عمومی (`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={['گزینه', 'پیش‌فرض', 'توضیح']} rows={[
  ['apiKey', '-', 'کلید API عمومی شما (ab_live_...). هرگز کلید سرور نه.'],
  ['storage', 'memory', 'جایی که refresh token بین بارگذاری‌های صفحه نگه داشته می‌شود. «وارد ماندن» را ببینید.'],
  ['storageKey', 'برگرفته از کلید API', 'کلید ذخیره‌سازی، تا دو پروژه هرگز یک نشست مشترک نداشته باشند.'],
  ['timeoutMs', '15000', 'مهلت درخواست به میلی‌ثانیه.'],
]} />

`await auth.ready()` وقتی نشست ذخیره‌شده (اگر باشد) بارگذاری شد resolve می‌شود. `onAuthStateChanged` در همان لحظه listener شما را با شناسه‌ی کاربر فعلی صدا می‌زند، و دوباره در هر ورود یا خروج. یک تابع برمی‌گرداند که گوش دادن را متوقف می‌کند.

<H2 id="sign-in" step={3}>ورود</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_...
```

فقط دکمه‌های روش‌هایی را نشان دهید که `getMethods()` برمی‌گرداند.

<H2 id="use-the-user-with-other-abrova-sdks" step={4}>استفاده از کاربر با SDKهای دیگر ابرووا</H2>

<Callout kind="soon">Abrova Sync، Chat، Push، Storage و A/B Testing به‌زودی می‌آیند. فراخوانی‌های زیر نشان می‌دهند کاربر Auth را چطور خواهند گرفت؛ امروز کاربر را با SDK Next.js ابرووا تریس (`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()` به یک access token تازه resolve می‌شود، یا وقتی کسی وارد نشده به `null`. `auth.tokenProvider` به توکن resolve می‌شود و وقتی کسی وارد نشده با `UNAUTHENTICATED` reject می‌شود: از آن برای Abrova Chat استفاده کنید که provider آن باید توکن برگرداند. بعد از ورود یا خروج، متد refresh آن SDK را صدا بزنید (مثلاً `sync.refreshUserToken()`). بیشتر: [استفاده با محصولات دیگر ابرووا](/docs/auth/other-products).

### روش‌های ورود

هر روش صفحه‌ی خودش را با راه‌اندازی کنسول دارد: [ناشناس](/docs/auth/anonymous)، [Apple](/docs/auth/apple)، [Google](/docs/auth/google)، [ایمیل و رمز عبور](/docs/auth/email-password)، [لینک یک‌بارمصرف](/docs/auth/magic-link)، [تلگرام](/docs/auth/telegram).

#### ایمیل و رمز عبور

```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' });
```

#### لینک یک‌بارمصرف

```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 });
```

#### تلگرام

```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 و Google

ورودِ خودِ ارائه‌دهنده را با nonce‌ای از SDK اجرا کنید، سپس ID token آن را به ابرووا بدهید:

```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 });
```

برای هر ورود یک nonce جدید بسازید. ورود با Google به اتصال به Google نیاز دارد که بعضی کاربران در ایران ندارند. ناشناس، ایمیل و رمز عبور، لینک یک‌بارمصرف و کد تلگرام بدون Google کار می‌کنند، پس دست‌کم یکی از آن‌ها را هم ارائه کنید. [ورود با Google](/docs/auth/google) را ببینید. روی وب، Apple از **Services ID** شما استفاده می‌کند: آن را در **Abrova Auth › روش‌های ورود › Apple** اضافه کنید.

### ارتقای کاربر ناشناس

وصل کردن شناسه‌ی کاربر را حفظ می‌کند، پس داده‌های کاربر مال خودش می‌ماند:

```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.
  }
}
```

### کاربر فعلی

```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()
```

### خروج و حذف حساب

```typescript
await auth.signOut();           // this device
await auth.signOutEverywhere(); // every device
await auth.deleteAccount();     // deletes the user, then signs out
```

### وارد ماندن

به‌طور پیش‌فرض چیزی ذخیره نمی‌شود: کاربر بعد از reload صفحه دوباره وارد می‌شود. برای نگه داشتن نشست، `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 و XSS">
هر اسکریپتی در صفحه‌ی شما می‌تواند `localStorage` را بخواند. یک باگ XSS یا یک وابستگی آلوده می‌تواند refresh token و همراه آن نشست کاربر را بردارد. از این گزینه فقط با یک Content Security Policy سخت‌گیرانه و بدون اسکریپت‌های نامطمئن استفاده کنید. SDK هرگز cookie تنظیم نمی‌کند.
</Callout>

می‌توانید حافظه‌ی دلخواه خودتان را هم بدهید: شیئی با متدهای async به نام `get`، `set` و `remove`.

### مدیریت خطاها

هر شکست یک `AbrovaAuthError` با یک `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);
}
```

SDK علاوه بر کدهای سرور از `NETWORK_ERROR` استفاده می‌کند. خطای شبکه هرگز کاربر را خارج نمی‌کند؛ نشستِ لغوشده یا منقضی این کار را می‌کند (`onAuthStateChanged(null)`). access token ۲ دقیقه پیش از انقضا تمدید می‌شود و فراخوانی‌های هم‌زمان در یک تمدید شریک می‌شوند. همه‌ی کدها: [کدهای خطا](/docs/auth/error-codes).

### عیب‌یابی

<TroubleshootItem title="خروج بعد از هر reload">
  <p>این رفتار پیش‌فرض است: نشست در حافظه نگه داشته می‌شود. اگر صفحه‌تان Content Security Policy سخت‌گیرانه دارد، storage: localStorageStorage() را بدهید، یا دوباره به‌صورت ناشناس وارد شوید.</p>
</TroubleshootItem>

<TroubleshootItem title="مقدار currentUserId درست بعد از reload برابر null است">
  <p>نشست ذخیره‌شده به‌صورت async بارگذاری می‌شود. منتظر auth.ready() یا اولین فراخوانی onAuthStateChanged بمانید.</p>
</TroubleshootItem>

<TroubleshootItem title="لینک ایمیلی با INVALID_INPUT رد می‌شود">
  <p>redirectUrl باید با یکی از آدرس‌های لینک در Abrova Auth › تنظیمات شروع شود.</p>
</TroubleshootItem>

- SDK ری‌اکت نیتیو: https://abrova.ir/docs/auth/react-native

<BestPracticeList columns={2} items={[
  ['امن برای کلاینت', 'فقط از کلید API عمومی استفاده می‌کند. قرار دادنش در اپ امن است'],
  ['Expo یا bare', 'react-native-keychain یا expo-secure-store برای نشست'],
  ['حافظه‌ی امن', 'refresh token فقط روی همین دستگاه؛ access token در حافظه'],
  ['token provider', 'tokenProvider و getToken() برای SDKهای دیگر ابرووا'],
  ['همان API وب', 'یک مجموعه فراخوانی برای کد وب و موبایل'],
  ['ارتقای مهمان‌ها', 'linkApple، linkGoogle و linkPassword شناسه‌ی کاربر را حفظ می‌کنند'],
]} />

<Callout kind="note" title="SDK React Native برای Abrova Auth نسخه‌ی v0.1.1">
این صفحه `@abrova/auth-react-native` نسخه‌ی 0.1.1 را توضیح می‌دهد.
</Callout>

<Callout kind="note" title="پیش‌نیازها">
React Native با `react-native-keychain`، یا Expo با `expo-secure-store`. ورود با Apple و Google به `crypto.getRandomValues` (`react-native-get-random-values`) هم نیاز دارد.
</Callout>

از دستیار هوش مصنوعی استفاده می‌کنید؟ این صفحه را با **Copy page for AI** به آن بدهید، یا همه‌ی مستندات را به‌صورت متن ساده از [/docs/llms.txt](/docs/llms.txt) بگیرید. [دستیارهای هوش مصنوعی](/docs/auth/ai-assistants) را ببینید.

<H2 id="installation" step={1}>نصب</H2>

پکیج از Abrova Center می‌آید. اول در `.npmrc` پروژه، scope `@abrova` را به رجیستری ابرووا ارجاع دهید:

<Code file=".npmrc" lang="INI">{`@abrova:registry=https://center.abrova.ir/api/packages/abrova/npm/`}</Code>

سپس آن را همراه یکی از کتابخانه‌های حافظه‌ی امن نصب کنید:

```bash
npm install @abrova/auth-react-native react-native-keychain
# or, with Expo
npx expo install @abrova/auth-react-native expo-secure-store
```

یا در `package.json`:

```json
{
  "dependencies": {
    "@abrova/auth-react-native": "^0.1.1"
  }
}
```

برای nonce ورود با Apple و Google، `react-native-get-random-values` را هم نصب کنید و آن را در ابتدای `index.js` import کنید:

```bash
npm install react-native-get-random-values
```

```typescript
// index.js, before anything else
import 'react-native-get-random-values';
```

در کنسول ابرووا، **Abrova Auth** را برای پروژه (**تنظیمات › محصولات**) و روش‌های ورود دلخواه را (**Abrova Auth › روش‌های ورود**) روشن کنید.

<H2 id="initialization" step={2}>مقداردهی اولیه</H2>

برای اپ یک کلاینت با کلید API عمومی (`ab_live_...`) و حافظه‌ی امن بسازید:

```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');
});
```

با 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) });
```

فقط refresh token ذخیره می‌شود (Keychain در iOS، حافظه‌ی متکی به Keystore در Android، فقط روی همین دستگاه). access token در حافظه می‌ماند. **بدون `storage`، هیچ چیز بعد از راه‌اندازی دوباره‌ی اپ باقی نمی‌ماند.**

`await auth.ready()` وقتی نشست ذخیره‌شده بارگذاری شد resolve می‌شود. `onAuthStateChanged` در همان لحظه listener شما را با شناسه‌ی کاربر فعلی صدا می‌زند، و دوباره در هر ورود یا خروج.

<H2 id="sign-in" step={3}>ورود</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}>استفاده از کاربر با SDKهای دیگر ابرووا</H2>

<Callout kind="soon">Abrova Sync، Chat، Push، Storage و A/B Testing به‌زودی می‌آیند. فراخوانی‌های زیر نشان می‌دهند کاربر Auth را چطور خواهند گرفت؛ هنوز در دسترس نیستند.</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()` به یک access token تازه resolve می‌شود، یا وقتی کسی وارد نشده به `null`. `auth.tokenProvider` به جای آن با `UNAUTHENTICATED` reject می‌شود: از آن برای Abrova Chat استفاده کنید. وقتی کاربر وارد یا خارج می‌شود، از SDKهای دیگر بخواهید توکن جدید بگیرند (مثلاً `AbrovaSync.refreshUserToken()`). بیشتر: [استفاده با محصولات دیگر ابرووا](/docs/auth/other-products).

### روش‌های ورود

هر روش صفحه‌ی خودش را با راه‌اندازی کنسول دارد: [ناشناس](/docs/auth/anonymous)، [Apple](/docs/auth/apple)، [Google](/docs/auth/google)، [ایمیل و رمز عبور](/docs/auth/email-password)، [لینک یک‌بارمصرف](/docs/auth/magic-link)، [تلگرام](/docs/auth/telegram).

#### ایمیل و رمز عبور

```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 });
```

#### لینک یک‌بارمصرف

```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 });
```

#### تلگرام

```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 و Google

ورود بومی را با nonce‌ای از SDK اجرا کنید، سپس ID token آن را به ابرووا بدهید:

```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 });
```

برای هر ورود یک nonce جدید بسازید. ورود با Google به اتصال به Google، و در Android به Google Play services هم، نیاز دارد؛ بعضی کاربران در ایران هیچ‌کدام را ندارند. ناشناس، ایمیل و رمز عبور، لینک یک‌بارمصرف و کد تلگرام بدون Google کار می‌کنند، پس دست‌کم یکی از آن‌ها را هم ارائه کنید. [ورود با Google](/docs/auth/google) را ببینید.

### ارتقای کاربر ناشناس

وصل کردن شناسه‌ی کاربر را حفظ می‌کند، پس داده‌های کاربر مال خودش می‌ماند:

```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.
  }
}
```

### کاربر فعلی

```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()
```

### خروج و حذف حساب

```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)
```

### مدیریت خطاها

هر شکست یک `AbrovaAuthError` با یک `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);
}
```

SDK علاوه بر کدهای سرور از `NETWORK_ERROR` استفاده می‌کند. خطای شبکه هرگز کاربر را خارج نمی‌کند؛ نشستِ لغوشده یا منقضی این کار را می‌کند (`onAuthStateChanged(null)`). access token ۲ دقیقه پیش از انقضا تمدید می‌شود و فراخوانی‌های هم‌زمان در یک تمدید شریک می‌شوند. همه‌ی کدها: [کدهای خطا](/docs/auth/error-codes).

### عیب‌یابی

<TroubleshootItem title="خروج بعد از هر بار راه‌اندازی دوباره">
  <p>storage: keychainStorage(Keychain) یا secureStoreStorage(SecureStore) را بدهید. بدون آن، نشست فقط در حافظه نگه داشته می‌شود.</p>
</TroubleshootItem>

<TroubleshootItem title="createNonce با NOT_CONFIGURED شکست می‌خورد">
  <p>crypto.getRandomValues وجود ندارد. react-native-get-random-values را نصب کنید و آن را در ابتدای index.js import کنید.</p>
</TroubleshootItem>

<TroubleshootItem title="لینک ایمیلی با INVALID_INPUT رد می‌شود">
  <p>redirectUrl باید با یکی از آدرس‌های لینک در Abrova Auth › تنظیمات شروع شود، مثلاً myapp://auth.</p>
</TroubleshootItem>

- دستیارهای هوش مصنوعی (به‌زودی): https://abrova.ir/docs/auth/ai-assistants

<Callout kind="soon">
هنوز سرور مستندات ابرووا برای دستیارهای هوش مصنوعی وجود ندارد. این صفحه می‌گوید چه کاری خواهد کرد و امروز چه چیزی کار می‌کند.
</Callout>

### چه کاری خواهد کرد

وقتی راه بیفتد، دستیار هوش مصنوعی‌تان (مثلاً دستیار کدنویسی داخل ادیتور) را یک بار به آن وصل می‌کنید. وقتی از دستیار بخواهید Abrova Auth را به اپ‌تان اضافه کند، به جای جواب دادن از حافظه، نسخه‌ی فعلی SDK، خط‌های نصب و مراحل راه‌اندازی را از همین مستندات پیدا می‌کند.

این سرور فقط‌خواندنی خواهد بود و ابزارهایی مثل این‌ها دارد:

<ConfigTable headers={['ابزار', 'چه کاری می‌کند']} rows={[
  ['list_products', 'محصولات ابرووا، همراه پلتفرم‌هایی که SDK دارند.'],
  ['search_docs', 'صفحه‌های مستندات را برای چند کلمه یا یک سؤال کوتاه پیدا می‌کند.'],
  ['read_doc', 'یک صفحه از مستندات را می‌خواند.'],
  ['get_sdk_info', 'نسخه‌ی فعلی SDK و خط‌های نصب برای یک محصول و پلتفرم.'],
  ['get_setup_guide', 'مراحل مرتب راه‌اندازی برای یک محصول و پلتفرم.'],
]} />

### حریم خصوصی

- **چه چیزی را می‌خواند:** مستندات عمومی ابرووا، نسخه‌های فعلی SDKها و کلماتی که دستیارتان برایش می‌فرستد.
- **هرگز نمی‌بیند:** کد شما، پروژه‌ها، کلیدها یا کاربران‌تان.

<Callout kind="warn" title="کلیدها را وارد گفتگو نکنید">
هرگز کلیدی را در گفتگو با دستیار هوش مصنوعی جای‌گذاری نکنید. بگذارید placeholder مستندات (`ab_live_your_api_key`) را بنویسد و مقدار واقعی را خودتان در تنظیمات پروژه قرار دهید.
</Callout>

### امروز چه چیزی کار می‌کند

- **Copy page for AI** در هر صفحه‌ی مستندات، آن صفحه را به‌صورت متن ساده کپی می‌کند تا در دستیارتان جای‌گذاری کنید.
- در [/docs/llms.txt](/docs/llms.txt) همه‌ی صفحه‌های مستندات به‌صورت متن ساده هست، برای دستیارهایی که می‌توانند لینک بخوانند.

صفحه‌های خوب برای شروع: [معرفی و شروع سریع](/docs/auth/quick-start) و صفحه‌ی SDK پلتفرم‌تان ([Flutter](/docs/auth/flutter)، [iOS](/docs/auth/ios)، [Android](/docs/auth/android)، [Web](/docs/auth/web)، [React Native](/docs/auth/react-native)).

درباره‌ی دستیارهای هوش مصنوعی و ابرووا بیشتر بخوانید: [دستیارهای هوش مصنوعی](/ai-assistants).

- ناشناس: https://abrova.ir/docs/auth/anonymous

<Callout kind="note" title="ورود ناشناس">
یک فراخوانی کاربری با شناسه‌ی تصادفی می‌سازد و دستگاه را وارد می‌کند. نه صفحه‌ای هست و نه چیزی برای تایپ کردن. نشست فقط روی همین دستگاه است، پس تا وقتی کاربر [یک روش ورود وصل نکرده](/docs/auth/upgrading)، او را مهمان در نظر بگیرید.
</Callout>

<H2 id="turn-it-on" step={1}>روشن کردن</H2>

در کنسول ابرووا، **Abrova Auth › روش‌های ورود** را باز کنید و **ناشناس** را روشن کنید. در صورت تمایل، در **Abrova Auth › تنظیمات › کاربران ناشناس** سقف روزانه‌ی کمتری برای کاربران ناشناس جدید بگذارید.

<H2 id="sign-in" step={2}>ورود</H2>

فقط وقتی کسی هنوز وارد نشده، ورود را انجام دهید. SDK نشست ذخیره‌شده را هنگام اجرا بازیابی می‌کند، پس همان مهمان در اجرای بعدی برمی‌گردد.

```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();
}
```

در Flutter، اگر از قبل یک کاربر ناشناس روی دستگاه وارد شده باشد، `signInAnonymously()` همان کاربر فعلی را برمی‌گرداند.

<H2 id="upgrade-later" step={3}>ارتقا در آینده</H2>

وقتی کاربر ناشناس خواست حسابش را نگه دارد، Apple، Google یا ایمیل و رمز عبور را به او وصل کنید. شناسه همان می‌ماند:

```dart
await AbrovaAuth.instance.linkPassword(email: email, password: password);
```

برای اینکه وقتی حساب از قبل وجود دارد چه اتفاقی می‌افتد، [کاربران ناشناس و ارتقا](/docs/auth/upgrading) را ببینید.

### سقف‌ها

<ConfigTable headers={['سقف', 'مقدار']} rows={[
  ['کاربر ناشناس جدید در روز', '۲۰۰ برای هر پروژه، یا سقف کمتری که خودتان بگذارید'],
  ['از یک آدرس', 'هجوم کاربران جدید از یک آدرس کُند می‌شود'],
  ['حذف در صورت عدم استفاده', 'بعد از ۹۰ روز بدون ورود یا تمدید (۷ تا ۳٬۶۵۰، در تنظیمات)'],
]} />

با عبور از سقف، فراخوانی با `RATE_LIMITED` شکست می‌خورد. هر کاربر ناشناس جدیدی که از اپ استفاده کند، مثل هر کاربر دیگری یک کاربر فعال ماهانه حساب می‌شود.

### خطاها

<ConfigTable headers={['کد', 'معنا']} rows={[
  ['METHOD_DISABLED', 'ورود ناشناس برای پروژه خاموش است.'],
  ['RATE_LIMITED', 'کاربران ناشناس جدید بیش از حد: برای یک آدرس، یا سقف روزانه. بعد از retryAfterSec دوباره امتحان کنید.'],
  ['MAU_LIMIT', '۱٬۰۰۰ کاربر فعال ماهانه‌ی رایگان این ماه تمام شده و کیف پول موجودی کافی برای بیشتر از آن ندارد.'],
]} />

- Apple: https://abrova.ir/docs/auth/apple

<Callout kind="note" title="ورود با Apple">
اپ شما ورودِ خودِ Apple را اجرا می‌کند و یک **ID token** از Apple می‌گیرد. SDK این توکن را به Abrova Auth می‌فرستد؛ Abrova Auth بررسی می‌کند که Apple آن را برای یکی از شناسه‌های اپِ **شما** امضا کرده باشد و کاربر را وارد می‌کند. در iOS، SDK می‌تواند کل صفحه‌ی Apple را برایتان اجرا کند.
</Callout>

<Callout kind="warn" title="قانون App Store">
اپ iOS که ورود با Google (یا ورود شخص ثالث دیگری) دارد باید ورود با Apple را هم ارائه کند، و اپی که اجازه‌ی ساخت حساب می‌دهد باید اجازه‌ی حذف آن را هم داخل اپ بدهد. Abrova Auth از هر دو پشتیبانی می‌کند.
</Callout>

<Callout kind="note" title="کاربران داخل ایران">
ورود با Apple به اتصال به Apple نیاز دارد که از ایران ممکن است ناپایدار باشد. ناشناس، ایمیل و رمز عبور، لینک یک‌بارمصرف یا کد تلگرام را هم ارائه کنید: این روش‌ها به Apple یا Google وابسته نیستند.
</Callout>

<H2 id="set-it-up-in-the-console" step={1}>راه‌اندازی در کنسول</H2>

**Abrova Auth › روش‌های ورود** را باز کنید، **Apple** را روشن کنید و شناسه‌هایتان را وارد کنید:

<ConfigTable headers={['فیلد', 'چه چیزی وارد کنید']} rows={[
  ['Bundle IDها (اپ‌های iOS)', 'bundle id هر اپ iOS یا macOS که از صفحه‌ی بومی Apple استفاده می‌کند، مثلاً com.example.app.'],
  ['Services IDها (وب و Android)', 'Services ID که در Apple Developer portal برای ورود با Apple روی وب یا Android ساخته‌اید.'],
]} />

Abrova Auth فقط ID tokenی از Apple را می‌پذیرد که برای یکی از این شناسه‌ها صادر شده باشد. توکنی که Apple برای هر اپ دیگری صادر کرده رد می‌شود.

#### کلید حذف حساب (توصیه‌شده)

Apple از اپ‌ها می‌خواهد وقتی کاربر حسابش را حذف می‌کند، ورود با Apple او را لغو کنند. برای اینکه Abrova Auth این کار را انجام دهد، در Apple Developer portal یک **Sign in with Apple key** بسازید (Certificates, Identifiers & Profiles › Keys) و در همان بخش Apple این‌ها را وارد کنید:

<ConfigTable headers={['فیلد', 'کجا پیدایش کنید']} rows={[
  ['Team ID', '۱۰ کاراکتر، در Apple Developer › Membership.'],
  ['Key ID', '۱۰ کاراکتر، کنار خود کلید نمایش داده می‌شود.'],
  ['کلید خصوصی (.p8)', 'کل فایل. رمزگذاری‌شده ذخیره می‌شود و دیگر نمایش داده نمی‌شود.'],
]} />

سپس هنگام ورود کاربر، `authorizationCode` مربوط به Apple را بفرستید (SDKها نشان می‌دهند کجا). Abrova Auth این کد را وقتی کاربر برای اولین بار با Apple ثبت‌نام می‌کند (یا Apple را وصل می‌کند) استفاده می‌کند، پس کلید را **پیش از** انتشار اپ اضافه کنید: ورود با Apple کاربرانی که پیش از ذخیره‌ی کلید ثبت‌نام کرده‌اند قابل لغو نیست. بدون کلید یا کد هم حذف حساب کاربر را حذف می‌کند؛ فقط لغو در سمت Apple انجام نمی‌شود.

<H2 id="the-nonce" step={2}>مقدار nonce</H2>

nonce، ID token مربوط به Apple را به همین یک ورود گره می‌زند تا توکنی که شنود شده دوباره قابل استفاده نباشد:

1. با تابع کمکی SDK یک **nonce خام** تصادفی بسازید (۱۶ تا ۲۵۶ کاراکتر).
2. SHA-256 آن را به‌صورت hex با حروف کوچک به **Apple** بدهید.
3. مقدار خام را به **Abrova Auth** بدهید.

Abrova Auth بررسی می‌کند که این دو با هم جور باشند و هر nonce را فقط یک بار می‌پذیرد. ID token مربوط به Apple هم باید کمتر از ۱۰ دقیقه عمر داشته باشد.

<ConfigTable headers={['SDK', 'nonce خام', 'مقدار برای 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}>ورود</H2>

#### iOS: SDK صفحه‌ی Apple را اجرا می‌کند

قابلیت **Sign in with Apple** را به target اپ اضافه کنید، سپس:

```swift
try await AbrovaAuth.shared.signInWithAppleNative()
```

SDK خودش nonce را می‌سازد، صفحه‌ی Apple را نشان می‌دهد و ID token، کد authorization و نامی را که Apple در اولین ورود می‌دهد ارسال می‌کند. وقتی کاربر صفحه را ببندد، خطای `.canceled` می‌دهد.

#### Flutter

با پکیج `sign_in_with_apple`:

```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

ورود وب Apple را با **Services ID** خودتان و `AbrovaNonce.sha256(rawNonce)` به‌عنوان nonce اجرا کنید، سپس `id_token` و `code` را که Apple برمی‌گرداند بفرستید:

```kotlin
AbrovaAuth.shared.signInWithApple(idToken, rawNonce, authorizationCode = code)
```

#### Web و React Native

از Sign in with Apple JS (وب) یا کتابخانه‌ی ورود با Apple در React Native استفاده کنید و `hashedNonce` را به‌عنوان nonce بدهید:

```typescript
const { rawNonce, hashedNonce } = await auth.createNonce();
// ... run Apple's sign-in with nonce: hashedNonce, then:
await auth.signInWithApple({ idToken, rawNonce, authorizationCode, name });
```

### نام و ایمیل

Apple نام کاربر را فقط در **اولین** ورود می‌دهد، و ایمیل ممکن است یک آدرس private relay باشد. Abrova Auth آن‌ها را (رمزگذاری‌شده) فقط وقتی ذخیره می‌کند که **ذخیره‌ی اطلاعات پروفایل** در **Abrova Auth › تنظیمات** روشن باشد. اگر اپ شما به نام نیاز دارد، آن را در اولین ورود در داده‌های خودتان ذخیره کنید.

### وصل کردن Apple به کاربرِ واردشده

برای ارتقای کاربر ناشناس، فراخوانی link را با همان آرگومان‌ها به کار ببرید: `linkApple(...)`، یا در iOS `signInWithAppleNative(link: true)`. شناسه‌ی کاربر همان می‌ماند. اگر این Apple ID از قبل متعلق به کاربر دیگری باشد، فراخوانی با `PROVIDER_ALREADY_LINKED` شکست می‌خورد.

### خطاها

<ConfigTable headers={['کد', 'معنا']} rows={[
  ['NOT_CONFIGURED', 'Apple روشن است، اما هیچ bundle ID یا Services ID وارد نشده است.'],
  ['INVALID_ID_TOKEN', 'Apple آن را امضا نکرده، برای شناسه‌ی اپ دیگری صادر شده، بیش از ۱۰ دقیقه عمر دارد، یا nonce آن SHA-256 همان nonce خامی که فرستادید نیست.'],
  ['INVALID_INPUT', 'nonce خام فرستاده نشده یا بین ۱۶ تا ۲۵۶ کاراکتر نیست.'],
  ['NONCE_REUSED', 'این nonce قبلاً استفاده شده است. برای هر ورود یک nonce جدید بسازید.'],
  ['PROVIDER_ALREADY_LINKED', 'فقط هنگام وصل کردن: این Apple ID متعلق به کاربر دیگری است.'],
  ['METHOD_DISABLED', 'ورود با Apple برای پروژه خاموش است.'],
]} />

- Google: https://abrova.ir/docs/auth/google

<Callout kind="note" title="ورود با Google">
اپ شما ورودِ خودِ Google را اجرا می‌کند (Credential Manager در Android، Google Sign-In در iOS و Flutter، و Google Identity Services در وب) و یک **ID token** می‌گیرد. SDK این توکن را به Abrova Auth می‌فرستد؛ Abrova Auth بررسی می‌کند که Google آن را برای یکی از OAuth client IDهای **شما** صادر کرده باشد و کاربر را وارد می‌کند.
</Callout>

<Callout kind="warn" title="کاربران داخل ایران">
ورود با Google به اتصال به Google، و در Android به Google Play services هم، نیاز دارد. بعضی کاربران در ایران هیچ‌کدام را ندارند: گوشی‌هایی که بدون Google Play services فروخته شده‌اند، یا سرویس‌های Google که در دسترس نیستند. برای آن‌ها دکمه‌ی Google پیش از اینکه به Abrova Auth برسد شکست می‌خورد. ناشناس، ایمیل و رمز عبور، لینک یک‌بارمصرف و کد تلگرام بدون Google کار می‌کنند، پس دست‌کم یکی از آن‌ها را کنار دکمه‌ی Google بگذارید.
</Callout>

<H2 id="set-it-up-in-the-console" step={1}>راه‌اندازی در کنسول</H2>

1. در Google Cloud Console › **APIs & Services › Credentials**، OAuth client IDهایی را که اپ‌هایتان با آن‌ها وارد می‌شوند پیدا کنید (یا بسازید). Android، iOS و وب هر کدام client ID خودشان را دارند.
2. در کنسول ابرووا، **Abrova Auth › روش‌های ورود** را باز کنید، **Google** را روشن کنید و **همه‌ی** client IDهایی را که اپ‌هایتان استفاده می‌کنند اضافه کنید.

Abrova Auth فقط ID tokenی از Google را می‌پذیرد که audience آن یکی از این client IDها باشد.

<Callout kind="note" title="کدام client ID در توکن قرار می‌گیرد">
در Android با Credential Manager، و در `google_sign_in` وقتی `serverClientId` را می‌دهید، ID token برای client ID **وب** شما صادر می‌شود. client ID وب را به فهرست اضافه کنید، حتی اگر اپ وب ندارید.
</Callout>

<H2 id="the-nonce" step={2}>مقدار nonce</H2>

با تابع کمکی SDK یک **nonce خام** تصادفی بسازید، SHA-256 آن را به‌صورت hex با حروف کوچک به **Google** بدهید و مقدار خام را به **Abrova Auth**. ابرووا بررسی می‌کند که این دو با هم جور باشند و هر nonce را فقط یک بار می‌پذیرد. ID token باید کمتر از ۱۰ دقیقه عمر داشته باشد.

<ConfigTable headers={['SDK', 'nonce خام', 'مقدار برای 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="nonce الزامی است">
Abrova Auth ورود با Google بدون nonce خام را رد می‌کند (`INVALID_INPUT`)، به همین دلیل همه‌ی SDKها آن را الزامی کرده‌اند.
</Callout>

<H2 id="sign-in" step={3}>ورود</H2>

#### Android (Credential Manager)

`androidx.credentials:credentials`، `androidx.credentials:credentials-play-services-auth` و `com.google.android.libraries.identity.googleid:googleid` را به اپ اضافه کنید:

```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

با `google_sign_in` نسخه‌ی ۷:

```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

ID token مربوط به Google را با `AbrovaNonce.sha256(rawNonce)` به‌عنوان nonce درخواست کنید، سپس:

```swift
try await AbrovaAuth.shared.signInWithGoogle(idToken: idToken, rawNonce: rawNonce)
```

#### Web و React Native

`hashedNonce` را به‌عنوان `nonce` به Google Identity Services (وب) یا کتابخانه‌ی ورود با Google در React Native بدهید:

```typescript
const { rawNonce, hashedNonce } = await auth.createNonce();
// ... run Google's sign-in with nonce: hashedNonce, then:
await auth.signInWithGoogle({ idToken, rawNonce });
```

### ایمیل

Abrova Auth از ایمیل Google فقط وقتی استفاده می‌کند که Google بگوید تأییدشده است، و آن را (رمزگذاری‌شده) فقط وقتی ذخیره می‌کند که **ذخیره‌ی اطلاعات پروفایل** در **Abrova Auth › تنظیمات** روشن باشد. یک حساب Google و یک حساب Apple یا رمز عبور با همان ایمیل، کاربران جداگانه می‌مانند مگر اینکه کاربر آن‌ها را به هم وصل کند.

### وصل کردن Google به کاربرِ واردشده

برای ارتقای کاربر ناشناس، `linkGoogle(...)` را با همان آرگومان‌ها صدا بزنید. شناسه‌ی کاربر همان می‌ماند. اگر این حساب Google از قبل متعلق به کاربر دیگری باشد، فراخوانی با `PROVIDER_ALREADY_LINKED` شکست می‌خورد.

### خطاها

<ConfigTable headers={['کد', 'معنا']} rows={[
  ['NOT_CONFIGURED', 'Google روشن است، اما هیچ client ID وارد نشده است.'],
  ['INVALID_ID_TOKEN', 'Google آن را امضا نکرده، برای client IDی صادر شده که در فهرست شما نیست، بیش از ۱۰ دقیقه عمر دارد، یا nonce آن SHA-256 همان nonce خامی که فرستادید نیست.'],
  ['INVALID_INPUT', 'nonce خام فرستاده نشده یا بین ۱۶ تا ۲۵۶ کاراکتر نیست.'],
  ['NONCE_REUSED', 'این nonce قبلاً استفاده شده است. برای هر ورود یک nonce جدید بسازید.'],
  ['PROVIDER_ALREADY_LINKED', 'فقط هنگام وصل کردن: این حساب Google متعلق به کاربر دیگری است.'],
  ['METHOD_DISABLED', 'ورود با Google برای پروژه خاموش است.'],
]} />

- ایمیل و رمز عبور: https://abrova.ir/docs/auth/email-password

<Callout kind="note" title="ایمیل و رمز عبور">
کاربران با یک آدرس ایمیل و رمز عبور حساب می‌سازند و سپس با همان‌ها وارد می‌شوند. Abrova Auth ایمیل‌های تأیید و بازیابی رمز عبور را می‌فرستد؛ لینک‌ها اپ (یا صفحه‌ی وب) شما را با یک `token` یک‌بارمصرف باز می‌کنند و اپ آن را به SDK برمی‌گرداند.
</Callout>

<H2 id="set-it-up-in-the-console" step={1}>راه‌اندازی در کنسول</H2>

1. **Abrova Auth › روش‌های ورود:** **ایمیل و رمز عبور** را روشن کنید. **کوتاه‌ترین رمز عبور** (۸ تا ۱۲۸ کاراکتر، پیش‌فرض ۸) را تعیین کنید و مشخص کنید آیا کاربران پیش از ورود به **ایمیل تأییدشده** نیاز دارند یا نه.
2. **Abrova Auth › تنظیمات › آدرس‌های لینک:** آدرس‌هایی را که لینک‌های ایمیلی شما اجازه دارند باز کنند اضافه کنید، مثلاً `https://example.com/auth` یا `myapp://auth`. هر کدام باید یک آدرس `https://` یا URL scheme خودِ اپ شما باشد.

<H2 id="sign-up" step={2}>ثبت‌نام</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' });
```

نتیجه `verificationSent` (ایمیل تأیید ارسال شده است) و `signedIn` را به شما می‌گوید. وقتی **ایمیل تأییدشده الزامی است** روشن باشد، کاربر تا وقتی لینک را باز نکند و سپس وارد نشود، وارد نمی‌شود.

رمز عبور باید دست‌کم به اندازه‌ی کوتاه‌ترین طول تعیین‌شده برای پروژه باشد، حداکثر ۱۲۸ کاراکتر، و جزو رمزهای خیلی رایج نباشد. در غیر این صورت فراخوانی با `WEAK_PASSWORD` شکست می‌خورد. آدرسی که از قبل حساب دارد با `EMAIL_TAKEN` شکست می‌خورد.

<H2 id="sign-in" step={3}>ورود</H2>

<ConfigTable headers={['SDK', 'فراخوانی']} rows={[
  ['Flutter', 'signInWithEmail(email: email, password: password)'],
  ['iOS', 'signIn(email: email, password: password)'],
  ['Android', 'signIn(email, password)'],
  ['Web، React Native', 'signInWithEmail({ email, password })'],
]} />

رمز اشتباه و ایمیل ناشناخته هر دو با `INVALID_CREDENTIALS` شکست می‌خورند، تا پاسخ هرگز فاش نکند چه کسی حساب دارد. شکست‌های پشت سر هم برای یک آدرس یا از یک مکان کُند می‌شوند (`RATE_LIMITED`).

<H2 id="verify-the-e-mail" step={4}>تأیید ایمیل</H2>

لینک تأیید، `<your link address>?token=...` را باز می‌کند و **۲۴ ساعت** اعتبار دارد. `token` را بخوانید و به SDK بدهید:

<ConfigTable headers={['SDK', 'فراخوانی']} rows={[
  ['Flutter', 'verifyEmail(token)'],
  ['iOS', 'verifyEmail(token: token)'],
  ['Android', 'verifyEmail(token)'],
  ['Web، React Native', 'verifyEmail({ token })'],
]} />

تأیید فقط ایمیل را تأییدشده علامت می‌زند؛ کاربر را وارد نمی‌کند. برای ارسال دوباره‌ی ایمیل برای کاربرِ واردشده، `sendEmailVerification` را با یک `redirectUrl` صدا بزنید.

<H2 id="reset-a-forgotten-password" step={5}>بازیابی رمز عبور فراموش‌شده</H2>

1. `sendPasswordReset` را با ایمیل و یک `redirectUrl` صدا بزنید. پاسخ چه آدرس حساب داشته باشد چه نه، یکسان است.
2. ایمیل به `<redirectUrl>?token=...` لینک می‌دهد که **۳۰ دقیقه** اعتبار دارد و فقط یک بار قابل استفاده است.
3. صفحه‌ی «رمز عبور جدید» را نشان دهید و `resetPassword` را با token و رمز عبور جدید صدا بزنید.

```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);
```

بازیابی رمز، **همه‌ی** نشست‌های کاربر را پایان می‌دهد و ایمیل را تأییدشده علامت می‌زند. کاربر را وارد نمی‌کند: کاربر با رمز عبور جدید وارد می‌شود.

### دادن رمز عبور به کاربر ناشناس

`linkPassword` یک ایمیل و رمز عبور به کاربرِ واردشده (معمولاً ناشناس) اضافه می‌کند. شناسه همان می‌ماند. وقتی کاربر دیگری آن آدرس را داشته باشد، با `EMAIL_TAKEN` شکست می‌خورد.

### ایمیل‌ها

Abrova Auth سه ایمیل می‌فرستد: **تأیید ایمیل**، **بازیابی رمز عبور** و **لینک یک‌بارمصرف**. نام پروژه‌ی شما در آن‌ها می‌آید و از آدرس ابرووا ارسال می‌شوند. ارسال برای هر آدرس (چند عدد در ساعت) و برای هر پروژه محدود است.

<Callout kind="warn" title="آدرس‌های لینک الزامی‌اند">
`redirectUrl`ی که با یکی از آدرس‌های لینک شما شروع نشود، پیش از ارسال هر ایمیلی با `INVALID_INPUT` رد می‌شود. این کار جلوی سوءاستفاده از پروژه‌ی شما برای ارسال لینک‌هایی به مقصد دیگر را می‌گیرد.
</Callout>

### خطاها

<ConfigTable headers={['کد', 'معنا']} rows={[
  ['INVALID_CREDENTIALS', 'ایمیل یا رمز عبور اشتباه است.'],
  ['EMAIL_TAKEN', 'حسابی با این ایمیل از قبل وجود دارد.'],
  ['WEAK_PASSWORD', 'خیلی کوتاه، خیلی بلند، یا جزو رمزهای رایج است.'],
  ['EMAIL_NOT_VERIFIED', 'پروژه ایمیل تأییدشده می‌خواهد و این ایمیل هنوز تأیید نشده است.'],
  ['TOKEN_INVALID', 'لینک تأیید یا بازیابی نامعتبر است، قبلاً استفاده شده، یا منقضی شده است.'],
  ['INVALID_INPUT', 'ایمیل معتبر نیست، یا redirectUrl جزو آدرس‌های لینک شما نیست.'],
  ['NOT_CONFIGURED', 'ارسال ایمیل موقتاً در دسترس نیست.'],
  ['USER_DISABLED', 'این کاربر را در کنسول غیرفعال کرده‌اید.'],
]} />

- لینک یک‌بارمصرف: https://abrova.ir/docs/auth/magic-link

<Callout kind="note" title="لینک یک‌بارمصرف">
کاربر آدرس ایمیلش را تایپ می‌کند و یک لینک ورود دریافت می‌کند. با باز کردن لینک، همراه یک `token` یک‌بارمصرف به اپ شما برمی‌گردد و SDK آن را با یک نشست عوض می‌کند. رمزی برای به خاطر سپردن نیست؛ حساب اولین باری که آن آدرس وارد شود ساخته می‌شود.
</Callout>

<H2 id="set-it-up-in-the-console" step={1}>راه‌اندازی در کنسول</H2>

1. **Abrova Auth › روش‌های ورود:** **لینک یک‌بارمصرف** را روشن کنید.
2. **Abrova Auth › تنظیمات › آدرس‌های لینک:** آدرسی را که لینک باز می‌کند اضافه کنید، مثلاً `https://example.com/auth/magic` یا `myapp://auth/magic`.

در موبایل، کاری کنید که آن آدرس اپ شما را باز کند: یک custom URL scheme، یا برای آدرس `https://` یک universal link در Apple یا App Link در Android.

<H2 id="send-the-link" step={2}>ارسال لینک</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' });
```

پاسخ چه آدرس حساب داشته باشد چه نه، یکسان است. به کاربر بگویید صندوق ایمیلش را ببیند.

<H2 id="sign-in-with-the-link" step={3}>ورود با لینک</H2>

لینک، `<redirectUrl>?token=...` را باز می‌کند. token را بخوانید و وارد شوید:

```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 });
```

اولین ورود با یک آدرس، کاربر را می‌سازد و ایمیل را تأییدشده علامت می‌زند. لینک‌های بعدی به همان کاربر وارد می‌شوند.

### قواعد

<ConfigTable headers={['قاعده', 'مقدار']} rows={[
  ['اعتبار لینک', '۱۵ دقیقه'],
  ['تعداد استفاده', 'یک بار. باز کردن دوباره با TOKEN_INVALID شکست می‌خورد'],
  ['ایمیل برای هر آدرس', 'چند عدد در ساعت'],
  ['آدرس‌های لینک', 'فقط آن‌هایی که مجاز کرده‌اید؛ هر آدرس دیگری با INVALID_INPUT شکست می‌خورد'],
]} />

کاربرِ لینک یک‌بارمصرف و کاربرِ ایمیل و رمز عبور با یک آدرس، یک کاربرند: لینک مالکیت آدرس را ثابت می‌کند. کاربرانی که با Apple یا Google وارد شده‌اند جدا هستند، حتی با همان آدرس.

### خطاها

<ConfigTable headers={['کد', 'معنا']} rows={[
  ['TOKEN_INVALID', 'لینک نامعتبر است، قبلاً استفاده شده، یا بیش از ۱۵ دقیقه از آن گذشته است. لینک جدیدی بفرستید.'],
  ['INVALID_INPUT', 'ایمیل معتبر نیست، یا redirectUrl جزو آدرس‌های لینک شما نیست.'],
  ['RATE_LIMITED', 'لینک‌های بیش از حد برای این آدرس یا از این مکان. بعد از retryAfterSec دوباره امتحان کنید.'],
  ['USER_DISABLED', 'این کاربر را در کنسول غیرفعال کرده‌اید.'],
  ['NOT_CONFIGURED', 'ارسال ایمیل موقتاً در دسترس نیست.'],
  ['METHOD_DISABLED', 'لینک یک‌بارمصرف برای پروژه خاموش است.'],
]} />

- کد تلگرام: https://abrova.ir/docs/auth/telegram

<Callout kind="note" title="کد تلگرام">
کاربر شماره تلفنش را وارد می‌کند و یک کد ورود ۶ رقمی از **ربات تلگرام پروژه‌ی شما** می‌گیرد. جایی که تلگرام رایج است، این روش جای پیامک را می‌گیرد، بدون هزینه برای هر پیام. تلگرام تأیید می‌کند که شماره متعلق به حساب تلگرام کاربر است، پس کد همیشه فقط به صاحب آن شماره می‌رسد.
</Callout>

تلگرام در ایران فیلتر است اما پرکاربرد است، و به Google یا Apple وابسته نیست. کاربرانی که تلگرام ندارند به روش دیگری مثل ایمیل یا لینک یک‌بارمصرف نیاز دارند.

<H2 id="create-and-connect-a-bot" step={1}>ساخت و وصل کردن ربات</H2>

1. در تلگرام با **@BotFather** صحبت کنید، `/newbot` را بفرستید و یک نام و username برای ربات‌تان انتخاب کنید (مثلاً `MyAppLoginBot`). BotFather یک **bot token** به شما می‌دهد.
2. در کنسول ابرووا، **Abrova Auth › روش‌های ورود** را باز کنید، **تلگرام** را روشن کنید و bot token را جای‌گذاری کنید.

Abrova Auth توکن را با تلگرام بررسی می‌کند و ربات را وصل می‌کند. توکن رمزگذاری‌شده ذخیره می‌شود و دیگر نمایش داده نمی‌شود. از ربات فقط برای Abrova Auth استفاده کنید: ابرووا پیام‌های ورودی آن را در دست می‌گیرد.

<H2 id="how-the-user-signs-in" step={2}>کاربر چطور وارد می‌شود</H2>

<NumberedPipeline steps={[
  { title: 'کاربر شماره تلفن را وارد می‌کند', body: 'با قالب بین‌المللی، مثلاً +989121234567. اپ شما requestTelegramCode را صدا می‌زند.' },
  { title: 'فقط بار اول: کاربر ربات را وصل می‌کند', body: 'اگر این شماره هنوز با ربات شما صحبت نکرده باشد، پاسخ sent: false و یک botUrl دارد. آن را باز کنید: کاربر Start را می‌زند و روی «Share my phone number» ضربه می‌زند.' },
  { title: 'کد در تلگرام می‌رسد', body: 'یک کد ۶ رقمی با اعتبار ۵ دقیقه. بعد از بار اول، کدها بلافاصله می‌رسند (sent: true).' },
  { title: 'کاربر کد را تایپ می‌کند', body: 'اپ شما verifyTelegramCode را با شماره و کد صدا می‌زند.' },
]} />

ربات فقط شماره‌ی **خودِ** کاربر را می‌پذیرد که با دکمه‌ی تلگرام به اشتراک گذاشته شده باشد. مخاطبِ فورواردشده‌ی شخص دیگر رد می‌شود.

<H2 id="code" step={3}>کد</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 });
```

اولین کد موفق برای یک شماره، کاربر را می‌سازد. کدهای بعدی برای آن شماره به همان کاربر وارد می‌شوند.

### قواعد

<ConfigTable headers={['قاعده', 'مقدار']} rows={[
  ['کد', '۶ رقم، با اعتبار ۵ دقیقه'],
  ['تلاش‌ها', '۵ بار برای هر کد؛ بعد کد جدید بخواهید'],
  ['کد برای هر شماره', '۵ عدد در ساعت'],
  ['قالب شماره', 'بین‌المللی، با + و کد کشور'],
]} />

وقتی تلگرام روشن است، `getMethods()` نام کاربری ربات را به‌صورت `telegramBot` برمی‌گرداند، اگر بخواهید آن را نشان دهید («کدها از @MyAppLoginBot می‌آیند»).

### خطاها

<ConfigTable headers={['کد', 'معنا']} rows={[
  ['INVALID_CREDENTIALS', 'کد اشتباه است، منقضی شده، یا تعداد تلاش‌ها تمام شده است.'],
  ['INVALID_INPUT', 'شماره تلفن در قالب بین‌المللی نیست، یا کد ۶ رقمی نیست.'],
  ['RATE_LIMITED', 'کدهای بیش از حد برای این شماره یا از این مکان. بعد از retryAfterSec دوباره امتحان کنید.'],
  ['NOT_CONFIGURED', 'تلگرام روشن است، اما هیچ رباتی وصل نیست.'],
  ['USER_DISABLED', 'این کاربر را در کنسول غیرفعال کرده‌اید.'],
  ['METHOD_DISABLED', 'ورود با تلگرام برای پروژه خاموش است.'],
]} />

- کاربران و نشست‌ها: https://abrova.ir/docs/auth/users-sessions

<Callout kind="note" title="کاربران و نشست‌ها">
هر **کاربر** Abrova Auth متعلق به یک پروژه است و یک شناسه‌ی تصادفی دارد. **نشست** چیزی است که آن کاربر را روی یک دستگاه وارد نگه می‌دارد: یک access token کوتاه‌مدت برای محصولات ابرووا و یک refresh token بلندمدت که SDK آن را با access tokenهای جدید عوض می‌کند.
</Callout>

### کاربران

هر کاربر شناسه‌ای مثل `ru_4fK9xQ2mB7nT1pLz8RcV3w` دارد: `ru_` و ۲۲ حرف و رقم تصادفی. شناسه هرگز ایمیل، شماره تلفن یا شناسه‌ی حساب Apple یا Google را در خود ندارد، پس ذخیره‌اش در داده‌هایتان و نمایشش در logها امن است.

- **هر پروژه، یک فهرست کاربر.** یک شخص در دو پروژه‌ی شما، دو کاربر بی‌ارتباط است. کاربرِ یک پروژه هرگز نمی‌تواند به پروژه‌ی دیگر وارد شود.
- **چند راه ورود، یک کاربر.** کاربر می‌تواند بیش از یک روش ورود وصل‌شده داشته باشد (مثلاً اول ناشناس، بعد Apple، بعد رمز عبور). شناسه همان می‌ماند. [کاربران ناشناس و ارتقا](/docs/auth/upgrading) را ببینید.
- **بدون ادغام خودکار بر اساس ایمیل.** یک حساب Apple و یک حساب Google با ایمیل یکسان دو کاربرند، مگر اینکه کاربر عمداً آن‌ها را به هم وصل کند. ادغام بر اساس ایمیل یک روش شناخته‌شده برای تصاحب حساب‌هاست.

SDKها کاربر را به این شکل برمی‌گردانند:

<ConfigTable headers={['فیلد', 'معنا']} rows={[
  ['id', 'شناسه‌ی کاربر (ru_...). همه‌جای اپ از آن به‌عنوان شناسه‌ی کاربر استفاده کنید.'],
  ['anonymous', 'تا وقتی کاربر Apple، Google یا رمز عبور را وصل نکرده، true است.'],
  ['emailVerified', 'وقتی کاربر مالکیت آدرس ایمیل را ثابت کرده باشد true است (لینک تأیید، لینک یک‌بارمصرف، بازیابی رمز عبور، یا ایمیل تأییدشده‌ی Google).'],
  ['createdAt', 'زمان ساخت کاربر.'],
  ['providers', 'روش‌های ورود وصل‌شده، مثلاً apple، google، password.'],
]} />

### نشست‌ها

هر ورود یک نشست روی آن دستگاه شروع می‌کند. هر نشست دو توکن دارد:

| | access token | refresh token |
|---|---|---|
| چیست | توکن کاربر ابرووا (یک JWT امضاشده) | یک مقدار تصادفی که به‌تنهایی معنایی ندارد |
| طول عمر | **یک ساعت** | ۶۰ روز از آخرین استفاده، حداکثر یک سال از زمان ورود |
| نگه‌داری روی دستگاه | در حافظه | در حافظه‌ی امن (Keychain، حافظه‌ی متکی به Android Keystore، یا هر چه روی وب انتخاب کنید) |
| نگه‌داری در ابرووا | هیچ: با امضایش بررسی می‌شود | فقط هش آن |
| فرستاده می‌شود به | همه‌ی محصولات ابرووا | فقط Abrova Auth |

کاربری که دست‌کم هر ۶۰ روز یک بار اپ را باز کند، تا یک سال وارد می‌ماند. بعد از یک سال، یا بعد از ۶۰ روز بدون باز کردن اپ، کاربر دوباره وارد می‌شود.

#### access token

access token همان **توکن کاربر ابرووا** استاندارد است. Abrova Sync، Chat، Push، A/B Testing و Storage امضای آن را بررسی می‌کنند و کاربر را از آن می‌خوانند، پس هرگز لازم نیست خودتان شناسه‌ی کاربر را به آن‌ها بدهید. این توکن شامل این‌هاست:

<ConfigTable headers={['Claim', 'مقدار']} rows={[
  ['sub', 'شناسه‌ی کاربر (ru_...). این همان auth.uid در قوانین امنیتی Sync است.'],
  ['pid', 'پروژه‌ی شما. توکنِ پروژه‌ی دیگر همه‌جا رد می‌شود.'],
  ['exp', 'یک ساعت بعد از صدور.'],
  ['amr', 'کاربر چطور وارد شده: anonymous، apple، google، password، magic_link یا telegram.'],
]} />

#### تمدید

تمدید توکن‌ها کار شما نیست. SDK access token را نگه می‌دارد و وقتی یک SDK ابرووا (یا کد شما) آن را بخواهد، اگر بیش از ۲ دقیقه از اعتبارش مانده باشد همان را برمی‌گرداند و در غیر این صورت تمدیدش می‌کند. چند درخواست‌کننده که هم‌زمان آن را بخواهند، در یک تمدید شریک می‌شوند.

<Callout kind="note" title="چرخش و تشخیص استفاده‌ی دوباره">
هر تمدید یک refresh token **جدید** برمی‌گرداند و قبلی را بازنشسته می‌کند. اگر یک refresh token بازنشسته دوباره استفاده شود، یعنی کسی آن را کپی کرده است: Abrova Auth فوراً کل آن نشست را پایان می‌دهد و آن را در گزارش فعالیت ثبت می‌کند. کاربر واقعی فقط دوباره وارد می‌شود؛ نسخه‌ی کپی‌شده از کار می‌افتد. تمدیدهای هم‌زمان از یک اپ به‌طور امن مدیریت می‌شوند.
</Callout>

#### آفلاین و خطاهای شبکه

خطای شبکه هرگز کاربر را خارج نمی‌کند. SDK نشست را نگه می‌دارد و در درخواست بعدی دوباره تلاش می‌کند. کاربر فقط وقتی خارج می‌شود که Abrova Auth بگوید نشست تمام شده است.

### پایان دادن به نشست

<ConfigTable headers={['چه اتفاقی می‌افتد', 'نتیجه']} rows={[
  ['signOut()', 'نشست را روی این دستگاه پایان می‌دهد. هرگز شکست نمی‌خورد: دستگاه نشست را فراموش می‌کند، حتی وقتی آفلاین است.'],
  ['signOutEverywhere()', 'همه‌ی نشست‌های کاربر را روی همه‌ی دستگاه‌ها پایان می‌دهد.'],
  ['deleteAccount()', 'کاربر و همه‌ی نشست‌هایش را حذف می‌کند. امنیت و داده‌ها را ببینید.'],
  ['بازیابی رمز عبور', 'همه‌ی نشست‌های کاربر را پایان می‌دهد. کاربر با رمز عبور جدید وارد می‌شود.'],
  ['غیرفعال کردن کاربر در کنسول', 'همه‌ی نشست‌ها را پایان می‌دهد. ورود و تمدید تا وقتی کاربر را دوباره فعال نکنید USER_DISABLED برمی‌گردانند.'],
  ['استفاده از refresh token کپی‌شده', 'آن نشست را پایان می‌دهد (تشخیص استفاده‌ی دوباره).'],
  ['۶۰ روز بدون استفاده، یا یک سال عمر', 'نشست منقضی می‌شود. تمدید بعدی SESSION_EXPIRED برمی‌گرداند.'],
]} />

وقتی نشستی روی سرور پایان می‌یابد، SDK روی آن دستگاه در تمدید بعدی متوجه می‌شود، نشست را پاک می‌کند و به listener وضعیت ورود شما خبر می‌دهد (کاربر `null` می‌شود).

<Callout kind="warn" title="تا یک ساعت">
access tokenها با امضایشان بررسی می‌شوند، نه با جستجو. access tokenی که پیش از خروج از همه‌جا، غیرفعال‌سازی یا حذف صادر شده، در محصولات دیگر ابرووا تا زمان انقضا، حداکثر یک ساعت بعد، کار می‌کند. تمدید آن فوراً رد می‌شود، پس قابل تمدید نیست.
</Callout>

### در کنسول

**Abrova Auth › کاربران** فهرست کاربران پروژه را همراه روش‌های ورود، زمان ساخت و آخرین فعالیت‌شان نشان می‌دهد. از همان‌جا می‌توانید کاربری را غیرفعال یا فعال کنید، او را از همه‌جا خارج کنید، یا حذفش کنید.

- کاربران ناشناس و ارتقا: https://abrova.ir/docs/auth/upgrading

<Callout kind="note" title="کاربران ناشناس">
کاربر ناشناس یک کاربر واقعی Abrova Auth است که اطلاعات ورود خودش را ندارد: فقط دستگاهی که آن را ساخته نشستش را نگه می‌دارد. اپ شما می‌تواند بلافاصله با همه‌ی محصولات ابرووا از آن استفاده کند و بعداً، بدون از دست رفتن چیزی، از کاربر بخواهد به‌طور کامل وارد شود.
</Callout>

### چرا با ناشناس شروع کنیم

- **بدون دیوار ورود.** کاربر اول اپ شما را امتحان می‌کند. سندهای Sync، اتاق‌های چت و تخصیص‌های A/B test از همان ابتدا به یک شناسه‌ی کاربر پایدار تعلق دارند.
- **قوانین امنیتی از اولین صفحه.** `auth.uid` برای کاربر ناشناس هم مقدار دارد، پس قوانینی مثل `data.ownerId === auth.uid` داده‌های او را از کاربران دیگر محافظت می‌کنند.
- **آزمایش برای بازدیدکنندگانِ واردنشده.** Abrova A/B Testing برای هر کاربر به توکن کاربر نیاز دارد؛ کاربر ناشناس یکی دارد.

<H2 id="create-the-anonymous-user" step={1}>ساخت کاربر ناشناس</H2>

**ناشناس** را در **Abrova Auth › روش‌های ورود** روشن کنید، سپس:

```dart
if (AbrovaAuth.instance.currentUser == null) {
  await AbrovaAuth.instance.signInAnonymously();
}
```

اول بررسی کنید کاربر فعلی وجود دارد یا نه. SDK نشست ذخیره‌شده را هنگام اجرا بازیابی می‌کند؛ صدا زدن `signInAnonymously()` در هر اجرا، هر بار یک کاربر جدید می‌سازد. [ورود ناشناس](/docs/auth/anonymous) را ببینید.

<H2 id="upgrade-link-a-sign-in-method" step={2}>ارتقا: وصل کردن یک روش ورود</H2>

وقتی کاربر آماده است حسابش را نگه دارد، یک روش را به کاربر ناشناسِ واردشده **وصل** کنید. شناسه‌ی کاربر تغییر نمی‌کند، پس هر چه زیر آن ذخیره شده مال خودش می‌ماند.

<ConfigTable headers={['فراخوانی', 'چه چیزی را وصل می‌کند']} rows={[
  ['linkApple', 'ورود با Apple'],
  ['linkGoogle', 'ورود با Google'],
  ['linkPassword', 'یک آدرس ایمیل و رمز عبور'],
]} />

```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.
}
```

بعد از وصل کردن، کاربر می‌تواند روی هر دستگاهی با آن روش وارد شود و به همان حساب برسد. وصل کردن یک نشست تازه هم شروع می‌کند که SDK آن را در دست می‌گیرد.

<H2 id="when-the-account-already-exists" step={3}>وقتی حساب از قبل وجود دارد</H2>

اگر حساب Apple یا Google از قبل متعلق به کاربر دیگری از پروژه‌ی شما باشد، وصل کردن با `PROVIDER_ALREADY_LINKED` شکست می‌خورد (برای رمز عبور: `EMAIL_TAKEN`). هیچ چیز خودبه‌خود ادغام نمی‌شود: داده‌های دو کاربر هرگز بی‌خبر از شما یکی نمی‌شوند.

کاری که بیشتر اپ‌ها می‌کنند:

1. به کاربر بگویید این حساب از قبل وجود دارد.
2. ورود به آن را پیشنهاد دهید. ورود معمولی (`signInWithGoogle`) را صدا بزنید که جای نشست ناشناس را می‌گیرد.
3. اگر کاربر ناشناس داده‌ی ارزشمندی داشت، پیش از جابه‌جایی آن را در اپ خودتان به کاربرِ واردشده منتقل کنید، یا کنارش بگذارید.

<Callout kind="warn" title="ورود جای کاربر ناشناس را می‌گیرد">
صدا زدن یک روش ورود (نه روش link) وقتی کاربر ناشناسی وارد شده، دستگاه را به کاربر دیگر منتقل می‌کند. کاربر ناشناس حذف نمی‌شود، اما دیگر هیچ دستگاهی نشستش را ندارد، پس هرگز دوباره قابل دسترسی نیست. وقتی می‌خواهید شناسه بماند link کنید؛ وقتی حساب دیگر را می‌خواهید وارد شوید.
</Callout>

### سقف‌ها در برابر ربات‌ها

ورود ناشناس به هیچ اطلاعاتی نیاز ندارد، پس راحت‌ترین روش برای سوءاستفاده است. Abrova Auth آن را از سه راه محدود می‌کند:

- **برای هر آدرس دستگاه:** هجوم کاربران ناشناس جدید از یک آدرس کُند می‌شود.
- **برای هر پروژه در روز:** تا ۲۰۰ کاربر ناشناس جدید در روز. می‌توانید سقف کمتری در **Abrova Auth › تنظیمات › کاربران ناشناس** بگذارید.
- با عبور از سقف، `signInAnonymously()` با `RATE_LIMITED` شکست می‌خورد. کاربران موجود تأثیری نمی‌بینند.

### پاک‌سازی کاربران ناشناس رهاشده

کاربر ناشناسی که هرگز برنمی‌گردد، بعد از چند روز بدون ورود یا تمدید نشست حذف می‌شود: به‌طور پیش‌فرض **۹۰ روز**، قابل تنظیم از ۷ تا ۳٬۶۵۰ در **Abrova Auth › تنظیمات › کاربران ناشناس**. کاربرانی که یک روش را وصل کرده‌اند هرگز این‌طور حذف نمی‌شوند.

<Callout kind="note" title="پاک کردن داده‌ها در محصولات دیگر با شماست">
پاک‌سازی فقط کاربر را از Abrova Auth حذف می‌کند. سندهای Sync، پیام‌های Chat و داده‌های دیگری که زیر آن شناسه‌ی کاربر ذخیره شده‌اند سر جایشان می‌مانند. اگر لازم است، در پاک‌سازی خودتان آن‌ها را حذف کنید.
</Callout>

- کاربر فعال ماهانه و سقف‌ها: https://abrova.ir/docs/auth/mau

<Callout kind="note" title="کاربر فعال ماهانه">
هزینه‌ی Abrova Auth بر اساس **کاربر فعال ماهانه** (MAU) است: تعداد کاربران متفاوتی که در یک ماه تقویمی وارد شده‌اند یا نشست‌شان را تمدید کرده‌اند. هر کاربر **ماهی یک بار** شمرده می‌شود، هر چند بار هم اپ را باز کند و روی هر چند دستگاه.
</Callout>

### چه چیزی شمرده می‌شود

کاربر اولین باری که در یک ماه (به وقت UTC) یکی از این کارها را انجام دهد شمرده می‌شود:

- با هر روشی وارد شود، از جمله ورود ناشناس و وصل کردن یک روش، یا
- نشستی را تمدید کند (SDK این کار را در پس‌زمینه، تقریباً هر یک ساعت یک بار تا وقتی از اپ استفاده می‌شود، انجام می‌دهد).

بقیه‌ی کارها رایگان است: خواندن کاربر فعلی، فراخوانی محصولات دیگر ابرووا با توکن، خروج، حذف حساب. کاربری که اپ را نصب کرده و در ماه بعد دیگر بازش نکرده، در آن ماه شمرده نمی‌شود.

### رایگان در هر ماه، سپس هزینه از کیف پول

| | رایگان در هر ماه | بیشتر از آن |
|---|---|---|
| کاربر فعال ماهانه | ۱٬۰۰۰ | ۱۰٬۰۰۰ تومان برای هر ۱٬۰۰۰ کاربر، هزینه از کیف پول |
| کاربر ناشناس جدید در روز | ۲۰۰ | سقف روزانه: در آن روز کاربر ناشناس جدیدی ساخته نمی‌شود |
| روش‌های ورود | هر ۶ روش | شامل است |
| گزارش فعالیت | شامل است | شامل است |

پلن یا اشتراکی وجود ندارد. ابرووا از کیف پول تومانیِ پیش‌پرداخت برداشت می‌کند: هر وقت خواستید آن را شارژ می‌کنید و مصرفِ بیشتر از سهمیه‌ی رایگان از آن کم می‌شود. [صفحه‌ی قیمت‌ها](/pricing) را ببینید.

<Callout kind="wallet">۱٬۰۰۰ کاربر فعال ماهانه رایگان در هر ماه. هر ۱٬۰۰۰ کاربر بیشتر، ۱۰٬۰۰۰ تومان هزینه از کیف پول.</Callout>

### در سقف

#### وقتی کیف پول موجودی دارد

هیچ‌کس رد نمی‌شود. هزینه‌ی کاربرانِ بیشتر از ۱٬۰۰۰ کاربر رایگان، با نرخ ۱۰٬۰۰۰ تومان برای هر ۱٬۰۰۰، از کیف پول پرداخت می‌شود. شمارش ماه را در **Abrova Auth › نمای کلی** می‌بینید.

#### وقتی کیف پول خالی است

وقتی در این ماه ۱٬۰۰۰ کاربر فعال بوده‌اند و کیف پول نمی‌تواند هزینه‌ی بیشتر را بدهد، کاربرِ **جدیدِ** آن ماه نمی‌تواند وارد شود: فراخوانی با `MAU_LIMIT` شکست می‌خورد.

- کاربرانی که این ماه شمرده شده‌اند به کار ادامه می‌دهند: مثل همیشه وارد می‌شوند و نشست‌شان را تمدید می‌کنند.
- کاربری که رد شده نشست ذخیره‌شده‌اش را نگه می‌دارد. این نشست از اول ماه بعد، یا به محض اینکه کیف پول را شارژ کنید، دوباره کار می‌کند.
- هیچ چیز حذف نمی‌شود: کاربران و تنظیمات‌تان همان‌طور می‌مانند.

برای `MAU_LIMIT` پیام دوستانه‌ای نشان دهید («ورود فعلاً در دسترس نیست، لطفاً بعداً دوباره امتحان کنید»). کاربران‌تان نمی‌توانند مشکل را حل کنند؛ شما می‌توانید، با شارژ کیف پول.

### کاربر ناشناس جدید در روز

جدا از MAU، هر پروژه می‌تواند روزانه تا **۲۰۰ کاربر ناشناس جدید** بسازد. این سقف جلوی ربات‌ها را می‌گیرد تا فهرست کاربران (و شمارش MAU) شما را پر نکنند. می‌توانید سقف کمتری در **Abrova Auth › تنظیمات › کاربران ناشناس** بگذارید.

با عبور از سقف، `signInAnonymously()` با `RATE_LIMITED` و یک زمان تلاش دوباره شکست می‌خورد. کاربرانی که از قبل وجود دارند تأثیری نمی‌بینند و روش‌های ورود دیگر همچنان کار می‌کنند.

### شمارش درست

- **در هر بار اجرا کاربر ناشناس جدید نسازید.** اول ببینید کاربری وارد شده یا نه؛ SDK نشست را هنگام اجرا بازیابی می‌کند.
- **کاربران ناشناس رهاشده** بعد از ۹۰ روز بدون استفاده حذف می‌شوند (قابل تنظیم). در هر حال از ماه بعد از اینکه استفاده از اپ را کنار بگذارند، دیگر شمرده نمی‌شوند.
- **برای هر نفر یک کاربر.** به جای ساختن کاربر دوم، یک روش ورود را به کاربر ناشناس وصل کنید. [کاربران ناشناس و ارتقا](/docs/auth/upgrading) را ببینید.

کاربران فعال روزانه، کاربران جدید و تعداد کسانی که برمی‌گردند در [آمار استفاده](/docs/auth/usage-insights) هستند (برای هر پروژه جداگانه روشنش کنید).

- آمار استفاده: https://abrova.ir/docs/auth/usage-insights

<Callout kind="note" title="چند نفر از اپ شما استفاده می‌کنند، و آیا برمی‌گردند؟">
Abrova Auth از قبل ورود و تمدید نشست هر کدام از کاربران شما را می‌بیند. **آمار استفاده** این را به اعداد روزانه تبدیل می‌کند: کاربران فعال، کاربران جدید و کاربران بازگشتی. لازم نیست چیزی به اپ اضافه کنید: نه SDK جدید، نه داده‌ی جدید از دستگاه، و هیچ راه‌اندازی‌ای جز یک کلید.
</Callout>

### روشن کردن

آمار استفاده تا وقتی روشنش نکنید **خاموش** است؛ برای هر پروژه جداگانه در **Abrova Auth › تنظیمات › آمار استفاده** روشن می‌شود (مالکان و مدیران). شمارش از همان لحظه شروع می‌شود؛ چیزی از قبل پر نمی‌شود.

**منطقه‌ی زمانی** که روزها بر اساس آن شمرده می‌شوند را انتخاب کنید (پیش‌فرض UTC؛ برای کاربران داخل ایران `Asia/Tehran`) تا «امروز» با بازار شما جور باشد. این یک تنظیم برای هر پروژه است و برای همه‌ی کسانی که آن را می‌بینند یکسان است. تغییر از روز بعد اعمال می‌شود؛ روزهای گذشته اعدادشان را نگه می‌دارند، و در روزِ تغییر ممکن است بعضی کاربران دو بار شمرده شوند.

خاموش کردن، شمارش را متوقف می‌کند و اعداد استفاده‌ی پروژه را **حذف** می‌کند.

### چه چیزی می‌بینید

در **Abrova Auth › نمای کلی › استفاده**:

| | معنا |
|---|---|
| **فعال امروز** | تعداد کاربران متفاوتی که امروز فعال بوده‌اند |
| **کاربران فعال روزانه** | تعداد کاربران متفاوتِ فعال در هر روز (۳۰، ۹۰ یا ۴۰۰ روز) |
| **فعال هفتگی** | تعداد کاربران متفاوتِ فعال در این هفته (دوشنبه تا یکشنبه) |
| **فعال ماهانه** | تعداد کاربران متفاوتِ فعال در این ماه تقویمی — همان عددی که بر اساسش هزینه می‌پردازید |
| **ماندگاری** | میانگین کاربران فعال روزانه در ۳۰ روز گذشته ÷ فعال ماهانه («مردم در X درصد روزها از آن استفاده می‌کنند») |
| **کاربران جدید** | کاربرانی که در هر روز ساخته شده‌اند |
| **کاربران بازگشتی** | از کاربرانی که در یک روز ثبت‌نام کرده‌اند، چند نفر دقیقاً ۱، ۷ و ۳۰ روز بعد دوباره فعال بوده‌اند؛ به تفکیک هفته‌ی ثبت‌نام |
| **به تفکیک پلتفرم** | کاربران فعال روزانه برای هر پلتفرم SDK: Android، iOS، وب، Flutter، React Native |
| **به تفکیک روش ورود** | کاربران فعال روزانه برای هر روش: ناشناس، Apple، Google، رمز عبور، لینک یک‌بارمصرف، تلگرام |

اعداد در حدود یک دقیقه به‌روز می‌شوند. کاربران فعال هفتگی و ماهانه مربوط به هفته‌ی جاری و ماه تقویمی جاری‌اند، نه ۷ یا ۳۰ روزِ اخیر.

### «فعال» یعنی چه

کاربر در روزی فعال است که در آن روز **وارد شود** یا **نشستی را تمدید کند**. SDKها access token یک‌ساعته را وقتی کمتر از ۲ دقیقه از اعتبارش مانده و اپ شما (یا SDK دیگری از ابرووا) آن را می‌خواهد تمدید می‌کنند: در عمل وقتی اپ بعد از بیش از یک ساعت باز می‌شود، و تقریباً هر یک ساعت یک بار در حین استفاده.

- درخواستی که رد شود شمرده نمی‌شود: سقف کاربر ماهانه با کیف پول خالی (`MAU_LIMIT`)، کاربر غیرفعال، نشست منقضی یا پایان‌یافته.
- حذف یک کاربر، یا حذف کاربران ناشناس بی‌استفاده، روزهای گذشته را تغییر نمی‌دهد.

**کمبود شناخته‌شده.** کاربری که اپ را آخر شب و دوباره کمی بعد از نیمه‌شب، در همان یک ساعت، باز می‌کند، در روز دوم دیده نمی‌شود: توکنش هنوز معتبر است، پس چیزی به Abrova Auth نمی‌رسد. به همین دلیل اعداد روزانه ممکن است کمی کمتر باشند، هرگز بیشتر.

### چه چیزی ذخیره می‌شود

شمارش، نه ردیابی. Abrova Auth فقط ذخیره می‌کند **چند نفر** از کاربران شما در هر روز فعال بوده‌اند — مثلاً «۳۱۲ کاربر در ۲۴ اکتبر» — و هرگز فهرستی از روزها یا ساعت‌هایی که یک شخص از اپ شما استفاده کرده نگه نمی‌دارد.

- هیچ داده‌ی جدیدی از دستگاه خارج نمی‌شود؛ فقط درخواست‌هایی که Abrova Auth از قبل دریافت می‌کند شمرده می‌شوند.
- هیچ آدرس IP، ایمیل، شماره تلفن، توکن یا شناسه‌ی کاربری بخشی از شمارش نیست.
- اعداد فقط برای شماست: بدون شخص ثالث، بدون تبلیغات، بدون پروفایل‌سازی.
- شمارش‌ها ۴۰۰ روز نگه داشته می‌شوند.

می‌توانید آن را در سیاست حریم خصوصی خودتان توضیح دهید، مثلاً: *«تعداد افرادی را که هر روز از اپ استفاده می‌کنند با یک شناسه‌ی ناشناس می‌شماریم؛ بدون نام، بدون ایمیل، بدون ردیابی.»*

### رایگان و با موجودی کیف پول

آمار استفاده هزینه‌ی اضافه‌ای ندارد. اینکه کنسول چه مقدار نشان دهد بستگی دارد به اینکه پروژه‌ی شما فقط از سهمیه‌ی رایگان ماهانه استفاده می‌کند یا به‌صورت پرداخت به‌اندازه‌ی مصرف از موجودی کیف پول هزینه می‌کند:

| | فقط سهمیه‌ی رایگان | با موجودی کیف پول (پرداخت به‌اندازه‌ی مصرف) |
|---|---|---|
| فعال امروز، کاربران فعال روزانه | ۳۰ روز | ۴۰۰ روز |
| فعال هفتگی / ماهانه، ماندگاری، کاربران جدید | بله | بله |
| کاربران بازگشتی (روز ۱ / ۷ / ۳۰) | ۴ هفته‌ی اخیر | ۴۰۰ روز |
| به تفکیک پلتفرم / روش ورود | — | بله |
| API آمار | — | بله |

شمارش‌ها همیشه ۴۰۰ روز نگه داشته می‌شوند؛ فقط چیزی که نمایش داده می‌شود تغییر می‌کند، پس با شارژ کیف پول کل تاریخچه‌تان فوراً نمایش داده می‌شود.

### API آمار

برای داشبوردها و اسکریپت‌های خودتان، وقتی پروژه‌ی شما به‌صورت پرداخت به‌اندازه‌ی مصرف از موجودی کیف پول هزینه می‌کند. آن را **از سرور خودتان** با کلید API و کلید سرور صدا بزنید، هرگز از اپ یا مرورگر: کلید سرور نباید در کد سمت کلاینت قرار بگیرد. اپی که فقط کاربران را وارد می‌کند به هیچ‌کدام از این‌ها نیاز ندارد — کنسول همین اعداد را نشان می‌دهد.

```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` و `to` روزهایی در منطقه‌ی زمانی پروژه‌اند، با قالب `YYYY-MM-DD`. بدون آن‌ها کل بازه‌ای را که می‌توانید ببینید می‌گیرید؛ بازه‌ای که از آن بیرون بزند به همان کوتاه می‌شود.
- مقادیر `day1`، `day7` و `day30` تا وقتی cohort به اندازه‌ی کافی قدیمی نشده `null` هستند.
- فهرست IPهای مجاز کلید سرور پروژه‌ی شما اعمال می‌شود.

| وضعیت | `code` | معنا |
|---|---|---|
| 401 | `UNAUTHENTICATED` | کلید API یا کلید سرور نیست یا اشتباه است، یا متعلق به پروژه‌ی دیگری است |
| 403 | `LIMIT_REACHED` | API به موجودی کیف پول نیاز دارد (پرداخت به‌اندازه‌ی مصرف) |
| 429 | `RATE_LIMITED` | بیش از ۶۰ درخواست در دقیقه از یک آدرس |

### چه چیزی شامل نیست

رویدادها، قیف‌ها (funnel)، صفحه‌ها و ویژگی‌های سفارشی بخشی از Abrova Auth نیستند: این سرویس کاربران را می‌شمارد، نه کارهایی که انجام می‌دهند. چیزی مثل «آیا کاربران مرحله‌ی ۳ را تمام کردند» را در داده‌های خودتان نگه دارید، مثلاً یک سند Abrova Sync برای هر کاربر.

- امنیت و داده: https://abrova.ir/docs/auth/security

<Callout kind="note" title="امنیت و داده‌ها">
Abrova Auth تا جای ممکن کمترین اطلاعات را از کاربران شما نگه می‌دارد، هر چه را که مجبور است نگه دارد رمزگذاری می‌کند، و اطلاعات محرمانه (رمزهای عبور، توکن‌ها، کدها) را فقط به شکلی ذخیره می‌کند که نتوان آن را به مقدار اصلی برگرداند.
</Callout>

### چه چیزی ذخیره می‌شود

<ConfigTable headers={['داده', 'چه زمانی', 'چگونه']} rows={[
  ['شناسه‌ی کاربر، زمان ساخت، آخرین فعالیت', 'همیشه', 'بدون رمزگذاری (شناسه تصادفی است)'],
  ['روش‌های وصل‌شده', 'همیشه', 'اینکه کدام روش‌ها، به‌علاوه‌ی یک keyed hash از شناسه‌ی حساب Apple یا Google'],
  ['آدرس ایمیل', 'ایمیل و رمز عبور و لینک یک‌بارمصرف (ایمیل همان شناسه‌ی ورود است)', 'رمزگذاری‌شده، به‌علاوه‌ی یک keyed hash برای پیدا کردن حساب'],
  ['ایمیل و نام از Apple یا Google', 'فقط وقتی ذخیره‌ی اطلاعات پروفایل روشن است (به‌طور پیش‌فرض خاموش)', 'رمزگذاری‌شده'],
  ['شماره تلفن', 'ورود با تلگرام (شماره همان شناسه‌ی ورود است)', 'رمزگذاری‌شده، به‌علاوه‌ی یک keyed hash برای پیدا کردن حساب'],
  ['رمز عبور', 'ایمیل و رمز عبور', 'فقط هش یک‌طرفه'],
  ['refresh tokenها، tokenهای لینک ایمیلی، کدها، nonceها', 'تا وقتی معتبرند', 'فقط هش'],
]} />

**ذخیره‌ی اطلاعات پروفایل** را در **Abrova Auth › تنظیمات** فقط وقتی روشن کنید که اپ شما به ایمیل یا نامی که Apple و Google برمی‌گردانند نیاز دارد. وقتی خاموش است، این کاربران فقط با شناسه‌شان و هش شناسه‌ی حساب ارائه‌دهنده شناخته می‌شوند.

### رمزگذاری

- **در حالت ذخیره:** داده‌های شخصی (آدرس‌های ایمیل، نام‌ها و شماره تلفن‌ها) رمزگذاری‌شده ذخیره می‌شوند.
- **در حین انتقال:** همه‌ی درخواست‌ها از HTTPS استفاده می‌کنند.
- **رمزهای عبور:** به‌صورت هش یک‌طرفه ذخیره می‌شوند و هرگز به هیچ شکل خوانایی ذخیره یا log نمی‌شوند. ورود، چه ایمیل حساب داشته باشد چه نه، همان مدت زمان را می‌برد.
- **اطلاعات محرمانه‌ی پروژه‌ی شما** (bot token تلگرام و کلید Apple برای حذف حساب) رمزگذاری‌شده ذخیره می‌شوند و بعد از ذخیره دیگر نمایش داده نمی‌شوند.
- **logها** هرگز توکن، رمز عبور، آدرس ایمیل، شماره تلفن یا آدرس IP را به‌صورت خوانا ندارند.

### جداسازی پروژه‌ها

پروژه‌ی هر درخواست از کلید API آن تعیین می‌شود، هرگز از چیزی که اپ در درخواست می‌فرستد. کاربران، نشست‌ها و تنظیمات یک پروژه از پروژه‌ی دیگر قابل خواندن یا استفاده نیستند. هر access token نام پروژه‌اش را دارد و همه‌ی محصولات ابرووا توکنِ پروژه‌ی دیگر را رد می‌کنند.

### محافظت در برابر حمله‌ها

<ConfigTable headers={['تهدید', 'محافظت']} rows={[
  ['حدس زدن رمز عبور', 'سقف برای هر آدرس و هر ایمیل؛ پاسخ یکسان (INVALID_CREDENTIALS) برای ایمیل ناشناخته و رمز اشتباه.'],
  ['فهمیدن اینکه چه کسی حساب دارد', 'بازیابی رمز عبور و لینک یک‌بارمصرف همیشه پاسخ یکسان می‌دهند، چه آدرس حساب داشته باشد چه نه.'],
  ['ساخت کاربر توسط ربات‌ها', 'سقف برای هر آدرس و سقف روزانه‌ی کاربران ناشناس جدید برای هر پروژه.'],
  ['refresh token دزدیده‌شده', 'چرخش در هر تمدید؛ استفاده‌ی دوباره از توکن قدیمی نشست را پایان می‌دهد.'],
  ['access token دزدیده‌شده', 'یک ساعت عمر دارد. هرگز log نمی‌شود.'],
  ['ID token شنودشده‌ی Apple یا Google', 'هر nonce فقط یک بار کار می‌کند؛ ID tokenهای قدیمی‌تر از ۱۰ دقیقه رد می‌شوند.'],
  ['ID token صادرشده برای اپ دیگر', 'فقط برای bundle IDها، Services IDها و client IDهایی که برای این پروژه وارد کرده‌اید پذیرفته می‌شود.'],
  ['حدس زدن کد یا لینک', 'کدهای ۶ رقمی ۵ تلاش در ۵ دقیقه دارند؛ لینک‌های ایمیلی مقادیر تصادفی طولانی‌اند که فقط یک بار کار می‌کنند.'],
  ['لینک‌های ایمیلی به مقصد دیگر', 'لینک‌ها فقط آدرس‌های لینکی را که مجاز کرده‌اید باز می‌کنند.'],
]} />

با عبور از سقف، فراخوانی با `RATE_LIMITED` شکست می‌خورد و می‌گوید کی دوباره امتحان کنید (`retryAfterSec`).

### گزارش فعالیت

برای همه‌ی پروژه‌ها شامل است: **Abrova Auth › فعالیت** رویدادهای امنیتی پروژه‌ی شما را نشان می‌دهد: ساخت کاربران، ورودها و ورودهای ناموفق، روش‌های وصل‌شده، بازیابی رمز عبور، خروج از همه‌جا، استفاده‌ی دوباره از refresh token، غیرفعال، فعال یا حذف شدن کاربران، و تغییر تنظیمات. رویدادها آدرس مبدأ را به‌صورت هش‌شده نشان می‌دهند، تا بدون دیدن آدرس بفهمید دو رویداد از یک جا آمده‌اند.

### حذف حساب

Apple از اپ‌هایی که امکان ساخت حساب دارند می‌خواهد اجازه دهند کاربران حساب‌شان را داخل اپ حذف کنند. `deleteAccount()` را صدا بزنید:

- کاربر، همه‌ی نشست‌ها و روش‌های وصل‌شده‌اش، و هر چه Abrova Auth درباره‌ی او ذخیره کرده حذف می‌شود. این کار قابل بازگشت نیست.
- اگر کاربر با Apple وارد شده و شما **کلید حذف حساب** (Team ID، Key ID و کلید خصوصی `.p8` در **Abrova Auth › روش‌های ورود › Apple**) را تنظیم کرده باشید، Abrova Auth همان‌طور که Apple می‌خواهد، ورود با Apple این کاربر را برای اپ شما هم لغو می‌کند. وقتی کاربر با Apple وارد می‌شود `authorizationCode` مربوط به Apple را بفرستید، وگرنه این مرحله چیزی برای لغو ندارد.
- داده‌ها در محصولات دیگر ابرووا (سندهای Sync، پیام‌های Chat، فایل‌های Storage) حذف نمی‌شوند. پیش از صدا زدن `deleteAccount()`، تا وقتی توکن کاربر هنوز کار می‌کند، آن‌ها را از داخل اپ حذف کنید.

همچنین می‌توانید کاربر را از **Abrova Auth › کاربران** در کنسول حذف کنید.

- استفاده با محصولات دیگر ابرووا: https://abrova.ir/docs/auth/other-products

<Callout kind="note" title="یک کاربر برای همه‌ی محصولات ابرووا">
Abrova Sync، Chat، Push، A/B Testing و Storage کاربر اپ شما را با یک **توکن کاربر ابرووا**ی امضاشده می‌شناسند. بدون Abrova Auth، سرور خودتان این توکن را با کلید سرور می‌سازد. با Abrova Auth، توکن از قبل در SDK Auth هست: **token provider** آن را به SDKهای دیگر بدهید تا به‌عنوان کاربرِ واردشده عمل کنند.
</Callout>

<Callout kind="soon">Abrova Sync، Chat، Push، Storage و A/B Testing به‌زودی می‌آیند. این صفحه نشان می‌دهد وقتی راه بیفتند کاربر Auth را چطور می‌گیرند؛ فعلاً قابل استفاده نیستند. امروز کاربرِ واردشده با [ابرووا تریس](#abrova-trace-today) کار می‌کند.</Callout>

### ابرووا تریس، از امروز

ابرووا تریس فعال است. شناسه‌ی کاربر Abrova Auth را به آن بدهید تا خطاها و کرش‌ها نشان دهند برای کدام کاربر رخ داده‌اند. آن را بعد از ورود تنظیم کنید و بعد از خروج پاک کنید:

```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
```

تریس فقط شناسه‌ی کاربر را می‌گیرد؛ به توکن نیازی ندارد. [SDK Flutter تریس](/docs/trace/flutter-sdk)، [SDK iOS](/docs/trace/ios-sdk) و [SDK Android](/docs/trace/android-sdk) را ببینید.

### چه چیزی به دست می‌آورید

- **قوانین امنیتی Sync بدون سرور کار می‌کنند.** `auth.uid` همان شناسه‌ی کاربر Abrova Auth (`ru_...`) است، پس `data.ownerId === auth.uid` از سندهای هر کاربر محافظت می‌کند. [قوانین امنیتی Sync](/docs/sync/rules) را ببینید.
- **Chat می‌داند چه کسی صحبت می‌کند.** پیام‌ها به نام کاربرِ توکن فرستاده می‌شوند؛ هیچ‌کس نمی‌تواند به جای دیگری بنویسد.
- **قوانین دسترسی Storage کاربر را می‌بینند.** قوانینی مثل `users/{userId}/**` به هر کاربر اجازه می‌دهند فقط فایل‌های خودش را بخواند و بنویسد. [قوانین دسترسی Storage](/docs/storage/bucket-policies) را ببینید.
- **A/B Testing و Push** رویدادها، variantها و پیام‌های inbox را به کاربر وصل می‌کنند، از جمله کاربران ناشناسی که هنوز به‌طور کامل وارد نشده‌اند.
- **چیز اضافه‌ای برای وصل کردن نیست.** SDKهای دیگر یک token provider می‌گیرند. توکن همان توکنی است که سرور خودتان می‌ساخت.

### توکن چطور جریان پیدا می‌کند

<NumberedPipeline steps={[
  { title: 'یک SDK دیگر ابرووا به توکن نیاز دارد', body: 'هنگام شروع، پیش از یک درخواست، یا وقتی توکنش نزدیک انقضاست، provider را که به آن داده‌اید صدا می‌زند.' },
  { title: 'SDK Auth پاسخ می‌دهد', body: 'با access token فعلی، که اگر کمتر از ۲ دقیقه از اعتبارش مانده باشد اول تمدید می‌شود. فراخوانی‌های هم‌زمان در یک تمدید شریک می‌شوند.' },
  { title: 'محصول آن را بررسی می‌کند', body: 'امضا، پروژه و زمان انقضا را بررسی می‌کند و شناسه‌ی کاربر را از توکن برمی‌دارد.' },
]} />

وقتی کسی وارد نشده، provider توکنی برنمی‌گرداند (یا برای Chat خطا می‌دهد)، و هر SDK همان‌طور که مستنداتش می‌گوید منتظر کاربر می‌ماند.

### دادن token provider

این محصولات به‌زودی می‌آیند؛ فراخوانی‌های زیر نشان می‌دهند توکن را چطور خواهند گرفت.

هر جا SDKی شناسه‌ی کاربر خواست (`userId` در Chat، `setUserId` در A/B Testing)، شناسه‌ی کاربر را از Abrova Auth بدهید تا با توکن جور باشد.

#### 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` مقدار `null` برمی‌گرداند. `chatTokenProvider` به جای آن خطای `UNAUTHENTICATED` می‌دهد؛ کلاینت Chat را بعد از ورود بسازید.

#### 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` مقدار `nil` برمی‌گرداند؛ `strictTokenProvider` خطا می‌دهد.

#### 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` یک تابع suspend است که وقتی کسی وارد نشده `null` برمی‌گرداند؛ `strictTokenProvider` به جای آن خطا می‌دهد؛ `blockingTokenProvider` thread فراخواننده را block می‌کند و هرگز نباید روی 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,
});
```

### وقتی کاربر وارد یا خارج می‌شود

SDKهای دیگر توکنی را که دارند cache می‌کنند. بعد از ورود، خروج یا جابه‌جایی به کاربر دیگر، به آن‌ها بگویید دوباره از provider بخواهند:

<ConfigTable headers={['محصول', 'فراخوانی']} rows={[
  ['Abrova Sync', 'AbrovaSync.refreshUserToken() (Flutter، React Native، Web)؛ sync.userTokens.refresh() (Android)؛ sync.refreshUserToken() (iOS)'],
  ['Abrova A/B Testing', 'refreshUserToken() بعد از ورود؛ clearUserId() بعد از خروج'],
  ['Abrova Storage', 'storage.refreshUserToken() (همه‌ی پلتفرم‌ها). تا وقتی کسی وارد نشده، فراخوانی‌های فایل منتظر می‌مانند و بعد از ورود ادامه می‌یابند.'],
  ['Abrova Chat', 'کلاینت را برای کاربر جدید بسازید؛ قبلی را قطع کنید'],
]} />

به وضعیت ورود SDK Auth (`authStateChanges`، `onAuthStateChanged`، `addAuthStateListener` یا `authState`) گوش دهید و این فراخوانی‌ها را همان‌جا انجام دهید تا همه‌ی محصولات کاربر را دنبال کنند.

### نوشتن قوانین امنیتی برای کاربر

شناسه‌ی کاربر در توکن، همان `auth.uid` در قوانین Abrova Sync است. آن را در سندهایی که مال کاربرند ذخیره کنید:

```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',
});
```

سپس **Require signed user tokens** را برای Sync در کنسول روشن کنید تا فقط توکن امضاشده بتواند `auth.uid` را تعیین کند. [قوانین امنیتی Sync](/docs/sync/rules) را ببینید.

### همراه با سرور خودتان

همچنان می‌توانید روی سرور خودتان با کلید سرور (`POST https://auth.abrova.ir/users/token`) برای شناسه‌های کاربرِ خودتان توکن بسازید. هر دو نوع توکن در همه‌ی محصولات کار می‌کنند. برای هر اپ یک منبع شناسه‌ی کاربر نگه دارید تا یک شخص دو کاربر نشود.

- کدهای خطا: https://abrova.ir/docs/auth/error-codes

<Callout kind="note" title="کدهای خطا">
هر فراخوانیِ ناموفق یک `code` ثابت دارد. پیام‌هایی که به کاربران نشان می‌دهید را بر اساس همین کد و به زبان خودشان بسازید. `message` همراه آن یک راهنمای انگلیسی برای توسعه‌دهنده است: هرگز کلید محرمانه یا آدرس ایمیل ندارد و ممکن است تغییر کند.
</Callout>

### خطاها چطور می‌رسند

<ConfigTable headers={['SDK', 'نوع خطا', 'فیلد کد']} rows={[
  ['Flutter', 'AbrovaAuthException (برای وصل کردن: AbrovaProviderAlreadyLinkedException)', 'code، با AbrovaAuthErrorCode مقایسه کنید'],
  ['iOS', 'AbrovaAuthError', 'code، مثلاً .invalidCredentials'],
  ['Android', 'AbrovaAuthException', 'code، با AbrovaAuthErrorCode مقایسه کنید'],
  ['Web، React Native', 'AbrovaAuthError (با isAbrovaAuthError بررسی کنید)', "code، مثلاً 'INVALID_CREDENTIALS'"],
]} />

با عبور از سقف درخواست، خطا مدت انتظار را هم دارد: `retryAfterSec` (iOS، Android، Web، React Native) یا `retryAfter` (Flutter).

### کدهای Abrova Auth

<ConfigTable headers={['کد', 'HTTP', 'معنا', 'چه باید کرد']} rows={[
  ['INVALID_INPUT', '400', 'یک فیلد نیست یا قالبش درست نیست: ایمیل، قالب شماره تلفن، nonce کوتاه‌تر از ۱۶ کاراکتر، یا redirectUrl که جزو آدرس‌های لینک شما نیست.', 'درخواست را اصلاح کنید. ممکن است شیء fields نام فیلد را بگوید.'],
  ['INVALID_API_KEY', '401', 'کلید API ناشناخته است.', 'کلید عمومی را از Abrova Auth › راه‌اندازی بردارید.'],
  ['PRODUCT_DISABLED', '403', 'Abrova Auth برای پروژه روشن نیست.', 'آن را در تنظیمات › محصولات روشن کنید.'],
  ['METHOD_DISABLED', '403', 'این روش ورود برای پروژه خاموش است.', 'روشنش کنید، یا دکمه را پنهان کنید (از getMethods استفاده کنید).'],
  ['NOT_CONFIGURED', '400 / 503', 'روش روشن است اما راه‌اندازی نشده (شناسه‌های Apple یا Google نیست، ربات تلگرام نیست)، یا ارسال ایمیل در دسترس نیست (503).', 'راه‌اندازی را در کنسول کامل کنید. برای 503، بعداً دوباره امتحان کنید.'],
  ['INVALID_CREDENTIALS', '401', 'ایمیل یا رمز عبور اشتباه، یا کد تلگرام اشتباه یا منقضی‌شده.', 'از کاربر بخواهید بررسی کند و دوباره امتحان کند.'],
  ['EMAIL_TAKEN', '409', 'کاربر دیگری این ایمیل را دارد.', 'ورود یا بازیابی رمز عبور را پیشنهاد دهید.'],
  ['EMAIL_NOT_VERIFIED', '403', 'پروژه ایمیل تأییدشده می‌خواهد و این ایمیل تأیید نشده است.', 'از کاربر بخواهید ایمیل تأیید را باز کند؛ ارسال دوباره را پیشنهاد دهید.'],
  ['WEAK_PASSWORD', '400', 'رمز عبور خیلی کوتاه، بلندتر از ۱۲۸ کاراکتر، یا خیلی رایج است.', 'رمز عبور بلندتر و کم‌رایج‌تری بخواهید.'],
  ['INVALID_ID_TOKEN', '401', 'ID token مربوط به Apple یا Google برای این پروژه معتبر نیست: شناسه‌ی اپ اشتباه، منقضی‌شده، بیش از ۱۰ دقیقه عمر، یا nonce جور نیست.', 'شناسه‌ها را در کنسول و نحوه‌ی کار با nonce را بررسی کنید.'],
  ['NONCE_REUSED', '401', 'این nonce قبلاً برای یک ورود استفاده شده است.', 'برای هر ورود یک nonce جدید بسازید.'],
  ['PROVIDER_ALREADY_LINKED', '409', 'هنگام وصل کردن: حساب Apple یا Google متعلق به کاربر دیگری است.', 'به جای آن، ورود به همان حساب را پیشنهاد دهید.'],
  ['TOKEN_INVALID', '400 / 401', 'token لینک ایمیلی نامعتبر، استفاده‌شده یا منقضی است (400)، یا refresh token ناشناخته است (401).', 'لینک جدید بخواهید، یا دوباره وارد شوید.'],
  ['SESSION_EXPIRED', '401', 'نشست تمام شده است (۶۰ روز بدون استفاده، یا یک سال عمر).', 'SDK خارج می‌شود. از کاربر بخواهید وارد شود.'],
  ['SESSION_REVOKED', '401', 'نشست پایان داده شده است: خروج از همه‌جا، بازیابی رمز عبور، یا استفاده‌ی دوباره از refresh token.', 'SDK خارج می‌شود. از کاربر بخواهید وارد شود.'],
  ['USER_DISABLED', '403', 'این کاربر را در کنسول غیرفعال کرده‌اید.', 'SDK خارج می‌شود. به کاربر بگویید حسابش غیرفعال است.'],
  ['UNAUTHENTICATED', '401', 'فراخوانی به کاربرِ واردشده نیاز دارد و کاربری وارد نشده (یا access token معتبر نیست).', 'اول وارد شوید.'],
  ['RATE_LIMITED', '429', 'تلاش‌های بیش از حد، یا رسیدن به سقف روزانه‌ی کاربران ناشناس جدید.', 'به اندازه‌ی retryAfterSec صبر کنید و دوباره امتحان کنید.'],
  ['MAU_LIMIT', '403', '۱٬۰۰۰ کاربر فعال ماهانه‌ی رایگان این ماه تمام شده، کیف پول موجودی کافی برای بیشتر از آن ندارد، و این کاربر در این ماه جدید است.', 'پیام دوستانه‌ای نشان دهید. کیف پول را شارژ کنید تا کاربران جدید وارد شوند.'],
  ['LIMIT_REACHED', '403', 'یک قابلیت به موجودی کیف پول نیاز دارد (مثلاً API آمار استفاده). فراخوانی‌های ورود این کد را برنمی‌گردانند.', 'کیف پول را شارژ کنید.'],
  ['INTERNAL', '500 / 503', 'مشکلی در سمت ابرووا پیش آمده است.', 'بعداً دوباره امتحان کنید.'],
]} />

### کدهایی که SDKها اضافه می‌کنند

این کدها از SDK می‌آیند، نه از Abrova Auth: یا پاسخی نیامده، یا مشکل روی دستگاه است.

<ConfigTable headers={['کد', 'SDK', 'معنا']} rows={[
  ['NETWORK_ERROR', 'همه', 'پاسخی نیامد (آفلاین، timeout). نشست حفظ می‌شود؛ دوباره امتحان کنید.'],
  ['UNKNOWN', 'Flutter، Web، React Native', 'پاسخ قابل خواندن نبود.'],
  ['INVALID_RESPONSE', 'iOS، Android', 'پاسخ قابل خواندن نبود.'],
  ['SDK_NOT_CONFIGURED', 'iOS، Android', 'configure() پیش از آن صدا زده نشده است.'],
  ['NOT_SIGNED_IN', 'iOS، Android', 'strictTokenProvider یا فراخوانی‌ای که کاربرِ واردشده می‌خواهد، در حالی که کسی وارد نشده است.'],
  ['CANCELED', 'iOS', 'کاربر صفحه‌ی ورود با Apple را بست.'],
]} />

### خطاهایی که نشست را پایان می‌دهند

وقتی تمدید نشست با `SESSION_EXPIRED`، `SESSION_REVOKED`، `TOKEN_INVALID` یا `USER_DISABLED` شکست بخورد، SDK نشست را از روی دستگاه پاک می‌کند و listener وضعیت ورود شما `null` می‌گیرد. همان‌جا کاربر را به صفحه‌ی ورود ببرید. هر خطای دیگری، از جمله `NETWORK_ERROR`، نشست را حفظ می‌کند.


## Abrova Push (coming soon)

- شروع سریع: https://abrova.ir/docs/push/quick-start

### ۱ · نصب

پس از عرضه‌ی Abrova Push در دسترس است. SDK مثل همه‌ی SDKهای ابرووا از Abrova Center نصب می‌شود.

### ۲ · ارسال نوتیفیکیشن آزمایشی

از کنسول یا از سرور با کلید سرور. قالب‌ها متغیر و نسخه‌ی فارسی / انگلیسی یک پیام را پشتیبانی می‌کنند.

### ۳ · اندروید بدون سرویس‌های گوگل

Abrova Push به گوشی‌های بدون Google Play services، از جمله هواوی، می‌رسد. پل اختیاری FCM هم جایی که Firebase در دسترس است کار می‌کند.

- پیکربندی: https://abrova.ir/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>

- دستیارهای هوش مصنوعی: https://abrova.ir/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/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/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'],
]} />

- پل FCM اندروید: https://abrova.ir/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/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/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/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/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/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: https://abrova.ir/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);
});
```

- موضوع‌ها: https://abrova.ir/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`

- مدیریت خطا: https://abrova.ir/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'],
]} />

- ارسال: https://abrova.ir/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: https://abrova.ir/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);
```

- آمار: https://abrova.ir/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"
  }
]
```

- زمان‌بندی: https://abrova.ir/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"
```

- قالب‌ها: https://abrova.ir/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"],
]} />

- بخش‌ها: https://abrova.ir/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.

- وب‌هوک: https://abrova.ir/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: https://abrova.ir/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'],
]} />

- تیم‌ها: https://abrova.ir/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.

- محدودیت نرخ: https://abrova.ir/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;
    }
  }
}
```

- نوتیفیکیشن غنی: https://abrova.ir/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"
  }
}
```

- رسید تحویل: https://abrova.ir/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.

- پیام درون‌اپ: https://abrova.ir/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'],
  ]}
/>

- صندوق: https://abrova.ir/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: https://abrova.ir/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

- مدیریت دستگاه: https://abrova.ir/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)

- شروع سریع: https://abrova.ir/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>

- احراز هویت: https://abrova.ir/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.

- دستیارهای هوش مصنوعی: https://abrova.ir/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).

- اتاق‌ها و شرکت‌کنندگان: https://abrova.ir/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>

- پیام‌ها: https://abrova.ir/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>

- رویدادهای بلادرنگ: https://abrova.ir/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).
```

- ویجت‌ها: https://abrova.ir/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/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: https://abrova.ir/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`.

- تنظیمات نوتیفیکیشن: https://abrova.ir/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'],
]} />

- نمونه‌ها: https://abrova.ir/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)

- نصب: https://abrova.ir/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).

- راه‌اندازی: https://abrova.ir/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).

- دستیارهای هوش مصنوعی: https://abrova.ir/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/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).

- کوئری‌ها: https://abrova.ir/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).

- شنونده‌های زنده: https://abrova.ir/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).

- دسته‌ای: https://abrova.ir/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>

- ماندگاری آفلاین: https://abrova.ir/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>

- حل تعارض: https://abrova.ir/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>

- قوانین امنیتی: https://abrova.ir/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>

- ساختار داده: https://abrova.ir/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.

- نکات پلتفرم: https://abrova.ir/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/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/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/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/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/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/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'],
]} />

- دستیارهای هوش مصنوعی: https://abrova.ir/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).

- پرچم قابلیت: https://abrova.ir/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.

- هدف‌گیری: https://abrova.ir/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>

- محیط‌ها: https://abrova.ir/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>

- انتشار: https://abrova.ir/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>

- چندمقداری: https://abrova.ir/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>

- وابستگی‌ها: https://abrova.ir/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>

- زمان‌بندی: https://abrova.ir/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>

- endpointهای عمومی SDK: https://abrova.ir/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>

- روند ارزیابی: https://abrova.ir/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)

- شروع: https://abrova.ir/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.

- دستیارهای هوش مصنوعی: https://abrova.ir/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/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/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/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/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/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/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',
}
```

- SDK پرچم قابلیت: https://abrova.ir/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)

- معرفی: https://abrova.ir/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>

- دستیارهای هوش مصنوعی: https://abrova.ir/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/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/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/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/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/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/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/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/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.'],
]} />

- تبدیل تصویر: https://abrova.ir/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.

- سیاست سطل‌ها: https://abrova.ir/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)
]);
```

- بهترین روش‌های امنیتی: https://abrova.ir/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>