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

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

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

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

۳- ثبت کاربر

۴- تست پیاده‌سازی

نصب کتابخانه

کتابخانه چابک از طریق CocoaPods در دسترس است، برای نصب خط زیر را به Podfile خود اضافه کنید:

target 'YourProject' do
  use_frameworks!

  pod 'ChabokPush', '~> 2.3.0'
  
end

سپس با دستور زیر آن را نصب کنید:

pod install --repo-update

پس از اجرای دستورات بالا اگر با خطایی رو به رو شدید، دستور زیر را وارد کنید، سپس pod install را دوباره اجرا کنید.

pod update

حالا برای اطمینان از نصب، پروژه را در xcode باز کنید ، اگر header فایل چابک را مشاهده کنید، افزودن کتابخانه موفقیت آمیز بوده است.

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

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

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

چابک برای راه‌اندازی نیاز به مقداردهی اولیه دارد.

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

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

۲- فایل دانلود شده را در Bundle Resources پروژه خود مطابق تصویر اضافه کنید:

۳- در آخر متدهای زیر را فرخوانی کنید.

تمامی متدهایی که در این بخش بیان می‌شود باید به کلاس AppDelegate اضافه شده و متدهای چابک باید در delegate متد didFinishLaunchingWithOptions فراخوانی شوند.

#import "AppDelegate.h"
#import <AdpPushClient/AdpPushClient.h>

@implementation AppDelegate

- (BOOL)application:(UIApplication *)application
            didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    
    [PushClientManager  resetBadge]; //Optional
    [PushClientManager.defaultManager addDelegate:self]; //Optional
    
    [PushClientManager.defaultManager configureEnvironment:Sandbox];
 
    return YES;
}

متد بالا برای محیط سندباکس است. در صورتی که حساب عملیاتی دارید کافیست فقط Sandbox را با ‍‍Production عوض کنید.

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

توجه داشته باشید هنگامی که گواهی sandbox اپل را در پنل تستی قرار می‌دهید، فقط امکان دریافت Push Notification در حالت debug وجود خواهد داشت. اما اگر گواهی production اپل را در محیط عملیاتی قرار دهید، زمانی Push Notification را دریافت خواهید کرد که اقدام به ساخت ipa از پروژه خود کرده و از طریق TestFlight یا Enterprise اپلیکیشن خود را نصب کنید.

جهت دسترسی به delegate‌های چابک باید متد addDelegate را همانند کد زیر فراخوانی کنید:

[PushClientManager.defaultManager addDelegate:self];

• متد resetBadge:

چابک به طور پیش‌فرض برای هر پیام در اپلیکیشنتان نشان (Badge) اعمال می‌کند. متد resetBadge برای خالی کردن و ریست Badge به کار می‌رود. شما با توجه به نیاز خود می‌توانید این متد را در جای خاصی از اپلیکیشنتان (مانند صندوق پیام‌ها) یا در حین باز شدن (launch) اپ خود فراخوانی کنید.

[PushClientManager  resetBadge];

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

ثبت کاربر

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

ورود به حساب کاربری

دقت داشته باشید که متدهای login و logout را در background thread فراخوانی نکنید و آن‌ها را حتما در main thread قرار دهید.

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

• امضای اول

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

[PushClientManager.defaultManager login:@"USER_ID"];

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

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

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

• امضای دوم

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

[PushClientManager.defaultManager login:@"USER_ID" userAttributes:];

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

• امضای سوم

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

[PushClientManager.defaultManager login:@"USER_ID" event:@"EVENT_NAME" data:]

خروج از حساب کاربری

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

[PushClientManager.defaultManager logout];

تست پیاده‌سازی

برای اطمینان از موفقیت‌آمیز بودن راه‌اندازی لطفا تست‌های زیر را انجام دهید.

تست SDK

آیا پس از راه‌اندازی، دستگاه شما به پنل اضافه شده است؟

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

دقت داشته باشید که آخرین نسخه SDK را دریافت کنید و موارد لیست تغییرات را مطالعه کنید.

تست login کاربران

۱- آیا وضعیت کاربران درست ثبت شده است؟ (لاگین، مهمان، حذف کرده/نکرده)

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

۲- آیا پنل به درستی کاربران را در صورت خروج از اپلیکیشن (logout) به کاربر مهمان تبدیل می‌کند؟

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

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