onesignal pushe.co s-3.664-0.699-5.062-2.099c-1.397-1.398-2.097-3.087-2.097-5.065s0.699-3.667,2.097-5.065c1.397-1.399,3.085-2.099,5.062-2.099 s3.664,0.699,5.062,2.099C223.888,120.556,224.587,122.244,224.587,124.223z"/>

راهنمای مهاجرت به نسخه دو پوشه در اندروید استودیو

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

تغییر dependency در تنظیمات gradle برنامه

برای اضافه کردن کتابخانه پوشه به برنامه خود، به جای دستور زیر که در نسخه یک پوشه استفاده می‌شد:

implementation 'co.ronash.android:pushe-base:1.6.0'

دستور زیر به بخش dependencies اضافه می‌شود:

implementation 'co.ronash.pushe:base:2.0.0-beta01'

افزایش مقدار compileSdkVersion

برای استفاده از نسخه‌ی دوم پوشه لازم است که مقدار compileSdkVersion تنظیم شده در پروژه‌ی شما حداقل 28 باشد.

این مقدار را می‌توانید در فایل build.gradle اپلیکیشن خود تغییر دهید:

android {
    compileSdkVersion 28

    defaultConfig {
        ...
    }
    ...
}

تغییر فایل AndroidManifest.xml

برای استفاده از نسخه‌ی دوم پوشه باید متنی در قالب متن زیر را درون تگ application فایل AndroidManifest.xml خود اضافه کرده و مقادیر <app> و <sender_id> را با اطلاعات اپلیکیشن خود جایگزین کنید.

<meta-data
   android:name="pushe_token"
   android:value="<appd>@<sender_id>" />

عبارت <appid> را با پکج‌نیم اپلیکیشن خود جایگزین کنید.

عبارت <sender_id> باید با Sender ID که اپلیکیشن شما با آن ثبت شده است جایگزین شود. اگر از مقدار آن اطلاع ندارید می‌توانید به روش زیر آن را بیابید.

Sender ID من چیست؟

اگر Sender ID مربوط به اپلیکیشن خود را نمی‌دانید می‌توانید آن را از تنظیمات مربوط به نسخه‌ی اول پوشه در فایل AndroidManifest.xml خود پیدا کنید.

در تنظیمات AndroidManifest.xml که برای نسخه‌ی اول پوشه استفاده می‌کردید عبارتی مشابه زیر وجود دارد

<meta-data android:name="co.ronash.pushe.token" android:value="PUSHE_123456789123"/>

در این متن عدد ۱۲ رقمی که بعد عبارت PUSHE آمده است Sender ID مربوط به اپلیکیشن شما را مشخص می‌کند.

نمونه‌ای از متن نهایی که باید در فایل AndroidManifest.xml شما قرار گیرد در ادامه آماده است

<meta-data
   android:name="pushe_token"
   android:value="co.pushe.demo@123456789123" />

در استفاده از نسخه دوم پوشه، نیازی به قرارگیری تگ‌ها و دسترسی‌هایی که مربوط نسخه‌ی اول بودند نیست و باید آن‌ها را از فایل AndroidManifest.xml حذف کنید.

  • عبارت‌های زیر را از فایل AndroidManifest.xml خود حذف کنید:
<uses-sdk
    tools:overrideLibrary="co.ronash.pushe" />
<permission
    android:name="<package_name>.permission.C2D_MESSAGE"
    android:protectionLevel="signature" />
<uses-permission
    android:name="<package_name>.permission.C2D_MESSAGE" />
<uses-permission
android:name="android.permission.ACCESS_NETWORK_STATE"/>

<!-- Optional permissions -->
<uses-permission android:name="com.google.android.gms.permission.ACTIVITY_RECOGNITION"/>
<uses-permission android:name="android.permission.READ_PHONE_STATE"/>
  • همچنین، receiverها و meta-dataهای زیر را از درون تگ application حذف کنید:
<receiver android:name="co.ronash.pushe.receiver.UpdateReceiver" >
    <intent-filter>
        <action android:name="android.intent.action.PACKAGE_REPLACED" />

        <data
            android:path="co.ronash.pushe.pushev1testoncode"
            android:scheme="package" />
    </intent-filter>
</receiver>

<receiver
android:name="com.google.android.gms.gcm.GcmReceiver"
android:exported="true"
android:permission="com.google.android.c2dm.permission.SEND" >
<intent-filter>
    <action android:name="com.google.android.c2dm.intent.RECEIVE" />

    <action android:name="com.google.android.c2dm.intent.REGISTRATION" />

    <category android:name="co.ronash.pushe.pushev1testoncode" />
</intent-filter>
</receiver>

<meta-data android:name="co.ronash.pushe.token" android:value="PUSHE_123456789123"/>
<meta-data android:name="co.ronash.pushe.cr" android:value="Tm9uZQ=="/>

حذف Pushe.initialize

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

حذف Pushe ID

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

شناسه‌ی Pushe ID در نسخه‌ی دوم همچنان قابل دستیابی و استفاده است ولی در نسخه‌های آینده پوشه حذف خواهد شد. بنابراین توصیه می‌کنیم اگر از آن استفاده می‌کنید کد خود را تغییر دهید تا از یکی از شناسه‌های دیگر استفاده کند.

پس از چی استفاده کنم؟

پیشنهاد ما استفاده از یکی از شناسه‌های زیر است:

  • Android ID: این شناسه توسط اندروید به کاربران داده می‌شود و می‌توانید آن را با فراخوانی تابع Pushe.getAndroidId بدست آورید.
  • Google Advertising ID: این شناسه را Google Play Services به کاربران اختصاص می‌دهد. می‌توانید آن را با فراخوانی تابع Pushe.getGoogleAdvertisingId بدست اورید.
  • Custom ID: این شناسه‌ای است که خود شما می‌توانید به کاربر‌ان خود اختصاص دهید و از طریق آن به آن‌ها اعلان ارسال نمایید. برای اختصاص دادن یک شناسه به یک کاربر تابع Pushe.setCustomId را فراخوانی کنید.

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

ثبت کاربر در تاپیک

فرض کنید نام تاپیک مورد نظرتان ‍‍‍sport باشد. برای عضویت در این تاپیک از دستور زیر استفاده کنید:

Pushe.subscribeToTopic("sport");

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

Pushe.unsubscribeFromTopic("sport");

گوش دادن به رویداد‌های اعلان

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

در نسخه‌ی دو پوشه برای این منظور لازم است یک کلاس بسازید که
PusheNotificationListener را پیاده‌سازی کند و آن را به تابع PusheNotification.setNotificationListener بدهید. پس از انجام اینکار، با دریافت اعلان جدید توابع کلاس تعریف شده شما فراخوانی خواهند شد.

توجه داشته باشید برای آنکه بتوانید در هنگام بسته بودن اپلیکیشن نیز از رویداد‌ها مطلع شوید، این عملیات را باید در Application.onCreate انجام دهید.

دسترسی به توابع مربوط به اعلان‌ها

در نسخه‌ اول پوشه امکان تغییر تنظیمات اعلان‌ها و همچنین امکان گوش دادن به رویداد‌های اعلان‌ها (مثلا هنگام دریافت اعلان یا اعلان با JSON) وجود داشت. این امکانات همگی در پوشه نسخه دو نیز وجود دارند ولی نحوه‌ی استفاده از آن‌ها تغییر کرده است.

در نسخه‌ی دو پوشه برای دسترسی به توابع مربوط به اعلان‌ها ابتدا باید یک شی از کلاس PusheNotification را به شکل زیر بدست آورید:

import co.ronash.pushe.Pushe;
import co.ronash.pushe.notification.PusheNotification;

PusheNotification pusheNotification = Pushe.getPusheService(PusheNotification.class);

تمامی توابع مربوط به تنظیمات اعلان‌ها باید بر روی شی pusheNotification فراخوانی شوند.

در ادامه نحوه‌ی گوش دادن به رویداد‌های اعلان‌ها را به صورت مرحله به مرحله توضیح می‌دهیم:

۱. ایجاد کلاس Application

در صورتی که قبلا برای اپلیکیشن خود یک کلاس Application ساخته‌اید می‌توانید از این مرحله بگذرید.

یک کلاس جدید بسازید که از کلاس ‍ ‍‍Application‍‍ ارث می‌برد. فرض می‌کنیم اسم کلاس جدید MyApplication است.

در فایل AndroidManifest.xml خود تگ application را پیدا کنید و به آن یک پارامتر android:name به شکل زیر اضافه کنید. توجه داشته باشید به جای MyApplication نام کلاس خود را بگذارید.

    <application
        android:name=".MyApplication"
        ...
        >
        ...
    </application>

۲. ثبت Callback برای رویداد‌ها

در تابع onCreate کلاس ساخته شده کد زیر را قرار دهید.

class MyApplication extends Application {

    public void onCreate() {
        super.onCreate()

        PusheNotification pusheNotification = Pushe.getPusheService(PusheNotification.class);

        if (pusheNotification == null) {
            Log.e("MyApplication", "Unable to obtain Pushe Notification");
            return;
        }

        pusheNotification.setNotificationListener(new PusheNotificationListener() {
            @Override
            public void onNotification(NotificationData notification) {
            }

            @Override
            public void onCustomContentNotification(Map<String, Object> customContent) 
            }

            @Override
            public void onNotificationClick(NotificationData notification, Map<String, Object> customContent) {
            }

            @Override
            public void onNotificationDismiss(NotificationData notification,  Map<String, Object> customContent) {
            }

            @Override
            public void onNotificationButtonClick(NotificationButtonData button, NotificationData notification, @Nullable Map<String, Object> customContent) {
            }
        });

    }
}

با پیاده‌سازی تابع‌های موجود در ‍‍PusheNotificationListener می‌توانید با پیش آمدن رویداد‌های متفاوتی که برای یک اعلان ممکن است پیش بیاید، عملیات دلخواه خود را تعریف کنید.

تابع‌های تعریف شده در PusheNotificationListener به صورت زیر هستند:

تابع زمان فراخوانی پارامتر‌های داده شده
onNotification دریافت اعلان قابل نمایش ‌ اطلاعات اعلان در قالب NotificationData
onCustomJson دریافت اعلانی که دارای اطلاعات دلخواه در قالب JSON باشد ‌ اطلاعات دلخواه در قالب Map
onNotificationClick زمانی که کاربر یک اعلان نمایش داده شده را لمس کند ‌ اطلاعات اعلان در قالب NotificationData و همچنین اطلاعات دلخواه اعلان در صورت وجود
onNotificationDismiss زمانی که کاربر اعلان نمایش داده شده را از صفحه پاک کند ‌ اطلاعات اعلان در قالب NotificationData و همچنین اطلاعات دلخواه اعلان در صورت وجود
onNotificationButtonClick زمانی که کاربر یک دکمه موجود در اعلان را لمس کند ‌ اطلاعات دکمه لمس شده در قالب NotificationButtonData، اطلاعات اعلان در قالب NotificationData و همچنین اطلاعات دلخواه اعلان در صورت وجود

۳. حذف کد مربوط به پوشه نسخه یک

پس از اینکه روش توضیح داده شده‌ی بالا را برای گوش دادن به رویداد‌های اعلان‌ها پیاده‌سازی کردید، می‌توانید کلاس ارث برده شده از PusheListenerService را که مربوط به نسخه اول پوشه بود، پاک کرده و همچنین از فایل AndroidManifest.xml حذف کنید.

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

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

PusheNotification pusheNotification = Pushe.getPusheService(PusheNotification.class);
pusheNotification.disableNotifications();

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

pusheNotification.enableNotifications();

ارسال اعلان به دستگاه دیگر

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

با داشتن شناسه‌ی دستگاه مورد نظر می‌توانید یک شی از کلاس UserNotification بسازید، در آن اطلاعات اعلان را وارد کنید و با دادن آن به تابع PusheNotification.sendNotificationToUser اعلان را ارسال نمایید.

نمونه کد زیر نحوه‌ی ارسال یک اعلان ساده با تیتر و متن را به کاربری که شناسه‌ی Android ID او را داریم نشان می‌دهد.

UserNotification notification =
                        UserNotification.withAndrodId(androidId)
                                .setTitle("تیتر اعلان")
                                .setContent("متن اعلان");

PusheNotification pusheNotification = Pushe.getPusheService(PusheNotification.class);
pusheNotification.sendNotificationToUser(notification);

در صورتی که می‌خواهید اعلان را با داشتن شناسه‌ای دیگر از کاربر ارسال کنید، می‌توانید از تابع‌های مربوطه در کلاس UserNotification استفاده نمایید:

UserNotification.withAndroidId(String androidId);
UserNotification.withAdvertisementId(String advertisementId);
UserNotification.withCustomId(String customId);
UserNotification.withPusheId(String pusheId);

از پوشه آی‌دی استفاده کنم؟

همانطور که در بخش حذف Pushe ID توضیح داده شد، استفاده از شناسه‌ی Pushe ID دیگر توصیه نمی‌شود. پیشنهاد می‌شود که برای ارسال اعلان به دستگاه‌های دیگر نیز از یکی از شناسه‌های دیگر استفاده کنید.

ارسال اعلان پیشرفته به دستگاه دیگر

در کلاس UserNotification توابعی قرار داده شده است که با آن می‌توانید اعلان مورد نظر خود را بسازید. در صورتی که مایلید اعلان پیشرفته‌تری بسازید که با توابع قرار داده شده ممکن نیست، می‌توانید از تابع UserNotification.setAdvancedNotification استفاده کنید.

برای اینکار باید به تابع اطلاعات اعلان را در قالب یک JSON String بدهید. ساختار JSON ورودی مشابه ساختار استفاده شده در ارسال اعلان با API می‌باشد.

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

ایجاد و حذف کانال اعلان

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

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

PusheNotification pusheNotification = Pushe.getPusheService(PusheNotification.class);
pusheNotification.createNotificationChannel(
            "channel_id", // Channel Id
            "all news channel", // Channel Name
            "", // Description about channel
            4, // Importance: Number between 0 to 5 (5 is the most important)
            true, // Enable Light
            true, // Enable Vibration
            true, // Show Badge
            Color.BLUE, // Led Color
            new long[]{100, 200, 300, 400, 500, 400, 300, 200, 400} // Vibrate mode (can be null)
);

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

PusheNotification pusheNotification = Pushe.getPusheService(PusheNotification.class);
pusheNotification.removeNotificationChannel("channel_id");

همیشه در کنارتان هستیم

در اولین فرصت با ایمیل به شما پاسخ خواهیم داد.

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