راهاندازی
ویرایش
نکته:
مستندات پیادهسازی زیر براساس نسخههای ۳ به بالا کتابخانه چابک نوشته شده است. در صورتی که از نسخه پایینتری استفاده میکنید به این صفحه مراجعه کنید.اگر از نسخههای پایینتر از ۳ کتابخانه چابک استفاده میکنید توصیه میکنیم کتابخانه چابک را به نسخه ۳ ارتقا دهید.
در صورتی که میخواهید نسخه خود را ارتقا دهید، حتما مستندات مهاجرت به نسخه ۳ چابک را مطالعه کنید.
پس از طی کردن مراحل صفحه پیشنیازها، میتوانید راهاندازی SDK چابک را شروع کنید. برای انجام این مراحل ابتدا نیاز است کتابخانه چابک را نصب کنید. سپس مقداردهی و راهاندازی کتابخانه چابک را در اپلیکیشنتان انجام دهید و در آخر برای شناخت کاربر توسط چابک، مرحله ثبت کاربر را حتما پشت سر بگذارید.
۲- مقداردهی اولیه (Initialize)
۱- نصب کتابخانه
برای دریافت کتابخانه چابک دستورات زیر را به فایل build.gradle
اصلی پروژه اضافه کنید (این فایل عموما در مسیر app/build.gradle وجود دارد):
دستور زیر را در انتهای فایل build.gradle
ماژول اپلیکیشن خود اضافه کنید:
در این قسمت شما باید کتابخانه استاندارد یا کتابخانه با قابلیت مکانیابی را نصب نمایید. برای استفاده از سرویس پیامرسانی و قابلیتهای آنی چابک میتوانید از کتابخانه استاندارد بهره ببرید. در صورتی هم که میخواهید این امکانات را همراه با قابلیت مکانیابی داشته باشید باید از کتابخانه با قابلیت مکانیابی استفاده کنید. دقت نمایید که هر دو کتابخانه همزمان نمیتوانند کار کنند و شما باید فقط از یکی از آنها متناسب با نیاز خود استفاده کنید.
نصب کتابخانه استاندارد چابک
برای استفاده از کتابخانه استاندارد چابک (بدون قابلیت مکانیابی) از کتابخانه chabok-lib
که در زیر به آن اشاره شده است، استفاده کنید.
فایل build.gradle
در ماژول اپلیکیشن را باز کرده و در بخش dependencies
خطوط زیر را اضافه نمایید:
نکته:
چابک در حال حاضر از FCM بهره میبرد؛ در عین حال به خاطر قابلیت backward compatibility خود از کاربرانی که از نسخههای پایینتر اندروید استفاده میکنند یا از GCM به FCM مهاجرت نکردهاند، پشتیبانی میکند. توجه داشته باشید که موضوع بسته شدن GCM برای سرورهای خودش است و در کلاینتهای اندروید چابک، دریافت توکن پوش همچنان امکانپذیر است.
نصب کتابخانه با قابلیت مکانیابی چابک
درصورتی که در برنامه خود نیاز به استفاده از موقعیت مکانی کاربر دارید، لازم است در ابتدا کتابخانه chabok-lib
را حذف و کتابخانه chabok-lib-geo
را جایگزین کنید. با توجه به این که در این کتابخانه از سرویس فیوز گوگل استفاده شده است، باید تغییرات زیر نیز در قسمت dependencies
اعمال شود:
نکات ضروری نصب کتابخانه
- تمامی گوشیهای با اندروید ۴ یا بالاتر قابلیت استفاده از کتابخانه چابک را دارند.
نکته
: برای گوشیهایی مانند شیاومی و هواوی که گزینه تنظیمات مربوط به برنامههای حفاظت شده دارند (ProtectedApps)، کاربر باید برنامه شما را در لیست برنامههای حفاظت شده، فعال کند تا دریافت پوشنوتیفیکیشن در همه حالتها امکانپذیر شود. برای اطلاعات بیشتر میتوانید بخش عیبیابی را مطالعه نمایید. - فایل
google-services.json
را از پنل فایربیس دانلود کنید و در پوشه ماژول اصلی اپلیکیشن خود قرار دهید. برای دانلود این فایل، مراحل زیر را طی کنید:
۱. به پنل فایربیس خود وارد شوید و پروژه را باز کنید.
۲. بر روی آیکون تنظیمات کلیک کنید و گزینه Project settings را انتخاب نمایید.
۳. از لیست اپلیکیشنها، اپلیکیشن مورد نظر خود را انتخاب کنید.
۴. بر روی google-services.json
کلیک کنید و آن را دانلود کنید.
- اگر از AndroidX استفاده میکنید قطعه کد زیر را در فایل
gradle.properties
پروژه خود اضافه کنید:
- کتابخانه چابک از فایربیس نسخه ۱۷.۱.۰ و بالاتر پشتیبانی میکند. بنابراین اگر از فایربیس استفاده میکنید نسخه آن را به حداقل نسخهی ذکر شده (۱۷.۱.۰) ارتقاع دهید.
نکته:
با راهاندازی کتابخانه چابک قادر به دریافت پوش نوتیفیکیشن خواهید بود و نیازی به پیادهسازی سرویس فایبربیس برای دریافت پوش نوتیفیکیشن نیست.
نکته
: حذف توکن به کمک متدdeleteInstanceId
فایربیس در نسخههای ۳.۲.۰ به پایین چابک، میتواند باعث نامعتبر شدن توکن پوش شود و روی آمار حذف تاثیر بگذارد، پس استفاده از آن توصیه نمیشود. و حذف توکن در نسخه ۳.۲.۰ به بالا چابک به طور خودکار هندل میشود و مشکلی برای توکن پیش نمیآورد.
- دقت داشته باشید که همیشه از جدیدترین نسخه ShortcutBadger استفاده کنید. برای اطلاع از آخرین نسخه میتوانید به این لینک مراجعه نمایید. همچنین با توجه به حجم زیاد مجوزهای نمایش نشان (Badge) روی آیکون اپ، میتوانید از این قسمت هر کدام از آنها را با اختیار خودتان بردارید.
- به علت محدودیتهای اندروید ۸ به بالا دقت کنید حتما مطابق جدول زیر تنظیمات نسخهها را به درستی انجام دهید. در صورت رعایت نکردن نسخههای ذکر شده در جدول زیر هنگامی که اپلیکیشنتان kill شده باشد به هنگام دریافت نوتیفیکیشن با خطا مواجه خواهد شد.
buildTools | compileSdk | targetSdk | googlePlayServices |
---|---|---|---|
25.x.x | 25 | >= 23 | >= 9.6.0 |
26.x.x | 26 | >= 23 | >= 9.6.0 |
27.x.x | 27 | >= 23 | >= 10.2.1 |
- توجه داشته باشید که برای
VERSION
آخرین نسخه کتابخانه را از این صفحه مشاهده کنید و سپس آن را وارد نمایید، همچنین توصیه میشود بخش مدل نسخهگذاری در چابک را مطالعه نمایید.
نصب دستی کتابخانه
آخرین نسخه فایل کتابخانه چابک از اینجا قابل دسترس میباشد. در انتها گزینه سینک را بزنید. برای نصب کتابخانه استفاده از این روش را توصیه نمیکنیم. زیرا شما از به روز رسانی نسخههای چابک مطلع نمیشوید.
۲- مقداردهی اولیه (Initialize)
چابک برای راه اندازی نیاز به مقداردهی اولیه دارد.
۱. برای مقداردهی ابتدا از پنل خود وارد بخش پیادهسازی> راهاندازی> دسترسی و توکنها> کتابخانه موبایل> فعالسازی راهاندازی هوشمند> شوید و فایل Chabok.sandbox.json یا Chabok.production.json را بسته به محیطتان دانلود کنید.
نکته:
برای غیرفعال کردن قابلیت پوش نوتیفیکیشن (pushNotification)، کافیست مقدار پیش فرض آن را در فایل دانلود شده تغییر بدید.
۲. فایل دانلود شده را در پوشه ماژول اصلی پروژه قرار دهید.
۳. در مرحله آخر نیاز است کدهای زیر را در کلاس اپلیکیشن خود فراخوانی کنید.
configureEnvironment: متد configureEnvironment
تعیین میکند که اپلیکیشن شما به محیط آزمایشی (Sandbox) و یا عملیاتی (Production) چابک متصل شده. این موضوع بستگی به این دارد که حساب کاربری شما روی کدام محیط تعریف شده باشد.
در صورتی که حساب عملیاتی دارید کافیست Environment.SANDBOX
را با Environment.PRODUCTION
عوض کنید.
برای درخواست حساب محیط عملیاتی، در بخش تنظیمات پنل، وارد بخش درخواست حساب عملیاتی شوید و درخواست خود را ثبت نمایید و پس از تایید و ساخت حساب عملیاتی فایل Chabok.production.json را دانلود کنید و به جای فایل Chabok.sandbox.json در پوشه ماژول اصلی پروژه خود قراردهید.
نکته:
دقت داشته باشید که قابلیت آنی (realtime) چابک به طور پیش فرض غیر فعال است. برای فعال کردن مقدار قابلیت آنی (realtime)، کافی است مقدار پیشفرض آن را در فایل دانلود شده تغییر بدید. این قابلیت در پیام چابک و پیامرسانی آنی استفاده میشود.
اگر از کامپوننتهای اندروید در پراسس دیگری استفاده میکنید. حتما متد setApplicationContext
را قبل از متد configureEnvironment
فراخوانی کنید. در نهایت کلاس اپلیکیشنتان به شکل زیر خواهد بود:
با قرار دادن کد زیر در فایل AndroidManifest.xml
در تگ Application
میتوانید آیکون پیشفرض نوتیفیکیشن را به چابک معرفی کنید:
۳- ثبت کاربر
یکی از مزیتهای چابک نسبت به درگاههای ارسال پوشنوتیفیکیشن، امکان معرفی هر کاربر با یک شناسه منحصر به فرد است. این قابلیت به شما امکان میدهد دستگاههای کاربر را مدیریت کنید و سوابق جمعآوری شده را همانند یک سیستم مدیریت مشتریان (CRM) در اختیار داشته باشید.
این شناسه میتواند برای دستگاههای متعدد یک کاربر استفاده شود. شناسه کاربر میتواند هر فیلد با ارزش و معنادار برای کسب و کار شما باشد که کاربر خود را با آن شناسایی میکنید. شماره موبایل، کدملی، شمارهحساب، ایمیل و یا حتی شناسه دیتابیستان مثالهایی از شناسههای کاربری مناسب در موارد واقعی هستند. ارسال پیام به کاربران توسط همین شناسهها و بدون استفاده از توکن یا شناسه گوشی، به سادگی امکان پذیر خواهد بود.
ورود به حساب کاربری (login)
متد لاگین تنها زمانی فراخوانی شود که کاربر در اپلیکیشن لاگین یا ثبتنام میکند. نیازی به فراخوانی این متد در هر بار اجرای اپلیکیشن نیست.
متد ثبت کاربر با چهار امضای متفاوت وجود دارد:
- امضای اول:
فقط شناسه کاربر را گرفته و کاربر را با آن شناسه بر روی سرور چابک ثبت نام میکند.
نکته:
مقدارUSER_ID
میتواند بین ۳ تا ۶۴ کاراکتر باشد. زبان فاسی، کاراکترهای#,+,*,\,/
و فاصله هم در آن مجاز نیستند.
نکته امنیتی:
مقدارUSER_ID
را هرگز به صورت خام درSharedPreferences
ذخیره نکنید، چون مقدار این شناسه معنادار است و میتوان با آن، کاربر را روی چابک ثبتنام کرد. همینطور میتوانید قبل از عملیات ثبت با استفاده از شماره گوشی از معتبر بودن کاربر (verification) اطمینان یابید، سپس شناسه او را ثبت نمایید.
- امضای دوم:
علاوه بر شناسه کاربر، اطلاعات کاربر (Attributes) را نیز دریافت میکند.
برای ثبت اطلاعات کاربران مستندات دادههای سفارشی کاربر، را مطالعه کنید.
- امضای سوم:
به غیر از شناسه کاربر، رفتار مورد نظر کاربر را نیز رصد میکند.
برای ارسال رویداد مستندات رصد رفتار درونبرنامهای، را مطالعه کنید.
- امضای چهارم:
به غیر از شناسه کاربر، لیست تگها را دریافت میکند.
به کمک لیست تگها در چابک میتوانید کاربرانتان را بر اساس ویژگیهای مورد نظرتان، دستهبندی و برچسبگذاری کنید و با آنها ارتباط برقرار کنید. برای کسب اطلاعات بیشتر به این صفحه مراجعه کنید.
خروج از حساب کاربری (logout)
در صورتی که کاربر از حساب کاربری خود خارج شد، با فراخوانی متد زیر میتوانید کاربر را همچنان با یک تگ مهمان در سیستم خود داشته باشید و تعاملتان را با او ادامه دهید.
۴- تست پیادهسازی
برای اطمینان از موفقیتآمیز بودن راهاندازی لطفا تستهای زیر را انجام دهید.
تست SDK
آیا پس از راهاندازی، دستگاه شما به پنل اضافه شده است؟
در منوی کاربران میتوانید دستگاههای موجود را همراه با جزئیات مشاهده کنید. پس از بازدید اول از اپلیکیشن اطلاعات دستگاه خود را در پنل با دقت مطابقت دهید.
نکته:
دقت داشته باشید که آخرین نسخه SDK را دریافت کنید و موارد لیست تغییرات را مطالعه کنید.
تست login کاربران
۱- آیا وضعیت کاربران درست ثبت شده است؟ (لاگین، مهمان، حذف کرده/نکرده)
در صورتی که در اپلیکیشن بخش لاگین دارید، ( پیادهسازی آن را از چابک کردهاید) میتوانید در فیلتر سگمنت جدید گزینه وضعیت کاربر را انتخاب کنید تا متوجه شوید کاربر در چه وضعیتی (لاگین، مهمان، حذف کرده و حذف نکرده) قرار دارد.
۲- آیا پنل به درستی کاربران را در صورت خروج از اپلیکیشن (logout) به کاربر مهمان تبدیل میکند؟
وقتی کاربران بر روی گزینه logout در اپلیکیشن کلیک میکنند و از اپ خارج میشوند، اطلاعاتشان در چابک ذخیره میشود و یک شناسه دیگری به هر کاربر خارج شده اختصاص میدهد تا وقتی مجدد وارد اپلیکیشن شود شناسه کاربری او تغییر کند. این کاربران در بخش سگمنت قابل مشاهدهاند.
نکته:
پروژه Starter به شما کمک میکند بدون هیچ کد اضافهای و فقط با اجرای آن، از پلتفرم چابک استفاده کنید. همچنین به کمک این پروژه با نحوه صحیح پیاده سازی متدهای چابک آشنا خواهید شد.