رفتن به مستندات
DIDBAN / SDK DOCUMENTATION

از نصب تا اولین رخدادِ قابل استفاده.

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

  1. 1
    نصبافزودن پکیج یا Agent
  2. 2
    اتصالتنظیم کلید، اپ و release
  3. 3
    بررسیارسال یک خطای کنترل‌شده
WEB SDK01

JavaScript / TypeScript

ثبت خودکار خطاهای مرورگر، درخواست‌های شبکه و ردپای رفتار کاربر.

@didban/browser-sdk

نصب SDK مرورگر

پکیج را با npm نصب کنید و آن را پیش از رندر اصلی برنامه مقداردهی کنید.

ترمینال
npm install @didban/browser-sdk

راه‌اندازی و release

توکن اپلیکیشن، محیط و شناسهٔ یکتای build را مشخص کنید.

مقدار release باید با مقداری که هنگام آپلود source map می‌فرستید یکسان باشد.

ورودی برنامه
import Didban from '@didban/browser-sdk';

Didban.init({
  apiKey: 'YOUR_API_KEY',
  appName: 'storefront-web',
  config: {
    baseUrl: 'https://api.getdidban.ir',
    environment: 'production',
    release: 'web@1.4.0',
  },
});

کاربر، سرنخ و خطای دستی

برای اینکه گزارش خطا قابل اقدام باشد، زمینهٔ کسب‌وکار را کنار خطا بفرستید.

ثبت زمینه
Didban.setUser({ id: 'user-42' });
Didban.addClue('Checkout opened', { cartId: 'cart-8' });
await Didban.capture(new Error('Payment failed'));

شبکه و درخواست‌های کند

خطاهای fetch و XHR خودکار ثبت می‌شوند. آستانهٔ درخواست کند را متناسب با SLO سرویس تنظیم کنید.

تنظیمات شبکه
config: {
  reportSlowRequests: true,
  slowRequestThresholdMs: 3000,
  ignoreUrls: ['/health'],
}

حریم خصوصی و داده‌های حساس

SDK فیلدهای رایج مانند password، token و apiKey را پاک‌سازی می‌کند؛ دادهٔ حساس اختصاصی محصول را هم پیش از ارسال فیلتر کنید.

بدنهٔ درخواست و پاسخ را فقط جایی فعال نگه دارید که سیاست نگهداری دادهٔ سازمان اجازه می‌دهد.

MOBILE SDK02

React Native / Expo

خطاهای JavaScript، مسیرهای اپ و شاخص‌های FPS در اپ موبایل.

@didban/react-native

نصب SDK موبایل

پکیج React Native را در پروژهٔ اپ نصب کنید.

ترمینال
npm install @didban/react-native

راه‌اندازی

مقداردهی را یک بار و در بالاترین نقطهٔ چرخهٔ اجرای اپ انجام دهید.

ورودی اپ
import Didban from '@didban/react-native';

Didban.init({
  apiKey: 'YOUR_API_KEY',
  appName: 'mobile-app',
  config: {
    baseUrl: 'https://api.getdidban.ir',
    environment: 'production',
    release: 'mobile@1.0.0',
  },
});

مسیر فعلی و زمینهٔ کاربر

در تغییر هر صفحه، مسیر فعلی را ثبت کنید تا breadcrumb ناوبری به خطا متصل شود.

زمینهٔ اپ
Didban.setUser({ id: 'user-42' });
Didban.setCurrentRoute('Checkout', { cartId: 'cart-8' });

کارایی صفحه و افت FPS

پروفایل صفحه و افت فریم را فعال کنید و نتیجه را همیشه روی build نوع release ارزیابی کنید.

تنظیمات کارایی
config: {
  enableScreenProfiling: true,
  reportFpsDrops: true,
  minimumFps: 50,
  slowFrameThresholdMs: 32,
}

محدودهٔ پوشش

نسخهٔ فعلی خطاهای thread جاوااسکریپت را پوشش می‌دهد. crash بومی iOS/Android یا توقف UI thread به ماژول native نیاز دارد.

این محدودیت را هنگام تعریف هشدار و انتظار تیم عملیات در نظر بگیرید.

SERVER AGENT03

Node.js و سرور

نبض CPU و RAM، رخدادهای سرویس و خطاهای شبکهٔ سمت سرور.

didban-server-agent

نصب Agent در Node.js

Agent را کنار سرویس Node.js نصب کنید.

ترمینال
npm install didban-server-agent

اتصال سرور به سازمان

برای هر سرور agentId یکتا و نامی قابل تشخیص بگذارید. کلید را از متغیر محیطی بخوانید.

راه‌اندازی Agent
import { DidbanServerAgent } from 'didban-server-agent';

const agent = new DidbanServerAgent({
  serverUrl: 'wss://api.getdidban.ir/api/v1/live',
  apiKey: process.env.DIDBAN_API_KEY,
  agentId: 'checkout-api-1',
  name: 'Checkout API',
});

agent.start();

خطای شبکه و سرور

فقط خطاهای زیرساختی مرتبط را با category مشخص بفرستید تا snapshot همان لحظه کنار رخداد نگهداری شود.

ثبت خطای شبکه
agent.captureException(error, {
  category: 'network',
  upstream: 'payments',
});

نمونهٔ CPU و RAM فقط برای خطاهای network/server نگهداری می‌شود تا مصرف فضای ذخیره‌سازی کنترل شود.

Agent مستقل Linux

برای سرویس‌های ASP.NET Core یا هر زبان دیگر، Agent مستقل را روی همان ماشین اجرا کنید؛ این روش زبان‌مستقل است.

نصب روی Linux
curl -fsSL https://raw.githubusercontent.com/GetDidban/didban-server-agent/master/install.sh \
  | sudo bash -s -- --api-key 'didban_...' \
  --server 'wss://api.getdidban.ir/api/v1/live' \
  --name 'Production API'

وضعیت ASP.NET Core

در حال حاضر SDK بومی APM برای .NET منتشر نشده است. Agent مستقل Linux نبض ماشین را ثبت می‌کند و اتصال مستقیم سرویس می‌تواند با پروتکل telemetry سازگار انجام شود.

RELEASE TOOLING04

CI/CD و Source Map

تبدیل stack فشرده به فایل و خط واقعی همان release.

@getdidban/cli

توکن محدود CI

از تنظیمات اپلیکیشن یک توکن با دسترسی source_maps:write بسازید و آن را در secretهای CI نگه دارید.

متغیر محیطی
DIDBAN_TOKEN=didban_sm_...

آپلود پس از build

فرمان آپلود را بلافاصله بعد از build و پیش از deploy اجرا کنید.

پایپ‌لاین CI
npx @getdidban/cli sourcemaps upload \
  --directory dist \
  --release "$GITHUB_SHA" \
  --url-prefix /assets \
  --delete-after-upload

تا زمان انتشار عمومی CLI، این فرمان را با نسخهٔ داخلی pipeline اجرا کنید.

تطبیق release

شناسهٔ release در SDK و فرمان آپلود باید دقیقاً برابر باشد. commit SHA انتخاب مطمئنی برای CI است.

  • source map را عمومی deploy نکنید؛ پس از آپلود حذفش کنید.

  • artifact هر release را مستقل نگه دارید.

  • شکست آپلود را باعث توقف pipeline کنید.