SDK / Flutter (Dart)
v1.3.0 · آماده استفاده

SDK Flutter (Dart)

سرویس‌های ingest داخل SDK پیاده شده‌اند. کلید API را کامل بگذارید، init را با شناسه دستگاه (مثل androidId) بزنید و بعد فقط متدها را صدا بزنید.

پیش‌نیاز

  • پروژه در پنل مشتری و applicationId
  • API Key با هدر X-Api-Key
  • آدرس پایه سرویس: همین سامانه‌ای که مانوآل را از آن باز کرده‌اید (__LogBI_BASE__)

بسته http لازم است. نمونهٔ init با androidId و سریال کامل، هم‌تراز curl است.

نصب و استفاده (فقط use)

// فایل lib/bugbi.dart (LogBI class) را کپی کنید و http را در pubspec داشته باشید
await LogBI.init(
  apiUrl: '__LogBI_BASE__',
  apiKey: 'bbi_live_YOUR_FULL_API_KEY',
  applicationId: 'YOUR_APP_ID',
  deviceUid: '9774d56d682e549c',
  androidId: '9774d56d682e549c',
  hardwareSerial: 'SERIAL123',
  terminalId: 'T-10042',
  model: 'Pixel 8',
  osName: 'Android',
  osVersion: '14',
  appVersion: '1.0.0',
  manufacturer: 'Google',
  locale: 'fa-IR',
  timezone: 'Asia/Tehran',
);
await LogBI.e('Checkout', 'failed');
await LogBI.sendFeedback('UX', 'slow');

مرجع سرویس‌ها و متدها

برای هر متد، توضیح، پارامتر، endpoint، نمونه SDK و curl هم‌تراز آمده است. قبل از تست، bbi_live_YOUR_FULL_API_KEY را با کلید کامل پنل و YOUR_APP_ID را با شناسه پروژه عوض کنید. آدرس پایه از همین صفحه پر می‌شود: __LogBI_BASE__.

init

SDK را با آدرس سرور، کلید کامل API و شناسه پروژه آماده می‌کند؛ سپس دستگاه و نشست را ثبت می‌کند. فیلدهای شناسایی مثل مدل، سیستم‌عامل، androidId، hardwareSerial و terminalId را هم بفرستید تا در پنل «پیام‌ها بر اساس دستگاه» درست دیده شوند. در اندروید با init(context) شناسه سخت‌افزار خودکار پر می‌شود؛ در iOS از identifierForVendor و در وب از localStorage استفاده می‌شود.

الزامی: apiUrl · apiKey (کلید کامل پنل، مثل bbi_live_YOUR_FULL_API_KEY) · applicationId
شناسه دستگاه و نشست
deviceUid · sessionUid — اگر خالی بگذارید، SDK خودش می‌سازد
شناسه سخت‌افزار (پنل دستگاه‌محور)
androidId · hardwareSerial · terminalId هم در ثبت دستگاه و هم در metadata ذخیره می‌شوند
در پیام‌ها هر دستگاه یک ردیف است و با جست‌وجوی سریع روی این شناسه‌ها پیدا می‌شود — حتماً در نمونهٔ init بفرستید (مگر Android با init(context))
مشخصات دستگاه
model · osName · osVersion · appVersion
manufacturer · locale · timezone · metadata
نشست
userId · sessionMetadata
کنترل و کرش
enabled · registerDevice · registerSession · debug · captureCrashes (پیش‌فرض true — خاموش: false)
کرش به‌محض وقوع به‌صورت FATAL با eventTypeهایی مثل crash.uncaught / crash.promise / crash.flutter / crash.panic ثبت می‌شود
میان‌برهای d/i/w/e/f(tag, msg) متن را با پیشوند [tag] می‌سازند و tags + eventType را هم می‌فرستند
Android (۱٫۳٫۰+)
پیشنهاد: LogBI.init(context, …) تا ANDROID_ID و سریال خودکار پر شوند
در غیر این صورت androidId / hardwareSerial / terminalId را مثل نمونهٔ curl دستی بدهید
iOS
اگر deviceUid ندهید، از identifierForVendor استفاده می‌شود · کرش فقط Obj-C exceptions (NSSetUncaughtExceptionHandler) — نه Swift fatalError/signal
وب / React
deviceUid در localStorage نگه داشته می‌شود؛ در hybrid می‌توانید androidId / terminalId را هم پاس دهید
Go
کرش سراسری نیست — goroutine را با Guard بپیچید یا بعد از recover CapturePanic را صدا بزنید
POST /api/v1/ingest/devices (+ sessions)

مثال SDK (قابل اجرا)

await LogBI.init(
  apiUrl: '__LogBI_BASE__',
  apiKey: 'bbi_live_YOUR_FULL_API_KEY',
  applicationId: 'YOUR_APP_ID',
  deviceUid: '9774d56d682e549c',
  androidId: '9774d56d682e549c',
  hardwareSerial: 'SERIAL123',
  terminalId: 'T-10042',
  model: 'Pixel 8',
  osName: 'Android',
  osVersion: '14',
  appVersion: '1.0.0',
  manufacturer: 'Google',
  locale: 'fa-IR',
  timezone: 'Asia/Tehran',
);
print(LogBI.getDeviceUid());

تست معادل با curl

# ۱) ثبت دستگاه — همان فیلدهای نمونهٔ init در SDK
curl -s -X POST "__LogBI_BASE__/api/v1/ingest/devices" \
  -H "Content-Type: application/json" -H "X-Api-Key: bbi_live_YOUR_FULL_API_KEY" -H "X-SDK-Platform: manual" \
  -d '{"applicationId":"YOUR_APP_ID","deviceUid":"9774d56d682e549c","androidId":"9774d56d682e549c","hardwareSerial":"SERIAL123","terminalId":"T-10042","model":"Pixel 8","osName":"Android","osVersion":"14","appVersion":"1.0.0","manufacturer":"Google","locale":"fa-IR","timezone":"Asia/Tehran","metadata":{"LogBISdk":"1.3.0","sdkInt":34,"release":"14","codename":"REL","brand":"google","androidId":"9774d56d682e549c","hardwareSerial":"SERIAL123","terminalId":"T-10042"}}'

# ۲) ثبت نشست
curl -s -X POST "__LogBI_BASE__/api/v1/ingest/sessions" \
  -H "Content-Type: application/json" -H "X-Api-Key: bbi_live_YOUR_FULL_API_KEY" -H "X-SDK-Platform: manual" \
  -d '{"applicationId":"YOUR_APP_ID","deviceUid":"9774d56d682e549c","sessionUid":"ses-manual","startedAt":"2026-11-15T00:00:00.000Z","userId":"u_demo"}'

✓ تأیید: در پیام‌ها یک ردیف برای همان Android ID/سریال ببینید؛ در دستگاه‌ها و Sessions هم رکورد جدید ثبت شده باشد.

log(level, message, extra?)

یک رویداد با سطح دلخواه می‌فرستد. فیلدهای اختیاری قرارداد ingest را داخل extra بگذارید؛ SDK آن‌ها را به بدنه وصل می‌کند (شناسه پروژه/دستگاه/نشست از init می‌آید). برای فیلتر در پنل، tags بفرستید یا از میان‌برهای d/i/w/e/f استفاده کنید.

level: DEBUG | INFO | WARNING | ERROR | FATAL
message: متن رویداد (الزامی، حداکثر ۲۰٬۰۰۰ کاراکتر)
extra: آبجکت اختیاری — هر فیلد زیر را می‌توانید بفرستید:
طبقه‌بندی
eventType · category · subcategory · action
outcome: success | failure | unknown | blocked | allowed
severity: informational | low | medium | high | critical
بازیگر
actorId · actorType (user|service|system|anonymous) · actorEmail · actorName · actorRoles
منبع / هدف
resourceType · resourceId · resourceName
sourceService · sourceHost · sourceComponent · environmentName · releaseVersion
شبکه / HTTP / ردیابی
srcIp · dstIp · userAgent · geoCountry · geoCity
httpMethod · httpPath · httpStatus
requestId · correlationId · traceId · spanId
تشخیصی
tags · stackTrace · metadata · customProperties · raw
idempotencyKey · timestamp (ISO-8601)
POST /api/v1/ingest/events

مثال SDK (قابل اجرا)

// ۱) ساده
await LogBI.log('INFO', 'user opened checkout');

// ۲) خطا با extra
await LogBI.log('ERROR', 'payment failed', {
  'eventType': 'payment.charge',
  'category': 'billing',
  'outcome': 'failure',
  'severity': 'high',
  'tags': ['checkout', 'stripe'],
  'stackTrace': 'Exception at Checkout...',
  'metadata': {'orderId': 'ord_91', 'amount': 250000},
});

// ۳) SOC — لاگین مسدود
await LogBI.log('WARNING', 'login blocked', {
  'eventType': 'auth.login',
  'category': 'security',
  'outcome': 'blocked',
  'severity': 'critical',
  'actorId': 'u_1001',
  'actorEmail': 'user@example.com',
  'httpMethod': 'POST',
  'httpPath': '/v1/auth/login',
  'httpStatus': 429,
  'srcIp': '203.0.113.10',
  'tags': ['auth', 'rate-limit'],
  'customProperties': {'attempts': 5},
});

تست معادل با curl

# ساده
curl -s -X POST "__LogBI_BASE__/api/v1/ingest/events" \
  -H "Content-Type: application/json" -H "X-Api-Key: bbi_live_YOUR_FULL_API_KEY" -H "X-SDK-Platform: manual" \
  -d '{"applicationId":"YOUR_APP_ID","deviceUid":"9774d56d682e549c","sessionUid":"ses-manual","level":"INFO","message":"user opened checkout"}'

# خطا با metadata / tags
curl -s -X POST "__LogBI_BASE__/api/v1/ingest/events" \
  -H "Content-Type: application/json" -H "X-Api-Key: bbi_live_YOUR_FULL_API_KEY" -H "X-SDK-Platform: manual" \
  -d '{"applicationId":"YOUR_APP_ID","deviceUid":"9774d56d682e549c","sessionUid":"ses-manual","level":"ERROR","message":"payment failed","eventType":"payment.charge","category":"billing","outcome":"failure","severity":"high","tags":["checkout","stripe"],"metadata":{"orderId":"ord_91","amount":250000},"stackTrace":"Error: timeout"}'

# SOC کامل — لاگین مسدود
curl -s -X POST "__LogBI_BASE__/api/v1/ingest/events" \
  -H "Content-Type: application/json" -H "X-Api-Key: bbi_live_YOUR_FULL_API_KEY" -H "X-SDK-Platform: manual" \
  -d '{"applicationId":"YOUR_APP_ID","deviceUid":"9774d56d682e549c","sessionUid":"ses-manual","level":"WARNING","message":"login blocked","eventType":"auth.login","category":"security","subcategory":"bruteforce","action":"authenticate","outcome":"blocked","severity":"critical","actorId":"u_1001","actorType":"user","actorEmail":"user@example.com","actorName":"Ali","actorRoles":["customer"],"resourceType":"account","resourceId":"acc_77","sourceService":"api-gateway","environmentName":"production","releaseVersion":"2.4.1","srcIp":"203.0.113.10","userAgent":"Mozilla/5.0","geoCountry":"IR","httpMethod":"POST","httpPath":"/v1/auth/login","httpStatus":429,"requestId":"req_abc","correlationId":"corr_xyz","traceId":"trace_1","spanId":"span_9","tags":["auth","rate-limit"],"customProperties":{"attempts":5},"idempotencyKey":"login-block-u_1001"}'

✓ تأیید: پیام‌ها → دستگاه مربوطه → با فیلتر تگ، متن یا سطح پیدا شود.

logBatch(events[])

چند رویداد را در یک درخواست می‌فرستد (تا ۵۰۰ مورد). برای بافر سمت کلاینت و کم‌کردن تعداد HTTP مناسب است. اگر شناسه‌ها خالی باشند، از وضعیت بعد از init پر می‌شوند.

events: آرایه‌ای از آبجکت رویداد (حداقل message)
POST /api/v1/ingest/events/batch

مثال SDK (قابل اجرا)

await LogBI.logBatch([
  {'message': 'batch-1', 'level': 'INFO'},
  {'message': 'batch-2', 'level': 'WARNING'},
]);

تست معادل با curl

curl -s -X POST "__LogBI_BASE__/api/v1/ingest/events/batch" \
  -H "Content-Type: application/json" -H "X-Api-Key: bbi_live_YOUR_FULL_API_KEY" -H "X-SDK-Platform: manual" \
  -d '{"events":[{"applicationId":"YOUR_APP_ID","deviceUid":"9774d56d682e549c","sessionUid":"ses-manual","level":"INFO","message":"batch-1"},{"applicationId":"YOUR_APP_ID","deviceUid":"9774d56d682e549c","sessionUid":"ses-manual","level":"WARNING","message":"batch-2"}]}'

✓ تأیید: دو پیام batch-1 و batch-2 ظرف چند ثانیه در کاوشگر ظاهر شوند.

d / i / w / e / f

میان‌بر سطح لاگ (از ۱٫۲٫۱). متن به‌صورت [tag] message ساخته می‌شود و همزمان tags و eventType همان تگ را می‌گیرند تا در پنل قابل فیلتر باشند. سطح‌ها: d=DEBUG، i=INFO، w=WARNING، e=ERROR، f=FATAL.

tag: برچسب کوتاه برای فیلتر · message: متن پیام
POST /api/v1/ingest/events

مثال SDK (قابل اجرا)

await LogBI.d('Manual', 'level DEBUG from SDK manual');
await LogBI.i('Manual', 'level INFO from SDK manual');
await LogBI.w('Manual', 'level WARNING from SDK manual');
await LogBI.e('Manual', 'level ERROR from SDK manual');
await LogBI.f('Manual', 'level FATAL from SDK manual');

تست معادل با curl

curl -s -X POST "__LogBI_BASE__/api/v1/ingest/events" \
  -H "Content-Type: application/json" -H "X-Api-Key: bbi_live_YOUR_FULL_API_KEY" -H "X-SDK-Platform: manual" \
  -d '{"applicationId":"YOUR_APP_ID","deviceUid":"9774d56d682e549c","sessionUid":"ses-manual","level":"DEBUG","message":"[Manual] DEBUG curl test","eventType":"Manual","tags":["Manual"],"category":"manual"}'

curl -s -X POST "__LogBI_BASE__/api/v1/ingest/events" \
  -H "Content-Type: application/json" -H "X-Api-Key: bbi_live_YOUR_FULL_API_KEY" -H "X-SDK-Platform: manual" \
  -d '{"applicationId":"YOUR_APP_ID","deviceUid":"9774d56d682e549c","sessionUid":"ses-manual","level":"INFO","message":"[Manual] INFO curl test","eventType":"Manual","tags":["Manual"],"category":"manual"}'

curl -s -X POST "__LogBI_BASE__/api/v1/ingest/events" \
  -H "Content-Type: application/json" -H "X-Api-Key: bbi_live_YOUR_FULL_API_KEY" -H "X-SDK-Platform: manual" \
  -d '{"applicationId":"YOUR_APP_ID","deviceUid":"9774d56d682e549c","sessionUid":"ses-manual","level":"WARNING","message":"[Manual] WARNING curl test","eventType":"Manual","tags":["Manual"],"category":"manual"}'

curl -s -X POST "__LogBI_BASE__/api/v1/ingest/events" \
  -H "Content-Type: application/json" -H "X-Api-Key: bbi_live_YOUR_FULL_API_KEY" -H "X-SDK-Platform: manual" \
  -d '{"applicationId":"YOUR_APP_ID","deviceUid":"9774d56d682e549c","sessionUid":"ses-manual","level":"ERROR","message":"[Manual] ERROR curl test","eventType":"Manual","tags":["Manual"],"category":"manual"}'

curl -s -X POST "__LogBI_BASE__/api/v1/ingest/events" \
  -H "Content-Type: application/json" -H "X-Api-Key: bbi_live_YOUR_FULL_API_KEY" -H "X-SDK-Platform: manual" \
  -d '{"applicationId":"YOUR_APP_ID","deviceUid":"9774d56d682e549c","sessionUid":"ses-manual","level":"FATAL","message":"[Manual] FATAL curl test","eventType":"Manual","tags":["Manual"],"category":"manual"}'

✓ تأیید: در لاگ دستگاه، فیلتر تگ همان مقدار tag را نشان دهد یا متن شامل [tag] باشد.

sendIssue(title, detail?)

یک Issue تجمیعی بر اساس fingerprint ثبت یا به‌روز می‌کند. برای کرش و خطاهای قابل پیگیری در منوی Issues است؛ اگر عنوان تکراری باشد شمارنده بالا می‌رود.

title: عنوان · detail: توضیح اختیاری
POST /api/v1/ingest/issues

مثال SDK (قابل اجرا)

await LogBI.sendIssue('Manual issue', 'repro from SDK docs');

تست معادل با curl

curl -s -X POST "__LogBI_BASE__/api/v1/ingest/issues" \
  -H "Content-Type: application/json" -H "X-Api-Key: bbi_live_YOUR_FULL_API_KEY" -H "X-SDK-Platform: manual" \
  -d '{"applicationId":"YOUR_APP_ID","deviceUid":"9774d56d682e549c","sessionUid":"ses-manual","title":"Manual issue","detail":"curl repro","level":"ERROR"}'

✓ تأیید: منوی Issues → عنوان «Manual issue» دیده شود.

sendFeedback(subject, message)

بازخورد کاربر نهایی را ثبت می‌کند (جدا از لاگ فنی). در منوی Feedback دیده می‌شود و وضعیتش قابل تغییر است.

subject: موضوع · message: متن بازخورد
POST /api/v1/ingest/feedback

مثال SDK (قابل اجرا)

await LogBI.sendFeedback('UX', 'docs feedback test');

تست معادل با curl

curl -s -X POST "__LogBI_BASE__/api/v1/ingest/feedback" \
  -H "Content-Type: application/json" -H "X-Api-Key: bbi_live_YOUR_FULL_API_KEY" -H "X-SDK-Platform: manual" \
  -d '{"applicationId":"YOUR_APP_ID","deviceUid":"9774d56d682e549c","sessionUid":"ses-manual","subject":"UX","message":"docs feedback test"}'

✓ تأیید: منوی Feedback → موضوع UX دیده شود.

setDeviceString / Integer / Boolean / setDeviceKey

یک ویژگی روی دستگاه جاری می‌گذارد تا بعداً قابل جست‌وجو باشد. متدهای String/Integer/Boolean نوع را مشخص می‌کنند؛ setDeviceKey مقدار خام می‌فرستد. برای بخش‌بندی (مثلاً plan، beta، locale، build) مناسب است.

key: نام ویژگی · value: مقدار متناسب با نوع
POST /api/v1/ingest/device-attributes

مثال SDK (قابل اجرا)

await LogBI.setDeviceString('plan', 'starter');

تست معادل با curl

curl -s -X POST "__LogBI_BASE__/api/v1/ingest/device-attributes" \
  -H "Content-Type: application/json" -H "X-Api-Key: bbi_live_YOUR_FULL_API_KEY" -H "X-SDK-Platform: manual" \
  -d '{"applicationId":"YOUR_APP_ID","deviceUid":"9774d56d682e549c","key":"plan","value":"starter"}'

curl -s -X POST "__LogBI_BASE__/api/v1/ingest/device-attributes" \
  -H "Content-Type: application/json" -H "X-Api-Key: bbi_live_YOUR_FULL_API_KEY" -H "X-SDK-Platform: manual" \
  -d '{"applicationId":"YOUR_APP_ID","deviceUid":"9774d56d682e549c","key":"build","value":42}'

curl -s -X POST "__LogBI_BASE__/api/v1/ingest/device-attributes" \
  -H "Content-Type: application/json" -H "X-Api-Key: bbi_live_YOUR_FULL_API_KEY" -H "X-SDK-Platform: manual" \
  -d '{"applicationId":"YOUR_APP_ID","deviceUid":"9774d56d682e549c","key":"beta","value":true}'

curl -s -X POST "__LogBI_BASE__/api/v1/ingest/device-attributes" \
  -H "Content-Type: application/json" -H "X-Api-Key: bbi_live_YOUR_FULL_API_KEY" -H "X-SDK-Platform: manual" \
  -d '{"applicationId":"YOUR_APP_ID","deviceUid":"9774d56d682e549c","key":"locale","value":"fa-IR"}'

✓ تأیید: جزئیات دستگاه → attributes شامل plan / build / beta / locale.

getDeviceUid / getSessionUid

شناسه دستگاه و نشست فعلی را از حافظه SDK می‌خواند. برای دیباگ یا الصاق به لاگ‌های خودتان است و درخواست شبکه نمی‌زند.

بدون پارامتر
— (محلی)

مثال SDK (قابل اجرا)

console.log(LogBI.getDeviceUid(), LogBI.getSessionUid());

تست معادل با curl

# فقط سمت SDK — درخواست شبکه ندارد

✓ تأیید: همان UIDهایی که بعد از init چاپ شده‌اند تا پایان عمر process ثابت بمانند.

چک‌لیست تست دستی (۰→۱۰۰)

  1. init بزنید → Devices و Sessions یک ردیف جدید دارند.
  2. i و e بزنید → در Events دو سطح INFO و ERROR می‌بینید.
  3. logBatch بزنید → دو پیام batch ظاهر می‌شود.
  4. sendIssue / sendFeedback → در Issues و Feedback ثبت شود.
  5. setDeviceString("plan","starter") → روی دستگاه attribute دیده شود.
# نمونه پشت‌سرهم با curl (کلید و App ID را کامل جایگزین کنید)
export HOST=__LogBI_BASE__
export KEY=bbi_live_YOUR_FULL_API_KEY
export APP=YOUR_APP_ID
export DEVICE=9774d56d682e549c
curl -s -X POST "$HOST/api/v1/ingest/events" -H "Content-Type: application/json" -H "X-Api-Key: $KEY" \
  -d "{\"applicationId\":\"$APP\",\"deviceUid\":\"$DEVICE\",\"androidId\":\"$DEVICE\",\"level\":\"INFO\",\"message\":\"smoke from docs\"}"

Endpointها (داخل SDK)

  • POST /api/v1/ingest/events
  • POST /api/v1/ingest/events/batch
  • POST /api/v1/ingest/devices
  • POST /api/v1/ingest/sessions
  • POST /api/v1/ingest/issues
  • POST /api/v1/ingest/feedback
  • POST /api/v1/ingest/device-attributes

محتوای بسته دانلود

lib/bugbi.dart · pubspec.yaml