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
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: آبجکت اختیاری — هر فیلد زیر را میتوانید بفرستید:
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 ثابت بمانند.
چکلیست تست دستی (۰→۱۰۰)
init بزنید → Devices و Sessions یک ردیف جدید دارند.
i و e بزنید → در Events دو سطح INFO و ERROR میبینید.
logBatch بزنید → دو پیام batch ظاهر میشود.
sendIssue / sendFeedback → در Issues و Feedback ثبت شود.
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