• نویسنده
• آگوست 18, 2019

راهنمای کامل مستندات وب سرویس نیواد (بخش ۳)

آیا تا به حال با خطاهایی در اپلیکیشن خود مواجه شده‌اید که کاربران گزارش می‌دهند اما شما نمی‌توانید آن‌ها را بازتولید کنید؟ مدیریت و ردگیری خطاها یکی از بزرگترین چالش‌های توسعه‌دهندگان اندروید است. خوشبختانه، وب سرویس نیواد با ارائه کتابخانه قدرتمند Nivad Core این مشکل را برای همیشه حل می‌کند.در بخش‌های قبلی مستندات، با مفاهیم اولیه API نیواد آشنا شدیم. اکنون در بخش سوم، به صورت کاملاً عملی به سراغ یکپارچه‌سازی این کتابخانه در پروژه‌های اندرویدی شما می‌رویم. این راهنما به شما نشان می‌دهد که چگونه به سادگی سیستم گزارش خطا و ثبت لاگ را در اپلیکیشن خود پیاده‌سازی کنید. پس با ما همراه باشید. 💡

مزایای کلیدی کتابخانه Nivad Core برای توسعه‌دهندگان

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

• 🎯 عیب‌یابی پیشگیرانه: با گزارش خودکار خطاها، قبل از اینکه کاربران متوجه شوند، مشکلات را شناسایی و رفع کنید.
• 📊 درک بهتر رفتار اپلیکیشن: با ثبت لاگ‌های سفارشی، جریان کار برنامه و نقاط بحرانی را به دقت تحلیل کنید.
• ⏰ صرفه‌جویی در زمان: به جای جستجوی دستی در میان هزاران خط کد، خطاها را به صورت متمرکز و با جزئیات کامل دریافت کنید.
• 🔧 بهبود تجربه کاربری (UX): با کاهش کرش‌ها و خطاهای پیش‌بینی‌نشده، رضایت و وفاداری کاربران خود را افزایش دهید.

پیش‌نیازها: برای شروع به چه چیزهایی نیاز دارید؟

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

1. Application ID
2. Application Secret

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

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

حالا به بخش هیجان‌انگیز ماجرا می‌رسیم. فرآیند اضافه کردن کتابخانه Nivad Core به پروژه اندروید شما بسیار ساده است و در سه مرحله کوتاه انجام می‌شود.

گام اول: اضافه کردن کتابخانه به پروژه

برای استفاده از قابلیت‌های نیواد، ابتدا باید فایل کتابخانه را به پروژه خود اضافه کنید. توصیه ما استفاده از Gradle در اندروید استودیو است که روشی مدرن و استاندارد محسوب می‌شود.

فایل jar کتابخانهٔ Nivad Core را  دریافت کرده و به پوشه libs در پروژه اندرویدتان اضافه کنید. سپس وابستگی آن را در فایل build.gradle تعریف نمایید.

گام دوم: تنظیم دسترسی‌های لازم

اپلیکیشن شما برای ارسال اطلاعات به سرورهای نیواد، به دسترسی اینترنت نیاز دارد. بنابراین، قطعه کد زیر را به فایل AndroidManifest.xml پروژه خود اضافه کنید. این کد باید خارج از تگ <application> قرار گیرد.

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

این دسترسی‌ها به کتابخانه اجازه می‌دهند تا گزارش‌ها و لاگ‌ها را به صورت ایمن به پنل شما ارسال کند.

گام سوم: راه‌اندازی اولیه کتابخانه (Initialization)

مهم‌ترین مرحله، معرفی کلیدهای شناسایی به کتابخانه است. بهترین مکان برای این کار، متد onCreate در کلاس Application شماست. اگر این کلاس را نساخته‌اید، یک کلاس جدید ایجاد کنید که از Application ارث‌بری کند.

public class YourApplicationClass extends Application {
    @Override
    public void onCreate() {
        super.onCreate();
        
        // Nivad Core Initialization
        NivadCore.initialize(
            this,
            "<YOUR_NIVAD_APPLICATION_ID>",
            "<YOUR_NIVAD_APPLICATION_SECRET>"
        );
    }
}

فراموش نکنید که مقادیر application id و application secret را که از پنل نیواد دریافت کرده‌اید، جایگزین کنید. برای راحتی بیشتر، این قطعه کد به صورت آماده در پنل مدیریت شما (بخش مستندات) نیز موجود است.

قابلیت‌های اصلی و کاربردهای API نیواد

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

۱. گزارش خطای خودکار (Automatic Exception Reporting)

این فوق‌العاده‌ترین ویژگی کتابخانه نیواد است. هرگونه خطا (Exception) که در برنامه شما رخ دهد و مدیریت (handle) نشود، به صورت خودکار به سرور نیواد گزارش می‌شود. ⚡️ این یعنی شما دیگر هیچ کرش غیرمنتظره‌ای را از دست نخواهید داد.

۲. گزارش خطای دستی (Manual Exception Reporting)

گاهی شما خطاها را در بلوک try-catch مدیریت می‌کنید، اما همچنان می‌خواهید از وقوع آن‌ها مطلع شوید. وب سرویس نیواد این امکان را نیز فراهم کرده است. با استفاده از کد زیر، می‌توانید خطاها را به صورت دستی گزارش دهید.

try {
    // بخشی از کد که ممکن است خطا ایجاد کند
} catch (Exception ex) {
    // خطا مدیریت شده است، اما آن را گزارش می‌دهیم
    NivadLogger.exception(ex);
}

۳. ثبت لاگ‌های سفارشی روی سرور (Server-Side Logging)

با کمک نیواد، می‌توانید پیام‌های متنی خاصی را برای ردگیری بهتر روی سرور ذخیره کنید. این لاگ‌ها در سه سطح مختلف دسته‌بندی می‌شوند تا تحلیل آن‌ها ساده‌تر باشد.

• ℹ️ سطح اطلاعات (Info): برای ثبت رویدادهای عادی و مهم برنامه.

    NivadLogger.i("PaymentFlow", "User entered payment page.");

• ⚠️ سطح هشدار (Warning): برای گزارش شرایط غیرمنتظره اما نه چندان بحرانی.

    NivadLogger.w("API_Response", "Image failed to load, using placeholder.");

• ❌ سطح خطا (Error): برای ثبت وقایع جدی که عملکرد بخشی از برنامه را مختل کرده‌اند.

    NivadLogger.e("Database", "Failed to save user profile.");

قدرت مانیتورینگ در دستان شما

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

حالا نوبت شماست! این کتابخانه را در پروژه خود پیاده‌سازی کنید و تجربه خود را در بخش نظرات با ما به اشتراک بگذارید. اگر سوالی دارید یا با مشکلی مواجه شدید، تیم پشتیبانی نیواد آماده پاسخگویی است. 👨‍💻

• برچسب ها:
• api
• Web API
• باگ اندروید
• گزارش باگ اندروید
• گزارش خطا
• نیواد
• وب سرویس