راه اندازی پوش‌پل در Flutter

• نسخه‌ی پوش‌پل: 1.7.8

این پلاگین در حال حاضر فقط برای اندروید قابل استفاده‌است.

راه‌اندازی

اضافه کردن کتابخانه

ابتدا کتابخانه را به پروژه اضافه کنید.

dependencies:
    pushpole: ^1.7.8

سپس flutter packages get را اجرا کنید تا پلاگین به پروژه اضافه شود.

تغییرات AndroidManifest.xml

• پس از ساخت اپلیکیشن در کنسول، در قسمت اپلیکیشن‌ها، روی آیکون دریافت مانیفست بزنید (این آیکون را با کلیک بر روی علامت سه نقطه‌ی گوشه‌ی کارت اپلیکیشن می‌توانید ببینید).
• مانیفست فلاتر را انتخاب کنید و محتویات آن را با توجه به راهنمای موجود، در قسمت‌های مربوطه کپی‌کرده و به AndroidManifest.xml پروژه خود اضافه کنید.

فایل مانیفست را می‌توانید در آدرس android/app/src/main/AndroidManifest.xml بیابید.

تگی‌ همانند زیر باید به درون تگ Application اضافه‌شود:

<meta-data android:name="com.pushpole.sdk.token"
            android:value="YOUR_TOKEN" />

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

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

افزودن کد

import 'package:pushpole/pushpole.dart';

PushPole.initialize();

• اگر در تابع بالا مقدار showDialog: true گذاشته شود و دستگاه کاربر شما گوگل پلی سرویس نداشته باشد و یا آن را غیرفعال کرده باشد دیالوگی باز می شود و به کاربر پیشنهاد نصب گوگل پلی سرویس داده می شود تا قابلیت دریافت و ارسال پوش نوتیفیکیشن فعال شود. اگر در تابع بالا showDialog: true را قرار دهید، این دیالوگ برای کاربر باز نمی شود.

از آنجایی که اندروید 13 (target 33) برای دریافت اعلان نیاز به دسترسی دارد، در پروژه باید دسترسی اعلان را از کاربر دریافت نمایید

تست

پس از نصب و اجرا کنسول را بررسی کنید و از مشاهده‌ی لاگ زیر اطمینان حاصل کنید:

Successfully registered to PushPole

• به صفحه نصب ها بروید.
• بعد از گذشت زمان کوتاهی یک ردیف مشخصات نصب به لیست نصب ها اضافه می شود که متعلق به گوشی شما است.
• یک اعلان تست ارسال کنید.دقت کنید تلفن همراه شما به اینترنت متصل باشد.

اگر می خواهید اپلیکیشن را بر روی Emulator تست کنید، بر روی ایمولاتور شما باید Google API نصب باشد.

امکانات

بعضی‌ از توابع پلاگین async هستند. لذا می‌توانید آنهارا با استفاده از تابع then ویا کلید await استفاده‌کنید.

PushPoleId

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

PushPole.getId().then((pushpoleId) {
  // Deal with id
}); // or you can use async/await

دسته‌بندی‌کاربران (Topic)

شما می‌توانید کاربران خود را در تاپیک یا تاپیک‌های متفاوت ثبت نام کنید و برحسب علاقمندی کاربران یا دسته‌بندی خودتان به تاپیک مرتبط پوش بفرستید. مثلا اگر شما اپلیکیشن خبری دارید و کاربرانی به اخبار ورزشی علاقمند هستند و عده ای به اخبار فرهنگی، می توانید دسته اول را در تاپیک ورزشی و دسته دوم را در تاپیک فرهنگی ثبت نام کنید و هنگام ارسال پوش، برحسب محتوای پوش‌تان به تاپیک مرتبط آن را ارسال کنید تا فقط کاربران علاقمند به آن موضوع آن را دریافت کنند. برای استفاده از این امکان باید کاربران خود را در تاپیک مورد نظر عضو کنید. فرض کنید نام تاپیک مورد نظرتان ‍‍‍sport باشد. برای عضویت در این تاپیک از دستور زیر استفاده کنید:

PushPole.subscribe("sport");

برای لغو عضویت از این تاپیک از دستور زیر استفاده کنید:

PushPole.unsubscribe("sport");

رویداد نوتیفیکیشن

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

PushPole.setNotificationListener(
      onReceived: (notificationData) { /* Your code */ },
      onClicked: (notificationData) { /* Your code */ },
      onDismissed: (notificationData) { /* Your code */ },
      onButtonClicked: (notificationData, clickedButton) { /* Your code */ },
      onCustomContentReceived: (customContent) => { /* Your code */ },
    );

نکته‌ی مهم: کالبک‌ها تنها زمانی اجرا می‌شوند که فلاتر در حال اجرا باشد. لذا زمانی که برنامه به طور کامل بسته‌شده کد‌های تعریف ‌شده‌ی بالا اجرا نخواهند شد.

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

غیرفعال کردن نمایش پوش

می‌توانید نمایش پوش را غیرفعال کنید. مثلا در تنظیمات اپلیکیشن خود امکان دریافت نکردن پوش را برای کاربر قرار دهید و طبق انتخاب کاربر آن را فعال یا غیرفعال کنید. برای غیرفعال کردن نمایش پوش از دستور زیر استفاده کنید:

PushPole.setNotificationOff();

برای فعال سازی دوباره ی نمایش پوش از دستور زیر استفاده کنید:

PushPole.setNotificationOn();

ارسال پوش از یک دستگاه به دستگاه دیگر

به این روش pid هر دستگاه را می توانید بدست بیاورید و آن‌ها را در سرور خود ذخیره کنید تا برای ارسال اعلان به دستگاه از آن استفاده کنید.

• برای ارسال اعلان ساده از دستور زیر استفاده کنید:

var pid = somePushPoleId; // For instance "pid_a0e3-82ac-a0"
PushPole.sendSimpleNotifToUser(pid, "title", "content");

• برای ارسال اعلان پیشرفته از این دستور استفاده کنید:

var pushpoleId = "some_pushpole_id";
PushPole.sendAdvancedNotifToUser(pushpoleId, '{ "title":"some_title", "content":"some_content" }');

نوتیفیکیشن باید بصورت جیسون به ورودی داده شود.

برای اطلاعات بیشتر در مورد کلید‌ها و نحوه‌ی آنها به ارسال با استفاده از API مراجعه کنید.

نکته مهم: توابع ارسال اعلان به دستگاه دیگر و عضویت یا لغو عضویت در تاپیک را بعد از اطمینان از اینکه عملیات initialization پوش‌پل انجام شده است، صدا بزنید. برای این کار به روش زیر عمل کنید:

PushPole.isPushPoleInitialized().then((initialized) {
      if (initialized) {
           PushPole.sendSimpleNotifToUser(pid, "title", "content");
      }
});

• در صورتی که قصد دارید به دستگاهی که این کد را اجرا کرده اعلان ارسال کنید، کافیست که شناسه‌ی ورودی را برابر شناسه‌ی دستگاه قرار دهید.

PushPole.getPushPoleId().then((pushpoleId) {
   PushPole.sendSimpleNotifToUser(pushpoleId, 'Title', 'content');
});

استفاده‌ی همزمان با سایر سرویس‌ها

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

برای این‌کار باید یک سرویس طراحی کنید و پیام‌های سایر سرویس‌ها را جداسازی کنید. بدین منظور در بخش اندروید پروژه یک فایل جاوا بسازید و کلاس پدر آن را سرویسی‌ قرار دهید که قصد دارید در کنار پوش‌پل استفاده شود. مثلا سرویس FlutterFirebaseMessagingService برای فایربیس. پس از ساختن سرویس کد سرویس را بصورت زیر تغییر دهید:

public class MyFCMService extends FlutterFirebaseMessagingService {
    @Override
    public void onNewToken(String s) {
        com.pushpole.sdk.PushPole.getFcmHandler(this).onNewToken(s);
        super.onNewToken(s);
    }
    @Override
    public void onDeletedMessages() {
        com.pushpole.sdk.PushPole.getFcmHandler(this).onDeletedMessages();
        super.onDeletedMessages();
    }
    @Override
    public void onSendError(String s, Exception e) {
        com.pushpole.sdk.PushPole.getFcmHandler(this).onSendError(s, e);
        super.onSendError(s, e);
    }
    @Override
    public void onMessageSent(String s) {
        com.pushpole.sdk.PushPole.getFcmHandler(this).onMessageSent(s);
        super.onMessageSent(s);
    }
    @Override
    public void onMessageReceived(RemoteMessage remoteMessage) {
        if (!com.pushpole.sdk.PushPole.getFcmHandler(this).onMessageReceived(remoteMessage)) {
            // It is for fire base, otherwise the condition will handle the message for PushPole
            super.onMessageReceived(remoteMessage);
        }
    }
}

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

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

کد‌های زیر را در تگ اپلیکیشن قرار دهید.

<service
   android:name="com.pushpole.sdk.fcm.FcmService" 
   tools:node="remove" />

<!-- Add your own service name instead of this , if you are not using firebase -->
<service
   android:name="io.flutter.plugins.firebasemessaging.FlutterFirebaseMessagingService" 
   tools:node="remove" />

سپس سرویس خود را اضافه نمایید:

<service android:name=".MyFcmService">
    <intent-filter>
        <action android:name="com.google.firebase.MESSAGING_EVENT" />
    </intent-filter>
</service>

عیب یابی

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

سینک‌کردن لایبرری‌ها هنگام بیلد به خطا منجر می‌شود

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