Basic4Android

راه‌اندازی

• برای استفاده از پوش‌پل بایستی بتوانید از SDK manager لایبرری دانلود نمایید. لذا حداقل از نسخه‌ی 7.8 استفاده کنید.
• برای استفاده از لایبرری باید از android.jar نسخه ی 26 و یا بالاتر استفاده کنید.
• در صورت بروز هرگونه مشکل لطفا ابتدا بخش عیب‌یابی را بررسی نمایید.

اضافه کردن پوش‌پل به پروژه‌ی B4A

کتابخانه پوش‌پل و ملزومات B4A را از این لینک دانلود کنید و محتوای پوش‌پل درون زیپ را در پوش‌پل Libraries برنامه‌ی B4A قرار دهید. در صورتی که نمی‌دانید پوش‌پل Libraries کجا قرار دارد با راست کلیک کردن بر روی پنجره‌ی Libraries Manager (در سمت راست نرم‌افزار B4A) و انتخاب گزینه‌ی Open Internal Libraries Folder این پوش‌پل برای شما باز می‌شود. اگر یک یا بیشتر از فایل‌ها از قبل وجود دارند میتوانید گزینه‌ی replace را انتخاب کنید.

پوش‌پل برای دریافت لایبرری‌های خود از Maven استفاده می‌کند. باتوجه به تحریم‌بودن سرورهای Maven لطفا از ابزار گذر از تحریم استفاده کنید تا با خطای Maven artifact not found‍‍ مواجه نشوید. در صورت بروز مشکل عیب‌یابی را بررسی کنید.

در نرم افزار B4A در پنجره Libraries Manager کلیک راست کنید و صفحه را Refresh کنید و کتابخانه PushPole را انتخاب کنید.

ایجاد اپلیکیشن در پنل پوش‌پل

وارد پنل پوش‌پل شوید و در قسمت راست صفحه دکمه اپلیکیشن جدید را کلیک کنید.

• اطلاعات اپلیکیشن را وارد کنید و توجه داشته باشید که مقدار نام بسته باید با عبارت Package Name در تنظیمات B4A (در قسمت Project -> Build Configurations) همخوانی داشته باشد.

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

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

• دکمه ایجاد اپلیکیشن را کلیک کنید تا اپلیکیشن جدید به پنل شما اضافه شود.

تغییرات AndroidManifest.xml

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

در پنجره‌ی باز شده نسخه‌ی 1 را انتخاب کنید و متن نمایش داده شده را کپی کنید.

در نرم‌افزار B4A، تنظمیات منیفست پروژه را از طریق منو Project > Manifest Editor باز کنید و متن کپی شده را در آن قرار دهید.

برخی از دسترسی ها (permissions) برای پوش‌پل اختیاری است. این دسترسی ها برای ارسال هدفمند اعلان به کاربران است. شما قادر خواهید بود با استفاده از این دسترسی ها کاربران خود را دسته بندی کنید و اعلانهای خود را هدفمند ارسال کنید.

CreateResourceFromFile(Macro, FirebaseNotifications.FirebaseNotifications)

<service android:name="anywheresoftware.b4a.objects.FirebaseNotificationsService">
   <intent-filter>
      <action android:name="com.google.firebase.MESSAGING_EVENT"/>
   </intent-filter>
</service>

افزودن کد

در کلاس Main در قسمت Sub Globals کد زیر را قرار دهید:

Dim pushpole As PushPole

در کلاس Main در قسمت Activity Create کد زیر را وارد کنید:

pushpole.initialize()

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

تست

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

• نکته: اگر برنامه خود را از نسخه ی قبلی پوش‌پل به نسخه ی جدید بروزرسانی می کنید، مطمئن شوید که کتابخانه های جدید را استفاده می کنید و تیک نسخه قبلی پوش‌پل را در قسمت لایبرری بردارید. برای اطمینان می توانید فایل های مربوط به نسخه قبلی پوش‌پل را از مسیر C:\Program Files (x86)\Anywhere Software\Basic4android\Libraries حذف کنید تا اشتباها استفاده نشوند.
• به صفحه نصب ها بروید.
• بعد از گذشت زمان کوتاهی یک ردیف مشخصات نصب به لیست نصب ها اضافه می شود که متعلق به گوشی شما است.
• یک اعلان تست ارسال کنید. دقت کنید تلفن همراه شما به اینترنت متصل باشد.

امکانات

PushPoleId

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

Dim pushpoleId As String = p.getId()

دریافت اطلاعات دلخواه با فرمت جیسون (JSON)

شما میتوانید از طریق پنل برای اپلیکیشن خود اطلاعات دلخواه در قالب جیسون (JSON) ارسال کنید. برای اینکه بتوانید از این اطلاعات در اپلیکیشن خود استفاده کنید مراحل زیر را انجام دهید.

• در منوی نرم‌افزار B4A گزینه‌ی Project -> Add New Module -> Service Module را انتخاب کنید و یک سرویس جدید بسازید. از شما خواسته خواهد شد که نام سرویس را وارد کنید، ما فرض می‌کنیم که نام سرویس MyJsonReceiver هست ولی شما می‌توانید نام دلخواه خود را انتخاب کنید.

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

Sub Process_Globals
    Dim PushPoleUtil As PushPoleB4AUtil
End Sub

Sub Service_Start (pIntent As Intent)
    If pIntent.Action == "com.pushpole.sdk.RECEIVE" Then
        Dim JsonMsg As String
        JsonMsg = PushPoleUtil.getPushPoleJsonMsg(pIntent)
        If JsonMsg <> "" Then
            MessageReceived(JsonMsg)
        End If
    End If
    Service.StopAutomaticForeground
End Sub

Sub MessageReceived (JsonMsg As String)
    Log("Received Json Message")
    Log(JsonMsg)

    ' Process json message here ...
End Sub

• از طریق منوی Project -> Manifest Editor تنظیمات منیفست پروژه را باز کنید و متن زیر را به آن اضافه کنید. توجه داشته باشید که عبارت MyJsonReceiver را با نام سرویس خود جایگزین کنید.

AddServiceText(MyJsonReceiver,
<intent-filter>
    <action android:name="com.pushpole.sdk.RECEIVE"/>
</intent-filter>
)

{
    "titr": "تیتر",
    "matn": "متن"
}

Sub MessageReceived (jsonStr As String)
    Dim jsonParser As JSONParser
    Dim jsonObject As Map
    Dim title as String
    Dim content as String

      Try
        jsonParser.Initialize(jsonStr)
        jsonObject = jsonParser.NextObject
        title = jsonObject.Get("titr")
        content = jsonObject.Get("matn")
        ToastMessageShow(title & ":" & content , True)
    Catch
        Log(LastException)
    End Try
End Sub

تاپیک (topic)

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

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

pushpole.subscribe("varzeshi")

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

pushpole.unsubscribe("varzeshi")

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

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

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

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

pushpole.notificationOff()

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

pushpole.notificationOn()

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

می توانید مستقیم از یک دستگاه به دستگاه دیگر اعلان بفرستید. برای این کار باید شناسه ی پوش‌پل ی آن دستگاه یعنی pushpoleId آن را داشته باشید. برای بدست آوردن شناسه هر دستگاه می توانید به روش زیر عمل کنید:

Dim p as PushPole
Dim pid As String = p.getId()

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

p.sendSimpleNotifToUser("pid_a0e3-82ac-a0", "title", "content")

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

p.sendAdvancedNotifToUser("pid_a0e3-82ac-a0", "{ \"title\":\"تست\", \"content\":\"پیام ارسالی از یک دستگاه \" }")

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

p.sendCustomJsonToUser("pid_a0e3-82ac-a0", "{ \"key1\":\"value1\", \"key2\":\"value2\" }")

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

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

If p.pushpoleInitialized() Then
    p.sendSimpleNotifToUser("pid_a0e3-82ac-a0", "title", "content")
End If

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

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

    Dim p As PushPole
    p.createNotificationChannel(
        "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 null)
    )

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

     Dim p As PushPole
     p.removeNotificationChannel(
         "MY_CHANNEL_ID" 'channelId 
    )

عیب یابی

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

خطا‌‌های مربوط به Maven Artifact not found …

کتابخانه‌های لازم برای پوش‌پل از Maven دانلود می‌شوند. در صورتی که یکی از این کتابخانه‌ها دانلود نشده باشد با این خطا مواجه خواهید شد. برای حل مشکل بایستی کتابخانه نام برده شده در خطا را دانلود نمایید.

از طریق ابزار SDK Manager در نرم‌افزار بیسیک۴‌اندروید شما می‌توانید این کتابخانه‌ها را دانلود کنید. ولی به دلیل تحریم بودن نیاز است که از یک تحریم‌شکن یا وی‌پی‌ان برای این کار استفاده کنید. در صورتی که این کار برای شما امکان پذیر نیست، راه دیگر این است که کتابخانه‌های لازم را مستقیم از لینکی که در ادامه می‌گذاریم دانلود کرده و به Android SDK خود اضافه کنید. نحوه‌ی انجام این دو روش را در ادامه توضیح می‌دهیم.

۱. نصب کتابخانه‌ها از طریق SDK Manager

از منوی Tools،‌ گزینه‌ی SDK manager را انتخاب کنید. کتابخانه‌های موجود و قابل نصب در این پنجره لیست می‌شوند، شما می‌توانید کتابخانه‌ی مورد نظر را انتخاب کرده و دکمه Install Selected را انتخاب کنید تا نصب شوند. توصیه می‌کنیم همه‌ی کتابخانه‌های پیشنهاد شده در این پنجره را انتخاب و نصب کنید ولی اگر مایل به این کار نیستید می‌توانید فقط کتابخانه‌ی نام برده شده در خطا را انتخاب کنید. بعد از اتمام عملیات نصب، دوباره اقدام به بیلد برنامه بکنید و اگر کتابخانه‌ها درست نصب شده باشند با خطای قبلی مواجه نخواهید شد.

۲. نصب کتابخانه‌ها به صورت دستی

توصیه می‌کنیم از روش اول استفاده کنید ولی اگر این کار برای شما امکان پذیر نیست، شما می‌توانید کتابخانه‌ها را به صورت دستی نیز نصب کنید. برای این کار ابتدا با توجه به نسخه‌ی پلتفورم اندروید خود یکی از فایل‌های زیر را دانلود کنید. (در صورتی که نمی‌دانید از چه نسخه‌ای استفاده می‌کنید، از طریق منو نرم‌افزار پنجره‌ی Tools -> Configure Paths را باز کرده و عبارت جلوی android.jar را نگاه کنید)

• آگر نسخه‌ی پلتفورم اندروید ۲۸ استفاده می‌کنید، این فایل را دانلود کنید

• آگر نسخه‌ی پلتفورم اندروید ۲۷ استفاده می‌کنید، این فایل را دانلود کنید

• آگر نسخه‌ی پلتفورم اندروید ۲۶ استفاده می‌کنید، این فایل را دانلود کنید

  بعد از اتمام دانلود فایل زیپ را باز کرده و داخل آن فولدری به نام b4a_remote پیدا خواهید کرد. این فولدر را در مسیر <Android SDK>\extras کپی کنید. توجه داشته باشید که در این مسیر عبارت <Android SDK> را با محل نصب SDK اندروید بر روی سیستم خود جایگزین کنید. برای مثال اگر SDK اندروید شما در C:\Android SDK نصب شده باشد، بعد از کپی کردن، فولدر C:\Android SDK\extras\b4a_remote باید وجود داشته باشد.

Resource entry provider_paths is already defined.

این مشکل به این دلیل رخ‌ می‌دهد که پوش‌پل یک File Provider با ریسورس provider_path ساخته و با اضافه‌کردن خط

CreateResource(xml, provider_paths, <external-files-path name="name" path="shared" />)

این خطا رخ خواهد داد.

برای حل این مشکل در صورتی‌که قصد ساخت ریسورس دارید نام دیگری برای آن انتخاب کنید، مثلا provider_path2 و آن را در provider نیز اعمال کنید.

AddApplicationText(
  <provider
  android:name="android.support.v4.content.FileProvider"
  android:authorities="$PACKAGE$.provider"
  android:exported="false"
  android:grantUriPermissions="true">
  <meta-data
  android:name="android.support.FILE_PROVIDER_PATHS"
  android:resource="@xml/provider_paths2"/>
  </provider>
)
CreateResource(xml, provider_paths2,  <external-files-path name="name" path="shared" />)

Maven artifact not found: com.google.auto.value/auto-value-annotations

این لایبرری در SDK manager بیسیک۴اندروید وجود ندارد و مطابق این پست بایستی این فایل را در آدرس زیر در AndroidSDK خود اکسترکت کنید.

<Android SDK>\extras\google

Uncaught translation error: java.lang.IllegalArgumentException: already added: …

این خطا به دلیل conflict دو یا بیشتر از لایبرری‌های اضافه‌شده به پروژه رخ می‌دهد.

با توجه به اینکه پوش‌پل لایبرری‌ها را با استفاده از Maven اضافه می‌کند، به احتمال زیاد لایبرری‌های دیگر از Maven استفاده نکرده‌اند. بایستی فایل xml لایبرری‌هایی که اضافه کرده‌اید را باز کنید و لایبرری‌ها را در صورت امکان به Maven تبدیل کنید.

Uncaught translation error: java.lang.IllegalArgumentException: already added: Landroid/support/annotation/AnimRes;
Uncaught translation error: java.lang.IllegalArgumentException: already added: Landroid/support/annotation/AnimatorRes;
Uncaught translation error: java.lang.IllegalArgumentException: already added: Landroid/support/annotation/AnyRes;
Uncaught translation error: java.lang.IllegalArgumentException: already added: Landroid/support/annotation/AnyThread;
Uncaught translation error: java.lang.IllegalArgumentException: already added: Landroid/support/annotation/ArrayRes;
Uncaught translation error: java.lang.IllegalArgumentException: already added: Landroid/support/annotation/AttrRes;
Uncaught translation error: java.lang.IllegalArgumentException: already added: Landroid/support/annotation/BinderThread;
Uncaught translation error: java.lang.IllegalArgumentException: already added: Landroid/support/annotation/BoolRes;
Uncaught translation error: java.lang.IllegalArgumentException: already added: Landroid/support/annotation/CallSuper;
UNEXPECTED TOP-LEVEL EXCEPTION:
java.lang.RuntimeException: Translation has been interrupted
at com.android.dx.command.dexer.Main.processAllFiles(Main.java:689)
at com.android.dx.command.dexer.Main.runMonoDex(Main.java:313)
at com.android.dx.command.dexer.Main.run(Main.java:279)
at com.android.dx.command.dexer.Main.main(Main.java:247)
at com.android.dx.command.Main.main(Main.java:106)
Caused by: java.lang.InterruptedException: Too many errors
at com.android.dx.command.dexer.Main.processAllFiles(Main.java:681)
... 4 more

در صورت موفق نشدن در این امر مشکل را با ذکر خطا به پشتیبانی پوش‌پل اطلاع دهید.

Generate R . Error

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

Install parse failed manifest malformed

این مشکل به دلیل این است که شما در Package Name اپلیکیشن خود از حروف بزرگ انگلیسی استفاده کرده اید. و اگر در منیفست شما از پکیج نیم استفاده شده باشد، بیسیک 4 اندروید نمی تواند کامپایل کند. برای آشنایی بیشتر می توانید به این سایت مراجعه کنید.

همچنین بررسی کنید که فایل مانیفست ایراد نگارشی نداشته باشد.

java.lang.OutOfMemoryError: GC overhead limit exceeded

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

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

C:\Users\<Your user name>\AppData\Roaming\Anywhere Software\Basic4android

فایلی با پسوند .ini در آن پیدا می‌کنید، این فایل را باز کنید. خطی بیابید که با عبارت MaxRamForDex شروع شود و مقدار جلوی آن را افزایش دهید. اگر مقدار فعلی آن 1024 است آن را به 2048 افزایش دهید و اگر مقدار 2048 هست به 4096 افزایش دهید. این فایل را ذخیره کنید و نرم‌افزار بیسیک‌فور‌اندروید را باز و بسته کنید و دوباره برنامه را کامپایل کنید.

B4A ورژن ۹.۳ به بالا

اگر نسخه b4a شما 9.3 و بالاتر است در صورتی که نصبی در پنل شما ثبت نمی‌شود و یا با خطاهای مرتبط با فایربیس مواجه می‌شوید بروی این لینک کلیک کنید و در مسیری که SDK اندروید خود را قرار داده‌اید محتوای فایل زیپ (فولدر b4a_remote) را جایگزین فولدر b4a_remote داخل sdk خودتون نمایید (مسیر پیشفرض C:\Android\extras).