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

راه‌اندازی

• برای استفاده باید نسخه‌ی یونیتی شما حداقل 5.0 باشد.
• برای استفاده از پوش‌پل می‌توانید از هر دو BuildSystem موجود یونیتی (Gradle و Internal) استفاده کنید.

ایمپورت‌کردن کتابخانه

کتابخانه پوش‌پل برای Unity را از این لینک دانلود کنید. در پروژه یونیتی خود بر روی فولدر Assets کلیک راست کنید و از Import Package بر روی Custom Package کلیک کنید و فایل پکیج دانلود شده بالا را انتخاب کنید.

• از منوی Assets -> Play Service Resolver -> Android Resolver گزینه‌ی Resolve و یا Force resolve را انتخاب کنید. (با توجه به تحریم‌بودن سرورهای گریدل از ابزارهای گذر از تحریم استفاده‌کنید).

تنظیمات پروژه

از منوی File گزینه ی Build Setting را فشار دهید. در بین پلتفرم ها Android را انتخاب کنید و دکمه ی Player Setting را بزنید. در قسمت Bundle Identifier از همین پنجره، پکیج نیم اپلیکیشن خود را وارد کنید.

تغییرات AndroidManifest.xml

وارد پنل پوش‌پل شوید و اپلیکیشن خود را ثبت کنید. توجه داشته باشید که از همان Package Name استفاده کنید که در مرحله‌ی قبل به عنوان Bundle Identifier وارد کرده‌اید. فایل منیفست مربوط به Unity را دانلود کنید و محتوای آن را در منیفست خود در مسیر Assets/Plugins/Android ادغام نمایید. اگر فایلAndroidManifest.xml در این مسیر موجود نیست، ابتدا این فایل را از مسیر C:\Program Files\Unity\Editor\Data\PlaybackEngines\androidplayer\apk کپی کرده و در مسیر Assets/Plugins/Android از پرو‌ژه‌ی خود paste کنید.

همچنین می‌توانید از فولدر tools در PushPole که ایمپورت کردید نیز این فایل را کپی کنید. در این صورت کافیست به جای TOKEN مقدار برنامه‌ی خود را قرار دهید.

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

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

افزودن به پروژه

پس از دانلود فایل‌ها توسط Jar resolver و اضافه‌کردن فایل مانیفست باید کد اسکریپت پوش‌پل را در Hierarchy قرار دهید تا اجرا شود. فایل اسکریپت PushPole.cs را به یکی از آبجکت‌های درون بازی Drag and drop کنید (در صورتی که آبجکتی ندارید، یک GameObject خالی بسازید و یا اسکریپت را به Main camera متصل کنید).

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

تست

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

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

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

امکانات

PushPoleId

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

var pushpoleId = PushPole.GetId();

تاپیک (topic)

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

برای استفاده از این امکان باید کاربران خود را در تاپیک مورد نظر عضو کنید. فرض کنید نام تاپیک مورد نظرتان varzeshi باشد. برای عضویت در تاپیک، فایل PushPole.cs را در مسیر Assets/PushPole باز کرده و تابع Subscribe را با ورودی "varzeshi" روی event مورد نظر خودتان (مثلا در دکمه ای در منوی تنظیمات) صدا بزنید.

برای لغو عضویت از این تاپیک تابع Unsubscribe را با ورودی "varzeshi" روی event مورد نظر خودتان صدا بزنید.

PushPole.Subscribe(topicName);

PushPole.Unsubscribe(topicName);

توجه داشته باشید که توابع مربوط به عضو شدن و لغو عضویت در تاپیک باید بعد از پایان PushPole.initialize اجرا شوند. بنابراین آنها را بلافاصله بعد از PushPole.initialize قرار ندهید.

دریافت جیسون

در حال حاضر این امکان برای پلتفرم یونیتی موجود نیست.

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

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

برای غیرفعال کردن نمایش پوش باید از تابع SetNotificationOff استفاده کنید. این تابع در کلاس PushPole.cs در مسیر Assets/PushPole قرار دارد.

برای فعال‌سازی دوباره ی نمایش پوش از تابع SetNotificationOn در کلاس PushPole.cs استفاده کنید. فراخوانی این توابع را در event موردنظر خود (مثلا در کلیک دکمه ای در منوی تنظیمات) قرار دهید.

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

نکته‌ی مهم: توابع ارسال اعلان به دستگاه دیگر و عضویت یا لغو عضویت در تاپیک را بعد از اطمینان از اینکه عملیات initialization پوش‌پل انجام شده است، صدا بزنید. برای این کار در کلاس PushPole.cs که در قسمت Assets/PushPole پلاگینی پوش‌پل که به پروژه اضافه کرده‌اید است، کدهای زیر را قرار دهید (یا در محل دیگری که موردنظرتان هست آن را فراخوانی کنید):

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

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

string pushpoleId = "some_thing";
PushPole.SendSimpleNotifToUser(pushpoleId, "title", "content");

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

string pushpoleId = "some_thing";
PushPole.SendAdvancedNotifToUser(pushpoleId, "{ \"title\":\"Hello\", \"content\":\"World!\" }");

نمونه‌ی یک جیسون کامل برای ارسال:

{
  "title": "عنوان",
  "content": "تیتر",
  "big_title": "تیتر کامل",
  "big_content": "متن بزرگ",
  "summary": "چکیده ",
  "image": "http://url/name.png",
  "icon": "http://url/name.png",
  "ticker": "متن نوار اعلان",
  "notif_icon": "file_download",
  "wake_screen": true,
  "sound_url": "http://static.push-pole.com/mp3/2.mp3",
  "visibility": true,
  "led_color": "-8206336",
  "show_app": true,
  "led_on": 300,
  "led_off": 500,
  "delay_until": true,
  "action": {
    "url": "tg://join?invite=sdfdsfdsfds",
    "action_type": "U"
  },
  "buttons": [
    {
      "btn_icon": "fileـdownload",
      "btn_order": 1,
      "btn_content": "متن دکمه",
      "btn_action": {
        "url": "tg://join?invite=fdsfdsfds",
        "action_type": "U"
      }
    },
    {
      "btn_icon": "local_cafe",
      "btn_order": 2,
      "btn_content": "متن دکمه",
      "btn_action": {
        "url": "http://fgfdgfdg.com",
        "action_type": "U"
      }
    },
    {
      "btn_icon": "phone_android",
      "btn_order": 3,
      "btn_content": "متن دکمه",
      "btn_action": {
        "url": "call:a_number",
        "action_type": "U"
      }
    }
  ]
}

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

ایجاد و حذف کانال نوتیفیکیشن در اپلیکیشن (Android 8.0+ only)

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

    CreateNotificationChannel(
                context,
        "MY_CHANNEL_ID", //channelId
                "all news channel", //Channel Name
                "", //description about channel
                4, //importance: Number between 0 to 5 (5 is the most important)
                true, //enableLight
                true, //enableViberation
                true, //showBadge
                -16776961, //led color
                new long[]{100, 200, 300, 400, 500, 400, 300, 200, 400} // Vibrate mode (can be Nullable)
    );

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

    RemoveNotificationChannel(
                context,
                "MY_CHANNEL_ID" //channelId
    );

سایر قابلیت ها را در فایل PushPole.cs می‌توانید مشاهده کنید.

عیب یابی

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

نصب بعد از مدت طولانی در کنسول دیده نمی‌شود

در حالت عادی نصب نبایستی بیش از ۱ یا ۲ دقیقه به طول انجامد. در صورتی که این مدت طولانی شد ابتدا پروسه‌ی اضافه‌کردن پوش‌پل را مرور کنید:

• پیام Resolution succeeded در یونیتی مشاهده می‌شود.
• گیم‌آبجکت پوش‌پل به Scene اصلی اضافه‌شده است.
• اسکریپتی که پوش‌پل را initialize می‌کند به گیم‌آبجکت اتچ‌شده‌است.
• در صورتی‌که به لاگ‌کت اندروید دسترسی دارید (مثلا با اندرویداستودیو یا ADB) از مشاهده‌ی Successfully registered to PushPole مطمئن شوید. در غیر اینصورت بایستی خطا را بررسی کنید.

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

تداخل لایبرری‌ها با پوش‌پل

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

پیغام Resolution failed از Jar resolver

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

کرش‌کردن قبل از نمایش لوگوی یونیتی بعد از اضافه‌کردن پوش‌پل

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

• Jar resolver لایبرری‌های لازم را به طور کامل اضافه نکرده.
  • در این صورت باید با وصل بودن ابزار گذر از تحریم Force resolve کنید تا لایبرری‌ها کامل اضافه‌شوند.
• مالتی‌دکس رخ‌داده. یعنی تعداد متد‌های برنامه از حد تعیین شده گذشته و بعضی‌کدها به فایل دکس نهایی اضافه‌نشده‌اند.
  • در این صورت باید مالتی‌دکس را در برنامه فعال کنید. می‌توانید این‌پست را برای انجام این کار بررسی کنید.