راه‌اندازی

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

برای انجام موفق این کار باید تمام مراحل زیر را به ترتیب انجام دهید:

۱- نصب کتابخانه

۲- مقداردهی اولیه

۳- ثبت کاربر


۱- نصب کتابخانه

برای نصب از طریق npm:

npm install chabokpush --save

یا yarn:

yarn add chabokpush

و یا با استفاده از CDN، چابک را به پروژه خود اضافه کنید.

<script src="https://unpkg.com/chabokpush/dist/chabokpush.min.js"></script>

افزودن Service Worker

برای ارسال پوش‌نوتیفیکشن در پس‌زمینه (‌Background) باید فایل ChabokSDKWorker.js را از این لینک دریافت نموده و در روت پروژه قرار دهید.

اگر از Github Desktop استفاده می‌کنید، برای دریافت آن می‌توانید از این لینک استفاده نمایید.

اگر هم از Webpack استفاده می‌کنید، می‌توانید از پلاگین CopyWebpackPlugin‍ برای انتقال service worker به پوشه dist استفاده نمایید.

 new CopyWebpackPlugin([
      {
        from: path.resolve(__dirname, '/node_modules/chabokpush/dist/ChabokSDKWorker.js'),
        to: path.resolve(__dirname, '/dist'),
        ignore: ['.*']
      }
    ])

نکته :‌ توجه داشته باشید که service worker فقط روی دامنه‌های https کار می‌کند.

مدل نسخه‌گذاری در چابک (Semantic Versioning)

چابک از مدل نسخه‌گذاری MAJOR.MINOR.PATCH استفاده می‌کند. همه تغییرات نسخه‌ها بلافاصله پس از انتشارشان به صورت موردی در صفحه لیست تغییرات برای اطلاع شما اضافه می‌شوند. برای همین توصیه می‌کنیم این صفحه را حتما مطالعه نمایید. این موارد برای هر نسخه در دو بخش ارتقا (در صورت وجود ارتقا) و تغییرات برای شما نمایش داده شده‌ است.

  • Patch: تغییرات در این سطح شامل Bug Fix و قابلیت‌های بسیار کوچک می‌باشد. به روز رسانی به این نسخه‌ها نیاز به تغییری در کد ندارد. برای آگاهی از آن‌ها، باید بخش تغییرات را مطالعه کنید. به عنوان مثال به‌ روز رسانی کتابخانه چابک از نسخه 2.13.0 به نسخه 2.13.2 مربوط به این سطح می‌شود.
  • Minor: تغییرات در این سطح شامل قابلیت‌های بزرگتر و تغییر در کارکرد (Functionality) کتابخانه می‌شود. در به روز رسانی به این نسخه‌ها حتما باید بخش ارتقا و تغییرات صفحه لیست تغییرات را با دقت مطالعه کنید. در صورت بروز هر گونه مشکل در نتیجه رعایت نکردن نکات بخش ارتقا و تغییرات در به روز رسانی به نسخه‌های Minor، تیم چابک مسئولیتی را نمی‌پذیرد. توصیه می‌کنیم که هر سه تا شش ماه اقدام به بررسی نسخه‌های Minor نمایید. به عنوان مثال به‌ روز رسانی کتابخانه چابک از نسخه 2.12.1 به نسخه 2.13.2 مربوط به این سطح می‌شود.
  • Major: این سطح از تغییرات مخصوص بازنویسی و یا تغییرات اساسی در کتابخانه چابک است. در به روز رسانی به این نسخه‌ها حتما باید بخش ارتقا و تغییرات تغییرات صفحه لیست تغییرات را با دقت مطالعه کنید. در صورت بروز هر گونه مشکل در نتیجه رعایت نکردن نکات بخش ارتقا و تغییرات در به روز رسانی به نسخه‌های Major، تیم چابک مسئولیتی را نمی‌پذیرد. بنابراین توصیه می‌کنیم که هر یک سال اقدام به بررسی نسخه‌های Major نمایید. به عنوان مثال به‌روزرسانی کتابخانه چابک از نسخه 1.0.1 به نسخه 2.13.2 مربوط به این سطح می‌شود.


۲- مقدار‌دهی اولیه (Initialize)

برای ارتباط با سرور چابک، لازم است یک نمونه از کلاس chabokpush بسازید و آن را مقدار‌دهی کنید.

برای مقدار‌دهی اولیه می‌بایست از طریق متد chabok اطلاعات حساب چابک و تنظیمات اولیه را وارد نمایید. در این متد به جای پارامتر‌های APP_ID ,API_KEY(SDK_KEY), SDK_USERNAME, SDK_PASSWORD مقادیر مربوط به حساب چابک خود را وارد نمایید. نحوه ایجاد حساب در بخش پیش‌نیازها توضیح داده‌ شده است. در صورت داشتن حساب چابک هم می‌توانید این مقادیر را از پنل بخش تنظیمات قسمت ** دسترسی‌ و توکن‌ها** بردارید.

نکته :‌ تمامی متدهایی که در این بخش بیان می‌شود باید تنها یک بار فراخوانی شود.

به قطعه کد زیر دقت کنید:

const auth = {
  appId: 'APP_ID',
  apiKey: 'API_KEY(SDK_KEY)',
  username: 'USERNAME',
  password: 'PASSWORD',
  devMode: true
}
const options = {
      webpush: {
        enabled: true,
        publicKey: 'VAPID_Public_Key'
      },
      silent: false,
    };
const chabok = new chabokpush.Chabok(auth, options)

مقدار devMode تعیین می‌کند که اپلیکیشن شما به محیط آزمایشی (Sandbox) و یا عملیاتی (Production) چابک متصل شود. این موضوع بستگی به این دارد که حساب کاربری شما روی کدام محیط تعریف شده باشد. مقدار true به محیط آزمایشی و مقدارfalse به محیط عملیاتی متصل می‌شود. در نظر داشته باشید، هر محیط به کلیدهای دسترسی (appId, apiKey,username و password) خودش در ایجاد کلاس نیاز دارد. بنابراین در صورت تغییر مقدار devMode کلید‌های دسترسی آن هم باید تغییر داده شوند.

تنظیمات اولیه
توضیحات پیش‌فرض نوع پارامتر
    Object [options]
فعال/غیرفعال‌سازی ارتباط آنی true Boolean [options.realtime]
    Object [options.webpush]
فعال‌سازی پوش ‌نوتیفیکیشن false Object [options.webpush.enabled]
پوش‌نوتیفیکیشن Public Key null String [options.webpush.publicKey]
دریافت مخفی پیام true Boolean [options.silent]

نکته : برای استفاده از چابک در محیط عملیاتی مقدار devMode را false کنید. برای تغییر به محیط عملیاتی باید از پنل بخش تنظیمات درخواست خود را ثبت نمایید تا پس از تایید، اطلاعات جدید حسابتان (appId, apiKey,username و password) تعیین گردد.


۳- ثبت کاربر (Register)

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

با استفاده از متد register می‌توانید یک نام کاربری به هر کاربر اختصاص دهید. این متد شناسه کاربر را گرفته و کاربر را با آن شناسه روی سرور چابک ثبت نام می‌کند.

    chabok.register('<USER_ID>')

نکته : متد register باید فقط یک بار در طول اجرا اپلیکیشن فراخوانی شود.

نکته امنیتی : مقدار USER_ID را هرگز به صورت خام در LocalStorage ذخیره نکنید، چون این مقدار شناسه معنادار می‌باشد و می‌توان با آن کاربر را روی چابک ثبت‌نام کرد. برای این منظور می‌توانید از متد ()chabok.getUserId چابک استفاده کنید که شناسه کاربر را به صورت رمزنگاری شده نگه‌ می‌دارد.

if (chabok.isRegistered()) {
    chabok.register(chabok.getUserId())
} else {
    chabok.register('<USER_ID>')
}

نکته: کاراکترهای ‍#,+,*,\,/ و فاصله در USER_ID مجاز نیستند، همچنین طول این رشته نباید کمتر از ۳ و بیشتر از ۳۲ کاراکتر باشد.

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

متد حذف کاربر

برای حذف دستگاه کاربر از سرور چابک می‌توانید از متد unregister استفاده کنید. پس از حذف کاربر، چابک دیگر به دستگاه‌های آن userId پوش ارسال نخواهد کرد. توصیه می‌شود این متد را زمانی که کاربر در اپلیکیشنتان از حساب خود خارج می‌شود (Logout) فراخوانی کنید. این امر باعث می‌شود تا کاربر از حفظ شدن حریم شخصی خود پس از خروج از حساب کاربری اطمینان یابد. پس از آن هم کاربر را به عنوان یک کاربر مهمان register کنید تا همچنان با او تعامل داشته باشید.

chabok.unregister()