Как запустить заметный сервис в отдельном процессе с помощью Unity

В этом руководстве рассказывается, как настроить и запустить заметную службу Android (активную службу, или FGS) в частном процессе из приложения Unity.

1. Как настроить поддержку заметных сервисов

В этом разделе объясняется, как настроить необходимые разрешения и объявить службу в манифесте вашего проекта.

1.1. Разрешения и декларация сервиса

В специальном файле 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. Если все три элемента не согласованы, запустить службу не удастся.

1.2. Добавьте Java-файл service-process в проект Unity

Процесс службы переднего плана выполняется на Java. Упакуйте код Java реализации сервиса в JAR-файл и поместите его в каталог Assets/Plugins/Android/. Unity автоматически включает JAR-файлы из этого каталога в папку libs/ Gradle и упаковывает их в APK. Процесс сервиса загружает эти классы во время выполнения. Подробнее о том, как реализовать сервис на Java или Kotlin…

2. Настройте отдельный процесс

Граница процесса включается с помощью одного атрибута манифеста:

android:process=":downloader"

Двоеточие в начале создает частный процесс приложения с именем your.package.name:downloader. У него другой идентификатор процесса, и он может продолжать работу после завершения основного процесса.

2.1. В процессе обслуживания нет единства

Чтобы не переносить libunity.so Unity, среду выполнения IL2CPP и другие подобные элементы в процесс сервиса, Java на стороне сервиса не должна использовать классы Unity (включая UnityPlayer.currentActivity) и должна зависеть только от Android Context, Intent extras и API платформы. Среда выполнения Unity загружается только через UnityPlayerActivity основного процесса. Частный процесс :downloader не загружает эти библиотеки, поэтому ссылки на классы Unity не работают в процессе сервиса.

2.2. Точки входа для запуска процессов

После того как основной процесс вызывает startForegroundService, система разветвляет процесс сервиса :downloader:

  • Создает экземпляр Application и вызывает Application.onCreate. Это выполняется в каждом процессе, поэтому инициализацию, необходимую для процесса сервиса, нужно выполнить здесь снова. Дополнительную информацию можно найти в разделе 2.3.
  • Создает DownloadService и вызывает onCreate – это точка входа в процесс сервиса.
  • Вызывает onStartCommand с намерением, созданным при запуске. Сервис переходит в активный режим и запускает рабочий процесс. Дополнительную информацию вы найдете в разделе 3.1.

2.3. Состояние существует один раз для каждого процесса

Код Dex доступен только для чтения, но состояние среды выполнения – нет:

  • Application.attachBaseContext и Application.onCreate запускаются в каждом процессе, в котором размещаются компоненты приложения.
  • Статические инициализаторы и статические поля существуют независимо в каждом процессе. Назначение статического поля в основном процессе не обеспечивает связь с сервисом.
  • Unity, C# и действия остаются в основном процессе.

3. Реализация на Java

В этом разделе рассматривается часть модуля FGS, написанная на Java: 3.1 и 3.2 – это DownloadService в процессе сервиса; 3.3 – это FgsBridge в основном процессе (точка входа, которую C# вызывает с помощью JNI).

3.1. Сначала переведите приложение в активный режим

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);
        }
    }

    ...

3.2. Добавьте уведомление

Для заметной службы требуется постоянное уведомление в канале уведомлений, чтобы сообщать о ходе выполнения. Уведомление содержит действие Stop, которое отправляет 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();
}

3.3. Точка входа хоста Java

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);
        }
    }
}

4. Запуск 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 и вызывает соответствующий статический метод Java. RequestNotificationPermission должен вызываться при запуске приложения, чтобы уведомление появлялось сразу после запуска процесса службы.