اجرای سرویس قابل‌درک در فرایندی مجزا با Unity

این راهنما پیکربندی و پیاده‌سازی موردنیاز برای اجرای سرویس قابل‌درک Android (سرویس پیش‌زمینه‌ای، یا FGS) را در فرایندی خصوصی از برنامه Unity پوشش می‌دهد.

۱. پیکربندی پشتیبانی سرویس قابل‌تشخیص

این بخش نحوه راه‌اندازی اجازه‌های لازم و اعلام سرویس در مانیفست پروژه را توضیح می‌دهد.

‫۱.۱ اظهارنامه اجازه‌ها و سرویس

Assets/Plugins/Android/AndroidManifest.xml سفارشی باید «فعالیت» راه‌انداز، اجازه‌های سرویس قابل‌تشخیص، اجازه اعلان، اجازه شبکه، و سرویس را اعلام کند:

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android">
    <uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
    <uses-permission android:name="android.permission.FOREGROUND_SERVICE_DATA_SYNC" />
    <uses-permission android:name="android.permission.POST_NOTIFICATIONS" />
    <uses-permission android:name="android.permission.INTERNET" />

    <application>
        <activity
            android:name="com.unity3d.player.UnityPlayerActivity"
            android:theme="@style/UnityThemeSelector"
            android:exported="true">
            <intent-filter>
                <action android:name="android.intent.action.MAIN" />
                <category android:name="android.intent.category.LAUNCHER" />
            </intent-filter>
            <meta-data android:name="unityplayer.UnityActivity" android:value="true" />
        </activity>

        <service
            android:name="com.sample.fgs.DownloadService"
            android:process=":downloader"
            android:exported="false"
            android:stopWithTask="false"
            android:foregroundServiceType="dataSync" />
    </application>
</manifest>

foregroundServiceType باید با کار واقعی مطابقت داشته باشد: dataSync برای انتقال، mediaPlayback برای بازپخش، location برای ردیابی مکان. این مقدار باید با اجازه FOREGROUND_SERVICE_<TYPE> مربوطه و فراخوانی startForeground مطابقت داشته باشد — هر سه باید باهم سازگار باشند، درغیراین‌صورت راه‌اندازی سرویس ناموفق خواهد بود.

‫۱.۲ افزودن Java پردازش سرویس به پروژه Unity

فرایند سرویس پیش‌زمینه‌ای، جاوا را اجرا می‌کند. کد Java پیاده‌سازی سرویس را در یک jar بسته‌بندی کنید و آن را در Assets/Plugins/Android/ قرار دهید. Unity به‌طور خودکار jarها را در آن دایرکتوری در libs/ ورودی Gradle قرار می‌دهد و آن‌ها را در APK بسته‌بندی می‌کند؛ فرایند سرویس این کلاس‌ها را در زمان اجرا بار می‌کند. برای اطلاعات بیشتر درباره نحوه پیاده‌سازی این سرویس در Java یا Kotlin، پیاده‌سازی Java را ببینید.

۲. پیکربندی فرایند جداگانه

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

android:process=":downloader"

دو نقطه ابتدایی فرایندی خصوصی برای برنامه ایجاد می‌کند که نام آن your.package.name:downloader است. این فرایند PID متفاوتی نسبت به فرایند اصلی دارد و می‌تواند پس‌از پایان فرایند اصلی به کار خود ادامه دهد.

‫۲.۱ فرایند سرویس Unity ندارد

برای جلوگیری از وارد کردن libunity.so Unity، زمان اجرای IL2CPP، و موارد مشابه به فرایند سرویس، Java سمت سرویس نباید از هیچ کلاس Unity (ازجمله UnityPlayer.currentActivity) استفاده کند و باید فقط به Android Context، Intent extras، و APIهای پلاتفرم وابسته باشد. زمان اجرای موتور Unity فقط ازطریق UnityPlayerActivity فرایند اصلی بار می‌شود؛ فرایند خصوصی :downloader این کتابخانه‌ها را بار نمی‌کند، بنابراین ارجاع دادن به کلاس‌های Unity در فرایند سرویس کار نمی‌کند.

‫۲.۲ نقاط ورودی راه‌اندازی فرایند

پس‌از اینکه فرایند اصلی startForegroundService را فراخوانی می‌کند، سیستم فرایند سرویس :downloader را منشعب می‌کند:

  • Application را نمونه‌سازی می‌کند و Application.onCreate را فراخوانی می‌کند — این در هر فرایندی اجرا می‌شود، بنابراین مقداردهی اولیه موردنیاز فرایند سرویس باید دوباره در اینجا انجام شود. برای اطلاعات بیشتر، به بخش ۲.۳ مراجعه کنید.
  • ‫DownloadService را ایجاد می‌کند و onCreate را فراخوانی می‌کند — این نقطه ورودی فرایند سرویس است.
  • با «قصدی» که در راه‌اندازی ساخته شده است، با onStartCommand تماس می‌گیرد. سرویس خود را در اینجا به پیش‌نما ارتقا می‌دهد و کارگر را شروع می‌کند. برای اطلاعات بیشتر، به بخش ۳.۱ مراجعه کنید.

‫۲.۳ وضعیت یک‌بار در هر فرایند وجود دارد

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

  • Application.attachBaseContext و Application.onCreate در هر فرایندی که مؤلفه‌های برنامه را میزبانی می‌کند اجرا می‌شوند.
  • مقداردهی‌های اولیه ایستا و فیلدهای ایستا به‌طور مستقل در هر فرایند وجود دارند. اختصاص دادن فیلد ایستا در فرایند اصلی با سرویس ارتباط برقرار نمی‌کند.
  • Unity،‏ C#‎، و «فعالیت‌ها» در فرایند اصلی باقی می‌مانند.

۳. پیاده‌سازی جاوا

این بخش سمت Java از واحد FGS را پوشش می‌دهد: ۳.۱ و ۳.۲ DownloadService در فرایند سرویس هستند؛ ۳.۳ FgsBridge در فرایند اصلی است (نقطه ورودی که C# ‎ بااستفاده از JNI فراخوانی می‌کند).

‫۳.۱ ابتدا به پیش‌زمینه ارتقا دهید

public class DownloadService extends Service {
    @Override
    public int onStartCommand(Intent intent, int flags, int startId) {
        try {
            startForegroundCompat();

            // Start the download thread; must come after promoting to foreground
            // ...
        } catch (Exception e) {
            Log.e(TAG, "onStartCommand() failed [errorType="
                    + e.getClass().getSimpleName() + "]: " + e.getMessage(), e);
            stopSelf();
        }

        return START_NOT_STICKY;
    }

    private void startForegroundCompat() {
        Notification notification = buildNotification(0L);
        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.Q) {
            startForeground(NOTIFICATION_ID, notification,
                    ServiceInfo.FOREGROUND_SERVICE_TYPE_DATA_SYNC);
        } else {
            startForeground(NOTIFICATION_ID, notification);
        }
    }

    ...

‫۳.۲ افزودن اعلان

سرویس قابل‌درک برای گزارش پیشرفت به اعلان جاری در کانال اعلان نیاز دارد. اعلان حاوی کنش «توقف» است که ACTION_STOP را بااستفاده از PendingIntent.getService به خود سرویس ارسال می‌کند تا آن را متوقف کند.

private Notification buildNotification(long progressBytes) {
    int progressMib = (int) (progressBytes / MIB);

    Intent launchIntent = getPackageManager().getLaunchIntentForPackage(getPackageName());
    PendingIntent contentIntent = launchIntent != null
            ? PendingIntent.getActivity(this, 0, launchIntent,
                    PendingIntent.FLAG_IMMUTABLE | PendingIntent.FLAG_UPDATE_CURRENT)
            : null;

    Intent stopIntent = new Intent(this, DownloadService.class)
            .setAction(ACTION_STOP);
    PendingIntent stopPendingIntent = PendingIntent.getService(this, 0,
            stopIntent, PendingIntent.FLAG_IMMUTABLE
            | PendingIntent.FLAG_UPDATE_CURRENT);

    Notification.Builder builder = new Notification.Builder(this,
            CHANNEL_ID)
            .setContentTitle("Download service")
            .setContentText("Downloaded " + progressMib + " MB / " + TOTAL_MIB + " MB")
            .setSmallIcon(android.R.drawable.stat_sys_download)
            .setProgress(TOTAL_MIB, progressMib, false)
            .setOngoing(true)
            .setOnlyAlertOnce(true)
            .addAction(new Notification.Action.Builder(null,
                    "Stop", stopPendingIntent).build());

    if (contentIntent != null) {
        builder.setContentIntent(contentIntent);
    }

    if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.S) {
        builder.setForegroundServiceBehavior(
                Notification.FOREGROUND_SERVICE_IMMEDIATE);
    }
    return builder.build();
}

‫۳.۳ نقطه ورودی میزبان جاوا

‫FgsBridge نقطه ورود Java است که فرایند اصلی برای کنترل FGS از آن استفاده می‌کند (این نقطه ورود در فرایند اصلی اجرا می‌شود، نه در فرایند سرویس). C# ‎ این روش‌های ایستا را بااستفاده از JNI برای شروع و توقف سرویس و مدیریت اجازه اعلان فراخوانی می‌کند:

public class FgsBridge {
    // Start the :downloader perceptible service and begin downloading
    public static void startDownloadService(Context context) {
        try {
            context.startForegroundService(new Intent(context, DownloadService.class));
        } catch (Exception e) {
            Log.e(TAG, "startDownloadService() failed [errorType="
                    + e.getClass().getSimpleName() + "]: " + e.getMessage(), e);
        }
    }

    // Stop the service: sends a stop intent; the service removes its
    // notification before exiting
    public static void stopDownloadService(Context context) {
        try {
            context.startService(new Intent(context, DownloadService.class)
                    .setAction(ACTION_STOP));
        } catch (Exception e) {
            Log.e(TAG, "stopDownloadService() failed [errorType="
                    + e.getClass().getSimpleName() + "]: " + e.getMessage(), e);
        }
    }

    // Request notification permission (only needed on API 33+; if already
    // granted, no dialog is shown and it returns immediately)
    public static void requestNotificationPermission(Activity activity) {
        if (Build.VERSION.SDK_INT < 33) {
            return;
        }
        try {
            activity.requestPermissions(
                    new String[] { POST_NOTIFICATIONS }, NOTIFICATION_PERMISSION_REQUEST);
        } catch (Exception e) {
            Log.e(TAG, "requestNotificationPermission() failed [errorType="
                    + e.getClass().getSimpleName() + "]: " + e.getMessage(), e);
        }
    }
}

۴. شروع و کنترل FGS از Unity (C#‎)

‫AndroidBridge پوشاننده C# ‎ است که FgsBridge را بااستفاده از JNI فراخوانی می‌کند. سه پیاده‌سازی روش:

public static void StartDownloadService()
{
#if UNITY_ANDROID && !UNITY_EDITOR
    CallStatic("startDownloadService");
#else
    Debug.Log("StartDownloadService() no-op outside Android");
#endif
}

public static void StopDownloadService()
{
#if UNITY_ANDROID && !UNITY_EDITOR
    CallStatic("stopDownloadService");
#else
    Debug.Log("StopDownloadService() no-op outside Android");
#endif
}

public static void RequestNotificationPermission()
{
#if UNITY_ANDROID && !UNITY_EDITOR
    CallStatic("requestNotificationPermission");
#else
    Debug.Log("RequestNotificationPermission() no-op outside Android");
#endif
}

‫CallStatic یک کمک‌کننده JNI داخلی است که کلاس FgsBridge را حل می‌کند و روش ثابت جاوا مربوطه را فراخوانی می‌کند. RequestNotificationPermission باید در راه‌اندازی برنامه فراخوانی شود تا اعلان بلافاصله پس‌از شروع فرایند سرویس ظاهر شود.