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

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

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

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

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

۳- ثبت کاربر

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

برای دریافت کتابخانه چابک دستورات زیر را به فایل build.gradle اصلی پروژه اضافه کنید:

buildscript {
    repositories {
        google()
        jcenter()
        maven {
            url "https://plugins.gradle.org/m2/" 
        }
    }
    
    dependencies {    
        classpath "io.chabok.plugin:chabok-services:1.0.0"
        classpath 'com.google.gms:google-services:4.3.2'
    }
}

دستور زیر را در انتهای فایل build.gradle ماژول اپلیکیشن خود اضافه کنید:

apply plugin: 'io.chabok.plugin.chabok-services'
apply plugin: 'com.google.gms.google-services'

نکته: این فایل عموما در مسیر زیر وجود دارد: app/build.gradle

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

نصب کتابخانه استاندارد چابک

برای استفاده از کتابخانه استاندارد چابک (بدون قابلیت مکان‌یابی) از کتابخانه chabok-lib که در زیر به آن اشاره‌ شده است، استفاده کنید.
فایل build.gradle در ماژول اپلیکیشن را باز کرده و در بخش dependencies خطوط زیر را اضافه نمایید:

dependencies {
    implementation 'com.adpdigital.push:chabok-lib:3.1.0'
    implementation 'me.leolin:ShortcutBadger:1.1.22@aar'  
    implementation 'com.google.firebase:firebase-messaging:17.1.0'
    implementation 'com.android.installreferrer:installreferrer:1.0'
} 

نکته: چابک در حال حاضر از FCM بهره می‌برد؛ در عین حال به خاطر قابلیت backward compatibility خود از کاربرانی که از نسخه‌های پایین‌تر اندروید استفاده می‌کنند یا از GCM به FCM مهاجرت نکرده‌اند، پشتیبانی می‌کند. توجه داشته باشید که موضوع بسته شدن GCM برای سرورهای خودش است و در کلاینت‌های اندروید چابک، دریافت توکن پوش همچنان امکان‌پذیر است.

نصب کتابخانه با قابلیت مکان‌یابی چابک

درصورتی که در برنامه خود نیاز به استفاده از موقعیت مکانی کاربر دارید، لازم است در ابتدا کتابخانه chabok-lib را حذف و کتابخانه chabok-lib-geo را جایگزین کنید. با توجه به این که در این کتابخانه از سرویس فیوز گوگل استفاده شده است، باید تغییرات زیر نیز در قسمت ‌‌‌dependencies اعمال شود:

dependencies {
   implementation 'com.adpdigital.push:chabok-lib-geo:3.1.0'

   implementation 'me.leolin:ShortcutBadger:1.1.22@aar'  
   implementation 'com.google.firebase:firebase-messaging:17.1.0'
   implementation 'com.google.android.gms:play-services-location:10.2.6'
   implementation 'com.android.installreferrer:installreferrer:1.0'
}

نکات ضروری نصب کتابخانه

  • تمامی گوشی‌های با اندروید ۴ یا بالاتر قابلیت استفاده از کتابخانه چابک را دارند.

    نکته: برای گوشی‌هایی مانند شیاومی و هواوی که گزینه تنظیمات مربوط به برنامه‌های حفاظت شده دارند (ProtectedApps)، کاربر باید برنامه شما را در لیست برنامه‌های حفاظت شده، فعال کند تا دریافت پوش‌نوتیفیکیشن در همه حالت‌ها امکان‌پذیر شود. برای اطلاعات بیشتر می‌توانید بخش عیب‌یابی را مطالعه نمایید.

  • فایل google-services.json را از پنل فایربیس دانلود کنید و در پوشه ماژول اصلی اپلیکیشن خود قرار دهید. برای دانلود این فایل، مراحل زیر را طی کنید:

۱. به پنل فایربیس خود وارد شوید و پروژه را باز کنید.

۲. بر روی آیکون تنظیمات کلیک کنید و گزینه Project settings را انتخاب نمایید.

۳. از لیست اپلیکیشن‌ها، اپلیکیشن مورد نظر خود را انتخاب کنید.

۴. بر روی google-services.json کلیک کنید و آن را دانلود کنید.

نکته: فایل ذکر شده را پس از دانلود، در پوشه ماژول اصلی برنامه قرار دهید.

  • اگر از AndroidX استفاده می‌کنید قطعه کد زیر را در فایل gradle.properties پروژه خود اضافه کنید:
    android.useAndroidX=true
    android.enableJetifier=true
    

نکته:با راه‌اندازی کتابخانه چابک قادر به دریافت پوش نوتیفیکیشن خواهید بود و نیازی به پیاده‌سازی سرویس فایبربیس برای دریافت پوش نوتیفیکیشن نیست.

  • دقت داشته باشید که همیشه از جدیدترین نسخه 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 آخرین نسخه کتابخانه را از این صفحه مشاهده کنید و سپس آن را وارد نمایید، همچنین توصیه می‌شود بخش مدل نسخه‌گذاری در چابک را مطالعه نمایید.

نصب دستی کتابخانه

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

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

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

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

نکته: توصیه می‌کنیم برای دریافت آخرین نسخه Bug Fixها از کاراکتر + (wildcard) استفاده نمایید تا gradle به صورت خودکار نسخه‌های patch را بیاورد.
نکته: اگر از نسخه‌های پایین‌تر از ۳ کتابخانه چابک استفاده می‌کنید توصیه می‌کنیم کتابخانه چابک را به نسخه ۳ ارتقا دهید.


نکته: با توجه به حجم زیاد مجوزهای نمایش نشان (Badge) روی آیکون اپ،‌ می‌توانید از این قسمت هر کدام از آن‌ها را با اختیار خودتان بردارید.

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

چابک برای راه اندازی نیاز به مقداردهی اولیه دارد.
۱. برای مقداردهی ابتدا از پنل خود وارد بخش تنظیمات> دسترسی و توکن‌ها> کتابخانه موبایل> فعال‌سازی راه‌اندازی هوشمند> شوید و فایل Chabok.sandbox.json یا Chabok.production.json را بسته به محیطتان دانلود کنید.

نکته: برای غیرفعال کردن قابلیت پوش نوتیفیکیشن(pushNotification)، کافیست مقدار پیش ‌فرض آن را در فایل دانلود شده تغییر بدید.

۲. فایل دانلود شده را در پوشه ماژول اصلی پروژه قرار دهید.


۳. در مرحله آخر نیاز است کد‌های زیر را در کلاس اپلیکیشن خود فراخوانی کنید.

public class MyAppClass extends Application {  
      @Override  
      public void onCreate() {
          super.onCreate();  
          AdpPushClient.configureEnvironment(Environment.SANDBOX); // ضروری  
          AdpPushClient.setLogLevel(LogLevel.VERBOSE); // اختیاری
          AdpPushClient.setDefaultTracker("Ym3gy7"); // اختیاری
    }
}


-configureEnvironment: متد configureEnvironment تعیین می‌کند که اپلیکیشن شما به محیط آزمایشی (Sandbox) و یا عملیاتی (Production) چابک متصل شده. این موضوع بستگی به این دارد که حساب کاربری شما روی کدام محیط تعریف شده باشد.

نکته:متدی که در بالا قرار دادیم برای راه‌اندازی محیط سندباکس است. در صورتی که حساب عملیاتی دارید کافیست Environment.SANDBOX را با Environment.PRODUCTION عوض کنید.

نکته: برای درخواست حساب محیط عملیاتی، در بخش تنظیمات پنل، وارد بخش درخواست حساب عملیاتی شوید و درخواست خود را ثبت نمایید و پس از تایید و ساخت حساب عملیاتی فایل Chabok.production.json را دانلود کنید و به جای فایل Chabok.sandbox.json در پوشه ماژول اصلی پروژه خود قراردهید.

نکته: دقت داشته باشید که قابلیت آنی (realtime) چابک به طور پیش فرض غیر فعال است. برای فعال کردن مقدار قابلیت آنی (realtime)، کافی است مقدار پیش‌فرض آن را در فایل دانلود شده تغییر بدید. این قابلیت در پیام چابک و پیام‌رسانی آنی استفاده می‌شود.

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

public class MyAppClass extends Application {  
      @Override  
      public void onCreate() {
          super.onCreate();  
          AdpPushClient.setApplicationContext(this); // ضروری
          AdpPushClient.configureEnvironment(Environment.SANDBOX); // ضروری  
          AdpPushClient.setLogLevel(LogLevel.VERBOSE); // اختیاری
          AdpPushClient.setDefaultTracker("Ym3gy7"); // اختیاری
      }
}

۳- ثبت کاربر

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

ورود به حساب کاربری (login)

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

متد ثبت کاربر با چهار امضای متفاوت وجود دارد:

  • امضای اول:

فقط شناسه کاربر را گرفته و کاربر را با آن شناسه بر روی سرور چابک ثبت‌ نام می‌کند.

public void login(String userId)

نکته: مقدار USER_ID می‌تواند بین ۳ تا ۶۴ کاراکتر باشد. زبان فاسی، کاراکترهای #,+,*,\,/ و فاصله هم در آن مجاز نیستند.

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

  • امضای دوم:

علاوه بر شناسه کاربر، اطلاعات کاربر (Attributes) را نیز دریافت می‌کند.

public void login(String userId, HashMap<String, Object> attributes)

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

  • امضای سوم:

به غیر از شناسه کاربر، رفتار مورد نظر کاربر را نیز رصد می‌کند.

public void login(String userId, String eventName, @Nullable JSONObject data)
  • امضای چهارم:

به غیر از شناسه کاربر، لیست تگ‌ها را دریافت می‌کند.

نکته: به کمک لیست تگ‌ها در چابک می‌توانید کاربرانتان را بر اساس ویژگی‌های مورد نظرتان، دسته‌بندی و برچسب‌گذاری کنید و با آن‌ها ارتباط برقرار کنید. برای کسب اطلاعات بیشتر به این صفحه مراجعه کنید.

public void login(String userId, String[] tagsName)

خروج از حساب کاربری (logout)

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

public void logout()

نکته: پروژه Starter به شما کمک می‌کند بدون هیچ کد اضافه‌ای و فقط با اجرای آن، از پلتفرم چابک استفاده کنید. همچنین به کمک این پروژه با نحوه صحیح پیاده سازی متدهای چابک آشنا خواهید شد.